MainWin® 3.3 Build 67 Release Notes

MainWin is a registered trademark and Mainsoft is a trademark of Mainsoft Corporation. All other product or service names mentioned herein are trademarks or registered trademarks of their respective owners.

Limited Liability Statement: In no event will Mainsoft Corporation be liable for any loss of data; lost opportunity for profits; cost of cover; or special, incidental, consequential or indirect damages arising from the use of this software.

Date of publication: 24 June, 1999.

MainWin® 3.3 Build 67 Release Notes

Contents

1 New Features in MainWin 3.3...................................................... 6

1.1 HTML and HTML-Help..................................................................... 6

1.1.1 HTML.................................................................................................................................. 7

1.1.2 HTML-Help........................................................................................................................ 7

1.1.3 Limitations........................................................................................................................ 7

1.2 Unicode programming support........................................................ 7

1.3 Japanese language support............................................................ 8

1.3.1 Default code page........................................................................................................... 8

1.3.2 Resources........................................................................................................................ 8

1.3.3 Controls and dialogs...................................................................................................... 8

1.3.4 Cut, copy, and paste....................................................................................................... 8

1.3.5 Japanese keyboard and Input Method Editors.......................................................... 8

1.4 Compaq Tru64 UNIX support.......................................................... 9

1.5 Performance and compliance improvements................................. 9

1.5.1 New font cache algorithm improves performance.................................................... 9

1.5.2 Better Windows Resource files handling................................................................... 9

1.5.3 Support for Windows Message Compiler.................................................................. 9

1.5.4 Support for multimedia timers.................................................................................... 10

1.5.5 Improved performance for BitBlt operations............................................................ 10

1.5.6 New version of comcat DLL....................................................................................... 10

1.5.7 #import directive........................................................................................................... 10

1.5.8 New version of tstcon32 ActiveX Control Test Container..................................... 10

1.5.9 Default registry no longer contains entries for all international code pages..... 11

1.6 Additional features......................................................................... 11

1.6.1 Support for advanced platforms and compilers...................................................... 11

1.6.2 Emacs key-bindings in Edit and Rich Edit controls............................................... 12

1.6.3 Enhanced support features........................................................................................ 12

1.7 Year 2000 information................................................................... 13

1.7.1 Readiness disclosure................................................................................................. 13

1.7.2 Compliance with Microsoft.......................................................................................... 13

1.8 Issues resolved since build 66...................................................... 13

1.9 Compatibility with previous versions............................................. 15

2 Using MainWin 3.3....................................................................... 16

2.1 Building a Unicode application....................................................... 16

2.1.1 File and string encoding.............................................................................................. 16

2.2 Using Japanese support................................................................ 17

2.2.1 Background.................................................................................................................... 17

2.2.2 Running Japanese applications................................................................................ 19

2.2.3 Japanese resources.................................................................................................... 20

2.2.4 Displaying Japanese and Japanese fonts.............................................................. 20

2.2.5 Japanese controls and dialogs................................................................................. 21

2.2.6 Cutting, copying, and pasting Japanese.................................................................. 21

2.2.7 Using Japanese keyboard and Input Method Editors............................................ 22

2.3 Rehosting applications that uses the #import directive................ 25

2.4 Using ATL on UNIX........................................................................ 31

2.4.1 Preprocessing ATL applications................................................................................ 31

2.4.2 Macros to help port ATL applications........................................................................ 31

2.4.3 Specializing a template................................................................................................ 32

2.4.4 Templates within classes for methods.................................................................... 32

2.4.5 Templates using __uuidof(x) extension.................................................................. 33

2.4.6 Templates having default parameters...................................................................... 33

2.4.7 Templates having default parameters that use __uuidof..................................... 36

2.4.8 Templates using com_interface_entry* macros and requiring __uuidof 37

2.5 Adjusting UNIX system limits if resources are used up................ 37

2.5.1 Maximum number of semaphore undo structures allowed system wide......... 39

2.5.2 Maximum number of open file descriptors per process....................................... 39

2.5.3 Maximum number of ptys allowed............................................................................ 39

2.5.4 Maximum and minimum size of shared memory segments............................... 40

2.5.5 Maximum number of shared memory segments................................................... 40

2.6 Using DCOM interoperability between NT and UNIX..................... 42

2.7 Using type libraries in resource files............................................. 43

2.8 New font cache mechanism......................................................... 43

2.9 Using console mode with MFC applications................................. 44

2.10 Using mwcleanup.......................................................................... 44

2.11 Runtime setup: setmwruntime script............................................ 45

2.12 Removing pragma pack from source code.................................. 45

2.13 Using WGL (Windows implementation of OpenGL)..................... 45

2.14 Using the new Resource Compiler with code written for previous version of MainWin 46

2.14.1 Changes in resource files (.rc files):........................................................................ 46

2.14.2 Changes in code........................................................................................................... 46

2.14.3 Build................................................................................................................................. 47

2.14.4 String tables in resources........................................................................................... 47

2.15 Private implementations of the new operator................................ 47

2.16 Making a .tlb file from an .odl file using MIDL................................. 48

3 Platform-specific information.................................................... 49

3.1 Patch management....................................................................... 49

3.2 SPARC Solaris-specific information............................................. 49

3.2.1 Operating System and system requirements......................................................... 49

3.2.2 Patches........................................................................................................................... 50

3.2.3 Compiler version........................................................................................................... 54

3.2.4 Using MainWin on Solaris........................................................................................... 55

3.3 HP-UX 11.00-specific Information................................................. 56

3.3.1 Operating System and system requirements......................................................... 56

3.3.2 Patches........................................................................................................................... 56

3.3.3 Compiler versions........................................................................................................ 56

3.3.4 Using MainWin on HP-UX 11.00................................................................................ 56

3.4 HP-UX 10.20-specific Information................................................. 57

3.4.1 Operating System and system requirements......................................................... 57

3.4.2 Patches........................................................................................................................... 57

3.4.3 Compiler versions........................................................................................................ 58

3.4.4 Using MainWin on HP-UX 10.20................................................................................ 58

3.5 IRIX 6-specific Information............................................................. 60

3.5.1 Operating System and system requirements......................................................... 60

3.5.2 Patches........................................................................................................................... 60

3.5.3 Compiler versions........................................................................................................ 60

3.5.4 Upgrading to IRIX 6.5.4................................................................................................ 60

3.5.5 Using MainWin on IRIX................................................................................................ 61

3.6 Compaq Tru64 UNIX-specific information..................................... 62

3.6.1 Operating System and system requirements......................................................... 62

3.6.2 Patches........................................................................................................................... 62

3.6.3 Compiler versions........................................................................................................ 62

3.6.4 Using MainWin on Compaq Tru64............................................................................ 62

3.7 IBM AIX-specific issues................................................................. 67

3.7.1 Operating System and system requirements......................................................... 67

3.7.2 Patches........................................................................................................................... 67

3.7.3 Compiler versions........................................................................................................ 68

3.7.4 Using MainWin on AIX.................................................................................................. 68

4 Reporting Problems to Mainsoft............................................... 69

4.1 Submitting the problem to Mainsoft............................................... 69

MainWin® 3.3 Build 67 Release Notes

1 New Features in MainWin 3.3

Mainsoft is proud to announce the release of MainWin 3.3, a major upgrade of MainWin. With this release, Mainsoft continues to demonstrate its commitment to bring the latest Microsoft technologies to UNIX. MainWin now supports Microsoft’s Internet development technologies, HTML browsing and parsing, HTML Help. In addition, MainWin 3.3 introduces support for Japanese language applications; and extends its platform support to include Compaq Tru64 UNIX.

MainWin 3.3 introduces:

· Microsoft Internet development technologies: HTML, HTML Help, JScript, and VBScript

· Japanese language support

· Enhanced Internationalization: Unicode and multi-byte programming support

· Compaq UNIX Tru64

· Improved performance and compliance

ü new font cache algorithm improves performance

ü better Windows resource file handling

ü support for Windows Message Compiler

ü support for multimedia timers

ü improved performance for Bit Block Transfer (BitBlt)

ü new version of comcat DLL

ü updated #import directive

ü updated version of tstcon32 ActiveX Control Test Container

· Support for advanced platforms

· Emacs key bindings in Edit and Rich Edit controls

· Enhanced support features

Note: If you are upgrading from a previous version of MainWin or if you need any other information pertaining to previous builds, please contact Mainsoft support (mailto://support@mainsoft.com ).

1.1 HTML and HTML-Help

MainWin 3.3 introduces Internet Explorer Extensions with support for HTML and HTML-Help, JScript, and VBScript.

1.1.1 HTML

MainWin now supports HTML as part of Internet Explorer Extensions. MainWin provides the same level of HTML support as Microsoft’s Internet Explorer 4: HTML browsing, URL parsing, full navigation support, form editing (Form 3), multi-language support, and bitmap and graphic file rendering. It is now possible to rehost applications that parse or browse HTML (Web) documents.

The MFC 6 class CHTMLView is now supported.

HTML support is provided as COM interfaces.

Note: If you are upgrading from a previous version of MainWin and using an existing registry, run regedit after you install this release to register the file $mwhome/system/iesdk.reg.

1.1.2 HTML-Help

MainWin now supports HTML-Help.

Applications using the HTML-Help can now be rehosted on UNIX. MainWin supports the APIs required to link the application to HTML Help files; and provides the HTML-Help executable on UNIX.

You can use the new HTML-Help viewer to learn about using HTML-Help and integrating it into your applications. To do so, set up the environment to run MainWin. Then type

hh $MWHOME/helpfile/htmlhelp.chm

To view another sample HTML-Help file, type

hh $MWHOME/helpfile/winui.chm

The standard Windows help utility (winhelp) is also still supported.

1.1.3 Limitations

HTML is supported on all Solaris platforms supported by MainWin. HTML on HP has a few unresolved issues which primarily affect its stability; in consequence, HTML on HP should be considered as a beta release.

HTML-Help is supported on all Solaris platforms supported by MainWin.

1.2 Unicode programming support

MainWin supports Unicode programming. The MainWin libraries export the wide-character (W) version of the Windows APIs.

For instructions on using Unicode in applications, see “Building a Unicode application,” page 16.

The MFC library is supplied in both ANSI and Unicode versions. Two DLLs and their resource files are shipped in this version: mfc400du (MFC debug Unicode library) and mfc400su (MFC optimized Unicode library).

1.3 Japanese language support

MainWin 3.3 allows you to create native UNIX versions of your Japanese language applications on Solaris 2.6 and Solaris 7 Japanese operating systems. Support for Japanese localization is implemented at the resource and window-control level, including input, display, cutting, copying, and pasting of Japanese. The Wnn6/htt and Atok8 Input Method Editors (IME) for the Japanese keyboard are supported.

To use the features described below, refer to “Using Japanese support,” page 17.

1.3.1 Default code page

MainWin supports the setting of the default language and code page in the registry, just as in Windows. When these defaults are set to Japanese, a MainWin Japanese application will behave as the Windows version.

1.3.2 Resources

Resource files can contain Western language or Japanese multi-byte strings. The registry defines which resource file is loaded. The language directive and Unicode (L) strings can be used in resource files.

1.3.3 Controls and dialogs

All controls available in MainWin (common controls, edit controls, and common dialogs) support both Western languages and Japanese. All controls will display Japanese editable text, embellishments (title bars), text labels, tool tips, error messages, and button labels.

1.3.4 Cut, copy, and paste

MainWin 3.3 supports the cf_unicodetext clipboard format for cutting, copying, and pasting text. Conversion of clipboard text to and from cf_text format is automatic. MainWin 3.3 also supports transferring international text strings (including Far Eastern languages) to and from CDE applications, such as dtterm and dtpad.

1.3.5 Japanese keyboard and Input Method Editors

The Japanese keyboard is supported, using the Wnn6/htt and Atok8 Input Method Editors (IME). Both Wnn6/htt and Atok8 have been fully tested.

1.4 Compaq Tru64 UNIX support

MainWin is now available on Compaq Tru64 UNIX (formerly DEC UNIX OSF/1).

1.5 Performance and compliance improvements

1.5.1 New font cache algorithm improves performance

With version 3.3, MainWin no longer requires the application to build a font cache every time it displays on a new X server, improving performance of MainWin applications. Refer to “New font cache mechanism,” page 43, for technical details on how the new font cache operates.

1.5.2 Better Windows Resource files handling

· Full compatibility with Windows resource file format. MainWin 3.3 fully supports the Windows Resource Compiler. As a result, MainWin 3.3 supports Windows resource files format exactly as on Windows. For further information about the Windows Resource Compiler resource file format, please refer to Microsoft Developer Network (MSDN) documentation.

· Resource loading and accessing improved. The speed of loading and accessing resources during runtime has been significantly improved.

· Binary compatibility improved. With the new resource compiler, the result of the LoadResource API is returned in the format native to the target platform, instead of in Wintel format (little endian, 2-bytes–wide char). It is no longer necessary to modify source code to convert the returned value to the format of the target platform.

Note: if, for a previous version of MainWin, you modified your source code to convert returned values to the target platform format, you must remove these modifications. Refer to “Using the new Resource Compiler with code written for previous version of MainWin,” page 46 for instructions.

· Improved bitmaps handling. Handling of bitmaps in resource files has been substantially improved.

· Type library support. Type libraries (.tlb files) inside resource files are supported. For instructions on using type libraries in resource files, refer to “Using type libraries in resource files,” page 43.

1.5.3 Support for Windows Message Compiler

MainWin 3.3 fully supports the Windows Message Compiler. The Message compiler can significantly improve the time it takes to look up strings when using the FormatString API. For further information about the Windows Message Compiler, please refer to Microsoft Developer Network (MSDN) documentation.

1.5.4 Support for multimedia timers

MainWin now supports multimedia timers. The following APIs have been implemented:

timeSetEvent	timeBeginPeriod	timeGetDevCaps
timeKillEvent	timeEndPeriod	timeGetSystemTime

Unlike regular timers, multimedia timers do not depend on the Message Loop; that is, they do not rely on the application to call GetMessage() and DispatchMessage(). For more information about multimedia timers, refer to Microsoft documentation.

In the current version, setting timer resolution is not supported. All multimedia timers work with the same resolution, which is determined by the underlying operating system.

1.5.5 Improved performance for BitBlt operations

The performance of the BitBlt (Bit Block Transfer) API for complex raster operation code has been improved. As a result, the GUI will repaint faster when using these operations.

In simple raster operation code, where the pattern has no influence on performance, such as in BltCopy (Block Transfer Copy), the performance of the BitBlt operation is not affected.

1.5.6 New version of comcat DLL

MainWin now supports the version of comcat DLL supplied with Visual Studio 6. Functionality is as described in Microsoft documentation. This information supercedes section 22.1.8 of the MainWin 3 Developer’s Guide published 19 January, 1999.

1.5.7 #import directive

The #import directive allows developers to easily import a COM type library and use smart interface pointers without the hassle of dealing with reference counting. “Rehosting applications that uses the #import directive,” page 25, describes how to port a Windows application that uses the VC++ #import directive.

1.5.8 New version of tstcon32 ActiveX Control Test Container

MainWin has updated the version of tstcon32 provided with MainWin to the version currently supplied with VisualStudio 6. tstcon32 is a container for testing ActiveX controls. tstcon32 allows developers to run an isolated control in the test container, change its properties, and invoke its methods.

1.5.9 Default registry no longer contains entries for all international code pages

In previous versions of MainWin, the default registry contained entries for every one of the 55 available code pages. In certain instances (for instance, when calling EnumSystemCodePages), the unneeded registry entries may cause filling up the file descriptor tables and unnecessary load on running applications.

Now, the default registry contains entries for the same code pages as in the default Windows NT (English) installation.

Developers who need international code pages (for applications that display several languages, such as Internet Explorer and HTML applications), should add international code pages as follows:

regedit ${MWHOME}/system/international.reg

Note: mwpack now enters in the user’s registry only those code pages that have entries in the developer’s registry.

1.6 Additional features

1.6.1 Support for advanced platforms and compilers

Sun Sparc Solaris 7 supported

In addition to Solaris 2.5.1 and 2.6, MainWin 3.3 supports Solaris OS 7.

IBM AIX 4.3.2 OS supported

MainWin 3.3 supports AIX OS 4.3.2, instead of OS 4.3. AIX OS 4.3.2 is an improved version of OS 4.3 and should not pose any problems when upgrading.

New HP-UX 11 compiler supported

MainWin now supports the HP C compiler c89 A.11.00.00, and the C++ compiler aCC A.03.13

IRIX 6.5.4 OS

MainWin now supports the IRIX 6.5.4 OS on SGI.

IRIX 6.2, 6.3, and 6.4 are hardware-specific platforms that have been superceded by IRIX 6.5.4, which supports all platforms. This version of MainWin is supported only on version 6.5.4 of the IRIX operating system.

1.6.2 Emacs key-bindings in Edit and Rich Edit controls

When using Motif look, the standard Emacs key bindings are now implemented in Edit and Rich Edit controls. Users can use popular Emacs key combinations, such as <Ctrl>e, <Ctrl>a, and <Ctrl>u to manipulate text within these controls.

1.6.3 Enhanced support features

regedit and regsvr32 can be invoked in console mode at runtime

regedit and regsvr32 can now be invoked in either console mode or GUI mode at runtime. This allows developers to use regedit and regsvr32 without having a connection to an X server open (useful, for instance, in build environment). End-users can still use the regedit and regsvr32 GUI for editing the registry.

To call regedit in console mode (no X display required)

regedit -c <myfile.reg>

To call regsrv32 in console mode (no X display required)

regsrv32 -c <my_control.ocx>

For backwards compatibility of source code developed for previous versions of MainWin, mwregedit and mwregsrv32 invoke regedit -c and regsrv32 -c, respectively.

Creating a new registry

On the rare occasion that you wish to recreate the registry (for instance, if you suspect that the registry is corrupt), use mwregedit to create a new starter registry as follows:

mwregedit –new

FreeCell binaries provided

UNIX executables are now provided for the popular Windows game FreeCell. After you install MainWin and set the UNIX environment (by running the script setupmainwin), you can run FreeCell. To run FreeCell, type

$ freecell

at the system prompt.

1.7 Year 2000 information

1.7.1 Readiness disclosure

An API implemented by MainWin will not exhibit improper, undefined, or unpredictable behavior because of dates after 31 December 1999 if the underlying operating system is itself Y2K compliant and provides the required functionality, and the date data supplied to MainWin is itself Y2K compliant.

1.7.2 Compliance with Microsoft

For the yy/MM/dd common control, MainWin now behaves the same as the new behavior of the Microsoft Windows NT 4 Service Pack 3: if the two-digit year is less than 35, then the year is assumed to be 20xx; otherwise it is assumed to be 19xx.

When you bring up the calendar in both cases (old and new), you are able to see the full year and can therefore override the two-digit year limitation.

1.8 Issues resolved since build 66

No.	Description
7748	MainWin windows do not get input focus in OpenWindows
7750	Constructor CTime(time_t time) is undefined on HP-UX 10
7751	Drawing speed: MFC vs. X calls - PolyPolygon() problem
7752	Call to IDispatch::Invoke crashes the client
7753	Receive running-out-of-handles message when repeatedly drawing icons
7755	WinHelp: Graphic not displayed properly
7762	ShellExecute fails to open registered file types
7763	Problem displaying bitmaps in a *.hlp file
7766	Running the command "regsvr32 libmfc400d.so" aborts at program termination
7767	Using Print Setup to select Landscape orientation does not work
7769	MFC DLLs require MWUSE_OLE_LIBS=true even if they do not use OLE
7770	Endian problem in bitmap header when saving/reading bitmap controls
7771	Launching WinHelp 17 consecutive times fails
7772	GetPrivateProfileSection fails in build 66
7773	Need automatic call to MwSetProcessDetachOnExit
7774	PCR# 25857, regsvr32 failed to register libLibServer.so/libTypeServer.so
7777	Bug in MwPDTDialogBoxIndirectParam in build 66
7780	Printer setup dialog does not retain settings from win.ini
7783	Bitmap does not appear in property sheet
7784	wgl.c is not thread safe
7788	Combo box crashes after ResetContent message
7789	mwspr should be packaged by mwpack
7795	CButton crashes when using a bitmap
7797	Menu text changes to bold once it is selected
7800	PostMessage does not work with NULL windows in build 66
7803	PCR 246525 -- Mainwin applications exit when launching Java applications On
7807	Process hangs if multiple Mainwin applications running
7808	GetFullPathName returns incorrect value when "/" is used.
7809	PostScript EPS output for "Arc" API has incorrect bounding box
7810	CreateProcess does not work on HP all the time
7811	Crash when selecting combo box item
7812	AddTypeLib problem in test case
7813	Winhelp crashes when selecting the Find tab under eXceed
7814	FindResource(NULL, ...) does not use the current process's hInstance
7815	Need to be able to switch back from an OpenGL window to a regular GDI window
7821	Problem with VK_CONTROL is desynchronization
7822	Running CreateProcess a second time causes CPU to jump to 100%
7824	Memory alignment problem in CEdit::GetLine
7825	Disabled toolbar buttons don't paint correctly under eXceed
7826	Stingray mouse/keyboard handling of the menus does not work correctly
7828	Objective Toolkit 6.0 - does not build on HP-UX 10.20 and IRIX
7829	MENUITEM without a label defaults to a huge value
7831	Redraw of grayed menus is slow
7835	X error (BadValue on X_ConfigureWindow) when displaying on eXceed
7836	Core-dumps at exit in MwCallWEP
7838	Application core dumps when clicking in managed objects window
7848	GetPrivateProfileString does not trim trailing spaces when retrieving section keys
7853	AfxBeginThread leaks memory (1MB per 1000 threads)
7855	Using “mwmake clean” does not remove the TemplateDB directory
7856	Problem with customized Non Explorer-Style file dialog box
7870	Pop-up menu's sub-menu item is automatically selected
7881	Need GetDeviceDC to work on pixmaps too
7882	Scroll Bar messages SBM_GET[SET]POS and SBM_GET[SET]RANGE are not processed
7887	Context help on main menubar items lock-up application and soak CPU
7888	CString::Insert does not work correctly when an overlapped memcpy must be done
7889	PCR 251434: Just having Cursor on Toolbar hogs CPU.
7891	_MOTIF_WM_HINTS gets set to bogus value
7895	Printing dialog crash for large number of printers.
7896	Incorrect font displayed on successive dialogs derived from CDialogEx
7897	CEdit::GetLine copies the wrong 2 bytes of nMaxLength
7899	Need mechanism to control dialog font scaling
7900	Browsing using FileOpen dialog accesses files */desktop.ini - slow on Solaris 2.6 when automounter has -browse setting
7902	Failed to launch WinHelp focus problem
7906	In FileOpen dialog, double clicking rapidly on the MyComputer icon and then on the drive icon causes application to crash
7910	Large icons are not centered on smaller Cbutton
7913	regedit hangs when using patch #5 on HP-UX 10.20 and HP-UX 11.00
7914	After clicking, selection follows mouse in SECListBoxEditor class (lbedit example)
7915	Paths are added multiple times in MW setupmainwin and setmwruntime
7917	SetScrollInfo positions a vertical scrollbar incorrectly
7918	Incorrect pixel sizes generated from CreateCompatibleDC() and GetDeviceCaps()
7923	CHotKeyCtrl is not working
7924	The typename Interface (in ..sdk/inc/comip.h) works on Solaris, but fails on UX10.
7925	GetLine does not return text from Cedit control
7929	Semaphore not freed after CreateProcess call of non-Mainwin program (HP-UX 10)
7934	Printer Dialog throws a "garbage" dialog instead of "File Exists..." dialog
7940	lstrcpyn will sometimes coredump when iMaxLength is larger than the source string

1.9 Compatibility with previous versions

Applications built using previous versions of MainWin are not binary compatible with the MainWin 3.3. Applications built with previous versions of MainWin must be recompiled in all cases, even if they seem to be compatible.

Makefiles and source code for previous version of MainWin are compatible with MainWin 3.3. Some changes are required in resource files and code that reads from resource files because of the new Windows Resource Compiler. Refer to “Using the new Resource Compiler with code written for previous version of MainWin,” page 46

2 Using MainWin 3.3

If there is any conflict between these release notes and the MainWin 3 Developer’s Guide printed on or before 19 January 1999, these release notes take precedence.

2.1 Building a Unicode application

To build a Unicode application using make.rules.simple, define the makefile variable unicode. You may define the unicode variable either dynamically at the command line or statically in the makefile.

To define unicode at the command line

mwmake UNICODE=1

To define unicode in the makefile

Add the line:

UNICODE=1

inside the makefile.

Either way, the switches –dunicode and –d_unicode are passed to the compiler, and the W (unicode) versions of the Windows APIs are used. These APIs expect WCHAR strings with Unicode encoding to be passed to them.

2.1.1 File and string encoding

Most UNIX compilers (all except IBM AIX) represent characters (the type wchar or wchar_t) as a four-byte data type, instead of two bytes as on Windows. All in-memory procedures must follow the representation used by the compiler. In consequence, when reading from a file, all character strings must be converted to the representation supported by the compiler. In order to maintain compatibility with Windows, all strings and text files must be converted to Windows format when saved to file.

Wide-character strings—L”myString”—are supported only with Western (iso8859-1) characters. This is a compiler limitation, since most UNIX editors and compilers encode non-Western wide characters to non-Unicode values. It is possible to use a string having a hexadecimal format—L”\x3068”—but the best solution for manipulating localized strings is to use resources.

When using Japanese, DBCS strings passed to MainWin APIs will be interpreted as having Shift-JIS encoding. Therefore, if character strings embedded in the program are to be passed to MainWin, they must have Shift-JIS encoding.

2.2 Using Japanese support

2.2.1 Background

This background section discusses Unicode and non-Unicode programming; various programming modes; Far East (in particular, Japanese) and Western code pages, languages, and strings; and related issues.

These topics are discussed both in general and as they relate to MainWin 3.3.

Unicode and non-Unicode programming

A code page represents both a set of characters (the character set) and the way of coding it with bytes (that is, numbers from 0 to 255). The Western code page is 1252; the Japanese code page is 932.

The default code page is defined in the registry under the entry:

[hkey_local_machines\System\CurrentControlSet\Control\Nls\CodePage] “acp”=<default code page>

Traditional (non-Unicode) programming operates in the context of a given code page, where the knowledge of the implicit default code page is necessary to interpret and display strings (including menus, dialogs, etc.) correctly. The suffix “A” (for ANSI, or American National Standards Institute) in this context means a byte-oriented string that can be a single-byte code (ANSI), double-byte code (DBCS), or multi-byte code (MBCS). Far East languages have extensive ideograph character sets that cannot be encoded in a single byte, hence the use of DBCS and MBCS. DBCS characters are either one or two bytes long. MBCS have variable-length coding. DBCS encoding is used by Microsoft operating systems. MBCS encoding is used by UNIX operating systems.

Unicode, on the other hand, uses a single coding for all possible characters.

Conversion between Unicode and non-Unicode

You can convert Unicode to and from code-page specific strings using methods or functions such as MultiByteToWideChar and WideCharToMultiByte of the NLS subsystem. MainWin supports the NLS subsystem (ported from NT) as well as the code pages supported by NT. The necessary tables are embedded in the standard MainWin release.

Windows APIs that accept strings as parameters come in two flavors:

· A—ANSI

· W—Wide character string or Unicode

For example, the CreateWindow API actually has two implementations: CreateWindowA and CreateWindowW. You call one or the other depending on whether you want to use it with code-page specific double-byte strings or with Unicode strings.

NT supports both the A and W flavors of programming; Windows 95 supports only the A flavor.

When an application is designed to work with Unicode and therefore has to deal only with the W flavor APIs, the makefile variable unicode should be set to 1 (refer to instructions in “Building a Unicode application,” page 16). This defines the _unicode macro, which will cause all Windows API calls to be aliased to their W flavor. For example, CreateWindow will be aliased to CreateWindowW.

Mixed-mode programming

The A and W flavor APIs are available simultaneously. For instance, in a Unicode program, where all Windows API calls are aliased to W, you can still choose to explicitly call an A flavor API. For example, you may call LoadResourceA in the middle of your Unicode program.

Dual-mode programming

An ISV may want to produce both a Win95 non-Unicode executable and an NT Unicode executable (possibly with additional features) from the same code base. Such a program should be written in a way that allows compilation with or without the _unicode macro.

The basis for this dual-mode programming is the tchar data type (along with other Txxx macros) that expands to wchar when the _unicode macro is defined and to char otherwise. The set of macros needed for dual-mode programming is embedded in the Windows header files, and is supported by MainWin 3.3.

Note that a dual-mode program can also be mixed mode if it explicitly calls some A or W flavor APIs.

Japanese coding on PC and on UNIX

Two major encoding schemes exist in Japan:

· Japanese EUC code—a general way of encoding MBCS strings, and implemented by UNIX systems

· Shift-JIS code—developed by Microsoft, using DBCS encoding (one or two bytes)

When a DBCS (Japanese) MainWin application runs on a UNIX system, the DBCS interface between the application and MainWin uses the Shift-JIS code page (932) for the interpretation of strings. Using this interface avoids having to adjust the application to the different encoding of the UNIX system.

When MainWin interfaces with the UNIX operating system, EUC encoding is used if necessary. Internally, MainWin uses either Shift-JIS or Unicode, and the translation to EUC is made at the outermost interface of MainWin with UNIX.

Most of the latest versions of UNIX operating systems also have a Shift-JIS interface. When the user logs in under the ja_JP.PCK locale, this interface to the UNIX operating system becomes active. As a result, the interface between MainWin and the UNIX operating system does not involve a translation (for example, file names will be created using the Shift-JIS coding).

When using Japanese, DBCS strings passed to MainWin APIs will be interpreted as having Shift-JIS encoding. Therefore, if string literals embedded in the program are to be passed to MainWin, they must have Shift-JIS encoding.

When using MainWin to write to or read from a UNIX-encoded text file, it is usually necessary to translate UNIX-encoded text strings to Shift-JIS format. To do so, developers may use the functions OemToChar() and CharToOem(). Mainsoft has rewritten these functions specifically for this purpose.

2.2.2 Running Japanese applications

Changing the registry

To run Japanese MainWin applications, it is necessary to indicate in the registry that the default language and default code page are Japanese. To do so, use the following command:

regedit ${MWHOME}/system/jpn.reg

To return to English (Western) defaults, use the following command:

regedit ${MWHOME}/system/enu.reg

Limitations

Japanese-language applications are supported on Solaris 2.6 and Solaris 7, Japanese edition.

Only the locales japanese,¸ja, and ja_JP.PCK are supported on Solaris 7. To change the locale, use the Options menu when logging in:

The Japanese default code page (932) is supported by MainWin only when the Japanese version (or extension) of the operating system is installed.

The default code page cannot be changed while the application is running. The default code page must be set before the application starts.

In MainWin, the default code page is global and unique for a given application. (Under Windows NT, the default code page can be changed at the thread level.)

When starting a MainWin application in Japanese mode, the lang environment variable must be set to japanese (note that the “j” must be lower case); this is done automatically when you log in as a Japanese user under CDE. Failure to do so will cause some MainWin resources to be loaded in Western rather than in Japanese (the Yes, No, Abort, and Cancel strings of the Message Boxes, and the system menu strings). This requirement of the lang environment variable will be lifted in a future version of MainWin.

2.2.3 Japanese resources

Compiling Japanese resources

If you are using the make.rules.simple build system that MainWin provides, sources for your Japanese resources (.rc files) should be in the subdirectory l.jpn under the project root directory.

The Japanese resources can be compiled using the command line:

mwmake MWLOCALES=jpn

Alternatively, if you want Japanese resources to be kept up-to-date by the make system without having to explicitly mention it on the command line, add the line mwlocales=jpn to the makefile. The Japanese resource compilation will then be activated (when necessary) each time mwmake is called.

In either case, the compiled resources (.rsb files) will be in an l.jpn subdirectory, located under the directory containing the compiled executable (for instance, /run/sunos5/l.jpn).

MainWin transparently loads the Japanese resources at run time from this subdirectory, whenever the registry in use specifies a default language of Japanese (see “Running Japanese applications,” page 19).

Restrictions

The locale cannot be changed while the application is running.

2.2.4 Displaying Japanese and Japanese fonts

The proper behavior of text displayed on screen depends on two things:

· selection of a code page that will result in a font that supports the character set of the desired country

· availability of screen fonts to support the character set needed: UNIX systems ship from the vendor with various font sets; in addition, ISV vendors and end users can find public domain fonts on the Internet

The enumeration of fonts using a specified code page (a specified character set) is also supported (EnumFontFamiliesEx). We advise using this API, and not using EnumFontFamilies (which may lead to the selection of a Western font).

2.2.5 Japanese controls and dialogs

Languages and strings in controls

All controls available in MainWin (common controls, edit controls, and common dialogs) support both Western languages and Japanese. When a control has been programmed as multi-byte, the international strings it displays will be interpreted relative to the current default code page, as expected. All controls can display Japanese editable text, embellishments (title bars), text labels, tool tips, error messages, and button labels.

The implementation of controls capable of handling international Far East text is greatly simplified when using MainWin 3.3 with Unicode programming, because with Unicode the number of characters is proportional to the length of the string.

Control Classes

Control Classes, when registered with RegisterClassW, are understood by MainWin (like Windows) to have a WindowProc capable of handling Unicode strings. Messages such as wm_setttext will therefore receive a Unicode string.

Unicode—multi-byte communication

MainWin (like Windows) has a message translation layer that allows a message sent by SendMessageA to be received by a W (Unicode) WindowProc, and vice-versa. As a result, a part of the application that is multi-byte is able to communicate with a control that is Unicode.

2.2.6 Cutting, copying, and pasting Japanese

UNIX applications use various methods to exchange international data. The official (OSF) method embedded in Motif Widget uses the xa_compound_string format. This is a multi-byte format wherein each part of the string is prefixed by a 3-byte or 4-byte escape sequence that specifies the code page. A homogeneous string (that is, one composed of characters all from the same code page) has only one escape sequence at the beginning of the string.

The CDE dtpad and dtterm applications use this OSF method, and MainWin 3.3 fully supports this clipboard exchange mechanism (cf_unicodetext clipboard format) for cutting, copying, and pasting text to and from UNIX applications. Conversion of clipboard text to and from cf_text format is automatic. MainWin 3.3 also supports transferring international text strings (including Far Eastern languages) to and from CDE applications, such as dtterm and dtpad.

Other (and older) UNIX applications support slightly different formats. Be aware that these UNIX applications may crash when cutting and pasting Far Eastern strings between them and MainWin.

Note: The default code page must be Japanese (932). When the default code page is Western (1252), then if any character in the string is outside of what is covered by the Western character set (and this is a likely occurrence), all the string encoding information will be lost.

2.2.7 Using Japanese keyboard and Input Method Editors

Keyboard and IME behavior

The MainWin Japanese keyboard has a UNIX (rather than Microsoft) behavior, which allows a consistent interaction with all programs running on the UNIX desktop. The Input Method Editors (IME)—Wnn6/htt and Atok8—as supported by MainWin also have UNIX behavior, for the same reason.

Typical IME operation under MainWin

An IME under UNIX usually requires, in addition to the X server and an Xlib module, two other processes. One process is the dictionary process, which provides the phonetic-to-character translations. The other process is the I/O process. These two processes (dictionary and I/O) are started automatically when the user logs in with the Japanese locale.

The I/O process can have its own input window, or can borrow the application’s input window. The I/O process collects the phonetic typing, allows basic editing in the window, launches translation requests when the user chooses to do so (for example, by typing <control><backslash>), and finally transfers the text to the application through the Xlib extension and the Xlib.

Under MainWin, the application does not create or position the IME window or choose the font, nor does it provide IME feedback to the user. The IME outputs wm_char messages to the application only when the user validates the input. While typing to the IME, there is no interaction with the application.

Input to Unicode and non-Unicode applications

If the application is Unicode, then it receives the input as characters of Unicode data, one character per wm_char message.

If the application is non-Unicode (for example, it calls GetMessageA or TranslateMessageA), then it receives the input as a sequence of DBCS (double-byte code) bytes using SJIS (Shift-JIS) coding.

Availability of IMEs

The UNIX vendor releases one or more IMEs along with the Japanese version of the operating system. End users can purchase and install third-party IMEs.

Integrating the IME within the application frame

Integrating the IME within the application frame enables the application to feel much more like other UNIX applications running on the desktop, and gives a more finished and pleasing look to the application. See Figure 1.

Figure 1. IME integrated within the application frame

However, this feature is MainWin-specific, and must be enabled in the extended style bits when creating the window:

Integrating the IME within the application frame in standard applications

Instead of using the code

CreateWindowEx(dwExStyle, lpClassName, ...

use the API MwCreateWindowExEx together with the flag ws_ex_ex_mwuse_ime_within_frame

#include <mainwin.h>

MwCreateWindowExEx(WS_EX_EX_MWUSE_IME_WITHIN_FRAME, dwExStyle, lpClassName, ...

The API has to be used once for each top-level window of the application, since all child windows will inherit the features of their parent top-level window.

Integrating the IME within the application frame in MFC applications

The CreateWindowEx call is handled by MFC, but the application can intercept the wm_nccreate message and add the style bit at this point. To do this, add a message handler to the class for the (window) frame:

ON_WM_NCCREATE()

//}}AFX_MSG_MAP

int CMainFrame::OnNcCreate(LPCREATESTRUCT lpCreateStruct)

{

::SetWindowLong(m_hWnd,GWL_MWEXEXSTYLE,WS_EX_MWUSE_IME_WITHIN_FRAME |

::GetWindowLong(m_hWnd,GWL_MWEXEXSTYLE));

return 1;

}

Integrating the IME within dialog windows

For dialogs, the MainWin dialog code detects the presence of a child window of type Edit or ComboBox and enables the feature.

However, if one subclasses the edit control, creates dynamic dialogs, or uses property sheets, then the ws_ex_ex_mwuse_ime_within_frame bit cannot be specified and the feature is not available.

Figure 2 shows a File Open dialog box where the IME has been automatically integrated into the frame by the MainWin dialog code:

Figure 2. File Open dialog box with IME integrated into the application frame by MainWin dialog code

Other modifications

When this feature is used, the frame size of the created windows bears a different relationship to the client region size (greater height to make space for the IME). Therefore, programs depending on specific size relationships will have to be further modified to take into account the possibility of an additional height in this mode. However, in the case of dialogs, the client area is kept the same so that all the controls still fit in as designed.

Drawbacks of not using the IME integration feature

When the ws_ex_ex_mwuse_ime_within_frame bit is not (or cannot be) specified, the IME functionality still is available, but will look less integrated.

When using the OpenWindows environment, there are many cases where the focus is not normally given to the application because of interference with the non-integrated input method. Therefore, if you plan to use your application under OpenWindows, the IME integration feature is highly recommended for a better user experience.

Under CDE, the Atok8 input method, when not integrated in the frame, creates a separate frame placed under the application window. Two minor problems appear when the integration feature is not used:

· When this frame is open (that is, IME is active) it does not move immediately when the application window is moved.

The workaround is to make the IME inactive, and then active again, for the IME frame to move.

· If the X desktop focus is given to the IME frame (by moving the mouse over it and clicking on it), the characters entered are not input into MainWin even though they are accepted and validated by the IME.

The workaround is to give back the focus to the application.

IME issues

· Some key accelerators, such as alt, may not work correctly when the IME window is open.

· Under OpenWindows, the IME window may be larger than the main application window.

· When the IME window is opened under OpenWindows, it may take the focus from the application. To give the application back the focus, point or click (as appropriate) in the application window.

2.3 Rehosting applications that uses the #import directive

This section describes how to port a Windows application that uses the VC++ #import directive.

Restrictions

These instructions assume that there are no dispinterfaces in the imported typelibrary or that they have been excluded with the exclude attribute of the #import directive.

If there are dispinterfaces in the typelibrary and they are used by the importing application, the imported project must be modified to expose custom interfaces in addition to the dispinterface. For instructions, see “Importing dispinterfaces,” page 29.

To port an application using the #import directive to UNIX

1. Compile the file containing the #import on PC.

This procedure generates the C++ files describing the interfaces that can be used in place of the #import.

It might be necessary to modify the #import directive.

First, the attribute no_namespace is required, in effect, declaring the smart pointer in the standard namespace, as namespaces are not supported on some native Unix compilers.

Remove any namespace specifier in the application. If the application expects a namespace, it may not compile anymore on the PC. Since we only want it to generate the interface descriptions, this is acceptable.

If there are no needed dispinterfaces in the type library, use the exclude attribute to remove them from the import.

Use the named_guid attribute to generate the various guids needed.

Example :

#import “control.tlb” no_namespace, exclude “IMyDisp”, named_guids

This procedure will generate two files in the object directory having the same name as the typelibrary but with the extensions tlh and tli. The above example would generate control.tlh and control.tli.

2. Copy the two generated files to the UNIX source directory and replace the #import directive by including the tlh file.

The following clean-up is also required:

a. At the end of the tlh file, the line including the tli file must be modified to remove the path specification. The name must be changed to all lowercase.

b. In the tli file, replace every occurrence of the __uuidof(this) by __uuidof(<interface_name>).

c. In the tlh file, move the section that defines the guids into some global cpp file such as stdafx.cpp.

d. In the tlh file, lines containing __cdeclspec(property(… must be removed.

e. Remove all #pragma.

3. When declaring smart pointers, remove any namespace specification.

4. VC++ uses a special feature to access a property by name. For example, to read a property named color, VC++ allows you to write

c=obj->Color

which the compiler rewrites it as

c=obj->GetColor()

To write to the Color property, VC++ allows you to write:

obj->Color=c

which the compiler rewrites it as:

obj->PutColor(c)

Since properties cannot be accessed by name on UNIX, PutColor() or GetColor() must be used instead.

5. uuids must be declared somewhere. This is a common COM porting issue.

Example of #import rehosting

In the example that follows, we illustrate how to rehost the tstcon sample, supplied on the MSDN CD.

We assume that the imported library tcprop has been successfully built and registered.

1. On the PC, in the file testcon.h, modify the line containing the #import directive to remove the namespace attribute and add a named_guids attribute. The line should now read:

#import “TCProps\TCProps.tlb” no_namespace named_guids

Two files, TCProps.tli and TCProps.tlh, will be generated in the object directory. Copy these files to the project directory on the UNIX machine.

2. Move to the UNIX environment. Convert the two files to UNIX format as follows:

mwtounix tcprops.tl*

In tcprops.tlh, modify

#include “<...MyPath\>TCProps.tli”

#include “tcprops.tli”.

The section that defines the several guids must be moved to another file, for example to stdafx.cpp.

extern "C" const GUID __declspec(selectany) LIBID_TCPropsLib =

{0xffc3c462,0x18de,0x11d1,{0x8e,0x2f,0x00,0xc0,0x4f,0xb6,0x8d,0x60}};

extern "C" const GUID __declspec(selectany) IID_ITCExtendedControl =

{0x3e6f10a8,0xe1d1,0x11d0,{0x8e,0x14,0x00,0xc0,0x4f,0xb6,0x8d,0x60}};

extern "C" const GUID __declspec(selectany) CLSID_TCExtPage =

{0xab39f080,0x0f5d,0x11d1,{0x8e,0x2f,0x00,0xc0,0x4f,0xb6,0x8d,0x60}};

The section that declares the properties as named must be deleted:

__declspec(property(get=GetName,put=PutName))

_bstr_t Name;

__declspec(property(get=GetPositionX,put=PutPositionX))

long PositionX;

__declspec(property(get=GetPositionY,put=PutPositionY))

long PositionY;

__declspec(property(get=GetSizeX,put=PutSizeX))

long SizeX;

__declspec(property(get=GetSizeY,put=PutSizeY))

long SizeY;

Lastly, in tcprops.tli, we must replace all occurrences of __uuidof(this) with __uuidof(ITCExtendedControl)

3. In tcitem.cpp, there are some places where the property Name is accessed explicitly by name. This must be replaced by a call to GetName() or PutName(…)

In the file tcitem.h, line 252 contains an ending semicolon. Delete the semicolon.

In the file tcview.cpp, the QuadPart of the large_integer structure must be accessed with the quad_part macro.

4. The GNUmakefile must be modified to generate the guids from the odl:

MIDL_IID=tstcon_i.c
MIDL_TLB=tstcon.tlb

5. The following must be added to tstcon.cpp to instantiate the various uuids:

ATL_TEMPLATE_PREFIX IID UUID_PLACEHOLDER<Document>::m_iid=CLSID_Document;

extern const GUID IID_ITestContainer98Events;

ATL_TEMPLATE_PREFIX IID UUID_PLACEHOLDER<ITestContainer98Events>::m_iid= DIID_ITestContainer98Events;

extern const GUID CLSID_TCExtPage;

ATL_TEMPLATE_PREFIX IID UUID_PLACEHOLDER<TCExtPage>::m_iid=CLSID_TCExtPage;

extern const GUID IID_ITestContainer98;

ATL_TEMPLATE_PREFIX IID UUID_PLACEHOLDER<ITestContainer98>::m_iid=DIID_ITestContainer98;

extern const GUID IID_ITCExtendedControl;

ATL_TEMPLATE_PREFIX IID UID_PLACEHOLDER<ITCExtendedControl>::m_iid=IID_ITCExtendedControl;

tstcon_i.c must also be included in tstcon.cpp.

Importing dispinterfaces

In the current version of MainWin, dispinterfaces cannot be imported as described above. This section contains sample code demonstrating how to import an MFC application exposing a dispinterface.

To be imported, the dispinterface must be converted to a custom interface that exposes the same functionality; the dispinterface does not need to be removed. To convert to the dispinterface to a custom interface, an idl file is required instead of the odl file. This idl file will contain the definition of the custom interface and the contents of the odl.

The following sample shows the odl plus the added code (in bold) and demonstrates how to create the custom interface. uuids were not written out in the example below; but you must write out uuids in full for the example to work.

[ uuid(…), version(1.0) ]

library myLib

{

importlib("stdole32.tlb");

[ uuid(…) ]

dispinterface IDisp

{

properties:

[id(1)] long prop;

methods:

[id(5)] boolean method();

};

[ uuid(…) ]

coclass myCoClass

{

[default] dispinterface IDisp;

};

The idl looks like this

#include <olectl.h>

import "oaidl.idl";

import "ocidl.idl";

[ uuid(…) ]

interface ICust : IUnknown

{

[propget,id(1)] HRESULT prop([out,retval] long *pret);

[propput,id(1)] HRESULT prop([in] long val);

[id(5)] HRESULT method([out,retval] BOOL *pret);

}

[ uuid(…), version(1.0) ]

library myLib

{

importlib("stdole32.tlb");

[ uuid(…) ]

dispinterface IDisp

{

properties:

[id(1)] long prop;

methods:

[id(5)] boolean method();

};

[ uuid(…) ]

coclass myCoClass

{

[default] dispinterface IDisp;

interface ICust;

};

To be able to compile the idl file, the MIDL settings for the project must be modified to remove the mktypelib flag. Remember to generate the header and iid files.

The file defining the object must be modified to declare the new custom interface.

To implement this custom interface and redirect it to the implementation of the dispinterface:

DECLARE_DISPATCH_MAP()

DECLARE_INTERFACE_MAP()

//Declare the new interface for the object.

BEGIN_INTERFACE_PART(mySubObj, ICust)

//Implement each interface number.

STDMETHOD(get_prop)(long *pres)

{

METHOD_PROLOGUE(CObj,mySubObj)

//To call the dispinterface method:

*pres=pThis->Getprop();

return S_OK;

}

…

END_INTERFACE_PART()

An interface map and the implementation of the IUnknown methods are also required. These procedures are described in MFC Technical Note 38, “MFC/OLE IUnknown Implementation” of Microsoft’s Developer’s Network (MSDN).

The newly created object now has a custom interface that duplicates the dispinterface. Depending of the interface, a proxy/stub DLL might be needed.

2.4 Using ATL on UNIX31

2.4.1 Preprocessing ATL applications

There are a number of UNIX-based compilation problems when using ATL (for example, default parameters for ATL templates are not supported by all UNIX compilers). In many instances, MainWin can preprocess the ATL application source code to make the code compatible with UNIX. The preprocessed source code remains fully Windows NT compatible and compiles correctly on Windows NT. For further information, see “Macros to help port ATL applications,” page 31.

In addition, the following features are also available for easier porting:

· In #include directives, all file names are changed to lower case, and “\” (backslash character) in file names are changed to “/” (slash character), as required by UNIX.

· In the MFC message map for MainWin, the macro theDerivedClass <derived class name> is defined before a class, and is set to be undefined afterwards. This definition is needed for correct compilation.

· Extra “;” (semicolon) is removed in C++ constructors, since UNIX compilers will not accept unnecessary semicolons.

· midl file names are converted to all lower case.

All of the features of this section are applied automatically if the ATL option is chosen when using the MainWin Preprocessor Wizard (invoked by mwgenmake; see MainWin Developer’s Guide for information about mwgenmake) or if the -atl switch is set when using mwprepro (refer to the MainWin Developer’s Guide).

2.4.2 Macros to help port ATL applications

MainWin provides several macros for helping port ATL applications. These macros provide solutions for a number of UNIX-based compilation problems, as discussed in the following sections. Some of the problems arise because UNIX compilers have yet to implement features of the ANSI standard to which Microsoft conforms, and others arise because of features that are Microsoft extensions to the ANSI standard. Note that these macro workarounds are for the preprocessing of ATL source code only.

Here is the list of compilation problems for which MainWin provides macros:

Compilation problem	Macro
“Specializing a template,” page 32	ATL_TEMPLATE_PREFIX
“Templates within classes for methods,” page 32	ATL_QI_ARGS
“Templates using __uuidof(x) extension,” page 33	ATL_DECLARE_UUIDOF
“Templates having default parameters,” page 33	MWNO_DEF_IN_TEMPLATES
“Templates having default parameters that use __uuidof,” page 36	MWNO_UUIDOF_IN_TEMPLATES
“Templates using com_interface_entry* macros and requiring __uuidof,” page 37	_ATL_HAS_UUIDOF

These macros are defined in the header file mwatldef.h, which is located at
<the directory where MainWin is installed>/userx/public/sdk/inc/atl

We recommend that you #include this header file even when compiling your application under Windows. There is a twofold advantage in doing so:

· You can use these macros in your Windows source code, so that the same source code is used and compiles correctly on both Windows and UNIX.

· In many cases you do not need to write #ifdef/#endif code.

2.4.3 Specializing a template

Problem:

The IBM AIX C++ compiler does not allow the use of template<> when specializing a template. For example, the following code on an AIX for specializing the function f() will produce an error:

template<class T> f(T);

template<> f(int); // specialization of f(T);

Solution:

Include the header file mwatldef.h, and change the code by using atl_template_prefix instead of template<>. In our example, write the above line of code for an AIX as:

template<class T> f(T);

ATL_TEMPLATE_PREFIX f(int); // specialization of f(T);

If the compiler is other than IBM AIX C++, use the original source code.

2.4.4 Templates within classes for methods

Problem:

UNIX C++ vendors do not yet support templates within classes for methods, this being a new feature in ANSI C++.

However, this feature is widely used: ATL passes a pointer to a COM object interface pointer, and from the type of the interface pointer ATL then deduces the IID of the interface. The QueryInterface method of many ATL classes is a typical example.

For example, the following code (if unsupported by UNIX) will produce an error:

HRESULT hr = m_spOleObject.QueryInterface(ppDisp);

Solution:

Include the header file mwatldef.h, and change the code to use atl_qi_args to wrap the passed parameter. In our example, write the above line of code as:

HRESULT hr = m_spOleObject.QueryInterface(ATL_QI_ARGS(ppDisp))

2.4.5 Templates using __uuidof(x) extension

Problem:

Visual C++ supports a Microsoft-specific extension to C++ called __uuidof(x). Its syntax is similar to that of sizeof(x), where x is a type; in the case of __uuidof(x), x is usually a COM interface.

The MainWin implementation defines __uuidof(x) as a static member of a template called uuid_placeholder, where x must be a COM interface. MainWin has instantiated this template for many of the public COM interfaces in uuid.dll.

However, MainWin’s instantiation cannot cover the private COM interfaces that your application defines. For example, if __uuidof(IPrivateInterface) is used (also indirectly), you will get the following unresolved symbol:

UUID_PLACEHOLDER<IPrivateInterface>::m_iid

Solution:

To resolve the unresolved symbol in the above example, include the header file mwatldef.h, and add atl_declare_uuidof(IPrivateInterface) to one of your C++ ATL files that includes mwatldef.h.

2.4.6 Templates having default parameters

Problem:

Some compilers (Sun and IBM AIX) do not support templates having default parameters. (Note: If the default parameter is __uuidof, then refer also to “Templates having default parameters that use __uuidof,” page 36.)

While default template parameters can appear anywhere, they are a particular problem in applications that require ATL, which utilizes default template parameters extensively. The following ATL classes are affected:

CcomEnum<class Base, const IID* piid, class T, class Copy, class ThreadModel = CcomObjectThreadModel>

CcomTearOffObjectBase<class Owner, class ThreadModel = CcomObjectThreadModel>

IconnectionPointImpl<class T, const IID* piid, class CDV = CcomDynamicUnkArray>

IDispatchImpl<class T, const IID* piid, const GUID* plibid, WORD wMajor = 1, WORD wMinor = 0, class tihclass = CComTypeInfoHolder>

IpropertyNotifySinkCP<class T, class CDV = CcomDynamicUnkArray>

IprovideClassInfo2Impl<class T, const IID* piid, const GUID* plibid, WORD wMajor = 1 , WORD wMinor = 0, class tihclass = CcomTypeInfoHolder>

Solution:

There are two possible solutions, depending on the template in question:

· The template is from MainWin and you preprocess the code. (Note that the ATL classes listed in the above table are MainWin supplied.)

Define the macro mwno_def_in_templates by including header file mwatldef.h. When you preprocess the code (see “Preprocessing ATL applications,” page 31), the #ifdefs will automatically be inserted as needed in the header files and source code. The template source code used for the above compilers (Sun and IBM AIX) will have the default parameters changed to non-default. For all other compilers the source code used will be the original template having the default parameters.

· The template is not from MainWin, for example, it is a template that you developed.

You will have to manually insert the necessary template default parameters and #ifdefs in the header files and source code. The template source code used for the above compilers (Sun and IBM AIX) should have the default parameters changed to non-default. For all other compilers the source code used should be the original template having the default parameters.

Following are some coding examples.

Coding example 1:

When the syntax “= ...” is not supported, then the expected parameters cannot be omitted when instantiating the template. For example, the code:

IDispatchImpl<T, &IID_IUnknown, &IID_IUnknown>

must be replaced by:

IDispatchImpl<T, &IID_IUnknown, &IID_IUnknown, 1, 0,

CcomTypeInfoHolder>

If you are able use the mwno_def_in_templates macro (as in this case, where the template is MainWin supplied) the changes will be made automatically by the preprocessor; otherwise (as in the case of a template that you developed), you will have to manually make the changes.

Coding example 2:

In general, code that includes the following syntax:

template <class A, class B = int>

class X {

A a;

B b;

};

class A {int a;};

void f (X<A>& x);

should be modified (possibly conditionally) to:

template <class A, class B>

class X {

A a;

B b;

};

class A {int a;};

void f (X<A,int>& x);

See the following coding example for further information.

Coding example 3:

The following code fragment will cause an error on some compilers:

template <class T, int i, class C = CSample2>

class CSample<piid>

{

//…

}

class CSample3 :

public CSample<Csample3, 2>

{

//…

}

If you are able use the mwno_def_in_templates macro (that is, the template to be changed is MainWin supplied) then the following changes will be made automatically by the preprocessor; otherwise (that is, the template is one you developed), you will have to manually make the changes.

In either case, here is the code (changes marked in bold) that is required:

#ifndef MWNO_DEF_IN_TEMPLATES

template <class T, int i, class C = CSample2>

#else

template <class T, int i, class C>

#endif

class CSample<piid>

{

//…

}

class CSample3 :

#ifndef MWNO_DEF_IN_TEMPLATES

public CSample<Csample3, 2>

#else

public CSample<Csample3, 2, Csample2>

#endif

{

//…

}

2.4.7 Templates having default parameters that use __uuidof

Problem:

Most UNIX compilers (except HP) do not support templates having default parameters that use __uuidof.

Solution:

There are two possible solutions, depending on the template in question:

· The template is from MainWin and you preprocess the code.

Define the macro mwno_uuidof_in_templates by including header file mwatldef.h. When you preprocess the code (see “Preprocessing ATL applications,” page 31), the #ifdefs will automatically be inserted as needed in the header files and source code. For compilers with this problem, the template source code used will have the default parameters containing __uuidof changed to non-default. For other compilers, the source code used will be the original template having the default parameters that use __uuidof.

· The template is from MainWin but you did not preprocess the code, or it is not a MainWin template (for example, it is a template that you developed).

You will have to manually insert the necessary template default parameters and #ifdefs in the header files and source code. For compilers with this problem, the template source code used should have the default parameters containing __uuidof changed to non-default. For other compilers, the source code used should be the original template having the default parameters that use __uuidof.

Note:

· For default-parameter coding examples, see “Templates having default parameters,” page 33.

· Whenever mwno_uuidof_in_templates is defined and used, then mwno_def_in_templates (see “Templates having default parameters,” page 33) must also be defined since it too will be used; however, both of these macros are defined in the same file mwatldef.h.

2.4.8 Templates using com_interface_entry* macros and requiring __uuidof

Problem:

When the com_interface_entry* macros (they are defined in <atlcom.h>) are used within templates and are given template arguments as parameters, the use of __uuidof is required. (Note, however, that this should be a rare situation, since the Visual C++ Application Wizard does not generate such code.)

Here is an example of com_interface_entry* code that does require the use of __uuidof:

template <class base>

class ImplBase : public Base{

public:

…

BEGIN_COM_MAP(Base)

COM_INTERFACE_ENTRY(Base)

…

END_COM_MAP()

…

};

In the above example you will get an error saying that IID_Base is undefined. The error is caused by com_interface_entry(Base) being expanded into:

{&IID_Base,…

Solution:

Include the header file mwatldef.h and define _atl_has_uuidof (this macro is disabled by default, as explained below). Note: _atl_has_uuidof is spelled with an “_” (underscore) at the start of the macro name.

Using _atl_has_uuidof will force com_interface_entry(Base) to be resolved as:

{&__uuidof(Base),…

This solution to the IID_Base-undefined error may in turn generate an unresolved-symbol error. Use atl_declare_uuidof (see “Templates using __uuidof(x) extension,” page 33) to resolve the unresolved-symbol error.

Note: The _atl_has_uuidof macro is different from the other macros described in this section: it is a configuration macro that affects ATL itself. When _atl_has_uuidof is defined, it affects the com_interface_entry* macros in <atlcom.h> (these macros use __uuidof(x) on PCs). _atl_has_uuidof is therefore disabled by default, since defining it leads to unresolved symbols at link time for uuid_placeholder<IPrivateInterface>::m_iid.

2.5 Adjusting UNIX system limits if resources are used up

Background

The UNIX operating system maintains a configurable list of system resource limits. The ones relevant to our discussion are listed in the following table:

Table 1: System Resource Parameters and Descriptions

Parameter	Description
semmnu	maximum number of semaphore undo structures allowed system wide
rlim_rd_cur	maximum number of open file descriptors allowed per process
pt_cnt	number of ptys allowed on the system
shmmax	maximum size of a shared memory segment
shmmin	minimum size of a shared memory segment
shmmni	maximum number of shared memory segments system wide
shmseg	maximum number of shared memory segments that a single process can attach to

The Problem

Any application that tries to consume more system resources than set by the system limits will fail to do so, and, in most cases there will be no system error message indicating this failure to the user.

In particular, there may be cases where a MainWin rehosted application fails to execute correctly due to an attempt to use more system resources than allowed. For example, say an application opens many files. After the application has already opened the maximum number of files allowed, its attempt to open one more file will not succeed; the application may crash, or it may not function properly.

Solution

The solution to the problem is to modify the system resource limits to suit the application’s needs.

In the rest of this section, we will discuss some of the system resource limits that an application may exceed, and how to modify the appropriate system settings to enable the application to execute correctly.

Note:

· The following procedures are intended for system administrators; root password privilege is required to change UNIX system parameters.

· The instructions given below are for Solaris systems. The names of system parameters or file locations may be different for other UNIX systems.

On Solaris, the system limits are set modifying the file /etc/system. Changes in this file only take effect after the system is rebooted. For more information regarding the Solaris /etc/system file format, see the man pages at:

$ man –s 4 system

2.5.1 Maximum number of semaphore undo structures allowed system wide

MainWin allocates a semaphore undo structure for each executing application. If a rehosted application fails to run concurrently with other instances of the application (or alongside any other rehosted application), it may be because this limit has been reached.

The number of semaphore undo structures permitted on the system should be greater than or equal to the maximum number of concurrent MainWin processes that will ever run simultaneously. If you do not have any idea, start with 100.

To set maximum number of semaphore undo structures allowed system wide

· Add the following line to the /etc/system file:

set semsys:seminfo_semmnu=###

where ### is the maximum number of semaphore undo structures allowed on the system.

2.5.2 Maximum number of open file descriptors per process

The default maximum number of open file descriptors allowed per process on Solaris is 64. If the application fails to open a file, it may be because it reached this limit.

To set maximum number of open file descriptors allowed per process

· Add the following line to the /etc/system file:

set rlim_fd_cur=###

where ### represents the maximum number of open file descriptors allowed per process.

2.5.3 Maximum number of ptys allowed

If at any time you suspect that your application ran out of available ptys (virtual ttys), increase the maximum number of ptys allowed.

To set maximum number of ptys allowed

· Add the following line to the /etc/system file:

set pt_cnt=###

where ### is the maximum number of ptys allowed on the system.

2.5.4 Maximum and minimum size of shared memory segments

MainWin makes use of shared memory for its internal purposes. It may be that the shared memory settings are incorrect; ensure that the maximum and minimum shared memory sizes are as follows:

· Set the maximum size of a shared segment to 1,048,576 bytes (1 MB).

To set maximum size of a shared memory segment to 1 megabyte

ü Add the following line to the file /etc/system:

set semsys:seminfo_shmmax=1048576

· Set the minimum size of a shared memory segment to be less than the maximum size, preferably to 1 byte.

To set the minimum size of a shared memory segment

ü Add the following line to the /etc/system file:

set semsys:seminfo_shmmin=1

2.5.5 Maximum number of shared memory segments

MainWin uses shared memory to hold internal information about threads, events, and other Windows resources. An application that is very demanding of such resources (for example, it is heavily multithreaded, or it creates and maintains a large number of events) may exhaust the available shared memory allocated to it by the operating system, resulting in application crash or unexpected behavior.

There are two system resource limits that should be set to help avoid the problem:

· shmmni—maximum number of shared memory segments system wide

· shmseg—maximum number of shared memory segments that a single process can attach to

In order to set shmmni and shmseg we need to estimate the number of shared memory segments required by MainWin at peak time, as described in the following procedure. (Note that the result of this procedure is an estimate, and should be used with a safety factor.)

To estimate number of shared memory segments required at peak time

1. Have as few as possible processes running on your system.

2. Run an instance of your MainWin application. Activate all features of your application to make sure it is using the maximum number of resources.

3. Run the ipcs command to determine how many shared memory segments are allocated by MainWin for your application. When running only one instance of your application, it is most likely that only two shared memory segments will be allocated. The following is an example of ipcs output when two shared memory segments are allocated:

m 0 0x500182c3 --rw-r--r-- root root

m 401 0x31004030 --rw-rw-r-- user1 group1

m 402 0x31004031 --rw-rw-r-- user1 group1

4. Run another, concurrent instance of your application. Make sure it is using the maximum number of resources. Repeat the ipcs command. If you get the same results as above, you know that both processes have fit into the same shared memory segment. Continue adding concurrent instances of your application and using the maximum number of resources, until you see an increase in the number of allocated shared memory segments. An example of ipcs output when MainWin allocates more shared memory segments follows:

m 0 0x500182c3 --rw-r--r-- root root

m 402 0x31004030 --rw-rw-r-- user1 group1

m 402 0x31004031 --rw-rw-r-- user1 group1

m 403 0x31004032 --rw-rw-r-- user1 group1

In this example, the additional line indicates that MainWin has automatically allocated another shared memory segment.

5. Note the number of concurrent instances of your application, and subtract 1. For convenience, let us call this number num_mw_proc_per_memseg.

6. Estimate the maximum number of shared memory segments system wide (shmmni) as follows:

shmmni = 1 + (max_concur_mw_proc / num_mw_proc_per_memseg)

where

ü max_concur_mw_proc stands for the maximum number of instances of your application that are ever expected to run concurrently.

ü num_mw_proc_per_memseg is the value that was calculated earlier in step 5.

ü If shmmni is fractional, round it up to the next highest integer.

Note: It is recommended, as a safety precaution, that you set the actual value of shmmni to be somewhat higher than the result of the calculation.

This concludes the procedure; you are now ready to set both the shmmni and shmseg limits.

Setting the maximum number of shared memory segments system wide

To set maximum number of shared memory segments system wide

· Add the following line to the /etc/system file:

set shmsys:shminfo_shmmni=####

where #### is the maximum number of shared memory segments system wide that was calculated in step 6, page 41.

Setting the maximum number of shared memory segments that a single process can attach to

You should set the value of shmseg—the maximum number of shared memory segments that a single process can attach to—to be equal to shmmni—the maximum number of shared memory segments system wide.

To set maximum number of shared memory segments that one process can attach to

· Add the following line to the /etc/system file:

set shmsys:shinfo_shmseg=####

where #### is the value of shmmni, as calculated earlier in step 6, page 41.

2.6 Using DCOM interoperability between NT and UNIX

This section supercedes section 22.1.5 of the MainWin 3 Developer’s Guide printed 19 January, 1999.

DCOM interoperability between NT and UNIX requires the following settings.

NT side

On the NT side you need Windows NT 4.0 with Service Pack 3 or later. Use regedit to manually edit the registry setting [hkey_local_machine\software\Microsoft\Rpc]@DCOM Protocols so that the ncacn_ip_tcp protocol is the first in the list of DCOM protocols. This is the only transport protocol that the current UNIX version supports.

UNIX side

Windows NT rpcss always use port 135 for DCOM communications. For DCOM communications between Windows and UNIX, you must explicitly direct rpcss on UNIX to use port 135. Before executing the application, set the environment variable mwrpc_endpoint to 135. To do so, use one of the following commands:

For Cshell:

setenv MWRPC_ENDPOINT 135

For Kshell:

MWRPC_ENDPOINT = 135

export MWRPC_ENDPOINT

Note that DCOM communications between two UNIX systems does not require port 135 and the connection is handled transparently by MainWin.

Port number 135 is a privileged port on UNIX (only root can bind to it and accept connections). Therefore, rpcss uses a special process, mwprip, to overcome this restriction. You must be root to set up mwprip. Use the following shell commands to set up mwprip:

cd $MWHOME/bin‑${MWCONFIG_NAME}_optimized/

chown root mwprip

chmod agu+s mwprip

Note: When mwprip is installed on a remote disk, you must have root equivalence between the NFS server and the local system to ensure that mwprip is running under root privilege.

DCOM interoperability between NT and IRIX or HP

On some IRIX and HP systems, port 135 is already in use by the DCE daemon. If you need DCOM interoperability between NT and IRIX or HP, you should ask your System Administrator to reconfigure the system and remove the DCE daemon. Interoperability with the DCE RPC server is under development.

2.7 Using type libraries in resource files

The function LoadTypeLib loads either a stand-alone type library or a type library in a resource file. The type library that will be loaded is the one stored in the file specified (as a parameter of the LoadTypeLib function).

If the specified file is a .tlb file, MainWin will search for the type library in the following order:

1. working directory

2. current path

3. according to the library path environment variable (ld_library_path on Solaris, IRIX, and Compaq Tru64; shlib_path on HP; libpath on AIX).

If the specified file is a DLL or executable, LoadTypeLib will look first in the resource file of the specified DLL or executable. If it cannot find it there, it will fall back to the same search order as for when a .tlb file is specified.

In either case, if a full path is specified for the location of the resource file, only the specified path will be searched.

2.8 New font cache mechanism

The new font cache mechanism builds a font cache in increments. This way, the end user does not perceive delays when an application starts for the first time on a new X server The font cache file update is spread over the duration of the application process, and is active only when the user chooses a new font. For simple applications, typically no more than five different fonts are used.

The font cache file is located in ${HOME}/windows/ directory under the name mwfc-<number>, where <number> is dependent on the specific display used. This file can be removed if it is suspected of interfering with font operations; if removed, it will be regenerated on the next run of a MainWin-based application.

The time needed to update the font cache entry for a given font is usually short, and can be measured at the shell level by issuing the command:

/bin/time xlsfont –lll <xfont-name> >/dev/null

where <xfont-name> is the specific font you want to time. (To get a list of fonts from the X server, use the command xlsfonts.)

Some scalable fonts (such as TrueType or Adobe Type 1) can take several seconds to render, especially if they have never been scaled before or if they display a large Asian character set. Once, however, the font is rendered, the information is cached and subsequent presentations of the font are instantaneous.

mwgenfontcache font cache utility

In the extreme case where no slowdown (due to incremental font cache rendering) on a specific display can be tolerated, use the mwgenfontcache utility to generate a font cache.

Run the command

mwgenfontcache –specific

to generate a display-specific font cache. If necessary, run the command

mwgenfontcache –help

to tell you under which (display) number the font cache has been generated. This font cache will be used the next time a MainWin application starts on that display.

In case you need to release this pre-generated, fully prepared, font cache to your end users, copy it to your release area, and—prior to launching the MainWin application—have the environment variable mwfont_cache_dir point to the directory where this font cache file is located.

2.9 Using console mode with MFC applications

Non-GUI MFC applications can run on UNIX without an Xserver connection. To implement support for MFC console mode applications, generate a makefile as follows:

mwgenmake –con –mfc

This information supercedes section 27.1 of the MainWin Developer’s Guide published 19 January, 1999.

2.10 Using mwcleanup

An abnormal termination of a MainWin application, e.g., a kill -9 command issued by the user, may leave the MainWin kernel and GUI objects in an inconsistent state. You can use the new mwcleanup utility to kill all active MainWin processes and clean the IPC and X Properties, which will restore stability to your system.

There are three instances when you can benefit from using the mwcleanup utility as part of your troubleshooting procedures.

1. Your application hangs and ctrl+c (^C) does not function. In this case, run mwcleanup in another window.

2. Your application hangs and ctrl+c (^C) does function. In this case, run mwcleanup after you use ctrl+c.

3. While your application is running, you receive the following error message: rpcss service main failed. In this case, exit your application and run mwcleanup.

2.11 Runtime setup: setmwruntime script

For end-users to be able to use MainWin applications, their environment must be set up properly to use MainWin. One simple way to set up the end-user environment is to use the script setmwruntime.

To use the setmwruntime script:

C Shell users

# setenv MWHOME <installation path>/mw

# source ${MWHOME}/setmwruntime.csh

Bourne or Korn Shell users

# MWHOME=<installation path>/mw

# export MWHOME;. ${MWHOME}/setmwruntime

2.12 Removing pragma pack from source code

The use of pragma pack may cause runtime applications to not function and should be removed from your code prior to compiling. With most compilers, you will not receive any compiling errors if you include pragma pack in your code, but your runtime application may not operate correctly.

2.13 Using WGL (Windows implementation of OpenGL)

Preparing target UNIX system to support WGL

Before you can use WGL in MainWin applications, OpenGL (supplied by the UNIX vendor) must be installed on the target UNIX system.

Compiling WGL application

On Solaris, HP-UX 10.20, and Compaq Tru64 UNIX, the application may hang if Xlib is initialized to support multithreaded applications and run with OpenGL. To use WGL (which requires OpenGL) on those platforms, Xlib must be initialized in single-thread mode. To do so, add the following line to your makefile:

MWINIT_DEFINES = -DMWUSE_OPENGL

Note: Initializing Xlib with MWINIT_DEFINES = -DMWUSE_OPENGL has the following consequences:

· The responsiveness of the application may be decreased

· MsgWaitForMultipleObject() and MsgWaitForMultipleObjectEx() may not function reliably

2.14 Using the new Resource Compiler with code written for previous version of MainWin

The Resource Compiler of the previous version of MainWin created resources in Windows NT format; that is, byte-ordering was always little-endian, wide character (wchar_t) was 2 bytes, and alignment was as documented in MSDN.

The new Resource Compiler creates resources in the format native to the UNIX system on which the resource is compiled. In consequence, modifications made in code for resources created with previous versions of MainWin must be removed. Details follow.

2.14.1 Changes in resource files (.rc files):

In previous versions of MainWin, the BEGIN...END statement had to be added to version resources. This statement should be removed before compiling the resource file with the new Resource Compiler.

2.14.2 Changes in code

There are three major changes in the binary format of resources built with the new Resource Compiler:

· Byte ordering (endianship) is in the format native to the UNIX system on which the resource is compiled.

Code from previous versions that was modified to reverse byte ordering when reading from resource files or when creating resource files at runtime must be removed.

· Wide characters are in the format native to the UNIX platform on which the resource is compiled. On all UNIX platforms wide characters are 4 bytes, except on AIX, where they are 2 bytes.

Code from previous versions that was modified to pad wide-character format when reading from resource files or when creating resource files at runtime must be removed.

· Structures and strings are automatically aligned on the 4-byte boundary.

Code from previous versions that manually aligned structures and strings on the 4-byte boundary when reading from resource files or when creating resource files at runtime must be removed. All strings (class name, title, font name, etc.) are aligned on the 4-byte boundary as required by UNIX operating systems (even on AIX).

2.14.3 Build

When building resources, type libraries (.tlb) may now be embedded in the resource. When the .tlb is embedded in the resource, it is not necessary to supply the .tlb file separately when packaging for distribution.

When compiling resources with embedded type libraries, make sure that the correct type library is located in the include path. If a type library file from the PC is found before the one UNIX one, an error will occur. In general, it is better not to have Windows type libraries anywhere in the project path.

2.14.4 String tables in resources

If you access string tables directly in memory, you must take UNIX byte alignment into account.

Entries in string tables have the following structure:

Number of characters (WORD)

Character 1

Character 2

•
•
•

Character N

On operating systems on which a wide character consists of 4 bytes (Solaris, HP, Compaq Tru64, and IRIX), wide characters are aligned on 4-byte boundaries. Since the first field of a string in a string table is a (2-byte) WORD, it will be necessary to skip a WORD when reading a string from the string table, so as to start reading the first character (the second field) at a 4-byte offset from the first field.

On IBM AIX, wide characters are 2 bytes as on Windows NT; in consequence, the above does not apply on AIX.

2.15 Private implementations of the new operator

Developers who overwrite the new operator with a private implementation under the HP-UX 11.00, HP-UX 10.20, IRIX 6.5.4, or AIX 4.3.2, must also implement new[]. If you wish, MainWin provides a small supplementary library, libmwsupl.a, which uses new to implement the new[] operator automatically.

To use the MainWin implementation of new[], be sure to link with the library libmwsupl.a. One way of making the link with mwsupl.a is to set the following flag in the makefile:

APP_LDFLAGS += -lmwsupl

2.16 Making a .tlb file from an .odl file using MIDL

When building your application you can make a .tlb file from an .odl file using MIDL. Either include the flag use_midl=1 inside the makefile, or run

mwmake USE_MIDL=1

3 Platform-specific information

3.1 Patch management

If you are currently using MainWin and your installed patches are meeting your needs and those of your customers, we strongly recommend that you not change your installed patches.

The list of patches below is recommended for new customers and customers experiencing problems. This list consists of the most up-to-date patches available from the system vendor.

Developers must install both the developer’s patches and the runtime patches listed below. You need supply only the runtime patches to your end users.

Important notice: Mainsoft makes every effort to provide the most current and accurate information about patches for the various platforms and operating systems. Just before we complete the development of a new release, we verify that we are using the smallest number of, and the most recent, patches available. The cycle of building and testing a new release may take several weeks. It frequently occurs that during that time, a vendor will issue a new patch that supersedes a patch that was used for the build. Mainsoft recommends using the tested patch list. However, we also recognize that not all customers will be able to update or roll back their patch configuration. Superseding patches should work; however, Mainsoft cannot take responsibility for patches that have not been tested.

3.2 SPARC Solaris-specific information

3.2.1 Operating System and system requirements

MainWin runs on Solaris 2.5.1, 2.6, and 7.

MainWin works correctly from the Solaris Kernel Revisions dated as follows:

· Solaris 7—from October 1998

· Solaris 2.6—from January 1998

· Solaris 2.5.1—from March 1997

To check the current revision of your kernel, use the command

showrev –a | grep “Kernel version”

The output from your command should be similar to the following:

· Solaris 7

Kernel version: SunOS 5.7 Generic October 1998

· Solaris 2.6:

Kernel version: SunOS 5.6 Generic 105181-05 January 1998

· Solaris 2.5.x:

Kernel version: SunOS 5.5.1 Generic 103640-08 March 1997

Note that the last two fields (Month and Year) are the current revision of your kernel.

The following parts are required for installing the Japanese operating system on SPARC Solaris:

· for the Solaris 2.6 workstation, part SOLMS-260WD99C (the Japanese operating system)

· for the Solaris 2.6 server, part SOLMS-260W999C (the Japanese operating system)

3.2.2 Patches

Detecting the graphics card

On Solaris systems, a patch is sometimes required that is specific for the installed graphics card. Use the instructions that follow to determine which graphics card is installed on your system.

To verify that an FFB accelerator is installed on the system (Creator 3D), enter

% dmesg | grep ffb

The output should be:

SUNW,ffb0 at root: UPA 0x1e 0x0

SUNW,ffb0 is /SUNW,ffb@1e,0

stdout is (/SUNW,ffb@1e,0) major (53) minor (0)

To verify that an AFB accelerator is installed on the system (Elite 3D), enter

% dmesg | grep afb

The output should be:

SUNW,afb0 at root: UPA 0x1e 0x0

SUNW,afb0 is /SUNW,afb@1e,0

stdout is major <79> minor <0>

To detect graphics cards (alternate method), enter

% ls /dev/fbs/*

You can tell which graphic card is present by the output from the command; see the following table.

Table 2: Detection of Graphic Cards

Output	Graphics card
/dev/fbs/m640	PGX graphics card
/dev/fbs/afb*	Elite3D graphics card
/dev/fbs/ffb*	Creator/Creator3D graphics card
/dev/fbs/cgsix*	GX graphics card
/dev/fbs/leo*	ZX graphics card
/dev/fbs/sx*	SX graphics card
/dev/fbs/tcx*	TCX graphics card

Solaris 7 patches

It is strongly recommended that you install the recommended Solaris Patch Cluster for Solaris 7.

Important: Please read “Patch management,” page 49.

Table 3: List of runtime patches for all Solaris 7 systems

Patch	Description	Reason for Patch	Notes
107078-10	Xsun Patch	Fixes bugs in XinitThreads and _XflushInt, that is, bug fixes for multithreaded applications under X.
106147-03 or later	VIS/XIL graphics patch

Table 4: List of configuration-specific runtime patches for Solaris 7

Patch	Description	Reason for Patch	Notes
107104-04 or later	OpenGL 1.1.2: OpenGL Patch	This patch is for users of OpenGL
106146-06 or later	M64 Graphics Patch	To fix gui hanging problems To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For PGX (M64 Graphics card)
106145-04 or later	FFB Graphics Patch	Supplemental patch for VIS/XIL graphics patch. To fix gui hanging problems To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For Creator Graphics Card on Solaris 7
106144-06 or later	AFB Graphics Patch	Supplemental patch for VIS/XIL graphics patch. To fix gui hanging problems To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For Elite3D Graphics Card

Solaris patches are available at http://sunsolve.sun.com/.

Solaris 7 Japanese patches

The Japanese version of Solaris 7:

does not require patches.

Solaris 2.6 patches

It is strongly recommended that you install the recommended Solaris Patch Cluster for Solaris 2.6.

Important: Please read “Patch management,” page 49.

Table 5: List of runtime patches for all Solaris 2.6 systems

Patch	Description	Reason for Patch	Notes
105633-21 or later	Xsun Patch	Fixes bugs in XinitThreads and _XflushInt, that is, bug fixes for multithreaded applications under X.	For both Solaris 2.5.1 and 2.6
105361-08	VIS/XIL 2.6 Graphics Patch

Table 6: List of runtime patches for specific configurations on Solaris 2.6

Patch	Description	Reason for Patch	Notes
106735-07	OpenGL 1.1.2	For users of OpenGL
106022-07	OpenGL 1.1.1 Patches	For users of OpenGL
106391-01	TCX Graphics Patch	• To fix gui hanging problems • To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For TCX Graphic card
105492	CGsix driver patch	For GX frame buffer
105363-19	AFB Graphics patch	Supplemental patch for VIS/XIL graphics patch for Elite 3D frame buffer: • To fix gui hanging problems • To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For Elite3D Graphics Card
105362-20	M64 Graphics Patch	Required for PGX (M64 Graphics card) PCI-based Ultra 5, 10, and 60 • To fix gui hanging problems • To fix paint problems (black/white regions appear in menu’s, dialog boxes, toolbars, etc.)	For PGX (M64 Graphics card)
105360-24 106395-06	FFB graphic patch	Supplemental patch for VIS/XIL graphics patch. • To fix gui hanging problems • To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For Creator Graphics Card

Solaris patches are available at http://sunsolve.sun.com/.

Solaris 2.6 Japanese patches

The following patches are required for SPARC Solaris 2.6-Japanese. They must be installed in the order listed:

· 106125 for speeding up the installation of patches

· 106040 X Input Method

· 105633 X server and Xlib

· 105181 kernel jumbo for multi-threading

Solaris 2.5.1 patches

It is strongly recommended that you install the recommended Solaris Patch Cluster for Solaris 2.5.1.

Important: Please read “Patch management,” page 49.

Table 7: List of runtime patches for all Solaris 2.5.1 systems

Patch	Description	Reason for Patch	Notes
103566-43 or later	Xsun Patch	Fixes bugs in XinitThreads and _XflushInt, that is, bug fixes for multithreaded applications under X.	For Solaris 2.5.1
105789-05 or later	VIS/XIL 2.5.1 Graphics patch

Table 8: List of runtime patches for specific configurations of Solaris 2.5.1

Patch	Description	Reason for Patch	Notes
106735-07	OpenGL 1.1.2	For users of OpenGL 1.1.2.
106022-07	OpenGL 1.1.1	For users of OpenGL 1.1.1.
105791-19 or later	AFB Graphics Patch	Supplemental patch for VIS/XIL: To fix gui hanging problems To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For Elite3D Graphics Card on Solaris 2.5.1
105790-15 or later	FFB Graphics Patch	Supplemental patch for VIS/XIL: To fix gui hanging problems To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For Creator Graphics Card on Solaris 2.5.1
103793-01	TCX graphic patch		TCX graphic card
103792-21	M64 Graphics Patch	To fix gui hanging problems To fix paint problems (black/white regions appear in menus, dialog boxes, toolbars, etc.)	For PGX (M64 Graphics card) on Solaris 2.5.1

The Solaris patches are available at http://sunsolve.sun.com/

3.2.3 Compiler version

Sun Workshop C/C++, version 4.2.

The following patches are required with this compiler:

Patch	Description
104631-07	Compiler patch
104731-06	Debugger patch

3.2.4 Using MainWin on Solaris

Running multi-threaded GUI applications on multi-processor Solaris systems

Some MainWin multi-threaded GUI applications may hang if run on multi-processor Solaris systems. The problem is related to the thread-safety of the Solaris Xlib. We have reported the problem to Sun, and the following Sun bug numbers have been assigned:

Bug ID	Description
so 4099505	XinitThreads under OpenGL
so 4233225	XinitThreads under OpenGL
so 4170854	Multi-processor bug

If multi-threaded GUI applications on multi-processor Solaris systems hang, you may try the following workaround: instruct MainWin not to use the XinitThread function of Xlib; and disable the extra thread that MainWin uses to process the Xevents queue. To do so, set the following environment variable values:

MWDONT_XINITTHREAD=TRUE

MWNO_RIT=TRUE

Performance may be negatively affected.

Debugging MFC libraries on Solaris

Due to optimization performed by the Solaris linker, object files must be available to debug source code. To save disk space and decrease installation time, MainWin no longer supplies object files of MFC libraries; therefore, developers who wish to debug MFC libraries must build the MFC libraries themselves. This is not necessary to debug MFC applications, only to debug the MFC libraries themselves.

To compile the MFC source code

4. Go to the $mwhome/../mfc400/src directory.

5. Run mwmake with one of the options described below.

The options chosen for mwmake depend on which MFC library is required:

For MFC library version	Run mwmake with the following options
mfc400d (ANSI debug)	COMPILE_OPTION=debug
mfc400du (Unicode debug)	COMPILE_OPTION=debug UNICODE=1

3.3 HP-UX 11.00-specific Information

3.3.1 Operating System and system requirements

HP-UX 11.00

3.3.2 Patches

Patch	Description
PHSS 16404	LD and linker tools and cumulative patch
PHSS 16021	X/Motif 2.1 Dev Kit, November ’98 periodic patch.

3.3.3 Compiler versions

Compiler	Version	Package Name	Number
C	c89 A.11.00.13	B3899BA	B.11.01.01
C++	aC++ A.11.03.13	B3911DB	B.11.01.06

3.3.4 Using MainWin on HP-UX 11.00

System limitations

WGL (Windows implementation of OpenGL) is not supported because OpenGL is not available on HP-UX 11.00.

Read and write access in FileMapping

HP-UX 11.00 imposes severe restrictions on the use of CopyOnWrite mode in FileMapping (UNIX mmap function). Consequently, if several processes are mapping the same file into memory, each process may see every update of the file being mapped.

new operator

If you implement the new operator under the HP-UX 11.00, refer to “Private implementations of the new operator,” page 47 for instructions.

DCOM interoperability between NT and HP

On some HP systems, port 135 is already in use by the DCE daemon. If you need DCOM interoperability between NT and HP, you should ask your System Administrator to reconfigure the system and remove the DCE daemon. Interoperability with the DCE RPC server is under development.

Default maximum number of threads

By default, the maximum number of threads per process is 64. If your application will be using more than this amount, you must reconfigure your kernel to support more threads. You must also do this for your end-users.

3.4 HP-UX 10.20-specific Information

3.4.1 Operating System and system requirements

HP-UX 10.20 (ACE release)

3.4.2 Patches

Development patches	Description	Reason for Patch	Note
PHSS_16586	HP aC++ (aCC A.01.18) to fix numerous defects	Upgrade to C++ Compiler A.01.18
PHSS_15389	10.01 10.10 10.20 MILLI cumulative patch	Dependency of compiler A.01.18
PHSS_15380	ld(1) and some tools cumulative patch	Dependency of compiler A.01.18
PHCO_14645	libc cumulative patch	Dependency of compiler A.01.18
PHKL_15240	s700 10.20 kernel header files cumulative patch	To fix incorrect typedef of time_t	This is for HP700
PHKL_15247	s800 10.20 kernel header files cumulative patch	To fix incorrect typedef of time_t	This is for HP800

Runtime patches	Description	Reason for Patch	Note
PHSS_17872	HP aC++ runtime libraries (ACC A.01.21)	Dependency of compiler A.01.21
PHSS_15391	dld.sl cumulative patch	Dependency of compiler A.01.18
PHCO_17187	s700_800 10.20 csh(1) cumulative patch	To fix a problem that when Mainwin crashes from a calling X terminal using csh, the terminal is closed.	This is only for people using csh

3.4.3 Compiler versions

Compiler	Version	Package Name	Number
C	c89 A.10.32.20	B3899BA	B.10.20.07
C++	aC++ A.01.18	B3911DB	A.01.15

3.4.4 Using MainWin on HP-UX 10.20

Thread Support

MainWin provides the latest multithreaded GUI (X library) available for the HP operating system (HP-UX 10.20). It is located at

${MWHOME}/lib-ux10 libX11.sl

You must use this version of X library to obtain satisfactory results.

This library is included in our MW3.1 CD-ROM. Please contact Mainsoft for support of this HP Xlib. Refer to “Reporting Problems to Mainsoft,” page 69 for instructions how to contact Mainsoft support.

HP-UX 10.20 Thread Support

HP-UX 10.20 supports POSIX Draft 4 standard and user-level threading, but it does not support POSIX signal APIs (for example, pthread_kill). Consequently, MainWin on HP-UX 10.20 cannot interrupt a thread asynchronously.

Due to HP-UX 10.20’s large installed base, Mainsoft is committed to supporting this operating system.

Scheduling, Suspending, and Resuming Threads

HP’s thread-scheduling policy (no asynchronous interruption) may cause thread starvation. MainWin has therefore added support for suspending and resuming threads, using user-level thread support. MainWin’s internal thread-suspending and thread-resuming functions use a flag that is tested only when the application calls the Win32API.

For finer control over thread scheduling—to suspend a thread even though it does not call the Win32 API–call MWTestCancellationPoint(true). Calling this function causes MainWin to test the suspend flag.

MWTestCancellationPoint(true) is defined in mainwin.h, which must be included to use this function.

WGL Support with HP-UX 10.20

To use WGL with MainWin applications on HP-UX 10.20, refer to “Using WGL (Windows implementation of OpenGL),” page 45.

Read and write access in FileMapping

HP-UX 10.20 imposes severe restrictions on the use of CopyOnWrite mode in FileMapping (UNIX mmap function). Consequently, if several processes are mapping the same file into memory, each process may see every update of the file being mapped.

SystemV synchronization objects and semaphores

Since the HP operating system does not provide interprocess POSIX synchronization objects, MainWin relies on SystemV semaphores.

MainWin on HP creates at least one SystemV semaphore for each process created.

To view active semaphores, use the command ipcs. To delete a semaphore, use the command ipcrm.

new operator

If you implement the new operator under the HP-UX 10.20, refer to “Private implementations of the new operator,” page 47 for instructions.

Debugger

For best productivity, we recommend using the WDB debugger with the HP operating system, instead of XDB. This debugger is available at http://www.hp.com/lang/tools/Debuggers/WDB

DCOM interoperability between NT and HP

3.5 IRIX 6-specific Information

3.5.1 Operating System and system requirements

MainWin now supports the IRIX 6.5.4 operating system on SGI.

IRIX 6.2, 6.3, and 6.4 are hardware-specific platforms that have been superceded by IRIX 6.5.4, which supports all platforms. This version of MainWin requires updating to IRIX 6.5.4.

3.5.2 Patches

None required.

3.5.3 Compiler versions

Compiler Type	Version Number
C	7.2.1
C++	7.2.1

3.5.4 Upgrading to IRIX 6.5.4

To upgrade to IRIX 6.5.4, you must install the 6.5.4 CD or the following CDs:

· IRIX 6.5 installation tools

· IRIX 6.5 applications CD

· IRIX 6.5 foundation 1

· IRIX 6.5 foundation 2

· IRIX 6.5.4 Installation tools and Overlays (1 out of 2)

· IRIX 6.5.4 Overlays (2 out of 2)

To upgrade your compilers to version 7.2.1 of the compiler, install the following:

· IRIX 6.5 Development Libraries

· IRIX 6.5 Development foundation

· MIPS PRO 7.2.1 C++

· MIPS PRO 7.2.1 C

· ProDEv Workshop (if you wish to debug)

3.5.5 Using MainWin on IRIX

Compiler bug compiling wchar_t[ ]

A bug in the IRIX C and C++ compilers causes initialization of wide character arrays by constant strings to fail. For instance:

wchar_t foo[] = L”bar”;

fails. foo becomes null or an undefined pointer. Replace the expression above by:

wchar_t *foo = L”bar”;

Thread Support

On IRIX 6.5.4, MainWin fully supports multithreaded GUI applications.

Using ld_libraryn32_path

If you use ld_libraryn32_path instead of ld_library_path environment variable to define the path to shared libraries, make sure that also MainWin libraries are included in the path. MainWin libraries are located in $mwhome/lib/irix6_optimized and $mwhome/lib/irix6_debug.

new operator

If you implement the new operator under IRIX 6.5.4, refer to “Private implementations of the new operator,” page 47 for instructions.

DCOM interoperability between NT and IRIX

On some IRIX systems, port 135 is already in use by the DCE daemon. If you need DCOM interoperability between NT and IRIX, you should ask your System Administrator to reconfigure the system and remove the DCE daemon.

Stack overflow

The size of the main thread stack on IRIX is limited (200–300 KB). An application may cause the stack to overflow. This may happen, for instance, when registering an ATL Unicode control (using regsrv32). This problem is even more severe when compiling in optimized mode than when compiling in debug mode, as the optimizer generates additional functions that consume stack space.

Using ATL on IRIX

On IRIX, an executable cannot contain more than one ATL module. This means that you cannot insert more than one ATL control into a container; and you cannot insert an ATL control into an ATL container.

3.6 Compaq Tru64 UNIX-specific information

3.6.1 Operating System and system requirements

Tru64 UNIX 4.0e

3.6.2 Patches

Compaq Tru64 UNIX does not require patches.

3.6.3 Compiler versions

Compiler Type	Version Number
C	6.1
C++	6.2

Compaq is expected to make its V6.2 C++ compiler available in early July, 1999. Until that time, Mainsoft has made special arrangements with Compaq to make this compiler available to Mainsoft customers. Contact Mainsoft support at support@mainsoft.com for instructions for obtaining the compiler from Compaq.

3.6.4 Using MainWin on Compaq Tru64

This section presents the issues that pertain to MainWin on Compaq Tru64 systems. Topics include:

· Working around 64-bit pointer problems

· Configuring system to run MainWin

· Variables of type long

· Scope of variables in for, while, and do-while statements

· Defining wide character string as constant

Working around 64-bit pointer problems on Compaq Tru64

Background

Windows NT pointers are 32-bit; in consequence, pointers in the MainWin implementation of Windows on UNIX are also 32-bit. However, the Compaq Tru64 compiler creates 64-bit pointers by default. To get around this default, MainWin itself and MainWin rehosted applications are built using special compiler options that generate 32-bit pointer code.

Problem

The C Run-Time library that comes with the Tru64 system is not built with the above special options; in consequence, it treats all pointers as 64-bit.

This in itself is not a problem when passing or receiving a pointer to or from a LibC Run-Time function. This is a problem when passing a pointer to a pointer, or when passing an array of pointers to a C Run-Time library function.

In the following example, we call the C library function strtol and provide it with a pointer to a (32-bit) pointer:

Example¾calling the function strtol:

//File: sample.c

#include <stdlib.h>

void f()

{

char *endptr;

printf("%d\n", strtol("123", &endptr, 10));

}

When compiling the file with the MainWin build system, you will get the warning:

cc: Warning: sample.c, line 7:

In this statement, the referenced type of the pointer value "&endptr" is "short pointer to char", which is not compatible with "long pointer to char".

(ptrmismatch)

printf("%d\n", strtol("123", &endptr, 10));

-----------------------------------^

When running the application, you will get unpredictable results.

Suggested Workaround

You can modify every place in your code that calls a LibC function that expects a pointer to a pointer. However, that might require changing innumerable locations in the code. In most cases, it will be more efficient to redefine the LibC function as demonstrated in the following example.

The following example shows how to provide a wrapper for the UNIX LibC function strtol so that it will accept a 32-bit pointer instead of a 64-bit pointer.

File wrapper.h:

//File: wrapper.h

#define strtol strtol_wrapper

File wrapper.c

//File: wrapper.c

#if defined strtol

#undef strtol

#endif

long strtol_wrapper(const char *str, char **endptr, int base)

{

#include <prolog64bit.h>

char *long_endptr;

#include <epilog64bit.h>

long ret;

ret = strtol(str, &long_endptr, base);

if( endptr)

*endptr = long_ptr;

return(ret);

}

Note: prolog64bit.h and epilog64bit.h are files provided with MainWin.

File which calls strtol add:

//File: sample.c

//modified to include wrapper.h

#include "wrapper.h"

#include <stdlib.h>

void f()

{

char *endptr;

printf("%d\n", strtol("123", &endptr, 10));

}

Accessing pointers in vtables

Note: Developers who access pointers in vtables directly should be aware that pointers in vtables are always 64 bits.

Configuring Compaq Tru64 UNIX system to run MainWin

MainWin applications that use a large number of threads or that use threads requiring large amounts of memory may fail. If this occurs, you may reconfigure the system parameters to support a larger number of threads.

The following system parameters, which can be found in /etc/sysconfigtab, affect the number of MainWin threads that can be created:

Under the section vm:

vm.vm-maxvas—the amount of addressable system-wide virtual memory

vm.mapentries—the number of mmap handles allowed system-wide

vm.vm-vpagemax—maximum number of virtual pages

Under the section proc:

max-per-proc-address-space—maximum address of virtual memory per process

per-proc-address-space—address space per process

max-per-proc-data-size—maximum size of data per process

per-proc-data-size—size of data per process

max-threads-per-user—max amount of threads per user process

To set the values of these system parameters, you must have an understanding of the amount of memory resources that your application and Mainwin use.

Note: By default, Mainwin uses about 1.1 MB of memory per thread. Without changing the amount of memory MainWin allocates for each thread, the following procedure will allow you to configure the system to create up to about 1900 threads. If your application requires additional memory within a thread, it will be at the expense of the number of threads that can be created.

To make ~1900 threads available for a single process for one user, define the following values in /etc/sysconfigtab.

Under the heading vm:

vm-mapentries = 1048576

vm-maxvas = 2147483648

vm-vpagemax = 262144

Under the heading proc:

max-per-proc-address-space = 2147483648

per-proc-address-space = 2147483648

max-per-proc-data-size = 2147483648

per-proc-data-size = 2147483648

max-thread-per-user = 1900

In addition, the swap space on the system should be at least 2GB.

Explanation

The amount of address space needed for ~1900 threads of Mainwin is ~1900 * 1.1MB, which is ~2GB; therefore the addressable virtual address space per system (vm-maxvas) is set to 2GB. The same applies to the data and address space per process (max‑per‑proc‑data‑size and max-per-address-space respectively).

Note that allocating more than 2 GB of address space will not increase the number of threads that can be created. Windows is a 32-bit operating system, which can address only 2 GB of virtual memory.

Since the default page size is 8K, we need 262144 (256K) pages (vm-vpagemax) to fully utilize 2GB of address space.

Since the number of processes being run by the user is 1, we need 1900 threads per user (max-thread-per-user).

Since MainWin utilizes mmap to access certain addresses in memory, the number of mmap entries per system (vm‑mapentries) is set at 1048576 (1MB).

For more information, the following documents are available:

Digital UNIX—System Configuration and Tuning Part Number: AA-Q0R3F-TE

Digital UNIX—System Administration: Part Number: AA-PS2RE-TE

Digital UNIX—Performance Manager - Order Number: AA-QTLRA-TE

You may also consult the following man pages:

man 8 sysconfig

and

man 8X dxkerneltuner

Variables of type long

On Windows systems, variables of type long are 32 bits. On Compaq Tru64 systems, however, variables of type long are 64 bits.

To be consistent with the Windows implementation, MainWin defines a new data type LONG (all caps) that is 32 bits. All MainWin code on UNIX uses the new data type LONG instead of the native Tru64 long (which is 64 bits). To prevent data type conflicts and unexpected results, we strongly recommend replacing all occurrences of long in your code to LONG. Your Windows code will not be affected by this change.

You may also use the following data types.

Data type	Windows size	Compaq Tru64 size
LONG	32	32
ULONG (unsigned)	32	32
LONGLONG	64	64
ULONGLONG (unsigned)	64	64
NATIVE_LONG	32	64
NATIVE_ULONG (unsigned)	32	64

Scope of variables in for, while, and do-while statements

In Windows programs, scope of variables extends until the end of the program block. On Compaq Tru 64 systems, scope of variables extends only until the end of the statement for which it is defined. If you want the scope of a variable to extend beyond the (for, while, or do-while) statement, you should declare the variable outside of the particular statement.

Note: Changing the code as presented in this sample will not affect the scope when your code runs on a Windows system.

Sample code:

void f()

{

if(condition) {

...

for(int i=0; i < n; i++) {

} // On DEC, i is unavailable after bracket

...

// On Windows, i is available until end of code block

}

Solution:

void f()

{

if(condition) {

...

int i;

for(i=0; i < n; i++) {

}

...

// On Windows and DEC, i is available until end of code block

}

Defining wide character string as constant

A bug in the current version of the Compaq Tru64 compiler does not reliably differentiate strings defined with the #define directive.

#define MyFirstString L”This is a string”

#define MySecondString L”This is a different string”

It is possible that the second string will be assigned to MyFirstString instead of the first one.

We recommend that you use constant initialization and not #define to define a wide character string:

LPWSTR STR=L”This is a string”

3.7 IBM AIX-specific issues

3.7.1 Operating System and system requirements

AIX 4.3.2

3.7.2 Patches

The following patch is required to run MainWin on AIX:

IX87930

The above AIX patches are available at:
http://service.software.ibm.com/support/rs6000 .

Please read “Patch management,” page 49.

3.7.3 Compiler versions

C and C++—cset++ 3.6.4

Distribution of the cset++ 3.6.4 compiler has been discontinued. However, the compiler is included in VisualAge C++ Professional for AIX, version 4.0.

To determine which compiler version is installed on your system, issue the following commands:

uname -r

uname -v

lslpp -L | grep xlC

3.7.4 Using MainWin on AIX

Compiler path

To use MainWin on AIX, the environment variable $path must contain the path to the compiler. By default, the path to the compiler is /usr/ibmcxx/bin.

new operator

If you implement the new operator under AIX 4.3.2, refer to “Private implementations of the new operator,” page 47 for instructions.

DCOM interoperability between NT and AIX

On some AIX systems, port 135 is already in use by the DCE daemon. If you need DCOM interoperability between NT and AIX, you should ask your System Administrator to reconfigure the system and remove the DCE daemon.

4 Reporting Problems to Mainsoft

Your comments and feedback are important to maintaining the high quality of MainWin. If you have general comments or questions, please send e-mail to Mainsoft Support at support@mainsoft.com. When you contact Mainsoft, please indicate that you are using MainWin 3.3 Build 67, and include a detailed description of the issue or problem.

For serious problems or bug reports, please use the bug-reporting tool mwspr, included in the ${mwhome}/bin directory. The mwspr utility will help you collect important system information and allow you to enter specific descriptions and details of the problem.

When reporting a problem to Mainsoft, please be sure to include the following background information:

Contact information: e-mail address, fax number, and phone number

System information: hardware platform, available RAM, available hard disk space, operating system (include the version number), and Window Manager

To each report, attach a list of the libraries accessed. To obtain the list, use the following command:

mwlsl <executable name>

X display information: attach output from the xdpyinfo command.

Complete environment settings: attach output from the mwspr command.

Please take the following action when reporting a problem:

· Isolate how the problem occurred.

· Check to make sure the problem can be reproduced.

· Report steps taken to correct the problem.

· Reproduce all command-line operations.

· Include a sample that reproduces the problem, if you can.

4.1 Submitting the problem to Mainsoft

By e-mail (preferred method): support@mainsoft.com

By fax: MainWin support at (408) 774-3404

By phone: MainWin support at (408) 774-3410