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 >
Wrap
OS/2 Help File
|
1999-05-12
|
208KB
|
6,127 lines
ΓòÉΓòÉΓòÉ 1. How To Use This Book ΓòÉΓòÉΓòÉ
The following topics explain how to use this book:
Using the Contents
Getting Additional Information
Using Menu Bar Choices
Documentation Conventions
ΓòÉΓòÉΓòÉ 1.1. Using the Contents ΓòÉΓòÉΓòÉ
When the Contents window is first displayed, some topics have a plus (+) sign
beside them. The plus sign indicates that additional topics are available.
To expand the Contents if you are using a mouse, click on the plus sign. If you
are using the keyboard, use the Up or Down Arrow key to highlight the topic,
and press the Plus (+) key. For example, Toolkit Roadmap has a plus sign beside
it. To see additional topics for that heading, click on the plus sign or
highlight that topic and press the Plus (+) key.
To view a topic, double-click on the topic (or press the Up or Down Arrow key
to highlight the topic, and then press Enter).
ΓòÉΓòÉΓòÉ 1.2. Getting Additional Information ΓòÉΓòÉΓòÉ
After you select a topic, the information for that topic is displayed in a
window. Highlighted words or phrases indicate that additional information is
available. You will notice that certain words and phrases are highlighted in
blue letters, or in white letters on a black background. These are called
hypertext terms. If you are using a mouse, double-click on the highlighted
word. If you are using a keyboard, press the Tab key to move to the highlighted
word, and then press Enter. Additional information is then displayed in a
window.
ΓòÉΓòÉΓòÉ 1.3. Using Menu Bar Choices ΓòÉΓòÉΓòÉ
Several choices are available for managing information presented in this book.
There are three menus on the menu bar:
Services menu
Options menu
Help menu
ΓòÉΓòÉΓòÉ 1.3.1. Services Menu ΓòÉΓòÉΓòÉ
The actions that are selectable from the Services menu operate on the active
window currently displayed on the screen. These actions include the following:
Search
Print
Bookmark
Copy
ΓòÉΓòÉΓòÉ 1.3.1.1. Search ΓòÉΓòÉΓòÉ
Search enables you to find occurrences of a word or phrase in the current
topic, selected topics, or all topics. You can specify a word or phrase to be
searched. You can also limit the search to a set of topics by first marking the
topics in the Contents list.
To search for a word or phrase in all topics, do the following:
1. Select Search from the Services menu. Type the word or words to be
searched for.
2. Click on All sections or press the Up or Down Arrow keys to select it.
3. Click on Search (or select it and press Enter) to begin the search.
4. The list of topics where the word or phrase appears is displayed.
ΓòÉΓòÉΓòÉ 1.3.1.2. Print ΓòÉΓòÉΓòÉ
Print enables you to print one or more topics. You can also print a set of
topics by first marking the topics in the Contents list. To print the document
contents list do the following:
1. Select Print from the Services menu.
2. Click on Contents (or press the Up or Down Arrow key to select it).
3. Click on Print (or select it and press Enter).
4. The Contents list is printed on your printer.
ΓòÉΓòÉΓòÉ 1.3.1.3. Bookmark ΓòÉΓòÉΓòÉ
Bookmark enables you to set a placeholder so you can retrieve information of
interest to you. When you place a bookmark on a topic, it is added to a list of
bookmarks you have previously set. You can view the list, and you can remove
one or all bookmarks from the list. If you have not set any bookmarks, the list
is empty. To set a bookmark, do the following:
1. Select a topic from the Contents.
2. When that topic is displayed, select Bookmark from the Services menu.
3. If you want to change the name used for the bookmark, type the new name
in the field.
4. Click on the Place radio button or press the Up or Down Arrow key to
select it.
5. Click on OK and press Enter. The bookmark is then added to the bookmark
list.
ΓòÉΓòÉΓòÉ 1.3.1.4. Copy ΓòÉΓòÉΓòÉ
Copy enables you to copy a topic that you are viewing to the System Clipboard
or to a file that you can edit. You will find this particularly useful for
copying syntax definitions and program samples into the application that you
are developing.
You can copy a topic that you are viewing in two ways:
Copy copies the topic that you are viewing into the System Clipboard. If
you are using a Presentation Manager editor (for example, the System
Editor) that copies or cuts (or both) to the System Clipboard and pastes
to the System Clipboard, you can easily add the copied information to
your program source module.
Copy to file copies the topic that you are viewing into a temporary file
named TEXT.TMP. You can later edit that file by using any editor. You
will find TEXT.TMP in the directory where your viewable document resides.
To copy a topic, do the following:
1. Expand the Contents list and select a topic.
2. When the topic is displayed, select Copy to file from the Services menu.
3. The system puts the text pertaining to that topic into the temporary file
named TEXT.TMP.
For information on one of the other choices in the Services menu, highlight
the choice and press the F1 key.
ΓòÉΓòÉΓòÉ 1.3.2. Options Menu ΓòÉΓòÉΓòÉ
The actions that are selectable from the Options menu allow you to change the
way your Contents list is displayed. To expand the Contents and show all levels
for all topics, choose Expand all from the Options menu. You can also press
Ctrl+*. For information on one of the other choices in the Options menu,
highlight the choice and press the F1 key.
ΓòÉΓòÉΓòÉ 1.3.3. Help Menu ΓòÉΓòÉΓòÉ
The actions that are selectable from the Help menu allow you to select
different types of help information. You can also press the F1 key for help
information about the Information Presentation Facility (IPF).
ΓòÉΓòÉΓòÉ 1.4. Documentation Conventions ΓòÉΓòÉΓòÉ
Throughout Using Your Toolkit, the following conventions distinguish the
different elements of text:
plain text Function names, structure names, data type
names, message names, enumerated types, and
constant names.
Initial capitalization Key names, group-box controls, drop-down list
boxes, dialog windows, combo-boxes, single-line
entry (SLE) and multiple-line entry (MLE)
fields.
UPPERCASE File names and error codes.
monospace Programming examples and user input at the
command line prompt or into an entry field.
bold Push buttons, check boxes, radio buttons, spin
buttons, menu bar choices, and menu items.
italics Parameters, structure fields, titles of
documents, and first occurrences of words with
special meaning.
ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ
Welcome to the IBM Developer's Toolkit for OS/2 Warp (OS/2 Warp Toolkit). This
book documents the following:
Additions and updates made to the OS/2 Warp Toolkit as listed in the
What's New section
Descriptions of online documentation, code samples, and tools
Programming considerations that have been changed or added
Toolkit roadmap that covers the folder hierarchy and the contents and
directory structure
Toolkit support information that assists you in installing or using the
OS/2 Warp Toolkit, or reporting suspected system defects as a result of
installing the OS/2 Warp Toolkit
ΓòÉΓòÉΓòÉ 3. README ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 4. Toolkit Desktop Objects ΓòÉΓòÉΓòÉ
To restore your Toolkit Desktop objects, insert the CD or diskette that
contains the Toolkit Installation program (TKINSTAL.EXE), start the program,
and follow these steps:
1. Click on Options to open Installation options.
2. Deselect Install selected files and Write CONFIG.SYS updates to: (only
Register WPS classes and Create desktop objects should be selected).
3. Click on OK to close Installation options.
4. Highlight the root (top-most) component in the component tree, and then
fill in the Destination: field with the location of your Toolkit
subdirectory.
5. Click on Install.
ΓòÉΓòÉΓòÉ 5. What's New ΓòÉΓòÉΓòÉ
What's New provides information about the latest release of the OS/2 Warp
Toolkit.
The following sections provide information about updates and additions:
- TCP/IP Toolkit Enhancements
- New APIs in OS/2 Warp Server for e-business
- Debugging and Serviceability Enhancements
The following tools have been removed from the Toolkit:
- IBM no longer supports SOM; however, the information about SOM
remains in the Toolkit.
- The ICAT Debugger is no longer included in the Toolkit; however, you
can download the debugger from the following Web site:
http://service.boulder.ibm.com/icat/
- OpenDoc is no longer included in the Toolkit; however, information
concerning OpenDoc is available at the following Web site:
http://www.software.ibm.com/ad/opendoc/
- The Universal Resource Editor (URE) is no longer included in the
Toolkit. This tool has been replaced by the Integrated Resource
Editor (IRE), which is included in IBM C++ Professional Version 4.0.
Information about this product is available at the following Web
site:
http://www.ibmlink.ibm.com
You should also review Important Information before using the tools and
sample programs in the Toolkit.
ΓòÉΓòÉΓòÉ 5.1. TCP/IP Toolkit Enhancements ΓòÉΓòÉΓòÉ
The TCP/IP Toolkit has been upgraded to version 4.21. Enhancements to the
TCP/IP Toolkit are:
New APIs:
- accept_and_recv()
- send_file
A new 32-bit version of the ring-0 library (R0LIB32), which enables
device drivers to call the new 32-bit networking kernel (socket.sys)
without the 16-bit to 32-bit thunk layer.
For information about the new TCP/IP samples added to this Toolkit, refer to
TCP/IP Samples .
ΓòÉΓòÉΓòÉ 5.2. New APIs in OS/2 Warp Server for e-business ΓòÉΓòÉΓòÉ
OS/2 Warp Server for e-business includes some new and some revised APIs. These
APIs relate to control programming functions, particularly those that are
affected by Logical Volume Manager (LVM), and to performance and RAS functions.
For more information, refer to the online book, OS/2 Programming Guide and
Reference Addendum for OS/2 Warp Server for e-business.
ΓòÉΓòÉΓòÉ 5.3. Debugging and Serviceability ΓòÉΓòÉΓòÉ
Major enhancements to the system diagnostic tools (RAS Enhancements) are
provided in FixPak 35 for OS/2 Warp 3.0, FixPak 10 for OS/2 Warp 4.0, and OS/2
Warp Server for e-business. They provide major functional enhancements to the
System Trace and Process Dump facilities, a summary of which is given below.
Full details of these enhancements are provided in the following documents that
are included with the operating system:
OS2\SYSTEM\RAS\TRACE.DOC
OS2\SYSTEM\RAS\DTRACE.DOC
OS2\SYSTEM\RAS\PROCDUMP.DOC
OS2\SYSTEM\RAS\TRSPOOL.DOC
Detailed information on debugging techniques and the use of system debugging
is provided in The OS2 Debugging Handbook (SG244640.INF), which is distributed
with this TOOLKIT.
Any changes and enhancements to serviceability tools introduced with a FixPak
are documented \OS2\INSTALL\README.DBG.
ΓòÉΓòÉΓòÉ 6. Important Information ΓòÉΓòÉΓòÉ
This section describes some items that can affect your development efforts when
using the OS/2 Toolkit.
Compiling with IBM C/2
Compiling with IBM VisualAge C++ for OS/2
Installing IBM VisualAge C++ for OS/2
VoiceType Developer's Toolkit Updates
ΓòÉΓòÉΓòÉ 6.1. Compiling with IBM C/2 ΓòÉΓòÉΓòÉ
The OS/2 Toolkit for OS/2 Warp Version 4.0 and later versions of the Toolkit
are not intended to be used with the IBM C/2, Version 1.1 compiler. If you
choose to use that compiler, you should use version 1.3 of the Toolkit.
The OS/2 Warp Toolkit is intended to be used with the IBM VisualAge C++
compiler.
ΓòÉΓòÉΓòÉ 6.2. Compiling with IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
The latest version of the C Set ++ compiler (now called VisualAge C++) has been
released. VisualAge C++ includes its own version of the OS/2 Warp Toolkit,
which includes updated sample makefiles. Changes to the sample makefiles relate
to the new linker (ILINK) and to the new library (CPPOM30.LIB).
With this version of the OS/2 Warp Toolkit, the same sample makefile changes
have been made so that you can use VisualAge C++.
You can compile the samples included with the OS/2 Warp Toolkit with C Set ++
(using LINK386) by changing any reference to CPPOM30.LIB to:
DDE4MBS.LIB
and changing any reference to ILINK to:
LINK386
Note: The /nofree option must be removed from the LINK386 statement.
ΓòÉΓòÉΓòÉ 6.3. Installing IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
Installing your compiler first and the OS/2 Warp Toolkit last prevents
unexpected results due to environment variable changes (automatic updates to
CONFIG.SYS).
To avoid a downlevel SOM Runtime installed by the VisualAge C++ 3.0 compiler,
follow these steps for installation:
1. Start the installation program for VisualAge C++ 3.0.
2. Deselect the OS/2 Warp Toolkit entries in the installation screen and
proceed with the installation.
3. After completing the installation of VisualAge C++ but before restarting
the system, edit CONFIG.SYS and modify the LIBPATH statement by moving
x:\ IBMCPP\DLL after y:\OS2\DLL, where x is the drive where the VisualAge
C++ compiler is installed and y is the drive where the system files for
OS/2 Warp Version 4 or later are installed. This prevents the SOM Runtime
installed by VisualAge C++ from overwriting the SOM Runtime shipped with
OS/2 Warp.
4. Save the modified CONFIG.SYS and restart your system.
5. Install the the OS/2 Toolkit and restart your system.
ΓòÉΓòÉΓòÉ 6.4. VoiceType Developer's Toolkit Updates ΓòÉΓòÉΓòÉ
The header files and libraries, samples, tools, and documentation associated
with the VoiceType Developer's Toolkit are located in the \TOOLKIT\SPEECH
subdirectories.
The VoiceType Developer's Toolkit includes:
Grammar compiler and its associated documentation
Utilities to be used with grammars
SMAPI.DLL
ΓòÉΓòÉΓòÉ 7. Toolkit Contents ΓòÉΓòÉΓòÉ
This section describes the contents of the OS/2 Warp Toolkit. It contains the
following topics:
Toolkit Roadmap -- provides the directory hierarchy and the folder
hierarchy of the Toolkit.
Header Files -- describes special programming considerations for various
header files included with the OS/2 Warp Toolkit.
Sample Programs -- provides descriptions of the code samples that are
included in the OS/2 Warp Toolkit.
Tools -- provides descriptions of the Presentation Manager, Multimedia,
SOM, TCP/IP, Workplace Shell, and XPG4 tools. It also introduces you to
the interface that installs the debug kernel, symbol files, and debug
version of PM and Workplace Shell and describes tools that support your
debugging efforts.
Online Documentation -- describes the online books of the OS/2 Warp
Toolkit.
ΓòÉΓòÉΓòÉ 7.1. Toolkit Roadmap ΓòÉΓòÉΓòÉ
The tools, samples, and technical documentation in the OS/2 Warp Toolkit are
available in two ways. You can access them through the Toolkit folder and its
subfolders on the Desktop, or you can access them using an OS/2 window or OS/2
full-screen session and changing into the \TOOLKIT subdirectory and its
subdirectories.
ΓòÉΓòÉΓòÉ 7.1.1. Directory Hierarchy ΓòÉΓòÉΓòÉ
The OS/2 Warp Toolkit package has the following directory structure:
\TOOLKIT - Root subdirectory for the Toolkit
Γöé
Γö£ΓöÇ\BIN - Programming tools
Γö£ΓöÇ\BITMAP - Sample multimedia bitmaps
Γö£ΓöÇ\BOOK - Online technical information
Γö£ΓöÇ\DLL - Toolkit dynamic link library (DLL) files
Γö£ΓöÇ\H - C, C++, and DTS header files
Γö£ΓöÇ\HELP - Toolkit help (HLP) files
Γö£ΓöÇ\ICON - Toolkit icon (ICO) files
Γö£ΓöÇ\IDL - Workplace Shell interface definition language (IDL) files
Γö£ΓöÇ\INC - Assembler header (INC) files
Γö£ΓöÇ\IPFC - Information Presentation Facility Compiler (IPFC) files
Γö£ΓöÇ\LIB - Import library (LIB) files
Γö£ΓöÇ\SAMPLES - Samples programs
Γö£ΓöÇ\SOM - SOM subdirectories
ΓööΓöÇ\SPEECH - VoiceType Developer's Toolkit
ΓòÉΓòÉΓòÉ 7.1.2. Folder Hierarchy ΓòÉΓòÉΓòÉ
The OS/2 Warp Toolkit package has the following Workplace Shell folder
hierarchy:
IBM Developer's Toolkit - Root folder of the Toolkit
for OS/2 Warp (contains the README file and the
Γöé other Toolkit folders)
Γöé
Γö£ΓöÇDevelopment Tools - Programming tools
Γö£ΓöÇMultimedia Bitmaps - Sample multimedia bitmaps
Γö£ΓöÇMultimedia Sample Programs - Multimedia sample programs
Γö£ΓöÇOpen32 Samples - Open32 sample programs
Γö£ΓöÇOpenGL Samples - OpenGL sample programs
Γö£ΓöÇOS/2 Sample Programs - Control Program sample programs
Γö£ΓöÇPM Sample Programs - Presentation Manager (PM) sample programs
Γö£ΓöÇREXX Sample Programs - REXX sample programs
Γö£ΓöÇToolkit Information - Online technical books
Γö£ΓöÇVoiceType Developer's Toolkit - VoiceType tools, samples, and online books
ΓööΓöÇWorkplace Shell Sample Programs - Workplace Shell (WPS) sample programs
ΓòÉΓòÉΓòÉ 7.2. Header Files ΓòÉΓòÉΓòÉ
You should be aware of special programming considerations in the following sets
of header files:
Control Program
Multimedia
OS/2
Note: For compatibility with VisualAge C++, the #pragma checkout directives
in all header files have been changed to #pragma info. The #pragma
checkout directive is no longer supported by VisualAge C++. Because the
#pragma info directive provides similar function to #pragma checkout,
the header file changes should not affect code that uses the header
files. If you use the #pragma checkout directive with VisualAge C++, it
generates an "unsupported pragma" error for both C and C++ compilers.
Refer to the VisualAge C++ Language Reference for more details.
ΓòÉΓòÉΓòÉ 7.2.1. Control Program Header Files ΓòÉΓòÉΓòÉ
DosSetDOSProperty() and DosQueryDOSProperty() in BSEDOS.H are not supported. Do
not use these functions.
ΓòÉΓòÉΓòÉ 7.2.2. Multimedia Header Files ΓòÉΓòÉΓòÉ
The multimedia header files listed below are delivered in two different
versions. One version uses conventions compatible with the standard OS/2
header-file format. The other version uses conventions compatible with
Microsoft Windows header files. The Windows-style headers are currently
included for compatibility with earlier multimedia applications, but will be
removed from the Toolkit in the future.
Use the OS/2-style header files for new applications and modify the source code
for existing applications that use the Windows-style headers.
Windows-Style OS/2-Style
CDAUDIO.H CDAUDOS2.H
MCIDRV.H MMDRVOS2.H
MIDI.H MIDIOS2.H
MMIO.H MMIOOS2.H
MMSYSTEM.H MCIOS2.H
ΓòÉΓòÉΓòÉ 7.2.3. OS/2 Header Files ΓòÉΓòÉΓòÉ
Instead of using the SELECTOROF macro in the OS2DEF.H header file, use one of
the following two macros to obtain the selector of a 16:16 address :
#define SELECTOROF(p) (((PUSHORT)&(p))[1])
OR
#define SELECTOROF(p) ((ULONG)(p)>>16)
If you use the selector returned from one of the above macros with the OFFSETOF
and MAKEP macros in the OS2DEF.H header file, you can successfully convert a
16:16 address to a 0:32 address.
ΓòÉΓòÉΓòÉ 7.3. Sample Programs ΓòÉΓòÉΓòÉ
This section describes the sample programs available with the OS/2 Warp
Toolkit.
The sample programs are categorized as follows:
BIDI (Bidirectional)
LAN Server
Multimedia
Open32
OpenGL
OS/2
Presentation Manager
Problem Determination
REXX
TCP/IP
Workplace Shell
Most sample programs are written in C language and demonstrate the use of the
functions of the control program (CP, base OS/2 operating system), the PM
interface, the multimedia (MM) interface, and the Workplace Shell (WPS).
Each sample program serves as a template that can be easily modified for your
own purposes. These programs let you investigate the best way to implement
your own application requirements.
Some of the sample programs require specific hardware devices. When
appropriate, the hardware is listed following the program descriptions.
Without these devices, you can still compile and run the sample programs;
however, you might not receive the full effect of the program. For example, if
a multimedia sample program has audio, you will not hear it unless you have an
audio adapter supported by OS/2 multimedia and speakers installed.
Most samples also contain the overhead routines necessary to create a PM
application, as well as stubs for the basic menu items that all applications
should have.
There are many comments within the source code that clarify technical
information.
Note: Names of the sample programs, in most cases, correspond to their
Toolkit subdirectory names.
ΓòÉΓòÉΓòÉ 7.3.1. Starting Sample Programs ΓòÉΓòÉΓòÉ
There are two ways to start a sample program:
From the Desktop:
When installed, all sample programs (with the exception of the
bidirectional samples, TCP/IP samples, Problem Determination samples, LAN
Server samples, some of the Multimedia samples, and some of the Workplace
Shell samples) appear in the sample programs folders located within the
Toolkit folder. To start a sample program, open the Toolkit folder, open
the folder representing the type of samples you wish to execute, and then
select the appropriate sample program.
From an OS/2 command prompt:
Change to the subdirectory where the sample is located, type the name of
the executable file and press Enter.
Most samples include a description file (or makefile) that you can use to
build the sample yourself. The name of the makefile is either MAKEFILE or
filename.MAK, where filename refers to the name of the sample. To build the
sample,
1. Go to an OS/2 command prompt and change to the subdirectory where the
makefile is located.
You must execute these commands from the subdirectory where the makefile
is located in order to build the sample correctly.
2. Enter one of the following, depending on the name of the makefile:
When the name of the makefile is MAKEFILE, type:
NMAKE
When the name of the makefile is filename.MAK, type:
NMAKE /f filename.MAK
For information about the NMAKE tool, refer to the Tools Reference.
Note: The makefile assumes that you are using the IBM VisualAge C++ for OS/2
compiler for code compilation.
ΓòÉΓòÉΓòÉ 7.3.2. BIDI Sample Programs ΓòÉΓòÉΓòÉ
These samples demonstrate the use of the Bidirectional Language support
available in the Arabic and Hebrew versions of OS/2. There are two sets of
samples provided: one set for the Arabic language and the other set for the
Hebrew language. For both languages, there are two samples:
STYLE
TELDIR
Note: Programs that use the bidirectional support functions will run only on
the Arabic and Hebrew versions of the OS/2 operating system. These are
currently the only versions of the operating system that support the
bidirectional support functions.
ΓòÉΓòÉΓòÉ 7.3.2.1. STYLE Sample Program ΓòÉΓòÉΓòÉ
STYLE is a sample program that demonstrates the bidirectional language support
features of PM controls and other system components.
Note: The Arabic versions of this sample (located in
\TOOLKIT\SAMPLES\BIDI\ARABIC), require the Arabic version of OS/2 to
run, and the Hebrew versions of this sample (located in
\TOOLKIT\SAMPLES\BIDI\HEBREW), require the Hebrew version of OS/2 to
run.
ΓòÉΓòÉΓòÉ 7.3.2.2. TELDIR Sample Program ΓòÉΓòÉΓòÉ
TELDIR is a simple bilingual telephone directory application that demonstrates
how language and orientation selections can be set dynamically by an
application that uses bidirectional functions.
Note: The Arabic versions of this sample require the Arabic version of OS/2 to
run, and the Hebrew versions of this sample require the Hebrew version
of OS/2 to run.
ΓòÉΓòÉΓòÉ 7.3.3. Device Driver Sample Programs ΓòÉΓòÉΓòÉ
Physical device driver (PDD) and virtual device driver (VDD) samples are not
included in the OS/2 Warp Toolkit. See the Developer Connection Device Driver
Kit for OS/2 for device driver samples.
ΓòÉΓòÉΓòÉ 7.3.4. LAN Server Sample Programs ΓòÉΓòÉΓòÉ
The LAN Server sample programs are as follows:
ACCESS32 - Access Control Profile Sample
ALIAS32 - File Resource Alias Sample
FILEEN32 - Server Open Files Sample
MESSAG32 - Network Message Sample
MLOGON32 - Network Logon Sample
SADMIN32 - Server Administration Sample
USER32 - User Account Sample
ΓòÉΓòÉΓòÉ 7.3.4.1. ACCESS32 ΓòÉΓòÉΓòÉ
ACCESS32 (located in \TOOLKIT\SAMPLES\LANSERV\ACCESS32) returns all the access
control profiles (ACPs) for a particular resource. You may alter any given ACP
by specifying the user and the new permissions.
ACCESS32 demonstrates how to use the following NetAPI functions:
Net32AccessAdd, Net32AccessGetInfo, and Net32AccessSetInfo.
This program can operate both locally and remotely. The machine running this
program must be logged on to the LAN with administrator authority.
ΓòÉΓòÉΓòÉ 7.3.4.1.1. Starting ACCESS32 ΓòÉΓòÉΓòÉ
To query a resource's ACP, type:
access32 <resource>
To change the ACP for a user, type:
access32 <resource> <name:permissions> <name:permissions> ...
ΓòÉΓòÉΓòÉ 7.3.4.2. ALIAS32 ΓòÉΓòÉΓòÉ
ALIAS32 (located in \TOOLKIT\SAMPLES\LANSERV\ALIAS32) adds a file resource
alias and shares it, gives the USERS group read-only access to the resource,
and adds a directory limit to the resource.
ALIAS32 demonstrates how to use the following NetAPI functions:
Net32WkstaGetInfo
Net32ServerEnum2
Net32GetDCName
Net32AliasAdd
Net32AliasDel
Net32ShareAdd
Net32AccessAdd
Net32AccessGetInfo
Net32AccessSetInfo
Net32DASDAdd
ΓòÉΓòÉΓòÉ 7.3.4.2.1. Starting ALIAS32 ΓòÉΓòÉΓòÉ
To start ALIAS32 from a command line, type:
alias32 aliasname resourcename
or
alias32 aliasname servername resourcename
where:
aliasname Is an 8-byte name that is not currently in use.
servername Specifies the server that the alias resource resides on.
If not specified, it is assumed that the alias resource
resides on the local machine.
resourcename Is a fully qualified path name.
ALIAS32 checks that the device is shared and returns basic information on the
device type.
ΓòÉΓòÉΓòÉ 7.3.4.3. FILEEN32 ΓòÉΓòÉΓòÉ
FILEEN32 (located in \TOOLKIT\SAMPLES\LANSERV\FILEEN32) returns information on
open files on a specific server. You can choose to view a list of all open
files or to restrict the list by device path or user. You can leave both the
path and the user ID unspecified to get information on all files opened by all
users on the specified server.
FILEEN32 demonstrates how to use the following NetAPI function: Net32FileEnum2.
ΓòÉΓòÉΓòÉ 7.3.4.3.1. Starting FILEEN32 ΓòÉΓòÉΓòÉ
To start FILEEN32 for a remote server, type:
fileen32 servername basepath
To start FILEEN32 for a local server, type:
fileen32 basepath username
where:
servername Indicates the machine where open files will be enumerated.
If a servername is specified, it must be the first
parameter specified. If no servername is specified, open
files at the local server will be enumerated.
basepath Is in the form of:
drive:\pathname
Only open files matching this basepath will be enumerated.
If basepath is not specified, all open files are
enumerated.
username Is the name of an existing user. If username is
specified, only files opened by this user are enumerated.
The username must be specified as the last parameter.
If no parameters are specified, all open files at the local server are
enumerated.
This program must be run by an administrator. The opened files that are to be
listed must be on a redirected drive on the target server.
ΓòÉΓòÉΓòÉ 7.3.4.4. MESSAG32 ΓòÉΓòÉΓòÉ
MESSAG32 (located in \TOOLKIT\SAMPLES\LANSERV\MESSAG32) is designed to send
simple messages through the messenger service. You can send messages from the
local machine or a remote server. You can send messages to specific users or a
domain group, or broadcast to an entire LAN.
MESSAG32 uses Net32MessageBufferSend to send the message.
ΓòÉΓòÉΓòÉ 7.3.4.4.1. Starting MESSAG32 ΓòÉΓòÉΓòÉ
To start MESSAG32 from the command line, type:
messag32
MESSAG32 prompts the user for where the message should be sent from:
1 - the local machine
2 - a remote server
If the message is being sent from a remote server, MESSAG32 prompts the user
for a servername. MESSAG32 then prompts the user for who the message should be
sent to as follows:
1 - a user
2 - a domain
3 - all the requesters on the LAN
If the message is being sent to a user or domain, MESSAG32 prompts the user for
the name of the user or domain to send the message to. Finally, MESSAG32
prompts the user to enter a text string for the message.
ΓòÉΓòÉΓòÉ 7.3.4.5. MLOGON32 ΓòÉΓòÉΓòÉ
MLOGON32 (located in \TOOLKIT\SAMPLES\LANSERV\MLOGON32) logs on a user, waits
for the user to press the Spacebar, and logs off the user. The user name,
password (if required), and domain name are passed as command line parameters
to the program.
ΓòÉΓòÉΓòÉ 7.3.4.5.1. Starting MLOGON32 ΓòÉΓòÉΓòÉ
To start MLOGON32 from the command line, type:
mlogon32 username password domainname
or
mlogon32 username domainname
ΓòÉΓòÉΓòÉ 7.3.4.6. SADMIN32 ΓòÉΓòÉΓòÉ
SADMIN32 (located in \TOOLKIT\SAMPLES\LANSERV\SADMIN32) executes a command on a
remote or local server. The command to be executed on the server is passed as a
command line parameter to this program, but it must reside on a disk visible to
the target server.
SADMIN32 demonstrates how to use NetServerAdminCommand, which is a NetAPI
function.
ΓòÉΓòÉΓòÉ 7.3.4.6.1. Starting SADMIN32 ΓòÉΓòÉΓòÉ
To start SADMIN32 from the command line, type:
sadmin32 \\targetservername command
ΓòÉΓòÉΓòÉ 7.3.4.7. USER32 ΓòÉΓòÉΓòÉ
USER32 (located in \TOOLKIT\SAMPLES\LANSERV\USER32) is designed to access and
control user account information. USER32 can display information about a user,
delete a user, or create a new user. When a new user is created, USER32
creates a new alias, gives the user access to it, and makes it a logon
assignment for the user; creates a new group and adds the user to it; creates a
private application definition and assigns that too to the user.
USER32 demonstrates how to use the following NetAPI functions:
Net32AccessAdd
Net32AccessGetInfo
Net32AccessSetInfo
Net32AliasAdd
Net32AliasDel
Net32AliasGetInfo
Net32AppAdd
Net32GetDCName
Net32GroupAdd
Net32GroupAddUser
Net32GroupDel
Net32GroupGetInfo
Net32ServerEnum2
Net32WkstaGetInfo
Net32UserAdd
Net32UserDCDBInit
Net32UserDel
Net32UserGetGroups
Net32UserGetInfo
Net32UserGetLogonAsn
Net32UserSetAppSel
Net32UserSetLogonAsn
NetStatisticsGet2 retrieves information from both the requester and the server
portions of a server machine. Note that these two sets of information, even
when they are in the same machine, are quite different.
ΓòÉΓòÉΓòÉ 7.3.4.7.1. Starting USER32 ΓòÉΓòÉΓòÉ
To display information about a user, type:
user32 username
To delete a user, type:
user32 username /DELETE
To create a new user, type:
user32 username /ADD
where username is the user ID of the account.
ΓòÉΓòÉΓòÉ 7.3.5. Multimedia Sample Programs ΓòÉΓòÉΓòÉ
The Multimedia sample programs are as follows:
ADMCT
ASYMREC
AVCINST
BEEHIVE
CAPSAMP
CAPTION
CASECONV
CDMCIDRV
Control File Templates
CLOCK
CODEC
DAUDIO
DIVE
DOUBPLAY
DUET1
DUET2
FSDIVE
FSSHT
MCD Command Tables
MCDTEMP
MCISPY
MCISTRNG
MIDISAMP
MMBROWSE
MMOTTK
MOVIE
RECORDER
Short Control File Templates
SHRC
TUNER
ULTIEYES
ULIOT
ΓòÉΓòÉΓòÉ 7.3.5.1. ADMCT Sample Program ΓòÉΓòÉΓòÉ
ADMCT (located in \TOOLKIT\SAMPLES\MM\ADMCT) is an example of a media control
driver (MCD) that demonstrates how to control a streaming device. Streaming
devices use the services of the sync/stream manager (SSM) of OS/2 multimedia to
control the data stream from a source location to a target location.
ΓòÉΓòÉΓòÉ 7.3.5.2. ASYMREC Sample Program ΓòÉΓòÉΓòÉ
ASYMREC (located in \TOOLKIT\SAMPLES\MM\ASYMREC) illustrates how to include
asymmetric recording function in your multimedia application. Modules include
source code extracted from the Video IN recorder application, which enables
frame-step recording using Ultimotion compression techniques.
ΓòÉΓòÉΓòÉ 7.3.5.3. AVCINST I/O Procedure Sample ΓòÉΓòÉΓòÉ
AVCINST (located in \TOOLKIT\SAMPLES\MM\AVCINST) illustrates how an application
can install and remove an I/O procedure to use multimedia input/output (MMIO)
file services. The AVC I/O procedure installation sample is a simple PM
application that enables you to install or remove the audio AVC I/O procedure,
AVCAPROC.DLL.
Hardware requirements:
Computer capable of running OS/2 Warp
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.4. BEEHIVE Sample Program ΓòÉΓòÉΓòÉ
BEEHIVE demonstrates the power of compiled sprites by comparing the performance
of a typical sprite algorithm against a compiled sprite.
When the application first starts, it will display a single sprite moving in a
random path around the application window. You can add sprites by holding down
the H key. As the sprite count increases, the effects on the frame rate will
become evident. The actual frame rate will be displayed on the title bar.
You will be able to switch the application from compiled sprites to normal
sprites using a menu. As the number of sprites increases, the difference in
performance from compiled to normal sprites becomes more dramatic.
While DIVE offers a high-performance API for blitting images to the screen, it
was not designed for implementing sprites. BEEHIVE demonstrates a technique for
implementing high-performance sprites in an OS/2 Warp/DIVE environment. The
source code provided offers a good starting point for building a
high-performance sprite engine.
Hardware Requirements:
Computer capable of running OS/2 Warp
SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)
Software Requirements:
OS/2 Warp Version 3 or later
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.4.1. Starting BEEHIVE ΓòÉΓòÉΓòÉ
You can start BEEHIVE in two ways:
From the command line, change to the TOOLKIT\SAMPLES\MM\BEEHIVE
subdirectory and type:
BEEHIVE
From the Desktop, open the Toolkit folder and then:
1. Open the Multimedia Samples folder.
2. Open the Video Samples folder.
3. Double-click on Beehive.
ΓòÉΓòÉΓòÉ 7.3.5.5. CAPSAMP Sample Program ΓòÉΓòÉΓòÉ
CAPSAMP (located in \TOOLKIT\SAMPLES\MM\CAPSAMP) and the caption utility
functions (located in \TOOLKIT\SAMPLES\MM\CAPDLL) are part of the sample
captioning system provided with the OS/2 Warp Toolkit. CAPSAMP demonstrates how
captioning can be integrated into applications using caption files in
conjunction with the caption utility functions.
Hardware requirements:
Computer capable of running OS/2 Warp
Speaker or headphones
Sound card
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.6. CAPTION Sample Program ΓòÉΓòÉΓòÉ
CAPTION (located in \TOOLKIT\SAMPLES\MM\CAPTION) is part of the sample
captioning system provided with the OS/2 Warp Toolkit. The caption creation
utility program creates a "caption" file. It enables you to synchronize an
audio file with a text file.
This concept can be extended beyond audio and text to apply to many
possibilities, such as synchronizing audio and video or synchronizing video and
text.
Note: In order for the Caption sample to work correctly, captioning must be
enabled in the operating system. To enable captioning proceed as
follows:
Open the Multimedia Setup object in the Multimedia folder
Go to the System page
Place a check mark in the Captioning check box.
ΓòÉΓòÉΓòÉ 7.3.5.7. CASECONV I/O Procedure Sample ΓòÉΓòÉΓòÉ
CASECONV (located in \TOOLKIT\SAMPLES\MM\CASECONV) provides a simple example of
how to write a file format I/O procedure (without illustrating the use of data
translation). This sample performs case conversion of text.
ΓòÉΓòÉΓòÉ 7.3.5.8. CDMCT Sample Program ΓòÉΓòÉΓòÉ
CDMCT (located in \TOOLKIT\SAMPLES\MM\CDMCIDRV) is an example of a media
control driver (MCD) that demonstrates how to control a non-streaming device.
Non-streaming devices stream data within the device.
ΓòÉΓòÉΓòÉ 7.3.5.9. Control File Templates ΓòÉΓòÉΓòÉ
The \TOOLKIT\SAMPLES\MM\CF subdirectory contains control file templates you can
utilize when installing a program using MINSTALL.
ΓòÉΓòÉΓòÉ 7.3.5.10. CLOCK Sample Program ΓòÉΓòÉΓòÉ
CLOCK (located in \TOOLKIT\SAMPLES\MM\CLOCK) illustrates the use of the memory
playlist feature of OS/2 multimedia. The memory playlist feature provides for
easy manipulation of multimedia in memory to create unique effects based on
user input or other dynamic events.
Hardware requirements:
Computer capable of running OS/2 Warp
Speaker or headphones
Sound card
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.11. CODEC Sample Program ΓòÉΓòÉΓòÉ
CODEC (located in \TOOLKIT\SAMPLES\MM\CODEC) illustrates how to write a CODEC
procedure to include compression and decompression routines in your multimedia
applications. A CODEC procedure operates on data within a file or buffer.
ΓòÉΓòÉΓòÉ 7.3.5.12. DAUDIO Sample Program ΓòÉΓòÉΓòÉ
DAUDIO (direct audio) demonstrates the use of the direct audio interface. This
high speed audio interface enables an application to send audio data directly
to the amp-mixer device. The sample demonstrates the steps required to set up
and use this new interface for playing and recording digital audio data.
See the Multimedia Application Programming Guide and the Multimedia Programming
Reference for more information on the direct audio interface.
Hardware requirements:
Computer capable of running OS/2 Warp
Sound card
Speakers or headphones
Software requirements:
OS/2 Warp Version 4 or later
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.12.1. Starting DAUDIO ΓòÉΓòÉΓòÉ
You can start DAUDIO in two ways:
From the command line, change to the TOOLKIT\SAMPLES\MM\DAUDIO
subdirectory and type:
DAUDIO
From the Desktop, open the Toolkit folder and then:
1. Open the Multimedia Samples folder.
2. Open the Audio Samples folder.
3. Double-click on Direct Audio.
ΓòÉΓòÉΓòÉ 7.3.5.13. DIVE Sample Program ΓòÉΓòÉΓòÉ
DIVE (located in \TOOLKIT\SAMPLES\MM\DIVE) illustrates the use of the direct
interface video extensions. DIVE provides optimized blitting performance for
motion video subsystems and applications that perform rapid screen updates in
the OS/2 PM and full-screen environments. Using DIVE interfaces, applications
can either write directly to video memory or use the DIVE blitter. The DIVE
blitter takes advantage of acceleration hardware when present and applicable to
the function being performed.
Note: The DIVE sample requires OS/2 Warp Version 3 or later in order to
execute properly. The files for the samples will be installed when the
samples are selected, but Workplace Shell objects will not be created
for them if the installed operating system is not OS/2 Warp Version 3 or
higher.
The OS/2 Warp color support defaults to 16 colors. This means that your setup
needs to be updated; otherwise, the DIVE sample will not run.
The maximum window size of this sample has been limited to 640x480 because
larger window sizes can cause excessive swapping on machines with less than
16MB.
Hardware requirements:
Computer capable of running OS/2 Warp
SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)
Software requirements:
OS/2 Warp
Multimedia support
Software motion video
ΓòÉΓòÉΓòÉ 7.3.5.14. DOUBPLAY Sample Program ΓòÉΓòÉΓòÉ
DOUBPLAY (located in \TOOLKIT\SAMPLES\MM\DOUBPLAY) enables an application to
play audio files directly from application memory buffers. An array of multiple
playlist structures that combines playlist commands with data buffers can be
constructed to perform complex operations on multiple buffers.
This sample takes a single wave file, MYWAVE.WAV, and plays it using a memory
playlist. The playlist is constructed as a circular buffer composed of a series
of small buffers, the sum of which might be larger than the size of the .WAV
file. This circular buffer is used to repeatedly play an audio file when the
PLAY button is selected. As each buffer in the playlist is expended, the
application refills the expended buffer with new data from the .WAV file. When
all the buffers in the playlist have been expended, the playlist branches back
to the first buffer to play the new data. This circular buffering process
continues until the STOP button is selected or the application is closed.
Hardware requirements:
Computer capable of running OS/2 Warp
Speakers or headphones
Sound card
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.15. DUET1 Sample Program ΓòÉΓòÉΓòÉ
DUET1 (located in \TOOLKIT\SAMPLES\MM\DUET1) illustrates the OS/2 multimedia
concept of device grouping and integrating multimedia into an application's
help information. This sample demonstrates the concepts of grouping two
streaming devices.
Note: The Streaming Device Duet sample (DUET1, located in
\TOOLKIT\SAMPLES\MM\DUET1) requires that the IBM M-Audio Capture and
Playback Adapter card be installed in order for the sample to execute
properly.
Hardware requirements:
Computer capable of running OS/2 Warp
Speaker or headphones
Sound card (capable of playing two mono wave files simultaneously such as
the IBM M-AUDIO card)
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.16. DUET2 Sample Program ΓòÉΓòÉΓòÉ
DUET2 (located in \TOOLKIT\SAMPLES\MM\DUET2) illustrates the OS/2 multimedia
concept of device grouping and integrating multimedia into an application's
help information. This sample demonstrates how one of the devices in the
multimedia device group can be a non-streaming device.
Hardware requirements:
Computer capable of running OS/2 Warp
Speaker or headphones
Sound card
CD-ROM drive
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.17. FSDIVE Sample Program ΓòÉΓòÉΓòÉ
FSDIVE (full-screen DIVE) demonstrates the use of multimedia's direct interface
video extensions (DIVE) by repeatedly displaying a short animation sequence.
The animation is performed by sequentially displaying a series of up to 16
bitmaps in a PM window. You can display the default bitmaps that are included
with the sample or specify the bitmaps by passing the file names as command
line parameters.
After the application is started, you can move or resize the window and observe
the effects on the frame rate of the animation (displayed on the title bar).
The latest version of the DIVE interface has been enhanced to allow an
application to take over the display and change the resolution. This enables an
application to run in a full screen without paying the performance penalty of
maintaining a high-resolution Desktop. Full-screen DIVE can be activated by
using the Alt+Home hot key.
Note: To run the full-screen DIVE sample on an OS/2 Warp Version 3 system, you
must first install full-screen support by running GSRVINST.EXE (located
in \TOOLKIT\SAMPLES\MM\FSDIVE). See the GAMESRVR.DOC file in the same
directory for more details. This installation is not necessary on an
OS/2 Warp Version 4 or later system.
Hardware Requirements:
Computer capable of running OS/2 Warp
SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)
Software Requirements:
OS/2 Warp Version 3 or later
Multimedia support
Software motion video
The maximum window size of this sample has been limited to 640x480 because
larger window sizes can cause excessive swapping on machines with less than
16MB.
ΓòÉΓòÉΓòÉ 7.3.5.17.1. Starting FSDIVE ΓòÉΓòÉΓòÉ
You can start FSDIVE in two ways:
From the command line, change to the TOOLKIT\SAMPLES\MM\FSDIVE
subdirectory and type:
FSDIVE
From the Desktop, open the Toolkit folder and then:
1. Open the Multimedia Samples folder.
2. Open the Video Samples folder.
3. Double-click on FS Dive.
ΓòÉΓòÉΓòÉ 7.3.5.18. FSSHT Sample Program ΓòÉΓòÉΓòÉ
FSSHT (located in \TOOLKIT\SAMPLES\MM\FSSHT) contains a sample file system
stream handler.
ΓòÉΓòÉΓòÉ 7.3.5.19. MCD Command Tables ΓòÉΓòÉΓòÉ
Before a media control driver (MCD) can interpret a string command, the media
device manager (MDM) must use a command table to change the string into an
equivalent procedural command. Represented as resources to the driver, command
tables are created using the RCDATA type of resource. The resource number of
the RCDATA block is the device type number. The \TOOLKIT\SAMPLES\MM\MCDTBL
subdirectory contains command tables for each of the following devices:
Amp Mixer
CD-ROM/XA
CD Audio
Digital Video
Sequencer
Videodisc
Wave Audio
If you want to support device-specific messages, you must create a device-
specific command table.
ΓòÉΓòÉΓòÉ 7.3.5.20. MCDTEMP Template ΓòÉΓòÉΓòÉ
MCDTEMP (located in \TOOLKIT\SAMPLES\MM\MCDTEMP) provides a basic template to
write a media control driver (MCD). Refer to the \ADMCT and \CDMCIDRV
subdirectories for specific streaming or to the multimedia I/O (MMIO) samples.
ΓòÉΓòÉΓòÉ 7.3.5.21. MCISPY Sample Program ΓòÉΓòÉΓòÉ
MCISPY (located in \TOOLKIT\SAMPLES\MM\MCISPY) monitors media control interface
messages that are exchanged between applications and the OS/2 multimedia
subsystem.
In addition to teaching you about multimedia messages, MCISPY also serves as a
powerful debugging aid.
The MCISPY sample must be manually set up. To do so, follow these steps:
1. Copy the MDM.DLL file located in the \MMOS2\DLL subdirectory to the
\TOOLKIT\DLL subdirectory.
2. Use the DLLRNAME tool (available with C Set ++ or VisualAge C++) to
rename the copy to MCI.DLL. To do this, type:
DLLRNAME MDM.DLL MDM=MCI
3. Create the executable (MCISPY.EXE) and the stub DLL (MDM.DLL) by running
the MCISPY makefile.
4. Place the stub MDM.DLL, built by the MCISPY makefile, in the LIBPATH so
that it is recognized prior to the MDM.DLL file located in the \MMOS2\DLL
subdirectory. The source code for the stub MDM.DLL is included in the
MCISPY sample.
5. Restart your system.
Note: Driver notifications might not be visible in releases prior to OS/2
Warp Version 3. These notifications include all multimedia messages
routed through mdmDriverNotify().
Hardware requirements:
Computer capable of running OS/2 Warp
Software requirements:
Multimedia support
OS/2 Warp
Note: The files for the samples will be installed when the samples are
selected, but Workplace Shell objects will not be created for them
if the installed operating system is not OS/2 Warp.
ΓòÉΓòÉΓòÉ 7.3.5.22. MCISTRNG Sample Program ΓòÉΓòÉΓòÉ
MCISTRNG (located in \TOOLKIT\SAMPLES\MM\MCISTRNG) serves as a powerful testing
and debugging tool that enables developers, who are writing media drivers, to
control their devices at the application level. The string test sample
illustrates how an application uses the interpretive string interface provided
by the media control interface.
This sample also illustrates how notification messages are returned from the
media drivers to the application.
Hardware requirements:
Computer capable of running OS/2 Warp
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.23. MIDISAMP Sample Program ΓòÉΓòÉΓòÉ
MIDISAMP illustrates the use of the real-time MIDI (RTMIDI) programming
concepts and usage of the new RTMIDI API. This sample initializes and sets up a
small MIDI node network and subsequently sends a MIDI message from an
application node to a hardware node, thereby demonstrating MIDI playback.
The RTMIDI functions are documented in the Multimedia Programming Reference.
Hardware requirements:
Computer capable of running OS/2 Warp
A sound card supported by a "Type A" RTMIDI device driver
Note: Type A device drivers provide direct hardware support for RTMIDI. The
following is a list of supported Type A device drivers:
MPU-401 - A generic driver for sound cards with true hardware MPU-401
compatibility (for example, not the AWE-32). It uses only UART dumb
mode. This driver is also an MMPM/2 driver. It can be found on the DDPak
CD-ROM.
OPL-3 - A generic driver for sound cards with true hardware Yamaha OPL-3
FM chips. This driver is also an MMPM/2 driver. It can be found on the
DDPak CD-ROM.
PAS-16 - A device driver for the Media Vision PAS-16 line of audio cards.
This driver is also an MMPM/2 driver. It can be installed using the
Selective Install program.
Software requirements:
OS/2 Warp Version 4 or later
Multimedia support
Standard MIDI file
ΓòÉΓòÉΓòÉ 7.3.5.23.1. Starting MIDISAMP ΓòÉΓòÉΓòÉ
You can start MIDISAMP in two ways:
From the command line, change to the TOOLKIT\SAMPLES\MM\MIDI subdirectory
and type:
MIDISAMP filename.mid
where filename.mid is a MIDI file.
From the Desktop, open the Toolkit folder and then:
1. Open the Multimedia Samples folder.
2. Open the Audio Samples folder.
3. Double-click on MIDI Samp.
Sample MIDI files are located in the MMOS2\SOUNDS subdirectory.
ΓòÉΓòÉΓòÉ 7.3.5.24. MMBROWSE Sample Program ΓòÉΓòÉΓòÉ
MMBROWSE (located in \TOOLKIT\SAMPLES\MM\MMBROWSE) illustrates how to use the
multimedia I/O (MMIO) subsystem to install I/O procedures for various image
formats and then convert these image formats to OS/2 bitmaps.
Hardware requirements:
Computer capable of running OS/2 Warp
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.25. MMOTTK I/O Procedure Sample ΓòÉΓòÉΓòÉ
MMOTTK (located in \TOOLKIT\SAMPLES\MM\MMIOPROC) provides an example of how to
write an I/O procedure for use with image file formats. This sample enables
file format transparency for M-Motion still video files and illustrates the use
of data translation.
ΓòÉΓòÉΓòÉ 7.3.5.26. MOVIE Sample Program ΓòÉΓòÉΓòÉ
MOVIE (located in \TOOLKIT\SAMPLES\MM\MOVIE) demonstrates device control of a
software motion video device.
This sample also illustrates how to cut, copy, paste, and delete movie data
from an application.
A movie can be played in an application-defined window or in the system default
window provided by the software motion video subsystem.
Note: If you installed the OS/2 Warp Toolkit from diskette, the Movie sample
(located in \TOOLKIT\SAMPLES\MM\MOVIE) does not contain the MOVIE.AVI
file necessary to execute the application. Copy any .AVI file from the
\MMOS2\MOVIES subdirectory on the drive on which you have OS/2
multimedia installed. The .AVI file should be copied to the
\TOOLKIT\SAMPLES\MM\MOVIE subdirectory on which you have the OS/2 Warp
Toolkit samples installed, and the target name of the file should be
MOVIE.AVI.
Hardware requirements:
Computer capable of running OS/2 Warp
Speakers or headphones
Sound card
SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)
Software requirements:
OS/2 Warp
Multimedia support
Software motion video
ΓòÉΓòÉΓòÉ 7.3.5.27. RECORDER Sample Program ΓòÉΓòÉΓòÉ
RECORDER (located in \TOOLKIT\SAMPLES\MM\RECORDER) illustrates the concept of
recording audio through the media control interface and how to query a device
to find out the recording capabilities.
This sample also illustrates how to change the audio recording and audio device
properties, such as bits per sample, samples per second, input level, and input
source.
Hardware requirements:
Computer capable of running OS/2 Warp
Speaker or headphones
Sound card
Software requirements:
OS/2 Warp
Multimedia support
ΓòÉΓòÉΓòÉ 7.3.5.28. Short Control File Templates ΓòÉΓòÉΓòÉ
The \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory contains a simple example of
control file templates you can use when installing a program using MINSTALL.
ΓòÉΓòÉΓòÉ 7.3.5.29. SHRC Sample Program ΓòÉΓòÉΓòÉ
SHRC (located in \TOOLKIT\SAMPLES\MM\SHRC) provides a sample stream handler
resource file.
ΓòÉΓòÉΓòÉ 7.3.5.30. TUNER Sample Program ΓòÉΓòÉΓòÉ
TV tuner cards allow a desktop PC to receive and display broadcast television
signals. TUNER (located in \TOOLKIT\SAMPLES\MM\TUNER), provides an example of
how to use the media control interface (MCI) string interface to control a
tuner card.
When the application is running, the display window can be sized and a TV
channel can be selected. The channel can be selected through up/down buttons or
a text entry field displayed at the bottom of the window.
Hardware requirements:
Computer capable of running OS/2 Warp
TV tuner card (such as the WinTV Basic)
Software requirements:
OS/2 Warp
Multimedia support
Appropriate drivers for installed tuner card
A TV tuner card is handled as a digital video device by the multimedia
subsystem. A typical system has one or more digital video devices, with
digitalvideo01 assigned to software motion video. By default this sample opens
the digitalvideo02 device. If the tuner card is not assigned to digital video
2 an alternate device ordinal must be provided at the command line with the
following format:
/d=digitalvideoxx
where xx is a two digit number, padded on the left with zero.
For example:
/d=digitalvideo03
Most TV tuner cards, such as the Hauppauge WinTV card, support several video
sources. The connector number that corresponds to the tuner video source is
dependent on the hardware and might not be the same for each tuner card. The
connector number is not changed by this sample. Instead, it uses the default
connector number that is set by the Multimedia Setup program.
ΓòÉΓòÉΓòÉ 7.3.5.31. ULTIEYES Sample Program ΓòÉΓòÉΓòÉ
ULTIEYES (located in \TOOLKIT\SAMPLES\MM\ULTIEYES) demonstrates the use of
non-linear video by displaying segments from a movie clip in response to input
from the mouse.
Hardware requirements:
SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system)
Software requirements:
Multimedia support
Software motion video
OS/2 Warp
Note: The files for the samples will be installed when the samples are
selected, but Workplace Shell objects will not be created for them
if the installed operating system is not OS/2 Warp Version 3.
ΓòÉΓòÉΓòÉ 7.3.5.32. ULIOT I/O Procedure Sample ΓòÉΓòÉΓòÉ
ULIOT (located in \TOOLKIT\SAMPLES\MM\ULTIMOIO) provides a detailed example of
what you need to consider when writing I/O procedures for software motion video
file formats. This sample program includes CODEC support and illustrates how to
integrate common and file-format-specific code to support multiple I/O
procedures.
ΓòÉΓòÉΓòÉ 7.3.6. Open32 Samples ΓòÉΓòÉΓòÉ
The following Open32 samples are included in the OS/2 Warp Toolkit:
Browser
HiWorld
ToyBox
DLL Initialization Entry Point (DLLMAIN.C)
WinMain Wrapper Function (MAIN.C)
Note: Open32 was formerly known as the IBM Developer API Extensions for OS/2.
ΓòÉΓòÉΓòÉ 7.3.6.1. Browser ΓòÉΓòÉΓòÉ
The Browser sample enables you to view the lines of text files in a Multiple
Document Interface (MDI) environment. The sample provides files containing the
program source code. You can open one or more of them, scroll them, change
their display fonts, and arrange their windows or icons inside the sample
program window.
There are two versions of the Browser sample. The Win32 version, located in the
\TOOLKIT\SAMPLES\OPEN32\BROWSER subdirectory, will build without source changes
on a Win32 system with the appropriate development tools. (Win32 tools are not
provided with the OS/2 Warp Toolkit.)
The OS/2 version of Browser is located in the \TOOLKIT\SAMPLES\OPEN32\BROWSER2
subdirectory.
ΓòÉΓòÉΓòÉ 7.3.6.2. HiWorld ΓòÉΓòÉΓòÉ
HiWorld is a simple Windows 32-bit (Win32) application that displays the
following text, centered in the client area of the main window:
Hello, World
There are two versions of the HiWorld sample. The Win32 version, located in the
\TOOLKIT\SAMPLES\OPEN32\HIWORLD subdirectory, will build without source changes
on a Win32 system with the appropriate development tools. (Win32 tools are not
provided with the OS/2 Warp Toolkit.)
The OS/2 version of HiWorld is located in the \TOOLKIT\SAMPLES\OPEN32\HIWORLD2
subdirectory along with a README that briefly describes the steps that were
taken to convert the Win32 version of HiWorld to this native OS/2 executable.
ΓòÉΓòÉΓòÉ 7.3.6.3. ToyBox ΓòÉΓòÉΓòÉ
ToyBox is a basic Win32 application that uses bit-block transfer (BitBlt) to
display a large number of simple bitmaps on the display screen and give them
motion. It moves the objects around the client portion of the screen and makes
the objects appear to change shape and rotate.
There are two versions of the ToyBox sample. The Win32 version, located in the
\TOOLKIT\SAMPLES\OPEN32\TOYBOX subdirectory, will build without source changes
on a Win32 system with the appropriate development tools. (Win32 tools are not
provided with the OS/2 Warp Toolkit.)
The OS/2 version of ToyBox is located in the \TOOLKIT\SAMPLES\OPEN32\TOYBOX2
subdirectory.
ΓòÉΓòÉΓòÉ 7.3.6.4. DLL Initialization Entry Point ΓòÉΓòÉΓòÉ
The DLLMAIN.C file (located in the \TOOLKIT\SAMPLES\OPEN32\DLLENTRY
subdirectory) contains the DLL initialization/termination function, which is
called when a process gains or loses access to the DLL. The .DEF file used to
build the DLL needs to specify INITINSTANCE and TERMINSTANCE; otherwise, this
function will be called only for the first process to gain access and the last
process to free up the DLL.
This implementation is for IBM VisualAge C++ and assumes that the C Runtime
library is being statically linked to the DLL and that the library uses C++
classes.
ΓòÉΓòÉΓòÉ 7.3.6.5. WinMain Wrapper Function ΓòÉΓòÉΓòÉ
The MAIN.C file (located in the \TOOLKIT\SAMPLES\OPEN32\WINMAIN subdirectory)
is provided as a helper (stub) to demonstrate how to invoke the Windows WinMain
function from OS/2.
This is the "main" wrapper for an application based on Open32. It initializes
the Alternative Windows Emulator (AWE) environment, calls the WinMain function,
and upon completion, calls the WinTerm function to shut down the AWE
environment.
Note: To be able to use the Windows WinMain() function, use the OS/2 Warp
main() function located in the MAIN.C file. MAIN.C gets compiled and
linked with the module containing WinMain() and creates an OS/2 Warp
executable file. If you do not use the OS/2 Warp main() function, you
will receive a link error stating that there is no starting address for
your program.
ΓòÉΓòÉΓòÉ 7.3.7. OpenGL Sample Programs ΓòÉΓòÉΓòÉ
The OpenGL sample programs are categorized as follows.
Note that installation of OpenGL is required for execution of the OpenGL
samples.
AUXDEMO - Auxiliary Library samples
GLUTDEMO - Graphics Library Utility Toolkit samples
ΓòÉΓòÉΓòÉ 7.3.7.1. AUXDEMO Sample Programs ΓòÉΓòÉΓòÉ
The following Auxiliary Library samples are provided in the OS/2 Warp Toolkit:
ACCANTI
This program shows accumulation of jittered objects with an orthographic
projection in order to antialias a scene.
ACCNOT
This program is basically the same as ACCANTI, but without the jittering
to show the same scene aliased.
ACCPERSP
This program shows the same scene as the prior ACCANTI and ACCNOT, but
with a perspective projection and accumulation of jittered images to
antialias the scene.
ACCUM
This program is another example of accumulating multiple images in order
to antialias a scene.
AIM
This program calculates the fovy (field of view angle in the Y
direction), by using trigonometry, given the size of an object and its
size.
ALPHA
This program draws several overlapping filled polygons to demonstrate the
effect order has on alpha blending results.
ALPHA3D
This program demonstrates how to intermix opaque and alpha blended
polygons in the same scene, by using glDepthMask(). By pressing the left
mouse button, you can toggle the eye position.
ANTI
This program draws antialiased lines in RGBA mode.
ANTIINDX
This program draws a wireframe icosahedron with antialiased lines, in
color index mode.
ANTIPIDX
This program draws antialiased points, in color index mode.
ANTIPOLY
This program draws filled polygons with antialiased edges. The special
GL_SRC_ALPHA_SATURATE blending function is used. By pressing the left
mouse button, you can turn the antialiasing on and off.
ANTIPT
This program draws antialiased points, in RGBA mode.
BEZCURVE
This program uses evaluators to draw a Bezier curve.
BEZSURF
This program renders a lighted, filled Bezier surface, using
two-dimensional evaluators.
BEZMESH
This program renders a wireframe Bezier surface, using two-dimensional
evaluators.
CHECKER
This program texture maps a checkerboard image onto two rectangles. This
program clamps the texture, if the texture coordinates fall outside 0.0
and 1.0.
CHECKER2
This program texture maps a checkerboard image onto two rectangles. This
program repeats the texture, if the texture coordinates fall outside 0.0
and 1.0.
CHESS
This program texture maps a checkerboard image onto two rectangles. The
texture coordinates for the rectangles are 0.0 to 3.0.
CLIP
This program demonstrates arbitrary clipping planes.
COLORMAT
This program will be in ColorMaterial mode after initialization. By
pressing the mouse buttons, you can change the color of the diffuse
reflection.
CONE
This program demonstrates the use of the GL lighting model. A sphere is
drawn using a grey material characteristic. A single light source
illuminates the object.
CUBE
This program draws a 3-D cube, viewed with perspective, stretched along
the Y-axis.
CURVE
This program uses the Utility Library NURBS routines to draw a
one-dimensional NURBS curve.
DEPTHCUE
This program draws a wireframe model, which uses intensity (brightness)
to give clues to distance. Fog is used to achieve this effect.
DISK
This program demonstrates the use of the quadrics Utility Library
routines to draw circles and arcs.
DOF
This program demonstrates use of the accumulation buffer to create an
out-of-focus depth-of-field effect. The teapots are drawn several times
into the accumulation buffer. The viewing volume is jittered, except at
the focal point, where the viewing volume is at the same position, each
time. In this case, the gold teapot remains in focus.
DOFNOT
This program demonstrates the same scene as DOF.C, but without use of the
accumulation buffer, so that everything is in focus.
DOUBLE
This program demonstrates double buffering for flicker-free animation.
The left and middle mouse buttons start and stop the spinning motion of
the square.
DRAWF
This program draws the bitmapped letter F on the screen several times.
This demonstrates use of the glBitmap() function.
FEEDBACK
This program demonstrates use of OpenGL feedback. First, a lighting
environment is set up and a few lines are drawn. Then feedback mode is
entered and the same lines are drawn. The results in the feedback buffer
are printed.
FOG
This program draws five red teapots, each at a different Z-distance from
the eye, in different types of fog. By pressing the left mouse button,
you can choose between three types of fog: exponential, exponential
squared, and linear. In this program, there is a fixed density value, as
well as fixed start and end values for the linear fog.
FOGINDEX
This program demonstrates fog in color index mode. Three cones are drawn
at different Z-values in a linear fog. Thirty-two contiguous colors
(from 16 to 47) are loaded with a color ramp.
FONT
This program draws some text in a bitmapped font using glBitmap() and
other pixel routines. FONT also demonstrates use of display lists.
LIGHT
This program demonstrates the use of the OpenGL lighting model. A sphere
is drawn using a grey material characteristic. A single light source
illuminates the object.
LINELIST
This program demonstrates the use of display lists to call different line
stipples.
LINES
This program demonstrates different line stipples and widths.
LIST
This program demonstrates how to make and execute a display list. Note
that attributes, such as current color and matrix, are changed.
LIST2
This program demonstrates the use of glGenList() and glPushAttrib(). The
matrix and color are restored before the line is drawn.
MAPLIGHT
This program demonstrates the use of the GL lighting model. A sphere is
drawn using a magenta diffuse reflective and white specular material
property. A single light source illuminates the object. This program
illustrates lighting in color-map mode.
MATERIAL
This program demonstrates the use of the GL lighting model. Several
objects are drawn using different material characteristics. A single
light source illuminates the objects.
MIPMAP
This program demonstrates using mipmaps for texture maps. To overtly show
the effect of mipmaps, each mipmap reduction level has a solid colored,
contrasting texture image. Thus, the quadrilateral is drawn with several
different colors.
MODEL
This program demonstrates the use of OpenGL modeling transformations.
Four triangles are drawn, each with a different transformation.
MVLIGHT
This program demonstrates when to issue lighting and transformation
commands to render a model with a light, which is moved by a modeling
transformation (rotate or translate). The light position is reset after
the modeling transformation is called. The eye position does not change.
A sphere is drawn using a grey material characteristic. A single light
source illuminates the object.
By pressing the left or middle mouse button, you can alter the modeling
transformation (X-rotation) by 30 degrees. The scene is then redrawn with
the light in a new position.
NURBS
This program shows a NURBS (Non-uniform rational B-splines) surface,
shaped like a heart.
PICKDPTH
This program demonstrates picking. In rendering mode, three overlapping
rectangles are drawn. When you press the left mouse button, you enter
selection mode with the picking matrix. Rectangles that are drawn under
the cursor position are " picked." Note the depth value range that is
returned.
PICKLINE
This program demonstrates picking. Press the left mouse button to enter
picking mode. You get two hits if you press the mouse, while the cursor
is where the lines intersect.
PICKSQR
This program demonstrates using multiple names and picking. A 3x3 grid of
squares is drawn. When you press the left mouse button, all squares
under the cursor position change color.
PLANE
This program demonstrates the use of local versus infinite lighting on a
flat plane.
PLANET
This program shows how to composite modeling transformations to draw
translated and rotated models.
By pressing the Left, Right, Up, or Down Arrow key, you can alter the
rotation of the planet around the sun.
PLANETUP
In this program, the planets (from PLANET.C) have been rotated so their
polar regions are north/south.
By pressing the Left, Right, Up, or Down Arrow key, you can alter the
rotation of the planet around the sun.
POLYS
This program demonstrates polygon stippling.
ROBOT
This program shows how to composite modeling transformations to draw
translated and rotated hierarchical models.
By pressing any of the arrow keys, you can alter the rotation of the
robot arm.
SCENE
This program demonstrates the use of the GL lighting model. Objects are
drawn using a grey material characteristic. A single light source
illuminates the objects.
SCNBAMB
This program demonstrates use of a blue ambient light source.
SCNFLAT
This program draws lighted objects with flat shading.
SCNLIGHT
This program demonstrates the use of a colored (magenta, in this example)
light source. Objects are drawn using a grey material characteristic. A
single light source illuminates the objects.
SELECT
This program is an illustration of the selection mode and name stack,
which detect whether objects collide with a viewing volume. First, four
triangles and a rectangular box representing a viewing volume are drawn
(drawScene routine). The green triangle and yellow triangles appear to
lie within the viewing volume, but the red triangle appears to lie
outside it. Then, the selection mode is entered (selectObjects routine).
Drawing to the screen ceases. To see if any collisions occur, the four
triangles are called. In this example, the green triangle causes one hit
with the name 1 and the yellow triangles cause one hit with the name 3.
SIMPLE
This program draws a white rectangle on a black background.
SMOOTH
This program demonstrates smooth shading. A smooth shaded polygon is
drawn in a 2-D projection.
SPHERE
This program draws a wire frame sphere. It uses glTranslatef() as a
viewing transformation.
STENCIL
This program draws two rotated tori in a window. A diamond in the center
of the window masks out part of the scene. Within this mask, a different
model (a sphere) is drawn in a different color.
STROKE
This program demonstrates some characters of a stroke (vector) font. The
characters are represented by display lists, which are given numbers
which correspond to the ASCII values of the characters. Use of
glCallLists() is demonstrated.
SURFACE
This program draws a NURBS surface in the shape of a symmetrical hill.
TEA
This program demonstrates two-sided lighting and compares it with
one-sided lighting. Three teapots are drawn, with a clipping plane to
expose the interior of the objects.
TEAAMB
This program renders three lighted, shaded teapots, with different
ambient values.
TEAPOTS
This program demonstrates several material properties. A single light
source illuminates the objects.
TEXGEN
This program draws a texture mapped teapot with automatically generated
texture coordinates. The texture is rendered as stripes on the teapot.
TEXSURF
This program uses evaluators to generate a curved surface and
automatically generated texture coordinates.
TRIM
This program draws a NURBS surface in the shape of a symmetrical hill,
using both a NURBS curve and pwl (piecewise linear) curve to trim part of
the surface.
ΓòÉΓòÉΓòÉ 7.3.7.2. GLUTDEMO Sample Programs ΓòÉΓòÉΓòÉ
The following Graphics Library Utility Toolkit (GLUT) samples are provided in
the OS/2 Warp Toolkit:
ATLANTIS
ATLANTIS displays sea-life (whales, sharks, and dolphins) using OpenGL
for rendering and the Graphics Library Utility Toolkit for window and
user interaction control.
TEST7
TEST7 demonstrates window manipulation using the Graphics Library Utility
Toolkit.
ΓòÉΓòÉΓòÉ 7.3.8. OS/2 Sample Programs ΓòÉΓòÉΓòÉ
The OS/2 sample programs are as follows:
CLOCK - Timer Services Sample
DLLAPI - Dynamic Link Library Sample
EAS - Extended Attributes Editor
HANOI - Multithreaded Sample (Towers of Hanoi)
NPIPE - Named Pipe Sample
QUEUES - Interprocess Communication Queue Sample
SEMAPH - Semaphore Sample
SORT - Mulithreaded Sample (Sorting Algorithm)
TIMER0 - High Resolution Timer Sample
VMM - Virtual Memory Management Sample
WORMS - Console I/O Sample
ΓòÉΓòÉΓòÉ 7.3.8.1. CLOCK Sample Program ΓòÉΓòÉΓòÉ
CLOCK (located in \TOOLKIT\SAMPLES\OS2\TIMESERV) demonstrates how to use and
implement window timers and system-resource timers. This sample program
displays both an analog and digital clock. To simulate elapsed seconds, the
main PM thread repeatedly sets a one-second window timer that updates the
current time.
CLOCK features an audible and visual alarm that you can set. When the time
expires, the sample makes use of the DOS timer services and notifies the user
by sounding an alarm and displaying a message box.
ΓòÉΓòÉΓòÉ 7.3.8.2. DLLAPI Sample Program ΓòÉΓòÉΓòÉ
DLLAPI (located in \TOOLKIT\SAMPLES\OS2\DLLAPI) demonstrates how to write and
use a dynamic link library (DLL). The sample has a .DLL file and an executable
(.EXE) file. The .DLL provides the 32-bit API function that is called by the
.EXE file.
The .DLL uses protected memory on its shared data, and exception management to
validate the pointer parameters for a 32-bit API function. The .EXE file
demonstrates how to handle a divide-by-zero exception, and calls the function
with invalid pointer parameters, followed by a call with valid pointer
parameters.
ΓòÉΓòÉΓòÉ 7.3.8.3. EAS Sample Program ΓòÉΓòÉΓòÉ
EAS (located in \TOOLKIT\SAMPLES\OS2\EAEDIT) demonstrates a multithreaded
application that retrieves, modifies, or sorts files by their extended
attribute value. Included in this sample program are PM procedures for dialog
boxes and a standard client window. The sample lets you select an extended
attribute file name from a list, or enter a new name in an entry field. You can
select the extended attribute type from a table.
ΓòÉΓòÉΓòÉ 7.3.8.4. HANOI Sample Program ΓòÉΓòÉΓòÉ
HANOI (located in \TOOLKIT\SAMPLES\OS2\HANOI) demonstrates a multithreaded
application with the familiar "towers of Hanoi" puzzle. When the sample program
is started, you see three poles (A, B, and C). Initially, pole A has on it a
stack of disks starting with the largest disks on the bottom and succeeding
smaller disks on the top. The main thread handles the PM interface and lets the
you start or stop the Hanoi routine. It also lets you reset the number of
working disks. The second thread is created when the Start item is selected
from the Options menu. This thread starts the recursive execution of the Hanoi
algorithm, runs in the background, and moves and paints the disks. All disks
end up on pole C.
ΓòÉΓòÉΓòÉ 7.3.8.5. NPIPE Sample Program ΓòÉΓòÉΓòÉ
NPIPE (located in \TOOLKIT\SAMPLES\OS2\NPIPE) demonstrates two-way
communication between two unrelated processes using named pipe functions. This
sample program implements the game of TicTacToe with two executable files:
CLINPIPE.EXE (the client)
The client is the user. For example, the client will:
- Connect to the server and acknowledge successful connection
(START_MSG).
- Notify the server through a pipe when it wishes to begin play
(YOU_FIRST or CLIENT_MOVE).
- Notify the server when it wishes to quit (CLIENT_QUIT).
- Send the server a valid move when requested by the server
(CLIENT_MOVE).
SVRNPIPE.EXE (the server)
The server is the computer. For example, the server will:
- Connect a pipe to the client through which play will be executed
(START_MSG) upon the initial request of a client to play.
- Play with many clients simultaneously.
- Notify the client of the server's move, and request a valid move
from the client (SERVER_MOVE).
- Notify the client of game-end (WIN_SERVER, WIN_CLIENT, WIN_DRAW).
ΓòÉΓòÉΓòÉ 7.3.8.6. QUEUES Sample Program ΓòÉΓòÉΓòÉ
QUEUES (located in \TOOLKIT\SAMPLES\OS2\QUEUES) demonstrates interprocess
communications (IPC) using the 32-bit queue component. It consists of two
executable programs:
SVRQUEUE.EXE
Creates an IPC queue; a named, shared-memory buffer for queue elements;
and a shared, named, mutex (mutual exclusive) semaphore. After
initializing the queue, SVRQUEUE starts a thread to read from the queue,
prints the contents of the messages read from the queue, and terminates
at the user's request.
CLIQUEUE.EXE
Opens the queue and accesses the shared-memory element buffer and mutex
semaphore, and starts a thread to write to the queue. CLIQUEUE requests a
string of data from the user, allocates a shared-memory element from the
buffer, puts the string in the shared-memory element, and then uses an
event semaphore to direct the thread to write the element to the queue.
CLIQUEUE terminates at the user's request.
ΓòÉΓòÉΓòÉ 7.3.8.7. SEMAPH Sample Program ΓòÉΓòÉΓòÉ
SEMAPH (located in \TOOLKIT\SAMPLES\OS2\SEMAPH) demonstrates the use of mutex
and event semaphores. In the sample, several threads share access to the same
resource.
A mutex semaphore is used to guarantee that only one thread has access to the
resource at a time. A mutex semaphore is used to check for a stop event or for
a user signal to give up the resource.
An event semaphore is used to signal the thread to give up the resource. An
event semaphore can be posted by the user, or run in auto mode, in which case
the event semaphore will be posted at fixed time intervals.
Each thread can be displayed as a square of a unique color. Similarly, the
resource can be displayed as a rectangle; its color is that of the first thread
that owns it.
ΓòÉΓòÉΓòÉ 7.3.8.8. SORT Sample Program ΓòÉΓòÉΓòÉ
SORT (located in \TOOLKIT\SAMPLES\OS2\SORT) demonstrates the use of multiple
threads by performing multiple sorts at the same time. Each sorting algorithm
runs from a separate thread. The main thread is used to handle the main
window's messages, while the routine that updates the display is run from
another thread.
ΓòÉΓòÉΓòÉ 7.3.8.9. TIMER0 Sample Program ΓòÉΓòÉΓòÉ
TIMER0 (located in \TOOLKIT\SAMPLES\OS2\TIMER0) creates four threads. Each
thread does the following:
1. Sets its priority to time-critical.
2. Sleeps for n milliseconds, where n is equal to 500 times the number of
the thread (for example, thread #1 sleeps 500ms, thread #2 sleeps 1000ms,
and so on).
3. Wakes up and increments a counter.
To start the TIMER0 sample from an OS/2 command line, type:
TIMER0
While the four threads are running, the main thread (the one that created the
other four) is in an infinite loop.
Note: To break out of the loop, press any key.
This loop displays the values of each of the four counters incremented by the
four threads. For example:
TIMER0$ opened. File Handle is 3
Counter: 00008703 1:00000017 2:00000008 3:00000005 4:00000004
The counter is the value of the millisecond counter in timer TIMER0 device
driver. This value gets incremented every millisecond and is very accurate.
The other four values are the four counters and these values are incremented
by each thread. The accuracy is dependent on the thread contention and other
things that are going on in the system. Note that #2 is approximately
one-half of #1, #3 is approximately one-third of #1, and #4 is approximately
one-fourth of #1.
ΓòÉΓòÉΓòÉ 7.3.8.10. VMM Sample Program ΓòÉΓòÉΓòÉ
VMM (located in \TOOLKIT\SAMPLES\OS2\VMM) demonstrates the use of virtual
memory by using new memory-management functions to allocate and set the
attributes of memory. Users can read or write data into memory and reset the
attributes using a dialog box. The memory manager protects or opens the virtual
memory to read or write operations according to the different attributes of
each memory block. To free memory, the user enters the address of the memory.
ΓòÉΓòÉΓòÉ 7.3.8.11. WORMS Sample Program ΓòÉΓòÉΓòÉ
WORMS (located in \TOOLKIT\SAMPLES\OS2\CONSOLIO) demonstrates how to call video
(Vio), keyboard (Kbd), and mouse (Mou) 16-bit function from a 32-bit code
segment. This sample program displays earthworms aimlessly moving about the
screen. Each worm is a separate thread with a unique color combination and
movement pattern. When one worm encounters another worm, the color attribute of
the worm is set to red. You can add or delete worms using the keyboard or
mouse.
ΓòÉΓòÉΓòÉ 7.3.9. Presentation Manager Sample Programs ΓòÉΓòÉΓòÉ
The PM sample programs are as follows:
CLIPBRD - Clipboard Sample
DIALOG - Introductory Dialog Box Sample
DRAGDROP - Direct Manipulation (Dragdrop) Sample
GRAPHIC - Non-retained Graphics Sample
HELLO - Standard Windows Sample
IMAGE32 - PM 16-bit to 32-bit Porting Sample
IPF - Information Presentation Facility Sample
JIGSAW - Bitmap Manipulation Sample
PALETTE - Palette Sample
PRINT - Printer Sample Program
STYLE - PM Controls Sample
TEMPLATE - Application Template
ΓòÉΓòÉΓòÉ 7.3.9.1. CLIPBRD Sample Program ΓòÉΓòÉΓòÉ
CLIPBRD (located in \TOOLKIT\SAMPLES\PM\CLIPBRD) demonstrates how to provide a
PM interface to the clipboard. Initially, this sample program displays a
standard window with a bitmap. You can cut and paste rectangular images in this
window, using the system clipboard as an intermediate storage area.
ΓòÉΓòÉΓòÉ 7.3.9.2. DIALOG Sample Program ΓòÉΓòÉΓòÉ
DIALOG (located in \TOOLKIT\SAMPLES\PM\DIALOG) demonstrates how to associate a
dialog box with a standard window. The dialog box is defined as a dialog
template in a resource file.
This sample program also demonstrates how to implement entry fields, push
buttons, and message boxes. Message boxes are displayed only for error
conditions.
ΓòÉΓòÉΓòÉ 7.3.9.3. DRAGDROP Sample Program ΓòÉΓòÉΓòÉ
DRAGDROP (located in \TOOLKIT\SAMPLES\PM\DRAGDROP) demonstrates how to move
files between directories by using the drag and drop operation of direct
manipulation. This sample program creates a drop-down list box that contains a
scrollable file name list of the current directory.
To change the current directory, select the Window option, type in the
directory name, and press Enter. To change the current directory to one higher
in the directory tree, select File from the menu bar, and then Open. The Select
subdirectory window is displayed. Type in the name of the subdirectory, and
then select OK.
DRAGDROP must be started twice, so that there are two running instances of the
sample. Then, using a mouse, you can:
Display a directory file list in the first sample.
Select a file name from the second sample.
Drag the file name (using the right mouse button) to the directory in the
first sample.
Drop the file name into the directory in the first sample.
The file is now moved to the chosen directory of the first sample.
ΓòÉΓòÉΓòÉ 7.3.9.4. GRAPHIC Sample Program ΓòÉΓòÉΓòÉ
GRAPHIC (located in \TOOLKIT\SAMPLES\PM\GRAPHICS) demonstrates how to use
default viewing transformation functions of the PM. It also demonstrates how to
use an asynchronous drawing thread. This sample program lets you load metafiles
using a dialog box. The dialog box contains a Help push button. When the Help
push button is activated, it provides instructions on loading a metafile from
another directory. You also can print a metafile or graphic circle.
ΓòÉΓòÉΓòÉ 7.3.9.5. HELLO Sample Program ΓòÉΓòÉΓòÉ
HELLO (located in \TOOLKIT\SAMPLES\PM\STDWND) demonstrates how to create and
display a standard window that conforms to the Common User Access requirements.
This sample program also demonstrates how to use resources defined in a script
file. Initially, HELLO displays a standard window with the text "Hello." The
Options conditional-cascaded menu contains three items. Each item paints a
different text string in the window.
This sample also shows how to override the Ctrl+C key combination.
ΓòÉΓòÉΓòÉ 7.3.9.6. IMAGE32 Sample Program ΓòÉΓòÉΓòÉ
IMAGE32 (located in \TOOLKIT\SAMPLES\PM\PORTING) demonstrates how to migrate an
existing OS/2 16-bit application to a 32-bit application.
This sample also demonstrates how to display an image using the GpiImage
function. The image data comes from a file that you must select using the
standard File Open menu item.
ΓòÉΓòÉΓòÉ 7.3.9.7. IPF Sample Program ΓòÉΓòÉΓòÉ
IPF (located in \TOOLKIT\SAMPLES\PM\IPF) demonstrates how to use the IPF to
create an online document. This sample program features customized windows that
display text, graphics, and animation.
Two files are associated with this sample:
IPF online document (INF)
The .INF file is the compiled IPF document. The source contains tagging
that defines different types of windows. Tags that control the format and
display of text also are included in this file.
OS/2 dynamic link library (DLL)
The .DLL file is the compiled OS/2 C language source for the code object
that is called when the .INF file is read at run time. A series of
bitmaps used for animation are included in the .DLL.
ΓòÉΓòÉΓòÉ 7.3.9.8. JIGSAW Sample Program ΓòÉΓòÉΓòÉ
JIGSAW (located in \TOOLKIT\SAMPLES\PM\BMPSAMP) demonstrates the use of bitmaps
in a graphics application. This sample provides a jigsaw puzzle based on the
decomposition of an arbitrary bitmap loaded from a file. You can jumble the
pieces, and then drag them with a mouse. The image can be made smaller, larger,
scrolled horizontally, or scrolled vertically.
This sample program also demonstrates how to call the Information Presentation
Facility help hook, to create an instance and associate the instance with the
active application window.
ΓòÉΓòÉΓòÉ 7.3.9.9. PALETTE Sample Program ΓòÉΓòÉΓòÉ
PALETTE (located in \TOOLKIT\SAMPLES\PM\PALETTE) demonstrates 32-bit graphics
functions including:
Creating a window using a custom palette and animation.
Using menus with switches, and modifying the menu text.
Using multiple threads and semaphores in the Presentation Manager
environment.
Displaying graphics on the screen using outline fonts and clip paths.
Online help.
When started, PALETTE displays a standard window with a large OS/2 logo in the
foreground. You have the ability to change the OS/2 logo to the IBM logo. If
you resize the window, the logo is scaled and redrawn to fit the new window
size. You can also control the animation speed from the PALETTE menu.
The animation is performed by:
Creating a clip path that represents the outline of the logo characters
(which are displayed using an outline font).
Setting the clip path to the presentation space.
Drawing a series of lines to the presentation space.
Each line is drawn with an incremental color index. Palette animation is
performed using the 32-bit GpiAnimatePalette function.
In order for PALETTE to remain responsive to system and user messages, no
animation is performed on the main window procedure thread. A second thread is
created from which all animation is performed.
Hardware requirements:
XGA adapter
1MG of RAM
32-bit graphics engine
ΓòÉΓòÉΓòÉ 7.3.9.10. PRINT Sample Program ΓòÉΓòÉΓòÉ
PRINT (located in \TOOLKIT\SAMPLES\PM\PRINT) demonstrates how to display and
print text, metafiles, and bitmaps. It also demonstrates how to:
Query and display system printer configurations
Interact with printer drivers to change job properties
Query and display available printer and screen fonts
Query and display printer forms and setup margins
Selectively print part or all of a document on an asynchronous thread.
ΓòÉΓòÉΓòÉ 7.3.9.11. STYLE Sample Program ΓòÉΓòÉΓòÉ
STYLE (located in \TOOLKIT\SAMPLES\PM\CONTROLS) demonstrates a PM application
that conforms with the Common User Access requirements and implements the
following controls:
Container
Notebook
Slider
Spin button
Value set
This sample program also demonstrates secondary windows, such as dialogs and
message boxes. The program lets you edit and save text files. The source for
online help, in IPF format, is also provided.
STYLE also demonstrates the detection of a font that does not conform to the
International Standards Organization (ISO 9241). When you are running the
sample on an ISO-compliant monitor and select a non-compliant font in the
standard font dialog, a message box is displayed.
The code in STYLE is structured so that the addition of a new function is
handled in an efficient manner. For example, to add a new command to an
existing menu, you need only add the command to the resource file, and then
add the appropriate message-processing routines to the STY_USER.C file.
ΓòÉΓòÉΓòÉ 7.3.9.12. TEMPLATE Sample Program ΓòÉΓòÉΓòÉ
TEMPLATE (located in \TOOLKIT\SAMPLES\PM\TEMPLATE) demonstrates the structure
common to all PM applications. This sample program shows how to structure an
application that has more than one source file. It includes the initialization
file (which is used and then discarded), the resident code, and the
non-resident code that is loaded only when needed.
TEMPLATE also demonstrates how to:
Create a standard window
Load resources from a resource file
Create a dialog box and a button control
Display a message box
Open a file
Close a file
Print text
Paint a window
Process a message from a menu
Run a thread in the background
Exit a process.
Several online help files are also provided in IPF format.
ΓòÉΓòÉΓòÉ 7.3.10. Problem Determination Sample Programs ΓòÉΓòÉΓòÉ
The Problem Determination sample programs are categorized as follows:
DMI - Desktop Management Interface Samples
ERRLOG - Logging Framework Samples
FFST - First Failure Support Technology Sample
TRACE - Trace Sample
ΓòÉΓòÉΓòÉ 7.3.10.1. DMI ΓòÉΓòÉΓòÉ
The following desktop management interface (DMI) samples are included with the
OS/2 Warp Toolkit. They are used in conjunction with the DMI MIF Browser, which
is provided with the OS/2 Warp Version 4 or later operating system.
DMI Overlay (DLL) Componentry Sample
DMI Direct Interface Componentry Sample
ΓòÉΓòÉΓòÉ 7.3.10.1.1. DMI Overlay (DLL) Componentry Sample ΓòÉΓòÉΓòÉ
The DMI Overlay Componentry sample (NAMES.C) is located in the
\TOOLKIT\SAMPLES\SYSMGT\DMI\NAMES subdirectory. To use NAMES, do the following:
1. Install the NAMES.MIF file into the DMI database.
a. Open the Problem Determination Tools folder (located in the OS/2
System folder).
b. Start the DMI MIF Browser.
c. Select Install new from the Components menu.
d. Select NAMES.MIF.
e. Do not close the DMI MIF Browser.
2. Copy the NAMES.DLL to a directory in the LIBPATH.
3. A component called DMI Service Layers will be created in the DMI MIF
browser. Expand the component and double-click on one of the groups to
see information about the operating system, company name, and the name of
the DMI service layer. This information is coming from the NAMES.DLL
file.
ΓòÉΓòÉΓòÉ 7.3.10.1.2. DMI Direct Interface Componentry Sample ΓòÉΓòÉΓòÉ
The DMI Direct Interface Componentry sample (NAMEDIR.C) is located in the
\TOOLKIT\SAMPLES\SYSMGT\DMI\NAMEDIR subdirectory.
To use NAMEDIR, do the following:
1. Copy the NAMEDIR.MIF file to the \DMIPATH directory.
2. Open the Problem Determination Tools folder (located in the OS/2 System
folder).
3. Start the DMI MIF Browser.
4. From an OS/2 session, run the NAMEDIR.EXE program. The following two
things will happen:
A new component will be added to the DMI database and will be
displayed in the DMI MIF Browser. The name of the component will be
DMI Service Layers - Direct Interface (DI) version.
The OS/2 session will display the following messages:
Preparing to install 'NAMEDIR.MIF'
Installation successful ComponentID=6.
Preparing to register component id 6
I got started
5. Expand the new component and double-click on one of the groups to see
information about the operating system, company name, and the name of the
DMI service layer. This information is coming from the NAMEDIR.EXE file.
ΓòÉΓòÉΓòÉ 7.3.10.2. ERRLOG ΓòÉΓòÉΓòÉ
The following samples demonstrate use of the logging functions.
ERRLOG1
ERRLOG2
It is helpful to run these sample files using a debugger so that you can step
through the code to see the function the API is actually providing.
ΓòÉΓòÉΓòÉ 7.3.10.2.1. ERRLOG1 ΓòÉΓòÉΓòÉ
ERRLOG1 (located in \TOOLKIT\SAMPLES\SYSMGT\ERRLOG\ERRLOG1) demonstrates how to
use the following functions to open a file, read an entry from the log, format
that entry, and then close the log.
LogOpenFile
LogReadEntry
LogFormatEntry
LogCloseFile
The program displays a message indicating whether each function call was
successful or not.
If the error log is empty, the program will end after the LogReadEntry
function call with a return code of 1750 indicating the end of the file was
reached without finding the desired record. To have the program run
successfully, run the FFSTProbe sample program (PROBE.EXE) to put an entry in
the log. PROBE.EXE is located in the \TOOLKIT\SAMPLES\SYSMGT\FFST\PROBE
subdirectory.
ΓòÉΓòÉΓòÉ 7.3.10.2.2. ERRLOG2 ΓòÉΓòÉΓòÉ
ERRLOG2 (located in \TOOLKIT\SAMPLES\SYSMGT\ERRLOG\ERRLOG2) demonstrates how to
use the following functions to open event notification, wait on an error log
event, change an event filter, and then close event notification.
LogOpenEventNotification
LogWaitEvent
LogChangeEventFilter
LogCloseEventNotification
The program displays a message after each error logging function call
indicating whether the call was successful or not. Because this program is
using the event notification functions, it will pause twice as it's waiting
for an error to be logged. At this time it will display a message indicating
that it is waiting for an event.
When event notification is started a filter is not specified. Therefore, on
the first use of LogWaitEvent, any record placed in the log will cause the
notification to occur. The LogChangeEventFilter function is then used to
filter on records where the vendor tag field contains IBM or the severity of
the error is less than, or equal, to 2. In either case, the FFSTProbe sample
program (PROBE.EXE) will cause the notification to occur.
To run ERRLOG2, do the following:
1. At an OS/2 command line, type:
ERRLOG2
It will run to the point where it displays a message stating that it is
waiting for an event.
2. Open another OS/2 window and start the FFSTProbe sample program by
changing to the \TOOLKIT\SAMPLES\SYSMGT\FFST\PROBE subdirectory and
typing:
PROBE
The ERRLOG2 program will display messages stating that it has received an
event, that it's changing the event filter, and that it is waiting for an
event.
3. Open another OS/2 window and start the FFSTProbe sample program again.
The ERRLOG2 program will again display a message stating that it has
received an event, followed by a message stating that it is closing event
notification.
ΓòÉΓòÉΓòÉ 7.3.10.3. FFST ΓòÉΓòÉΓòÉ
PROBE (located in \TOOLKIT\SAMPLES\SYSMGT\FFST\PROBE) shows how to use the
FFSTProbe function. You should use the FFSTProbe function with a "wrapper"
function. An example of a wrapper function is included in this sample code. You
can add or delete parameters sent to the wrapper function based on your own
needs.
To run the PROBE sample, do the following:
1. Copy PROBE.MSG and PROBE.REP into the \OS2\SYSTEM directory. PROBEMSG.TXT
and PROBEREP.TXT are the source files used to create the message and
template repository files.
2. Install the MIF file into the DMI database.
a. Open the Problem Determination Tools folder (located in the OS/2
System folder).
b. Start the DMI MIF Browser.
c. Select Install new from the Components menu.
d. Select PROBE.MIF.
e. Do not close the DMI MIF Browser.
3. At an OS/2 command line type:
PROBE
After the PROBE sample runs, use the System Error Logger (in the Problem
Determination Tools folder) to view the two probe entries, 1111 and 2222.
Double-click on the entries to view detailed information.
ΓòÉΓòÉΓòÉ 7.3.10.4. TRACE ΓòÉΓòÉΓòÉ
TRACEEXP (located in \TOOLKIT\SAMPLES\SYSMGT\TRACE) shows how to create a trace
event in the system-event trace buffer. The Trace Create Entry Request packet
is initialized with the major code, minor code, length of data to be collected
(if any), and starting address of the data (or NULL). The size of the packet
and the trace release number must also be supplied.
The call to TraceCreateEntry() will place this data into the system-event trace
buffer if the major and minor codes were turned on by the user. If trace is not
enabled, or if the major and minor code combination is not turned on, the call
to TraceCreateEntry() performs no action.
Use the Trace Formatter, provided with the OS/2 Warp Version 4 or later
operating system, to look at the system-event trace buffer.
For more information on using this sample, see Starting TRACEEXP.
ΓòÉΓòÉΓòÉ 7.3.10.4.1. Starting TRACEEXP ΓòÉΓòÉΓòÉ
To run the TRACEEXP sample, you need one or both of the following lines in your
CONFIG.SYS:
trace=on
tracebuf=4
Be sure to restart your system if you make changes to CONFIG.SYS.
Turn on trace for the major code in this example by typing the following:
trace on 123
To run the sample, type:
traceexp
To turn the trace off, type:
trace off
To see the captured trace point, type:
tracefmt
This should show an entry with major code 123.
ΓòÉΓòÉΓòÉ 7.3.11. REXX Sample Programs ΓòÉΓòÉΓòÉ
The REXX sample programs are as follows:
CALLREXX
DEVINFO
PMREXX
REXXCALC
REXXUTIL
RXMACDLL
REXX Animal SOM Class Sample
REXX Workplace Shell Class Sample
REXX Workplace Shell Folder Sample
REXX Complex Number Sample
REXX Concurrency Sample
REXX Directives Sample
REXX Display Month Array Sample
REXX Factorial Sample
REXX Guard and Reply Sample
REXX Pipe Sample
REXX Query Date Sample
REXX Query Time Sample
REXX Semaphore Class Sample
REXX Stack Sample
REXX Start and Guard Sample
ΓòÉΓòÉΓòÉ 7.3.11.1. CALLREXX Sample Program ΓòÉΓòÉΓòÉ
CALLREXX demonstrates how a C-language application calls a REXX application. To
run the REXX application BACKWARD.FNC, CALLREXX.C issues RexxStart. RexxStart
calls the REXX interpreter and passes it a parameter string. BACKWARD.FNC
returns a result string to the C-language application.
ΓòÉΓòÉΓòÉ 7.3.11.2. DEVINFO Sample Program ΓòÉΓòÉΓòÉ
DEVINFO issues DosDevConfig and returns the data in a collection of compound
variables when all available items are requested or a single variable when only
one item is requested. This is a REXX subcommand handler and variable pool
example. This sample can be run in an OS/2 full-screen session, an OS/2
text-window session, or in PMREXX.
ΓòÉΓòÉΓòÉ 7.3.11.3. PMREXX Sample Program ΓòÉΓòÉΓòÉ
PMREXX provides a PM window in which you can display the output from a REXX
procedure or from any programs called by the REXX procedure. The window has an
entry field into which you can type.
ΓòÉΓòÉΓòÉ 7.3.11.4. REXXCALC Sample Program ΓòÉΓòÉΓòÉ
REXXCALC illustrates the steps required to develop enhanced applications.
ΓòÉΓòÉΓòÉ 7.3.11.5. REXXUTIL Sample Program ΓòÉΓòÉΓòÉ
REXXUTIL demonstrates a set of external functions packaged in a dynamic link
library, including:
Use of OS/2 system functions in REXX external functions
Techniques for passing large amounts of data to a REXX program using REXX
compound variables as arrays.
REXXUTIL runs on 32-bit OS/2. It can be run in an OS/2 full-screen session, an
OS/2 window session, or in PMREXX.
ΓòÉΓòÉΓòÉ 7.3.11.6. RXMACDLL Sample Program ΓòÉΓòÉΓòÉ
RXMACDLL demonstrates the macrospace interface with the two following
C-language programs and that are compiled into two separate dynamic link
libraries (DLLs):
MACRO.C
Contains REXX external functions, which perform REXX macrospace
operations.
RXNLSINF.C
Contains a REXX external function that provides information related to
national language support (for example, as a currency symbol and
separator).
RXMACDLL.CMD uses MACRO.DLL to load NLSMONEY.CMD into the macrospace and calls
NLSMONEY.CMD several times to format currency amounts. NLSMONEY.CMD formats
the amounts according to the specifications provided by RXNLSINF.DLL.
RXMACDLL can be run in an OS/2 full-screen session, an OS/2 window session, or
in PMREXX.
ΓòÉΓòÉΓòÉ 7.3.11.7. REXX Animal SOM Class Sample ΓòÉΓòÉΓòÉ
The sample code in the \TOOLKIT\SAMPLES\REXX\SOM\ANIMAL directory illustrates
the use of a simple metaclass to provide customized constructors and to perform
basic instance tracking.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.8. REXX Workplace Shell Class Sample ΓòÉΓòÉΓòÉ
The WPSORXCL.CMD sample in the \TOOLKIT\SAMPLES\REXX\WPS directory demonstrates
how to use the OS/2 Workplace Shell folders to represent Object REXX classes.
This is presented in a tree view where an Object REXX class is a folder and
subclasses are subfolders. The top folder title is updated as classes are added
for a progress indicator. Methods in a class can be represented as abstract
WPS objects; but the default is not to create them because it is quite time
consuming.
For this sample to function properly, Object REXX must be installed.
The REXX Workplace Shell samples also require the REXX classes first be
registered with the Workplace Shell. To register REXX classes with the
Workplace Shell, type the following at an OS/2 command prompt:
WPSINST
The WPSINST.CMD program can be used at any time to query REXX classes and to
register and deregister them. To deregister the REXX classes, type the
following at an OS/2 command prompt:
WPSINST -
ΓòÉΓòÉΓòÉ 7.3.11.9. REXX Workplace Shell Folder Sample ΓòÉΓòÉΓòÉ
The WPSORXFL.CMD sample in the \TOOLKIT\SAMPLES\REXX\WPS directory demonstrates
useful routines for folders. The first routine will take a WPS folder as input
and return an array of SOM objects; one for each object in that folder. The
second routine will take an array of WPS objects and a string; returning an
array of objects that match the string. The sample also uses three methods to
iterate over arrays as iteration examples.
For this sample to function properly, Object REXX must be installed.
The REXX Workplace Shell samples also require the REXX classes first be
registered with the Workplace Shell. To register REXX classes with the
Workplace Shell, type the following at an OS/2 command prompt:
WPSINST
The WPSINST.CMD program can be used at any time to query REXX classes and to
register and deregister them. To deregister the REXX classes, type the
following at an OS/2 command prompt:
WPSINST -
ΓòÉΓòÉΓòÉ 7.3.11.10. REXX Complex Number Sample ΓòÉΓòÉΓòÉ
The COMPLEX.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how
to create a complex number class using the ::class and ::method directives.
Also shown is an example of subclassing the complex number class (the vector
subclass). Finally, the stringlike class demonstrates the use of a mixin to
provide some string behavior to the complex number class.
The USECOMP.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
use of the ::requires directive to use the complex number class defined in
COMPLEX.CMD.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.11. REXX Concurrency Sample ΓòÉΓòÉΓòÉ
The CCREPLY.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how
to use reply to run two methods at the same time.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.12. REXX Directives Sample ΓòÉΓòÉΓòÉ
The GUESS.CMD sample in the \TOOLKIT\SAMPLES\REXX directory creates a simple
node class and uses it to create a logic tree. The logic tree is filled in by
playing a simple guessing game.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.13. REXX Display Month Array Sample ΓòÉΓòÉΓòÉ
The MONTH.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
use of arrays to replace stems. This sample displays the days of the month.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.14. REXX Factorial Sample ΓòÉΓòÉΓòÉ
The FACTOR.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates a way
to define a factorial class using the subclass method and the .methods
environment symbol.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.15. REXX Guard and Reply Sample ΓòÉΓòÉΓòÉ
The GREPLY.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
difference between Guarded and UnGuarded methods. In the first example, the
method is guarded, so it does not begin execution until the final result is
tallied. In the second example, the method is unguarded so it can begin
execution while method sum_up is still looping. In fact, unguarded_get often
runs immediately after the Reply, so using a guard instruction ensures sum_up
runs for a bit before unguarded_get returns with the intermediate sum.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.16. REXX Pipe Sample ΓòÉΓòÉΓòÉ
The PIPE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the use
of the ::class and ::method directives to create a simple implementation of a
CMS-like pipeline function.
The USEPIPE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how
to use the pipes implemented in the PIPE.CMD sample.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.17. REXX Query Date Sample ΓòÉΓòÉΓòÉ
The QDATE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory displays the
current date and moon phase for that date in English.
ΓòÉΓòÉΓòÉ 7.3.11.18. REXX Query Time Sample ΓòÉΓòÉΓòÉ
The QTIME.CMD sample in the \TOOLKIT\SAMPLES\REXX directory displays the
current time in English.
ΓòÉΓòÉΓòÉ 7.3.11.19. REXX Semaphore Class Sample ΓòÉΓòÉΓòÉ
The SEMCLS.CMD sample in the \TOOLKIT\SAMPLES\REXX directory implements a
semaphore class in Object REXX. The class is defined to the Global OREXX
environment.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.20. REXX Stack Sample ΓòÉΓòÉΓòÉ
The STACK.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how to
implement a stack class using the ::class and
::method directives. This sample also includes a short example of the use of a
stack.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.11.21. REXX Start and Guard Sample ΓòÉΓòÉΓòÉ
The KTGUARD.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the
use of the start method and the guard instruction to control execution of
several programs. In this sample, the programs are controlled by one "guarded"
variable.
For this sample to function properly, Object REXX must be installed.
ΓòÉΓòÉΓòÉ 7.3.12. SOM Sample Programs ΓòÉΓòÉΓòÉ
Note: The ANIMALS and TP (text processing) sample programs are not included in
the OS/2 Warp Toolkit. Refer to the SOMobjects Developer Toolkit for
accessing them and obtaining information on them.
ΓòÉΓòÉΓòÉ 7.3.13. TCP/IP Sample Programs ΓòÉΓòÉΓòÉ
The TCP/IP sample programs are categorized as follows:
ACCXRECV (accept_and_recv function)
ECHOSAMP
HPS
OS2IOCTL
R0LIB32
RCOPY
RPC
RPCGEN
SAMPDLL
SENDFILE
SOCKET
SYSCTL
ΓòÉΓòÉΓòÉ 7.3.13.1. ACCXRECV Sample Program ΓòÉΓòÉΓòÉ
The accept_and_recv function call is explained in this sample program. The
server opens a socket to which it binds and then does a listen on that socket.
It starts the number of specified threads and does accept_and_recv on each of
them. The client opens a socket, connects to the server and sends the data. As
the timeout option is set (by using setsockeopt), whenever the client connects
but doesn't send any data, the server times out.
ΓòÉΓòÉΓòÉ 7.3.13.2. ECHOSAMP Sample Program ΓòÉΓòÉΓòÉ
This is a client/server application that is implemented using the Echo
protocol. Whatever the echo client sends to the server, the server sends it
back to the client.
ΓòÉΓòÉΓòÉ 7.3.13.3. HPS Sample Program ΓòÉΓòÉΓòÉ
This is a client/server application that is implemented for exploiting High
Performance Send. The server opens a socket to which the client connects and
passes data using HPS. The server responds to the client using HPS.
ΓòÉΓòÉΓòÉ 7.3.13.4. OS2IOCTL Sample Program ΓòÉΓòÉΓòÉ
This sample program issues SIOSTATRT for getting the routing entries from the
routing table, which is displayed on the screen, and issues SIOCSSYN to set the
SYN attack prevention frunction flag to on.
ΓòÉΓòÉΓòÉ 7.3.13.5. R0LIB32 Sample Program ΓòÉΓòÉΓòÉ
The client sends 1k of data (all 'a'). Then, the server modifies the data
(changes all 'a' to 'b') and sends the modified data to the client. The client
prints the data received from the server. The client sends a string to the
client using sendmsg() call, and the server receives it (by recvmsg() call) and
sends another string to the client. The client receives the string and prints
it. The client program is a ring3 program. The server program accesses the
socket calls through r0lib32.
ΓòÉΓòÉΓòÉ 7.3.13.6. RCOPY Sample Program ΓòÉΓòÉΓòÉ
RCOPY is located in \TOOLKIT\SAMPLES\TCPIPTK\RCOPY). It makes use of the FTP
API, FTPAPI.DLL, to transfer a directory and all of its subdirectories between
a client and FTP server. RCOPY does not read the user ID or password from the
NETRC file, so they must be specified when required.
The following explains how to build and run the RCOPY samples.
1. To compile and link the sample, type:
nmake -f vacpp.mak (to build using the VisualAge C/C++ compiler)
2. To run rcopy.exe:
Command syntax:
RCOPY put|get ascii|binary [-l<local path>] -h<host>
-u<userid> -p<password> [-r<rem path>] [-a<account>]
where:
put Transfers from local host to remote host (default)
get Transfers from remote host to local host
binary Binary transfer mode (default)
ASCII ASCII transfer mode
Example:
rcopy put -ld:\tmp -holeg -uyozzo -pyozzops -rc:\newtmp
where:
d:\tmp Is a local path to transfer
oleg Is a remote host (FTP server)
yozzo Is a remote user ID
yozzops Is a remote password
ΓòÉΓòÉΓòÉ 7.3.13.7. RPC Sample Programs ΓòÉΓòÉΓòÉ
RPC consists of three C programs located in \TOOLKIT\SAMPLES\TCPIPTK\RPC:
RAWEX.C provides an example of the RAW client/server usage. Portmapper
must be running.
GENESEND.C sends an integer to the remote host (GENESEND) and receives
the integer back at the local host. Portmapper and Remote server
(GENESEND) must be running.
GENESERV.C is a generic server. It receives an integer or float and
returns them, respectively. Portmapper must be running.
The following explains how to build and run the RPC samples.
1. To compile and link the sample program, type:
nmake -f rpcsamp.mak
2. To start Portmapper, type:
start portmap
3. To start the geneserv.exe server, type:
start geneserv
4. To run genesend.exe, type:
genesend hostname integer
For example:
genesend charm 1000
5. To run rawex.exe, type:
rawex integer
For example:
rawex 1000
ΓòÉΓòÉΓòÉ 7.3.13.8. RPCGEN Sample Programs ΓòÉΓòÉΓòÉ
RPCGEN consists of three user-written files located in
\TOOLKIT\SAMPLES\TCPIPTK\RPCGEN):
RG.X defines the remote procedure characteristics
RGUS.C demonstrates an RPC server program
RGUC.C demonstrates an RPC client program
The following explains how to build and run the RPCGEN samples.
1. Perform the following:
rpcgen rg.x
This generates rg.h, rg.i, rgs.c, rgc.c, and rgx.c.
2. From rgx.c, add the include headers to rgus.c and rguc.c if they do not
already exist
3. Run rpcgsamp.cmd to compile rgus.c, rguc.c, rgs.c, and rgc.c
Link rgs.obj and rgus.obj to generate rgs.exe
Link rgc.obj and rguc.obj to generate rgc.exe
4. Start portmap.exe and rgs.exe on the same machine:
start portmap
start rgs
5. Start rgc.exe by typing:
rgc hostname "user_input string"
ΓòÉΓòÉΓòÉ 7.3.13.9. SAMPDLL Sample Programs ΓòÉΓòÉΓòÉ
SAMPDLL (located in \TOOLKIT\SAMPLES\TCPIPTK\SAMPDLL) demonstrates the use of a
DLL.
MYPROG (located in \TOOLKIT\SAMPLES\TCPIPTK\SAMPDLL) demonstrates building a
DLL.
ΓòÉΓòÉΓòÉ 7.3.13.10. SENDFILE Sample Program ΓòÉΓòÉΓòÉ
This is a TCP client/server application that is used for explaining the
send_file (). The client sends a file to a server.
ΓòÉΓòÉΓòÉ 7.3.13.11. SOCKET Sample Programs ΓòÉΓòÉΓòÉ
SOCKET consists of three client/server samples and SELECTS.C located in
\TOOLKIT\SAMPLES\TCPIPTK\SOCKET.
SELECTS.C is a simple TCP and UDP server that uses the BSD select() call.
MSGC.C/MSGS.C, TCPC.C/TCPS.C, and UDPC.C/UDPS.C are sample C socket
client/server programs demonstrating network programming with OS/2 sockets.
The following explains how to build and run the SOCKET samples.
1. To compile and link the sample programs, type:
nmake -f vacpp.mak (to build using the VisualAge C/C++ compiler)
2. Running udps.exe and udpc.exe:
a. To start the udps server, type:
start udps
An additional session is created and the following message is
displayed:
Port assigned is 1028
b. To run the udpc client, type:
udpc 9.67.60.10 1028
where:
9.67.60.10 Is the IP address of the machine where the udps
server is running
1028 Is the port assigned by the udps server
After running the udpc client, you will see the following output on
the server session:
Received message Hello ................
3. Running tcps.exe and tcpc.exe
a. To start the tcps server, type:
start tcps 2000
where 2000 is the port number assigned to the tcps server.
b. To run the tcpc client, type:
tcpc charm 2000
where:
charm Is the hostname of the machine where the tcps server
is running
2000 Is the port assigned to the tcps server
4. Running selects.exe
The selects server has the same function as the tcps and udps servers.
a. To start the selects server, type:
start selects 2000
where 2000 is the port number assigned to the selects server.
b. To run the tcpc client, type:
tcpc charm 2000
where:
charm Is the hostname of the machine where the selects
server is running
2000 Is the port assigned to the selects server
c. To run the udpc client, type:
udpc 9.67.60.10 2000
where:
9.67.60.10 Is the IP address of the machine where the selects
server is running
2000 Is the port assigned by the selects server
After running the udpc client, you will see the following output on the
server session:
Received message Hello ................
5. Running msgs.exe and msgc.exe
msgs.c and msgc.c are the same program as udps.c and udpc.c, except they
are written using recvmsg() and sendmsg() calls.
a. To start the msgs server, type:
start msgs
An additional session is created and the following message appears:
Port assigned is 1028
b. To run the msgc client, type:
msgc 9.67.60.10 1028
where:
9.67.60.10 Is the IP address of the machine where the msgs
server is running
1028 Is the port assigned by the msgs server
ΓòÉΓòÉΓòÉ 7.3.13.12. SYSCTL Sample Program ΓòÉΓòÉΓòÉ
The sysctl() call accesses and modifies system-wide parameter values for the
entire TCP/IP stack. This sample program sets the ipgate to 1 and then back to
0.
ΓòÉΓòÉΓòÉ 7.3.14. Workplace Shell Sample Programs ΓòÉΓòÉΓòÉ
The Workplace Shell sample programs are as follows:
BROWSE
CAR
CARPP
TEXTFLDR
WPSTUTOR
WSFILE
Note: All Workplace Shell samples require SOM 2.1 in order to execute
properly.
ΓòÉΓòÉΓòÉ 7.3.14.1. BROWSE Sample Program ΓòÉΓòÉΓòÉ
BROWSE displays file system objects in a PM window in either text or
hexidecimal format. Hexidecimal is the default format. To view a file, you can
either drop a file system object on the Workplace Shell ASCII/Hex File Browser
or double-click on the Workplace Shell ASCII/Hex File Browser and enter the
name of a file to view.
To choose the format for viewing an object, click on the Workplace Shell
ASCII/Hex File Browser and select Open Text View or Open Hex View from the Open
menu.
The default view format can be changed in the Settings notebook of the
Workplace Shell ASCII/Hex File Browser by doing the following:
1. Select the Menu tab.
2. Select ~Open from the Available menus: list box.
3. Select Settings.
4. Select Open ~Hex View or Open ~Text View from the Default action list
box.
5. Select OK.
ΓòÉΓòÉΓòÉ 7.3.14.2. CAR Sample Program ΓòÉΓòÉΓòÉ
CAR demonstrates how to create a Workplace Shell object using basic
object-oriented programming techniques and the SOM, including:
Initializing an object
Adding settings pages to an object
Saving and restoring the state of an object
Modifying an object's context menus (adding and deleting menu items)
Querying object class data
Processing context menu items
Implementing settings page dialog processing
Handling exceptions
ΓòÉΓòÉΓòÉ 7.3.14.3. CARPP Sample Program ΓòÉΓòÉΓòÉ
CARPP is a C++ version of the CAR sample program. CARPP demonstrates how to
create a Workplace Shell object using basic object-oriented programming
techniques and the SOM, including:
Initializing an object
Adding settings pages to an object
Saving and restoring the state of an object
Modifying an object's context menus (adding and deleting menu items)
Querying object class data
Processing context menu items
Implementing settings page dialog processing
Handling exceptions
ΓòÉΓòÉΓòÉ 7.3.14.4. TEXTFLDR Sample Program ΓòÉΓòÉΓòÉ
TEXTFLDR allows only plain text objects to be placed into the folder. Objects
that are not plain text, that is, control- or extended-ASCII characters, are
rejected. Objects are considered to be plain text if the "Associated type"
field of the Settings notebook is set to plain text. If there is no associated
type set, the first 500 bytes are placed into the folder.
ΓòÉΓòÉΓòÉ 7.3.14.5. WPSTUTOR Sample Program ΓòÉΓòÉΓòÉ
WPSTUTOR displays the order in which object methods are invoked by the
Workplace Shell. When a sample object's class method is executed, the method's
name and a description of its function are displayed in a PM window. The sample
saves the object's title and its icon title backwards.
This object class subclasses the WPDataFile class. Most Workplace Shell
instance and class methods are overridden so that information about the methods
can be displayed to the user.
This sample is designed to be more of a tutorial for Workplace Shell
programming than a programming example.
Note: The SHOWDESC.EXE file should be renamed to SHOWDESC.BAK (or something
else) to turn off the sample. Rename the file back to SHOWDESC.EXE to
turn the sample back on.
ΓòÉΓòÉΓòÉ 7.3.14.6. WSFILE Sample Program ΓòÉΓòÉΓòÉ
WSFILE displays, creates, and installs Workplace objects of two classes: WSFILE
and WSFOLDER. The WSFILE class is a subclass of the WPDataFile class, and the
WSFOLDER class is a subclass of the WPFolder class.
ΓòÉΓòÉΓòÉ 7.4. Tools ΓòÉΓòÉΓòÉ
This section provides a brief description of each tool with just enough detail
to get you started at the OS/2 command line.
The tools are categorized as follows:
Development Tools
Multimedia
Presentation Manager (PM)
SOM
TCP/IP
Workplace Shell
XPG4
For complete information about the tools described here, please refer to the
online Tools Reference.
Note: The Wave Doctor, previously available with the OS/2 Multimedia Toolkit
product, is not included in the OS/2 Warp Toolkit.
ΓòÉΓòÉΓòÉ 7.4.1. Development Tools ΓòÉΓòÉΓòÉ
The Developer tools help you develop OS/2 programs. It is not likely that you
will use the tools described in this section as much as the compiler and
linker. Nonetheless, these tools are handy to have. Perhaps you will use only a
few of them in your programming career, but it is important to know where you
can find information about them, in the event you will ever need them. The
tools included in this section are:
ALP - Assembly Language Processor
EXEHDR - Executable-Header Files
FWDSTAMP - Forwarders
IMPLIB - Import a Library
KwikINF - Quick Information
LINK386
MARKEXE
MASM2ALP - MASM Compatible Command Line Interface to ALP
MKMSGF - Make Message File
MKTMPF - Make Template File
MSGBIND - Message Binding
NMAKE
PACK and UNPACK
PACK2 and UNPACK2
TRCUST - Trace Customizer
ΓòÉΓòÉΓòÉ 7.4.1.1. ALP ΓòÉΓòÉΓòÉ
The Assembly Language Processor (ALP) is a macro assembler that runs under the
32-bit OS/2 operating system. ALP is designed as a functional replacement for
the Microsoft Macro Assembler (MASM). It accepts the full syntax of the MASM
5.10 assembly language, which is a subset of the MASM 6.00 high-level directive
language. It also understands the complete Intel 80X86 instruction set,
including the MMX extensions. ALP creates standard Object Module Format (.OMF)
files that can be linked to produce DOS or OS/2 executables and can generate
line number debug information compatible with IBM's Presentation Manager
Debugger. In addition, this tool offers a rich set of command-line options, as
well as a comprehensive listing file with user-tailored formatting, allowing a
visual perspective not possible with other assemblers.
ALP translates assembly language source files (typically having a file-name
extension of .ASM) into object (.OBJ) files. The LINK386 utility can then be
used to combine multiple object files into a single executable file, dynamic
link library, or device driver.
While ALP is designed as a functional replacement for the Microsoft MASM
assembler in terms of source code compatibility, it does not use the MASM
command-line syntax. ALP uses a free-form syntax, has a comprehensive set of
options, and allows assembly of multiple input files with a single command-line
invocation.
For each corresponding input source file, ALP can produce the following types
of output files:
Object (.OBJ) files, which contain program data and executable code.
Listing (.LST) files, which document the results of the assembly.
Message (.MSG) files, which can contain all error, warning, and
informational messages produced during the assembly.
See the ALP Programming Guide and Reference for more information on ALP.
Online help is also available from the command line for all ALP options.
ΓòÉΓòÉΓòÉ 7.4.1.2. EXEHDR ΓòÉΓòÉΓòÉ
EXEHDR provides a listing of the contents of the header of an executable file.
It also provides a listing of the attributes of all segments in the file.
Uses of EXEHDR include:
Determining whether a file is an application or a dynamic link library
Modifying and viewing the attributes set by the module definition file
Viewing the number and size of code and data segments.
ΓòÉΓòÉΓòÉ 7.4.1.3. FWDSTAMP ΓòÉΓòÉΓòÉ
FWDSTAMP adds entry points, called forwarders, to a dynamic link library (.DLL)
file. Forwarders point to API functions or other exported code or data. They
contain an import reference so that the final target address of the forwarded
entry is contained in a different module. A forwarder might be called an
imported export.
When a file has a fix-up to a forwarded entry point, the loader resolves that
fix-up to the address of the entry point that the forwarder imports by
traversing the chain of forwarders until the end of the chain (a non-forwarded
export) is reached. All forwarders are implicitly exported.
The imported entry point that a forwarder refers to may itself be another
forwarder. The loader will process a chain of forwarders until a non-forwarder
entry point is encountered.
There is no run-time cost to forwarders; however, there is a slight load-time
cost as the loader resolves forwarder chains with their final addresses.
ΓòÉΓòÉΓòÉ 7.4.1.3.1. Using FWDSTAMP ΓòÉΓòÉΓòÉ
You use forwarders to combine several DLLs into one without having to relink
old applications. For example, if MOUCALLS and VIOCALLS were combined into a
single DLL called NEWLIB.DLL, then MOUCALLS and VIOCALLS could be replaced with
special DLLs containing forwarders to NEWLIB.DLL.
ΓòÉΓòÉΓòÉ 7.4.1.4. IMPLIB ΓòÉΓòÉΓòÉ
IMPLIB is used to generate an import library (.LIB) file. IMPLIB takes a module
definition file (.DEF) as input. For each export definition in the .DEF file,
IMPLIB generates a corresponding import definition.
The .LIB file generated by IMPLIB is used as input to LINK386, which creates an
executable (.EXE) file. The .LIB file provides LINK386 with information about
imported dynamic link functions.
ΓòÉΓòÉΓòÉ 7.4.1.4.1. Creating an IMPLIB ΓòÉΓòÉΓòÉ
Import libraries are created by IMPLIB and are used to link DLLs with
applications.
Import libraries are somewhat similar to standard libraries:
You specify import libraries and standard libraries in the same
command-line field of LINK386.
Both types of libraries resolve external references at link time.
However, import libraries differ from standard libraries in that they contain
no executable code. Rather, they identify the DLLs where the executable code
can be found at run time.
Creating import libraries is an extra step. Nevertheless, import libraries are
recommended for use with all DLLs for two reasons:
IMPLIB automates much of the program creation process for you. To use
IMPLIB, you need to supply the .DEF file you already created for the
dynamic link library. Without an import library, you must create a second
.DEF file that explicitly defines all needed functions in the dynamic
link library.
Import libraries make it easier for one person to write a library and
another to write the application. Much of the linking process (linking
the .DLL file and creating the import library) can be done by the author
of the dynamic link library. The import library and associated .DLL file
can then be given as a unit to the person linking the application--that
person need not worry about creating a .DEF file.
ΓòÉΓòÉΓòÉ 7.4.1.5. KwikINF ΓòÉΓòÉΓòÉ
KwikINF provides you with a quick and convenient method of accessing
information in online documents stored in the OS/2 BOOKSHELF from anywhere on
the Desktop, with the exception of DOS or WIN-OS/2 sessions. When KwikINF is
started, you can search for a text string of your choice directly or through a
pop-up window by pressing a user-selectable hot key. Until you configure
KwikINF, your KwikINF hot key is Alt+Q.
How you initiate a search for information in online documents depends on where
you are on the Desktop when you press the KwikINF hot key:
From an OS/2 full-screen session, a PM VIO or AVIO window, or PM MLE:
Position the cursor on the string you want to search for and press the
KwikINF hot key. KwikINF retrieves the word at the cursor. If you have
configured KwikINF to display the KwikINF window when the KwikINF hot key
is pressed, KwikINF will automatically place the retrieved word in the
Search string entry field of the KwikINF window. When you select Search
or press Enter, KwikINF displays the information. If you have configured
KwikINF to bypass the KwikINF window when the KwikINF hot key is pressed,
KwikINF automatically displays the information.
From a graphic-text PM window:
Press the KwikINF hot key, and then type the string you want to search
for in the Search string entry field of the KwikINF window. The KwikINF
text-retrieval feature is not available from graphic-text PM windows.
ΓòÉΓòÉΓòÉ 7.4.1.6. LINK386 ΓòÉΓòÉΓòÉ
LINK386 is used to combine object files and standard library files into a
single executable file. LINK386 also generates DLLs and device drivers.
LINK386 uses the following files as input:
One or more object files that are linked with any optional library files
to create the executable file. Object files usually have a .OBJ
extension.
One or more library files. The library files contain object modules that
are linked with the object files to create the executable file. Library
files usually have a .LIB extension.
A module definition file. The module definition file provides information
to LINK386 about the executable file or dynamic link library file it is
creating. The module definition file usually has a .DEF extension.
LINK386 produces three types of output files:
An executable file. This executable file runs under OS/2 whenever you
specify a module definition file that has a NAME statement. The
executable file usually has an .EXE extension.
A dynamic link library file. A dynamic link library is produced whenever
you specify a module definition file that has a LIBRARY statement. A
dynamic link library file usually has a .DLL extension.
A device driver file. A virtual or physical device driver is produced
whenever you specify a module definition file that has the VIRTUAL DEVICE
or PHYSICAL DEVICE statements. A device driver file usually has a .SYS
extension.
Note:
Three additional options are available with the OS/2 Warp Toolkit:
/E[XEPACK:{1|2}] Causes pages of code and data in the file to be
compressed.
/NOO[UTPUTONERROR] Prevents the LINK386 from creating the
executable file if an error is encountered.
/NOS[ECTORALIGNCODE] Turns off the alignment feature provided through
the LINK386 linker. LINK386 normally aligns
pages of code on sector (512 byte) boundaries,
reducing the time to load the pages when the
application is executed. The /NOSECTORALIGNCODE
option aligns pages of code based on the value
used in the /ALIGN option.
ΓòÉΓòÉΓòÉ 7.4.1.6.1. Creating a Response File for LINK386 ΓòÉΓòÉΓòÉ
To operate LINK386 using a response file, you must first create a file that
contains the responses you want LINK386 to process. You can give the file any
name and create it with any text editor.
Type the following command at the command prompt:
LINK386 @filename[.ext]
The @ symbol tells LINK386 that filename is a response file. If the file is not
in the working directory, you must specify the path. Begin using a response
file at any point on the LINK386 command line or at any LINK386 prompt. The
file should contain responses in the same order as the LINK386 prompts. Each
response needs to be on a separate line. If you choose to place responses on
the same line, separate them with commas.
If the file does not contain responses for all the prompts, LINK386 displays
the appropriate prompt and waits for you to supply a response. End the response
file with a semicolon.
You can use special characters in the response file the same way you would use
them in responses entered at the keyboard.
ΓòÉΓòÉΓòÉ 7.4.1.6.2. Example of a Response File for LINK386 ΓòÉΓòÉΓòÉ
The response file in the following example instructs LINK386 to generate an
executable file called FUN.EXE, and four object modules: FUN, SUN, RUN, and
GAMES.
fun+sun+run+games /map
fun.exe
funlist
;
If you specify the file name FUNLIST, LINK386 will generate a map file named
FUNLIST.MAP. Adding the /MAP option causes LINK386 to include the public
symbols of the application in the map file.
ΓòÉΓòÉΓòÉ 7.4.1.6.3. OS2STUB.EXE ΓòÉΓòÉΓòÉ
OS2STUB.EXE is included in the executable file created by LINK386 if the STUB
statement is included in the module definition file. The stub is invoked
whenever the file is executed under DOS. By default, LINK386 adds its own
standard stub for this purpose.
ΓòÉΓòÉΓòÉ 7.4.1.7. MASM2ALP ΓòÉΓòÉΓòÉ
MASM2ALP is a utility that accepts a Microsoft Macro Assembler (MASM)
command-line syntax, translates the parameters into a syntax acceptable to the
ALP assembler, and then invokes ALP.EXE to perform the assembly. It allows ALP
to be used in place of MASM without requiring modifications to existing
makefiles. See the ALP Programming Guide and Reference for more information.
ΓòÉΓòÉΓòÉ 7.4.1.8. MARKEXE ΓòÉΓòÉΓòÉ
MARKEXE lets you view and set the type of application. The type of application
identifies the OS/2 sessions in which a program can run. You can use MARKEXE in
conjunction with programs that you have created using LINK386 or with programs
created by some other means.
ΓòÉΓòÉΓòÉ 7.4.1.9. MKMSGF ΓòÉΓòÉΓòÉ
MKMSGF converts a text message file to an output (binary) message file that
DosGetMessage uses to display messages. Text messages in OS/2 full-screen
applications do not need to be loaded into memory with the application; they
can reside on disk until needed.
You can use the output message file by specifying a message file name and a
message number in the DosGetMessage parameter list. The messages also can be
bound to the executable file by MSGBIND.
ΓòÉΓòÉΓòÉ 7.4.1.9.1. Creating a MKMSGF ΓòÉΓòÉΓòÉ
The input message file is a standard ASCII file that contains three types of
lines:
Comment
Component identifier
Component message
Comment lines are the first lines of a file and must begin with a semicolon. A
component-identifier is a three-character name identifier (for example, "DOS")
that precedes all MKMSGF message numbers. Component-message lines consist of
a message header and an ASCII text message.
The following is an example of a text message source file.
;This is an example
;of a text message
;file
DOS
DOS0100E: File not found
DOS0101?:
DOS0102H: Usage: del [drive:][path] filename
DOS0103?:
DOS0104I: 1% files copied
DOS0105?:
DOS0106W: Warning! All data will be erased!
DOS0107?:
DOS0108?:
DOS0109P: Do you wish to apply these patches (Y or N)? %0
where:
DOS0100E - DOS0109P Identifies message numbers in sequence. The first
three characters indicate the component identifier;
the four-digit number indicates the message number,
which is followed by a letter (described below), and
then a colon and blank space. If a message number is
not used, type the number, end it with a question
mark (?), and leave an empty entry.
E, H, I, P, W Indicates the type of message. Categories include
error (E), help (H), information (I), prompt (P), and
warning (W).
%0 Displays a prompt for input from the user, after
which a carriage return and line feed are inserted.
ΓòÉΓòÉΓòÉ 7.4.1.10. MKTMPF ΓòÉΓòÉΓòÉ
MKTMPF creates template repository files from text input files. A template
repository is a binary file used by the OS/2 Error Logging Facility to find
error messages, causes, and actions in various message files. MKTMPF is located
in the \TOOLKIT\BIN subdirectory.
MKTMPF is located in the \TOOLKIT\BIN subdirectory.
ΓòÉΓòÉΓòÉ 7.4.1.11. MSGBIND ΓòÉΓòÉΓòÉ
When DosGetMessage is issued, it searches for the message in the message
segment bound to the application's executable file, and then searches the
application's message file on a hard disk. To ensure that a message is
displayed quickly, you can bind it to the application's executable file by
using the MSGBIND utility program. For each executable file, MSGBIND specifies
which message files to scan; for each message file, it specifies which message
to include in the executable file.
Note: The MSGBIND utility program supports the new compression format
available with LINK386 (/EXEPACK:2) and RC (-x2).
The input file contains three types of lines:
> Executable file
< Message file
Message numbers
An example of an input file follows:
>PROG1.EXE
<\MESSAGES\PRGMSG.MSG
PRG0100
PRG0101
PRG0102
<\MESSAGES\APP.MSG
APP0001
APP0002
APP0003
where:
>PROG1.EXE Is the executable file to be modified
< Defines the first message of a series to be bound, delimited
either by the end of the series or a less-than symbol (<).
<\MESSAGES\PRGMSG.MSG and <\MESSAGES\APP.MSG Names the files containing the
binary versions of the messages (created by MKMSGF) and their
identifying numbers: the three-character component identifier
and the four-digit message number.
ΓòÉΓòÉΓòÉ 7.4.1.12. NMAKE ΓòÉΓòÉΓòÉ
NMAKE carries out all tasks needed to create or update a program after one or
more of the source files in the program have changed. NMAKE compares the
modification dates for one set of files (the target files) with those of
another set of files (the dependent files). NMAKE then carries out a given
task only if a target file is out of date. NMAKE does not compile and link all
files just because one file was updated. This can save time when creating
programs that have many source files or that take several steps to complete.
ΓòÉΓòÉΓòÉ 7.4.1.12.1. Using NMAKE ΓòÉΓòÉΓòÉ
To use NMAKE, create a description file (or makefile). A description file, in
its simplest form, lists which files depend on others and which commands need
to be executed if a file changes. You can create an NMAKE description file with
any text editor that produces ASCII files.
A description file looks like this:
targets... : dependents...Γöé
command ΓöéΓöÇΓöÇΓöÇΓöÇ description block
: Γöé
targets... : dependents...
command
:
A dependent relationship among files is defined in a description block. A
description block indicates the relationship among various parts of the
program. It contains commands to bring all components up-to-date. The
description file can contain any number of description blocks.
Use NMAKE description files for creating backup files, configuring data files,
and running programs when data files are modified.
ΓòÉΓòÉΓòÉ 7.4.1.13. PACK and UNPACK ΓòÉΓòÉΓòÉ
PACK reduces the size of a file by compressing its data. You can use PACK for a
single file or a group of files, thereby reducing the disk space required for
your OS/2 application. UNPACK (provided with the OS/2 operating system)
restores a compressed file to its original size and copies it to a specified
directory.
ΓòÉΓòÉΓòÉ 7.4.1.13.1. Creating a List File ΓòÉΓòÉΓòÉ
To use a list file with PACK, you must first create a file that contains the
names of the files you want to compress. You can give the list file any name.
Following is an example of specifying a list file at the command line:
PACK DEVICE.LST DEVICE.DRV /L
The /L indicates that DEVICE.LST is a list file. If the list file is not in the
working directory, you must specify the drive and path. Global file-name
characters are not permitted in the list-file name. DEVICE.DRV is the
destination file for the end-to-end-compressed data. (End-to-end compressed
data is the data from each of the files contained in the list file. This data
is stored in a contiguous format in the destination file.)
The syntax used in the list file is similar to that used in the command line.
The syntax for a single line in the list file follows:
sourcefile [/H:headerpath\|/H:headerfile|/H:headerpath\ headerfile]
[/D:headerdate] [/T:headertime] [/C]
Remember, when using the list-file method (method 2), global file-name
characters are not permitted in the source-file name. Notice also that "PACK"
is excluded, and packedfile is not permitted in the list file, because they
were specified on the command line. You can include comments or blank lines by
entering a semicolon as the first character of the line. An example of a list
file follows:
;This is a comment
C:\OS2\COMMAND.COM
CONFIG.SYS /H:CONFIG.BAK /C
\OS2\INSTALL\DDINSTAL.EXE /H:\OS2\DDINSTAL.TMP /D:10-15-91 /T:11.45
ΓòÉΓòÉΓòÉ 7.4.1.14. PACK2 and UNPACK2 ΓòÉΓòÉΓòÉ
The algorithm used to compress files has been substantially enhanced. The use
of these utility programs is identical to the PACK and UNPACK utilities, which
are documented in the Tools Reference.
Note: UNPACK2 is provided with the OS/2 operating system.
ΓòÉΓòÉΓòÉ 7.4.1.15. TRCUST, MAKETSF, and DEBDEL ΓòÉΓòÉΓòÉ
The Trace Customizer utility program (TRCUST) converts a trace source file
(TSF) to a trace format file (TFF) that defines the formatting for an event
trace record. You can use TRCUST to combine multiple TFFs into a single TFF.
Two additional tools that are complementary to TRCUST are also included in the
Toolkit:
MAKETSF
The purpose of MAKETSF is to extract dynamic trace definitions imbedded
in C or ASM source file to which they relate. MAKETSF can also
substitute line number information into those trace definitions that are
specified by line number and source file reference.
DEBDEL
The purpose of DEBDEL is to remove debugging information from a load
module after TRCUST has generated the trace definition file (TDF).
For more information on all of these tools, refer to the OS/2 Debugging
Handbook.
ΓòÉΓòÉΓòÉ 7.4.2. Multimedia Tools ΓòÉΓòÉΓòÉ
This section describes the Multimedia tools that help you develop multimedia
programs. The following multimedia tools are available in this release:
MIDICONV - MIDI Conversion Utility
P2STRING
Note: The Wave Doctor, previously available with the OS/2 Multimedia Toolkit
product, is not available with this version of the OS/2 Warp Toolkit.
ΓòÉΓòÉΓòÉ 7.4.2.1. MIDICONV ΓòÉΓòÉΓòÉ
MIDICONV is a conversion utility program that lets you convert a MIDI format 1
file to a MIDI format 0 file through the use of an installable I/O procedure.
Note: A MIDI format 0 file has only one track of music; a MIDI format 1 file
has multiple tracks of music.
ΓòÉΓòÉΓòÉ 7.4.2.2. P2STRING ΓòÉΓòÉΓòÉ
P2STRING is used to test OS/2 multimedia subsystems through the media control
interface string commands in the OS/2 multimedia environment. This tool
processes script files (containing string commands and tool directives) to test
the behavior of subsystems in OS/2 multimedia. P2STRING extracts the strings
from the script files and processes the commands through the mciSendString
function. Messages and error conditions of the processes included in the
scripts are logged to an output file and displayed in windows.
P2STRING provides subsystem developers with an effective testing tool because
it alleviates the need for extensive test code to be written. Developers can
write script files to test all relevant scenarios and it also aids in debugging
using log files.
Note: Refer to the README.P2S file in the P2STRING subdirectory for
information about how to use P2STRING and how to create script files
that it can process. The OS/2 Multimedia Subsystem Programming Guide
contains additional information describing P2STRING.
ΓòÉΓòÉΓòÉ 7.4.3. Presentation Manager (PM) Tools ΓòÉΓòÉΓòÉ
This section describes the Presentation Manager tools that help you develop
Presentation Manager programs:
DLGEDIT - Dialog Editor
FONTEDIT - Font Editor
ICONEDIT - Icon Editor
IPFC - Information Presentation Facility Compiler
RC - Resource Compiler
ΓòÉΓòÉΓòÉ 7.4.3.1. DLGEDIT ΓòÉΓòÉΓòÉ
DLGEDIT (Dialog Editor) is used to create and modify dialog boxes and specify
the controls and text within dialog boxes. As you create a dialog box and add
controls, the dialog editor draws it to the screen. You can resize and
reposition the dialog box, and then test its controls before you incorporate it
in your application.
Although the dialog editor draws box outlines and controls to the screen so
that you can view it from a user's perspective, the dialog editor does not save
it as a graphic. Instead, the dialog editor stores a description of the dialog
box and its controls in a text file that has a file-name extension of .DLG. It
also creates a compiled form of the .DLG file into a resource file that has an
extension of .RES. The dialog-box and resource files can each contain
descriptions of more than one dialog box. The resource file can contain other
application resources, such as icons, bitmaps, and string tables. It is
attached to the application's executable (.EXE) file after the compile and link
processes.
This version of the Dialog Editor is enhanced for use with Pen for OS/2. With
this enhanced version, handwriting and sketch controls are available.
ΓòÉΓòÉΓòÉ 7.4.3.2. FONTEDIT ΓòÉΓòÉΓòÉ
FONTEDIT (Font Editor) is used to design and save fonts for use in
applications. A font is a set of alphanumeric characters, punctuation marks,
and other symbols that share a common typeface design and line weight.
When the font editor creates a font file, it supplies an .FNT file-name
extension. The font file contains a header, which describes the font in general
terms, and a section that contains bitmaps of the characters themselves.
ΓòÉΓòÉΓòÉ 7.4.3.2.1. Font Resource Files ΓòÉΓòÉΓòÉ
All resources, except fonts, can be bound to the application's executable file
or compiled into a dynamic link library (DLL). Fonts must be put in a separate
.DLL using the RC. You then link the file at run time and load the resources
into your application by using DosLoadModule or GpiLoadFonts. A .DLL containing
font resources must have a file-name extension of .FON. The .FON file can be
installed on the system.
ΓòÉΓòÉΓòÉ 7.4.3.3. ICONEDIT ΓòÉΓòÉΓòÉ
ICONEDIT (Icon Editor) is used to create icons, pointers, and bitmaps. In the
PM, an icon is a graphic symbol that identifies a data object, a system action,
or a minimized application. A pointer is a small shape on the screen that
reflects the movement of the mouse. Pointers have a hot spot that identifies
their exact location on the screen.
Icons, pointers, and bitmaps produced by the Icon Editor are graphic symbols
comprised of pels in any of the following display states:
Black
White
Color
Screen (background color)
Inverse screen (inverse of background color).
Mini-icons (also called small icons) are icons that are one-half the size of
normal icons (also called large icons). Normal icons are 32x32 or 40x40 pels
(depending on the monitor resolution). Mini-icons are 16x16 or 20x20 pels.
They are used in areas where a normal icon is too large, for example, in
toolbars.
If you previously had OS/2 installed on your system, and if you did not update
your icon profile when you installed this OS/2 Warp Toolkit, you need to run
the Icon Editor once with its profile update options in order to use the
mini-icon forms. To do this, enter:
X:\TOOLKIT\BIN\ICONEDIT /t /i
where X is the drive location for the installed OS/2 Warp Toolkit.
After the initial run of Icon Editor, the new mini-icons will be part of your
profile and you will not need to use options /t /i again.
ΓòÉΓòÉΓòÉ 7.4.3.3.1. Starting ICONEDIT ΓòÉΓòÉΓòÉ
To start the Icon Editor, select the PM Development Tools folder, and then
select the Icon Editor object. The following window is displayed:
Notice the information area at the top of the Icon Editor window; the items
displayed from left to right include:
A two-button mouse, showing the color currently selected for each button
An actual-size image of the current figure that you are editing
A status area that provides:
- Size (in pels using X- and Y-coordinates)
- Pen location
- Pen size (from 1-by-1 to 9-by-9)
- Hot spot (for icons and pointers, but not bitmaps)
- Figure type (icon, pointer, or bitmap)
- Form name
The palette window, in the lower-right corner, displays the colors that are
available for use during editing. The colors currently selected are marked
with frames.
The editing window is the largest part of your working area. Use the mouse to
paint the enlarged representation with the selected color.
The menu-bar choices provide access to the many functions of the Icon Editor.
These choices enable you to:
Create a new icon, pointer, or bitmap
Edit an existing icon, pointer, or bitmap
Test the new icon or pointer
Superimpose a grid over the editing window (for drawing a symmetrical
figure)
Restrict a drawing to straight vertical or horizontal lines
Make transparent pels (for icons or pointers) visible
Change the shape and size of the pen
Select system preferences (to set prompts or suppress warnings)
Define hot spots (where the mouse pointer is directed).
ΓòÉΓòÉΓòÉ 7.4.3.4. IPFC ΓòÉΓòÉΓòÉ
Information Presentation Facility (IPF) is a set of tools used to create an
online help facility for an application. IPF is also used to create online
information that can be viewed independent of an application. It is a tool for
both the information author and the application programmer.
As an author of online information, you can define the windows in which
information is displayed. For example, a window can be split so that scrollable
text can be displayed beside a stationary illustration that the text describes.
The following figure shows an IPF application-control-window.
ΓòÉΓòÉΓòÉ 7.4.3.4.1. Developing Online Information ΓòÉΓòÉΓòÉ
IPF makes it possible for you to design your information in two types of
formats:
An online document format for reference books
A help-window format for context-sensitive help for your application
programs
To produce either format, you must create a text file using a text editor and
two IPF elements:
IPF tagging language, which consists of instructions for formatting and
displaying your document on the screen.
Information Presentation Facility Compiler (IPFC), which interprets the
tags and converts the source file into an IPF format.
ΓòÉΓòÉΓòÉ 7.4.3.4.2. Compiling Help Files ΓòÉΓòÉΓòÉ
To compile a source file that is intended as a help-text window, use the IPFC
command without the /INF option. For example:
IPFC myhelp.hlp
ΓòÉΓòÉΓòÉ 7.4.3.4.3. Compiling with International Language Considerations ΓòÉΓòÉΓòÉ
The following parameters provide international language support:
/COUNTRY = nnn (where nnn is the 3-digit country code)
/CODEPAGE = nnnn (where nnnn is the 3 or 4-digit code page)
/LANGUAGE = xxx (where xxx is a 3-letter identifier that
indicates an international language file is to be used)
An example of the command-line syntax follows:
IPFC myfile.txt /INF /COUNTRY=033 /CODEPAGE=437 /LANGUAGE=FRA
You can now add additional languages to IPFC by providing an IPFxxx.NLS file
where xxx matches the name of the language supplied with the /LANGUAGE or -L
switch.
You can also add additional code pages by providing an APSYxxxx.APS file where
xxxx matches the number of the code page. Four-digit code pages are supported.
Three-digit code pages have a leading 0 in their APSYxxxx.APS file name, but
the leading 0 does not have to be passed with the /CODEPAGE or -C switch. The
underlying operating system must support the supplied code page.
Note: When adding new language or code page files, be sure they are located in
the same subdirectory where your IPFC program files are located.
The bidirectional version of IPFC.EXE (IPFCBIDI.EXE) is not included as a
separate program with this version of the OS/2 Warp Toolkit. However, the
bidirectional support in IPFCBIDI has been integrated into the American
version of the program, IPFC.EXE. It will be necessary for you to modify any
makefiles that reference IPFCBIDI.EXE to reference IPFC.EXE instead.
ΓòÉΓòÉΓòÉ 7.4.3.4.3.1. IPFC Environment Variables ΓòÉΓòÉΓòÉ
There are four environment variables that can be used to specify the location
of source files:
IPFC Specifies the location of the .IPF support files (such as
APSYMBOL.APS and IPF*.NLS).
IPFCIMBED Searches for files imbedded with the .im macro.
IPFCARTWORK Specifies the location of artwork files and artlink files.
TMP Indicates where the compiler should store the temporary
files it creates during the compilation.
ΓòÉΓòÉΓòÉ 7.4.3.4.4. Viewing an Online Document ΓòÉΓòÉΓòÉ
If you want to see your formatted online document, you can use the VIEW command
to display it.
An online document has an extension of .INF. It can be viewed by entering its
name as a parameter to the VIEW command; for example:
VIEW myfile
You do not need to include the .INF file extension.
Note: You cannot use VIEW to display help-text windows for application
programs. However, for test viewing purposes, you can compile the help
text as .INF files and use VIEW to look at the information.
ΓòÉΓòÉΓòÉ 7.4.3.5. RC ΓòÉΓòÉΓòÉ
RC (Resource Compiler) is a tool that lets you add application resources, such
as message strings, pointers, menus, and dialog boxes, to your application's
executable file. The primary purpose of RC is to prepare data for applications
that use functions such as WinLoadString, WinLoadPointer, WinLoadMenu, and
WinLoadDlg. These functions load resources from the application's executable
file or another specified executable file. The application then can use the
loaded resources as needed.
RC and the resource functions let you define and modify application resources
without recompiling the application itself. RC can modify the resources in an
executable file at any time without affecting the rest of the file. You can
create custom applications from a single executable file by using RC to add the
custom resources you need to each application. RC is especially important for
international language support because it lets you define all
language-dependent data, such as message strings, as resources. Preparing the
application for a new language is simply a matter of adding new resources to
the existing executable file.
ΓòÉΓòÉΓòÉ 7.4.3.5.1. Creating an RC File ΓòÉΓòÉΓòÉ
All resources are defined in a resource script file. You use a text editor to
create a resource script file that has an .RC extension. Resources are defined
either explicitly in statements in the resource script file, or in other files
(such as output files from the resource editors). The .RC file is the input
file to the RC; the output has an .RES extension. The .RC file can contain
statements that define resources and that include resources from other files.
Text-based resources such as menus, accelerator keys, and text strings are
defined in the .RC file. Non-text-based resources are specified in the .RC file
as file names of the external files where these resources reside. Such
resources include icons, pointers, and bitmaps. The syntax for including
external files in a resource script varies according to the nature of the
resources defined or contained in the files. Fonts have a resource file to
themselves.
Make sure that none of the include files in your resource script file contain
an end-of-file character. When the RC sees an end-of-file character, it assumes
it to be the end of all input.
For an example of a resource script file, see the sample program TEMPLATE.
ΓòÉΓòÉΓòÉ 7.4.4. SOM Tools ΓòÉΓòÉΓòÉ
SOM tools help you develop SOM programs. This section describes the SOM tools:
CTOI
IRDUMP - Information Repository Dump
PDL - Public Definition Language
PREGIMPL - PM version of REGIMPL
REGIMPL - Implementation Registration
SC - SOM Compiler
SOMCORBA - SOM CORBA
SOMDCHK - SOM Check
SOMDD - SOM DSOM Daemon
SOMDSRV - SOM Server
SOMENV - SOM Environment
SOMSTARS
SOMXH - SOM .XH Header Files
WPIDL2XH - Workplace Shell .IDL To .XH Files
ΓòÉΓòÉΓòÉ 7.4.4.1. CTOI ΓòÉΓòÉΓòÉ
CTOI automates the conversion process from the SOM 1.0 format (.CSC files) to
SOM 2.0 format (.IDL files). An example of the syntax follows:
CTOI f1
where f1 is the name of the .CSC file to be converted.
You might require some modifications to your environment and your existing code
in order to use this tool successfully. For more information, see the article
titled Using the SOM CTOI Tool in the online version of the Developer
Connection News, Volume 5. This newsletter can be found by opening the
following folders, starting with The Developer Connection folder:
The Developer Connection Browser
The Developer Connection for OS/2 References
Newsletters
Developer Connection News
ΓòÉΓòÉΓòÉ 7.4.4.2. IRDUMP ΓòÉΓòÉΓòÉ
IRDUMP (Information Repository Dump) verifies that a class exists in the
Information Repository. An example of the syntax follows:
IRDUMP [-o] [-w] [-?] [object]
where:
-o Includes file offset information.
-w Follows dump with "within" operation.
-? Shows this usage information.
object Is a simple or fully qualified name of an object in the Interface
Repository.
The default action is to dump all objects.
ΓòÉΓòÉΓòÉ 7.4.4.3. PDL ΓòÉΓòÉΓòÉ
PDL (Public Definition Language) is a separate program that performs the same
function as the Public Definition Language (PDL) emitter used with the SOM
Compiler. That emitter generates a copy of an .IDL file that has had the
portions designated as private removed. The file generated is the same as the
.IDL file from which it is produced, except that it removes all items within
the .IDL file that are marked as "private." An item is marked as private by
surrounding it with #ifdef __PRIVATE__ and #endif directives. Thus, the PDL
emitter can be used to generate a "public" version of an .IDL file. (Generally,
client programs will need only the "public" methods and attributes.)
The PDL program can be invoked independently of the SOM Compiler. In addition,
the PDL program can remove any kind of items in the .IDL file that are preceded
by a user-specified #ifdef directive and followed by an #endif directive.
The PDL program is invoked as follows:
PDL [-c] [-d] [-f] [-h] [-s] [-/] files
where:
-c cmd Specifies that, for each .IDL file, the PDL program is to run
the specified system command. This command can contain a single
occurrence of the string %s, which will be replaced with the
source file name before the command is executed. For example,
the option -c sc -sh %s has the same effect as issuing the SC
command with the -sh option.
-d dir Specifies a directory in which the output files are to be
placed. (The output files are given the same name as the input
files). If no directory is specified, the output files are
named <fileStem>.PDL (where fileStem is the file stem of the
input file) and are placed in the current working directory.
-h Requests this description of the PDL command syntax and
options.
-f Specifies that output files are to replace existing files with
the same name, even if the existing files are read-only. By
default, files are replaced only if they have write access.
-s smemit Specifies the SMEMIT variable with which the PDL program is to
invoke the SOM Compiler.
-/ <string> Specifies the #ifdef pattern for which the PDL program will
strip out .IDL statements. The default value is #ifdef
__PRIVATE__.
files Specifies one or more .IDL files whose specified #ifdef
sections are to be removed. File names must be completely
specified (with the .IDL extension). If no #ifdef directive is
specified (by including a -/<string> option), the #ifdef
__PRIVATE__ sections will be removed by default.
Selected options can be specified individually, as a string of option
characters, or as a combination of both. Any option that takes an argument
either must be specified individually or must appear as the final option in a
string of option characters.
ΓòÉΓòÉΓòÉ 7.4.4.4. PREGIMPL ΓòÉΓòÉΓòÉ
PREGIMPL is a Presentation Manager version of the REGIMPL tool.
ΓòÉΓòÉΓòÉ 7.4.4.5. REGIMPL ΓòÉΓòÉΓòÉ
Before an implementation (a server program and class libraries) can be used by
client applications, it must be registered with DSOM by running the
Implementation Registration utility program, REGIMPL. This facility is
available primarily for use in command (.CMD) files.
During execution of REGIMPL, DSOM updates its database to include the new
server implementation and the associated classes. This enables DSOM to find
and, if necessary, to activate the server so that clients can invoke methods on
it.
Below are some examples on how you can use REGIMPL.
To enter interactive mode:
REGIMPL
To add implementation:
REGIMPL -A -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>]
[-h <str>] [-m {on|off}] [-z <str>]
To update implementation:
REGIMPL -U -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>]
[-h <str>] [-m {on|off}]
To delete implementation:
REGIMPL -D -i <str> [-i ...]
To list implementations:
REGIMPL -L [-i <str> [-i ...]]
To list aliases:
REGIMPL -S
To add classes:
REGIMPL -a -c <str> [-c ...] -i <str> [-i ...]
To delete classes:
REGIMPL -d -c <str> [-c ...] [-i <str> [-i ...]]
To list classes associated with implementations:
REGIMPL -l [-i <str> [-i ...]]
where:
-i <str> Is the implementation alias name.
-p <str> Is the server program name. The default value is
SOMDSVR.EXE.
-v <str> Is the server-class name. The default value is
SOMDServer.
-f <str> Is the reference data file name. Use NULL to delete.
-b <str> Is the reference data backup file name. Use NULL to
delete.
-h <str> Is the host machine name. The default value is
localhost.
-m {on|off} Enables multi-threaded server.
-z <str> Is the implementation ID.
-c <str> Is the class name.
ΓòÉΓòÉΓòÉ 7.4.4.6. SC ΓòÉΓòÉΓòÉ
The OS/2 operating system provides a programming interface that enables
applications to implement Desktop objects. This programming interface enables
you to create Desktop objects that conform to the CUA architecture using a
basic object-oriented programming interface. The interface is implemented using
the IBM SC (SOM Compiler).
The SOM Compiler (SC) helps implementers build classes in which interface and
implementation are decoupled. The SOM Compiler reads the IDL definition of a
class interface and generates:
An implementation skeleton for the class
Bindings for implementors
Bindings for client programs
Bindings are language-specific macros and procedures that make implementing
and using SOM classes more convenient. These bindings offer a convenient
interface to SOM that is tailored to a particular programming language. For
instance, C programmers can invoke methods in the same way they make ordinary
procedure calls. The C++ bindings "wrap" SOM objects as C++ objects, so that
C++ programmers can invoke methods on SOM objects in the same way they invoke
methods on C++ objects. In addition, SOM objects receive full C++
typechecking, just as C++ objects do. Currently, the SOM Compiler can generate
both C and C++ language bindings for a class.
ΓòÉΓòÉΓòÉ 7.4.4.6.1. SMEMIT Environment Variable ΓòÉΓòÉΓòÉ
SMEMIT is used to indicate which emitter programs should be executed. Like the
SMINCLUDE environment variable it can consist of a list of items separated by
semicolons. Each item designates a particular emitter by the name of the file
extension the emitter produces. The syntax is as follows:
SMEMIT=[h;ih;c;xh;xih;xc;def;ir;pdl]
The default values are h and ih. For example:
SET SMEMIT=H;IH;DEF;
indicates that EMITH.EXE, EMITIH.EXE, and EMITDEF.EXE programs should be
executed to produce .H, .IH, and .DEF files, respectively. By default all
emitted output files are placed in the same directory as the input file. If the
SMEMIT environment variable is not defined, the SOM compiler will perform a
syntax check of your class definition but no output will be produced.
Note: All command-line modifiers can be set in the environment by changing
them to UPPERCASE and preappending SM to them.
ΓòÉΓòÉΓòÉ 7.4.4.6.2. SMINCLUDE Environment Variable ΓòÉΓòÉΓòÉ
The SOM compiler uses an environment variable called SMINCLUDE to locate
included class definitions. SMINCLUDE specifies where to search for .IDL and
.EFW files. Because every SOM class will have an include file for its parent
class definition, you must set SMINCLUDE before running the SOM compiler. Its
form is similar to the OS/2 PATH or DPATH environment variables, in that it can
consist of one or more directory names, separated by a semicolon. Directory
names can be specified with absolute or relative path names. The syntax is as
follows:
SMINCLUDE=<dir1>[;<dir2>]+
For example:
SET SMINCLUDE=.;C:\TOOLKIT\SOM\INCLUDE;C:\TOOLKIT\IDL;
Note: All command-line modifiers can be set in the environment by changing
them to UPPERCASE and preappending SM to them.
ΓòÉΓòÉΓòÉ 7.4.4.6.3. SMKNOWNEXTS Environment Variable ΓòÉΓòÉΓòÉ
SMKNOWNEXTS add headers to user-written emitters. The syntax is as follows:
SMKNOWNEXTS=ext[;ext]+
Note: All command-line modifiers can be set in the environment by changing
them to UPPERCASE and preappending SM to them.
ΓòÉΓòÉΓòÉ 7.4.4.6.4. SMTMP Environment Variable ΓòÉΓòÉΓòÉ
The SMTMP environment variable specifies the name of a directory that the SOM
compiler uses to hold intermediate output files. The syntax is as follows:
SMTMP=<dir>
For example:
SET SMTMP=%TMP%
tells the SOM compiler to use the same directory for temporary files as given
by the setting of the TMP environment variable. As a general rule, the
directory indicated by SMTMP should never coincide with the directory used by
the SOM compiler for its input or the emitted output files.
Note: All command-line modifiers can be set in the environment by changing
them to UPPERCASE and preappending SM to them.
ΓòÉΓòÉΓòÉ 7.4.4.6.5. SOMIR Environment Variable ΓòÉΓòÉΓòÉ
SOMIR provides a list of IRs to search for. The syntax is as follows:
SOMIR=<path>[;<path>]+
Note: All command-line modifiers can be set in the environment by changing
them to UPPERCASE and preappending SM to them.
ΓòÉΓòÉΓòÉ 7.4.4.6.6. #pragma Directives ΓòÉΓòÉΓòÉ
There are two pragma directives:
#pragma somemittypes on Turns on the emission of global types.
#pragma somemittypes off Turns off the emission of global
types.
#pragma modifier <modifier stm> Replaces a modifier statement.
ΓòÉΓòÉΓòÉ 7.4.4.6.7. Running SOM Emitters ΓòÉΓòÉΓòÉ
You complete the SOM compilation process by running the emitters. You can
control the output of the emitters from the command line by typing:
command [-o filename] [-a name[=value]]*
where:
command Is one of the following:
EMITH
EMITIH
EMITC
EMITDEF
filename Is an explicit name (including drive, path, and file-name
extension) for the emitted output file. If this option is
not specified, the output file is placed in the current
directory, and the file-name extension defaults to a type
appropriate to the selected emitter program.
-a name[=value] Adds a global attribute.
ΓòÉΓòÉΓòÉ 7.4.4.7. SOMCORBA ΓòÉΓòÉΓòÉ
SOMCORBA is a command script that you can use to convert to implicit pointers
(like CORBA) for interface references.
ΓòÉΓòÉΓòÉ 7.4.4.8. SOMDCHK ΓòÉΓòÉΓòÉ
SOMDCHK evaluates the environment to verify whether DSOM can operate correctly.
The program generates messages that evaluate the DSOM environment. It
determines whether the necessary SOM DLLs can be located, whether DSOM is
enabled for workgroup (cross-machine) communication, whether Interface and
Implementation Repositories can be located, and it displays the settings of
important environment variables. In its "verbose" mode, SOMDCHK gives the
default settings for DSOM environment variables and explains how DSOM uses
them.
The program is invoked from the command line using the syntax given below. The
optional verbose setting can be turned on by including the -v option with the
following command:
SOMDCHK [-v]
ΓòÉΓòÉΓòÉ 7.4.4.9. SOMDD ΓòÉΓòÉΓòÉ
SOMDD is the DSOM daemon. It must be started prior to running a DSOM
application. The daemon can be started manually from the command line, or it
could be started automatically from a start-up script run at boot time. It can
be run in the background with the following command:
START SOMDD
The SOMDD program requires no parameters. An optional -q parameters can be
used to set "quiet" mode, to suppress messages.
Note: The SOMDD.EXE program included with VisualAge C++ is incompatible with
the version of SOM used with OS/2 Warp Toolkit and should not be used.
You will need to update both your LIBPATH and PATH statements to ensure
that the OS/2 Warp Toolkit path is ahead of the VisualAge C++ compiler.
ΓòÉΓòÉΓòÉ 7.4.4.10. SOMDSVR ΓòÉΓòÉΓòÉ
SOMDSVR is the "generic" server program. It can be started either from the
command line or automatically upon demand. When starting SOMDSVR from the
command line, the server's implementation ID or alias must be supplied as an
argument. The command syntax for starting a generic SOM server is:
SOMDSVR [impl_id | -a alias]
ΓòÉΓòÉΓòÉ 7.4.4.11. SOMENV ΓòÉΓòÉΓòÉ
SOMENV is a command script to set the environment variables required for SOM
programming. This command script requires that the SOMBASE environment variable
be set.
ΓòÉΓòÉΓòÉ 7.4.4.12. SOMSTARS ΓòÉΓòÉΓòÉ
SOMSTARS is a command script that you can use to convert to explicit pointers
for interface references.
ΓòÉΓòÉΓòÉ 7.4.4.13. SOMXH ΓòÉΓòÉΓòÉ
SOMXH is a command script that you can use to create the .XH header files from
the .IDL files located in the \TOOLKIT\SOM\INCLUDE subdirectory.
ΓòÉΓòÉΓòÉ 7.4.4.14. WPIDL2XH ΓòÉΓòÉΓòÉ
WPIDL2XH.CMD is a command file to emit .XH header files from Workplace Shell
.IDL files.
To re-generate the .XH headers for C++, invoke this command file on each
Workplace Shell class .IDL file from the Toolkit. It is only necessary to do
this when you upgrade to a new level of SOM. Invoking the SOMXH command script
will create .XH files for you, as the Workplace Shell classes currently only
maintain passthru sections for .H files for C. The syntax is as follows:
WPIDL2XH <inputfile>
ΓòÉΓòÉΓòÉ 7.4.5. TCP/IP Tools ΓòÉΓòÉΓòÉ
The following TCP/IP tools are available in this release of the OS/2 Warp
Toolkit:
RPCGEN
WSFORMAT
ΓòÉΓòÉΓòÉ 7.4.5.1. RPCGEN ΓòÉΓòÉΓòÉ
Use the RPCGEN command to generate C code to implement an RPC protocol. The
input to RPCGEN is a language similar to C, known as RPC language.
You normally use RPCGEN infile to generate the following four output files. For
example, if the infile is named PROTO.X, RPCGEN generates:
A header file called PROTO.H
XDR routines called PROTOX.C
Server-side stubs called PROTOS.C
Client-side stubs called PROTOC.C
RPCGEN is located in the \TOOLKIT\BIN subdirectory.
ΓòÉΓòÉΓòÉ 7.4.5.2. WSFORMAT ΓòÉΓòÉΓòÉ
WSFORMAT is the WinSock 1.1 for OS/2 trace formatter. The WSFORMAT command
accepts binary trace input from a serial port, file, or an OS/2 pipe, and
converts the input into a readable format that can be displayed on the screen
or written to a file, serial port, or OS/2 pipe.
ΓòÉΓòÉΓòÉ 7.4.6. VoiceType Tools ΓòÉΓòÉΓòÉ
The Grammar Compiler takes a plain-text grammar file (BNF) and compiles it into
a finite state grammar file (FSG). The FSG file is what the speech engine uses
at run time to determine which words and phrases are currently available for a
user to say to your application.
Documentation on the Grammar compiler can be found in the Grammar Guide. The
VoiceType Developer's Toolkit also includes the following utilities to assist
you in evaluating grammars:
FSGENUM.EXE - Enumerates the strings produced by the grammar.
FSGTEST.EXE - Determines whether input strings are accepted by the
grammar.
FSGPRINT.EXE - Displays the graph that defines the grammar.
TIDYGRAM.EXE - Used to combine the Finite State Grammer (FSG) and What
Can I Say (WCS) files, allowing grammars to be displayed in the What Can
I Say window.
The Grammar compiler and utilities are located in the TOOLKIT\SPEECH\BIN
subdirectory.
ΓòÉΓòÉΓòÉ 7.4.7. Workplace Shell Tools ΓòÉΓòÉΓòÉ
This section describes the Workplace Shell tools that help you develop
Workplace Shell programs. There are two Workplace Shell tools in this release :
OBJUTIL - Object Utility/2
WPCLSLST - Workplace Class List
ΓòÉΓòÉΓòÉ 7.4.7.1. OBJUTIL ΓòÉΓòÉΓòÉ
OBJUTIL (Object Utility/2) is a new Workplace Shell tool that provides a
facility for registering classes, and creating and modifying instances of
classes.
ΓòÉΓòÉΓòÉ 7.4.7.2. WPCLSLST ΓòÉΓòÉΓòÉ
WPCLSLST (Workplace Class List) creates a workplace object class and an
instance of a workplace object class. Workplace objects are constructed using
the SOM protocol and are instances of one of the following workplace object
classes:
Predefined These classes are defined by the system. Examples of predefined
workplace object classes are WPObject, WPFileSystem, and
WPAbstract.
Subclass These classes are derived from existing predefined workplace
object classes. They add or remove function; however, they
retain the basic behavior of that class.
Replaced These classes replace the class being subclassed. They notify
the behavior of an instance of a predefined workplace object
class without the instance being aware of the new class.
ΓòÉΓòÉΓòÉ 7.4.8. XPG4 Tools ΓòÉΓòÉΓòÉ
The OS/2 Warp Toolkit supports the development of fully internationalized,
single source, single object (SSSO) applications that can be translated into
other languages. This support is now enhanced by the addition of two new
internationalization (I18N) models: an implementation of industry standard
XPG4 I18N functions and tools and an implementation of the IBM Universal
Language Support (ULS) functions.
Internationalization of programs requires that messages be displayed in the
language of the user. This requirement is satisfied by producing versions of
the messages that are translated into all supported languages. The OS/2 C
library messaging support is based on the messaging support described in the
X/Open XPG4 specification. It consists of functions for extracting messages
from message catalog files (catopen, catgets, catclose) and the following
utilities for producing message catalog files:
GENCAT - Generate Message Catalog Utility
MKCATDEF - Preprocess Message Source File Utility
The functions for extracting message from message catalog files are found in
the C Library Reference.
ΓòÉΓòÉΓòÉ 7.4.8.1. GENCAT ΓòÉΓòÉΓòÉ
The GENCAT utility processes a message source file and produces a catalog file
usable by the C library messaging functions.
GENCAT creates the message catalog (usually *.cat) from a message source file
(usually *.msg) or standard input. You can specify any number of message source
files. A message source file is a text file that contains messages consisting
of a message number followed by the message text. See the Preprocess Message
Source File Utility (MKCATDEF) for using symbolic message identifiers in your
message source file.
ΓòÉΓòÉΓòÉ 7.4.8.2. MKCATDEF ΓòÉΓòÉΓòÉ
The Generate Message Catalog Utility (GENCAT) does not accept symbolic message
identifiers; you must use the MKCATDEF utility if you want to use symbolic
message identifiers in your message source file for use with GENCAT.
MKCATDEF processes a message source file containing symbolic identifiers and
produces the following output:
The SYMBOLNAME.H file, containing statements that equate symbolic
identifiers with the set numbers and message ID numbers assigned by
MKCATDEF. You must include the SYMBOLNAME.H file in your application
program to associate the symbolic names to the set and message numbers
assigned by MKCATDEF.
A new message source file containing message numbers instead of symbolic
message identifiers. This output is suitable for input to GENCAT.
MKCATDEF sends the new message source file, with numbers instead of symbolic
identifiers, to standard output. You can use MKCATDEF output as input to
GENCAT in the following ways:
Use MKCATDEF with a > (redirection symbol) to write the new message
source to a file. Use this file as input to GENCAT.
Pipe the MKCATDEF output file directly to GENCAT.
After running MKCATDEF, you can use symbolic names in an application to refer
to messages.
ΓòÉΓòÉΓòÉ 7.5. Online Documentation ΓòÉΓòÉΓòÉ
The Toolkit provides a variety of online documentation for your needs. The
OS/2 Warp Online Technical Library provides both guidance and reference
information. This information can help you develop applications for OS/2 Warp.
The following topics describe the different online documentation.
ΓòÉΓòÉΓòÉ 7.5.1. OS/2 Warp Online Technical Library ΓòÉΓòÉΓòÉ
The following online books are located in the \TOOLKIT\BOOK subdirectory. You
can also access them from the Desktop by opening the Toolkit folder and then
the Toolkit Information folder. The titles in the list below are the same as
the associated book icon names in the Toolkit Information folder.
ALP Programming Guide and Reference
Bidirectional Language Programming Guide
C Library Reference
Control Program Programming Guide and Reference
DMI Programmer's Guide
DPI Programmer's Guide
GPI Guide and Reference
IBM OS/2 Server Family Programming Reference
IPF Programming Guide and Reference
Multimedia Application Programming Guide
Multimedia Programming Reference
Multimedia Subsystem Programming Guide
Object REXX Programming Guide for OS/2
Open32 Programming Guide and Reference
OpenGL Programming Reference
OS/2 Debugging Handbook
OS/2 Programming Guide and Reference Addendum for OS/2 Warp Server for
e-business
Presentation Manager Programming Guide and Reference
Problem Determination Guide and Reference
RXSTRING.DOC
SOM Programming Guide
SOM Programming Reference
TCP/IP Programming Reference
Tools Reference
Unicode Programming Reference
Windows Sockets
Workplace Shell Programming Guide
Workplace Shell Programming Reference
ΓòÉΓòÉΓòÉ 7.5.1.1. How to Use Online Documents ΓòÉΓòÉΓòÉ
The online documents in the OS/2 Warp Toolkit were developed with IPF. IPF
displays information through a familiar user interface and lets you do the
following:
View a table of contents from which you can quickly gain access to a
category
View the category and select related topics from a menu
View multiple windows of related information for comparison values
Search for a topic throughout the document
Copy the contents of a topic to the system clipboard for editing with the
OS/2 System Editor, the Enhanced Editor, or any other editor with this
capability
Copy the contents of a topic to a temporary file for editing with a text
editor
When installed, the online documents are added to the Toolkit Information
folder. To access the online documents, double-click on the folder, and then
select the appropriate book. A window that has a table of contents (Contents
window) is displayed.
When the Contents window is displayed, some categories have a plus sign (+)
beside them. The plus sign indicates that additional topics are available.
Using the left mouse button, click on the plus sign to expand the category.
For more information about using the OS/2 Warp Toolkit online documents, refer
to the How to Use This Book section.
ΓòÉΓòÉΓòÉ 7.5.1.2. ALP Programming Guide and Reference ΓòÉΓòÉΓòÉ
This book describes how to install and run the ALP assembler. It provides a
complete description of the following:
Installing ALP
Using ALP
Language Reference
Processor Reference
Assembler Messages
Return Codes
ΓòÉΓòÉΓòÉ 7.5.1.3. Bidirectional Language Programming Guide ΓòÉΓòÉΓòÉ
This book provides information about the interface (API) for the Arabic and
Hebrew languages to help programmers create Arabic or Hebrew applications for
this environment.
The Bidirectional support in PM is provided in the Arabic and Hebrew language
versions of the OS/2 operating system. The support is active/configured when
the COUNTRY selection during OS/2 installation is Arabic or Hebrew in these
versions.
ΓòÉΓòÉΓòÉ 7.5.1.4. C Library Reference ΓòÉΓòÉΓòÉ
This book describes the C library functions provided as part of OS/2 Warp.
ΓòÉΓòÉΓòÉ 7.5.1.5. Control Program Programming Guide and Reference ΓòÉΓòÉΓòÉ
This book provides the C-language syntax for each of the base operating-system
application programming interfaces (APIs), including input and output
parameters, data structures, data types, return codes, and example codes.
Guidance information is also provided to assist you in developing applications
using these items. API functions (indicated by the prefix "Dos") are presented
by component, such as Error Management, Exception Management, and File System.
The API functions, within each of the components to which they apply, are
listed in alphabetic order. API functions also are available from a single
alphabetic list.
ΓòÉΓòÉΓòÉ 7.5.1.6. DMI Programmer's Guide ΓòÉΓòÉΓòÉ
This book is designed as a programmer's guide for the System Management Agent,
which provides access to system components that have been defined according to
the Desktop Management Interface (DMI) standard. These components can be
hardware or software in the system that have been defined in the Management
Information Format (MIF). Although the DMI itself is protocol-independent, the
System Management Agent can manage any DMI-enabled components in the system and
translate the MIF information into SNMP management information bases (MIBs).
ΓòÉΓòÉΓòÉ 7.5.1.7. DPI Programmer's Guide ΓòÉΓòÉΓòÉ
This book is designed as a programmer's guide for the System Management Agent,
which provides the Simple Network Management Protocol (SNMP) distributed
protocol interface (DPI). The SNMP DPI permits users to dynamically add,
delete, or replace management variables in the local Management Information
Base (MIB) without requiring you to recompile the SNMP agent.
ΓòÉΓòÉΓòÉ 7.5.1.8. GPI Guide and Reference ΓòÉΓòÉΓòÉ
This book describes the concepts associated with graphical output--
presentation spaces, device contexts, graphic primitives, fonts--and how to
prepare graphical output for display and printing. It provides the C-language
syntax for all the graphical programming interface (GPI), including input and
output parameters, data structures, data types, return codes, and example
codes. Guidance information is also provided to assist you in developing
applications using these items. GPI functions (indicated by the prefix "Gpi")
are listed in alphabetic order.
ΓòÉΓòÉΓòÉ 7.5.1.9. IPF Programming Guide and Reference ΓòÉΓòÉΓòÉ
This book describes the concepts--help windows, hypertext linking, author-
controlled viewports, dynamic data formatting--and the functions used for
implementing help in OS/2 applications. It describes how to create online help
and information. It also contains an alphabetic list of IPF tags, symbols, and
control words. The IPFC error messages, window functions, dynamic data
formatting functions, and help manager messages and functions are included.
ΓòÉΓòÉΓòÉ 7.5.1.10. IBM OS/2 Server Family Programming Reference ΓòÉΓòÉΓòÉ
This reference provides a description of the application programming interfaces
(APIs) provided by the IBM Operating System/2 for OS/2 Warp Servers, LAN
Servers, and the Directory and Security Server (DSS). These functions provide
the functional interface for server and client application development. The
OS/2 operating system referred to in this book is OS/2 Versions 2.1 through
OS/2 Warp 4 (with the applicable CSDs and ServicePaks applied).
This book also provides the OS/2 Warp LAN Requester API. These functions are
32-bit and are generally consistent with the Net32xxx and Dos32xxx LAN
functions that are included with LAN Server 4.0. DOS refers to DOS versions
3.3, 5.0, 6.x, or 7.0.
This book is written as a reference for the application or system programmer
who is developing Directory and Security Server (DSS) software applications or
OS/2 LAN Server software for a LAN Server, LAN Requester, OS/2 Warp Connect LAN
Requester (client only), or DOS LAN Services (DLS) workstation. Information in
this book applies to the following servers and clients:
LAN Server 3.0
LAN Server 4.0
OS/2 Warp Server
OS/2 Warp Connect
Directory and Security Server
This book includes DLS programming information that is not supported by
Directory and Security Server.
The reader should be familiar with programming the OS/2 base operating system
or an equivalent multitasking operating system and should understand the C
programming language.
ΓòÉΓòÉΓòÉ 7.5.1.11. Multimedia Application Programming Guide ΓòÉΓòÉΓòÉ
This book describes the concepts associated with managing audio and video data
and hardware using an extendable architecture that includes logical media
devices (amplifier-mixer, waveform audio, MIDI sequencer, CD-audio, CD-XA,
digital video, and videodisc) and I/O procedures for supporting various file
formats.
ΓòÉΓòÉΓòÉ 7.5.1.12. Multimedia Programming Reference ΓòÉΓòÉΓòÉ
This book describes the media control interface, PM graphic push buttons,
secondary windows functions, multimedia I/O services, direct interface video
extensions (DIVE), and subsystem services for synchronization and streaming.
ΓòÉΓòÉΓòÉ 7.5.1.13. Multimedia Subsystem Programming Guide ΓòÉΓòÉΓòÉ
This book describes the subsystem components--media control driver, stream
handler, and I/O procedure--that support a multimedia device.
ΓòÉΓòÉΓòÉ 7.5.1.14. Object REXX Programming Guide for OS/2 ΓòÉΓòÉΓòÉ
The Object REXX Programming Guide for OS/2 describes the Object-based
REstructured eXtended eXecutor, or Object REXX programming language. (When not
comparing it to its traditional predecessor, it is just referred to as REXX.)
REXX is an integral part of the OS/2 operating system.
This information is aimed at developers familiar with OS/2 who want to use REXX
to do object-oriented programming--or some mix of traditional and
object-oriented programming--with the shortest learning curve possible.
This information assumes you are already familiar with the techniques of
traditional structured programming and uses them as a springboard for
explaining REXX and, in particular, Object REXX. This "no frills" approach is
designed to help experienced programmers get involved quickly with the REXX
language, exploit its virtues, and become productive fast.
ΓòÉΓòÉΓòÉ 7.5.1.15. Open32 Programming Guide and Reference ΓòÉΓòÉΓòÉ
The Open32 Programming Guide and Reference provides information on the
following topics:
What Open32 is and how it can help you to either:
- Migrate Windows code to OS/2 code
- Write common source code for OS/2 and Windows
How to use the SMART tool to analyze Windows code and see how much effort
is involved to migrate it to OS/2 code
Differences in behavior between some Open32 functions and their Windows
counterparts
The functions supported by Open32
As an enhancement for Open32, the OS/2 Resource Compiler (RC) now supports
string IDs for resources in addition to numbers. You can use either SMART or
the Resource Compiler to convert resources. If you use the Resource Compiler,
you do not need to include the hhh file with your code. OS/2 supports string
IDs that contain quotation marks. See the discussion of the RESOURCE statement
in the Tools Reference for more information.
ΓòÉΓòÉΓòÉ 7.5.1.16. OpenGL Programming Reference ΓòÉΓòÉΓòÉ
This book provides an overview of OpenGL function and describes in detail the
window and input interface that integrates OpenGL with the Presentation
Manager. Application developers can use this interface to:
Create and prepare an OpenGL context for rendering
Swap a window's front and back buffers
Select a color palette for a color index context
Integrate GPI and OpenGL rendering and fonts
The interface provides much the same functionality as the OpenGL window
interfaces for X Windows and Microsoft systems.
ΓòÉΓòÉΓòÉ 7.5.1.17. OS/2 Debugging Handbook ΓòÉΓòÉΓòÉ
This book explains problem debugging in an OS/2 environment. The book is
written for service personnel, system programmers, and software developers. It
provides information about the internal workings of the OS/2 operating system
and describes the use of system debugging tools.
ΓòÉΓòÉΓòÉ 7.5.1.18. OS/2 Programming Guide and Reference Addendum for OS/2 Warp Server for e-business ΓòÉΓòÉΓòÉ
This book provides information about APIs that are new to OS/2 Warp Server for
e-business. This information includes syntax, input and output parameters,
data structures, data types, return codes, and sample code.
ΓòÉΓòÉΓòÉ 7.5.1.19. Presentation Manager Programming Guide and Reference ΓòÉΓòÉΓòÉ
This book provides the C-language syntax for the base operating-system
application programming interface (API), including input and output parameters,
data structures, data types, return codes, and example codes. API function
prefixes include Drg (dragdrop), Ddf (dynamic data format), Prf (profile), Spl
(spooler), and Win (window). Also included are application hooks and PM
messages.
ΓòÉΓòÉΓòÉ 7.5.1.20. Problem Determination Guide and Reference ΓòÉΓòÉΓòÉ
This book provides programmers with guide and reference information for
collecting and managing problem determination data.
This book first provides conceptual and introductory information about OS/2
Warp's First Failure Support Technology (FFST). This sophisticated and powerful
tool requires thoughtful planning and code instrumentation. These topics
present planning, setup, and examples that are used for collecting and managing
problem determination data.
Separate sections are devoted to understanding the aids that are provided for
tracking, collecting, storing, and formatting problem determination data, such
as traces, dumps, and error logs.
After reading this book you should understand the benefits of FFST and know how
to instrument your code. This understanding enables you to take advantage of
the technology and tools that are associated with problem determination data.
You should also know how to use the API, trace, error logging, and dump
functions. These functions retrieve, format, and analyze problem determination
data.
This book assumes that you have the OS/2 Toolkit installed and you are
developing application programs.
ΓòÉΓòÉΓòÉ 7.5.1.21. RXSTRING.DOC ΓòÉΓòÉΓòÉ
RXSTRING.DOC is an ASCII text file that documents the utility library that is
included with the OS/2 Warp Toolkit. The utilities enable C programmers to
effectively handle REXX string variables.
ΓòÉΓòÉΓòÉ 7.5.1.22. SOM Programmers Reference ΓòÉΓòÉΓòÉ
This book is a complete reference for each of the classes and methods used for
the object-oriented programming environment. Also included are System Object
Model (SOM) C-language and C++ bindings, the Object Interface Definition
Language syntax, and the SOM compiler command syntax.
ΓòÉΓòÉΓòÉ 7.5.1.23. SOM User's Guide ΓòÉΓòÉΓòÉ
This book explains how programmers using C, C++, and other languages can:
Implement class libraries that exploit the SOM library-packaging
technology
Develop client programs that use class libraries that were built using
SOM
Develop applications that use the frameworks supplied with the SOMobjects
Developer Toolkit, class libraries that facilitate development of
object-oriented applications.
ΓòÉΓòÉΓòÉ 7.5.1.24. TCP/IP Programming Reference ΓòÉΓòÉΓòÉ
This book describes the routines for application programming in the TCP/IP for
OS/2 Warp environment on a workstation.
ΓòÉΓòÉΓòÉ 7.5.1.25. Tools Reference ΓòÉΓòÉΓòÉ
This book describes the tools that are included in the IBM Developer's Toolkit
for OS/2 Warp.
ΓòÉΓòÉΓòÉ 7.5.1.26. Unicode Programming Reference ΓòÉΓòÉΓòÉ
The Unicode Programming Reference documents the Universal Language Support
(ULS) and Unicode conversion functions. OS/2 Warp Version 4 or later provides a
dynamically linked C-language run-time library that supports multithreaded and
Unicode-enabled programs. For information on this library, see the C Library
Reference.
ΓòÉΓòÉΓòÉ 7.5.1.27. Windows Sockets ΓòÉΓòÉΓòÉ
The Windows Sockets specification defines a network programming interface for
Microsoft Windows, which is based on the "socket" paradigm popularized in the
Berkeley Software Distribution (BSD) from the University of California at
Berkeley. It encompasses both familiar Berkeley socket style routines and a
set of Windows-specific extensions designed to help the programmer to take
advantage of the message-driven nature of Windows.
The Windows Sockets Specification is intended to provide a single API to which
application developers can program and multiple network software vendors can
conform. Furthermore, in the context of a particular version of Microsoft
Windows, it defines a binary interface (ABI) such that an application written
to the Windows Sockets API can work with a conformant protocol implementation
from any network software vendor. This specification thus defines the library
calls and associated semantics to which an application developer can program
and which a network software vendor can implement.
Network software which conforms to this Windows Sockets specification will be
considered "Windows Sockets Compliant." Suppliers of interfaces that are
"Windows Sockets Compliant" are referred to as "Windows Sockets Suppliers." To
be Windows Sockets Compliant, a vendor must implement 100% of this Windows
Sockets specification.
Applications that are capable of operating with any "Windows Sockets Compliant"
protocol implementation are considered as having a "Windows Sockets Interface"
and are referred to as "Windows Sockets Applications."
This version of the Windows Sockets specification defines and documents the use
of the API in conjunction with the Internet Protocol Suite (IPS, generally
referred to as TCP/IP). Specifically, all Windows Sockets implementations
support both stream (TCP) and datagram (UDP) sockets.
While the use of this API with alternative protocol stacks is not precluded
(and is expected to be the subject of future revisions of the specification),
such usage is beyond the scope of this version of the specification.
ΓòÉΓòÉΓòÉ 7.5.1.28. Workplace Shell Programming Guide ΓòÉΓòÉΓòÉ
This book describes the concepts associated with object-oriented programming
for the OS/2 operating system--SOM, Workplace Shell classes and methods--and
how to create object-oriented applications for the OS/2 Desktop.
ΓòÉΓòÉΓòÉ 7.5.1.29. Workplace Shell Programming Reference ΓòÉΓòÉΓòÉ
This book provides the detailed descriptions of the Workplace Shell
object-oriented programming interface.
ΓòÉΓòÉΓòÉ 7.5.2. VoiceType Developer's Toolkit Documentation ΓòÉΓòÉΓòÉ
Online documentation for the VoiceType Developer's Toolkit is located in the
\TOOLKIT\SPEECH\BOOK subdirectory. You can also access the information from the
Desktop by opening the Toolkit folder, and then the VoiceType Developer's
Toolkit folder.
Note: The VoiceType Developer's Toolkit online documentation is in HTML
format. You need a Web browser to view it.
The following information is provided:
Application Programming Interface (API) Reference
Grammar Guide
ΓòÉΓòÉΓòÉ 7.5.2.1. API Reference ΓòÉΓòÉΓòÉ
This reference provides a description of the Speech Manager (Sm) application
programming interface. Two types of functions are covered--function calls to
the speech engine and data access functions, which are functions that retrieve
data from reply messages.
ΓòÉΓòÉΓòÉ 7.5.2.2. Grammar Guide ΓòÉΓòÉΓòÉ
Grammars can be used by speech-enabled applications to specify what phrases to
accept. Grammars can also be used to enhance Voice Manager navigation of
applications that are not speech-enabled. The Grammar Guide describes the basic
steps for writing an application grammar. It also contains information that
explains how to use the grammar utilities that are provided with the VoiceType
Developer's Toolkit.
ΓòÉΓòÉΓòÉ 8. Programming Considerations ΓòÉΓòÉΓòÉ
Programming considerations apply for the following areas of the OS/2 Warp
operating system:
General Considerations
Presentation Manager
SOM
IBM VisualAge C++ for OS/2 Compiler
Workplace Shell
ΓòÉΓòÉΓòÉ 8.1. General Considerations ΓòÉΓòÉΓòÉ
Included in this section are important items that can affect your future
development efforts when using the IBM Developer's Toolkit for OS/2 Warp.
Compiling with IBM C/2
Compiling with IBM VisualAge C++ for OS/2
Installing IBM VisualAge C++ for OS/2
Known Limitations for the Container Part
Known Limitations for DIVE
ΓòÉΓòÉΓòÉ 8.1.1. Compiling with IBM C/2 ΓòÉΓòÉΓòÉ
The IBM Developer's Toolkit for OS/2 Warp Version 4 and later versions are not
intended to be used with the IBM C/2, Version 1.1 compiler. If you choose to
use that compiler, you should use version 1.3 of the Toolkit.
The OS/2 Warp Toolkit is intended to be used with the IBM VisualAge C++
compiler.
ΓòÉΓòÉΓòÉ 8.1.2. Compiling with IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
The latest version of the C Set ++ compiler (now called VisualAge C++) has been
released. VisualAge C++ includes its own version of the OS/2 Warp Toolkit,
which includes updated sample makefiles. Changes to the sample makefiles relate
to the new linker (ILINK) and to the new library (CPPOM30.LIB).
With this version of the OS/2 Warp Toolkit, the same sample makefile changes
have been made so that you can use VisualAge C++.
You can compile the samples included with the OS/2 Warp Toolkit with C Set ++
(using LINK386) by changing any reference to CPPOM30.LIB to:
DDE4MBS.LIB
and changing any reference to ILINK to:
LINK386
Note: The /nofree option must be removed from the LINK386 statement.
ΓòÉΓòÉΓòÉ 8.1.3. Installing IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
Installing your compiler first and the OS/2 Warp Toolkit last prevents
unexpected results due to environment variable changes (automatic updates to
CONFIG.SYS).
To avoid a downlevel SOM Runtime installed by the VisualAge C++ 3.0 compiler,
follow these steps for installation:
1. Start the installation program for VisualAge C++ 3.0.
2. Deselect the OS/2 Warp Toolkit entries in the installation screen and
proceed with the installation.
3. After completing the installation of VisualAge C++ but before restarting
the system, edit CONFIG.SYS and modify the LIBPATH statement by moving
x:\ IBMCPP\DLL after y:\OS2\DLL, where x is the drive where the VisualAge
C++ compiler is installed and y is the drive where the OS/2 Warp
operating system files are installed. This prevents the SOM Runtime
installed by VisualAge C++ from overriding the SOM Runtime shipped with
OS/2 Warp Version 4 or later.
4. Save the modified CONFIG.SYS and restart your system.
5. Install the OS/2 Toolkit and restart your system.
ΓòÉΓòÉΓòÉ 8.1.4. Known Limitations for the Container Part ΓòÉΓòÉΓòÉ
The Container part has the following known limitations. Note that the behavior
described below will be exhibited by all samples that subclass from the
Container part.
A SYS3175 error occurs when you select Open As->Details from the
Container part's View menu. This error will close the document.
A SYS3175 error occurs when saving a document containing a selected
Container part inside a root Container part. It will occur if the
selected part subclasses from the Container part. This error will not
occur if the selected part, for example, is the Cookbook part.
The Container part's Show As menu selection from the View menu does not
work correctly. This selection will incorrectly change the view type of
selected parts, when it should only change the activated part's view
type. The correct way to change the view type of selected parts would be
to select Show selection as from the Edit menu.
The Move selection from the Edit menu is incorrectly enabled for an
activated part. The Move selection, like all Edit menu selections, are
for selected parts only.
A part that subclasses from the Container part may not have its intrinsic
content clipped correctly to the embedded parts. The Container part
correctly handles the clipping of its embedded parts, but there is no way
for a part that subclasses from the Container part to tell the Container
part how to clip the embedded parts to its own content. Generally, the
subclass part's intrinsic content will write over the embedded parts.
ΓòÉΓòÉΓòÉ 8.1.5. Known Limitations for DIVE ΓòÉΓòÉΓòÉ
DIVE will not run in direct mode on some systems if the video card requires
bank switching. To determine if your video card requires bank switching, select
Query Caps from the Options menu of the DIVE sample. If the Screen access
requires bank switch field is set to YES, setting a lower Desktop resolution in
the System Setup might fix this.
DIVE might not work on some systems when the Desktop is set to 16 million
colors. If your system is set to 16 million colors and DIVE does not work
properly, try setting the Desktop to fewer colors in the System Setup.
ΓòÉΓòÉΓòÉ 8.1.6. Replacing DLGEDIT ΓòÉΓòÉΓòÉ
IBM supports the version of the Dialog Editor (DLGEDIT) in this release of the
OS/2 Warp Toolkit.
ΓòÉΓòÉΓòÉ 8.2. Presentation Manager Considerations ΓòÉΓòÉΓòÉ
Making modifications to Microsoft Windows programs to enable dynamic data
exchange (DDE) communications with PM programs helps facilitate a gradual
migration of applications to PM. Not all data formats are automatically
converted when using DDE between Windows programs and PM programs (DDE set
public).
The following formats are converted automatically by the OS/2 operating system:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
Γöé PM Application Γöé Windows Application Γöé
Γöé Data Format Γöé Interpretation Γöé
ΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöé
Γöé PM bitmap Γöé Windows DIB Γöé
Γöé PM private Γöé Windows private Γöé
Γöé Text Γöé Text (codepage 819) Γöé
Γöé---------------------------------------------Γöé
Γöé Windows Application Γöé PM Application Γöé
Γöé Data Format Γöé Interpretation Γöé
Γö£ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöñ
Γöé Text (codepage 819) Γöé Text Γöé
Γöé Windows DIB Γöé PM Bitmap Γöé
Γöé Windows private Γöé PM Private Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Note: Code page translation (Windows 819 to/from current PM code page) is
performed for topic name in all cases.
When data conversion is not automatically performed, programs can still
communicate using DDE when the two programs perform the data conversion and
pass private data formats.
ΓòÉΓòÉΓòÉ 8.3. SOM Considerations ΓòÉΓòÉΓòÉ
This version of the OS/2 Warp Toolkit contains a subset of the SOMobjects
Developer Toolkit. The following SOM programming considerations are briefly
described:
Distributed SOM
SNGLICLS.HH
SOM 1.0 OIDL
SOM Bindings
SOM Coding Styles
SOM Compiler
SOM DLLs
ΓòÉΓòÉΓòÉ 8.3.1. Distributed SOM (DSOM) ΓòÉΓòÉΓòÉ
New features, known limitations, and restrictions pertain to Distributed SOM
(DSOM). They are briefly described as follows:
DSOM now provides a PM version of the REGIMPL tool for registering
servers in the implementation repository. It is called PREGIMPL and is
similar in functionality to REGIMPL. To invoke the tool, type PREGIMPL on
a command line. Remember to select File Save before exiting to save any
changes you make.
You are now able to control the number of request threads created per
server. The environment variable SOMDNUMTHREADS is used to indicate the
maximum size of the thread pool. If this environment variable is not set,
a separate thread will be created for each request.
The OUT_LIST_MEMORY, IN_COPY_VALUE, and DEPENDENT_LIST flags, used with
the dynamic invocation interface, are not supported.
Concurrent updates to the implementation repository are currently not
properly serialized and can conflict.
The is_nil method of SOMDObject has been changed from a true method to a
procedure so that is_nil can be safely invoked on a NULL object pointer.
As a result, the syntax for invoking is_nil from C++ client programs has
changed. The new syntax is:
obj->is_nil(obj,env);
Rather than:
obj->is_nil(env);
where:
obj Is an object pointer of type SOMDObject.
env Is of type Environment.
ΓòÉΓòÉΓòÉ 8.3.2. SNGLICLS.HH ΓòÉΓòÉΓòÉ
The Direct-to-SOM version of the SNGLICLS header file cannot be emitted with
the version of the SOM Compiler included with this Toolkit. Therefore, this
file (SNGLICLS.HH) is provided as part of the SOM Direct-to-SOM headers.
ΓòÉΓòÉΓòÉ 8.3.3. SOM 1.0 OIDL Users ΓòÉΓòÉΓòÉ
If you need to recompile an OIDL class that overrides somDumpSelf or
somDumpSelfInt, change the data type of the level parameter in the function
definition in your C source program from INT to LONG. For example, if your
original class source program has a somDumpSelfInt override procedure similar
to:
SOM_Scope void SOMLINK somDumpSelfInt(
<className> *somSelf, INT level)
{
...
}
Change it to read:
SOM_Scope void SOMLINK somDumpSelfInt(
<className> *somSelf, LONG level)
{
...
}
Because both INT and LONG data types require 4 bytes on OS/2, this change does
not affect the binary interface of your class.
ΓòÉΓòÉΓòÉ 8.3.4. SOM Bindings ΓòÉΓòÉΓòÉ
The XH and H files included with this OS/2 Warp Toolkit work only with the IDL
files included with this Toolkit. You will need to generate new SOM bindings if
you install a new version of SOM. This means that the XH and H files will need
to be re-emitted if new versions of the IDL files are made available. There are
two steps that you need to take.
If you install version 'Y' of SOM on top of version 'X', you will need to
generate SOM bindings for version 'Y'. The version 'X' SOM bindings are not
guaranteed to be compatible with version 'Y'.
Use the SOMSTARS.CMD file to generate the SOMSTARS version of the
bindings.
Use SOMCORBA.CMD to generate the SOMCORBA version of the bindings. This
upgrades your SOM bindings.
The command file WPIDL2XH.CMD is provided to upgrade Workplace Shell bindings
for developers who will upgrade their SOMobjects Developer Toolkit in the
future. This command file emits the .XH header files from the Workplace Shell
.IDL files. The file should be invoked upon each of the .IDL files from the
OS/2 Warp Toolkit to regenerate the headers for C++. This is only necessary
when you upgrade to a new level of the SOMobjects Developer Toolkit. Invoking
the SOM compiler's .XH emitter on the Workplace Shell .IDL files do not emit
.XH files for you, because the Workplace Shell classes currently only maintain
passthru sections for .H files for C.
ΓòÉΓòÉΓòÉ 8.3.5. SOM Coding Styles ΓòÉΓòÉΓòÉ
There are two possible forms of C bindings for SOM programming:
SOMCORBA The strict CORBA-compliant form in which pointer references
('*'s) are NOT exposed in object references.
SOMSTARS The OIDL-compatible C++ form in which pointer references ('*'s)
are visible in object references.
The SOMSTARS form is more appropriate if you plan to move your class
implementations from C to C++ at some future point. This choice will determine
how object references will appear in all of your C programs. For example, to
declare a reference to an instance of class Foo, you would code either:
Foo afoo; /* Strict CORBA compliant form */
or
Foo *afoo; /* C++ migration or OIDL-compatible form */
If you later decide to switch from one SOM coding style to the other, you will
have to convert any C code that you have already written in one style to the
other style.
The Workplace Shell uses the SOMSTARS version of the SOM header files.
Therefore, the OS/2 Warp Toolkit installs the SOMSTARS version of the header
files.
The Workplace Shell interface definition language (IDL) files (WP*.IDL) are
the counterparts for the documented Workplace Shell classes' SC files provided
with the OS/2 2.1 Toolkit. The WP*.H and WP*.XH files emitted from the
Workplace Shell's IDL files by the SOM compiler are also provided.
The OS/2 makefiles for the Workplace Shell OS/2 Warp Toolkit samples are
written assuming the SOMSTARS style of coding. The C samples provided with the
SOMobjects Developer Toolkit use the SOMCORBA style of coding (these samples
are not part of the IBM Developer's Toolkit for OS/2 Warp).
ΓòÉΓòÉΓòÉ 8.3.6. SOM Compiler ΓòÉΓòÉΓòÉ
New features, known limitations, and restrictions pertain to the SOM compiler.
There are briefly described as follows:
Mutually recursive IDL struct and union are not currently supported. The
following is an example of unsupported mutual recursion:
struct X;
struct Y
{
sequence<X> indirectSelf;
};
struct X
{
sequence<Y> indirectSelf;
};
The C bindings do not permit the use of multiple methods with the same
name that also take an argument of data type VA_LIST within the same
module. For example, the following legal IDL will result in incorrect C
usage bindings:
module X
{
interface Y
{
void Foo (in LONG f, in VA_LIST ap);
};
interface Z
{
void Foo (in LONG f, in VA_LIST ap);
};
};
The SOM C++ language bindings are built assuming use of the VisualAge C++
for OS/2 compiler, but other C++ compilers should be able to use these
bindings as well. For example, to use BCOS2 (the Borland C++ compiler for
OS/2), use -DSOMLINK=_syscall on the compile line, and make sure that the
SOMobjects' include directory is consulted before BCOS2/include (because
BCOS2/include contains older SOM.H include files).
If the SOM compiler is interrupted by the user (using Ctrl+C, for
example), it sometimes leaves a temporary file with a .CTN extension in
the temporary directory specified by the SMTMP environmental variable.
These temporary files should be removed periodically.
When direct references to SOMFOREIGN types are made in an IDL struct or
union, the C or C++ language bindings are generated incorrectly. To refer
to a SOMFOREIGN type (for example, "somId") in a struct or union , it is
necessary to supply a secondary typedef for "somId." For example:
#include <somobj.idl>
struct S1
{
somId badId; /* Generates incorrect */
}; /* C/C++ bindings */
#include <somobj.idl>
typedef somId somId2;
struct S1
{
somId2 badId; /* OK */
};
ΓòÉΓòÉΓòÉ 8.3.7. SOM Dynamic Link Libraries (DLLs) ΓòÉΓòÉΓòÉ
When SOMobjects 2.0 (not the version included with this OS/2 Warp Toolkit) is
installed on OS/2 Warp Version 3, the LIBPATH, PATH, and DPATH environment
variables in CONFIG.SYS are changed to place the SOMobjects directories before
the operating system directories in the search order for DLLs, EXEs, and data
files. This causes the Workplace Shell to encounter an unrecoverable error the
next time the system is restarted because it requires the SOM DLLs that are
contained in the \OS2\DLL subdirectory.
In order to allow SOMobjects 2.0 Workstation applications to run successfully,
you must edit CONFIG.SYS and change the LIBPATH, PATH, and DPATH statements
before restarting the system. These statements must be changed to place the
operating system directories before the SOMobjects directories.
Note: This only applies to SOMobjects Workstation applications, not Workgroup
applications.
The same problem will occur for any application that includes SOMobjects 2.0
DLLs if the application places its DLL directory first in the LIBPATH. Again,
the workaround is to assure that the \OS2\DLL subdirectory is before any other
directory that contains earlier versions of the SOM DLLs. Any changes made to
the PATH and DPATH environment variables by the application installation must
also be reversed.
ΓòÉΓòÉΓòÉ 8.4. Workplace Shell Considerations ΓòÉΓòÉΓòÉ
When including an OBJECTID=<....> keyname=value pair in a setup string, you
must specify it at the end of the setup string.
ΓòÉΓòÉΓòÉ 9. Toolkit Support ΓòÉΓòÉΓòÉ
The OS/2 Developer's Toolkit provides programming tools, samples and
information to support end-user development of OS/2 applications. We will make
every effort to respond to support requests, but the Toolkit is provided on an
as-is basis, and there is no guarantee of formal support.
Informal electronic support for the IBM Developer's Toolkit is provided through
the Internet and the OS/2 BBS. Internet users may report problems by sending
mail to devcon@us.ibm.com. Users may obtain informal support or exchange ideas
or comments by accessing the DEVCON CFORUM on the OS/2 BBS under Talklink (a
feature under the IBMLink Commercial Services). For TalkLink access, U.S.
customers can call 1-800-547-1283; other customers can contact their IBM
Marketing Representatives.
ΓòÉΓòÉΓòÉ 10. Notices ΓòÉΓòÉΓòÉ
(C) Copyright International Business Machines Corporation 1997, 1999. All
rights reserved.
Note to U.S. Government Users Restricted Rights --Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this
document in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or
imply that only that IBM product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any
IBM intellectual property right may be used instead. However, it is the user's
responsibility to evaluate and verify the operation of any non-IBM product,
program, or service.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing,
to:
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS information "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied
warranties in certain transactions, therefore, this statement may not apply to
you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the information. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
information at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
Department LZKS
11400 Burnet Road
Austin, TX 78758
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement between
us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments
may vary significantly. Some measurements may have been made on
development-level systems and there is no guarantee that these measurements
will be the same on generally available systems. Furthermore, some measurement
may have been estimated through extrapolation. Actual results may vary. Users
of this document should verify the applicable data for their specific
environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available
sources. IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change
or withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are
subject to change without notice. Dealer prices may vary.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrates programming techniques on various operating platforms. You may
copy, modify, and distribute these sample programs in any form without payment
to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for
the operating platform for which the sample programs are written.
These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function
of these programs. You may copy, modify, and distribute these sample programs
in any form without payment to IBM for the purposes of developing, using,
marketing, or distributing application programs conforming to IBM's application
programming interfaces.
ΓòÉΓòÉΓòÉ 10.1. Trademarks ΓòÉΓòÉΓòÉ
The following terms are trademarks of the IBM Corporation in the United States
or other countries or both:
AVC Presentation Manager
C/2 SOMobjects
Common User Access Ultimotion
C Set ++ VisualAge
CUA WIN-OS2
IBM VoiceType
Workplace Shell OS/2
Microsoft, Windows, and the Windows 95 logo are trademarks or registered
trademarks of Microsoft Corporation.
UNIX is a registered trademark in the United States and other countries
licensed exclusively through X/Open Company Limited.
Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.
ΓòÉΓòÉΓòÉ 11. Toolkit Licensing Information ΓòÉΓòÉΓòÉ
The IBM OS/2 Developer's Toolkit includes header files, include files, and
audio files. These files have extensions of .H, .HH, .XH, .INC, and .WAV. The
Toolkit also contain programming tutorials illustrating OS/2 and multimedia
programming techniques. Both executable and source files for these tutorials
are included. You may copy and distribute the above header files, include
files, audio files, and programming turorials in any form without payment to
IBM, for the sole purposes of developing, using, marketing, and distributing
application programs written to the OS/2 and MMPM/2 application programming
interface. Each copy or any portion of these programming tutorials or any
derivative work thereof, which are distributed to others, must include a
copyright notice as follows: "(C) Copyright (your company name) (year). All
Rights Reserved." The IBM Developer's Toolkit for OS/2 Warp includes a dynamic
link library, SMAPI.DLL, for the Voice Type application programming interfaces.
You may copy and distribute this library in object code form only, as part of
your OS/2 software application program, without payment to IBM, provided that
(1) you agree to indemnify, hold harmless and defend IBM against any claims,
lawsuits and liabilities arising out of the use and distribution of your
applications and (2) you distribute your applications pursuant to a license
that prohibits the user from copying (except for backup purposes) or
distributing this library.