Introducing the Developer's Toolkit for OS/2 Warp Version 4

by Jill Simula and Robert Spinneweber

This volume of the IBM Developer Connection introduces the Developer's Toolkit for OS/2 Warp Version 4, positioning you to take advantage of the many new features available in the next release of OS/2 Warp. This new Toolkit contains support for features such as OpenGL, connectivity features, and problem determination.

This article outlines the new header files, tools, online documentation, and samples that have been added to the Toolkit to assist you in your development efforts. For exciting information about the operating system, see the article, Inside the Next Release of OS/2 Warp, in this volume.

Header Files and Libraries
Many new header files and libraries have been added to the Toolkit. They can be categorized as follows:
 * C Runtime
 * MPTS
 * OpenGL
 * Peer Services
 * Problem Determination
 * TCP/IP
 * Universal Language Support (ULS)

Tools
The Toolkit contains eight new tools to assist you in the development of your OS/2 applications, including two utilities that enable applications to be translated into other languages.
 * MKTMPF:The Make Template File (MKTMPF) tool 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.
 * RPCGEN:This command generates C code to implement a remote procedure call (RPC) protocol The input to RPCGEN is a language similar to C, known as RPC language. RPCGEN generates the following four types of output files:
 * A header file (*.H)
 * XDR routines (*.C)
 * Server-side stubs (*.C)
 * Client-side stubs (*.C)


 * TRCUST:The Trace Customizer (TRCUST) assists you in preparing a program for event tracing. You can use event tracing to create a record of program processing to help you diagnose errors or performance problems in your application. TRCUST converts a trace source file (TSF) to a trace format file (TFF) that defines the formatting for an event trace record. You can also use TRCUST to combine multiple TFFs into a single TFF.
 * WSFORMAT:The WSFORMAT command is the WinSock1.1 for OS/2 trace formatter. The WSFORMAT command accepts binary trace input from a serial port, file, or 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.
 * Remote ICAT:This is a remote debugger used for debugging OS/2 device drivers, kernel code, installable file system (IFS), and applications that are running on an OS/2 Warp Version 4 remote machine. Remote ICAT is a source-level debugger that helps you detect and diagnose errors in code written in C, C++, and assembler languages It provides a graphical user interface (GUI) and debugs PM and non-PM (single- or multi-threaded) applications as well as device drivers and other system-level binaries. See the article, OS/2 Debugging in Style, on page 18 for more information about Remote ICAT.
 * NMAKE:A new version of the NMAKE tool is now available for Beta testing. NMAKE is used to automate the process of updating a project after a change has been made to a source file. This Beta version is fully compatible with previous versions of the tool NMAKE also provides a richer set of functions including the following:
 * Transformation macros, which are used to manipulate strings. Transformation macros can be used for pattern matching, or converting a string to upper or lower case.
 * Built-in commands, which are commands that are processed internally. Built-in commands perform a procedure or operation, such as changing directories or setting an environment variable.
 * Additional directives such as !elseif and !tryinclude Directives can also be used at run time as part of a command block.
 * Built-in functions, which are used in conditional constructs to test certain contains, such as the return code of the last command executed.
 * Macro assignments can use += or =+ to either append a string to the end of an existing definition, or to add a string to the beginning of an existing definition.

For detailed information about the new NMAKE function, see the NMAKE documentation in the Beta directory.

Translation Utilities
The OS/2 Warp Toolkit supports the development of applications that can be translated into other languages The OS/2 C runtime support for internationalization is based on the industry standard X/Open XPG4 model. The GENCAT and MKCATDEF utilities are used together to produce XPG4 message catalog files. (The functions used to extract messages from the message catalog files are documented in the C Library Reference.)


 * GENCAT:The General Message Catalog (GENCAT) utility creates the message catalog (*.CAT) from a message source file (*.MSG) or standard input. You can specify any number of message source files. A message source file is a text file that contains entries consisting of a message number followed by the message text.
 * MKCATDEF:You must use the Preprocess Message Source File (MKCATDEF) utility if you want to use symbolic message identifiers in you 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.
 * After running MKCATDEF, you can use symbolic names in an application to refer to messages.

For detailed information about using the new tools, see the OS/2 Tools Reference, located in the Toolkit Information folder.

Online Documentation
The following new online documentation is provided to assist you in taking advantage of the Toolkit additions. You can find these books in the Toolkit Information folder: Refer to Using Your Toolkit for an online roadmap to help you find what you're looking for.
 * C Library Reference
 * IBM OS/2 Server Family Programming Reference
 * OpenGL Programming Reference
 * Problem Determination Guide and Reference
 * TCP/IP Programming Reference
 * Unicode Programming Reference
 * Windows Sockets

Samples
With OS/2 Warp Version 4, the Toolkit now provides more than 200 samples. The new OpenGL, LAN Server, TCP/IP, and problem determination samples were specifically designed to help you exploit those features of the operating system.

OpenGL
OpenGL is a portable API from Silicon Graphics, Inc. that enables development of complex three-dimensional graphics applications. The OpenGL samples are categorized as follows:
 * Auxiliary Library (AUXDEMO):More than 60 different examples demonstrate rendering by drawing different shapes and demonstrate various techniques such as shading, lighting, texturing, and fogging.
 * OpenGL Utility Toolkit (GLUTDEMO):These samples demonstrate the rendering function along with window manipulation and user interaction control.

LAN Server
The LAN Server API provides an interface for server and client application development Functions are available for nearly every task a program might need to perform - from simple tasks, such as logging on to a network, to advanced tasks, such as security administration. The LAN Server samples demonstrate several fundamental tasks of programming in a networking environment.
 * Access Control Profile (ACCESS32):This sample returns all the access control profiles (ACPs) for a particular resource. You can alter an ACP by specifying the user and the new permissions.
 * File Resource Alias (ALIAS32):This sample adds a file.
 * resource alias and shares it, gives a group read-only access to the resource, and adds a directory limit to the resource.


 * Server Open Files (FILEEN32):This sample returns information about open files on a specific server. You can choose to view a list of all open files or restrict the list by device path or user.
 * Network Message (MESSAG32):This sample is designed to send simple messages through the messenger service Messages can be sent from the local machine or a remote server; they can be sent to specific users or a domain group, or broadcast to an entire LAN.
 * Network Logon (MLOGON32):This sample logs on a user, waits for the user to press the Spacebar, and logs the user off The user name, password (if required), and domain name are passed as command-line parameters to the program.
 * Server Administration (SADMIN32):This sample 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.
 * User Account (USER32):This sample is designed to access and control user account information. It can display information about a user, delete a user, or create a new user.

TCP/IP
The TCP/IP protocols provide the vehicle for communication between client and server that enables services such as remote printing of files, remote execution of programs, and network file systems The TCP/IP samples are categorized as follows:
 * RPC:These samples provide examples of Remote Procedure Call (RPC) client, server, and raw data stream programs.
 * RPCGEN:These samples define remote procedure characteristics and demonstrate an RPC server program and client program.
 * SAMPDLL:These samples demonstrate building and using a TCP/IP.DLL
 * SOCKET:These samples consist of several C socket client/server programs, which demonstrate network programming with OS/2 sockets.

Problem Determination
As operating systems become increasingly sophisticated, determining the cause of problems becomes more complex. The OS/2 Warp Version 4 operating system provides utilities that make it easier to find and fix problems. The Toolkit provides functions that you can add to your application to enable it to interface with the problem determination component of the operating system. The problem determination samples are categorized as follows:


 * Desktop Management Interface (DMI):These samples are used in conjunction with the DMI Browser, which is provided with the operating system. The DMI is a set of interfaces and a service layer that mediate between the management applications and components residing in the operating system.
 * Logging Framework:These samples demonstrate how to use the error-logging functions ERRLOG1 opens a file, reads an entry from the log, formats that entry, and closes the log ERRLOG2 opens event notification, waits on an error log event, changes an event filter, and then closes event notification
 * First Failure Support Technology (FFST):This sample shows how to insert a probe into a program so the system can log a failure and associated data, and save trace data or dump data. See the sidebar article on page 18 for more information.
 * Trace (TRACEXP):This sample shows how to create a trace event in the system-event trace buffer. You can view the system-event trace buffer using the Trace Formatter provided with the operating system.

Summary
These additions to the Developer's Toolkit make it easier to develop OS/2 applications and enable you to take advantage of the new features in the next release of OS/2 Warp. Your feedback on this new version of the Toolkit is appreciated and encouraged - please use the survey in the Toolkit package. It is this feedback that drives our development efforts So let us know we will be listening!