OS/2 Professional Developers Kit 1992 November

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / os2tk20 / c / samples / samples.ls_ / SAMPLES.LST

Wrap

File List | 1992-08-28 | 21.0 KB | 502 lines

SAMPLE PROGRAMS --------------- This file describes the sample programs available with the Toolkit. Most sample programs are written in C language and demonstrate the use of the API functions of the control program (base operating system) and the Presentation Manager interface. In addition to C language, there are assembler language and REXX sample programs. Each sample program serves as a template that can be easily modified for your own purposes. All C language samples contain the overhead routines necessary to create a Presentation Manager 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 infor- mation by presenting it in an alternate form. STARTING A SAMPLE PROGRAM _________________________ FROM THE DESKTOP When installed, most sample programs appear in the Sample Programs folder. To start a sample program, select the folder, then select the appropriate sample program. FROM AN OS/2 COMMAND PROMPT To start a sample program from an OS/2 command prompt, type the name of the executable file and press Enter. If you have edited source code of a sample program and want to recompile, link, and run the files; change to the SAMPLES subdirectory and type: NMAKE /f samples.mak [samplename] where: SAMPLENAME is the name of the sample program you want to build. To build all of the programs, set samplename to ALL (or omit it). Your output is the executable file. For information about the NMAKE utility, refer to the online Tools Reference. FROM WORKFRAME/2 Perhaps you have installed both the Toolkit and the WorkFrame/2 product; if so, you can start a sample program (assuming you have set up a project for the sample program) from the WorkFrame/2 Project Control window. Select ACTIONS from the menu bar, then select RUN; a project window displays the sample program. You also can edit, compile, link, and run a sample program from the WorkFrame/2. ANIMALS -- THE BASIC SOM SAMPLE PROGRAM _______________________________________ ANIMALS demonstrates a system object model (SOM) program in an object- oriented programming context. ANIMALS also demonstrates basic concepts of subclassing and inheritance, polymorphism, encapsulation, and constructors using the analogy of a zoological taxonomy. This sample program consists of 6 classes containing 14 methods. The AnimalFactory and DogFactory metaclass supply constructor methods. BigDog and LittleDog inherit the metaclass of their parent, DogFactory, and their constructors can be used to create BigDogs, LittleDogs, and generic Dogs. CLIPBRD -- THE CLIPBOARD SAMPLE _______________________________ CLIPBRD demonstrates how to provide a Presentation Manager interface to the clipboard. Initially, CLIPBRD displays a standard window with a bit map. The user can cut and paste data in this window, using the system clipboard as an intermediate storage area. CLOCK -- THE TIMER SERVICES SAMPLE __________________________________ CLOCK 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 Presentation Manager thread repeatedly sets a one-second window timer that updates the current time. CLOCK features an audible and visual alarm that the user can set. When the time expires, the sample makes use of the DOS timer services and notifies the user by sounding an alarm. DIALOG -- THE DIALOG BOX SAMPLE _______________________________ 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 an entry field, push buttons, and message boxes. DLLAPI -- THE DYNAMIC LINK LIBRARY SAMPLE _________________________________________ 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 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. DRAGDROP -- THE DIRECT MANIPULATION SAMPLE __________________________________________ DRAGDROP demonstrates how to move files between directories with the dragging techniques of direct manipulation. This sample program creates a list box that contains a scrollable list of the current directory. To change the current directory to one lower in the directory tree, the user selects the directory name from the list and presses Enter. To change the current direc- tory to one higher in the directory tree, the user selects FILE from the menu bar, then OPEN. The SELECT SUBDIRECTORY window appears. The user types the name of the subdirectory, then selects OK. The sample program must be started twice so there are two running instances of the sample. Then, using a mouse, the user: o Changes the directory file list in the first sample as previously men- tioned o Selects a file name from the second sample o Drags the file name (with mouse button 2) to the directory in the first sample o Drops the file name in the directory of the first sample. The file is now moved into the chosen directory. EAS -- THE EXTENDED ATTRIBUTES EDITOR SAMPLE ____________________________________________ EAS demonstrates a multithreaded application that retrieves, modifies, or sorts files by their extended attribute value. Included in this sample program are Presentation Manager procedures for dialog boxes and a standard client window. EAS lets the user select an extended attribute file name from a list, or enter a new name in an entry field. The user can select the extended attribute type from a table. GRAPHIC -- THE GRAPHICS SAMPLE ______________________________ GRAPHIC demonstrates how to use default viewing transformation functions of the Presentation Manager. It also demonstrates how to use an asynchronous drawing thread. The sample program lets the user load metafiles using a dialog box. The dialog box has a help push button. When the help push button is activated, it provides instructions on loading a metafile from another directory. The user also can print a metafile or graphic circle. HANOI -- THE MULTITHREADED PRESENTATION MANAGER SAMPLE ______________________________________________________ HANOI demonstrates a multithreaded application with the familiar "towers of Hanoi" puzzle. When the sample program is started the user sees 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 Presentation Manager interface and lets the user start or stop the Hanoi routine. It also lets the user reset the number of working disks. The second thread is created when START is selected from the Options menu. This thread starts the recursive execution of the Hanoi algo- rithm, runs in the background, and moves and paints the disks. HELLO -- THE STANDARD WINDOW SAMPLE ___________________________________ HELLO demonstrates how to create and display a standard window. This sample program also demonstrates how to use resources defined in a resource script file. Initially, HELLO displays a standard window with the text "Hello." The menu bar contains the OPTIONS choice. If the choice is selected, the resulting menu contains three choices, each of which paint a different text string in the window. IMAGE -- THE PRESENTATION MANAGER PORTING SAMPLE ________________________________________________ IMAGE demonstrates how to migrate from an existing OS/2 16-bit application to a 32-bit application. This program also demonstrates how to display an image using the GpiImage function. The image data comes from a file the user selects using the standard File Open dialog procedure. IPF -- THE INFORMATION PRESENTATION FACILITY SAMPLE ___________________________________________________ IPF demonstrates how to use the Information Presentation Facility to create an online document and an application-controlled window that displays ani- mation. The online document also features customized windows that display text and graphics. Two files are associated with this sample: o The IPF online document (.INF) file o The OS/2 dynamic link library (.DLL) file. The .INF file is the compiled IPF tag 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. The .DLL file is the compiled C-language source for the communication object that is called when the .INF file is read during run time. The bit map files used for the animation are also provided. JIGSAW -- THE RETAINED GRAPHICS SAMPLE ______________________________________ JIGSAW demonstrates the use of bit maps in a graphics application. JIGSAW provides a jigsaw puzzle based on the decomposition of an arbitrary bit map loaded from a file. The user can jumble the pieces, then drag them with a mouse. The image can be made smaller or larger, or scrolled horizontally and vertically. JIGSAW also demonstrates how to call the Information Presentation Facility help hook, to create a help instance and associate the instance with the active application window. NPIPE -- THE NAMED PIPES SAMPLE _______________________________ NPIPE demonstrates two-way communication between two unrelated processes using named pipe functions. This sample program implements the game of tic- tac-toe with two executable files, CLINPIPE.EXE (the client) and SVRNPIPE.EXE (the server). The server is the computer, and the client is the user. PALETTE -- THE PALETTE MANAGER SAMPLE ------------------------------------- PALETTE demonstrates the creation of a window using a custom palette and animation. The user can display an IBM logo or an OS/2 logo. When run on a system having a fully-populated XGA adapter, the sample shows a palette animation technique from a second thread of execution. PDD -- THE PHYSICAL DEVICE DRIVER SAMPLE ________________________________________ PDD demonstrates how to construct a physical device driver. Features of this sample include: o Initializing a device driver o Defining a device driver header o Requesting device driver helper services. Also included are such elements as a strategy routine and interrupt handlers. PDD is an assembler language sample program. To run PDD, add a DEVICE state- ment to the bottom of the CONFIG.SYS file. Specify the path and complete file name to PDD. For example: DEVICE=C:\TOOLKT20\ASM\SAMPLES\PDD\PDD.SYS PRINT -- THE PRINTER SAMPLE ___________________________ PRINT demonstrates how to display and print text, graphics, metafiles, and bit maps. It also demonstrates how to: o Query and display a system printer configuration o Interact with the printer drivers to change job properties o Query and display available printer and screen fonts o Print from an asynchronous thread. QUEUES -- THE INTERPROCESS COMMUNICATION QUEUE SAMPLE _____________________________________________________ QUEUES demonstrates interprocess communications (IPC) using 32-bit queuing APIs. It consists of two executable programs, SVRQUEUE.EXE and CLIQUEUE.EXE. SVRQUEUE creates an IPC queue; a named, shared-memory buffer for queue ele- ments; and a shared, named, mutex (mutual exclusive) semaphore. After ini- tializing 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 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, then uses an event semaphore to direct the thread to write the element to the queue. CLIQUEUE terminates at the user's request. REXX -- THE PROCEDURES LANGUAGE/2 REXX SAMPLES ______________________________________________ Five REXX sample programs are included with the &tk.: o CALLREXX o DEVINFO o PMREXX o RXMACDLL o REXXUTIL CALLREXX -- THE REXX INTERPRETER INVOCATION SAMPLE 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 in a parameter string. BACKWARD.FNC returns a result string to the C-language application. DEVINFO -- THE REXX VARIABLE POOL INTERFACE SAMPLE This program issues DosDevConfig and returns the data in a collection of com- pound variables when all available items are requested, or a single variable when only one item is requested. This is a REXX subcommand handler and Vari- able Pool example. This sample can be run in an OS/2 full-screen session, an OS/2 text-window session, or in PMREXX. PMREXX -- THE PRESENTATION MANAGER REXX INTERFACE SAMPLE This sample provides a Presentation Manager window in which the user 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 the user can type. RXMACDLL -- THE EXTERNAL FUNCTIONS IN REXX MACROSPACE SAMPLE This sample demonstrates the macrospace interface with two C-language programs: MACRO.C and RXNLSINF.C, which are compiled into two separate dynamic link libraries. MACRO.C contains REXX external functions, which perform REXX macrospace oper- ations. RXNLSINF.C contains a REXX external function that provides informa- tion 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. REXXUTIL -- THE REXX UTILITY FUNCTIONS SAMPLE REXXUTIL demonstrates a set of external functions packaged in a dynamic link library, including: o Use of OS/2 system functions in REXX external functions o Techniques for passing large amounts of data to a REXX program using REXX compound variables as arrays. REXXUTIL can be run in an OS/2 full-screen session or an OS/2 window session. REXXUTIL cannot be run in PMREXX because some of the functions use video ser- vices. SEMAPH -- THE SEMAPHORE AND SHARED MEMORY SAMPLE ________________________________________________ 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. An event semaphore is used to signal the thread to give up the resource. The event semaphore can be posted by the user or run in auto mode. In auto mode, the event semaphore will be posted at fixed time intervals. A mutex semaphore is used to check for a stop event or for a user signal to give up the resource. Each thread can display as a different colored square; similarly, the resource can display as a rectangle, the color of which is that of the first thread that owns it. SORT -- THE MULTITHREADED PROCESS SAMPLE ________________________________________ 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. STYLE -- THE STYLE-GUIDE SAMPLE _______________________________ STYLE demonstrates a Presentation Manager application that conforms with Common User Access (CUA)* requirements and implements the following new controls: o Container o Notebook o Slider o Spin button o Value set. This sample program also demonstrates secondary windows, such as dialog and message boxes. 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, then add the appropriate message-processing routines to the STY_USER.C file. *CUA is a trademark of the IBM Corporation. TEMPLATE -- THE APPLICATION TEMPLATE SAMPLE ___________________________________________ TEMPLATE demonstrates the structure common to all Presentation Manager appli- cations. This sample program shows how to structure an application that has more than one source file. TEMPLATE also demonstrates how to: o Create a standard window o Load resources from a resource file o Create a dialog box and a button control o Display a message box o Open a file o Close a file o Print text o Paint a window o Process a message from a menu o Run a thread in the background o Exit a process. TP -- THE ADVANCED SOM SAMPLE PROGRAM _____________________________________ TP (text processing) demonstrates an advanced system object model (SOM) program in an object-oriented programming context. TP demonstrates the use of abstract superclasses, and public and private methods. This sample program also demonstrates subclassing, polymorphism, and encapsulation. TP reads a free-form file of text and markup language and produces a for- matted output file. The markup language is deliberately made up so that it is clearly defined as a simulation. The input file demonstrates the pro- duction of paginated, multi-column text with indentation, page numbers, unor- dered lists, headers, and footers. VDD -- THE VIRTUAL DEVICE DRIVER SAMPLE _______________________________________ VDD demonstrates a basic virtual device driver, including how to: o Interface with the virtual device driver helper services o Enable and disable system interrupts o Enable and disable a network card interrupt o Simulate interrupts in a DOS session o Initialize the device driver o Define a virtual device header. Use VDD with the physical device driver sample (PHYSDEV), to establish inter- device driver communications between a 16-bit physical device driver and a 32-bit virtual device driver. VDD also demonstrates how to control a network card -- this concept can be used to control other peripheral devices. VMM -- THE VIRTUAL-MEMORY MANAGEMENT SAMPLE ___________________________________________ 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 oper- ations according to the different attributes of each memory block. To free memory, the user enters the address of the memory. WORMS -- THE MIXED-MODE SAMPLE ______________________________ WORMS demonstrates how to call video (Vio), keyboard (Kbd), and mouse (Mou) 16-bit function from a 32-bit code segment. This sample program displays earth worms 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 first worm is set to red. The user can add or delete worms using the keyboard or mouse. WPCAR -- THE WORKPLACE OBJECT SAMPLE ____________________________________ WPCAR demonstrates how to create a workplace object using basic object- oriented programming techniques and the IBM System Object Model (SOM), including: o Initializing an object o Adding settings pages to an object o Saving and restoring the state of an object o Modifying object context menus (adding and deleting menu items) o Querying of object class data o Processing context menu items o Implementing settings page dialog processing.