64 bit ClearWin+

Introduction

ClearWin+ is accessible from third party 64 bit Fortran compilers such as gFortran. Any third party 64 bit Fortran compiler that passes character variable arguments in the same way as gFortran can be used and this includes NAGfor. In this article we will refer to any such compiler as "fx64".

The 64 bit ClearWin+ library is accessed via a DLL called clearwin64.dll. A small number of changes to the ClearWin+ code are required for fx64. Once these changes have been made the code can still be compiled and developed using FTN95.

The initial Fortran code must be Fortran 95 standard conforming. This means that FTN95 library routines that are not in the ClearWin+ library must be removed or replaced. For example CORE4(0) can not be used with fx64 whilst LOC may not be available. A number of the old FTN95 intrinsics such as RS, LS and LENG can be replaced by standard conforming Fortran 90 variants. See below for further details.

Paralled development using both FTN95 and fx64 can go hand-in-hand provided the code is kept within the Fortran 95 Standard (plus the small number of 2003 extensions permitted by FTN95). Paralled development is advisable for two reasons. First because of the debugging and CHECKMATE features of FTN95 and second because ClearWin+ error reporting is very limited when using fx64.

Primary changes required in the ClearWin+ code

There are two primary changes that are required in order to make ClearWin+ code accessible to both fx64 and FTN95.

First, ClearWin+ routines that end with the @ symbol must be changed so that they end with the $ (dollar) symbol. Thus winio@ becomes winio$, window_update@ becomes window_update$, clearwin_string@ becomes clearwin_string$, and so on. For a full list of routines see Silverfrost\FTN95\source64\clrwin.f95.

Second, ClearWin+ INCLUDE and USE statements must be changed according to the following table...

Old	New
INCLUDE <clearwin.ins>	USE clrwin$
INCLUDE <win32api.ins>	USE winapi$ (See note 1)
INCLUDE <win32prm.ins>	USE winprm$
INCLUDE <windows.ins>	USE mswin$ (See note 2)
INCLUDE <opengl.ins>	USE opengl$
USE clrwin	USE clrwin$
USE mswin32	USE winapi$ (See note 1)
USE msw32prm	USE winprm$
USE mswin	USE mswin$ (See note 2)

FTN95 versions of the new modules are provided in compiled form in the default FTN95 "Include" folder and these are automatically accessed when using FTN95.

fx64 versions of the new modules are provided in code form for you to copy to the local project folder for inclusion in the current fx64 project whilst the corresponding FTN95 project will automatically access the precompiled FTN95 modules. Alternatively you can use the supplied gFortran .mod files which are located in FTN95\include\gFortran. In this case the .o files that are associated with the gFortran modules are combined for you into a DLL called clearwin64f.dll.

Note 1: The FTN95 form of this file (and module) is a complete copy of the old, whilst the fx64 form provides only a template for further development.
Note 2: This module merely calls upon the modules clrwin$, winapi$ and winprm$ so "Note 1" also applies to the winapi$ part.

Important Note

The gFortran .mod files were created using a particular version of gFortran. If you use a different version of gFortran then you may need to rebuild the .mod files. You can do this by using your gFortran to compile the file called ClearWin64f.f95 that can be found in FTN95\Source64. Here is a suitable command line, given that gfcompiler is the name of an environment variable that provides the full path of the gFortran compiler.

%gfcompiler% clearwin64f.f95 -c -fdollar-ok -fno-range-check

Minor changes required in the ClearWin+ code

ClearWin+ occasionally uses HANDLEs that correspond to Microsoft HANDLEs such as HWND, HDC, HFONT, HBITMAP etc. These are all addresses (C pointers). So in 32 bit FTN95 they are stored in user code as INTEGER*4 variables whilst in 64 bit fx64 they require INTEGER*8 variables. For this reason the clrwin$ modules define an INTEGER KIND called CW_HANDLE that matches the environment. This means that relevant HANDLEs should be declared with type INTEGER(kind=CW_HANDLE). Note, however, that some HANDLEs described in the ClearWin+ documentation do not represent Microsoft HANDLEs and these are invariably INTEGER*4. This includes the %gr handle used in a call to select_graphics_object$.

fx64 is assumed to use Standard conforming ISO_C_BINDING in order to interface with DLLs written in C/C++ (the programming language used for the ClearWin+ library). This form of binding is used in the fx64 forms of the ClearWin+ modules.

Changes required for specific ClearWin+ format codes

Some winio$ format codes require special attention as follows...

%za %zz	These are new format codes designed for 64 bit ClearWin+. They are used to mark the beginning and the end of a format string or a sequence of format strings that use winio$ continuations. %za and %zz allow ClearWin+ to determine the lengths of the format strings without any ambiguity. %za is placed at the beginning of the first winio$ format string (in a continuation sequence) and %zz is placed at the end of the last. If winio$ is called without continuation then the two codes mark the beginning and end of the single format string. %za and %zz have no effect when using NAGfor (or FTN95). Their use for other compilers is optional because the ambiguity is not expected to be critical.
%lw	leaves the window open. If yield_program_control$ (or temporary_yield$) is not explicitly called in the program, then FTN95 has always made a hidden call this routine when the program exits. With 64 bit ClearWin+, this hidden call is not always effective so an explicit call becomes advisable and this now takes the form... CALL stop_when_windows_close$()
%eb	Some of the edit_info members are pointers so the corresponding array of integers must be replaced by a structure (TYPE(edit_info)) that is defined in the supplied clrwin.f95 used to create the clrwin$ module. If a NULL pointer is required it can be declared as... type(edit_info),pointer::EDIT_INFO_NULL_PTR=>NULL()
%ht	You can use either the existing HYPERTEXT keyword or HTML in resource scripts
%cw	External WRITE/PRINT statements (for %cw) will not work with fx64. The work-around is to use an internal WRITE (to write to a character variable) and then to call cw_write$(unit, string).
%og	Stricter type checking in gFortran means that some scalar arguments (to OpenGL functions) must be changed to one-element arrays.
%pl	has not been implemented for 64 bit ClearWin+.
%di	has occasional limitations when using the gFortran resource compiler.
%gr	Some very old routines (e.g. undocumented DBOS polygon drawing routines) have not been ported.

Parallel Development using FTN95

If your code conforms to the Fortran 95 standard then you will normally be able to use one set of source files for both compilers. However, if necessary, preprocessor directives can be used in order to handle any differences. For example, the following fragment of code could be for FTN95 only...

#ifdef FOR_FTN95
integer,pointer::C_NULL_PTR=>NULL()
#endif

In this case the FTN95 command line would include: /cfpp /vparam FOR_FTN95 1
whilst the gFortran command line would include : -cpp

Using Plato

In addition to the existing platforms: "Win32" and ".NET", Plato supports "x64". A switch in the Settings dialog allows you to compile and link using 64 bit gFortran rather than FTN95. Project "Properties" for gFortran are very limited. For ClearWin+ projects you should add references to clearwin64.dll and clearwin64f.dll (located in the FTN95 folder). Alternatively you can use clearwin64.a and clearwin64f.a for linking.

Also for ClearWin+ projects you should add "-mwindows" to the linker commands in the "Project Properties" in order to create a "Windows" executable rather than a "console" executable.

If you use a manifest file in order to provide an XP theme for your controls then you may need to change the markup code in the manifest file in order to include

For the Windows 8 operating system, the XP theme is the default, so a manifest is not needed.

Using gFortran

When running an executable produced by gFortran, calls will be made to libgfortran-3.dll. When running outside of Plato you would normally provide access to this DLL via the PATH environment variable.

Here are some FTN95 intrinsics that will need translating...

LS(i, shift) becomes ISHFT(i, shift)
RS(i, shift) becomes ISHFT(i, -shift)
LENG(str) becomes LEN_TRIM(str)
CORE1, CORE2, CORE4, FCORE4, DCORE8 and CCORE1 have been ported without change of name but cannot take a zero argument.
LOC can be used in gFortran without change.
TEST_BIT@ becomes TEST_BIT$
SET_BIT@ becomes SET_BIT$
CLEAR_BIT@ becomes CLEAR_BIT$
FILES@ becomes FILES$
GET_FILES@ becomes GET_FILES$

Deployment

Like salflibc.dll, clearwin64.dll (and clearwin64f.dll for gFortran ClearWin+ modules) can be released free of charge.

Commercial Limitation

Development of 64 bit ClearWin+ code effectively requires an FTN95 licence from Silverfrost. Otherwise ClearWin+ error reports are not transmitted to the developer.

gFortran download

64 bit gFortran can be downloaded from https://gcc.gnu.org/wiki/GFortranBinaries.