Getting started with FTN95 using Visual Studio

FTN95 is a full Fortran 95 compliant compiler for Windows and Microsoft .NET. The compiler produces a) .OBJ files for Win32 that are linked using the Silverfrost linker called SLINK, b).DBK files for .NET that are linked using the Silverfrost linker called DBK_LINK, DBK_LINK2 or DBK_LINK4 and c) .OBJ files for 64-bit Windows

FTN95 is invoked from a command line and you can work directly from the command line if you prefer (see Compiler Options on a Command Line). Alternatively you can use a variety of Integrated Development Environments (IDEs) including Microsoft Visual Studio, or Plato to create both .NET and Win32 applications.

This section focuses on how to create FTN95 applications for .NET using Microsoft Visual Studio and FTN95. For Win32 applications you must change the mode as described in Changing compiler options from Visual Studio.


Differences Between FTN95 Express and Microsoft Visual Studio

FTN95 is available in two forms: one that will integrate with existing installations of Visual Studio; and as FTN95 Express, a standalone version with an IDE based on the Visual Studio Shell. This topic outlines the major points that should be noted between versions.

  • The Compiler - The build of FTN95, the compiler itself, is the same between versions. The Fortran compiler has all the same options and capabilities no matter which version of the IDE is in use.
  • Debugging - The same debuggers are available with either FTN95 integrated into Visual Studio or with FTN95 Express. An integrated debugger is available for .NET programming and a choice of an integrated or standalong debugger is available for use with Win32 programming.
  • Help - The same help system is available for both environments, including F1, or context sensitive help.
  • Other Languages - Visual Studio usually has one or more languages built in. Using Visual Studio, the developer can write mixed langauge solutions, say with one solution written in C# and another written with FTN95. If using FTN95 Express Fortran is the only language available. While FTN95 Express can be used to interoperate with other languages (say by adding a reference to an existing .NET assembly and then calling methods contained within it) it cannot be used to author multi-language solutions.
  • File Formats - All versions use the same file format to store information. An FTN95 project file written using Visual Studio can be used with FTN95 Express (and Plato 3 also). Note that the solution file extension is different between Visual Studio and FTN95 Express (FTN95 Express uses the extension .fsln). If migrating projects between Visual Studio and FTN95 Express then the solution should be recreated and the existing project files added.


Software and hardware requirements

Microsoft .NET requires Windows XP, Windows Server 2003, Windows Vista, Windows 7 or Windows Server 2008.

Microsoft Visual Studio requires various operating systems depending on the version of Visual Studio in use. Silverfrost FTN95 Express requires Windows XP or Windows Vista.

Before working through this section you should install the latest version of Microsoft .NET and the latest version of Silverfrost's FTN95 which includes a Fortran 95 compiler, an integrated debugger and a Microsoft Visual Studio integration package or FTN95 Express.

Microsoft Visual Studio is a substantial application that runs very slowly on old hardware. A minimum of a 50 GB hard drive is recommended together with a modern processor and at least 1024 MB of RAM. Your display must be set to a minimum of 800x600 pixels.

After installing FTN95, the Silverfrost logo should be visible on the splash screen when starting Visual Studio. You should also ensure that there is an entry for FTN95 for .NET in the About Microsoft Development Environment dialog obtained from the main Help menu. Part of this dialog is shown below. Depending on the version of Visual Studio in usage or if using FTN95 Express then this dialog may look different.

If integrating with Visual Studio then the 'standard' version of any version is required. FTN95 does not integrate with any of the Microsoft 'Express' line of products, but does come in its own Express version, with Fortran as the only language supported in the environment.

Please note that in the .NET architecture Microsoft configure the CPU to operate at 64-bit precision. This can result in slight numerical differences when FTN95 .NET calculations are compared with Win32 calculations.


Fortran programming with Microsoft .NET

Microsoft .NET provides a powerful development environment. Features of particular interest to the Fortran programmer include:

1. The potential for multi-platform executables and graphical user interfaces.

2. Coordinated mixed language programming using for example Visual Basic .NET and C#.


Basic features of Visual Studio

Microsoft Visual Studio is an integrated development environment. It includes text editors for programs and image editors for various kinds of image resources such as bitmaps, icons and cursors.

The program files for a particular executable (for example) are grouped together into what is called a project. Within Visual Studio you can build a project (to create the executable). The designated compiler is automatically invoked and compilation error messages are easily tracked. After a successful build the executable can be run from within Visual Studio.

During development a given FTN95 project can be configured to be in debug mode or Checkmate mode, whilst release mode is designed for final shipping. Checkmate mode switches on Silverfrost's Checkmate. This provides run-time checking features. The debug and Checkmate modes also allow you to step through the program code line-by-line, setting break points, running to the cursor position etc. as required.

The FTN95 for Microsoft .NET Visual Studio integration package also provides integrated and dynamic help facilities.


Using Visual Studio

The basic object in Visual Studio or in FTN95 Express is a solution. A solution is a group of projects. This might for example include a project to create an executable, another to create a help file and a third to create an installation package for both the executable and the help file. In this guide it is assumed that a solution consists of just one project to create an executable based on a Fortran program. Note that images shown in the help are for Visual Studio 2005, but the same principals apply to Visual Studio 2005, 2008 and 2010.

When you start up Visual Studio for the first time you will see a Start Page in what we shall refer to as the client area. If using FTN95 Express, the start page looks different to that shown above, but provides links to create new projects, open exisiting projects and to visit the Silverfrost website. There are three other windows of interest at this stage. If any of the following windows are not visible then they can be shown by selecting them from the main View menu.

The Solution Explorer dialog

If the Solution Explorer window is not visible, select Solution Explorer from the main View menu. Initially we shall use this to view the project files.

The Solution Explorer window is just one of a number of tabbed windows that appear in this dialog. For example, the dialog is also used for the Help Contents, Help Index and Help Search windows.

By double clicking on the banner, the Solution Explorer dialog can be "undocked" to become a free floating dialog. This also applies to the two other dialogs introduced below.

The Output dialog

The Output window may not be visible initially but it will appear when there is output to view. This might be the output from a build process for example.

The Output window is just one of a number of tabbed windows that appear in this dialog. For example, the dialog is also used for Find Results and for the Task List.

The Properties dialog

If the Properties window is not visible, select Properties Window from the main View menu. We shall use this window later to view and change the properties of our Fortran files.

The Properties window is just one of a number of tabbed windows that appear in this dialog. In particular, the Dynamic Help window is usually positioned here also.

Note that all images on this help page and throughout the help system are from Visual Studio 2005, the appearance inside Visual Studio .NET 2003, Visual Studio 2008 and FTN95 Express may differ slightly.


A simple Fortran project

In order to get started we shall create a new project containing a very simple Fortran program. Select New and then Project from the main File menu.

Select FTN95 Projects from the Project Types. We shall call the project Project1. Choose a Location (that is a folder) for the project. Click on the OK button to create the project.

A new project is created which initially contains one file called FreeFormat1.f95. If you wish you can change the name of the file in the Solution Explorer window but we shall use the default name. To add other files to the project, in the Solution Explorer window, use the right mouse button to click on the Project1 item and then select Add New Item from the resulting popup menu.

Note the Build menu item in this popup menu that we shall use in a moment. Note also the item in the tree called References. This is used to provide references to additional libraries and DLLs when they are needed in the linking process. Further information can be found in the Visual Studio help contents and index. Select the type of the source file in the resulting dialog box and click on Open to create the file and to add it to the project.

Open FreeFormat1.f95, delete the default text and type in a simple program.

Now click on Build in the Solution Explorer popup menu (see above). The program is automatically compiled and linked and any error messages are reported in the Output window. After a successful build you can run the program by selecting Start without debugging from the main Debug menu (Ctrl+F5).

Tracking compilation error messages

If your program contains compilation errors, these appear as a Task list in the Output dialog. Double click on the build icon or the red exclamation icon in order to go to the error in the client area.

Changing between modes

When a project is created it is automatically set to be a .NET application in Debug mode. In order to change the mode, select an item from the Solutions Configurations drop-down list on the main toolbar.

Or select Configuration Manager from this list.

Choose a mode using the box at the top entitled Active Solution Configuration. Click on the arrow icon and select a mode from the drop down list. Release mode can be selected when a solution is ready for use/shipping. The debug and Checkmate modes plant debugging code that allows you to step into the code using the integrated debugger. The Checkmate mode is recommended for development.

The default configuration at project level reflects the Active Solution Configuration and should be left unchanged.

Note that you can also change from .NET to Win32. Most of the features of Visual Studio can be used to create Win32 as well as .NET applications and DLLs. You can even use ClearWin+ together with the Visual Studio image and dialog editors if you wish. The main difference is that, when the mode is set to Win32, a choice of debuggers is available. Win32 applications can be debugged using an integrated Visual Studio debugger or SDBG.

Using the debugger

The simplest way to get started using the FTN95 for .NET debugger is to set the cursor on a line in the program, click on the right mouse button and select Run to Cursor from the popup menu.

If you wait a few moments without touching anything you will get the following display.

Now press F10 to step over a line at a time viewing the changes to local variables as you proceed.

In addition to the display in the Locals window, you can also view the value of a variable by allowing the mouse cursor to hover over a point where the variable is used in the program. This causes a tooltip popup window to appear. This contains the value of the variable.

Another method is to click on the Watch 1 window and then click on the first cell in the Name column. Now type in the name of a variable you want to watch. The Quick Watch window is also useful. Select Quick Watch from the popup menu or from the main Debug menu. A Watch window is particularly useful when tracking non-local variables.

The call stack can be viewed from the Output dialog.

Once you are familiar with these basic methods, you can begin to experiment by setting break points and stepping into and out of procedures.

Changing the compiler options

So far we have used the default compiler command line options based on Checkmate. Options for a project can be changed from the Project Properties dialog. Click with the right mouse button on the Project1 item in the Solution Explorer window.

This displays the Project Properties dialog that contains a section like that shown below. Change the entries in this dialog in order to configure the project as a whole.

The Output File Type is one of EXE, DLL and MDL.

When using Visual Studio 2005, Visual Studio 2008 or Visual Studio 2010, an option is present to select the .NET Framework version to target. 4.0 and 2.0 are available.

The linker options can also be changed from this dialog box. To do this select Linker Options from the tree on the left hand side (see Using the linker in Visual Studio).

When your project contains a number of files, you can set different command line options for a particular file by using the File Properties window as follows.

Click with the left mouse button on the file freeformat1.f95 in the Solution Explorer window (or use the right mouse button and select Properties from the popup menu). Now look at the Properties dialog that normally appears below the Solution Explorer dialog. If the Properties Window is not visible, select Properties Window from the main View menu.

On the CustomCompilerOptions line, click on Off and the resulting arrow icon in order to view the options to Append to or Override the global project options. Now type in the options in the box labeled CustomSwitches. For example, if the project is set to debug rather than Checkmate mode then a particular file might be set to Checkmate using this option.

For further information see Changing compiler options from Visual Studio.


Using multiple files

As your project grows, you will naturally add more files to it. The build process automatically checks for file dependency resulting from the use of Fortran modules and included files. For example, if a file A uses a module B in another file and module B is changed then file A is automatically recompiled. For complete safety you can select Rebuild rather than Build and all the source files will be recompiled. Note that, by default, project files are automatically saved at the start of a Build/Rebuild process.

You can also compile a particular file by selecting the file in the Solution Explorer window and by clicking on Compile in the popup menu.

Please note that this feature is not available in Microsoft Visual C# .NET. You can still compile a particular file by modifying it's contents and selecting Build from the Project menu.

In addition to Build and Rebuild there is also a command called Clean. This command deletes all the object files together with the executable (or DLL).

You can issue these commands from the Solution Explorer window by selecting the name of the project and using a right mouse click. If you select the name of the solution rather than the name of the project, then the command is applied to all the projects in the solution. The Build command for a solution will act upon file dependencies that span more than one project.


Help facilities

Searching for Help topics

In addition to the dynamic help facility you can also search for help on a given topic. If the Search window is not visible in the Solution Explorer dialog, select Search from the main Help menu.

Type in the item to look for and select the Silverfrost FTN95 filter. When you click on the Search button results are displayed in the Output dialog. Note that if using Visual Studio .NET 2003 the help system appears diffrerently. The image above corresponds to the help system in use with Visual Studio 2005.

Method tips and bracket matching

A method tip is a tooltip popup window that automatically appears when you type an open round bracket after the name of a procedure.

Method tips provide information about the arguments required by the procedure.

Bracket matching automatically occurs when you type in a matching closing bracket with the result that the included code is displayed in bold font.

Dynamic and F1 help

If the Dynamic help window is not visible select Dynamic Help from the main Help menu. A link to a help topic will appear in this window when you type a recognised procedure name in the program. Alternatively you can place the text cursor on the name and press F1. This automatically opens the Help Index window and selects the name in the index. Press Enter to view the help topic.

Navigating through the code

The simplest way to navigate through the code is to use the drop-down lists that are displayed at the head of the code window.

The left hand list includes "(Globals)" together with the names of any modules that are in this file. "(Globals)" includes the main program (if present) and any external subroutines and functions. When a selection is made from this list, the list on the right of it is automatically populated with the corresponding subroutines and functions. When a selection is made from the list on the right, the code window scrolls to show the selected subprogram.


Popup menu and toolbar facilities

The following facilities can be selected from the popup menu that appears when you do a right mouse click in the program code.

Outlining

Visual Studio has an outlining facility that can be very helpful when reading and editing large amounts of code.

To begin, select Outlining and then Collapse to Definitions from the popup menu in the program code. Now click on the Plus icon that appears in the outlined program. Click on the other Plus icon that comes into view in order to view the DO loop that is shown in the illustration.

Unnamed Bookmarks

Unnamed bookmarks provide a simple and convenient method to mark points in the code so that they can be returned to later. The standard toolbar provides buttons to add and navigate through unnamed bookmarks. Unnamed bookmarks are project settings that Visual Studio keeps for you from one work session to the next.


File management

The Visual Studio .NET Start Page can be used to open an existing project and to create new projects. If this page is not visible, select Tools from the main menu and then Options. In tree on the left of the dialog select Environment and then General. Finally, in the At Startup box at the top of the right hand side of the dialog select Show Start Page. If using the Express version of FTN95, then the start page can be shown by navigating to View and then Other Windows, then select the Start Page.

In addition to the Start Page, you will also find a list of Recent Files and Recent Projects in the main File menu.

Visual Studio can be used to edit Fortran files without adding them to a project. Such files will exhibit syntax colouring, method tip and dynamic help and outlining, but they cannot be compiled within Visual Studio. In order to open a file, click on the Open File button on the main toolbar. Now using the standard Open dialog box, select files of type FTN95 Files in the combo box.

Now navigate through the directories and select the file that you want to open.

Alternatively you can open a Fortran file from Explorer either by double clicking on the file or by dragging the file and dropping it on to Visual Studio.


Visual Studio options

Select Options from the main Tools menu in order to open the Options dialog. Here are some of the settings that you may wish to change.

Fonts and colours

From the tree on the left, select Environment and Fonts and Colors. In the Display items, find the syntax colour names beginning with FTN95.NET. You can change the foreground and background colours to suit your personal taste. You can also select a different fixed-width font.

Line Numbers and tab settings

You can opt to view line numbers in the margin of your programs. From the tree on the left of the dialog select Text Editor then All Languages and General. Now find the Line numbers check box.

In the Text Editor section you will also see entries for Fortran77 and Fortran95. Use these sections to change the tab behaviour and settings.


Find and replace

Find and replace tools are accessed from the main Edit menu.


Working from the command line

See Compiler options on a command line.


Getting started with FTN95 using Plato

FTN95 is a full Fortran 95 compliant compiler for Win32 and Microsoft .NET. The compiler produces a) .OBJ files for Win32 that are linked using the Silverfrost linker called SLINK and b) .DBK files for .NET that are linked using the Silverfrost linker called DBK_LINK.

FTN95 can also produce 64 bit object code files for x64 that are linked using the Silverfrost linker called SLINK64.

FTN95 is invoked from a command line and you can work directly from the command line if you prefer (see Compiler Options on a Command Line). Alternatively you can use Plato to create Win32 applications. For .NET applications you are recommended to use Microsoft Visual Studio.


Basic features of Plato

Plato is an integrated development environment. It includes a text editor with syntax highlighting for various languages including Fortran and C++, unlimited undo, and project managment facilities. Plato is designed to have the same look and feel as Microsoft Visual Studio. The project management facilities replicate the Silverfrost FTN95 plug-in for Visual Studio. You can use project (.ftn95p) files created with Plato in Visual Studio and vice-versa.

The program files for a particular executable (or DLL) are grouped together into what is called a project. Within Plato you can build a project (to create the executable). FTN95 is automatically invoked and compilation error messages are easily tracked. After a successful build the executable can be run from within Plato.

During development a given FTN95 project can be configured to be in debug mode or Checkmate mode, whilst release mode is designed for final shipping. Checkmate mode switches on Silverfrost‘s Checkmate. This provides run-time checking features. The debug and Checkmate modes also allow you to step through the program code line-by-line, setting break points, running to the cursor position etc. as required.

If you open a second project without closing the first then you are given the option to combine the two into a solution. Plato solutions are not portable to Visual Studio. Plato will not automatically build a whole solution for you. You must build each project in turn, in the appropriate order.

Plato also provides integrated help facilities.


Using Plato

The basic object in Plato is an FTN95 project. Typically a project is used to create a Fortran executable or DLL.

Plato uses two modeless dialog boxes for project managment. A modeless dialog is one that can be left open whilst continuing with other tasks in Plato. A third modeless dialog is used for "Find and Replace" instructions.

The Project Explorer dialog

The Project Explorer dialog becomes visible when you open an existing project or create a new project. If it is not visible, select Project Explorer from the main View menu. We shall use this window to manage the project files.

The Project Explorer dialog can be "undocked" to become a free floating dialog. This also applies to the Output dialog introduced below. To undock a dialog, click once on the size bar (on the left hand border when the dialog is docked on the right hand side). You can prevent unwanted docking by holding down the Ctrl key whilst moving the window.

The Output dialog

The Output window may not be visible initially but it will appear when there is output to view. This is typically the output from a build process. The Output window is also used for the results of a "Find in Files" process.

Unlike Visual Studio, in Plato the Properties dialog is not modeless. You can use this dialog to change the properties of your Fortran files.


A simple Fortran project

Single Fortran files can be compiled and run without creating a project. Simply open the file and press Ctrl+Shift+B to build and then Ctrl+F5 to run or use a right mouse button click and select Run to Cursor. You can change the associated compiler options using the Options dialog selected from the main Tools meanu.

When this approach is inadequate you will need to create either a project shell or a full project as follows.

In order to get started we shall create a new project containing a very simple Fortran program. Select New Project from the main File menu.

a) Select the Project Type.

b) Browse to an existing folder to hold your project source files or type in the Location of a new folder.

c) Type in the Name of the project file (we shall call this Project1). The extension (.ftn95p) will be added for you. For simplicity the project file name can be the same as the name of the folder. It will also be the default name of the target (the executable or DLL).

d) Click on the Open button to create the project.

Now we add a new item to the project. In the Project Explorer window, use the right mouse button to click on the Project1 item and then select Add New Item from the resulting popup menu.

Note the Build menu item in this popup menu that we shall use in a moment. Note also the item in the tree called References . This is used to provide references to additional libraries and DLLs when they are needed in the linking process. Select Free format source file in the resulting dialog box and type in a name for the file (we shall call this freeformat1.f95). The location is normally the project folder. Click on Open to create the file and to add it to the project. The file will be opened for you.

When the child window is maximised its name appears on a Files bar. If the Files bar is not visible, select Files Bar in the main View menu.

Type in a simple program.

Now click on Build in the Project Explorer popup menu (see above). The program is automatically compiled and linked and any error messages are reported in the Output window. After a successful build you can run the program by selecting Start from the Project Explorer popup menu (or press Ctrl+F5).

Tracking compilation error messages

If your program contains compilation errors, these appear in the Output dialog. Double click on an error line in order to go to the error in the source file.

Changing between modes

When a project is created in Plato it is automatically set to be a Win32 application in CheckMate mode. In order to change the mode, use the Configuration drop down list on the main toolbar.

Release mode can be selected when a solution is ready for use/shipping. The Debug and Checkmate modes plant debugging code that allows you to step into the code using the Silverfrost Win32 debugger (SDBG) which is automatically called by Plato. The Checkmate mode is recommended for development.

Note that you can also change from Win32 to .NET. However, for .NET it is better to use Microsoft Visual Studio because the Silverfrost plug-in for Visual Studio provides an intergrated debugger for .NET.

The simplest way to get started using SDBG is to set the cursor on a line in the program, click on the right mouse button and select Run to Cursor from the popup menu.

This launches SDBG and sets a break point at the cursor position. You can then use SDBG to view the local variables, step through the program, etc. For further information see Using SDBG.

Changing the compiler options

So far we have used the default compiler command line options based on CheckMate. Options for a project can be changed from the Project Properties dialog. Click with the right mouse button on the Project1 item in the Project Explorer window and select Properties.

This displays the Project Properties dialog that contains a section like that show below. Change the entries in this dialog in order to configure the project as a whole.

The Output File Type is one of EXE, DLL and MDL.

The linker options can also be changed from this dialog box. To do this select Linker Options from the tree on the left hand side.

When your project contains a number of files, you can set different command line options for a particular file by using the File Properties window as follows.

Click with the right mouse button on the file freeformat1.f95 in the Project Explorer window and select Properties from the popup menu.

From the Custom compiler options drop down list you can opt to Append to or Override the global project options. Now type in the options in the box labeled Custom switches. For example, if the project is set to debug rather than Checkmate mode then a particular file might be set to CheckMate mode with the following entry.

Creating a Solution

You can combine more than one project into a Plato Solution. For example, you could combine a project to create a Fortran executable together with a project to create an associated DLL that is called by the executable.

If a project is open and you then open or create another project, you are prompted to either close the existing project or create a Solution that includes the two projects. Further projects can then be added to this solution. Existing solutions can also be opened directly from the Open Project dialog.

The Project/Solution Explorer window will display the project for the currently active file. Alternatively you can right click on the current project node in the Explorer window and the popup menu provides options to view another project or remove the current project from the solution.

Plato does not provide a mechanism to build a solution as one action. You must select each project in turn and build them separately and in the right order.

Creating additional source file folders

The Project Explorer window automatically provides a node for Source Files, for Include Files and also for Resource Files. The Include and Resource File folders are automatically populated by Plato whilst you have control over the files to add to the list of Source Files.

Also you can add named folders for new grouping of your source files. Simply right click on the project node and select Add New Folder, then click on the default folder name in order to change the name to your choice. Source files can then be dragged from one folder to another.

Note also that a source file can renamed by selecting the node for the file and then using a siingle click on the node to begin editing the name. Click elsewhere to end the edit.


Using multiple files

As your project grows, you will naturally add more files to it. The build process automatically checks for file dependency resulting from the use of Fortran modules and included files. For example, if a file A uses a module B in another file and module B is changed then file A is automatically recompiled. For complete safety you can select Rebuild rather than Build and all the source files will be recompiled (for further information see File dependency). Note that, by default, project files are automatically saved at the start of a Build/Rebuild process.

You can also compile a particular file by selecting the file in the Project Explorer window and by clicking on Compile in the popup menu.

In addition to Build and Rebuild there is also a command called Clean. This command deletes all the object files together with the executable (or DLL).

You can issue these commands from the Project Explorer window by selecting the name of the project and using a right mouse click.


Using gFortran or iFort

If an x64 gFortran or iFort compiler is installed on your computer, it can be used for the x64 platform instead of the Silverfrost Fortran compiler FTN95.

The alternative compiler is activated by selecting "Fortran compiler for x64" from the main Build menu (Alt+X). This opens a dialog that provides a choice between FTN95, gFortran amd iFort. This dialog can be kept open. It displays a Settings button and a Properties button that open other dialogs. The Settings dialog provides the paths that Plato requires in order to run the alternative compilers. When gFortran is installed via mysys64 and iFort is installed via Intel OneAPi, these typically take the following forms (details will vary as new versions of the compilers are released)...

gFortran path | C:\msys64\usr\bin
gFortran compiler | gfortran.exe
Path to bin\intel64\iFort.exe | C:\Program Files (x86)\Intel\oneAPI\compiler\2021.2.0\windows\
iFort Community path | C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30037\
iFort Bin Kit path | C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\

The gFortran path is optional and should be left blank when the gFortran compiler can be accessed via the PATH environment variable. The gFortran compiler defaults to the name shown above.

In order to use an alternative compiler, the x64 platform must be selected from the platform options on the main toolbar. With the x64 platform selected, any of the configurations Debug, Release and Checkmate can be selected. Checkmate is a trademark of FTN95. For the alternative compilers, Plato will use relevant checking options as follows.

Single file mode

Plato uses a fixed set of command line options depending on the configuration selected. These can be viewed from a BuildLog file after compiling and linking.

Project mode

The command line options used by Plato can be viewed and potentially changed by clicking on the Properties button in the x64 dialog. These options act independently of the corresponding FTN95 options which will remain in place, except for the name of the executable or DLL, its extension (.exe or .dll) and the type of the subsystem (console or Windows). These are inherited from the FTN95 properties.

Note that default linker options are provided for Intel Fortran in the form of a list of .lib files that are typically required for an Intel Windows application. These are not needed for an Intel console application. Note also that iFort.exe is used for linking (as well as compilation) and linker options are passed on to a Microsoft linker. This usually means that iFort linker options must be prefixed by "/Qoption,link,/". For example, the option supplied by Plato for a Windows application for Intel Fortran is "/Qoption,link,/subsystem:windows".

Plato uses subfolders for the object files etc., one for each platform. As a result a rebuild is generally not required when changing from one platform to another. The name of the x64 subfolder is normally "x64" but for gFortran this becomes "x64g", whilst for iFort this becomes "x64i". The .mod files are compiler dependent so Plato directs them (together with .obj files) to the relevant subfolder The exception to this rule is the FTN95 compiler because in this case the mod files are given the extension .mod64 rather than .mod.

ClearWin+

See Using ClearWin+ with third party Fortran compilers.

ClearWin+ interface source files (located in FTN95\Source64) can be imported into a project by selecting Import Items from the main Project menu or by right clicking on Source Files in the Project Explorer window. This will copy the selected files and the modules can then be USEd in the program code. Copying the ClearWin+ interface files will ensure that the resulting .mod and .obj files relate to the selected compiler and its version number.

Note that, by default, FTN95 does not allow the compilation of modules with names ending with $. The command line option /DOLLAR_MOD over-rides this default and is required when compiling modules such as clrwin$ which appears in files that are copied from FTN95\Source64\clrwin.95.


Help facilities

Bracket matching

Bracket matching automatically occurs when you place the text cursor after a bracket. This feature must be switched on using the Options dialog selected from the main Tools menu. The colour and attributes of the matching brakcets can be changed in the Fonts and Colours section in the Options dialog.

F1 help

Keyword help is provided when you place the text cursor on a word and press F1. This automatically opens the FTN95 Help file and selects the word from the index.

"What's this" help

Most dialogs have a question mark icon on the caption bar. Click on this icon and then on a control in the dialog to obtain "What's this" help.


Editing facilities

Outlining

Plato has an outlining facility that can be very helpful when reading and editing large amounts of code. To switch outlining on, select Options from the main Tools menu and then select Text Editor and General. Outlining is not currently available for fixed Fortran source code.

Unnamed Bookmarks

Unnamed bookmarks provide a simple and convenient method to mark points in the code so that they can be returned to later. The standard toolbar provides buttons to add and navigate through unnamed bookmarks.

Bookmarks are saved with the project data. See also Using named Bookmarks.

You can also move back to a previous viewing context in the code by using the command "Undo move" (Ctrl+Shift+Z by default). This is designed on the basis of bookmarks that are automatically attached to each line of the code that has been visited. "Undo move" therefore takes you back to the last line that you visited and can be repeated in usual manner for undo commands. The command "Redo undo move" (Ctrl+Shift+Y by default) is also provided.


File management

Plato can be used to edit Fortran files without adding them to a project. Such files will exhibit syntax colouring but (within Plato) they can only be compiled and built as stand alone files. In order to open a file, click on the Open File button on the main toolbar. Now using the standard Open dialog box, select Fortran files of type Free format or Fixed format from the drop down list.

Now navigate through the folders and select the file that you want to open.

Alternatively you can open a Fortran file from Explorer either by double clicking on the file or by dragging the file and dropping it on to Plato.

The double click event requires Plato to be linked to Explorer for opening Fortran files. To provide this link you can select "Register Fortran file types for Explorer" from the Plato Options dialog (on the main Tools menu) or you can use Explorer to change the Folder options (using the Tools menu item in the main Explorer menu).


Debugging

Plato can be used to launch the Win32 debugger called SDBG. In order to debug code for .NET you must use Visual Studio.

If your application uses command line arguments and you need to pass them to SDBG then it is simpler if you create a project (even when there is only one file).

From a project

If you are working with a project, first select either CHECKMATE or DEBUG mode and build the project. Then there are two basic ways to launch SDBG:

a) In the Explorer Window, right click on the name of the project and select Step Into. This starts up SDBG and sets a break point at the first executable statement,

b) In the code window, right click on a line and select Run to Cursor. This starts up SDBG and sets a break point on the given line.

To pass command line arguments to SDBG, select Properties from the Project menu and under the Miscellaneous section of Compiler Options, set the Launch arguments.

Single file - no project

If you are working with a single file (with no project open) first build the file using compiler options (such as /CHECKMATE) that plant debugging code. The build command can be found on the main Build menu. The compiler options (for use when there is no project open) are set in the Options dialog under Environment, and General.

Then, in the code window, right click on a line and select Run to Cursor. This starts up SDBG and sets a break point on the given line.

Controlling the debugger from Plato

The process of stepping through the code in the debugger can be controlled from Plato by using the Build toolbar...

If you cannot see this toolbar, use the View menu to make it visible.

You can also set breakpoints from Plato by pressing Ctrl+Shift and clicking in the margin of the appropriate line. If the debugger is not running, invalid breakpoints are cancelled when the debugger is started.

Additional integration with the debugger can be switched on from the Options dialog (select Tools, Options and then General). This causes the file viewing in SDBG to be reflected back to Plato. This means that you can view the code with its syntax colouring. Files that are automatically opened for viewing are also closed when debugging ends. Changes to the code cannot be made whilst debugging. When hovering over a variable in the source code, a tooltip shows its value. Double clicking on a variable displays its value in a new window whilst doing this with the control key down will add the variable to the Watch window.


Plato options

Select Options from the main Tools menu in order to open the Options dialog. Here are some of the settings that you may wish to change.

Fonts and colours

From the tree on the left, select Environment and Fonts and Colours . You can change the foreground and background colours to suit your personal taste. You can also select a different fixed-width font.

Opening Fortran files from Explorer

If you select Environment and General from the tree, you can opt to "Register Fortran file types for Explorer". This plants information into the Registry that is used by Explorer. Opening a file in Explorer will cause it to appear in Plato.

Note

a) If you have installed Microsoft Visual Studio and you are using a Fortran plugin, then you can register Fortran file types for Explorer with Plato but, if you cancel this option, when you use Visual Studio you will be prompted to re-install the plugin.

b) To remove all Plato registry entries use the command line:
Plato /Unregister

Line Numbers and tab settings

You can opt to view line numbers in the margin of your programs. From the tree on the left of the dialog select Text Editor then General. Now find the Line numbers check box.

In the Text Editor section you will also see an entry for Tabs and Indents. Use this section to change the tab behaviour and settings.


Basic editing

The Plato source code editor uses standard keyboard and mouse operations such as those found in Microsoft Word for Windows. Here is a summary of the basic features.

Opening a file: You can open a file by using the the Project Explorer window, by using the standard Open dialog or by using Explorer.

Moving the cursor: Use the arrow keys or the mouse to position the caret (the text cursor) at a point in the source code.

Popup menu: Click on the text with the right mouse button in order to generate a popup menu.

Selecting text: Hold down the mouse button and drag the mouse to select a section of the text. This text can then be copied or cut to the clipboard by using the Edit menu. The same text can then be pasted to another point in the text. Alternatively you can click at one end of the required selection, hold down the Shift key, and then click at the other end of the required selection. A selection can be dragged and moved to another point in the text or dragged and copied by holding down the Control key.

By default the caret can only be positioned within the existing text. If you click past the end of a line then the caret position is adjusted to the end of the line. However, if you hold down the Ctrl key and click past the end of a line, then the caret becomes free and spaces are automatically inserted when you next type a character or paste some text.

A column of text can be selected by holding down the ALT key and dragging with the mouse. A selection can then copied, cut or deleted. Columns can be exported to and imported from Microsoft Visual Studio by using the Clipboard.

Selecting a word: Double click on the word (Ctrl+U and Ctrl+Shift+U change its case) or use a single click holding down the Control key.

Extending a selection: Hold down the Shift key and use the direction keys or the mouse to extend a selection.

Home and End: Home takes you to the beginning of the current line whilst Ctrl Home goes to the beginning of the file. End takes you to the end of the current line whilst Ctrl End goes to the end of the file. Using Shift extends a selection.

Page Up and Page Down: These keys scroll up and down by a number of lines depending on the current size of the edit window.

Delete and Backspace: Delete deletes the character after the cursor whilst Backspace deletes the character before the cursor. If a block of text is selected then Delete deletes the whole selection (it does not cut to the clipboard).

Right and Left arrow: Using the Control key moves to the beginning of the next or previous word. Using Shift extends a selection.

Automatic indentation : A linefeed is followed by automatic indentation. To suppress automatic indentation use Shift+Enter.

Using the margin: You can use the margin to select a single line or a block of lines by dragging the mouse. You can select one line and then (holding down the shift key) select another to select a block. Use the Ctrl key to select all the lines (or press Ctrl+A). Ctrl + Shift + click is used to set and reset a break point.

See also Keyboard accelerators and Creating and using macros.


Editing Image Files

Plato provides basic image editing for bitmaps, icons and cursors but with some limitations.

1. The undo feature is robust but potentially demanding on memory so when editing images the length of the undo list is limited. If you continue to make changes beyond the limit then the oldest operations in the undo list are lost. This limit can be configured via the "Tools" menu under "Options" and then "Image editor". Also, for the same reason, the undo list is cleared every time the file is saved. A warning appears on the status line when the undo limit is near and a "Save" becomes advisable.

2. Plato image editing does not include a facility to add text to an image. In order to add text you could use the Microsoft Paint utility to create the text, copy it to the clipboard and then paste it into your Plato image edit.

3. Editing bitmaps using Plato does not provide any advantages over using the Microsoft Paint utility. Also, for icons and cursors, you may be able to find better freeware editors online.

If your project includes a resource script or a RESOURCES section after the main program then the component resource files become dependent files and are treated like INCLUDE files. This means that the dependency checking automatically adds the component files under the heading of "Resources" in the Project Explorer window. If you are using a resource script then you must add it to the list of source files so that Plato will compile it using the SRC resource compiler.

Main editing features

a. Use a left mouse click on the palette in order to select a colour for use with the left mouse button when editing. This colour is shown in a box to the left at the bottom of the palette.

b. Use a right mouse click on the palette in order to select a colour for use with the right mouse button when editing. This colour is shown in a box to the right at the bottom of the palette.

c. Use the pencil tool and hold down the shift key in order to select a pixel colour back from the image to the palette.

d. Use a right mouse click at other points in the palette to get a popup menu. This allows you to select the zoom, brush size and screen and inverse colours.

e. Bitmaps (but not icons and cursors) can be resized by dragging the right and bottom edges.

f. Icons and cursors can have multiple device images (i.e. more than one size and pixel depth). These are accessible via a button on the toolbar.

g. Cursors have a "hotspot". Use the relevant button on the toolbar to select a tool before seting the hotspot.

h. After selecting a rectagle with the "select" tool, you can drag the selection to another part of the image. If you also hold down the control key then the original selection is not cleared. If you hold down the shift key then the original selection is cleared to the currently selected (left) colour.

i. RGB boxes in the palette show the current colour values for the left button. These values can be changed directly but only if the image has more than 256 colours.

j. 256 colour images that are created in Plato can be created with one of three default palettes (Standard, Web safe or Grey scale). 256 colour images created elsewhere can be edited in Plato with their own palettes.

k. Monochrome images are displayed alongside a grey-scale palette but the fill patterns are monochrome with varying densities of back and white pixels.


Editing HTML Files

Plato provides direct access to the standard Microsoft HTML editor.

When you open or create an HTML file (with extension .html or .htm) initially it will be displayed in source form showing the markup codes. In order to display the file as it would be seen in a web browser, you need to right click on the name of the file in the tab bar and select "Show Web View".

The web view provides a WYSIWYG editor that you can use to insert text, change the font etc. but with certain limitations...

a) The "undo" history is not linked up between the source view and the web view. This means that you ought to save your changes when changing the view.

b) The Microsoft editor automatically adds <!DOCTYPE ...> and <META name=GENERATOR...> markups that might be unwanted.

c) Cascading style sheets and images etc. will be implemented/viewed but only when the associated file path is not relative (that is, you should provide the full path if the associated file is not in the same folder as the source file).

d) Simple tables can be inserted but currently there are no table editing facilities in Plato.


Standard keyboard accelerators

By default Plato uses standard accelerators keys that conform as far as possible with the default Microsoft Visual Studio settings. See also Changing keyboard accelerators. Here is a table of standard accelerator keys.

Ctrl+A | Select all
Ctrl+B | Rebuild the project
Ctrl+C | Copy selected text to the clipboard. Copy the line if there is no selection.
Ctrl+F | Find text
Ctrl+G | Goto line number or named bookmark
Ctrl+H | Find and replace
Ctrl+L | Select current line and cut
Ctrl+N | Create a new document
Ctrl+O | Open an existing file
Ctrl+P | Print the current document
Ctrl+S | Save the current document
Ctrl+T | Transpose adjacent characters
Ctrl+U | Change selection to lower case
Ctrl+V | Paste from the clipboard
Ctrl+W | Select current word
Ctrl+X | Cut selected text to the clipboard
Ctrl+Y | Redo the last Undo
Ctrl+Z | Undo the last edit
Ctrl+] | Go to matching bracket
Ctrl+[ | Select to matching bracket
Ctrl+F3 | Select current word and find next
Ctrl+F4 | Close the current file
Ctrl+F5 | Start the executable
Ctrl+F7 | Compile the current source file
Ctrl+F8 | Debug step out
Ctrl+F9 | Find the next difference in two files
Ctrl+F10 | Debug run to cursor
Ctrl+F12 | Comment out selected lines
Ctrl+SPACE | Auto-complete Fortran name
Ctrl+CANCEL | Cancel the current Build process
Ctrl+Shift+B | Build the project
Ctrl+Shift+C | Spike the selected text (append to clipboard). Spike the line if there is no selection.
Ctrl+Shift+D | Open Command Prompt
Ctrl+Shift+E | Extend block selection
Ctrl+Shift+F | Find in files
Ctrl+Shift+G | Go to the next error report etc.
Ctrl+Shift+L | Select current line and delete
Ctrl+Shift+N | Create a new project
Ctrl+Shift+O | Open an existing project
Ctrl+Shift+P | Run the currently active macro
Ctrl+Shift+R | Record a macro/Macro properties
Ctrl+Shift+S | Save all open documents
Ctrl+Shift+U | Change selection to upper case
Ctrl+Shift+V | Paste from clip library
Ctrl+Shift+Y | Redo move
Ctrl+Shift+Z | Undo move
Ctrl+Shift+] | Type } and reformat indentation for the C/C# block
Ctrl+Shift+F3 | Select current word and find previous
Ctrl+Shift+F12 | Remove comment marks from selected lines
Ctrl+Shift+SPACE | Auto-complete Fortran construct or routine
F2 | Debug toggle break point
F3 | Find next
F5 | Debug run
F6 | View the next document (pane)
F7 | Debug step into
F8 | Debug step over
F9 | Compare two files for differences
F10 | Toggle view clip library
Shift+F2 | Debug set conditional break point
Shift+F3 | Find previous
Shift+F5 | Debug stop
Shift+F6 | View the previous documnet (pane)
Alt+D | Mark as "dirty" (not saved, force recompile)
Alt+E | Toggle error reporting filter ON/OFF
Alt+F | Provide added FTN95 options (no project)
Alt+S | Toggle integrated/external debugging
Alt+V | Display and select from the clipboard ring.
Alt+U | Convert hex to UNICODE
Alt+X | Select FTN95, gFortran or iFort for x64
Alt+F3 | Repeat the last Find instruction
Alt+F4 | Exit Plato
Ctrl+Alt+R | Record temporary macro


Using a project shell

Using the default project and using a project shell

When there is no project open, you can view the Project Explorer window in order to add references that are used when compiling and linking the current file. These references are not inherited when you open a normal project. You could keep a long list of references and selectively include and exclude items using the Properties dialog for each reference. If you also want to configure your command line options then you can use a project "shell" as follows.

As an alternative to using the default project, you can create a special kind of project for general use. After creating the project, use the Project menu to select "Build Uses Active Source Only". This marks the project as a "shell".

A project shell is something between using a full project and not having a project open. When using the shell you can set command line options and references but the list of project files is hidden and cannot be used. When building, only the currently open and active source file is included in the build. Also there are no sub-folders for the various configurations and platforms.

A shell is particularly useful in a teaching environment. It can also be used when you need a "generic" shell for multiple projects, each of which contains only one source file.


Changing keyboard accelerators

By default Plato uses standard accelerators keys that conform as far as possible with the default Microsoft Visual Studio settings. Accelerator key can be configured to your preferred settings or you can elect to use Plato2 default keys.

To change accelerator keys, select Options from the main Tools menu and then select Keyboard from the tree on the left.

A number of menu commands do not have default accelerator keys. These can also be configured from using this dialog.

You can use one of two buttons to restore the Plato and Plato2 default settings. Also you can select a command from the commands column. Information about the command is given in the main status bar where you will see the standard prompt for the command. Now you can change the accelerator key using the Accelerator Key group of controls. Select a key from the drop down list or click on the "Next press" edit box and press the key that you want to use. Also select the Ctrl/Shift/Alt state. A box labelled "Used by" indicates when the selected key is already in use (if you continue the old use will be replaced unless it is used by a macro).

The list view of commands has its own context menu.

See also Creating and using macros.


Find and replace

Find and replace tools are accessed from the main Edit menu.

You can also use the Standard toolbar to type in words to find and then use the Find Next and Find Previous buttons to search through the code.

When you right click on this combo box you get a context menu for Match whole word only and Match case.

The "Find what" string in a simple Find process (not Find in Files) can include wildcards as follows:

^* | Any character string. This must not appear at the beginning or the end of the whole Find string.
^? | Any single non-space character.
^$ | Any single letter.
^# | Any single decimal digit.
^p | The linefeed character.
^d | Any integer number.
^w | Any combination of spaces and tabs.
^W | Any combination of zero or more spaces and tabs.
^t | The tab character.
^^ | The caret character.

In the "Find and Replace" dialog and the "Replace with" edit box, the text can include one alias as follows:

&.. | Denotes the current "Find what" text, or
&.clipName. | Denotes the clip text with item name "clipName" in a category called "User".

Use one alias at a time.


Creating and using macros

A sequence of key strokes can be saved as a Macro. This might be a temporary macro only for immediate use or a named macro that is kept in a library. A simple example of a macro is a command to delete from the current cursor position to the end of the line. The standard key sequence for this is Ctrl+End followed by Delete.

You can also use macros to create alternative accelerator keys especially for built-in commands. For example pressing Home calls a built-in command that takes you to the beginning of a line. You cannot disconnect the built-in commands from their keys but you can use macros to provide aliases.

To record a macro press Ctrl+Shift+R to open the Macro dialog.

Click on New and, if you wish, give the new macro a meaningful name. You can also attach an accelerator key to the macro (a box labelled "Used by" indicates when the selected key is already in use).

Now click on Record. This closes the current dialog and displays a small modeless dialog whilst recording continues.

The toolbar buttons in this dialog allow you to Pause, Stop and Cancel the recording. There is also a record (REC) indicator on the status bar.

Whilst recording continues you can record keyboard operations but not mouse operations (the mouse cursor indicates this state). This includes most edit and "Find" commands as well as any previously defined macros. Recursive macros calls are flagged as an error.

You can select one macro as the currently active macro. This macro is called when you press Ctrl+Shift+P. It is usually a temporary macro.

From the Tools menu, you can also issue the command to Play Back Repeatedly. This will run the currently active macro until the caret position does not change. This process is run on a separate thread and can be cancelled by selecting Cancel from the Build menu.

To delete a macro, click on its name in the Macro Name list and then press the Delete key.

Do not use Ctrl+K and Ctrl+M because these are reserved for future development.

Temporary macros

You can use a shortcut method to create a temporary macro. Select Record Temporary Macro from the Tools menu or use the associated accelerator key (the same key also stops a recording). This creates a new macro with the name Temporary.Macro and starts recording. The temporary macro is set as the active macro so after recording you can play back using Ctrl+Shift+P. If you decide to keep a temporary macro then you must change its name otherwise it will be over-written when you next record a temporary macro.


Creating and using commands

Commands that are normally executed from a Command Prompt (DOS box) can be saved and attached to an accelerator key. Standard components can be replaced by markers. For example %f represents the name of the active document (see below for details). Output from a command is directed to the same Output window that is used for a Build process. If your command generates standard error messages then you will be able to double click on a line in order to go to the relevant source line.

To create a command start from the Tools menu and select Commands.

Click on New and, if you wish, give the new command a meaningful name. You can also attach an accelerator key to the command (a box labelled "Used by" indicates when the selected key is already in use).

Type the command into the Command box. Commands normally begin with the name of an executable file. Often the executable is on the PATH. In some cases you may need to include the file extension (.exe). Executable file names that include spaces should be set in double quotation marks.

Here is a list of markers that you can use in a command.

%f | Denotes the name of the active document without its path and extension.
%e | Denotes the file extension of the active document without a leading dot (period).
%p | Denotes the full path of the active document.
%d | Denotes the folder for the active document.
%n | Denotes the line number of the caret in the active document.
%w | Denotes the word at the current caret position.
%t | Denotes the current project target. Only use this for projects.
%u | Denotes the string displayed in the 'Command line options' dialog.
%! | Represents a single % symbol.

Here is an example of a typical command used internally by Plato:

FTN95 %p /NO_BANNER /VS7 /DELETE_OBJ_ON_ERROR /ERROR_NUMBERS /UNLIMITED_ERRORS

Click on Run to close the dialog and run the selected command.

To delete a command, click on its name in the list and then press the Delete key.

Do not use Ctrl+K and Ctrl+M for accelerator keys because these are reserved for future development.


Using named bookmarks

For unnamed bookmarks see Editing facilities.

Named bookmarks can be used in a project or when there is no project open. Within a project they are stored with the project data otherwise they are stored in Plato3.ini.

Select Named Bookmarks from the main Tools menu to show the Bookmarks dialog. If you want to create a new bookmark then select the relevant line before opening the dialog.

To create a new bookmark, click on the New button and enter its name into the small edit box that appears in the Name column. The line number and file name are supplied automatically.

To go to a bookmark, select the bookmark from the Name column and then click on the Go to button (you can also use the Goto dialog to go to a named bookmark).

To delete a bookmark, select the bookmark from the Name column and then click on the Delete button.

To change the name of a bookmark, click on its name twice (in the usual manner for a list view) and use the small edit box that appears.

The Close button closes the dialog. This does not undo any changes that you have made.

This dialog can be resized.

To create a new bookmark you can also use the popup menu and select Toggle Named Bookmark. This uses to above dialog but implements New and Close automatically.


File dependency

By default Plato will keep a table of dependent files in your project. For example, you might define a Fortran module in file M.f95 and use it in a file U.f95. In this case Plato will detect that U.f95 is dependent upon M.f95. If a change is made to M.f95 then, when building, Plato will recompile M.f95 because it has changed and then U.f95 because it is dependent upon M.f95. A similar situation arises when you use the INCLUDE statement in your code.

The "Clean" process does not rebuild the table of dependent files. However, Plato will reconstruct its dependency table when you select Rebuild Dependencies from the Build menu.

If your project contains a very large number of files you may wish to remove the overhead caused by using the dependency table. To do this toggle the menu item called Enable Dependency Checking which you will find on the main Project menu.

If the process of adding a file to a project takes a long time then this means that the resulting dependency relationship is too complex for Plato to handle. (For example, although Plato tests for INCLUDE files, it does not look for pre-processing commands such as CIF etc. A combination of CIF commands with INCLUDE could cause this kind of problem.) In such cases it is advisable to disable dependency checking and to use Rebuild in preference to Build.


Working with non-standard files

Plato can edit standard Unicode files. Note, however, that FTN95 can only compile standard ASCII files.

A standard Unicode file is of the type UTF-16/UCS-2 (little endian). Files of type UTF-8 generate a warning message but are not decoded. ASCII files are converted to Unicode on opening and back to ASCII on saving. Other file types cannot be read by Plato.

Use the standard Character Map accessory to copy non-ASCII characters on to the clipboard and paste them into your text.

A warning appears if you paste Unicode characters into an ASCII file. In which case, when you save the file. you will be given the option to save with Unicode encoding or to delete all Unicode characters and save as ASCII.

Plato accepts ASCII files that use Unix or Mac linefeed characters. The file is saved in the same format. If the file contains linefeed characters of more than one type, then the Microsoft Windows carriage return/linefeed sequence is used when the file is saved.


Comparing two files for differences

To compare two files, select Compare from the Files menu (F9 by default).

Click on the first Browse button in order to select the first file. Click on the Read only check box if you want to protect the file from accidental changes. Do the same for the second file. Click on the White space must match check box if the two files are required to be exactly the same otherwise any white space (spaces and tabs) in one file will be allowed to match white space in the other file. Also blank lines are only significant when this option is selected. Finally click on the Compare button in order to open the two files and locate the first difference. The lines with the first difference are marked by red arrows in the margin and the caret is positioned at the appropriate point on each line.

In order to merge two files, it is a good idea to make one of them (the first, say) read only and to edit the second file accordingly.

To continue the search, place the text cursor on matching lines in the two files and then press Ctrl+F9 to find the next difference. Alternatively pressing F9 again restarts the search at the beginning of both files. This is recommended when merging two files.


Spell checking

Spell checking can be switched on and off from the Tools menu or by assigning an accelerator key to this command. The switch only affects the currently active document. Spell checking is performed via an syntax colouring algorithm that provides an alternative to the various algorithms for differing types of source code.

Plato loads valid words from the file English.lex and colours them using the text "Foreground" colour. Invalid words are coloured using the "Error" colour (both colours can be configured in the Fonts and Colours section of the Options dialog). You can provide alternative files to English.lex but you must specify its name in the Options dialog. The file must contain words made up from the 26 standard alphabetic characters in the ranges a - z and A - Z. The apostrophe, hyphen and underscore are also recognised. Words must be separated by spaces or linefeeds. They need not be in dictionary order.

A word that appears as invalid can be added to the dictionary by using the popup menu. These additional words are treated as user keywords and stored in Plato3.ini. You can include these words in your .lex file by issuing a command to Export the dictionary. This command can be found in the Keyboard section of the Options dialog under the name Spelling.Export. The file called English.lex is treated as read-only so you are prompted to export to a file with a different name.

You would normally use spell checking with plain text files but you can also switch it on for source code if it contains text that you would like to check.


Using the clip library

The clip library works like the standard clipboard but the text that you copy is given a category and name so you can paste many different items.

To view the library, select Clip Library from the main View menu.

The Clip Library window contains a tree that lists the categories with child nodes showing the items. You can add new categories and items, edit and delete items and paste the text into the current document. You can also rename a new item by clicking on its name in the tree.

The tree is populated with data obtained from two files: a) ClipLib.ini is a read-only library of standard clips and b) UserClips.ini is a file that is created when you add a new clip or edit a standard clip. [Note that if you delete a standard category or item then it will be restored when you get your next upgrade.]

Right click on an existing category to create a new category.

Ctrl+Shift+V pastes the currently selected clip into the text. You can also use this accelerator key when the library is not visible.

Linefeeds can be included in the paste. Also the paste can include a special character (a centre dot) that represents the current selection. This means that if you select some text then the paste will be wrapped around the selection.

When you create a new item (or a new category and item) you must provide the required names. Use the tab key to move from one edit box to the next.

When using the clipboard, Plato remembers the last 16 clips and stores them in a "clipboard ring". These can be recovered by using the accelerator key Alt+V and then selecting from the displayed list.


Adding syntax colouring for other languages

You can use the Options dialog to add syntax colouring for new programming languages. Select Language settings in the left hand pane. If the language you want to use is not in the list provided, click on the New button or the Import button. Use the Import button to read *.syn language syntax files downloaded from the TextPad website.

In the example shown, language settings have been imported for MatLab program files.

The check box in the list view is used to activate the programming language. Languages that are activated appear in the dialog when a New file is created.

The tabs for Words 1, etc. are used to define groups of keywords and other syntax attributes. Keywords are presented in a linear list separated by one or more spaces.

When you select a built-in language from the list view, only the User keywords tab is displayed. This allows you to include additional keywords for these languages.


Adding new plug-ins

Plato has four standard plug-ins for 1) an FTN95 executable, 2) an FTN95 DLL, 3) an SCC executable and 4) an SCC DLL.

[Note: you can add C++ files to an FTN95 project and you can add Fortran files to an SCC project.]

You can create additional plug-ins for other compilers or for special adaptations of FTN95 and SCC. To do this you must provide templates for the compilation and linking processes etc.

To begin, open the Options dialog and select Project templates from the left hand pane.

The check box in the list view allows you to activate the plug-in. Plug-ins that are activated appear in the dialog when a New Project is created.

The Title, Prompt and Icon fields are also used in the New Project dialog. Further information is provided in the "What's this" help.

Some of the edit fields use format specifiers (such as %f) to represent current components in a command. Details appear below. %! represents a single % symbol. Escape sequences that are not listed are reserved.

Compile:

This field is used when compilng in project mode and non-project mode (i.e. when there is no project open).

%f | the stem of the current file name (e.g. "main" in main.f90)
%e | the extension of the current file name
%b | the full path of the binary file to create
%o | the options for the current configuration and platform (see below)
%p | the full path of the current file
%d | the full path of the directory for the current file
%D | the full path of the directory for the binary file to create

[Note: Error reports are currently assumed to conform to the Silverfrost pattern.]

Debug etc:

These fields provide the options to use in place of %o above depending upon the current configuration and platform.

Link file:

This field is only used for linking when there is no project open.

%b | the full path of the binary file to link
%t | the target to create

[Note: Object files are currently assumed to have the .obj extension.]

Link project:

This field is only used for linking when there is a project open.

%b | a list of binary files to link separated by spaces
%t | the target to create
%L | a list of references as shown in the Project Explorer dialog.

Run:

This field is used in both project and non-project mode. It is normally left blank which defaults to "%t %r".

%t | the target to run
%r | the run-time parameters described below

Run params:

This field is used in both project and non-project mode. It contains the run-time parameters represented by %r above.

[Note: In project mode you can also set "Launch arguments" in the Project properties. You can use both. The plug-in attributes apply to all projects of this type. The Launch arguments are project dependent.]

Step into and Run to:

These fields are used in both project and non-project mode.

%t | the target to debug
%r | the run-time parameters described above
%p | the full path of the active file
%n | the current line number in the active file


Using FTN95 configuration files with Plato

FTN95 configuration files are created by using /CONFIG on the FTN95 command line. A configuration file must have the name FTN95.CFG but can be placed either in the compiler directory and/or in the current working directory. A configuration file that is placed in the compiler directory is universal (it will be applied to all calls to FTN95). A configuration file that is placed in the current working directory is local (it will be applied to calls to FTN95 made from that directory).

Plato is designed to work independently of any configuration files and, particularly when using projects in Plato, they are assumed to be unnecessary. Plato does not look for configuration files and does not handle them in any way. It issues FTN95 commands on your behalf and, if FTN95 finds one or more configuration files, then FTN95 processes them independently of Plato. Therefore, to avoid unnecessary complications, it is simpler to avoid using FTN95 configuration files with Plato. If you do use an FTN95 configuration file with Plato then please note the following...

  1. Configuration files that are placed in the compiler directory are always implemented and the configured options override (and may conflict) with those provided from Plato.
  2. When building a project, the current working directory (for an FTN95 command) is the project directory (the one that contains the .ftn95p file for the project). This means that a local configuration file must be placed in the project directory.
  3. When compiling a file and not using a project, the current working directory is the directory that contains the file. This means that a local configuration file must be placed in the same directory as the file that you are compiling.


Building for .NET 2.x or .NET 4.x when 1.x is installed

When building a .NET assembly, by default Plato will build for .NET 2.0 if this version is installed on the PC.

If only .NET 4.0 is installed then by default Plato will build for .NET 4.0.

If both .NET 2.0 and .NET 4.0 are installed and you do not want to build for version 2.0 then you can either

a) configure your project to build for .NET 4.0 using the Project Properties dialog or

b) configure Plato to always build for .NET 4.0 by adding the following kind of data to your Plato.ini...

[Settings]

DotNetBuildVersion=4


Migrating to FTN95

Unsupported features

Deleted features

Obsolescent features

Converting INCLUDE files


Unsupported features

The following syntax forms which may occasionally appear in legacy code are not included in the Fortran 95 standard and are also not available in FTN95.

DATA I/%K/

This would initialise 'I' to the address of the statically allocated variable 'K'. Use I = LOC(K) to get the same effect.

Octal constants using ':177' notation
These could not be implemented because of ambiguities with array section syntax, e.g. is 'A(:177)' the 127th element of 'A', or is it a section from the start of the array to number 177? Use O'177' syntax instead.

Branching to END IF from outside the block

This is the only deleted feature not to be implemented. Alter the code to branch to the statement following the END IF.

VAX extensions
Only those VAX extensions that are now part of the Fortran 95 standard have been implemented in FTN95. Most of the VAX extensions that are not in this category have equivalent functionality in Fortran 95.


Deleted features

The following features have been deleted from the standard. With the exception of 'branching to ENDIF', these features are included in FTN95 but for portability should not be written into new code. Although these features will not be deleted from FTN95, in future versions, technical support in these areas will not be provided. Naturally these features are not available when the compiler option /ISO is used.

  • REAL and DOUBLE PRECISION DO index variables.

  • Branching to END IF from outside the IF (see above).

  • PAUSE statement.

  • ASSIGN and assigned GOTO.

  • Hollerith constants.


Obsolescent features

The following features are marked as obsolescent in the standard. These features are included in FTN95 but should not be written into new code for compatibility with future Fortran versions. Although these features will not be deleted from FTN95, in future versions, technical support in these areas will not be provided.

  • Arithmetic-IF.

  • Shared DO-loop termination, e.g.

    DO 10 I=1,10
    DO 10 K=1,10
    ...
    10 CONTINUE

  • Alternate return.

  • Computed GOTO.

  • Statement functions.

  • DATA statements among executable code.

  • Assumed-length character functions.

  • Fixed-format source code.

  • Assumed-size arrays (i.e. with '*' in the last dimension).

  • CHARACTER*<len> declarations.


Converting INCLUDE files

It is recommended that FTN95 /CONVERT be used on any INCLUDE files to ensure these files are compatible with both fixed and free format source code.


Introduction to compiler options

Compiler options

FTN95 is invoked from a command line and you can work directly from the command line if you prefer. Alternatively you can use Microsoft's Visual Studio to create both .NET and Win32 applications.


Changing compiler options from Visual Studio

General information on how to use Visual Studio with FTN95 and how to create a simple Fortran project is given in Getting Started with FTN95.

By default a new FTN95 project in Visual Studio will be configured for .NET rather than Win32 and will be set in debug rather than Checkmate or release mode. On the FTN95 command line, the .NET platform is selected by using the compiler option /CLR whilst Checkmate mode is selected by using /CHECKMATE.

In general, compiler options can be set at three levels: solution level, project level and file level.

Solution level

The default settings can be changed from the Solutions Configurations drop-down list on the main toolbar or from the Configuration Manager dialog. Select Configuration Manager from the main Build menu in order to open this dialog.

Choose a mode using the box at the top entitled Active Solution Configuration. Click on the arrow icon and select a mode from the drop down list. Release mode can be selected when a solution is ready for use/shipping. The debug and Checkmate configurations plant debugging code that allows you to step into the code using the integrated debugger. The default configuration is Checkmate and this is recommended for development.

The names that appear in this list (Debug .NET etc) are names for standard configurations. By selecting <New...> from the list you can create a new configuration. Choose an existing configuration as a basis and then change the default settings at project level using the Project Contexts grid.

The Projects Context grid describes the configuration for each project and by default this reflects the Active Solution Configuration. It is better to leave this grid unchanged unless you are defining a new Active Solution Configuration.

Note that you can also change the default .NET platform to Win32. Most of the features of Visual Studio can be used to create Win32 as well as .NET applications and DLLs (you can even use ClearWin+ together with the Visual Studio image and dialog editors if you wish).

Project level

Having selected a configuration at solution level, additional compiler options can be included for each project in the solution. To do this open the Property Pages dialog for the project by clicking on the name of the project in the Solution Explorer window. Click on the right mouse button and select Properties from the popup menu.

The following dialog appears...

Configuration: By default this will be set to the active solution configuration and need not be changed.

Platform: By default this will be set to the active solution platform and need not be changed.

Configuration properties: Compiler options are classified in the tree on the left hand side of the dialog. Most of the options can be left in their default state. Under Miscellaneous you will find Output File Type. Change to DLL or LIB if you are creating a DLL or library file. In the same section you will also find Launch Arguments. If the project creates an executable rather than a DLL or library then (for the purpose of debugging) any arguments required by the executable should be included here. For example, if your application processes a file and the name of the file is provided on the command line after the name of the executable, then the name of a sample file can be included here. When using Visual Studio 2005 .NET Framework Version allows you to chose the version of the .NET Framework to target, versions 2.0 or 1.1 are available.

All options have help information that appears in the field at the bottom of the dialog, select an option to see the help for it.

File level

When your project contains a number of files, you can set different compiler command line options for a particular file by using the File Properties window as follows.

Click with the left mouse button on the name of the file in the Solution Explorer window (or use the right mouse button and select Properties from the popup menu). Now look at the Properties dialog that normally appears below the Solution Explorer dialog. If the Properties Window is not visible, select Properties Window from the main View menu.

On the CustomCompilerOptions line, click on Off and the resulting arrow icon in order to view the options to Append to or Override the project options. Now type in the options in the box labeled CustomSwitches. For example, if the project is set to debug rather than Checkmate mode then a particular file might be set to Checkmate mode with the following entry.

You can also use this dialog to:

1) Exclude this file from the build process.

2) Change the name of the file (this renames the file on the drive and in the solution).

3) View certain properties of the file.

4) Mark the file as read only.


Compiler options on a command line

FTN95 is a command line compiler and so can be invoked from a Command Prompt box.

The compiler reads programs from text files that have been created using a suitable ASCII text editor (like that included in Visual Studio). The text file can be specified as the first parameter to the FTN95 command as follows:

FTN95 <pathname> /CLR

Note that options may be abbreviated, but care should be exercised to ensure that the abbreviated form is unique.

When the /CLR switch is used the compiler makes .DBK files for .NET rather than Win32 .OBJ files. When <pathname> does not include an extension, the compiler searches for the file <pathname>.F95 (or .F90). Source files must have .F95 or .F90 as an extension, or be specified with an explicit extension. Any file name acceptable to the operating system can be used.

By default, files that have a .F95 or .F90 extension are assumed to be free format files whilst files that have a .FOR or .F extension are assumed to be fixed format files.

For example

FTN95 MYPROG /CLR

compiles the program in the file MYPROG.F95 which is in the current directory whilst

FTN95 C:\FTN\PROJECT\MYPROG /CLR

compiles the file MYPROG.F95 in the directory C:\FTN\PROJECT\.

Only one source file name may be specified unless wildcards are used. For example:

FTN95 *.F95 /CLR

would compile all of the .F95 files in the current directory. In this case an explicit extension (like .F95) is essential.

If the program is contained within a single file it can linked to form a .NET executable by using /LINK.

FTN95 MYPROG /CLR /LINK

When /CLR is not present /LINK is used to create a Win32 executable.

The /LINK option can also used to create a .NET DLL file or a .NET module (not to be confused with a Fortran module). For a Win32 platform (when /CLR is not present), /LINK can also be used to create a DLL or library.

For single program files there is also a load-and-go option:

FTN95 MYPROG /CLR /LGO

This compiles, links and loads the program without creating permanent object and executable files.

If your project uses a number of source files, then each file must be separately compiled using a command of the form:

FTN95 MYPROG /CLR

The resulting set of .DBK files are then linked together using the Salord linker DBK_LINK or DBK_LINK2 or DBK_LINK4. If /CLR is not used, the resulting set of .OBJ files are linked together using the Silverfrost linker SLINK.

FTN95 for Microsoft .NET does not have an independent debugger so you must use Visual Studio in order to step into the code for debugging purposes. FTN95 for Win32 uses either the independent debugger SDBG or can use the debugger inside Visual Studio.

Some of the compiler command line options can be adopted as compiler defaults. The default options can be listed and changed from an interactive dialog that is opened with the following command:

FTN95 /CONFIG

Many of the options have a corresponding opposite. For example /-INTL is the opposite of /INTL. If the default setting is changed by using the /CONFIG dialog, then there are occasions when you may wish to use the opposite option in order to temporarily restore the original default. The dialog indicates which options can be configured and hence have an opposite.


Compiler Options - Quick Reference

Options classified

/?
Gives a list of options when FTN95 is used from a command line in a Command Prompt box.

/132
Prints error messages formatted for 132 column screens.

/64
Produces 64 bit object code for the x64 platform as opposed to Win32 and .NET.

/ALLOW_RECURSION
Allows procedure recursion when the RECURSIVE attribute has not been specified (not recommended).

/ALL_WARNINGS
Prevents certain warnings from being reported only once.

/ALT_KINDS
Allows byte size for KIND numbers. e.g. REAL(8) instead of REAL(2); also 1.0_8 instead of 1.0_2 but 1.0_K must use the default KIND values.

/ANSI
Old synonym for /ISO option.

/ASMBREAK
Win32 only. Like /BREAK but enters debugger at assembler level.

/BINARY <filename>
Used to specify the .DBK or .OBJ file name. If this option is omitted, the object file name is created by replacing the source file-name's suffix with .DBK or .OBJ, e.g. with FOO.F95, the object file would be FOO.DBK for .NET (using /CLR) and FOO.OBJ for Win32.

/BREAK
Win32 only. Implies both /CHECK and /LGO and causes a break to the symbolic debugging facility at the first executable statement.

/BOUNDS_CHECK
Check array subscripts only (/CHECK includes /BOUNDS_CHECK).

/BRIEF
Causes all errors, warnings and comments to be output in a form that is compatible with Borland BRIEF.

/CFPP more...
Invoke the C-style preprocessor on all input files. Use this for #if, #ifdef, #endif statements.

/CHECK more...
Causes code to be planted in order to enable the run-time checking of array bounds, overflow etc., and also to enable the use of the source-level debugging facilities (/CHECK implies /DEBUG).

/CHECKMATE
A synonym for /FULL_UNDEF. /FULL_UNDEF implies /UNDEF which in turn implies /CHECK.

/CHECK_ALIAS more...
Provides runtime checking for aliased arguments when used with /CHECK.

/CHECK_WINIO
Provides a compile time check of WINIO@ arguments against their corresponding format codes. When an error is detected the compilation is abandoned. These errors would otherwise be detected at runtime.

/CKC
Win32 only. Appends "__C" to C_EXTERNAL aliases that do not start with a double underscore.

/CONTAINING_CLASS <classname>
only. Supplies a fully qualified class name to hold the Fortran code when using /LINK.

/CLR
only. Outputs object code for .NET Framework, version 2.0 is targeted by default - use /CLR along with /CLR_VER 4 to target 4.0. (Support for 1.1 has been removed as of version 6.35 of FTN95)

/CLR_VER <version>
only. Target a specific version of the .NET Framework, use /CLR_VER 4 to target version 4.0.

/COLOUR
Compiler output in a Comand Prompt box is coloured. See Silverfrost environment variables to change the default settings.

/CONFIG
Opens a dialog box to set-up installation compiler defaults. This must be the only option on the command-line. See also Default Compiler Options.
This dialog can be used to change the global compiler defaults. Use /CFG in order to change the local compiler defaults.

Default options are placed in a file FTN95.cfg. The file for global values is written to the same directory as the compiler FTN95.exe. The file for local values is written to the working directory for the current project. FTN95 reads default options first from a global file and then from a local file where they exist.

/CONVERT
Converts fixed-format source into free-format, output to the screen. All comments are lost and Hollerith constants replaced with strings. This is useful for converting fixed-format INCLUDE files into files suitable for both fixed and free formats. This option implies the /NO_BINARY option and no error checking, other than for matching brackets and checking the fixed-format column rules, is done. All other options on the command-line are ignored.

/DBREAK
Win32 only. Implies /LGO and causes a break to the symbolic de bugging facility at the first executable statement (i.e. like /BREAK, but /CHECK is not implied).

/DCLVAR
Implies IMPLICIT NONE and also requires that external subprograms be explicitly declared as EXTERNAL.

/DEBUG
causes FTN95 to generate symbolic information and to activate the symbolic debugger when fatal errors occur. /DEBUG is included in /CHECK, /UNDEF and /CHECKMATE which are normally preferred. /DEBUG can be used on its own in order to allow the debugger to be used on "dirty" code, which intentionally violates some of the rules of Fortran.

/DEBUG_SOURCE
Adds a call to DEBUG_SOURCE@ after every executable line (currently not available for x64).

/DEFINT_KIND <kind>
Sets the default INTEGER kind. Use kind=2 or 3. kind=3 is the default.

/DEFLOG_KIND <kind>
Sets the default LOGICAL kind. Use kind=1 or 2 or 3. kind=3 is the default.

/DEFREAL_KIND <kind>
Sets the default REAL kind. Use kind=2 or 3. kind=3 is for Win32 only.
/DEFREAL_KIND 2 also promotes all variables declared as REAL*4 or REAL(1) to double precision. In this respect it is the same as the option /DREAL and is unlike the behaviour of /DEFINT_KIND. Similarly (for Win32) DEFREAL_KIND 3 is the same as /XREAL.

/DELETE_OBJ_ON_ERROR
If /LINK or /LGO is used no permanent object file is created. Otherwise, by default an object file will be generated except when errors are present. /DELETE_OBJ_ON_ERROR represents the default and must be negated to prevent the object file from being deleted.

/DO1
Causes DO loops to be executed at least once to allow certain Fortran 66 programs to execute correctly.

/DREAL more...
Set the default KIND for REAL types to be 2 (DOUBLE PRECISION).

/DUMP
Output a variable dump in listing file.

/ERROR_NUMBERS
Error messages are accompanied by their error number.

/ERRORLOG
Creates a file called <filename>.ERR containing a copy of all error and warning messages.

/EXPLIST [<filename>]
Generate a listing file containing a symbolic assembler listing. <filename> is the optional name of the .LIS file. /EXPLIST is equivalent to /LIST but causes each source statement to be followed by the assembler statements corresponding to the instructions into which it was compiled.

/F_STDCALL
Win32 only. Applies the F_STDCALL keyword to all user-defined and imported subprograms. Standard intrinsics, and FTN95 intrinsics and library routines are automatically excluded. FTN95 routines such as CISSUE must be renamed CISSUE@. Certain Fortran language restrictions apply and, in particular, INTERFACE statements may not be used with this option. When used with /CHECK, certain checking processes are not implemented. In particular, what are called "write-ability" checks are not applied. This means that it is advisable to test your code using /CHECK (or /CHECKMATE say) without using /F_STDCALL.

/F2K
Permits the use of some Fortran 200x statements as an extension. This option is now switched on by default.

/FIXED_FORMAT
Accept source code in ISO fixed source format. This is assumed for files with .FOR or .F suffixes. If the name of the source file on the command line has no suffix and this option is supplied then .FOR is assumed to be the suffix.

/FPP more...
Invoke the preprocessor on all input files (this is required in order to use CIF/CELSE/CENDIF when /SPARAM and /VPARAM are not used). This option is implied by /CLR.

/FREE_FORMAT
Accept source code in ISO free source format. If the name of the source file on the command line has a suffix which is not .FOR and not .F, this option is assumed. If the name of the source file on the command line has no suffix, .F90 is assumed.

/FULL_DEBUG
Outputs full debugging information including PARAMETERs.

/FULL_UNDEF
Like /UNDEF but also INTENT(OUT) arguments are initialised as undefined on entry to a procedure (/INHIBIT_CHECK 14 switches this off) and by default character variables are initialised as undefined. The reading of an undefined value precipitates an error condition.

/HARDFAIL more...
Win32 only. Used with /LGO to suppress entry into the debugger in the event of a run time error.

/HELP
Invokes the Windows based help system.

/IGNORE <error number>
Suppresses all errors and warnings with the given number. Error numbers are generated using /ERROR_NUMBERS. Suppressing error numbers is unsafe but may be useful during debugging.

/IMPLICIT_NONE
Fault on IMPLICIT type definitions.

/INCLUDE <pathname>
Allows specification of list of include paths. This is appended to the list of include-paths optionally specified in the environment variable F95INCLUDE.

/INHIBIT_CHECK <integer> more...
Prevent the specified check being added with /CHECK and /FULL_UNDEF.

/IMPORT_LIB <pathname>
Win32 only. Scans a CVF generated library, automatically creating F_STDCALL interfaces.

/INTL more...
Set default KIND for type INTEGER to be 3 (this is the default). This is equivalent to /DEFINT_KIND 3.

/INTS more...
Set default KIND for type INTEGER to be 2. This is equivalent to /DEFINT_KIND 2.

/ISO
Specifies that all constructs used in a program must conform to the Fortran 95 ISO Standard. No FTN95 extensions to the Standard are allowed. The /ISO option also informs the FTN95 run-time system that ISO-conformity is required. This means that, for example, non-standard use of format descriptors (such as business editing in a run-time format) causes a run-time failure.

/LGO more...
Compile, load and execute.

/LIBRARY<filename>
Specification of relocatable binary library and input files when using /LGO or /LINK.

/LINK [<filename>] more...
Generates an executable file, DLL or relocatable library (in the case of .NET, a .NET assembly file or module). If <filename> is not provided, the name is created by using the source file name. For example, FOO.F95 would generate a Win32 executable called FOO.EXE.

/LIST [<filename>] more...
Produces a source listing file. If <filename> is not provided, the name is created by replacing the source-suffix with .LIS, e.g. with FOO.F90, the map file would be FOO.LIS.

/LIST_INSERT_FILES
Used with /LIST to include INCLUDE files in listing.

/LOGL more...
Use LOGICAL (KIND=3) as default LOGICAL type (this is the default). This is equivalent to /DEFLOG_KIND 3.

/LOGS more...
Use LOGICAL (KIND=2) as default LOGICAL type. This is equivalent to /DEFLOG_KIND 2.

/MAC_EOL
Specifies that the source code uses Apple Macintosh end-of-line characters.

/MAP [<filename>]
Produces a linker map. If <filename> is not provided, the name is created by replacing the source-suffix with .MAP, e.g. with FOO.F90, the map file would be FOO.MAP.

/MESSAGE_SET_TO_COMMENT
Sets all compiler diagnostic messages to comment severity.

/MESSAGE_SET_TO_ERROR
Sets all compiler diagnostic messages to error severity.

/MESSAGE_SET_TO_FATAL
Sets all compiler diagnostic messages to fatal severity.

/MESSAGE_SET_TO_SUPPRESS
Applies /IGNORE to all error numbers.

/MKLIB
Win32 only. Generates a static library containing a separate object for each function or subroutine.
/MKLIB causes FTN95 to call the Silverfrost library manager called SLIM. Objects in the resulting static library may work correctly with the debugger SDBG. The use of SLIM objects with SDBG is not supported.

/MOD_PATH <pathname>
Sets alternative path for module files. More than one /MOD_PATH is permitted. This is appended on to the path contained in the optional environment variable MOD_PATH.

/NO_BANNER
Suppress compilation logos.

/NO_BINARY or /NO_CODE
Suppresses the creation of an object file.

/NO_COMMENT
Suppress compiler comments, but not warnings and errors.

/NO_FAIL
Synonym for /PERSIST.

/NO_MODULE_MEMMAP
Use standard Win32 I/O for .MOD files (only required when creating .MOD files on a network drive where the server is a Windows 9x machine).

/NO_OBSOLETE
Suppress reports of obsolete and extension warning messages after the first has been displayed.

/NO_OFFSETS
Suppresses the output of address offsets in the source listing.

/NO_QUIT
Suppresses the simulated quit after a bad compilation. This normally simulates a ^C to halt a batch-file compilation. With this option set

IF ERRORLEVEL 1

must be use to test for compilation failure in a batch file if this option is set, or alternatively

IF NOT EXIST <file>.OBJ

if the /DELETE_OBJ_ON_ERROR option is also used.

/NO_WARN_WIDE
Suppresses warnings for characters appearing in columns 133 (free format) or 73 (fixed format) and beyond in the source file.

/NO_SCALAR_TO_ARRAY
Treats the assignment of a whole array to a scalar value as an error.

/NO_SCREEN_MESSAGES
Suppresses messages when using /LIST.

/NO_TRUNCATE
Characters beyond column 72 (132 for free format files) are treated as an error.

/NON_STANDARD
Suppresses compiler messages that warn of syntax that is permitted by the FTN95 compiler but does not conform to the Fortran 95 standard. Such warnings will be converted to errors if /ISO is used. /NON_STANDARD is switched on by default.

/OLD_ARRAYS
INTEGER A(1) implies INTEGER A(*) when declaring procedure arguments.

/OPTIMISE more...
Invokes the peephole and tree optimisers. /CHECK, /UNDEF, /DEBUG and their variants are incompatible with this option.
Should not be used during initial testing because it omits some syntax checking.
Note that 64 bit optimised code will not load on a machine that does not support the AVX instruction set.

/OPTIONS <filename>
Specifies a file containing additional compiler options.

/OVERFLOW
only. Implied by /CHECKMATE. Can be used in release mode to call CHECK_FINITE@ after every floating point calculation.

/P6
Win32 only. Uses some instructions which are only available on a Pentium Pro (P6) (or better) processor.

/PARAMS <param-list> more...
Used with /LGO or /BREAK to pass options to the program rather than the compiler. This must be the last FTN95 option on the command line.

/PAUSE_ON_ERROR
Outputs error/warning/comment messages one at a time and waits for a key press after each message.

/PERSIST
By default compilations with errors will terminate as if control break had been pressed. When the command appears in a batch file, the batch process will then be interrupted. If /PERSIST is used, the control break is suppressed and processing of the batch file will continue even when compilation errors have occurred.

/PROFILE
x64 only. Inserts code to record how many times each line is executed.

/REF <.NET assembly>
only (but see additional note below). Used with /LINK and /LGO to pass a reference to the linker. It can also be used during compilation to access information about methods and objects that are defined in the assembly and used in the program.
Note that /REF must not reference a DLL via the global assembly cache (GAC). DLLs in the GAC should have alternative copies in a corresponding "redist" folder. Use the "redist" version and not the GAC version with /REF.
Additional note: /REF is designed for but is not limited to .NET. It can also be used as an alternative to a LIBRARY statement under Win32.

/RESTRICT_SYNTAX
Increases compiler strictness to reject dubious code.

/RUNTRACE
Adds a call to RUN_TRACE@ after every executable line (currently not avaiable for x64).

/SAVE more...
Do not use the stack for storage of local variables and arrays. Otherwise dynamic storage is used for all local variables and arrays. This has the effect of a blank Fortran SAVE statement in each subprogram. Its use should normally be avoided.

/SEARCH_INCLUDE_FILES
Searches through INCLUDE files for CONTAINS. Switch this on only if an INCLUDE file contains executable statements. This option is set by /ISO. When compiling typical Fortran 77 programs containing many INCLUDE statements, this will speed compilation.

/SET_ERROR_LEVEL <code> <number>
Changes the severity of a compiler diagnostic. <code> is Suppress, Comment, Warning, Restricted, Error, or Fatal. <number> is the error number reported by using /ERROR_NUMBERS.

/SILENT
Suppress warning and comment messages. Also when /SILENT is used, the message that is output on the screen at the end of the compilation of a program unit does not include the numbers of warning and comment messages.

/SINGLE_LINE
Only prints the first line of an error message, ignoring any continuations. This is ignored if /BRIEF is specified. Without this option, when an error is reported, the offending line is output together with any continued lines.

/SIZE_ISO
Used with /64 in order to force the SIZE intrinsic to return a 32 bit value.

/SPARAM <integer> more...
Sets the value of all SPECIAL PARAMATERs.

/STACK <size>
Used with .NET or x64 to set stack size per thread when using /LINK or /LGO.
For x64 the size supplied is the number of millions of bytes.

/STANDARD_ERROR_REPORTING
Suppress windowed diagnostic information.

/STATISTICS
Print the number of lines compiled and the compilation speed on the screen.

/SUPPRESS_ARG_CHECK
Suppresses /CHECK mode checking for argument constistency across routines.

/TABS <integer>
By default FTN95 assumes that tab characters in the code correspond to fixed tab positions at intervals of 8 characters. This option can be used to change to some value other than 8.

/TIMING
Plants code to do per-routine timing (see /TIMING).

/UNDEF more...
Implies /CHECK and also causes code to be planted in order to do run-time checking for any undefined variables or array elements.

/UNDERFLOW more...
Win32 and x64 only. Used to trap underflow.

/UNLIMITED_ERRORS
Carry on compiling even after 12 error messages.

/VERSION
Display version information.

/VPARAM <name> <integer> more...
Like /SPARAM but allows the user to define a SPECIAL PARAMETER by name, instead of having all the same value (over-rides SPARAM).

/WARN_FATAL
All warnings and comments become errors.

/WRAP
Source lines are wrapped rather than truncated when an error or warning is output.

/WIDE_SOURCE
Line-truncation for fixed format files at the 72nd column is suppressed.

/WINDOWS
Win32 and x64 only. Program is compiled for use with ClearWin+.

/XREAL
Win32 only. Sets the default KIND for REAL types to be 3.

/XREF [<filename>]
Generates a cross-reference .XRF file. If <filename> is specified, the file name is created by replacing the source file-name's suffix with .XRF, e.g. with FOO.F90, the resulting name would be FOO.XRF.

/ZEROISE more...
All static variables and arrays set to zero at start of execution.


Using /LGO and /LINK

FTN95 provides a load-and-go facility via the /LGO compiler option so that programs can be quickly compiled, loaded and executed. /LGO can be used with large and complex programs, even those that require the use of libraries. No permanent object or executable file is produced (although there must be enough disk space to accommodate a temporary object file). These features make this facility invaluable for teaching, testing and development where repeated compilations and test runs are the norm.

If you wish to keep a copy of the current executable file then the /LINK option should be used. /LINK has no effect when used with /LGO.

Most of the other compiler options summarised in Compiler options - Quick reference are available together with a number of extra options which allow the following:

  • specification of relocatable binary library and input files,

  • interactive debugging.


The /LGO option

The load-and-go facility is invoked by the /LGO option. For example:

FTN95 MYPROG /CHECK /LGO

would compile, load and execute the program held in the source file MYPROG.F90 for Win32. The order of options on the command line is immaterial, except when an option requires a name, in which case the name must follow it.

The Win32 options /BREAK and /DBREAK both imply /LGO. These options also imply either /DEBUG or /CHECK.

These options are summarised in the following table for easy reference.

Option | Debug code planted | Check code planted | Immediate entry to debugger | /LGO implied
/DEBUG | yes |  |  |
/CHECK | yes | yes |  |
/BREAK (Win32 only) | yes | yes | yes | yes
/DBREAK (Win32 only) | yes |  | yes | yes


The /LINK compiler option

When the compiler is invoked with the /LINK option, for example

FTN95 MYPROG /LINK

the linker is automatically invoked after compilation is complete (assuming, of course, that no compilation errors have occurred). The resultant object code is loaded and a corresponding .EXE file is produced (a .OBJ file is not saved). The example above would create a Win32 run file called MYPROG.EXE.

If you wish to load other relocatable binary files, in addition to that produced by compilation of the named source file, the /LIBRARY compiler option (or the corresponding directive) should be used (see Relocatable binary libraries and input files).


Relocatable binary libraries and input files

The use of the /LGO and /LINK options is not restricted to programs that require only the FTN95 library. Other system or user relocatable binary (RLB) libraries and RLB input files can be specified by using one or both of the following methods:

  • By using the /LIBRARY option in the FTN95 command line. For example:

    FTN95 MYPROG /LGO /LIBRARY GKSLIB

  • By using a LIBRARY directive (which, in fixed format Fortran, must commence at or beyond column 7) in the source file.

    LIBRARY '<pathname>'

    where <pathname> is the name of the file. For example:

    LIBRARY 'C:\GRAPHICS\GKSLIB'

    Use of a LIBRARY directive ensures that no RLB library or input file is forgotten when loading a program as the directives are always present in the source file.

    If a library filename does not include path information, the current directory is searched, followed by the directory containing the FTN95 compiler.

    Notes:

  • If the name of a Win32 library file does not include an extension then the compiler will automatically add .OBJ to the name.

  • Win32 dynamic link libraries are not specified in a LIBRARY directive. DLLs are normally located either in the Windows 'system' directory or on the PATH.


The /PARAMS option

The /PARAMS option is provided to specify command line information for the program. This option is necessary in order to prevent FTN95 from scanning the whole command line before the user's program is executed.

For example, suppose that NEWPROG.F90 obtains two filenames FILE1 and FILE2 by means of calls to the system routine CMNAM. These filenames could be specified as follows:

FTN95 NEWPROG /LGO /PARAMS FILE1 FILE2

An illustrative program appears with the description of the CMNAM routine (see CMNAM).


Compiler Options (Classified)

Run-time checking

Program listing

Error messages

Properties of the code

Default KINDs for intrinsic types

Optimisation of the code

Destination for binary code

Compilation statistics

Conditional compilation

Automatic loading after compilation

Others


Run-time checking options

A significant feature of FTN95 is its ability to implement a range of powerful run-time checks that help the programmer to develop error free code. The options in this group direct the compiler to plant code that carries out these checks. /CHECKMATE (which is the same as /FULL_UNDEF) provides comprehensive checking and is recommended for normal development.

/BREAK
Win32 only. Implies both /CHECK and /LGO and causes a break to the symbolic debugging facility at the first executable statement.

/BOUNDS_CHECK
Check array subscripts only (/CHECK includes /BOUNDS_CHECK).

/CHECK more...
Causes code to be planted in order to enable the run-time checking of array bounds, overflow etc., and also to enable the use of the source-level debugging facilities (/CHECK implies /DEBUG).

/CHECKMATE
A synonym for /FULL_UNDEF. /FULL_UNDEF implies /UNDEF which in turn implies /CHECK.

/CHECK_ALIAS more...
Provides runtime checking for aliased arguments when used with /CHECK.

/DEBUG
causes FTN95 to generate symbolic information and to activate the symbolic debugger when fatal errors occur. /DEBUG is included in both /CHECK and /UNDEF which are normally preferred. /DEBUG can be used on its own in order to allow the debugger to be used on "dirty" code, which intentionally violates some of the rules of Fortran.

/FULL_DEBUG
Outputs full debugging information including PARAMETERs

/FULL_UNDEF
Like /UNDEF but also INTENT(OUT) arguments are initialised as undefined on entry to a procedure (see /INHIBIT_CHECK to switch this off) and by default character variables are initialised as undefined. The reading of an undefined value precipitates an error condition.

/INHIBIT_CHECK <integer>
Prevent the specified check being added with /CHECK and /FULL_UNDEF as follows:
1 - suppress marking DO-loop indices as unwritable in a function call
2 - suppress marking INTENT(IN) arguments as unwritable in a function call
3 - suppress POINTER checking partially
4 - suppress POINTER checking completely
5 - suppress the argument type/size checking on function entry
6 - suppress the extra information added to a CHECK mode function call
7 - suppress CHARACTER length checks on procedure entry
8 - suppress UNDEF check with WRITE/PRINT statements
9 - suppress FULL_UNDEF check with CHARACTER WRITE/PRINT statements
10 - suppress checking of overwriting of DO-loop index using "(Writability of ...)"
11 - suppress checking of overwriting of DO-loop index after SUBROUTINE call using "(Value of ...)"
12 - suppress checking of overwriting of DO-loop index after FUNCTION call using "(Value of ...)"
13 - suppress checking of overwriting of EQUIVALENCEd/COMMON DO-loop index after assignment using "(Value of ...)"
14 - suppress FULL_UNDEF check with INTENT(OUT)
15 - same as item 5 but only for module procedures
16 - spare
17 - suppress a recursion check (64 bit only)
18 - suppress argument alias checking (cancels /CHECK_ALIAS)
19 - suppress array conformance checking
20 - suppress array bounds checking (simple arrays not array sections)

/SUPPRESS_ARG_CHECK
Suppresses /CHECK mode checking for argument consistency across routines.

/UNDEF more...
Implies /CHECK and also causes code to be planted in order to do run-time checking for any undefined variables or array elements.


Program listing options

The options within this group specify the kind of program listing that the compiler is to provide.

/DUMP
Output a variable dump in listing file.

/EXPLIST [<filename>]
Generate a listing file containing a symbolic assembler listing. <filename> is the optional name of the .LIS file. /EXPLIST is equivalent to /LIST but causes each source statement to be followed by the 32-bit Intel assembler statements corresponding to the instructions into which it was compiled. The assembly language listing is fully symbolic. Information about 32-bit Intel assembler can be found in one of the Intel Programmer's Reference Manuals.

/LIST [<filename>] more...
Produces a source listing file. If <filename> is not provided, the name is created by replacing the source-suffix with .LIS, e.g. with FOO.F90, the map file would be FOO.LIS.

/LIST_INSERT_FILES
Used with /LIST to include INCLUDE files in listing.

/MAP [<filename>]
Produces a linker map. If <filename> is not provided, the name is created by replacing the source-suffix with .MAP, e.g. with FOO.F90, the map file would be FOO.MAP.

/NO_BANNER
Suppress compilation logos.

/NO_OFFSETS
Suppresses the output of address offsets in the source listing.

/NO_SCREEN_MESSAGES
Suppresses messages when using /LIST.

/XREF [<filename>]
Generates a cross-reference .XRF file. If <filename> is specified, the file name is created by replacing the source file-name's suffix with .XRF, e.g. with FOO.F90, the resulting name would be FOO.XRF.


Error message options

All error, warning and comment messages are output to the compilation listing file if one is specified or implied, otherwise, these messages are output on the screen. Note that these messages are never simultaneously output to the compilation listing file and on the screen. Messages fall into three categories - error, warning and comment.

The following list includes options for disabling certain messages and options for specifying what constitutes an error.

/132
Prints error messages formatted for 132 column screens.

/ANSI
Old synonym for /ISO option.

/BRIEF
Causes all errors, warnings and comments to be output in a form which is compatible with the SIDE and Borland BRIEF text editors. Programs can then be compiled and then edited whilst still within the editor.

/COLOUR
Compiler output in a Comand Prompt box is coloured. See Silverfrost environment variables to change default settings.

/DELETE_OBJ_ON_ERROR
If /LINK or /LGO is used no permanent object module is created. Otherwise, by default an object module will be generated even when errors are present. /DELETE_OBJ_ON_ERROR overrides the default.

/ERROR_NUMBERS
Error messages are accompanied by their error number.

/ERRORLOG
Creates a file called <filename>.ERR containing a copy of all error and warning messages.

/IGNORE <error number>
Suppresses all errors and warnings with the given number. Error numbers are generated using /ERROR_NUMBERS. Suppressing error numbers is unsafe but may be useful during debugging.

/IMPLICIT_NONE
Fault on IMPLICIT type definitions.

/ISO
Ensures that all constructs used in a program conform to the Fortran 95 ISO Standard. The /ISO option also informs the FTN95 run-time system that ISO-conformity is required. This means that, for example, non-standard use of format descriptors (such as business editing in a run-time format) causes a run-time failure.

/MESSAGE_SET_TO_COMMENT
Sets all compiler diagnostic messages to comment severity.

/MESSAGE_SET_TO_ERROR
Sets all compiler diagnostic messages to error severity.

/MESSAGE_SET_TO_FATAL
Sets all compiler diagnostic messages to fatal severity.

/MESSAGE_SET_TO_SUPPRESS
Applies /IGNORE to all error numbers.

/NO_COMMENT
Suppress compiler comments, but not warnings and errors.

/NO_FAIL
Synonym for /PERSIST.

/NO_OBSOLETE
Suppress reports of obsolete and extension warning messages after the first has been displayed.

/NO_QUIT
Suppresses the simulated quit after a bad compilation. This normally simulates a ^C to halt a batch-file compilation. With this option set

IF ERRORLEVEL 1

must be use to test for compilation failure in a batch file if this option is set, or alternatively

IF NOT EXIST <file>.OBJ

if the /DELETE_OBJ_ON_ERROR option is also used.

/NO_SCALAR_TO_ARRAY
Treats the assignment of a whole array to a scalar value as an error.

/NO_WARN_WIDE
Suppresses warnings for characters appearing in columns 133 (free format) or 73 (fixed format) and beyond in the source file.

/NON_STANDARD
Suppresses compiler messages that warn of syntax that is permitted by the FTN95 compiler but does not conform to the Fortran 95 standard. Such warnings will be converted to errors if /IOS is used. /NON_STANDARD is switched on by default.

/PAUSE_ON_ERROR
Outputs error/warning/comment messages one at a time and waits for a key press after each message.

/PERSIST
By default compilations with errors will terminate as if control break had been pressed. When the command appears in a batch file, the batch process will then be interrupted. If /PERSIST is used, the control break is suppressed and processing of the batch file will continue even when compilation errors have occurred.

/RESTRICT_SYNTAX
Increases compiler strictness to reject dubious code.

/SET_ERROR_LEVEL <code> <number>
Changes the severity of a compiler diagnostic. <code> is Suppress, Comment, Warning, Restricted, Error, or Fatal. <number> is the error number reported by using /ERROR_NUMBERS.

/SILENT
Suppress warning and comment messages. Also when /SILENT is used, the message that is output on the screen at the end of the compilation of a program unit does not include the numbers of warning and comment messages.

/SINGLE_LINE
Only prints the first line of an error message, ignoring any continuations. This is ignored if /BRIEF is specified. Without this option, when an error is reported, the offending line is output together with any continued lines.

/STANDARD_ERROR_REPORTING
Suppress windowed diagnostic information.

/UNLIMITED_ERRORS
Carry on compiling even after 12 error messages.

/WARN_FATAL
All warnings and comments become errors.

/WRAP
Source lines are wrapped rather than truncated when an error or warning is output.

/WIDE_SOURCE
Line-truncation at the 132nd (or 72nd) column is suppressed.


Properties of the code

/64
Produce 64-bit code

/ALLOW_RECURSION
Allows procedure recursion when the RECURSIVE attribute has not been specified (not recommended).

/ANSI
Old synonym for /ISO option.

/CKC
Win32 only. Appends "__C" to C_EXTERNAL aliases that do not start with a double underscore.

/CONVERT
Converts fixed-format source into free-format, output to the screen. All comments are lost and Hollerith constants replaced with strings. This is useful for converting fixed-format INCLUDE files into files suitable for both fixed and free formats. This option implies the /NO_BINARY option and no error checking, other than for matching brackets and checking the fixed-format column rules, is done. All other options on the command-line are ignored.

/CONTAINING_CLASS <classname>
only. Supplies a fully qualified class name to hold the Fortran code when used with /LINK.

/DO1
Causes DO loops to be executed at least once to allow certain Fortran 66 programs to execute correctly.

/F_STDCALL
Win32 only. Applies the F_STDCALL keyword to all user-defined and imported subprograms. Standard intrinsics, FTN95 intrinsics and FTN95 library routines are automatically excluded. FTN95 routines such as CISSUE must be renamed CISSUE@. Certain Fortran language restrictions apply and, in particular, INTERFACE statements may not be used with this option. When used with /CHECK, certain checking processes are not implemented. In particular, what are called "write-ability" checks are not applied. This means that it is advisable to test your code using /CHECK (or /CHECKMATE say) without using /F_STDCALL.

/F2K
Permits the use of some Fortran 200x statements as an extension.

/FIXED_FORMAT
Accept source code in ISO fixed source format. This is assumed for files with .FOR or .F suffixes. If the name of the source file on the command line has no suffix and this option is supplied then .FOR is assumed to be the suffix.

/FREE_FORMAT
Accept source code in ISO free source format. If the name of the source file on the command line has a suffix which is not .FOR and not .F, this option is assumed. If the name of the source file on the command line has no suffix, .F90 is assumed.

/IMPLICIT_NONE
Fault on IMPLICIT type definitions.

/INCLUDE <pathname>
Allows specification of list of include paths. This is appended to the list of include-paths optionally specified in the environment variable F95INCLUDE.

/ISO
Ensures that all constructs used in a program conform to the Fortran 95 ISO Standard. The /ISO option also informs the FTN95 run-time system that ISO-conformity is required. This means that, for example, non-standard use of format descriptors (such as business editing in a run-time format) causes a run-time fail ure.

/MAC_EOL
Specifies that the source code uses Apple Macintosh end-of-line characters.

/MOD_PATH <pathname>
Sets alternative path for module files. More than one /MOD_PATH is permitted. This is appended on to the path contained in the optional environment variable MOD_PATH.

/OLD_ARRAYS
INTEGER A(1) implies INTEGER A(*) when declaring procedure arguments.

/OVERFLOW
only. Implied by /CHECKMATE. Can be used in release mode to trap overflow by planting a call to CHECK_FINITE@ after every floating point calculation.

/SAVE more...
Do not use the stack for storage of local variables and arrays. Otherwise dynamic storage is used for all local variables and arrays. This has the effect of a blank Fortran SAVE statement in each subprogram. Its use should normally be avoided.

/STACK <size>
only. Sets stack size per thread when using /LINK or /LGO.

/TABS <integer>
By default FTN95 assumes that tab characters in the code correspond to fixed tab positions at intervals of 8 characters. This option can be used to change to some value other than 8.

/UNDERFLOW more...
Win32 only. Used to trap underflow.

/VERSION
Display version information.

/WINDOWS
Win32 only. Program is compiled for use with ClearWin+.

/ZEROISE more...
All static variables and arrays set to zero at start of execution.


Default KIND values for intrinsic types

/ALT_KINDS
Allows byte size for KIND numbers. e.g. REAL(8) instead of REAL(2); also 1.0_8 instead of 1.0_2 but 1.0_K must use the default KIND values.

/DEFINT_KIND <kind>
Sets the default INTEGER kind. Use kind=2 or 3. kind=3 is the default.

/DEFLOG_KIND <kind>
Sets the default LOGICAL kind. Use kind=1 or 2 or 3. kind=3 is the default.

/DEFREAL_KIND <kind>
Sets the default REAL kind. Use kind=2 or 3. kind=3 is for Win32 only.
/DEFREAL_KIND 2 also promotes all variables declared as REAL*4 or REAL(1) to double precision. In this respect it is the same as the option /DREAL and is unlike the behaviour of /DEFINT_KIND. Similarly (for Win32) DEFREAL_KIND 3 is the same as /XREAL.

/DREAL more...
Set the default KIND for type REAL to be 2 (DOUBLE PRECISION).

/XREAL
Win32 only. Sets the default KIND for type REAL to be 3.

/INTS more...
Set default KIND for type INTEGER to be 2.

/INTL more...
Set default KIND for type INTEGER to be 3 (this is the default).

/LOGS more...
Set default KIND for type LOGICAL to be 2.

/LOGL more...
Set default KIND for type LOGICAL to be 3 (this is the default).


Optimisation of code

/OPTIMISE more...
Invoke the peephole and tree optimisers. /CHECK, /UNDEF, /DEBUG and their variants are incompatible with this option.

/P6
Uses some instructions which are only available on a Pentium Pro (P6) (or better) processor. /OPTIMISE can be ON or OFF when using /P6.


Destination for binary code

/BINARY <filename>
Used to specify the .OBJ file name. If this option is omitted, the OBJ file name is created by replacing the source file-name's suffix with .OBJ, e.g. with FOO.F90, the object file would be FOO.OBJ.

/CONTAINING_CLASS <classname>
only. Supplies a fully qualified class name to hold the Fortran code when used with /LINK.

/DELETE_OBJ_ON_ERROR
If /LINK or /LGO is used no permanent object file is created. Otherwise, by default an object file will be generated except when errors are present. /DELETE_OBJ_ON_ERROR represents the default and must be negated to prevent the object file from being deleted.

/MKLIB
Win32 only. Generates a static library containing a separate object for each function or subroutine.
/MKLIB causes FTN95 to call the Silverfrost library manager called SLIM. Objects in the resulting static library may work correctly with the debugger SDBG. The use of SLIM objects with SDBG is not supported.

/NO_BINARY or /NO_CODE
Suppresses the creation of an object module.


Compilation statistics

/PROFILE
Win32 only. Inserts code to record how many times each line is executed.

/STATISTICS
Print the number of lines compiled and the compilation speed on the screen.

/TIMING
Plants code to do per-routine timing (see /TIMING).


Using the preprocessor

/FPP
Invoke the preprocessor on all input files (this is required in order to use CIF/CELSE/CENDIF when /SPARAM and /VPARAM are not used). This option is implied by /CLR.

Silverfrost FTN95 Preprocessing

/SPARAM <integer>
Sets the value of all SPECIAL PARAMETERs.

/VPARAM <name> <integer>
Like /SPARAM but allows the user to define a SPECIAL PARAMETER by name, instead of having all the same value (over-rides SPARAM).

/DEFINE <name> <integer>
As VPARAM. Values defined by either DEFINE or VPARAM can be used within the Silverfrost FTN95 Preprocessor or the C-style preprocessor.

/CFPP
Invoke the C-style preprocessor on all input files. Use this for #if, #ifdef, #endif statements.

C-style Preprocessing


Automatic loading after compilation

/ASMBREAK
Win32 only. Like /BREAK but enters debugger at assembler level.

/BREAK
Win32 only. Implies both /CHECK and /LGO and causes a break to the symbolic debugging facility at the first executable statement.

/DBREAK
Win32 only. Implies /LGO and causes a break to the symbolic de bugging facility at the first executable statement (i.e. like /BREAK, but /CHECK is not implied).

/HARDFAIL more...
Win32 only. Used with /LGO to suppress entry into the debugger in the event of a run time error.

/LGO more...
Compile, load and execute.

/LIBRARY<filename>
Specification of relocatable binary library and input files when using /LGO or /LINK.

/LINK [<filename>] more...
Generates an executable file, DLL or relocatable library (in the case of .NET, a .NET assembly file or module). If <filename> is not provided, the name is created by using the source file name. For example, FOO.F95 would generate a Win32 executable called FOO.EXE.

/PARAMS <param-list> more...
Used with /LGO or /BREAK to pass options to the program rather than the compiler. This must be the last FTN95 option on the command line.

/UNDERFLOW more...
Win32 only. Used with /LGO to trap underflow.


Others

/?
Gives a list of options when FTN95 is used from a command line in a Command Prompt box.

/CONFIG
Set-up installation compiler defaults. This must be the only option on the command-line.

/DEBUG_SOURCE
Adds a call to DEBUG_SOURCE@ after every executable line.

/HELP
Invokes the Windows based help system.

/OPTIONS <filename>
Specifies a file containing additional compiler options.

/RUNTRACE
Adds a call to RUN_TRACE@ after every executable line.

/SEARCH_INCLUDE_FILES
Searches through INCLUDE files for CONTAINS. Switch this on only if an INCLUDE file contains executable statements. This option is set by /ISO. Using this option will speed the compilation when compiling programs containing many INCLUDE statements.


Compiler directives

FTN95 will successfully process simple programs which contain only Fortran source statements. Such usage of the compiler implies that, for many options such as run-time diagnostics, either the system default will operate or a FTN95 compiler option must be used to change this default for the whole program source. Clearly, in the case of large or complex programs, this is not satisfactory. FTN95 therefore provides a number of compiler directives (described below) which can be used to give fine control over the facilities that are available. Compiler directives can also be embedded within comments.

The following table provides a list of compiler directives that can be inserted into the FTN95 source code.

Directives | Purpose
OPTIONS | To specify one or more compiler options in a source file
INCLUDE '<pathname>' | To insert the contents of the specified file at the current point in the compilation. Useful for frequently used common blocks etc. (this is included in the draft Fortran 95 standard).
LIBRARY '<pathname>' | Used with /LINK and /LGO to access a specified library.
IMPLICIT NONE | Forces the programmer to give every variable an explicit type (this is included in the Fortran 90 standard).
CODE & EDOC | To start and terminate a 32-bit assembler sequence. These directives are only allowed if an /ISO compiler option has not been selected
WINAPP | Creates a Windows executable for use with ClearWin+ (see the ClearWin+ documentation for further information).

The following notes apply to all compiler directives:

  • In fixed format files, each directive must start in column 7 or beyond.

  • Unless otherwise stated, a compiler directive may appear anywhere in a source program.

  • For fixed format Fortran, spaces have no significance except in file names which appear as character constants within quotation marks.

  • Compiler directives other than CODE and EDOC must not be la belled. (CODE and EDOC can be treated as executable statements should this be desired.)


The OPTIONS directive

The OPTIONS compiler directive provides a means of specifying many but not all of the compiler options within a source file. For example:

OPTIONS(SILENT,DREAL)

could appear in a file instead of using the command line options /SILENT and /DREAL.

  • An OPTIONS directive can only appear before the first program unit, or between program units, in a source file.

  • There is no limit to the number of OPTIONS directives that can appear in the source file.

  • When invoking the compiler from a command line in a Command Prompt window, there are three methods for configuring the compiler and their order of precedence is significant. Default compiler options, configured by using the command FTN95 /CONFIG, are read first and are superseded by any command line compiler options (including those presented via a /OPTIONS file). These in turn are superseded by any compiler directives given in the program.


The INCLUDE directive

It is possible to include source statements and compiler directives from another file by means of an INCLUDE directive which may appear anywhere in the current source file. This directive takes the form:

INCLUDE 'pathname'

where pathname is the name of a file containing Fortran source statements and compiler directives. If the pathname includes an extension then this must appear in the directive. For example:

   INCLUDE 'COLOURS.INS'

includes the given file from the current directory.

An alternative (non-standard) form of the INCLUDE directive is available, illustrated by the example:

   INCLUDE <COLOURS.INS>

which includes the given file from the INCLUDE sub-directory of the Silverfrost compiler directory.

Note that a source program may contain any number of INCLUDE directives each of which can, optionally, specify a different file. INCLUDE directives can be "nested" to a depth of 10. Thus one INCLUDEd file can itself contain other INCLUDE directives.


Comment embedded directives

Compiler directives can also be embedded within comments. For example:

!FTN95$OPTIONS(SILENT,CHECK)

or, in fixed format form:

CFTN95$OPTIONS(SILENT,CHECK)

The use of this form produces code that conforms to the ISO Fortran standard. The comment character (! or C) is followed by FTN95$ and then one of the following directives.

Directive | Purpose
OPTIONS | an alternative form for the OPTIONS(...) directive
WINAPP | an alternative form for the WINAPP directive, takes three arguments as described in the ClearWin+ documentation (Win32 only).
FREE | sets to free format (see note 1)
FIXED | sets to fixed format (see note 1)
RESTORE_FORMAT | restores the last source format (fixed or free) (see note 1)
INHIBIT_OPT | disables a list of optimisation numbers (like /INHIBIT_OPT) (see note 2)
ENABLE_OPT | restores a list of optimisations that have been inhibited by earlier use of INHIBIT_OPT (see note 2)
INHIBIT_CHECK | disables a list of checking options (like /INHIBIT_CHECK) (see note 2)
ENABLE_CHECK | restores a list of checking options that have been inhibited by an earlier use of INHIBIT_CHECK (see note 2)
SET_ERROR_LEVEL | same as the /SET_ERROR_LEVEL compiler option
LIBRARY | an alternative form for the LIBRARY directive
DEFINT_KIND | same as the /DEFINT_KIND compiler option
DEFREAL_KIND | same as the /DEFREAL_KIND compiler option
DEFLOG_KIND | same as the /DEFLOG_KIND compiler option
ATTRIBUTE | an alternative form for the .NET ATTRIBUTE command
ASSEMBLEY_EXTERNAL | an alternative form for the .NET ASSEMBLY_EXTERNAL command
ASSEMBLEY_INTERFACE | an alternative form for the .NET ASSEMBLY_INTERFACE command
STDCALL | an alternative to using F_STDCALL (not .NET); can be used before an EXTERNAL statement as well as before a SUBROUTINE or FUNCTION definition
DLLEXPORT | marks an external subprogram for export from a DLL (not .NET)
IGNORE | like /IGNORE but should be placed at the top of a file with a comma separated list of error numbers to ignore

Notes:

  • FIXED, FREE and RESTORE must not appear within a statement that is continued on the next line.

  • INHIBIT_OPT and ENABLE_OPT must appear immediately after the FUNCTION/SUBROUTINE/PROGRAM line of a subprogram and must not be used in a local subprogram (i.e. after a CONTAINS statement).


Diagnostic facilities

Program Development Diagnostic Facilities

FTN95 provides extensive diagnostic facilities which enable programs to be speedily developed and debugged. Diagnostics can be output

  • during compilation,

  • during loading,

  • at run-time.


Using modules

Modules in Fortran 95

Using modules for global data

Modules for data abstraction

Modules and FTN95


Modules in Fortran 95

The concept of modules is a powerful feature defined by the Fortran 90 standard which did not exist in the Fortran 77 standard. Modules can be used for many purposes, from sharing data between subroutines and functions (somewhat in the manner of COMMON, but in a cleaner, more abstract way), to providing support for user-defined data types and operations thereon.

The first part of this section provides a brief introduction to the syntax of module definitions and references by means of some examples. This is one of the few language-related areas expanded to this level in this manual and is intended as a supplement to the description in the accompanying textbook. This is because this topic is perhaps the most important aspect of the new facilities added to Fortran 77 by the Fortran 90 standard and many of the ideas will be somewhat unfamiliar to some Fortran 77 programmers.

The second part of this section discusses how these ideas are implemented, in terms of what happens when a MODULE is compiled under FTN95.


Using modules for global data

Modules provide an alternative method to using COMMON blocks for sharing data between different program units without passing such data as arguments. While the end result is similar, the two achieve this effect in different ways. COMMON relies on "storage association" -- a COMMON block definition specifies the layout of a region of storage, and since other COMMON definitions refer to the same region of storage, different routines can access the same data. It is left up to the programmer to check that the common definitions match. Many programmers make use of the INCLUDE facility (non-standard in Fortran 77) to ensure that the same definition of the common block is used in every place. There is no mechanism for ensuring that a particular piece of storage in the common block is not used as an integer in one place and a floating point quantity in another (although a number of static analysis tools are available which will perform this kind of checking).

By contrast, the way that modules share data is by "name association". Each of the names accessible from a program unit referencing the module is made known together with its type, so that the referencing module refers to a central definition of the data contained in the module. This removes the possibility of conflicting declarations.

An example of a module used in this way follows:

MODULE DATA_MODULE
 REAL :: ARRAY1(10), B, ARRAY2(20,20)
 INTEGER :: COUNT=0
 INTEGER, PARAMETER :: ORDER=10
 COMPLEX C_ARRAY(ORDER,ORDER)
END MODULE DATA_MODULE

The module can be referenced with a USE statement in the program unit which requires access to the global data. USE statements must come after the subprogram header statement (i.e. PROGRAM, SUBROUTINE, FUNCTION etc.) and before the local declarations for the program unit. The syntax of the USE statement provides some flexibility, allowing only specified entities to be accessed, or allowing certain entities to be used under a different name from their declaration in the module.

Here are some examples based on the module definition above. To allow you to reference all the objects in the module without qualification:

USE DATA_MODULE

To allow you to reference only the arrays, use:

USE DATA_MODULE, ONLY: ARRAY1, ARRAY2, C_ARRAY

It is possible to rename some objects defined in the module. This allows local objects with the same names as objects in modules to be defined. In this example ARRAY1 and ARRAY2 are renamed to be referred to as VECT and MATRIX:

USE DATA_MODULE, VECT => ARRAY1, MATRIX => ARRAY2


Modules for data abstraction

As well as containing data declarations, modules can contain subroutine and function definitions which provide operations on the data. Used in conjunction with the PRIVATE attribute, to make particular data objects not directly accessible from outside the module, this provides a mechanism for construction of aggregate types and a set of operations which are allowed on them.

The following example implements some operations on integer sets: Example

There are a number of points to note here:

  • The module defines a type SET, which can be used to declare objects in the program unit referencing the module. However, the components of the type are PRIVATE, which means they can only be accessed by procedures within the module. The referencing routine thus has no dependence on precisely how the type is implemented. In the above example the set is implemented by a fixed length array, but this could be changed to a scheme where the set is represented by a linked list, without the code which uses the module needing to be recompiled.

  • An operator ".IN." has been defined. This returns logical .TRUE. or .FALSE. depending on whether the integer specified by the left operand is a member of the set specified by the right operand. The ".IN." operator is used within the module itself in two places.

  • The "*" operator is overloaded with the operation of set intersection. This means that applying the "*" operator to two sets will return another set which is the intersection of the two. Of course, use of "*" with two integers still has the meaning of multiplication. Attempting to use "*" with an integerand a set for example will produce a compilation error "No specific match for reference to generic *".

  • The procedure CARD defined in the module is accessible to the referencing routine. Note that a procedure to extract the cardinality of the set is necessary, since the component CARD of the SET type is not directly accessible outside the module.

A trivial example illustrating use of this module follows:

PROGRAM SET_TEST
USE INTEGER_SETS

TYPE (SET) S1,S2

S1 = BUILD_SET( (/ 7,3,1,8,4,5 /) )
S2 = BUILD_SET( (/ 2,4,6,8 /) )

PRINT *, 'S1 : ', CARD(S1), ' ELEMENTS: ',VECTOR(S1)
PRINT *, 'S2 : ', CARD(S2), ' ELEMENTS: ',VECTOR(S2)
PRINT *, 'S1*S2: ', CARD(S1*S2),' ELEMENTS: ',VECTOR(S1*S2)

END PROGRAM SET_TEST

This produces the output:

S1 : 6 ELEMENTS: 1 3 4 5 7 8
S2 : 4 ELEMENTS: 2 4 6 8
S1*S2: 2 ELEMENTS: 4 8


Modules and FTN95

When looking for a module, say "LONG_NAME", FTN95 will look for a file called "LONG_NAME.MOD" if it is a Win32 compiler, or "LONG_NAM.MOD" with a DBOS compiler. If this file cannot be found in the current directory, FTN95 will search the module-path. The module-path is constructed from the environment variable MOD_PATH together with any supplied /MOD_PATH arguments appended (/MOD_PATH is a compiler command line option). When using a DBOS compiler, if the MOD file is still not found, FTN95 searches for files named using the sequence below:

LONG_NAM.@00, ..., LONG_NAM.@09, LONG_NAM.@0A, ..., LONG_NAME.@0Z, LONG_NAM.@10, ..., LONG_NAM.@ZZ

This allows for modules whose names share the same first 8 characters.

Zero or more OBJ files will also be associated with a module. These are searched for using the module-path, and can be in different directories from their MOD files.

As an example, suppose we have a file C:\MODULES\DEF1.F90:

MODULE mod1
CONTAINS
SUBROUTINE proc1
PRINT *, 'HELLO'
END SUBROUTINE
END MODULE

and the file C:\MODULES\DEF2.F90:

MODULE mod2
USE mod1
CONTAINS
SUBROUTINE proc2
CALL proc1
END SUBROUTINE
END MODULE

both of which are compiled using a command line of the form:

FTN95 DEF<n> /BINARY C:\OBJECTS\DEF<n>.OBJ

Now given a program C:\SOURCES\PROG1.F90:

PROGRAM test
USE mod2
CALL proc2
END

then to compile this program we would need either a) the environment variable MOD_PATH to include "C:\MODULES" or b) the command line:

C:\SOURCES>FTN95 PROG1 /MOD_PATH C:\MODULES

if no environment variable MOD_PATH had been set (or did not contain the path "C:\MODULES".)

To compile and link correctly we would need the command line:

C:\SOURCES>FTN95 PROG1 /MOD_PATH C:\MODULES;C:\OBJECTS /LINK

or the environment variable MOD_PATH to contain both "C:\MODULES" and "C:\OBJECTS".

If the program is compiled using SLINK directly, then the module's OBJ files will need to be specified in the list of OBJ files, e.g. with SLINK we would need to use the following sequence to link PROG1:

LOAD C:\SOURCES\PROG1.OBJ
LOAD C:\OBJECTS\DEF1.OBJ
LOAD C:\OBJECTS\DEF2.OBJ
FILE PROG1.EXE


The FTN95 address space

FTN95 uses a 4 gigabyte address space. The address of any variable is an unsigned 32 bit integer. The smallest item that can be addressed has a size of one byte so, for example, a Fortran integer of default (4 byte) size spans 4 addresses. If your program data was based on a single one-dimensional integer array then its size would be limited to a value slightly below 1 Gb (approximately 1073 million). Normally, if the runtime data cannot be accommodated in RAM then the hard drive will be used as an auxilliary storage device with data being automatically swapped between the two.

The address space is reduced to 2Gb by most operating systems. However, some operating systems, including Windows XP Professional, provide a /3GB switch in boot.ini that extends the user's address space to 3GB. To take advantage of this additional memory, you must use version 1.32 (or later) of SLINK. By default, SLINK will produce executables with the 3GB address space provided that none of the debugging options are used. The SLINK commands (2GB and 3GB) allow you to change the default behaviour. For example, the command 3GB might sensibly be used whilst debugging (/DEBUG alone). However, the use of the SLINK command 3GB together with Silverfrost compiler checking options is potentially unsafe and is not supported.


Silverfrost environment variables

The following environment variables can be used with Silverfrost compilers in order to over-ride the default settings. Depending on the operating system, environment variables are defined in an AUTOEXEC.BAT file or by using the Control Panel.

MOD_PATH

MOD_PATH can be used in association with FTN95 in order to specify an additional search path for .MOD and associated .OBJ module files. For example,
SET MOD_PATH=C:\FTN95;C:\DBOS.DIR\INCLUDE
would result in FTN95 searching in these directories if the .MOD file could not be found in the current working directory.

F95INCLUDE

F95INCLUDE is like MOD_PATH and is used with FTN95 in order to specify an alternative search path for INCLUDE files that are presented between angled brackets. For example,
INCLUDE <WINDOWS.INS>

DATE_FAIL

If DATEFAIL=YES then a runtime error will occur if either of the Silverfrost library functions DATE@ and EDATE@ is used to return a date that is not year 2000 compliant (i.e. the 8 character form is used rather than the 10 character form).

TMPDIR etc.

TMPDIR can be used to set the directory to be used with OPEN(STATUS='SCRATCH') and the Silverfrost library routines TEMP_FILE@ and TEMP_PATH@. Other environment variables are also available as indicated in the following search order:
%TMPDIR%
%TMP%
%TEMP%
%HOMEDRIVE%+%HOMEPATH%
\TMP
\TEMP
current working directory.

SALFENVAR

SALFENVAR can be set to MASK_UNDERFLOW or UNMASK_UNDERFLOW in order to provide a default state for masking Win32 underflows (see Underflows).

LIB

LIB is used by SLINK and provides a search path for Win32 library files.

SCCINCLUDE

SCCINCLUDE is used to provide a search path for C/C++ include files to be used with the Silverfrost C/C++ compiler.

SOURCEPATH

SOURCEPATH is used by the Silverfrost Win32 debugger SDBG to provide an alternative search path for source files.

SALFORD_COLOUR

SALFORD_COLOUR is used by FTN95 to set colours for command line output. Different colours can be applied to the following types of messages output from FTN95:

Error Messages (default bright red)
Warning Messages (default bright yellow)
Comment Messages (default bright green)
Banners and Headings (default white)
Standard Lines (default bright white)
Pause Messages (default bright cyan)

The environment variable SALFORD_COLOUR is specified as a string containing a character corresponding to each of these message types, optionally separated by semi-colons. The following value are valid within the environment variable:

k - Black
b - Blue
g - Green
r - Red
y - Yellow
c - Cyan
m - Magenta
w - White

To make any colour bright, prefix the colour character with '-'.

Example

To set FTN95 command prompt messages to:

Error Messages - red
Warning Messages - bright magenta
Comment Messages - yellow
Banners and Headings - black
Standard Lines - bright cyan
Pause Messages - black

The following string should be provided for the environment variable SALFORD_COLOUR:

r;-m;y;k;-c;k;


Compilation diagnostics

During compilation, three types of messages can be output:

  1. ERROR MESSAGES which indicate that the rules Fortran 95 have not been obeyed, for example, that a label has been referenced but not defined. When FTN95 is invoked from a command line, error messages are preceded by *** (three asterisks).

It is possible (but not recommended) to load and execute a program that contains compilation errors (if the /PERSIST option was used) but unpredictable results will occur if the parts that are executed contain compilation errors. If /PERSIST is not used, the compiler will cease code generation once an error has been reported and the relocatable binary file will be marked to make it unloadable.

Note that certain error conditions become fatal when the /ISO option is used otherwise they are classed as warnings.

  2. WARNINGS are output for one of two reasons:

  • If the program is correct Fortran but probably contains a logic error. For example, the following statement is legal but will cause an infinite loop:

10 GOTO 10

In the following example, the compiler will warn that the second statement will never be executed.

RETURN
A = B
C = D
. . .

  • Each time the program uses those ex tensions to Fortran 95 which have been included in order to allow compatibility with Fortran 66.

For example, users converting programs containing Hollerith data will find their listings annotated with the message:

Warning: The use of Hollerith data is an extension to Fortran 95.

It is always possible to load and execute a program whose compilation produces only warnings.

  3. COMMENTS are informative messages. They serve to remind the programmer that there might be a better way of writing a particular statement. As an example, the statement

A = FLOAT(I)

would cause the compiler to output the message:

COMMENT: FLOAT could be replaced by its generic equivalent (REAL) throughout this program unit

When FTN95 is used from a command line, most messages are output immediately after the statement to which they refer.

If it is necessary to delay the output of a message or the source listing option has not been chosen, the message is followed by a line number which refers to the source file. Certain error messages referring to EQUIVALENCE statements are always output (with a line number reference) immediately after the first executable statement in a program unit has been listed.

Some messages, notably those referring to undefined or unused labels, are not output until the END statement of a program unit has been processed.

Each diagnostic message has an associated error number. It is possible to instruct the compiler to ignore every occurrence of the error associated with a particular error number by using the /IGNORE compiler option as follows:

FTN95 MYFILE /IGNORE <error number>

where <error number> is the number of the error that is to be ignored. This number can be obtained by using the /ERROR_NUMBERS compiler option in an earlier compilation that exhibits the error. More than one /IGNORE option can be specified, if it is desired, in order to ignore several errors.

Note:

If messages other than warnings or comments are ignored, the compiler may generate incorrect code.


Linker diagnostics

During the linking of a program, the relocatable binary code that has been output by the compiler is linked with routines from the Fortran 95 library and from other relocatable binary files and libraries specified by the user. There are a number of error and warning messages that can be output by the linker, most of which are self-explanatory.

A commonly occurring message is one that reports that a routine is missing. A name can appear as "missing" for either of the following reasons:

  1. A routine of the specified name is not available to the linker because:

  • an appropriate LIBRARY directive has not appeared in the source program or

  • the name of a library routine has been misspelt. A commonly occurring error is the use of the letter O instead of the digit 0 in calls to library routines, for example, the use of MO1ANF instead of M01ANF.

  2. The name was intended to be an array element name but has not been dimensioned. It has then been used only in a function reference, a CALL statement or on the right hand side of an assignment statement, for example:

B = A(3)
CALL SUB(A(I),X)
C = F(A(I+J))

Fortran is defined in such a way that each of the above would generate a reference to a function called A. The name A would be out put by the loader as "missing".

Note:

If the "missing" name corresponded to a routine in a library compiled in CHECK mode, a run-time error might occur saying that the routine had been called inconsistently. In the worst case, an appropriate routine with consistent arguments would be loaded and the program would run with unpredictable results!

Programs with missing routines can be executed up to the point at which a missing routine is called.


Run-time diagnostics

Comprehensive run-time diagnostic facilities are provided by the system in such a way that users can always choose the level of checks that are applied to any part of their program.

During the early stages of program development, it is useful to have all or most of these checks performed by the system but later, when the program is thought to be thoroughly tested, it is usual to remove checks in order to achieve the fastest possible execution speed and smallest possible object program size. If new routines or lines of code are added to an existing program, it is a simple matter to specify that checks should be performed only on the pro gram units that have been changed.

The available run-time diagnostic information is controlled by directives which may appear before any program unit. Note that the default level of checks to be applied can be set by one of the FTN95 compile-time options /CHECK, /UNDEF or /QUICK_BOUNDS. These keywords may also appear as part of an OPTIONS directive.

For example:

OPTIONS (CHECK)
OPTIONS (UNDEF,CHECK)

Once an error has been detected by the checking mechanism, execution terminates and the system enters the symbolic debugger to give diagnostic information.

The run-time checks are described more fully in the topics that follow in browse order.


Arithmetic overflow checking

No computer permits the storage and manipulation of arbitrarily large quantities. The following limits apply when using FTN95:

INTEGER (KIND=1) | -128 to +127
INTEGER (KIND=2) | -32768 to +32767
INTEGER (KIND=3) | -2147483648 to +2147483647
REAL (KIND=1) | (1E-37 to 1e+39) (approx.)
DOUBLE PRECISON | (1D-307 to 1D+309) (approx.)

If a calculation is performed whose result exceeds these limits arithmetic overflow occurs.

If a CHECK directive appears in the source pro gram, then runtime checking for overflow is enabled.

If a checked statement does set overflow then execution is terminated and the interactive debugger is entered. If a statement sets overflow and is not checked, then execution continues with an in correct result in the case of integers, but terminates in the floating point case.

When a program is loaded, all numeric variables (except those which have appeared in a DATA statement) are initialised to an "undefined" value unless the /ZEROISE compile-time option is used.

In the case of integer variables, the undefined value chosen is -32640 which will not result in overflow being set as the result of an assignment and, furthermore, overflow will not always occur when an expression is evaluated which involves an undefined value.

Undefined variables can be trapped by use of the /UNDEF option (see below).

Note:
Variables and array elements in otherwise uninitialised common blocks are not initialised to the undefined value.


Argument consistency checking

There are a number of run-time checks associated with the calling of routines. A subroutine or function compiled with a checking option will produce a run-time error if one of the following occurs:

  1. Arrays used as actual arguments are too small for the declared size.

  2. An actual argument which is a constant or a local variable that is in use as a DO-variable is altered by the called routine. For example:

     CALL FRED(1.0)
     . . .
     DO I=1,100
       CALL FRED(I)
       . . .
     ENDDO
     . . .
     END
     SUBROUTINE FRED(N)
     . . .
     N = G
     . . .
     END

Either of the calls to FRED in the above example would cause a run-time error.

  3. A simple character argument is not large enough for its declared size.

In the absence of checking, these conditions result in program corruption with unpredictable results.


Array subscript checking

The /CHECK option ensures that every array reference lies within the storage allocated to the array. Each individual subscript expression is also checked. Consider the following coding:

DIMENSION
                A(10,10)
I = 11
J = 7
A(I,J) = 0.0

The storage element referenced by the subscripts lies within the declared storage for the array even though the first subscript is outside its corresponding bound. This is not valid Fortran 95 (although it is valid Fortran 66).

Using the above DIMENSION statement for A, it is apparent that the statement

I = 11
J = 10
A(I,J) = 0.0

would cause a run-time error if either of the compiler options were used.

In general, array bound checking incurs a run-time overhead of both store and execution speed. Full array bound checking for multi-dimensional arrays is very costly. The simpler array bound check is less so.

Array bound checking is available for arrays of any type. The array may have explicit dimensions, for example:

PARAMETER (N=10,M=6)
DIMENSION A(N,M),B(10,20)

or may be passed as arguments with variable bounds, for example:

SUBROUTINE FRED (A,B,C,N)
COMMON/ABC/M
DIMENSION A(M),B(N),C(*)

The checks will work in all cases for both upper and lower bounds.

Note: When using Fortran 90 assumed-shape arrays in an external subprogram, you must provide a corresponding INTERFACE statement where the subprogram is called.

If checking is not in use, unpredictable effects may occur at run-time. An attempt to transfer a value from an element outside the bounds of an array can either:

  1. assign or use an arbitrary value which might cause overflow, or

  2. cause the program to fail with general protection fault which means that the program has tried to access storage outside the limits available to it, or

  3. overwrite a pointer and cause a fault in a different part of the program.

If an attempt is made to transfer data to an element outside the defined bounds of an array without specifying the checks, the effects are to tally unpredictable and will frequently result in a spurious error when some unrelated part of the program is executed.


Checking for undefined variables (/UNDEF)

/UNDEF (which implies /CHECK) causes FTN95 to plant code to check that a variable or array element used in the circumstances described below has been previously given a value.

/UNDEF causes extra code to be planted for a name or array element appearing in the following circumstances:

  • as the right hand side of a non-character assignment,

  • in arithmetic expressions involving + - / * or **,

  • in relational expressions involving .NE. .EQ. etc.,

  • in logical expressions involving .AND. .OR. etc.,

  • as an array subscript,

  • as a substring expression,

  • as the argument to an ISO standard intrinsic function such as SIN, COS etc.,

  • as the expression used within a logical or arithmetic IF statement.

/FULL_UNDEF (also called /CHECKMATE) is like /UNDEF but also INTENT(OUT) arguments are initialised as undefined on entry to a procedure and by default character variables are initialised as undefined.

All local static variables are predefined to an undefined value. This value has HEX 80 in every byte. Routines compiled with /CHECK also clear their dynamic variables to this value on entry to the routine. This value is treated as undefined by the symbolic debugger. An undefined integer has one of the following values:

INTEGER (KIND=1) | -128
INTEGER (KIND=2) | -32640
INTEGER (KIND=3) | Z'80808080'

In rare cases, most likely when using integer data, the undefined integer value may be intended by the programmer and the use of /UNDEF will cause a spurious error to be reported. In this case, all that can be done is to compile the program unit(s) in question without /UNDEF. Note that:

  • The use of /UNDEF causes a significant run-time execution speed penalty.

  • It is necessary to compile the main program with this option if uninitialised common blocks are to be set appropriately.


Character data

The checking mechanism provides the following diagnostic checks for character data:

  1. That an argument of type character is of sufficient length for its declared dummy size. For example, in CHECK mode, the following program would cause a run-time error:

CHARACTER*20 A
. . .
CALL CHSUB(A)
. . .
END
SUBROUTINE CHSUB(X)
CHARACTER*30 X
. . .
END

The error could be prevented in this case by declaring X in the subroutine as follows:

CHARACTER(*) X

so that X would assume the character length of the actual argument.

  2. That substring expressions are valid. There are two possible sources of error that may arise when using a substring reference of the form A(I:J):

  • either the value of I is greater than the value of J or

  • the value of I is less than 1 or the value of J is greater than the declared or assumed length of the character variable or array element.

All of the character assignment statements in the following program would cause a run-time error:

CHARACTER*20 A,B(20)
. . .
I = 0
J = 21
K = 4
L = 3
A(I:) = 'X'
A(1:J) = 'XXX'
B(3)(K:L) = 'XXX'
END


Execution errors and IOSTAT values

All execution error messages consist of a message in English. These messages are listed below. Execution errors corresponding to input/output statements can be trapped by means of the ERR= and/or IOSTAT= keyword specifiers used with the input/output statements. The value returned by IOSTAT in this case is n where n is the execution error number that appears in the table below. Users are advised to trap specific errors by means of IOSTAT rather than to continue execution regardless of the error that has been detected by the input/output system.

Notes:

  • The IOSTAT value -1 indicates that an end-of-file condition has occurred.

  • The positive values chosen for IOSTAT in this implementation of Fortran 95 will, in all probability, differ from those chosen in any other implementation for the same error conditions.

Error No. | Message
0 | No error
1 | Floating point arithmetic overflow
2 | Integer arithmetic overflow
3 | Argument to CHAR outside range 0 - 255
4 | Character argument/function name of wrong length
5 | Attempt to execute invalid assigned GOTO
6 | Inconsistent call to routine
7 | DO-loop has zero increment
8 | User-specified range check error
9 | Might be array bound error or corrupt program - recompile with /CHECK
10 | Lower substring expression > upper
11 | Array subscript(s) out-of-bounds
12 | Lower substring expression out-of-range
13 | Illegal character assignment
14 | Attempt to alter an actual argument that is a constant, an expression, an INTENT(IN) argument, or a DO variable
15 | Attempt to access undefined argument to routine
16 | Lower array bound > upper bound
17 | Upper substring expression out-of-range
18 | This routine has been entered recursively (-ANSI mode)
19 | Actual array argument size smaller than dummy array argument size
20 | Argument to SINH/COSH out of range
21 | Zero raised to negative or zero power
22 | Floating point division by zero
23 | Floating point arithmetic underflow
24 | This source has not been compiled with /PROFILE
25 | Argument to EXP out-of-range
26 | Argument to ASIN/ACOS out-of-range
27 | Invalid floating point number
28 | Negative argument to square root
29 | Call to missing routine - %1
30 | Storage heap is corrupt
31 | Floating point number too big for integer conversion
32 | Second argument to MOD is zero
33 | Both arguments to ATAN2/DATAN2 zero
34 | Negative or zero argument to logarithm routine
35 | Illegal argument to TAN routine
36 | Negative number raised to non-integer power
37 | Integer divide overflow
38 | Illegal character assignment (R.H.S. overlaps L.H.S.)
39 | Illegal window
40 | No more windows available
41 | Maximum number of breakpoints already set
42 | This line number is not available as a breakpoint
43 | Invalid command
44 | Unable to open file
45 | String not found
46 | Routine not found or not compiled in check mode
47 | Invalid expression
48 | No more room for debugger information
49 | Attempt to call a block data subprogram
50 | Undefined input/output error
51 | Format/data mismatch
52 | Invalid character in field
53 | Overflow detected by input/output routine (data out-of-range)
54 | m > w in Iw.m run-time format
55 | m > w in Ow.m, Zw.m or Bw.m run-time format
56 | Unit has been closed by means other than a CLOSE statement
57 | Attempt to read past end-of-file
58 | Corrupt listing file
59 | There is no repeatable edit descriptor in this format
60 | Invalid external unit identifier
61 | Invalid scale factor
62 | Invalid or missing repeat count
63 | Preconnected file comprises formatted records
64 | Preconnected file comprises unformatted records
65 | This command is not permitted from this window
66 | File not in correct format
67 | Character buffer too small
68 | Field width exceeds direct access record size
69 | Invalid record length (see documentation)
70 | Logical input field is blank
71 | H or apostrophe editing not allowed for input
72 | Repeated formats nested too deep (>10)
73 | Missing opening parenthesis in run-time format
74 | Invalid editing descriptor
75 | A zero or signed repeat count or field width is not allowed
76 | Repeat count not allowed
77 | Digit(s) expected
78 | Decimal point missing
79 | Missing separator
80 | Invalid ACCESS specifier
81 | Invalid combination of specifiers
82 | ANSI - RECL is an invalid specifier
83 | Label does not reference a format statement
84 | Only BLANK may be changed for a file that exists for a given program
85 | Repeated character constant must not extend past the end of a line
86 | Character input/output list item is part of internal file
87 | ENCODE/DECODE character count zero or negative
88 | Internal file must not be constant or expression
89 | Attempt to write past end of internal file
90 | File access and properties are incompatible
91 | Missing ) from complex number
92 | Invalid CLOSE statement
93 | Missing ( from complex number
94 | Unit has neither been OPENed nor preconnected
95 | Invalid direct access record number
96 | Illegal operation (BACKSPACE/ENDFILE/REWIND) on a direct access file
97 | Direct access record length too big
98 | Invalid FILETYPE specifier
99 | A function which performs I/O must not be referenced in a WRITE or PRINT statement
100 | List-directed input/output is not allowed with direct access
101 | Direct access is not allowed with an internal file
102 | A formatted, direct access statement must only transfer one record
103 | Missing FILE specifier
104 | File positioned at end-of-file
105 | Invalid record length for existing direct access file
106 | A valid record length must be specified if access is direct
107 | STATUS=NEW must not be used with an existing file
108 | Direct access record length mismatch
109 | Brackets nested too deeply (>20)
110 | Unformatted record is corrupt
111 | Coprocessor invalid operation
112 | Reference to undefined variable, array element or function result (/UNDEF)
113 | Insufficient allocatable storage
114 | Emulator failure
115 | Reference to undefined object (/UNDEF)
116 | Too many files open
117 | Disk full
118 | ANSI - exponent out-of-range (use Ew.dEe or Gw.dEe edit descriptors)
119 | Down to page reserve
120 | Weitek coprocessor not available (use /WEITEK DBOS option)
121 | Too many registered traps
122 | No high resolution graphics mode is available
123 | Too many labels in debug macro file
124 | This command is only allowed in a macro
125 | A file of this name already exists
126 | ANSI - invalid STATUS specifier
127 | ANSI - invalid edit descriptor
128 | File does not exist
129 | Invalid attempt to use peripheral
130 | Unformatted record too big
131 | ANSI - octal/hexadecimal/binary input not permitted
132 | Device type not known on this installation
133 | Expression required
134 | File already in use
135 | Sign not at start of field in business editing descriptor
136 | Business editing not allowed for input
137 | Illegal operation after a BACKSPACE
138 | Attempt to write to a 'READONLY' file or inconsistent file access
139 | You may not write to a file that is 'READONLY'
140 | You cannot OPEN a directory
141 | ANSI - invalid $ in format descriptor
142 | $ editing not allowed for input
143 | Incorrectly positioned $ character in format descriptor
144 | Illegal name in OPEN/CLOSE/INQUIRE statement
145 | ANSI - the Aw edit descriptor must be used with an item of type CHARACTER
146 | File path not found
147 | Macro label not found
148 | Invalid hash table
149 | Value returned by RECL= or NEXTREC= will cause overflow (use INTEGER*4 instead of INTEGER*2)
150 | Count for ENCODE/DECODE must be in the range 1 to 32767
151 | Invalid FORM specifier
152 | Invalid STATUS specifier
153 | Invalid BLANK specifier
154 | Unpaired brackets
155 | Error detected by user-specified device driver
156 | Unexpected error in Fortran I/O system
157 | Do-loop will never be executed (/DOCHECK)
158 | Unformatted record is too short for input list
159 | Trailing sign or "CR" not at end of field in business editing descriptor
160 | Multiple leading sign before "$" in business editing descriptor
161 | "*" must precede "$" or "Z" in business editing descriptor
162 | "$" in wrong position in business editing descriptor
163 | "Z" after decimal point in business editing descriptor
164 | Decimal point appears more than once in business editing descriptor
165 | Comma at start of field or after decimal point in business editing descriptor
166 | Invalid character found in business editing descriptor
167 | DO-loop will never be executed (/DOCHECK)
168 | Unanticipated DOS error encountered in I/O system
169 | Underflow detected by input/output routine (data out-of-range)
170 | Equals missing
171 | Absolute value of complex argument out of range
172 | The left hand side of a LET must be a variable or array element
173 | You may not delete a file that is 'READONLY'
174 | Array has wrong number of dimensions
175 | Array subscript(s) out-of-bounds
176 | Unpaired quotes
177 | Name longer than 32 characters
178 | Variable is not an array
179 | Variable is an array
180 | Unknown variable
181 | Block IF unterminated on leaving a macro
182 | Error in the structure of WHILE-ENDWHILE block in a macro
183 | Error in the structure of block IF in a macro
184 | Display full
185 | Routine not found
186 | Unknown vector
187 | Parameters may not be altered
188 | Too many points to be plotted
189 | ANSI - invalid FORM specifier
190 | Attempt to read from a file opened with FORM='PRINTER'
191 | Key name expected
192 | Substring required, not an array index
193 | Pascal run time error
194 | Reference through NULL pointer
195 | Reference through invalid pointer
196 | Expected ON or OFF
197 | Requested a negative amount of memory
198 | Not enough storage heap to open window
199 | Run out of heap space
200 | Buffer overflow in namelist-directed I/O
201 | End-of-file in namelist input group
202 | Syntax error encountered while reading namelist group
203 | Too many values supplied for input array in namelist-directed input/output
204 | Invalid identifier in namelist input group
205 | Incorrect number of subscripts in namelist input
206 | Subscript or substring out-of-range in namelist input
207 | Invalid SHARE specifier
208 | You may not read from a file that is write-only
209 | Invalid ACTION specifier
210 | Invalid POSITION specifier
211 | Invalid DELIM specifier
212 | Invalid PAD specifier
213 | Invalid ADVANCE specifier
214 | You cannot use an ADVANCE specifier here
215 | Input record too short
216 | Invalid argument
217 | Divide by zero
218 | Fortran unallocated runtime message
219 | Fortran unallocated runtime message
220 | Fortran unallocated runtime message
221 | +, - or digit expected
222 | 1st parameter is undefined
223 | 1st string is undefined
224 | 2nd parameter is undefined
225 | 2nd string is null
226 | 2nd string is undefined
227 | Assign not allowed on an open file
228 | Bad file control block
229 | DA access not allowed for text files
230 | DA access not allowed to terminal or string
231 | DA not allowed for text files
232 | Digit expected
233 | DOS pathname unobtainable
234 | End of file
235 | EOLN used at EOF
236 | Failed to position to end of file
237 | Failed to position to record
238 | File cannot be closed
239 | File cannot be emptied
240 | File cannot be opened
241 | File cannot be positioned
242 | File cannot be reopened
243 | File cannot be rewound
244 | File has not been opened
245 | File is not open for reading
246 | File is not open for writing
247 | File is open for reading
248 | File is open for writing
249 | File is readonly
250 | File OUTPUT may not be reset
251 | File size is not a multiple of record size
252 | Heap slot has already been disposed
253 | Heap slot has been corrupted
254 | Heap slot is of the wrong size
255 | Invalid record number
256 | No EOLN before EOF
257 | No storage available
258 | Not enough room for insertion
259 | Not enough room for result
260 | Number too large
261 | Pascal system error
262 | Pointer is NIL
263 | Pointer is undefined
264 | Range error
265 | Set range error
266 | String files not allowed
267 | String is null
268 | String is undefined
269 | This operation only allowed for DA files
270 | Too many temporary files
271 | Undefined Boolean
272 | while reading from file
273 | while writing to file
274 | Reference through invalid C pointer
275 | Reference through NULL pointer %F
276 | Reference through un-initialised pointer %F
277 | Attempt to overwrite constant data
278 | Corrupt storage availability index
279 | Attempt to call Windows application routine when not in windows
280 | Run out of Windows selectors
281 | String is not terminated %F
282 | Invalid long jump %F
283 | Search has spilled outside storage area %F
284 | Negative count not permitted %F
285 | Concatenation would spill outside storage area %F
286 | Read has spilled outside storage area %F
287 | Conversion has spilled outside storage area
288 | Reference through dangling C pointer %F
289 | Reference to a portion of the format buffer which has been overwritten %F
290 | Essential arguments missing %F
291 | Not enough arguments to satisfy format %F
292 | Pointer does not point at a function
293 | Pointer references code - not data %F
294 | Storage block is not big enough for this operation %F
295 | Impossible number of bytes in copy operation %F
296 | Invalid FILE structure
297 | Invalid double passed to printf
298 | Invalid long double passed to printf
299 | Reference to missing C argument
300 | Corrupt destructor chain
301 | Attempt to create invalid SAI entry
302 | Attempt to 'free' memory allocated by 'new' - use 'delete'
303 | Attempt to 'delete' memory not allocated by 'new'
304 | This operation is not allowed on a windows stream
305 | Input/Output failure in the C library.
306 | Read operation has failed
307 | Write operation has failed
308 | Illegal attempt to close standard streams (stdin, stdout or stderr)
309 | Cannot read from a stream after writing without an intervening seek or fflush
310 | Cannot write to a stream after reading without an intervening seek.
311 | Unable to find length information to delete whole array with destructors
312 | Attempt to call a pure virtual function implicitly
313 | Illegal attempt to write to a read only file.
314 | Illegal attempt to read from a write only file.
315 | Illegal attempt to use low level IO functions on a file opened by ANSI C IO functions
316 | Object contains corrupt virtual function table pointer
317 | Pointer to member function has not been defined
318 | C library floating point error handler unexpectedly called. Contact your dealer!
319 | Attempt to exit a function without a return value
320 | Attempt to create overlapping SAI entry
321 | Invalid size must be > 0
322 | #define CREATE_CONSTRUCTOR
323 | #define SEEKMODE_SEEKOFFSET
324 | Invalid file handle
325 | Null buffer pointer or zero buffer size
326 | Automatic allocation of buffer failure
327 | Attempt to use an output stream for input - invalid mode
328 | Fail to open file
329 | Invalid index
330 | Available space is full
331 | #define STDIOSTRM_CONSTRUCTOR
332 | Invalid file mode - ios::in, ios::out or ios::app
333 | Invalid seek_mode - ios::beg, ios::end or ios::cur
334 | Attempt to write beyond buffer supplied to istream object
335 | #define CREATE_COUT
336 | #define CREATE_CIN
337 | Object already buffered or invalid buffer pointer or size
338 | #define STRSTREAMBUF_ALLOCATION
339 | Null pointer supplied to stream function
340 | Object is not a streambuf class
341 | Invalid window handle
342 | Reference to position beyond buffer
343 | Invalid stream pointer (FILE*=NULL)
344 | JUMP@ in incompatible with the .NET framework
345 - 357 | streams spare
358 | Special failed number type 2
359 | Special failed number type 1
360 | Invalid disk drive number (0=A, 1=B, etc..)
361 | Invalid file mode
362 | Invalid argument
363 | Invalid clearwin window's handle
364 | Invalid dialog handle
365 | Unable to dynamically allocate common block
366 | streams spare
367 | streams spare
368 | streams spare
369 | Function unimplemented in /CLR mode
370 | get_real_mode_memory_region can only be used on real mode memory (ie 0 to 0x10000000)
371 | Windows program could not be started (is LAUNCHER running?)
372 | Attempt to start Windows program outside Windows
373 | No characters read by scanf
374 | This operation requires a Pentium-class processor
375 | Attempt to free part of a storage block
376 | Attempt to delete unallocated storage
377 | Attempt to free unallocated storage
378 | Coprocessor stack is not empty (CHECKSTACK@)
379 | Attempting to close a standard stream is illegal
380 | Zero or negative array size not permitted
381 | Fortran run-time error
382 | Coprocessor stack overflow
383 | Coprocessor stack underflow
384 | Second argument to NEAREST is zero
385 | Real and imaginary parts of the argument to complex LOG are both zero
386 | The FROMPOS, LEN and TOPOS arguments of MVBITS must be nonnegative and not exceed BITSIZE(FROM)
387 | FROMPOS+LEN and TOPOS+LEN must not exceed BITSIZE(FROM)
388 | DIM out of range
389 | Nonconformant arrays
390 | Undefined pointer
391 | Disassociated pointer
392 | Corrupt pointer
393 | Inconsistent call to FTN95 routine
394 | ORDER array should have the same number of elements as SHAPE (RESHAPE)
395 | ORDER array is not a permutation of (1,2,...,size(SHAPE)) (RESHAPE)
396 | The result array size is different from the size of VECTOR (PACK)
397 | The result array size is too small (PACK)
398 | MASK is scalar with the value true, the size of VECTOR is less than the size of ARRAY (PACK)
399 | MASK is scalar with the value true, the size of ARRAY is different from the size of RESULT (PACK)
400 | SHAPE must be rank 1 (RESHAPE)
401 | ORDER must be rank 1 (RESHAPE)
402 | PAD must not be scalar (RESHAPE)
403 | VECTOR has insufficient elements (UNPACK)
404 | Result has insufficient elements
405 | Reference to undefined character (/FULL_UNDEF)
406 | Invalid call to random number seeder
407 | DEALLOCATE failed
408 | ALLOCATE was unable to obtain sufficient storage
409 | Field width zero not allowed on input
410 | A function called from within an I/O statement has itself performed I/O
411 | This access of date facilities is not Millenium compatible
412 | Preconnection unit number not in range 1-99
413 | Can't parse preconnection string
414 | Pathname is too long
415 | Missing closing parenthesis in run-time format
416 | Bad request for stack memory
417 | Non-conformant array shapes for matrix multiplication (MATMUL)
418 | MATMUL can accept, at most, one vector
419 | Reference through unset Fortran POINTER
420 | Reference through NULL Fortran POINTER
421 | Reference through dangling Fortran POINTER
422 | Attempt to DEALLOCATE invalid Fortran POINTER
423 | Attempt to DEALLOCATE part of a storage block
424 | Attempt to DEALLOCATE dangling Fortran POINTER
425 | Integer out of range for conversion to/from unsigned
426 | CHARACTER dummy argument defined to be larger than actual argument
427 | Reference through missing OPTIONAL argument
428 | Date out of range
429 | Internal Error: Stack pointer corrupt
430 | Internal Error: Floating-point stack not empty
431 | Active DO-loop index altered
432 | ALLOCATABLE object has already been ALLOCATEd
433 | A function called from within an I/O statement has performed I/O on the same unit
434 | An internal TempAlloc has not been TempFree'd
435 | Stack alignment fault
436 | Array intrinsic called with an unallocated array
437 | NCOPIES does not match DIM in SPREAD function
438 | Result of array intrinsic has not been allocated memory
439 | Floating point overflow on exponentiation x**y
440 | Integer overflow on exponentiation x**y
441 | Invalid argument for OPENRW@/OPENR@/OPENW@/OPENF@
442 | Invalid address passed to RETURN_STORAGE@
443 | Negative argument to SQRT routine
444 | Insufficient virtual stack (FTN95 /VSTACK )
445 | Internal virtual stack failure
446 | Negative or zero ALLOCATE
447 | Positive width required when using E or G format descriptor
448 | Value returned by INQUIRE POS=ivalue will cause overflow. Use higher KIND
449 | Missing NEW_LINE at end of STREAM record
450 | The given POS value does not match the start of a STREAM record
451 | Memory corrupted before call to LEN_TRIM


Profiling

It is often useful to know how many times each statement in a program has been executed. Such information may reveal logical errors and can often help in tracing the execution path in the event of a run-time failure. It will also indicate which parts of a program are most heavily used so that those parts can be examined and recoded to improve execution speed should this be considered worthwhile. Profiling has a further use in ensuring that test data exercises all parts of a program.

Profiling is only available for a Win32 platform. For some .NET programs you can temporarily change to Win32 in order to make use of this facility.

Profiling is enabled by using the FTN95 command line option /PROFILE. Once profiling is enabled each executable statement is compiled so that a count is kept at run-time of the number of times that statement is executed.

Profiling information is viewed from the debugger SDBG so it is necessary to compile the program using one of the debugging options (e.g. /DEBUG or /CHECKMATE). When you run the program using SDBG (either to a break point or to completion), the number of times each line of code is executed appears in a column on the right hand side of the code window.

SDBG can be launched from the command line (see Invoking SDBG) or from Visual Studio by selecting Debug and then Start from the main menu.


Win32 platform

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Using the linker

SLINK is Silverfrost's 32-bit linker for Win32. It is designed to accept Win32 COFF object files and produce Win32 libraries (.LIBs), Win32 Portable Executable (PE) executables (.EXEs) and Dynamic Link Libraries (.DLLs). SLINK has been designed to make it powerful and easy to use.

SLINK will act either as a library builder or as a conventional linker or both simultaneously. SLINK is tailored for object code produced by Silverfrost compilers. It can, however, be used with COFF object code produced by other compilers. SLINK will not accept 32 bit OMF object code, the native object code format for OS2/2.


Getting started

SLINK has three modes of operation:

  1. command line mode,

  2. interactive mode and

  3. script file mode.

Command line mode takes all parameters from the command line whilst interactive mode processes commands one at a time as they are entered from the keyboard. This is very similar to LINK77, the Salford linker for the DBOS family of compilers. Script file mode reads the commands from a text file. This has two variations, a Salford LINK77 compatible command mode and a Microsoft compatible command mode.

It is easy to build executables with SLINK. For example, suppose that you compiled a program contained within one file, say MYPROG. The compiler will produce an object file called MYPROG.OBJ. To produce an executable from this, the following command line will suffice

slink myprog.obj

In response, SLINK will:

  1. Load MYPROG.OBJ.

  2. Set the default entry point for Silverfrost programs.

  3. Scan the Fortran library, FTN77.DLL or FTN95.DLL.

  4. Scan the Silverfrost C library, SALFLIBC.LIB.

  5. Scan the default list of system DLL's.

  6. Set the file name to MYPROG.EXE (derived from the name of the object file).

  7. Create the executable.

This command line illustrates SLINK's command line mode. Alternatively, we could use SLINK's interactive mode in the form:

slink
$ load myprog
$ file

Note that SLINK's command prompt is a $, and that SLINK has provided the .OBJ extension. Interactive mode always terminates with a file command. The file command is used both to terminate the session and to optionally provide the filename that is to be used to store the output. SLINK will know that you are building an executable and automatically supplies the .EXE extension.


Command line mode

This is an example of how to use SLINK in command line mode:

slink myprog.obj –file:test

In command line mode, all of SLINK's commands begin with "–" or "/". Any parameters are separated from the command by a colon ":". Note that there must be no spaces within the command (in this case file:test). Where the command does not take parameters, it should not be terminated with a colon. Where parameters are optional because SLINK will complete the command (for example the file command) then the colon is also optional.


Linking multiple object files

Multiple object files can be linked:

  1. in command line mode by placing more objects on the command line,

  2. in interactive mode by using more load commands, and

  3. in script file mode by modifying the script file in a manner corresponding to 1) for command line mode or 2) for interactive mode.


Abbreviating commands

Many of SLINK's commands have an abbreviation. These are shown in the command reference (see the end of this section). For example, instead of the load command you may use lo. Also, many of SLINK's commands have an alias.


Script or command files

When large numbers of commands are needed or the same command sequence is repeated many times it is helpful to place the commands in a script or command file. Interactive mode script file names are prefixed with a "$" on the SLINK command line, whereas command line mode script files are prefixed with an "@". Commands taken from script files are presented in the same form as that used when entering commands from a command prompt in interactive mode or from the command line. For example,

slink $myprog.inf

will tell SLINK to take its commands from a file called MYPROG.INF and that the command format is interactive mode, whilst

slink @myprog.lnk

will tell SLINK to take its commands from a file called MYPROG.LNK and that the command format is command line mode.

Note that the file suffixes .INF and .LNK are purely conventional and do not affect how the commands will be interpreted - you may use suffixes of your own choosing if you wish.

As a special case, for interactive mode command files, the $ before the file name can be omitted. In this case, if the file is not recognised as a COFF object, it will be opened as a script file. For this reason, COFF objects specified on the command line must have the correct filename extension as SLINK will not complete the filename itself.

More than one script file may be specified on the command line but script files may not themselves contain script files.


Differences between command line mode and interactive mode

The main difference between command line mode and interactive mode is that command line commands (i.e. commands that begin with a "-") are implemented first and objects and libraries are loaded later. Commands have a deferred effect and can appear anywhere in the command line or script file and in any order. For example,

slink myprog.obj -file:test

and

slink -file:test myprog.obj

have exactly the same effect. In the latter case, specifying -file:test first, tells SLINK that the filename will be TEST.EXE but no immediate action is taken on the file command.

Interactive mode commands are implemented immediately, where appropriate. For example, placing the following commands in a script file:

lo myprog
file test

and

file test
lo myprog

will have different effects.

The first script will do as expected, load an object file called MYPROG.OBJ and produce an executable from it called TEST.EXE.

The second script will terminate with an error since the SLINK session is always terminated in interactive mode by file and at that point no object files have been loaded.


Comments

In script files (for both interactive and command line mode) all text following the semicolon character ";" is ignored until a newline character is encountered. This makes it easy to temporarily "comment out" commands. For example in

slink file1.obj file2.obj ;file3.obj tpgraph.lib

the objects FILE3.OBJ and TPGRAPH.LIB will not be loaded.


Mixing command line script files and interactive mode script files

It is not advisable to mix interactive mode and command line mode script files due to the differences in the way that they are interpreted.


Executables

The previous section described briefly how to generate executables. This section looks at additional commands that are either useful during the production of the executable or affect the way the executable is produced.


Link map

The link map is used to examine the structure of the executable or DLL in detail. The map will show:

  1. The entry point (see below) and its address.

  2. All of the routines that SLINK could not find a definition for. These are called unresolved externals (see below). The SLINK map will also show the path name of the file that contained the initial reference to the symbol.

  3. The map then lists all of the defined symbol names and their addresses together with the path name of the file that contained the definition of the symbol. These addresses show the "preferred address". The actual run time address may be different.

  4. The link map finally contains a brief outline of the executable by showing the addresses where the executable's sections have been loaded.

For example, the following SLINK session will produce a link map named FILE1.MAP and an executable FILE1.EXE. These names are derived from the first loaded object file name.

slink
$ lo file1
$ lo file2
$ map
$ file


Unresolved externals

Unresolved externals are those symbols for which SLINK was unable to find a definition when searching the specified library and object files. Some omissions may be intentional and may simply be routines that will not be called. Others may be unintentional omissions. SLINK will successfully complete a link session even when there are unresolved externals. It will provide a temporary definition of these symbols so that, when the function is called, an error message will be printed out stating the name of the function and the address from which it has been called.

In interactive mode, the command lure (List UnResolved Externals) may be used at any time to check the progress of the linker session. This command will list all of the functions for which it currently has no definition together with the path name of the file that contained the reference.

Do not be alarmed if a large number of functions are listed as unresolved when the command is used immediately before the file command is issued. This is quite normal because there will be functions in FTN77.DLL, FTN95.DLL, SALFLIBC.LIB (or SALFLIBC.DLL) and in the system DLLs that need to be linked. SLINK will automatically link them after the file command has been issued.


Direct linking with DLLs

SLINK allows direct linking with one or more DLLs without the need to use import libraries (see section 5). It will generate its own import library for a DLL based upon the information contained in the DLL's export table. If you produce a DLL, you have the choice whether or not to produce an import library.

Sometimes, as is the case with SALFLIBC.LIB (or SALFLIBC.DLL), the library is a combined import and standard library. In this case, the functions in the standard library part are not contained within the DLL, so directly linking with the DLL will not achieve the same result as linking with the .LIB file. This means that you should not link directly with SALFLIBC.DLL – always use the .LIB file i.e. SALFLIBC.LIB.

For example, suppose that some of the functions you need are provided inside a DLL called TPGRAPH.DLL. In this case the linker would not import the runtime code for the functions from the DLL even though the DLL must be loaded as illustrated here:

slink
$ lo file1
$ lo file2
$ lo tpgraph.dll
$ file

TPGRAPH.DLL is merely used to acquire the information that is necessary for the executable to import functions from TPGRAPH.DLL at run time.

rlo can be used instead of lo with the result that, when the resulting application is executed, the DLL is not required to be accessible when the application is loaded. The binding is delayed until the first call to a routine in the DLL. In other words, the executable can be run without the DLL being present and a runtime failure will not occur unless and until a call is made to a routine in the DLL.

SLINK will not search the system path for the DLL. You should specify the full path name on the load command.


Additional Commands

Various commands are used to provide information that is required to generate an executable. SLINK will take a sensible default for all of these commands and it is unlikely that you will need to use them.


Runtime tracebacks

SLINK builds an internal map into each executable. The location of this map is registered with SALFLIBC at runtime. It contains the true fixed-up runtime addresses. In the event of a fault during program execution that causes the program to abort, SALFLIBC will print out a traceback of the various routines called, tracing back to the user's main program.

The internal map contains the name and address of all the static and external functions in your code. You may wish (e.g. for code security reasons) to remove this map and forego the run time traceback facility. This may be achieved by using the notrace command.


Linking for Debug

When source files are compiled using checking or debugging options, the compiler inserts additional information into the object files produced. This information has to be organised and placed into the executable so that the Silverfrost debugger can be used to examine source files, set break points, examine variables etc. SLINK will automatically insert the debugging information into the executable. However, since this increases the size of the executable by a considerable amount, you are advised to switch off the checking and debugging options before preparing production versions of your executable.

The syntax of the command is:

debug [full | partial | none]

This means that the word debug can be followed by one of the options full, partial and none. The debug command with no parameters or with the keywords partial or full will insert debug information into the executable. partial and full have the same meaning. The keyword none will remove the debug information. The default is full.

If debug information is not found in the object files, then SLINK will not insert any debug information into the executable. In this case, if you are using the debug command with partial or full, then SLINK will produce a warning.


Comment text

The syntax for the command is:

comment [on | off | "text"]

This means that the word comment can be followed by one of the options on, off and some user-supplied text in quotation marks (in this section, user-supplied values are shown in bold italics). It is possible to embed comment text into an executable using the comment command. Comments are included into the .comment section in the executable (here the word comment is preceded by a period/full stop). Typically copyright information and version information is included in comment text. Even if the file name is changed, text within the comment section will still identify the executable as your product.

SLINK will prepend the text with the characters "@(#)", and will also add newline characters at both ends of the text. This makes the text easy to search for with a grep type utility. Comment text is also added by the compiler used and by SLINK in order to identify version numbers used for the build. SLINK will always add its own comment to the executable.

Any number of comment commands may be issued. Text following the comment command should be delimited with double quotation marks ("). The comment command is only available in interactive mode.

It is also possible exclude the .comment sections of COFF objects from the executable. This is useful where, for example, your application has been linked from a large number of COFF objects. The .comment section in the executable would then normally be very large. The comment off command will prevent the inclusion of these comments from the point at which the command was issued until a comment on command is issued. User comments will still be included.

Here is an example of the use of comments.

comment "Mars Attack v2.03,InterGalactic Software Inc."
comment off
.....
comment on


Virtual Common

It is possible in most languages (and in particular in Fortran and C/C++) to have uninitialised global data, for example, a common block in Fortran not initialised with a BLOCK DATA subprogram. Under normal linking, these are accumulated into the .bss section in the executable (BSS is an old IBM term meaning Block Started by Symbol). Although this section does not contribute to the size of the executable it does contribute to the size of the loaded image. The consequence of this is that the system must have the resources available to meet the size of the .bss section. This is unfortunate, since many applications use very large global arrays, only some of which is ever used.

If the SLINK command vc or virtualcommon is used at some stage during the link process, the ".bss" section is removed from the executable and the global data is allocated to virtual memory at runtime. The result is that pages of memory (4KB each) are allocated from the system on demand.


Libraries

Win32 acknowledges three types of library: Standard Libraries, Import Libraries and Dynamic Link Libraries (DLLs).


Standard libraries and import libraries

These libraries contain code that is linked into the user's program by SLINK as part of the program's executable image. They are easy to build and need no special initialisation. Win32 standard and import libraries are very similar to UNIX COFF archives and for that reason are referred to as archives. Archives consist of complete object files loaded in together with various headers. These object files are referred to as members. Win32 archives usually have the filename extension .LIB.


Import Libraries

Import libraries are used by programs that wish to link with DLLs. Import libraries are not usually needed when SLINK is used because SLINK can extract the information directly from the DLL itself. However, SLINK will generate import libraries for the DLLs it creates if requested and will also accept them as input for the load command. Import libraries have to be generated for other linkers that cannot extract information directly from the DLL.


Silverfrost run time library

All programs that are compiled using a Silverfrost compiler must be linked with SALFLIBC.LIB. SALFLIBC.LIB is a special kind of library and is a combined standard and import library. SLINK will automatically link with SALFLIBC.LIB for you. Although SALFLIBC.DLL exists, it should not be scanned directly since SALFLIBC.LIB is more than just an import library. Not all references that are satisfied by scanning SALFLIBC.LIB can be satisfied by scanning SALFLIBC.DLL.

Any import library or DLL may only be scanned once. A situation like the following is to be avoided:

lo object1.obj | creates references to KERNEL32.DLL
lo kernel32.dll | satisfies current references to KERNEL32.DLL
lo object2.obj | creates more references to KERNEL32.DLL

SLINK will automatically scan the system DLLs, in order to satisfy references in the user program, if any unresolved references exist at the end of the link process.

The following order of linking should be observed:

  1. Object files

  2. Non system DLLs, non system import libraries and other standard libraries

  3. SALFLIBC.LIB

  4. System DLLs

The list of DLLs included in "system DLLs" is given in the reference section.

Note that the last three stages are automatic but should none the less be regarded as having taken place.


Dynamic Link Libraries

Dynamic Link Libraries are special kinds of libraries used by modern operating systems. They do not contain code that is directly linkable with the user's program. They are pre-linked bodies of code that are called at run time and are a kind of executable, rather than a kind of archive. The advantage is that, when the DLL is updated, the user's program does not have to be relinked unless the order of the routines contained within the DLL has changed. Also, by using a DLL, very little code is added to the user program.

Win32 DLLs require that programs wishing to use a DLL must link with an import library (see above). This is so that the system loader can make the link between the user program and the DLL when the user's program is loaded at run time. The Silverfrost Fortran and C/C++ runtime libraries are contained in one or more DLLs. Usually, runtime library routines are not linked into the user program. The exception is the case where the compiler has inserted the code inline. Thus executables that use DLLs are much smaller than would otherwise be the case.


Static libraries

The linker command archive will specify that an archive (i.e. a static library) is to be generated. The archive command is available in both command line and interactive mode.

Object files to be placed into the archive are specified using the addobj command. This informs the linker that the object specified is not to be included in the normal link process but is to be placed in the archive. Archives themselves may be added to the archive. In this way, objects may be added to already existing archives. You can also give the addobj command a listfile name preceded by @ that contains a list of files that you wish to be included.

The following example constructs an archive named NEWLIB.LIB which contains the object files FILE1.OBJ, FILE2.OBJ together with all the object files contained within LIBFILE.LIB. This results in two more object files being added to LIBFILE.LIB. Note how the file command is used to terminate the linker session and initiate building the archive.

slink
$ archive newlib.lib
$ addobj file1.obj
$ addobj file2.obj
$ addobj libfile.lib
$ file

or

slink
$ archive newlib.lib
$ addobj @listfile
$ file

where listfile contains the following text lines

file1.obj
file2.obj
libfile.lib

the command line form of this command would be:

slink -archive:newlib.lib -addobj:file1.obj
  -addobj:file2.obj -addobj:libfile.lib

or

slink -archive:newlib.lib -addobj:@listfile

Note that the load and addobj commands may be used with wildcards. For example,

addobj *.obj

A static library can then be used when creating executables and/or DLLs. For example, if a main program in main.obj calls a routine in the above file1.obj we could use

slink
$ lo main.obj
$ lo newlib.lib
$ file

and only the relevant objects will be loaded into the executable called main.exe.


Generation of DLLs and exporting of functions

Since DLLs are run time libraries, it follows that they can also provide routines for other applications that are running. These routines have to be exported in order to make them available to other applications. A DLL must have some exports.

The export command will make a function (or a variable) available to other applications by inserting it into the export table in the DLL.

If you wish all of your functions to be exported, unless otherwise specified by the exportx command, then the exportall command will insert them all into the export table.

The exportx command will prevent functions from being inserted into the export table. The export command overrides the exportx command.

The dll command is used to specify that a DLL is to be built.

If your DLL contains a large number of routines (some internal and some for export) then you can use exportall as a simple expedient. If subsequently, an executable duplicates the name of a routine that was designed to be internal to the DLL, then use the SLINK command permit_duplicates, otherwise SLINK will fail to carry out the linking. You should also ensure that the executable objects are loaded (into SLINK) before the DLL.

The following example will generate a DLL named MYDLL.DLL. All of the functions within MYDLL.OBJ are exported.

slink
$ dll
$ lo mydll.obj
$ exportall
$ file

Note that the filename extension .DLL is appended by SLINK.

Import libraries can be generated by using the archive command. In which case, all of the exported functions will have the necessary members added to the import library to enable them to be linked with the DLL at runtime.


The export command

The export command has the form:

export entryname [=internalname] [@ordinal [noname]] [data]

Only a shortened version of the command is available in command line mode, namely:

-export:entryname [=internalname]

internalname is the name of the symbol as it appears in your program or object files. Note that, in the case of _ _stdcall functions, there is an additional "decoration" added to the end of the symbol. In general, you should not use this decoration nor the leading underscore added to the symbol name. SLINK will match the undecorated name specified with the decorated name in the loaded object files. In the case of Silverfrost C++ decorations, the full decorated name should be specified but without the leading underscore.

entryname is the name of the symbol by which the user would call your function. SLINK will append a leading underscore and transfer any _ _stdcall decoration found for the internalname to the entryname. The name of the function will appear in the DLL export table exactly specified with this command.

In the following example, suppose your _ _stdcall function func exists with the full decorated name _func@12

export gloop=func

SLINK will match func with _func@12 and also export _func@12. The name appearing in the export list will be gloop and the symbol appearing in the import library (if any) will be _gloop@12.

The name in the export table and the name in the calling program's import table are identical. This is so that the system loader is able to find the function in the DLL.

data is used to export a data item. You must use a pointer to the data item in your program. See the command reference for descriptions of ordinals and the noname keyword.


Using SLIM

Introduction

SLIM, the Silverfrost Library Manager is used to create or perform maintenance tasks on static Win32 libraries. Note: Use of the word library throughout this topic specifically excludes dynamic link library (.dll) files.

SLIM will accept the following as input:

  • Object files (.obj). FTN95 and SCC produce object files after successful compilation of a source file which contain subroutine and function definitions that are used when building executable programs (.exe) or dynamic link libraries (.dll).
  • Concatenated object files (.cat). Concatenated object files are normally produced by the user appending object files end to end. For example, suppose that the object files subs1.obj, subs2.obj and subs3.obj were combined as follows using the copy command:

Copy subs.cat subs1.obj+subs2.obj+subs3.obj

The result would be the concatenated object file subs.cat containing the three objects subs1.obj, subs2.obj and subs3.obj. This file could be used as input to the linker, SLINK - where all three could either be loaded, or combined into a library.

If a concatenated object file is added into a library, it is as if each component object file in that concatenated object was added individually. Each component object file is then available for selection by SLINK independently of the others.

  • Library files (.lib). Library files could be produced both by the linker, SLINK, and by SLIM. Library files might also be output from FTN95 if the /MKLIB option is used. Library files contain object files organised in such a way that the linker can load them selectively. Each object file within a library is termed a member.

As an example of selective loading, suppose that your program used a subroutine SUB1 defined in a library. Scanning the library with the linker would link only that member of the library, which contains the definition of SUB1. Of course, that member may contain a reference to another function (say SUB2) defined in another member of the library, in which case SUB2 would also be linked.

What SLIM will do

  • Create library files from: object files, concatenated object files and other libraries Replace any member of a library with a different version of that member.
  • Extract member(s) of a library to one or more files.
  • Remove (delete) any member of a library.
  • List the members of a library.

What SLIM will not do

  • Process definition (.def) files Produce import libraries. Import libraries are produced by SLINK at the user's option when a dynamic link library is built.

Listing a library

To list the members of a library, use the /list option as in the following example:

SLIM mylib.lib old.lib /list:listfile

This option would list all of the members of mylib.lib and old.lib to a text output file named listfile. If no output filename for the listing were specified, the listing would be directed to the console (i.e. your "DOS box"). Use of the /list option inhibits production of an output library.

The name of library member is its file name. To refer to that member you must use the member name in full as shown in the output produced by the /list option. For example, "subs.obj" is a different member from "obj\subs.obj". Conversely, all members with the same name are regarded as being components of the same object. All components of a concatenated object have the same name, so that operations on one affect all components. Similarly, import libraries such as kernel32.lib or salflibc.lib have many members with the same name and operations on one affect them all en masse. If the option /SHORTNAMES (see below) is used when creating the library, only the filename portion (rather than the full pathname) will be used for the member name. Filename with different path names will produce multiple members with the same name. Removing or replacing one will remove or replace them all.

Creating a library

Use the SLIM command line to specify each library or object file that you wish to become part of your library and, optionally, supply an output file name.

For example,

SLIM old.lib subs.obj subs.cat /file:subs.lib

will add all the members contained in old.lib, the object file subs.obj and the components of the concatenated object file subs.cat in to a new library called subs.lib. If no output file name is specified then the name of the first object on the command line is taken, a .lib extension added and the resulting name used as the output filename. In the given example, the output filename would be old.lib if the /FILE option was to be omitted.

Replacing a library member

Suppose that old.lib contained subs1.obj, subs2.obj and three members named subs.cat. The SLIM command

SLIM old.lib subs1.obj

will replace the previous version of subs1.obj with the new subs1.obj. The old version is defined as being on the left of the new version on the command line. The output filename will be old.lib since no /FILE option was given.

SLIM old.lib subs.cat

Will delete all members named subs.cat from old.lib and replace them with the component objects of the new subs.cat.

Removing a library member

One or more members of a library may be removed from the library by using the /REMOVE option.

SLIM old.lib /remove:subs.cat

will remove all members named subs.cat from the library

Extracting a library member

One or more members of a library may be extracted from the library to a file by using the /EXTRACT option. The members will be written to a file with the same filename portion of the member name unless an optional /FILE option is used in which case the output will be written to that. Note that, if /FILE is used, only one /EXTRACT option may be used. All members with a specified name will be written to the same output file. For example:

SLIM old.lib /extract:subs.cat

will extract all members named subs.cat to the output file subs.cat and

SLIM kernel32.lib /extract:kernel32.dll

will extract all members named kernel32.dll to kernel32.dll. In cases such as this, you are strongly advised to use a different name for your output file!

SLIM new.lib /extract:obj\subs.obj

Will extract all members named obj\subs.obj to a local file subs.obj.

Creating non-local libraries

If you want to create a library which is not in the local directory, you must either use the /FILE option giving the pathname, or use the /FORCE option. This is to prevent accidental overwriting of libraries found on the LIB environment variable path. For example, suppose that you have a third party library called TPGRAPH.LIB and you did this

SLIM tpgraph.lib /remove:lineto.obj

TPGRAPH.LIB might not be local and was found on the LIB path. If you did not intend to /REMOVE but wanted to /EXTRACT, you will have unintentionally altered TPGRAPH.LIB.

If you really intend to do this then either specify a path name using /FILE or use the /FORCE option.

Using the /SHORTNAMES option

Many libraries have members whose names contain file path information. This can lead to difficulties when extracting, removing or replacing members, since the full member name has to be supplied to SLIM. Use of the /SHORTNAMES option allows the member names to be supplied truncated down to just the filename component of the pathname. If an output library is written, and the /SHORTNAMES option is used, the truncated member name is written into the library, otherwise the full member name is used.

For example:

Suppose that a library named MYLIB.LIB contains a member called "build\obj\newfunct.obj". Replacing this member without using /SHORTNAMES would mean either that you would have to have a file called precisely "build\obj\newfunct.obj" or that you would have to first remove the member and then add the new version of the member (i.e. use SLIM twice). If the /SHORTNAMES option is used then the following would suffice:

SLIM mylib.lib newfunct.obj /SHORTNAMES

Similarly, if /SHORTNAMES is used on the SLIM command line, /EXTRACTing or /REMOVEing an object only requires the filename part of the member name.

Command Reference

/EXTRACT:member

Specifies member(s) to be written to file. To extract more than one member, use multiple /EXTRACT options. All members that match the specified name will be written to the same file, producing a concatenated object file. If /FILE is also used then only one /EXTRACT option may be used and the output will be directed to the file given in the /FILE option. If /FILE is omitted, or if no filename is specified, then the member name truncated to just the filename. Note that if /EXTRACT is used then an output library will not be written.

/FILE[:filename]

Specifies the output filename. When building a library, if /FILE is omitted, or if no filename is specified, then the name of the first object on the option line is taken and a .lib extension added. When extracting a library member, the /FILE option has a special meaning, see /EXTRACT.

/FORCE

Forces the production of an output library, even if the library is non-local and has a name derived from an input library or object.

/LIST[:listfile ]

Lists all the members contained in the objects placed on the command line to listfile. If the filename listfile is not supplied, then output is to the console. /LIST inhibits production of an output library.

/OUT[:outfile]

This option is an alias for /FILE.

/REMOVE:member

Specifies a member to remove from the output library. To remove more than one member, use multiple /REMOVE options. The member name must be specified in full. SLIM combines all the objects specified on the command line and then removes any members specified before creating the output library.

/SHORTNAMES

Truncates member names down to just the filename portion. This is useful when only short names are required for member names.


SLINK command reference

SLINK has two basic modes of operation: interactive and command line.

Generally, where a file name is optional the default file name is generated by taking the file name of first loaded object file and adding the appropriate extension.


Interactive mode

This mode takes commands in a similar form to a command prompt. The commands are order dependent with the exception that the map command may be given at any point.

A list of the interactive mode commands is given below. Note that the alias is given in brackets alongside the command and that all commands are case insensitive.

You can type the commands or, more likely, have them pre-entered in a text file. You simply add the name of the command text file to the main slink command line:

slink your-command-file

addobj [filename | @listfile]
The specified COFF object is to be included in a COFF archive. Only COFF object and COFF archive files may be so loaded. PE executables and dynamic link libraries (DLLs) may not. This allows COFF archives to contain ReLocatable Binary (RLB) code and also be an IMPort LIBrary (IMPLIB) for a DLL. SALFLIBC.LIB is such an example, it is an import library for SALFLIBC.DLL and yet contains RLB for the startup procedure SALFStartup.

Alternatively, a list of COFF objects to be included may be inserted in a listfile the path of which is preceded by an @.

archive (implib) filename
Specifies that an archive is to be generated from objects loaded with the addobj command. It also specifies that an import library is to be generated from the export list, if it is non-empty.

comment [on | off | "text"]
text is inserted into the .comment section in the executable. The text must be delimitted by a quotation mark ("). Alternatively you can use on or off to enable the inclusion of .comment sections from COFF objects from that point onwards in the link process.

decorate
Symbols in the map and in the listing of unresolved externals are normally reported in their undecorated form. This command will force symbols to be reported in their decorated form.

dll (library) modulename
Specifies that a DLL library is to be generated. DLLs have an internal name, distinct from the filename, used by the system loader to recognise the DLL. The DLL command also sets the internal name (i.e. the module name) that the DLL is known as to the system loader to modulename.

If a module name is not specified, then the module name is generated from the file name with a .DLL suffix. Note that this is equivalent to the library keyword in a module definition file (.DEF file). The default suffix for the file command is set to .DLL.

For example, one of the system DLLs, USER.DLL, has a filename USER32.DLL. By default, SLINK will set the internal name of the DLL to be the same as the filename.

entry symbol
Specifies the entry point for the program. For linking Silverfrost compilations, this command is unnecessary as the entry SALFStartup is assumed. If used, this command MUST be the first command in the SLINK session. If this command is not used, then the entry point will be set to SALFStartup after the first object file has been loaded. If an entry point other than SALFStartup has been specified, this will disable the default loading of SALFLIBC.LIB.

export entryname[=internalname] [@ordinal [noname]] [constant]
This has the same syntax as an entry in the exports section in a .DEF file. It adds an entry to the export list. The entryname specified does not have to exist but if it does not it may cause a run time error if the entry point is used. If the DLL command is not used the module name is generated from the file name with a .EXE suffix. Overrides the exportx command.

Note: Only a shortened version of this command is available in command line mode.

ordinals

An exported function's ordinal is a two byte integer. The system loader will ultimately obtain the function's address from the ordinal table and the export address table. It does this by looking up the function's ordinal from its name and then using the ordinal as an index into the export address table. By default SLINK will assign ordinals to the exported functions. However, you may wish to guarantee that the function has the same ordinal in all builds of the DLL. In which case you may specify the ordinal with this command

e.g. the following example will assign ordinal 4 to the function func exported as gloop

export gloop=func @4

noname

This will export the function by ordinal only. This is used to hide a function within a DLL but still make it accessible to those who know its ordinal. You must specify the ordinal if you use the noname keyword.

e.g.

export func @4 NONAME

will export func by ordinal only, with an ordinal value of 4 whilst

export func NONAME

will produce an error.

exportall
Adds all exportable code entries to the export list. These are code symbols with storage class "external" that have been defined in a COFF object file, i.e. not a COFF archive or DLL. This excludes you from re-exporting an entry point in another DLL unless you specifically export it with the EXPORT statement.

exportx
This prevents symbols from being included in the export list generated by the exportall command. The export command will take precedence over this command if a symbol appears in both.

file (fi) filename
Performs the following actions in order.

  1. Symbols specified in the export list are exported and the export (.edata) section generated. The archive, if required is also generated.

  2. Scans the default libraries

  1. FTN77.DLL or FTN95.DLL

  2. SALFLIBC.LIB (unless an entry command has been used specifying other than _SALFStartup see above). SALFLIBC.LIB will be searched for in the following places:

  1. Locally

  2. The directory specified in the environment variable SCCLIB.

  3. The directory above that specified in the environment variable SCCINCLUDE.

  4. The directory where the invoked copy of SLINK resides.

The scanning of each of the following DLLs is dependent upon there being unresolved references and upon the DLL in question being present. These are searched for in the following places:

  1. Locally

  2. The "system directory", i.e. the directory returned by the function GetSystemDirectory e.g. C:\WINNT\SYSTEM32.

  3. The directories specified on the system path

  4. The directory where the invoked copy of SLINK resides.

  3. KERNEL32.DLL

  4. USER32.DLL

  5. GDI32.DLL

  6. COMDLG.DLL

  3. Generates the internal traceback map

  4. Generates the map listing file if one has been requested.

  5. Displays a list of unresolved external references.

  6. Writes the executable. If an executable is to be written, a suffix of .EXE is appended to filename as a default if one has not been supplied. If a DLL is to be written, a suffix of .DLL is appended to filename as a default if one has not been supplied.

  7. Exits SLINK.

Note: Missing externals will not cause a failure but will generate warnings. However, if an attempt is made to call one of the missing routines at run time a message will be printed out giving the name and the return address of the routine. The user's program is then aborted.

filealign value
Specifies the physical alignment of the sections within the file. value should be an integral power of 2.

default value = 0x200

heap reserve[,commit]
Specifies the program heap size in bytes. An initial heap of commit bytes will be allocated. If this is used up then a further commit bytes will be allocated up to the maximum size of reserve. The reserve and commit values are rounded to 4 byte boundaries.

Silverfrost libraries provide their own heap and so a minimal heap need only be specified.

defaults:

for Silverfrost programs:

reserve = 0x0

commit = 0x0

for other programs:

reserve = 0x100000 (1Mb)

commit = 0x1000 (4Kb)

imagealign (align) value
Specifies the virtual address alignment in bytes of sections within the executable. value should be an integral power of 2.

default value = 0x1000

imagebase (base) address
Specifies the preferred base address for the loaded image. This may be relocated by the loader.

The virtual address space begins at 0x00000000 but the user program starts much higher in memory. The base command specifies the virtual address at which the program is to start. This is called the preferred load address. If the system loader cannot load the program at that address it calculates what is called a DELTA which is the difference between the preferred load address and the actual load address. This DELTA is then applied to all the virtual addresses in the program, actually those specified in the program's fix up table. SLINK will set the base address to be 0x00400000 for executables and 0x01000000 for DLLs. You may wish to change the base address if there is already something else loaded at that address. The fix up process is much more likely to affect DLLs than executables. However, the fix up process is so fast that it is tiny in comparison with the load process overall and can safely be ignored. The base address is specified in decimal, but can also be specified in hex or octal using the 0x or 0 prefixes respectively.

The value set by the base command will be rounded down to be a multiple of 64K. The resulting value must be non zero.

defaults:

executables

address = 0x00400000

DLLs

address = 0x01000000

The following example sets the base address to be 0x00700000

BASE 0x700000

insert filename
Executes the linker commands contained in the text file filename.

listunresolved (lure)
Prints a list of external references which are missing. This command may be used to check the progress of a SLINK session and may be used at any time. This command has no other effect.

load (lo) filename
Loads object file filename. filename may be either a COFF object file, a COFF archive library (i.e. .LIB) or a directly imported dynamic link library (.DLL). A .OBJ suffix will be appended to filename if one isn't already supplied.

SALFLIBC.LIB will automatically be loaded if has not already been loaded and if the entry point name has not been changed from SALFStartup.

map filename
Specifies that a symbol map file should be produced and written to filename. The action of this command will be deferred until all object files have been loaded. A suffix of .MAP is appended as a default if one has not been supplied.

notrace
Suppresses the generation of the internal map within the executable. Without this map a runtime traceback is impossible.

rlo dllname
Loads the DLL dllname. rlo has the same effect as lo (load) but when the resulting application is executed, the DLL is not required to be accessible when the application is loaded. The binding is delayed until the first call to a routine in the DLL. In other words, the executable can be run without the DLL being present and a runtime failure will not occur unless and until a call is made to a routine in the DLL.

stack reserve [,commit]
Specifies the program stack size in bytes. An initial stack of commit bytes will be allocated. If this is used up then a further commit bytes will be allocated up to the maximum size of reserve. The reserve and commit values are rounded to 4 byte boundaries.

defaults,

for Silverfrost programs:

reserve = 0x3200000 (50MBytes)

commit = 0x4000 (16KBytes)

for other programs:

reserve = 0x100000 (1MByte)

commit = 0x1000 (4KBytes)

virtualcommon (vc) [base, [commit]]
Specifies that the uninitialised data section, i.e. the .bss section is removed entirely from the executable and placed into virtual paged memory. The base address of this virtual memory may be specified but should be done with care. Similarly, a commitvalue can be specified to indicate how much memory should be committed from the system at each acquisition. Small values of commit mean that there is less memory wastage whilst larger values will improve (slightly) run time performance at the expense of memory usage.

base and commit must be aligned on a page boundary, i.e. if specifying the values in hex the least significant 3 digits must be zero.

defaults,

base = 0x20000000

commit = determined at run time initialisation

subsystem subsys
You should specify whether the program will require a Character User Interface (CUI) or a Graphical User Interface (GUI). The subsystem specified should be one of console for a CUI, windows for a GUI or native if no subsystem is required. Win32 will not allow output to stdout unless console has been selected as the subsystem.

By default, SLINK will set the subsystem to be console.

subsys should be one of the following:

native no subsystem required

windows a graphical user interface subsystem is required.

console application requires only a character mode subsytem (but
using a GUI is not precluded).

default: subsys = console

The following example sets a CUI subsystem requirement.

SUBSYSTEM CONSOLE

quit (q)
Immediately exits SLINK. No output files are produced.


Command line mode

In this mode all of the object files and SLINK commands are placed on the command line.

SLINK [files] [options] [commandfile]

Object files, script files and options may be freely intermixed. There may be more than one command file.

1. Script files

Script files contain commands and/or object files.

Interactive style script files are prefixed by a "$" or have no prefix. Command line script files are prefixed by an "@".

2. Interactive style script files

These contain the same commands as may be used in interactive mode and are executed in the order that they appear in the file.

e.g.

SLINK myprog

If myprog (no filename extension) does not exist then myprog will be assumed a interactive style script file.

or

SLINK $myprog

This form is explicitly a interactive style script file.

3. Command line style script files and command line arguments

These may contain the following commands:

-addobj:{@listfile | filename}

-align:#

-archive:[filename] alias for -implib

-base:address

-debug [:full| :partial| :none]

-decorate

-dll [:modulename] alias for -library

-entry:symbol

-export:entryname [=internalname]

-exportall

-exportx:entryname

-file [:filename] alias for -out

-filealign:#

-heap:reserve [,commit]

-help alias for -?

-imagealign:# alias for -align

-imagebase:address alias for -base

-implib [:filename]

-library [:filename]

-map [:filename]

-notrace

-out [:filename]

-rlo :dllname

-stack:reserve[,commit]

-subsystem:{native | windows | console}

-vc[:baseaddress[,commit]] alias for -virtualcommon

-virtualcommon[:baseaddress[,commit]] alias for -vc

Commands have the same requirements and meaning as the corresponding interactive command, may be in upper or lower case and may have either a "/" or a "-" prefix.

Commands are executed first and so may appear anywhere and in any order. Object files are scanned after all of the commands have been scanned.

Object file names are specified with the .OBJ extension and, unlike interactive mode no extension is automatically appended. However, object files are loaded in the order in which they appear.

The -out: (-file:) command is unnecessary since an executable will be automatically written after all commands have been processed and all object files have been scanned. For example:

SLINK myprog.obj -map: @others.inf -file:test @defltlib.inf

This will link the object file myprog.obj with any object files, libraries, or DLLs listed in others.inf or defltlib.inf. A map file myprog.MAP will be produced (name taken from the first loaded object) and executable test.EXE (automatic file name extension) written. For example:

SLINK tester.obj mylib.obj

tester.obj is scanned and then mylib.obj is scanned. An executable named tester.EXE will be written.

It is generally not advisable to mix interactive and command line style script files due to their different behaviour. If more than one interactive style script file is used remember that commands are executed in the order in which they appear.


Direct import of Dynamic Link Libraries

Care should be taken on importing DLLs. The mechanism is designed to replace the importation of "pure" import libraries. It is possible that the .LIB file contains loadable library code in addition to the imported symbol. In such cases, the loadable library code is missing from the DLL and so cannot be loaded. SALFLIBC.LIB is such a library, the DLL SALFLIBC.DLL cannot be loaded directly since it does not contain, for example, the symbol _SALFStartup which is necessary for initialisation and to provide the application's entry point.

Direct import of dynamic link libraries require that the exported names in the DLL follow the following rules

  1. _ _stdcall symbols

The exported name is created by removing the leading underscore and does not contain the appended @ and subsequent characters

e.g. _MessageBeep@4 will be exported as MessageBeep

  2. Symbols beginning with a leading underscore

The leading underscore is removed.

  3. Other symbols

All other symbols are assumed to be exported unchanged.

Archive and import library generation

Archives and import libraries may be generated without any objects being loaded with the load command.

For example the following SLINK script will generate a combined RLB and import library. Note that the file command is necessary to initiate the build. Ignore the comments in brackets

archive mylib  (archive file to be called mylib.LIB)
dll   (module name set to mylib.DLL)
addobj func1.obj
addobj func2.obj
addobj func3.obj
addobj func4.obj
export functiona
export functionb
export functionc
export functiond
export functione
export functionf
export functiong
file

Entry Points

The executable file needs an entry point that is called by the system loader immediately after the program has been loaded. This entry point is not the main, WinMain or LibMain function as you may think, but library startup code. The Silverfrost entry point for all executables, including DLLs is _SALFStartup. Object files produced by other compilers will have a different entry point which you will have to set explicitly.

The entry point is specified with the entry command, omitting the leading underscore. SLINK will automatically set the entry point to be _SALFStartup unless you use the entry command before any objects files have been loaded. In command line mode the entry command can be placed anywhere in the command line or script file since commands are always processed first.

e.g. The following command will set the entry point to be _SALFStartup. This is redundant since SLINK will do this for you.

ENTRY SALFStartup

You cannot change the entry point after the first object file has been loaded or if an entry command has previously been used.


Overview of the debugger

Frequently Asked Questions

Source Windows

Variables Window

Call Stack and Status Window

Simple Expression Windows

Array View Windows

Structure/TYPE Windows

Memory Dump Windows

Assembler Windows

Find Window

Scripting


SDBG_Introduction

Using the debugger

The Silverfrost Win32 debugger SDBG can be invoked from Visual Studio if the project is set in "Debug Win32" or "CheckMate Win32" mode. SDBG is launched externally when a "Run to Cursor" or "Run to breakpoint" command is executed (see Getting started with FTN95). If possible you should use the debugger that is integrated into Visual Studio instead. To do this select "CheckMate .NET" or "Debug .NET" for development and change to the Win32 platform for release.

SDBG may be used either:

  • in conjunction with the Silverfrost CHECKMATE facilities, by compiling (for example) with /CHECKMATE, or

  • without CHECKMATE by compiling with /DEBUG.

SDBG allows you to view your source file(s) whilst controlling the execution of your program using function keys and debugger commands. These keys and commands control the following facilities:

  • Program breakpoints

  • Single stepping

  • Display of variables

  • Source and data file inspection

  • Evaluation of expression values

  • Program status display

  • Write/use data breakpoints (using hardware)

  • Machine code debugging

  • Profiling (statement execution count)

  • Input/output stream information

  • Display of the contents of virtual memory

  • Control of screen size


Invoking_SDBG

SDBG can be invoked from Visual Studio if the project is set in "Debug Win32" or "CheckMate Win32" mode. SDBG is launched externally when a "Run to Cursor" or "Run to breakpoint" command is executed (see Getting started with FTN95). If possible you should use the integrated debugger instead. To do this select "CheckMate .NET" or "Debug .NET" for development and change to the Win32 platform for release.

SDBG can be invoked from the command line in Command Prompt bix in one of several ways.

  • By compiling a program for immediate execution with the /BREAK option, for example:

FTN95 MYPROG /BREAK

Used in this way /BREAK implies the /CHECK and /LGO options.

  • By compiling the program with the /DBREAK option. This option is similar to the /BREAK option except that it does not imply the /CHECK option which causes the compiler to plant checking code.

  • By linking together one or more .OBJ files produced with /CHECK or /DEBUG options and executing the resultant .EXE file as follows.

You can also use /PROFILE on the FTN95 command line (see Profiling ).

For Win32 executables use SLINK and then type,

SDBG MYPROG

The source file for each section of the code to be debugged should be available exactly as it was compiled (i.e. you must not edit these source files prior to using the debugger).

Assuming that no compile-time error is encountered, each of these commands will cause your program to be suspended at the first executable statement in a module compiled with /DEBUG.

The /DEBUG and /DBREAK options cause the compiler to plant sufficient information to enable SDBG to operate, but specify that no checking code is to be planted.

In general, it is better to debug a program compiled with checks, but /DBREAK and /DEBUG are very useful in the following cases:

  • When a problem does not manifest itself when the checks are enabled. Often this is a consequence of a calculation being performed with undefined variables or array elements and you are advised to compile the program using the /UNDEF option before using SDBG.

  • When the program is just too large to fit in memory when compiled with checks.

  • When the program runs too slowly when compiled with checks.

Programs which are not checked may well overwrite themselves and/or the tables which SDBG uses to interpret their behaviour. This can produce unpredictable results.


Command line switches for SDBG

Location of source files
By default the debugger will look for the source files in the directories they occupied at compile time. If the source files have been moved, there are two methods for specifying alternative directories to for the debugger to search.

Firstly you can specify the environment variable SOURCEPATH in your AUTOEXEC.BAT or its equivalent. This can contain a list of paths. Semicolons are used to separate the paths in the same way as the standard PATH variable. For example:

SET SOURCEPATH=C:\COMMON\SOURCE;C:\USERS\PROJ;W:\SRC

Secondly, the Windows debuggers can take an optional command line parameter that specifies a source path. This path will replace any path brought in by the SOURCEPATH environment variable. For example

SDBG SIMUL /SOURCEPATH C:\COMMON\SOURCE;C:\USERS\PROJ;W:\SRC

/SOURCEPATH can be abbreviated to /SP.

Passing run-time command line parameters
If the executable that you are debugging uses command line parameters, then you will need to pass these to SDBG. To do this use /PARAMS (or /P) followed by a space and then the list of parameters to pass. Everything to the right of this option is passed on the command line to the program being debugged.

Enabling Run-to-line from the command line
To start SDBG, set a breakpoint and run to that line, the switch /RUNTO can be used. The format for this is:

/RUNTO filename line_number

Hiding routines on the call stack
By default, Silverfrost library routines (defined in salflibc.dll) are not shown in the SDBG call stack. The SDBG command line option /NO_HIDE_SALFLIBC (or /NHS) forces all Silverfrost library routines to be shown.

Hiding the debugger
The SDBG option /SILENT causes the debugger to be hidden unless there is a run-time error.

SDBG version number
The SDBG option /VERSION (or /V), causes SDBG to output the version number of the debugger and then exit.


Using_SDBG

The first task SDBG will carry out is to save the running program's screen display and replace it with the debugger screen, switching to text mode if required. SDBG only displays information in text mode although you can debug programs that use graphics modes supported by the Silverfrost graphics library.

SDBG makes use of a windowed interface. In common with other user interfaces a mouse is not absolutely necessary but is extremely useful. The mouse cursor will appear as a one character block in the middle of the screen.

The window that appears on top of all the others is called the current window. The current window will respond to any key-presses or mouse actions. It can be distinguished by the double line border surrounding the window. All other windows have a single line border. You can change the current window by pointing at another window and pressing and then releasing the left mouse button. In this case the window you pointed to will be brought to the front and you will see the border change.

You can cycle through the currently open windows by pressing Alt+N. The current window can be moved by pointing to its title bar and pressing the left mouse button. While the button is depressed you can 'drag' the window to its new location.

At the bottom right hand corner of a window you will see that the border thins from a double line to a single line. The single line denotes the fact that you can resize the window. This is achieved by moving the mouse to this area and pressing and holding the left mouse button. You can then drag the window corner to its new size.

At the top left corner of most windows you will see a box character (shown as []). By moving the mouse over this area and pressing the left mouse button the window will close. You can also close a window by pressing Alt+F4. Some windows will close when the Esc key is pressed.

When the SDBG screen initially appears it will contain three windows that sit on top of the so called desktop window. Namely

  • a stack/status window,

  • a source code window,

  • a variables window.

If SDBG was invoked because of a run-time error, a description of the problem is displayed in the stack/status window. Otherwise the stack/status window will initially be hidden behind the source window which will show the current execution point. Other windows called data view windows can be opened by the user when required. These five differing types of window are described in the following sections.


Desktop_window

All visible windows sit on top of the desktop. This is a blue and white hatch with the bottom line displaying help and status information. The status line is mostly made up of a line of white text on a blue background. This gives a list of the most common key presses for the current window. This status line is sensitive to the Alt and Ctrl keys being depressed. You can also click the left mouse button over a key description and the key press will be simulated. The rightmost six characters show the current debugger mode. The alternatives are:

Status | Meaning
PAUSE | The program has stopped because of a breakpoint and is awaiting commands.
STOP | The program has stopped because of a runtime error (which will be displayed in the stack/status window). You will not be able to continue, step or run the program from this point.
END | The program has terminated.
RUN | The program is running and can be paused by pressing Ctrl+Break. SDBG does not automatically switch to the program screen because most switches would be unnecessary and waste time. The screen is switched as required.


The_stack_status_window

The stack/status window

This window can be brought to the top by pressing Alt+C in any other window. The stack/status window provides two uses:

  • to display the reason why SDBG has been entered.

  • to display the current call stack,

The status part of this window gives the reason that SDBG has been entered.

The stack part gives a trace back through the active call stack. This is a list of the active subroutines and functions. Routines that have debugging information, and therefore can be debugged at the source code level, are displayed in black text. Routines having no debugging information are shown in grey text. You can view the source code and variables for any routine in the call stack with debugging information by either:

  • moving the bar in the status window to the line containing the routine name and pressing Enter,

  • or by double-clicking the left mouse button over the routine name.

If you try to open a routine with no debugging information a machine code window will appear. This may appear confusing if you are not familiar with programming at this low level. If one appears, simply click the close button or press Escape and it will disappear.

The stack/status window does not have a close button and cannot be closed. This is because the current call stack and status are always relevant.

There are some key presses that apply to every window.

They are as follows:

Key | Action
F1 | Help
Alt+F4 | Close window
F5 | Display user screen
F6 | Run or continue the program
F7 | Single step the program
F8 | Single step over
Alt+C | Display call stack window
Alt+N | Next window
Alt+X | Exit SDBG


Frequently asked questions

How do I find the routine I want to debug?

How do I quickly find the value of a variable?

How do I debug programs if the source files have moved?


Source_code_window

Introduction

Setting breakpoints

Setting conditional breakpoints

Run to line

Single stepping

Examining variables

Profiling information

Miscellaneous information


Source_code_wind_Intro

Source code window

When SDBG is first entered the source window will display the source code for the current execution point. A red bar denotes the first line that caused SDBG to be entered. You can display the source code for any routine in the call stack (assuming the routine was compiled with debugging information) by selecting the routine from the call stack window as described above. Each routine is displayed in a separate window. The routines that are not at the top of the call stack will have their execution point marked with a brown bar.

You can move around in a source window in a manner that is very similar to a text editor or word processor. However, the text cannot be changed. The current position is marked by a cursor, which will initially be on the same line as the execution bar. You can move the cursor around the source window with the mouse or using the keyboard.

The right most edge of the source code window contains a scroll bar. You can move this either by clicking the left mouse button whilst the mouse cursor is in the scroll bar or by dragging the scroll bar (you drag the scroll bar by pressing the left mouse button and moving the mouse whilst keeping the left mouse button pressed). To move the source code up or down one line at a time, click on the arrows at the top and bottom of the scroll bar. The source window now also contains a horizontal scroll bar.

You can also use the following key presses to navigate the window:

Key | Meaning
Left arrow | Left one character
Right arrow | Right one character
Up arrow | Up one line
Down arrow | Down one Line
Page Up | Up one page
Page Down | Down one page
Ctrl+Home | Start of file
Ctrl+End | End of file
Ctrl+Page Up | Move up the call stack
Ctrl+Page Down | Move down the call stack
Home | Start of current line
End | End of current line
Ctrl+O | Go to instruction point (Origin)
Ctrl+G | Go to line number
Ctrl+S | Search for text (case insensitive)
Ctrl+A | Search for text specified by the last Ctrl+S command

The Win32 debugger has buttons on the toolbar to move up and down the call stack. They also have a bookmark facility. This is accessed by selecting Bookmarks from the Window menu. Bookmarks can be set, used or deleted.

The most common actions performed on source code in a debugger are usually 1) setting breakpoints, 2) single stepping and 3) running the program. Several key strokes are available to help you do this.

These are summarised in the table below:

Key | Meaning
F2 | Set or reset breakpoint
Shift+F2 | Set or reset a conditional breakpoint
F3 | Get to current line
F6 | Run program
F7 | Step to next source line
F8 | Step to next source line and step over any routine calls


Setting_breakpoints

The F2 key acts as a toggle. It will set a breakpoint on a line that has no existing break point. Alternatively, it will remove a breakpoint if one already exists on the highlighted line. This only works if the line is an executable statement. So pressing F2 when the cursor is over a comment line will have no effect. It will also have no effect when the cursor is over a declaration. Breakpoints are marked by a white bar. Once you have set the breakpoints required you can continue the program by pressing F6. A message box appears if the line is can not be used as a breakpoint.

You should take care when using breakpoints. If the line of code is never executed, due to an IF condition, the program will not stop.


Setting_conditional_breakpoints

In most circumstances programs can be successfully debugged by setting breakpoints, running the program and examining data. There are some problems which are difficult to debug using simple breakpoints. For example an iterative loop which goes wrong on the 1563th iteration would be very time consuming to debug. You could add extra code to the program to allow SDBG to activate a breakpoint on the 1562nd loop. However, a quicker method is to use a conditional breakpoint. A conditional breakpoint is one which only activates when a given condition is satisfied.

A conditional breakpoint is formed in three parts. Firstly there is an initial delay. This is the number of times the breakpoint has to be executed before it will activate. Secondly there is a repeated delay. This allows you to activate a breakpoint at predetermined intervals. Thirdly, there is an optional expression. When a breakpoint is about to activate, the expression will be evaluated. The breakpoint will only activate if the result of the expression is non-zero.

When you press Shift+F2 an input box will be displayed. You should type into this box the number of times the breakpoint can be executed before it is activated. Entering '5' will cause the breakpoint to activated the 5th time this line is executed. You will then be asked for the number of executions between subsequent breakpoints. You will finally be given an input box into which you can type an expression that will control whether a breakpoint activates or not. You can leave this expression blank if it is not required.

The following table gives examples for the three settings:

Requirement | Initial number | Repeat number | Expression
Stop after the 198th iteration | 198 | 1 |
Stop after the 7th iteration and every subsequent 11th | 7 | 11 |
Stop when eps is greater than 1 | 1 | 1 | eps >1
Stop when eps is greater than 1 and I know this is after the 654th iteration | 654 | 1 | eps >1

You should note that there is a speed penalty if SDBG has to calculate the result of an expression. Indeed a small speed penalty will result from setting any breakpoint. This is in direct proportion to the number of breakpoints encountered.

You can set the initial delay to zero. This implies that the breakpoint will never activate which can be useful when trying to establish how many times a certain point is reached. You can cancel a conditional breakpoint by moving the cursor to the line and pressing either F2 or Shift+F2. In fact the standard breakpoint is a conditional breakpoint with the delays set to one. You can display the status of all system breakpoints with the 'breakpoints' command.


Run_to_line

One important variation on the 'set breakpoints and run' idea is that of 'get to here'. This is achieved by placing the cursor on the line you would like the breakpoint to appear and pressing F3. SDBG will set a temporary breakpoint at that line, run the program and then reset the breakpoint. This works in a similar manner to the key sequence F2, F6, F2. Again you should be aware that your program may not stop if the code is never executed due to say an IF statement.


Single_stepping

Single stepping offers an alternative to setting breakpoints. It allows you to trace the flow of execution a single line at a time. There are two possible methods of single stepping, step into and step over.

The first method (step into) will enter any function or subroutine which contains debugging information. This is useful when you want to follow the logical flow through several routines. You can use the step into method by pressing F7. If you step into a new subroutine or function a new source window will be opened. This will display the code for the new subroutine/function. Alternatively, if you execute a return statement, the current source window will be closed and the window with the calling line will be made the current window.

The second method (step over) will execute the current line but will not enter a subroutine or function even if debugging information is present. This latter case is useful when you are sure that a subroutine or function is working correctly and you do not want to trace the call through the routine. Whilst a new window will never be opened with the step over method, it is possible for the current source window to close due to the execution of a return statement. The step over method is performed by pressing F8.


Examining_variables

The simplest method for examining any of the current active variables is to use the variables window. This window presents a list of all variables that are accessible from the current scope. This list is sorted into scope order and then ascending alphabetical order. The variables window is made the current window by pressing F4.

If you want to examine a particular variable, you can do this by opening a data view window. Once opened, a data view window will remain open until the variable goes out of scope or you choose to close it. The contents of the window will be updated each time a break point (or single step action) is encountered.

The source window provides the user with four methods of examining the contents of a variable in a data view window.

  1. Press the right mouse button over a variable name in a declaration or executable statement.

  2. Move the cursor to a variable name in a declaration or executable statement and press Ctrl+P.

  3. Mark a block over an expression and either press the right mouse button over the block or press Ctrl+P (this allows the expression to be displayed).

  4. Use the 'print' command from the command line (this allows complete freedom in the choice of data shown).

Methods 1 and 2 provide a very quick way to access simple variables. Methods 3 and 4 can be used to access more complex information like the current array element in a loop. Method 3 has the disadvantage that the expression must be present in the source code. Using the command line (method 4) allows greater flexibility.

To mark a block you can either drag the mouse pointer over the text whilst keeping the left hand mouse button depressed. Alternatively, you can use the arrow keys with the shift key held down. The block is shown as blue text on a cyan background. Pressing an arrow key without holding down the shift key will cancel the block mark.

In addition to the above methods for examining variables, the Win32 debugger provides 'tooltips' which appear when the mouse cursor passes over a variable in the source window. This tooltip takes the form of a small volatile window containing the value of the given variable.


Profiling_information

You can display profiling information (i.e. information on how many times each line has been executed) for a source file by pressing the F9 key. You must have compiled the source file with /PROFILE. The numbers displayed down the right hand column give the number of times each line has been executed. You can also display profile information with the 'profile' command.

More than one source file can be compiled with /PROFILE. In addition the profile counts can be written to a file.


Miscellaneous_information

The following table summarises the miscellaneous actions available with SDBG

Key | Meaning
F11 | Displays assembler output for this source code
F1 | Help
Right mouse button or Insert | Displays context menu-alternatives to some keystrokes


Variables_window

The variables window displays a variables list for the current source window (i.e. the one nearest the top). If the source window is not in the call stack the variables window will be empty. You can switch back to the source window by pressing F4. The window contains a highlight bar that shows the currently selected variable. The type of the variable is displayed in the bottom left corner of the window border.

In addition to using the scroll bar, you can move the highlight bar by using the following keystrokes:

Key | Meaning
Up | Bar up one
Down | Bar down one
Page Up | Bar up one page
Page Down | Bar down one page
Home | Start of list
End | End of list
Right | Scroll the window to the right
Left | Scroll the window to the left
Enter | Display variable in its own window
F4 | Display source
F5 | Display user screen
F6 | Run program
F7 | Step to next source line
F8 | Step to next source line and step over any calls tp routines
Shift+F9 | Fix window size and position
Alt+C | Display call stack
Ctrl+U | Set use (read/write) break point on variable
Ctrl+W | Set write break point on variable

The variables window displays the contents of all the variables in the current scope. This is usually more than adequate for simple variables. It is often useful to have commonly accessed variables or more complex variables (such as C structures or Fortran 95 types) displayed in a separate data view window. From a variables window this can be achieved by one of two methods:

  • Press Enter with the variable highlighted.

  • Double-click the left mouse button over the variable name.

    In addition, pressing the right mouse button will bring up a menu duplicating some of the above items as well as options to display memory dumps at the location of the variable and at the location indicated by the value of the variable.


Data_viewing_windows

Introduction

Simple expression

Array

Structure

Memory dump

Data view window


Data_viewing_windows_intro

Data Viewing Introduction

The variables window is always available and allows you to quickly see the current state of variables in a routine. A data view window is a window dedicated to one particular variable (or part of a variable) allowing you to see its contents in isolation. There are four different types of data view: simple expression, array, structure and memory dump. In addition, from one data view window you can also open other. These five types of data view are described below. You do not have to worry about which view should be displayed. It is all handled by SDBG.

The method used to display a data view window depends upon the current window.


Simple_expression

A simple expression window is displayed in one of two situations:

  • when the result of the variable or expression is a simple data type that can be displayed in one line, these data types include: integer, logical, real, complex, string and pointers to pointers;

  • when the variable or expression is in error, in which case an error message will be displayed.

    • If the data type is a pointer then you can display another window (that is the result of de-referencing the pointer) by pressing the Enter key. If the data is too long to fit into the window you can scroll the window to the left or right by pressing the left and right arrow keys. If you press the right mouse button with the mouse cursor over an expression window then a menu will appear.

    This menu contains the following items:

    Menu item | Action
Print value | Same as pressing Enter.
Memory dump at variable | Opens a memory dump window located at the address of the result. For example if the window displayed the value of a variable called ptr, this would produce a memory dump showing the physical memory used to store ptr .
Memory dump using contents | Opens a memory dump window located at the address pointed to by the result of this expression. The result does not have to be a pointer for this to work.
Set write break on variable | Places a write data break on the variable.
Set use break on variable | Places a use (read or write) break on the variable.

    You can close any data view by pressing the Esc key.


Array

An array view window will be displayed if the variable or expression results in an array. The array elements are displayed in a column. The window contains a highlight bar that shows the currently selected element. This can be expanded into its own data view window by either pressing Enter or double-clicking with the left mouse button. You can move the highlight bar by dragging the scroll bar. In addition you can also move the highlight bar by using the following key presses:

Key | Action
Up | Bar up one
Down | Bar down one
Page Up | Bar up one page
Page Down | Bar down one page
Home | Start of array
End | End of array

If you press the right mouse button with the mouse cursor over an expression window you will see a menu appear.

The items on the menu are as follows:

Menu item | Action
Print value | Same as pressing Enter.
Set visible range | This opens up a dialog that allows the visible range of subscripts to be set. This means that you need only display the array section that you are interested in.
Memory dump at variable | Opens a memory dump window located at the address of the result. In this case this would be a memory dump showing the physical portion of memory used by this array element (and those around it).
Memory dump using contents | Opens a memory dump window located at the address pointed to by the result of this expression. The result does not have to be a pointer for this to work.
Set write break on variable | Places a write data break on the variable.
Set use break on variable | Places a use (read or write) break on the variable.

You can close any data view by pressing the Esc key.


Structure

A structure view window lists the elements of a type (Fortran 95), structure (C), union (C), or class (C++) and their values. Each element resides on its own line in a manner similar to the array view and variables list.

The window contains a highlight bar that shows the currently selected element. This can be expanded into its own data view window by either pressing Enter or double-clicking with the left mouse button.

In addition to moving the highlight bar by dragging the scroll bar you can use the following key presses:

Key | Action
Up | Bar up one
Down | Bar down one
Page Up | Bar up one page
Page Down | Bar down one page
Home | Start of structure
End | End of structure

If you press the right mouse button with the mouse cursor over an expression window a menu will appear.

The items on the menu are as follows:

Menu item | Action
Print value | Same as pressing Enter.
Memory dump at variable | Opens a memory dump variable located at the address of the result. In this case showing the memory taken by this structure member.
Memory dump using contents | Opens a memory dump window located at the address pointed to by the result of this expression. The result does not have to be a pointer for this to work.
Set write break on variable | Places a write data break on the variable.
Set use break on variable | Places a use (read or write) break on the variable.

You can close any data view by pressing the Esc key.


Memory_dump

A memory dump window shows the individual bytes of memory with no formatting. The data in this window is displayed in three columns. The first column contains the start address of a strip of memory. The second column shows the bytes of memory that are contained in the memory starting at that address. The third and final column contains the ASCII representation of the same strip of memory.

The width of the strip depends on the window size and will automatically be scaled to the size of the window. In addition you can quickly change the size by pressing one of the following keys:

Key | Width
6 | 16 bytes wide
8 | 8 bytes wide
4 | 4 bytes wide
2 | 2 bytes wide
1 | 1 byte wide

Data values that read 'XX' constitute an invalid address.

One of the data values is highlighted. This is the current address. This is initially set to the address that you requested to display. The highlighted address is mirrored in the ASCII representation.

You can move the highlight using the following keys:

Key | Action
Left | One byte to the left
Right | One byte to the right
Up | Up one line
Down | Down one line
Page Up | Up one window height
Page Down | Down one window height

Pressing Alt+P will take the byte under the highlight and the following three bytes to form an address. The window will then be refreshed using this new address. This allows a pointer to be followed. You can go back to the address at which you pressed Alt+P by pressing Alt+B. You can nest Alt+P key presses to a depth of 20 and still be able to return to the starting point using Alt+B.

The expression, structure and array view windows all update to show any new values whenever the program is stepped or run to a new point. Because you may be looking at a specific area of memory, the memory dump window does not do this automatically even if the value of the expression used to set the window changes. You can force the window to reposition itself in memory by pressing Ctrl+O.

If you press the right mouse button with the mouse cursor over a memory dump window you will see a menu appear.

The items on the menu are as follows:

Menu item | Action
16 bytes per line | 16 bytes per memory strip
8 bytes per line | 8 bytes per memory strip
4 bytes per line | 4 bytes per memory strip
2 bytes per line | 2 bytes per memory strip
1 byte per line | 1 byte per memory strip
Set write break | Places a write data break on the address
Set use break | Places a use (read or write) break on the address

You can close any data view by pressing the Escape key.


Data_view_window

It is possible to open a data view window from a previous data view. This is used when following pointers etc.. To open one data view from another:

  • press Enter with the item highlighted or

  • double-click the left mouse button over the item name.

    • You can close any data view by pressing the Esc key.


Machine_code_windows

A machine code window displays the instructions that the CPU uses to execute your program and should only be used by people who understand assembler. A machine code window will be displayed on the following occasions:

  • if you select a routine in the call stack that has no debugging information; these routines have grey lettering rather than black,

  • if you select a routine in a Find window that has no debugging information; these routines have the words '(no debugger information)' following the routine name,

  • if you press F11 from a source window.

As with source windows the current execution point is shown by a red bar. An execution point that is not at the top of the call stack is shown in brown.

The window is split into three distinct columns. The first column shows the start address that the instruction is located at. The second column shows the assembler instruction at that location and the third column shows the offset of the instruction into the routine. The following key presses can be used within this window:

Key | Action
Esc | Close window
Up | Move up one instruction.
Down | Move down one instruction.
Page Up | Move up one page of instructions.
Page Down | Move up one page of instructions.
Ctrl+Home | Move to first instruction in routine.
F6 | Continue execution
F7 | Step one instruction.
F11 | Display source code if debugging information is available.
Ctrl+R | Display registers window.
Ctrl+M | Show memory dump window positioned on the current address


Command_line

To provide greater flexibility within SDBG a simple command line facility is available. The command line is accessed from the source window. It can be displayed by pressing Alt+P in the source window. Alternatively, you can display the command line by pressing any alphanumeric key (without holding down Alt or Ctrl). In this case the key press will appear on the command line. You can hide the command line by pressing Alt+P again. It is also possible to edit the command line.

The following key presses are permitted when editing a command line (see also Commands):

Key | Action
Left | Cursor left
Right | Cursor right
Home | Start of line
End | End of line
Backspace | Delete character to left
Delete | Delete character under cursor
Up | Recalls last command line (up to 20 are stored)
Down | Recalls next command line (up to 20 are stored)
Enter | Execute command line
Esc | Clear command line. If the command line is already clear it will be hidden.


Commands

This section contains a list of the valid commands that may be entered on the command line.

L/text/ or /text

This command performs a search forward within the source window for text and repositions the cursor if the text is found. The search is case insensitive.

BL/text/ or ?text

This command performs a search backward within the source window for text and repositions the cursor if the text is found. The search is case insensitive.

MOVETO n

Moves the cursor to line n. If n is greater than the number of lines within the file then the command is ignored.

PROFILE

Toggles profile information and has exactly the same effect as pressing F9.

PROFILE filename

This will write the source window, together with any profile counts, into the file filename. The profile information must already be displayed.

PRINT expr or P expr

Produce a data view window for the expression expr. The type of data view displayed is dependent on the expression given and will be automatically adjusted. This command provides a more general mechanism than displaying individual variables or marked expressions.

Examples

print machine_data[i] - C syntax

print machine_data(i) - Fortran syntax

print mph*1.6

print *ptr+stru->element - C syntax

PRINTMEM expr or PM expr

Produce a memory dump window centred about the value of expr. The given expression does not have to be a pointer type. It can be an integer or even a calculation.

VIEW filename

This command opens a new source window and displays the file filename in it. If the file is not an object file that makes up the current program or the relevant object file does not have debugging information then you will not be able to display expressions or set breakpoints from it. Any ASCII file can be displayed with this command.

FIND routine

This command will search for routines whose names contain the text routine. If one match is found that routine will be displayed. If more than one routine name matches the text given then a Find window will appear displaying all the matches.

The window will respond to the following key presses:

Key | Action
Up | Move the highlight bar up one line
Down | Move the highlight bar down one line
Home | Move the highlight bar to the top of the list
End | Move the highlight bar to the end of the list
Page Up | Move the highlight bar up one page
Page Up | Move the highlight bar down one page
Enter | Display the routine. If the words '(no debugging information)' appear after the routine name then a machine code window will be displayed. Otherwise the file appearing in brackets after the routine name will be displayed.
Esc | Close the window

The Find window will be kept open to allow further selections to be made, although it will probably be initially hidden by the new source (or machine code) window. You can easily cycle through all open windows by pressing Alt+N.

Example

find init

Could find the routines initialise_module, AnswerInIteration and DOINIT

WRITE_BREAK expr or WB expr

Places a write data break on the address indicated by evaluating expr. The break point will be set on the address of the result. For example:

write_break count | breakpoint placed on address of count
write_break *ptr | breakpoint placed on value of pointer ptr
write_break arr(9) | breakpoint placed on ninth element of arr
write_break 0x78647292 | breakpoint placed on address 0x78647292

USE_BREAK expr or UB expr

Places a use (i.e. read or write) data break on the address indicated by evaluating expr. The break point will be set on the address of the result as is the case with WRITE_BREAK.

REGS

Displays a window that shows the current values of the CPU registers. The values are in hexadecimal. The floating point stack is also shown.

BREAKPOINTS or BPS

Displays a window which contains the status of currently active breakpoints.

STREAMS

Opens a window that lists the currently open Fortran units.

STREAM n

Opens a window showing the status of Fortran unit n.

LET expr1=expr2

This command allows you to make changes to data without having to recompile. The value of expr2 is assigned to the item indicated by expr1. expr1 must be an expression to which a value can be assigned, for example let 12=6+a is invalid. If the two expressions refer to different data types a conversion will be applied to the result of expr2 to allow it to be used. You should, however, exercise caution when using differing types.

Examples

let i=10 | Simple variable assignment
let arr(j)=arr(count) | Array element assignment
let shape.colour=0x0f3229 | Structures

DOS cmdline or EXECUTE cmdline or X cmdline (DOS debugger only, not Win16/Win32)

This will load the command processor and execute the command cmdline, which may be a standard '.COM', '.EXE' or '.BAT' file. The command line may be omitted in which case the command shell will be started into which you can type commands. You should type the command EXIT to return to SDBG. You should not execute commands which:

  • Modify (or attempt to modify) any open files. This includes removing disks from the floppy drive that your program is using.

  • Try to execute Microsoft Windows or DosShell.

  • Execute any TSR program, including network shells.

  • Run any DBOS application. This includes Salford compilers and linkers.


Scripts

When using SDBG you can press Ctrl+P and enter a command directly into the debugger. These commands are approximately equivalent to the operations you can carry out with the mouse and menus in SDBG. In addition you can also join several of these commands together to produce a script. There are three ways to run a script:

1. You can execute the 'script' command from the command line. This will load the file specified and execute the commands.

2. You can specify a script on the debugger command itself. You use the /script option for this. A .script file extension will be assumed for the script. For example:

sdbg myprogram /script runtoproblem

3. You can specify the script as text on the debugger command. You use the vertical bar character to separate commands. This allows simple scripts to be run without creating a file. The /scriptis option is used to do this. For example:

sdbg myprogram /scriptis "getto mod1.f90 3456|print flow(7)"

You should enclose you script in quotes so that spaces can be used. You should note that the TYPE operator '%' should not be used on the command line as it can be confused with a DOS macro, use the C style '.' instead. For example:

sdbg myprogram /scriptis "breakpoint mod1.f90 12 6|go|print glob.flux"


Find window

This window shows the routines that contain a given sequence of characters. Routines from the current program listed first, followed by any matching library routines. The window respnds to the following keys:

Up | Move the highlight bar up one line
Down | Move the highlight bar down one line
Home | Move the highlight bar to the top of the list
End | Move the highlight bar to the end of the list
Page Up | Move the highlight bar up one page
Page Down | Move the highlight bar down one page
Enter | Display the routine If the words '(no debugging information)' appear after the routine name then a machine code window will be displayed. Otherwise the file appearing in brackets after the routine name will be displayed.
Esc | Close the window

The find window will be kept open to allow further selections to be made, although it may be initially hidden by the new source (or machine code) window.


Customising_the_debugger

SDBG can be customised in order to change its look and feel. To access the options, select Options from the Tools menu. The options available are:

Automatically open variables window – When checked the variables window will open automatically when the debugger is entered. When debugging programs with large numbers of variables it can sometimes be better to not open the variables window and just use the data view windows or tooltips. Default is on.

Sort variables window alphabetically – When checked the variables window is sorted into alphabetical order. When not checked the variables are listed in scope order, that is, local variables will be listed first followed by globals. Default is off.

Show PARAMETERs in variables window – When checked PARAMETERs will be shown in the variables window if /FULL_DEBUG is used on the FTN95 command line. When debugging programs with large numbers of parameters (Windows applications in particular) the parameters can clutter up the variables window, obscuring the variables. Default is on.

Only use one source window – With this option turned on the debugger will only use one window for displaying source files. When turned off the debugger will use a new window for each routine in the call stack that is shown. Default is off.

Show Tips at Startup – When checked the debugger will show the 'Tip of the day' window at startup. Default is on.

Debugger is MDI – When checked the debugger windows will be enclosed within a MDI (multi document interface) window. When not checked the windows will appear directly on the desktop. Win16/Win32 only, default is on.

Display bubble help – When checked the toolbar buttons will show tooltips when required. Win16/Win32 only, default is on.

Display variable values in source – When checked popup tooltip help will appear when the mouse cursor is over a variable name. The tooltip help will contain the variable's name and value. Win16/Win32 only, default is on.

Use original colour scheme - Unchecking this will cause future SDBG sessions to default to plainer colour scheme than the original version. This can also be modifed by the user by editing the SDBG.INI file, found in the Windows folder (eg. C:\WINDOWS\SDBG.INI). Settings in the ini file take precedence over the default colours.

The format is:

xxxxWindow-ColourElement=nnnn
Where xxxx is the window type and nnnn is the rgb colour required. The colour can be in hex if prefixed by '0x' and the format is 0xBBGGRR.

The following are the keys recognised:

SourceWindow-Text and SourceWindow-Window
Colour of text/background in a source window

VariablesWindow-Text and VariablesWindow-Window
Colour of text/background in a variables window

VariablesWindow-ProtectedText
Colour of protected members in a struct

VariablesWindow-PrivateText
Colour of private members in a struct

StackWindow-Text and StackWindow-Window
Colour of text/background in a stack window

StackWindow-NoDebugText
Colour of text for routines that do not have debugging information

StackWindow-StatusText
Colour of the status text in the stack window

AsmWindow-Text and AsmWindow-Window
Colour of text/background in an assembler window

FindWindow-Text and FindWindow-Window
Colour of text/background in find routines result window

RegsWindow-Text and RegsWindow-Window
Colour of text/background in a register window

ExpressionWindow-Text and ExpressionWindow-Window
Colour of text/background in an expression window

ExpressionWindow-ProtectedText
Colour of protected members in a struct

ExpressionWindow-PrivateText
Colour of private members in a struct

BreakpointsWindow-Text and BreakpointsWindow-Window
Colour of text/background in the breakpoints window

StreamsWindow-Text and StreamsWindow-Window
Colour of text/background in the streams window

For example and in keeping with the original sdbg strong colours

StackWindow-StatusText=0x0000ff
StackWindow-Text=0x000000
StackWindow-Window=0x00ffff


Exception handling

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Trapping Win32 exceptions

Exceptions are events generated outside the normal flow of control through a program or thread of execution. Such an event may arise due to a hardware event (such as a page fault) or through a software trap such as an attempt to access another processes memory space. The default action of the process is to terminate the process and produce diagnostic information.

TRAP_EXCEPTION@ and SET_TRAP@ provide the programmer with a method to trap these exception events and to act appropriately. This means that it is possible to trap (say) an underflow event and reset a variable to a known value (say zero).

This is achieved by maintaining a table of functions to be executed in the event of an exception. Only one exception handler may be installed for any particular exception event at any one time. So you may have two different handlers installed for two different exception events, but you may not have two handlers chained together for the same exception event. This also applies to mixed language programming where nominally different handlers are required for Fortran and C code. If you want to handle an exception differently in different parts of the code, you can remove one exception handler and install another.

Each exception event is identified by an exception event code. This is an integer value that is used to uniquely identify each of the possible exceptions that are trapable by the user. These codes are defined in the insert file except.ins which is provided as part of the FTN95 system.

When an exception event occurs, the operating system copies the machine state into an area of memory. The image of the machine may be manipulated to correct the fault in order to resume execution in an orderly manner. Once the machine state has been saved, the exception handler searches for a handler offering the event to the following processes:

  • Debugger first chance.

  • The frame based handler installed by the program.

  • Debugger second chance.

The frame based handler is the one installed by any main program compiled with FTN95. This handler is really a filter. It examines the exception event that has occurred and looks to see if the user program has installed a handler for that event. If such a handler routine is installed, control is passed back to the routine. If no handler is found, the Fortran program takes the default action or it terminates and the exception details are displayed for debugging purposes.

The two functions TRAP_EXCEPTION@ and SET_TRAP@ are used to install an event handler for a given event. SET_TRAP@ is used to trap the use of CTRL+C to break into program execution.

Here is a summary of the FTN95 error and exception handling routines that are peculiar to Win32.

ACCESS_DETAILS@ | Gets details of the access violation.
CLEAR_FLT_UNDERFLOW@ | Clears a floating point underflow exception.
EXCEPTION_ADDRESS@ | Finds the address of the instruction that generated the exception.
GET_VIRTUAL_COMMON_INFO@ | Gets virtual common block details.
PRERR@ | Prints the error message associated with a given error code.
RESTORE_DEFAULT_HANDLER@ | Removes a user defined exception handler.


Underflows

Here is a summary of how FTN95 handles underflow. Details appear below. By default FTN95 sets underflow as unmasked so that when a underflow occurs an exception is generated. FTN95 handles this exception internally and by default allows the computation to continue. A call to the routine MASK_UNDERFLOW@ sets underflow as masked so that an underflow does not generate an exception. A call of PERMIT_UNDERFLOW@(.FALSE.) resets underflow as unmasked and also triggers a run time error when FTN95 handles the exception internally.

Intel architectures use IEEE format floating point numbers. An underflow occurs when the result of a floating point operation is too small to be represented by the floating point format. The discussion below is illustrated using extended precision as an example. Single and double precision underflows are similar.

If x=1E-3000 then y=x*x cannot be represented because the result is 1E-6000 which is smaller than the smallest normalised floating point number (approximately 1E-4932). y would be set to zero.

The floating point unit has a masked and an unmasked response to underflow. In the above example y is set to zero in both cases. However, the mechanisms are quite different. With the masked response, the actual result is zero and is directly assigned. The unmasked response is to generate an underflow exception which is trapped by the run time library. The failing instruction is decoded and the target register or storage is replaced with zero. Unless PERMIT_UNDERFLOW@(.FALSE.) is used, control is then returned to the program at the following instruction and execution continues as normal.

Denormals
Denormals arise for one of two reasons: a) when an integer or an unset variable is passed as an argument that should be an floating point number and b) when the result of a floating point calculation is too small to be a normalised number but still large enough to have a representation (this only occurs when using the masked response to underflow).

In case (b), when the smallest exponent of the number is reached, leading zeroes are introduced into the significand of the number. Thus precision is lost for these numbers. Smaller numbers introduce more leading zeroes and this continues until no more leading zeros can be introduced and the result becomes zero. This process is called gradual underflow. Only when the number is less than about 1E-4951 does it become zero.

For example, the hex pattern below is the smallest positive extended precision normalised number. This is defined as such in the IEEE specification.

Exponent | Significand
0001 | 8000000000000000 (64 bits of precision)

Note that the most significant bit of the significand is 1 (8 is 1000 in binary). This is the normalisation bit. Every valid floating point number is shifted so that this bit is 1. This allows 64 bits of precision because there are no leading zeroes. However, if a smaller number is generated, the exponent is 0 and a leading zero is introduced into the significand:

Exponent | Significand
0000 | 4000000000000000 (63 bits of precision)

The number is then termed a denormal. The smallest denormal is:

Exponent | Significand
0000 | 0000000000000001 (1 bit of precision)

Although precision is lost for these extremely small values, the unmasked response of replacing them with zero represents a total loss of precision. Denormals, therefore give better numerical results although at times they may be non-zero when zero was expected. Denormals are handled like any other number and are printed correctly by the I/O system.

If underflows become unmasked, an attempt to use a denormal results in a run time error whilst the output field for a denormal is filled with "?".

Masking underflows
Underflows can be masked by calling the subroutine MASK_UNDERFLOW@

SUBROUTINE MASK_UNDERFLOW@()

Underflows can be unmasked by calling the subroutine UNMASK_UNDERFLOW@

SUBROUTINE UNMASK_UNDERFLOW@()

This is the default. If one of these is used, it should be the first executable line in your program. You are very strongly advised not to change the underflow state after this. Calling PERMIT_UNDERFLOW@(.FALSE.) causes underflows to become unmasked. The environment variable SALFENVAR can be set to MASK_UNDERFLOW or UNMASK_UNDERFLOW in order to provide a default state for your programs. If there is no environment variable setting, then the default is to unmask underflows.

Summary
Masking underflows provides a very safe way of handling underflows and achieving better numerical results, although you should be aware of the issues involved.

The table below shows the range of positive floating point values.

 | Largest | Smallest | Smallest denormal(masked underflows)
Single precision | 1E38 | 1E-38 | 1E-46
Double precision | 1E308 | 1E-308 | 1E-324
Extended precision | 1E4932 | 1E-4932 | 1E-4951


The in-line assembler

Introduction

The execution environment

The CODE/EDOC facility

Mixing of Intel 32-bit Assembler and Fortran

Labels

Referencing Fortran variables

Literals

Halfword and byte forms of instructions

Using the coprocessor

Instruction prefixes

Other assembler facilities

Other machine-level facilities

Error messages


Assembler Introduction

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

This section explains how to write 32-bit assembler instructions in Fortran programs written for the Win32 platform. FTN95 users wishing to code at the assembler level should obtain a copy of a Programmer's Reference Manual published by Intel.


The execution environment (Win32)

The execution environment

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

Each process executes in its own 32-bit virtual address space. This gives 2 gigabytes for the combined code and data spaces (the remaining 2 gigabytes are reserved for the operating system). Using the advanced features of the CPU, each process address space is protected from modification by other processes executing within the system.


The CODE/EDOC facility

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

This item is about CODE/EDOC when compiling in 32-bit mode. For a discussion of 64-bit CODE/EDOC see here.

The CODE statement switches the compiler into a mode in which it accepts Intel 32-bit assembler instructions rather than Fortran statements. The compiler is returned to normal by the EDOC statement. A CODE/EDOC sequence may appear anywhere that an executable Fortran statement is permitted. For example:

    CHARACTER*10 L
    CODE
    LEA EDI%,L ;EDI gets address of L
    MOVB AL%,='*' ;Asterix in AL
    MOV ECX%,=10 ;Count in ECX
    REP ;Rep prefix coded as
   + ; a separate instruction
    STOSB ;This fills L with aster isks
    JMP $10 ;Jump to label 10
    EDOC
    PRINT *,'This should not be printed'
    STOP
    10 PRINT *,'L = ',L
    END

This example is artificial in that there is no real point in performing operations in assembler that can be done in Fortran, however it illustrates that code is written according to the following conventions:

  • Instructions refer to Fortran objects or explicitly to the registers

  • Register names are followed by a '%' to distinguish them unambiguously from variable names.

  • Instructions must start in column 7 or beyond.

  • Only numeric (Fortran) labels are permitted.

  • Comments may be included provided they are preceded by a semi-colon character (;)

  • Some mnemonics are followed by an 'H' to indicate halfword (16-bit) operation or by 'B' to indicate a byte operation. This is discussed in more detail below.


Mixing of Intel 32-bit Assembler and Fortran

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

Assembler programs should not alter registers EBX% (pointer to non-local dynamic data), EBP% (pointer to local dynamic data), or ESP% (stack pointer). Other general registers can be used freely.

The coprocessor will be empty and in rounding mode when control is passed to assembler, and it must be in the same state afterwards.


Labels

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

It is possible to jump from Assembler to labelled Fortran statements and vice-versa. As in the above example, labels are Fortran labels and are referred to by preceding the numeric label by a dollar character thus:

    JMP $7

Conditional jumps are coded in 32-bit form when necessary, so these may be used without considerations of range. The LOOP instructions, which do not have 32-bit forms, are not supported by the assembler.


Referencing Fortran variables

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

Variables are referenced using the following scheme.

  • Local dynamic variables are addressed using EBP%.

  • Non-local dynamic variables are addressed using EBX%.

  • An argument can only be referenced by its address. For example, in order to load the argument L into AX% use:

SUBROUTINE FRED(L)
INTEGER*2 L
CODE
  MOV EAX%,=L ;Get address of L
  MOVH AX%,[EAX%] ;Load halfword
  .
  .

  • References to common or external variables are constructed using a full 32-bit address.

These rules mean that local variable references may be indexed by one extra register, and common variables may have two indexing registers if necessary. For example:

INTEGER*4 L(200)
CODE
  MOV EAX%,=8
  MOV L[EAX%],=0 ;This sets L(3) to 0

Variable references may be offset. For example:

CHARACTER*10 FOO
CODE
  MOVB FOO+3,=32 ;Sets FOO(4:4)=' '

Indices can also contain multipliers of 1 (default), 2, 4, or 8. For example:

ADD [EAX%+ECX%*4], =6


Literals

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

An instruction operand may be a constant (literal). In this case the constant must be preceded by an '='. Floating point instructions may have literal arguments, which are placed in memory and addressed, since there is no immediate form of these instructions.

Literals may contain any constant expression (which will be evaluated using the standard Fortran rules) and may be of any type. For example:

FLD      =5.0
DFADD    =5.0D0                  ;Note REAL*8
                                 ; constant needed
MOV      EAX%,=(4*5)             ;Load 20 into EAX%
TEST     FRED,=Z'FEFFFFFF'       ;Hex constant


Halfword and byte forms of instructions

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

In standard (16 bit) assembler notation, many instructions have two forms depending on whether the operand is of type byte or word. In 32 bit assembler, instructions may have three forms - full word (32-bit), half word (16-bit) and byte (8-bit).

Rather than follow the Intel convention that the instruction is defined by its operand (something which is hard to define in the context of Fortran variables), each distinct instruction has a different mnemonic. The conventional Intel mnemonic refers to the 32-bit form of the instruction, and we append an 'H' to refer to a half word instruction (constructed using an operand size prefix) or a 'B' to refer to a byte instruction where available. Thus for example we have the following string move instructions:

MOVS ;Move a full word
MOVSH ;Move a half word
MOVSB ;Move a byte

A similar scheme is used with the memory reference coprocessor instructions. Thus we have for example four types of memory reference floating point additions:

FIADDH I ;Add an integer half word
FIADD L ;Add an integer full word
FADD R ;Add a short real (4 bytes)
DFADD D ;Add a long real (8 bytes)


Using the coprocessor

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

Coprocessor stack operands are referred to using the following notation:

    ST(0) ;Stack top
    ST(1) ;Next to stack top
    etc.

Stack reference instructions use the short real form of the mnemonic (for example, FADD) but the actual calculations are performed to the full precision of the coprocessor. The coprocessor stack must be returned empty and with the control word unchanged. Coprocessor instructions do not contain an implied WAIT. WAIT instructions are only necessary after results are returned to the 32-bit Intel chip (FSTP, or FSTSWAX for example), and even then only if the result will be used before another coprocessor instruction is started.

If you are writing code that might be used in an another environment, you should ensure that any coprocessor mnemonics you use are appropriate to that environment.


Instruction prefixes

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

The following prefixes are available as pseudo instructions coded on the line above :

REP
REPE
REPNE
FS ;Appends the FS: prefix
GS ;Appends the GS: prefix

For example:

FS ;Source operand from FS
REP
MOVSB

or

MOV FS:0,ESP%

would be coded as

FS
MOV 0,ESP%

Other prefixes are rarely needed, however they are available using the DB pseudo instruction to code an arbitrary byte. For example the CS: prefix could be coded as:

DB Z'0E'


Other assembler facilities

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

In general, the assembler pseudo-instructions and macros are not available, as equivalent or more powerful facilities are available using FTN95. The following pseudo instructions have been provided:

  • In-line data may be inserted using DB, DW, or DD pseudo instructions. For example:

DD Z'FEFFFFFF' ;4 bytes
DW 45 ;2 bytes
DB -1 ;1 byte

  • Do not try to select the coprocessor rounding mode by using an explicit FLDCW, as this will invalidate the independent control of arithmetic precision. Each of the following pseudo instructions is snapped on first use to the appropriate FLDCW command referencing a table of suitable control words:

FROUND ; Select rounding mode
FCHOP ; Select chopping towards 0
FCHOPM ; Select chopping towards - infinity
FCHOPP ; Select chopping towards + infinity


Other machine-level facilities

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

It is always inconvenient to have to descend to assembler, even in the form of a CODE/EDOC sequence, and a number of special Fortran constructions have been introduced for convenience.

  • The intrinsic functions CCORE1, CORE1, CORE2, CORE4, FCORE4, DCORE8, XCORE10, ZCORE8, ZCORE16, and ZCORE20 are available to examine the contents of a given location.

Each function takes an INTEGER(KIND=7) argument which is an address and returns the following value at that address.

CCORE1 | CHARACTER
CORE1 | INTEGER(KIND=1)
CORE2 | INTEGER(KIND=2)
CORE4 | INTEGER(KIND=3)
FCORE4 | REAL(KIND=1)
DCORE8 | REAL(KIND=2)
XCORE10 | REAL(KIND=3)
ZCORE8 | COMPLEX(KIND=1)
ZCORE16 | COMPLEX(KIND=2)
ZCORE 20 | COMPLEX(KIND=3)

These functions may also be used on the left hand side of an assignment. For example:

CORE2(L) = CORE2(L)+1
CCORE1(P)=' '
CORE1(PTR)=123

If an argument to a routine is one of these functions the actual address is passed, for example:

INTEGER(7) L
INTRINSIC LOC,CORE2
K = 4
L = LOC(K)
CALL FRED(CORE2(L))
PRINT *,K
END
SUBROUTINE FRED(M)
M = M + 2
END

would print 6.

  • A special form of the SUBROUTINE statement is available for x86 (Win32) thus:

      SPECIAL SUBROUTINE JACK

Special routines must have no arguments, and contain no preamble to set EBX%,EBP% etc. They can only really be followed by CODE/EDOC sequences, and no reference to dynamic variables must be made in such a routine. Static variables may be referenced and will use the full address form of the instruction (rather than EBX% relative). Special subroutines may contain additional entry points coded as special entries:

      SPECIAL ENTRY BILL

Special routines may not contain ordinary entry points and vice-versa. The return from a special subroutine must be via a RET instruction and not as a result of executing a RETURN or END statement. The main purpose of the special subroutine is as a routine which can be called from assembler without altering the contents of the registers.

An additional use of this facility is in conjunction with the SET_TRAP@ routine. A control break or floating point fault can take place at an arbitrary point in a program, and it is important to be able to save the registers etc. before they are overwritten. Although this can be done with an interrupt subroutine without the use of CODE/EDOC, the latter offers the ability to inspect and alter the contents of the registers if desired.

  • Circular shifts are available as intrinsic functions and thus do not require the use of assembler.

  • The LOC intrinsic function returns the address of its argument as a 32 bit number (64 bit for x64).


Error messages

In this section:

  • Introduction
  • The execution environment
  • The CODE/EDOC facility
  • Mixing of Intel 32-bit Assembler and Fortran
  • Labels
  • Referencing Fortran variables
  • Literals
  • Halfword and byte forms of instructions
  • Using the coprocessor
  • Instruction prefixes
  • Other assembler facilities
  • Other machine-level facilities
  • Error messages
  • 64-bit assembler

Owing to the syntax of assembler, use of unpaired apostrophes and parentheses in comments in CODE/EDOC sequences will cause the compiler to output apparently spurious messages concerning the mismatching.


Mixed language programming

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

This section discusses the details of inter-language Win32 programming between Fortran and Silverfrost C/C++. The sizes of the various data types, data storage and function call styles are covered in order to facilitate the mixing of modules compiled in either language. It is important to note that you can freely mix FTN95 and FTN77 compiled code and either or both can do the input/output.


Data types

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Basic data types

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

The table below illustrates the amount of storage required for the basic data types associated with each language. In all the languages, pointers are represented as 32-bit quantities.

Data type | Size (bytes) | C/C++ | FTN77 | FTN95
Integer | 1 | char | INTEGER*1 | INTEGER (KIND=1)
Integer | 2 | short int | INTEGER*2 | INTEGER (KIND=2)
Integer | 4 | int long int | INTEGER*4 | INTEGER (KIND=3)
Unsigned integer | 1 | unsigned char | - | -
Unsigned integer | 2 | unsigned short int | - | -
Unsigned integer | 4 | unsigned int | - | -
Logical | 1 | char | LOGICAL*1 | LOGICAL (KIND=1)
Logical | 2 | short int | LOGICAL*2 | LOGICAL (KIND=2)
Logical | 4 | int | LOGICAL*4 | LOGICAL (KIND=3)
Real | 4 | float | REAL; REAL*4 | REAL (KIND=1)
Real | 8 | double | REAL*8; DOUBLE PRECISION | REAL (KIND=2)
Real | 10 | long double | - | REAL (KIND=3)
Character | 1 | char | CHARACTER | CHARACTER


Array Storage

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

There are two methods of storing arrays, row-wise and column-wise. Row-wise storage means that the elements are stored a row at a time starting from a base address and increasing towards high memory. Arrays stored column-wise have the elements stored a column at a time increasing towards high memory.

For example, consider the array consisting of 10 rows and 20 columns. The appropriate declarations in each language would be:

FTN77 | INTEGER*4 numbers(10,20)
FTN95 | INTEGER (KIND=3) numbers(10,20)
C/C++ | int numbers[20][10];

A row-wise array would be stored as:

numbers(0,0); numbers(1,0); numbers(2,0); ... numbers(9,0);
numbers(0,1);....

whilst a column-wise array would store the elements as

numbers(0,0); numbers(0,1); numbers(0,3); ... numbers(0,9);
numbers(1,0);....

The various language standards define Fortran as using column-wise storage, whilst C/C++ stores arrays row-wise. Therefore, a Fortran array defined as numbers(10,20), would have the equivalent C/C++ declaration numbers[20][10]. In Fortran by default the elements are actually numbered from one whilst in C/C++ they are numbered from zero.


Character strings

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

C/C++ character strings are stored as a NULL (char(0)) terminated arrays of characters whilst Fortran characters strings are fixed length and are padded to the end of the array with spaces. It is important to take into consideration these different methods of storing strings when passing or receiving them as parameters.


Calling FTN95 from C/C++

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

The following text assumes that you are writing in Silverfrost C/C++ and are calling an FTN95 relocatable binary library (RLB) or dynamic link library (DLL).

When calling FTN95 routines from C/C++, the following major points should be considered:

• Fortran arguments are passed by reference rather than value.

• All Fortran external names are upper case (regardless of the case of the original source text).

• Fortran character variables have no simple analogue in C/C++.

If you have a C/C++ main program calling a Fortran RLB, then the main program should call the library initialisation routine if there is one. Failure to do so will result in unpredictable behaviour. If you are calling a DLL then the initialisation will probably take place automatically when the DLL is loaded.

For a practical example of how to call an FTN95 DLL from a Visual C++ program see the following topic, which includes example source code.

Visual C Interoperabilty - Calling an FTN95 DLL from Visual C++ (Win32)


CHARACTER variables

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

Fortran character arguments are fixed length and padded with space characters. In order to determine the length of a character argument, the FTN95 compiler passes the length of the string as an extra argument at the end of the argument list for the subroutine/function. If more than one character argument is passed, then the lengths are passed in the order in which the character arguments appear in the argument list. For example:

SUBROUTINE COMPARE(STRING1, STING2)
CHARACTER (LEN=*)::STRING1, STRING2
.
.
END

This subroutine would have the following C/C++ prototype:

extern "C" COMPARE(char *s1,char *s2,int l1,int l2);

where l1 and l2 are the lengths of the two strings s1 and s2 respectively. In order to call COMPARE from within a C/C++ program, the programmer must pass the lengths of the two strings so the call would look something like this:

char *str1, *str2;
.

.
COMPARE(str1, str2, strlen(str1), strlen(str2));


Arrays Access

Array Access

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

As we have already noted, the standards for C/C++ and Fortran define array storage differently. Is is therefore necessary to provide an interface routine between the FTN95 library and the C/C++ code or to modify the C/C++ code to take into account the differences in data storage.


INTEGER, LOGICAL and REAL

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

It is necessary to ensure that the data type of the C/C++ variable matches that of the FTN95 variable (see the table in Basic data types ). All parameters in the Fortran argument list will be passed by reference. You should therefore declare each argument as a pointer in C or as a reference variable in C++.


Calling C/C++ from FTN95

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

The C_EXTERNAL and STDCALL keywords give the Fortran programmer the ability to call C/C++ routines, forcing the compiler to generate extra code to handle some of the data conversions. C_EXTERNAL is used when the "cdecl" calling convention is used by C/C++ (e.g. the Win16 Windows API). STDCALL is used when the "stdcall" calling convention is used by C/C++ (e.g. the Win32 Windows API).

An example of a type requiring data conversion is the string data type. As we have already noted, C/C++ strings are NULL terminated, whilst Fortran strings are fixed length, padded with spaces. The C_EXTERNAL and STDCALL declarations for a function inform the compiler that the function or subroutine is written in C/C++ and is external to this program module. If the function uses a string data type, code is planted to generate a C/C++ style string before entering the C/C++ function. Code is also generated after the function call to convert the C style string back into a Fortran string. This frees the C/C++ programmer from the additional complexities of providing the conversion code. It also means that a Fortran programmer can call a third party library without converting all string references into C/C++ strings before calling an external routine.

The C_EXTERNAL declaration has the following form (for STDCALL, simply replace C_EXTERNAL by STDCALL or refer to the ClearWin+ User's Guide).

C_EXTERNAL name ['alias'] [(desc , ...)] [:restype]

where:

name
is the name to be used to call the function in the Fortran program.

alias
is the external name used for the routine (i.e. the name that is used in the C/C++ source code). This appears in single quotes and is case-sensitive.

desc
describes the arguments that the routine receives and/or returns.

restype
identifies the routine as a function and describes the type of the object returned; this may be any function type other than CHARACTER.

Some examples of valid C_EXTERNAL declarations are given below.

Example 1

C_EXTERNAL SUB

This describes an external C/C++ routine which accepts no arguments and returns no result. The corresponding C/C++ declaration would be

extern "C" void SUB(void)
{
.....
}

and the function would be called by the Fortran statement CALL SUB.

Example 2

C_EXTERNAL WRITE 'WriteFile' : INTEGER*4

This describes a C/C++ routine called WriteFile which accepts no arguments, but returns an integer result. The routine is called from a Fortran program by the statements

INTEGER(KIND=3)::RESULT
RESULT = WRITE()
.....

The C/C++ code could have the following form

int WriteFile(void)
{
.....
}

Before continuing, we must first examine the possible forms of the desc parameter and the restype part of the declaration in more detail.

The desc parameter allows the programmer to over ride the default linkage of arguments. If you use these argument descriptors, the number of arguments in each occurrence of a call must agree with the number of descriptors in the routine definition. desc may be any one of: REF, VAL, STRING, INSTRING, OUTSTRING.

The VAL specifier may only be used for numeric and logical scalars. Instead of pushing the address of the value onto the stack, the actual value is pushed. This allows C/C++ functions to use its arguments as local variables. The REF specifier may be used with any Fortran object. This forces the Fortran program to push the address of the object onto the stack. This is the default action but should be used as a matter of good programming practice to allow the compiler to check for the correct usage of external functions. So we may additionally have the following descriptions:

C_EXTERNAL UNIX_WRITE 'write' (VAL, REF, VAL): INTEGER*4

for the UNIX low-level write function. This is defined in C/C++ as

int write(int handle, void *buffer, int amount)
{
.....
}

but it now looks to the Fortran program as if it was a Fortran function declared as:

FUNCTION UNIX_WRITE(HANDLE, BUFFER, BUFSIZ)
INTEGER(KIND=3)::HANDLE, BUFFER, BUFSIZ, UNIX_WRITE

The remaining three types, STRING, INSTRING, OUTSTRING, are a little more complicated. All three are used to describe a string object. Each one forces the compiler to do differing amounts of work before the function call is made. As we have already seen from the discussion at the start of this section, the compiler can be forced to convert strings from Fortran strings to C/C++ strings and visa-versa. This is the default action and is equivalent to the STRING descriptor. However this causes an unnecessary overhead if and argument is to be used for either input to a function or output from a function but not both. In this case the INSTRING and OUTSTRING maybe used. This saves the redundant copy operation from taking place. It is also possible to restrict the length of the temporary variable used to store the string which is actually used in the function call. The default length of the string is the length of the CHARACTER array or 256 bytes in the case of a CHARACTER(LEN=*) array. This is done by specifying the length of the string in parentheses after the descriptor. Further examples of the C_EXTERNAL are:

C_EXTERNAL COPY_STRING 'strcpy' (OUTSTRING,INSTRING): INTEGER*4
C_EXTERNAL STRNCPY 'strcat' (STRING, INSTRING(40)): INTEGER*4

where strcpy and strcat are the standard C library functions.


Calling an FTN95 DLL from Visual Basic

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

An FTN95 DLL that is called by an executable that uses the STDCALL calling convention (e.g. one created using Win32 Visual Basic) must use F_STDCALL in the declaration of all exported subprograms. For example,

F_STDCALL FUNCTION F(X)
INTEGER F,X
F=X
END

Such a function could make calls to Windows API functions provided an interface is provided via, for example, "USE MSWIN" or "INCLUDE <windows.ins>". Alternatively an interface for each API function can be given explicitly. For example,

STDCALL SENDMESSAGE 'SendMessageA' (VAL,VAL,VAL,VAL):INTEGER*4

A call is automatically made to a DLL function called LIBMAIN when the DLL is loaded. If you do not provide a definition of LIBMAIN then SLINK will provide a default for you. LIBMAIN is used to initialise global data. It takes the following form.

F_STDCALL INTEGER FUNCTION LIBMAIN(hInst,ul,lpR)
INTEGER hInst,ul,lpR
!***** Initialise global data here
LIBMAIN=1
END

A simple SLINK script would take the form:

dll
lo f95.obj
exportall
file c:\windows\f95.dll

A Visual Basic program can use calls to the API functions LoadLibrary and FreeLibrary in order to ensure that the DLL does not unload whilst a Visual Basic form is loaded. Here is some sample code for this purpose.

Private Declare Function LoadLibrary Lib "kernel32" Alias "LoadLibraryA" (ByVal s As String) As Long
Private Declare Function FreeLibrary Lib "kernel32" (h As Long) As Long
Dim hLibModule As Long

Private Sub Form_Load()
hLibModule = LoadLibrary("f95.dll")
End Sub

Private Sub Form_Unload(Cancel As Integer)
i& = FreeLibrary(hLibModule)
End Sub

The FTN95 DLL is assumed to reside in the Windows system directory.


Mixing I/O systems in Fortran and C/C++

In this section:

  • Mixed language programming
  • Basic data types
  • Arrays
  • Character strings
  • Calling FTN95 from C/C++
  • CHARACTER variables
  • Arrays
  • INTEGER, LOGICAL and REAL
  • Calling C/C++ from FTN95
  • Calling an FTN95 DLL from Visual Basic
  • Mixing I/O systems in Fortran and C/C++

You can freely mix FTN95 and FTN77 compiled code and either or both can do the input/output.

However, in general the I/O systems in Fortran and C/C++ are different and should not be mixed. For example, it is not usually possible to open a file in FTN95, and then pass the handle to be used in C/C++. The only exception to this rule is that if you use DBOS library calls to manipulate files, then the handles are common across the language boundary.


Introduction to 64 bit FTN95

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

Getting started

The Silverfrost Fortran compiler FTN95 creates 64 bit executables and DLLs when:

  1. the option /64 is used on the FTN95 command line,
  2. SLINK64 is used in place of SLINK,

Differences between 32- and 64-bit Fortran

Silverfrost Fortran tries to make code work in both 32 and 64 bit modes. For most applications and systems you won't notice the difference. There are some differences though:

  • Extended precision (REAL*10 and COMPLEX*20) are not available when creating 64 bit applications
  • salflibc64.dll and clearwin64.dll are used in place of salflibc.dll.
  • 64-bit programs run in a much larger address space. 32-bit FTN95 programs could, with some configuration, use 3GB of RAM. 64-bit programs are effectively limited to the amount of RAM, with hard disk backing, that you can give them.
  • 64-bit programs cannot run on 32-bit versions of Windows.
  • 64-bit programs cannot use 32-bit DLLs (and vice-versa).
  • When distributing you programs you must also distribute the 64-bit run time DLLs. These are salflibc64.dll and clearwin64.dll
  • 64-bit Microsoft Windows HANDLEs are addresses (64-bit integers). So if a Windows handle is used explicitly in Fortran code, it will currently appear as a 32 (KIND=3) integer and must become a 64-bit (KIND=4) integer for 64-bit applications. FTN95 has a special KIND value (7) that is interpreted as KIND=3 for 32-bit applications and KIND=4 for 64-bit applications. Alternatively INTEGER(KIND=CW_HANDLE) can be used together with standard INCLUDE and MOD files because CW_HANDLE is defined as a parameter with value 7. Windows HANDLEs are mainly used with %lc, %hw and some direct calls to the Windows API.
  • Assembler in CODE/EDOC is not compatible between 32 and 64-bit modes

64 bit FTN95 is a progression from Win32 FTN95 and not .NET FTN95. So the command line option /64 cannot be combined with /CLR.

SLINK64

The Silverfrost 64 bit linker SLINK64 can be used in:

  1. command line mode,
  2. interactive mode or,
  3. script file mode.

Here is an example of using command line mode...

  FTN95 prog.f95 /64
  FTN95 sub.f95 /64
  SLINK64 prog.obj sub.obj /file:prog.exe

Here is an example of using interactive mode...

  SLINK64
  $ lo prog.obj
  $ lo sub.obj
  $ file prog.exe

Here is an example of using a script file...

  SLINK64 @prog.inf

where prog.inf contains...

  lo prog.obj
  lo sub.obj
  file prog.exe

For further information see below or type...

  SLINK64 /help

SLINK64 automatically scans commonly used Windows DLLs. If a Windows function located in (say) xxx.dll is reported as missing then the DLL should be loaded by using a script command of the form

  lo C:\Windows\Sysnative\xxx.dll

where C:\Windows illustrates the value of the %windir% environment variable.

Note that SLINK64 can construct executables and DLLs but not static libraries. Users can create a static library by constructing a master file containing only INCLUDE statements for the relevant files. Compiling the master file will create a .obj file that is equivalent to a static library file.

SDBG64

The 64 bit debugger SDBG64 operates in essentially the same way as the corresponding 32 bit debugger SDBG.

ClearWin+

64 bit ClearWin+ was available (before 64 bit FTN95) for use with third party compilers via clearwin64.dll. This DLL has been extended for use with 64 bit FTN95. Users who have adapted their code for use with third-party compilers can continue to use their modified code. Alternatively native FTN95/ClearWin+ code can be used without change apart from the following exceptions.

64 bit Microsoft HANDLEs are addresses (64 bit integers). So if a Microsoft handle is used explicitly in 32 bit Fortran code, it will appear as a 32 (KIND=3) integer and must become a 64 bit (KIND=4) integer for 64 bit applications. FTN95 has a special KIND value (7) that is interpreted as KIND=3 for 32 bit applications and KIND=4 for 64 bit applications. Alternatively INTEGER(KIND=CW_HANDLE) can be used together with standard INCLUDE and MOD files because CW_HANDLE is defined as a parameter with value 7. Microsoft HANDLEs are mainly used with %lc, %hw and some direct calls to the Windows API. For further information see Using Microsoft handles.

The winio@ edit control %eb, when used with a grave accent, requires a user-supplied "edit_info" array or TYPE. For 64 bit programs, some of the items in the array become 64 bit addresses so for 64 bit applications users are advised to avoid the array form and use only TYPE(edit_info) which is defined in the standard INCLUDE files (such as clearwin.ins) and the associated modules. For example:.

 INCLUDE <clearwin.ins>
 INTEGER i
 INTEGER(2)::handle,err_code
 TYPE(edit_info) info
 i=winio@('%60.20`eb','*',0,info)
 IF(info%modified > 0)THEN
   i=winio@('%cnSave changes?%2nl%6bt[Yes] %6bt[No]')
   IF(i.EQ.1)THEN
     CALL openw@('myfile.txt',handle,err_code)
     CALL writef@(CCORE1(info%buffer),handle,info%buffer_size,err_code)
   ENDIF
 ENDIF
 END

The function CLEARWIN_INFO@ now returns an INTEGER(KIND=7) value.

A few very old (DBOS) graphics routines have not been ported to 64 bit ClearWin+. Other DBOS routines are available (e.g. DRAW_TEXT@) but now require an explicit interface that can be found in the INCLUDE file called dbos.ins.

The function CPU_CLOCK@ is not available for 64 bit applications and has been replaced by rdtsc_val@...

 INTEGER(KIND=4) FUNCTION RDTSC_VAL@()

The following undocumented Win32 routines have been ported to 64 bits:

  FPOSLONG@, RFPOSLONG@ and FPOS_EOFLONG@.

These are similar to FPOS@, RFPOS@ and FPOS_EOF@ but take INTEGER*8 position arguments. Note that other arguments are INTEGER*2.

SRC

SRC is the Silverfrost Resource Compiler. Use the SRC command line option /r for 64 bit applications and link the resulting .res file (together with the .obj files) via SLINK64. Current experience suggests that using the "default.manifest" in a resource script causes the resulting 64 bit application to fail to load. However, a user-supplied manifest file can improve the appearance. The text of a suitable manifest file is presented below.

RESOURCES

An FTN95 RESOURCES directive can be used at the end of a 64 bit FTN95 main program but it only has effect when used with FTN95 command line options /LINK or /LGO. Otherwise a separate call to SRC is required.

Silverfrost INCLUDE and MOD files

Silverfrost INCLUDE files have been modified so that Microsoft HANDLEs have type INTEGER(KIND=7). Silverfrost MOD files can be used without change provided they are updated to those in a release of of 64 bit FTN95.

Note that user FTN95 MOD files for 64 bit applications may differ from those for 32 bit applications. So FTN95 uses the extension .mod64 for 64 bit MOD files whilst retaining the extension .mod for 32 bit MOD files. The corresponding object files always differ and the respective linker (SLINK or SLINK64) will reject object files of the wrong kind.

By default FTN95 uses the extension .obj for both 64 bit and 32 bit object files. For projects, both Plato and Visual Studio retain the default extension and use a system of sub-folders in order to create executables for different platforms (such as Win32, x64 and .NET) and for differenct configurations (such as Debug, CheckMate and Release).

Users who prefer to build their applications using batch and/or makefiles can adopt a similar sub-folder approach to that used by Plato and Visual Studio. Alternatively, 64 bit object files can be given a different extension (e.g. .o64) by using /BINARY (together with the object file name) on the FTN95 command line. In that way, 64 bit and 32 bit object files could reside in the same folder.

Plato

An associated release of Plato (the Silverfrost integrated development environment) is configured by default to use FTN95 when you select "Release x64" etc. on the main toolbar. Previously this used gFortran. The default can be changed from the Settings dialog.

Plato can launch the 64 bit debugger SDBG64 as an internal process or as an external application.

Redistributing

Like salflibc.dll, salflibc64.dll and clearwin64.dll can be freely redistributed with your applications and DLLs.

Additional notes on porting from 32 bit to 64 bit applications

1) The Fortran Standard stipulates that the SIZE intrinsic function (without a KIND argument) should return an value of default integer type. For FTN95 this is a 32 bit integer unless the default is changed via a command line switch. FTN95 is not standard conforming in this respect unless /SIZE_ISO or /ISO is used on the command line. In other words, SIZE usually provides a 64 bit value. An exception to this rule is that a call to a routine of the the form FUNC(SIZE(...)) is standard conforming. This is because the type of an argument will be critical when used with generic functions. LBOUND and UBOUND are similar but are always standard conforming (by default they return a 32 bit integer).

2) It is possible that there may be some slight loss of precision when porting from 32 bit to 64 bit calculations. This is mainly because some FTN95 32 bit mode floating point calculations actually use hidden extended precision on the way to producing double or single precision results. It is therefore possible that the process of porting to 64 bits may expose a numerically unstable calculation (i.e. one that depends critically on the level of round-off error). In the same way, in extreme cases it is possible that new exceptions may appear at runtime due to floating point overflow. Overflow can occur directly or as the result of dividing by a value that has underflowed to zero. In some cases it is possible to resolve these issues by using a scaling factor in the calculations.

Contents of a clrwin.manifest file...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
    <security>
      <requestedPrivileges>
        <requestedExecutionLevel level="asInvoker" uiAccess="false"/>
      </requestedPrivileges>
    </security>
  </trustInfo>
  <dependency>
    <dependentAssembly> <assemblyIdentity type="Win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0"
                                          processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
    </dependentAssembly>
  </dependency>
</assembly>


Further information about 64 bit FTN95

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

Programs compiled with FTN95 using the /64 option, use the AMD64 instruction set (subsequently adopted by Intel, and referred to as x64 or x86_64) which is almost universally available on modern PC's. This code cannot be mixed with legacy 32-bit code, nor can it access legacy 32-bit DLL's. 64-bit object files must be linked using the new utility SLINK64. This object file format is incompatible with all third-party link utilities.

The default size of INTEGER variables remains unchanged (231-1), so INTEGER*8 (8-byte) variables must be used to index extremely large arrays. These variables are implemented in a more efficient and natural way in 64 bits. Note that some arrays that would not fit in the old 4GB limit may still be indexable using default sized integers, for example a REAL*8 array of 2,000,000,000 elements would occupy nearly 16GB of memory, but could be indexed using default integers.

The main value of 64-bit compilation is that the available address space has increased from 4GB to approximately 1.8 x 1019 bytes. This means that for the foreseeable future (possibly forever), the size of programs will be limited only by the amount of physical memory available on a system.

Arrays that are ALLOCATEd, or which are in COMMON or in MODULEs can exceed the 4GB limit, except that initialised arrays must fit within the .EXE or .DLL file to which they belong, and the the size of these files cannot extend beyond the 4GB limit. This is a Microsoft limit, but is fairly reasonable, since the time needed to load a 4GB file would be excessive.

COMMON blocks and MODULE arrays are allocated dynamically as a program starts in order to enjoy no 4GB restrictions. This is applied to all such storage blocks, because a program may exceed the 4GB limit even though each individual array lies within this limit.

Local arrays are placed on the stack and the default size of this stack is currently 32MB. This size can be adjusted without limit via a command to the linker (SLINK64). Alternatively, users who require a very large local array, can use a COMMON block or MODULE or change to an ALLOCATABLE array.

Variables with the SAVE attribute are currently limited to a total of 1GB of memory. SAVEd variable that are initialised are packed into the EXE or DLL file to which they belong. Since the code can be distributed across multiple DLL's plus an EXE file, the code itself is also not limited to 4GB - although this is not usually a serious concern.

The various 64-bit Windows operating systems provide less than the full 1.8 x 1019 address space, and the size of this space varies somewhat with the available physical memory on the system. Nevertheless, these limits are very generous and will increase as physical memory becomes more plentiful. In part, these limits are due to the fact that the paging mechanism itself requires memory.
For further information see...
https://msdn.microsoft.com/en-us/library/aa366778.aspx

The pair of 64 bit DLLs, SALFLIBC64.DLL and CLEARWIN64.DLL take the place of the 32 bit SALFLIBC.DLL. Currently CLEARWIN64.DLL (which contains much more than ClearWin+) is compiled with Microsoft C++. In the future this may be absorbed into SALFLIBC64.DLL but will remain independent for use with third-party compilers.

Perhaps surprisingly, FTN95.exe and SLINK64.exe are 32-bit executables, and so still require access to SALFLIBC.DLL at compile time.

Note that the extra executables and DLL's that support 64-bit mode can coexist with those that support 32-bit operations because they have different names.

Example

SUBROUTINE sub1(n)
  INTEGER n,localA(1000)
  INTEGER automaticA(n)
  INTEGER,ALLOCATABLE::dynamicA(:)
  ALLOCATE(dynamicA(50))
  automaticA(1) = 42
END SUBROUTINE
PROGRAM arraytest
  CALL sub1(1000)
END PROGRAM

Compile this sample with the options /64 /EXPLIST and examine the resulting .lis file.

Local array localA

On entry to sub1, the assembly instruction "SUB_Q RSP,168" moves the "stack pointer" down the stack by an amount that depends on the size of the array localA. At the end of sub1 the instruction "ADD_Q RSP,168" moves the stack pointer back up the stack by the same amount. If there were to be a call to another routine sub2 within sub1 then the stack pointer would move further down the stack during the call to sub2 and so on.

The required stack size corresponds to the lowest point that is reached by the stack pointer for the various paths through your code.

SLINK64 provides for a default stack size of 32MB. This can be changed via the SLINK64 "stack_size" option where the value is input in hexadecimal form (so the default is 0x2000000). The original upper limit for this value was 4GB. But this limit was effectively removed at v8.50 of FTN95. SLINK64 constructs the header for your application and this conforms to the "Portable Executable" standard. SLINK64 simply uses the stack_size value to set the OptionalHeader.SizeOfStackReserve entry in the "MasterHeader" part.

SLINK64 can use "stack" as an alternative to "stack_size". "stack" takes a decimal value that is the required size in (decimal) megabytes (i.e. millions).

Automatic array automaticA

The allocation of memory for the automatic array autmaticA appears in the assembly instructions as a call to __alloc_pseudo_stack. This allocation operates via a separate stack (which for our purposes is called the "pseudo" stack). The inverse operation is represented by a calls to __return_pseudo_stack_ptr and __set_pseudo_stack_ptr. This "pseudo" stack is automatically initialised via a call to the Windows API function VirtualAlloc. The default size of this stack is half of the size of the available RAM less the size of your program code. This default value can be reduced by using the FTN95 command line option /VSTACK. VirualAlloc provides memory on demand (when committed). The reserved size that is used when initialising does not restrict the amount of RAM that is available for other purposes.

Dynamic array dynamicA

The allocation of memory for the dynamic array dyanamicA appears in the assembly instructions as a call to __ALLOCATE@. This function calls in turn upon the Windows API function HeapAlloc in order to allocate memory from the Windows OS heap. FTN95/SLINK64 provide no limit to the amount of dynamic memory that can be allocated.

Note that the performance on your application might depend on factors such as the size of the available RAM. Using large amounts of memory can lead to the paging in and out of memory from a hard drive resulting in extremely poor response times.


Using the 64 bit linker

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

The SINK64 command line

SLINK64 can be used in 3 ways...

1) It can use a series of commands from a file (recommended). The commands are placed in a file with the .inf or .link suffix, and is invoked thus:

   SLINK64 file.inf

or

   SLINK64 @file.inf

A $ symbol may be used as an alternative to @.

2) It can be used interactively, using the same commands as in (1).

3) It can be used from the command line. This can be derived from the command specifications.
Thus the command lo can be coded on the command line as /lo (obj file)

SLINK64 commands

load(lo) <file> | Loads the file, which must be FTN95/SCC 64-bit object code.
rlo <file> | Loads the file for a DLL with delayed binding. The file must be FTN95/SCC 64-bit object code.
map <file> | Requests a link map, to be placed in the specified file. If the file argument is omitted, the map is placed in a file whose name is derived from the name of the DLL or EXE file being created.
file <exe or dll file> | Completes the linking operation and puts the result in the given file name. Note that the choice of suffix (DLL or EXE) determines the type of file created. Currently all entry points in the code are exported in the case of a DLL.
windows | This command forces the creation of a WINDOWS application, which does not use a console. This is normally used in conjunction with ClearWin+ code.
load(lo) <file.dll> | Uses the entry points in the specified DLL to satisfy calls in the code. The DLL must be avaible at run-time.
load(lo) <file.res> | Loads a resource file created with SRC using the /r switch. This is the same SRC command used in 32-bit mode except that the /r switch must be used.
image_base <hex address> | Specifies the base address for the link (not normally required, and can be overwritten at run time by Windows).
stack_size <hex number> | Specifies the stack size. The default value is 0x2000000 (32 MB).
stack <number_of_millions> | An alternative to stack_size where the value supplied is multiplied by 1 million.
alias <name> <alias> | Sets up an alias to an external name when making a DLL. Note that the names are case sensitive. This was added to enable gFortran to call a DLL built with FTN95. It circumvents the problem that gFortran uses lower case names while FTN95 uses upper case names! It may have other specialised uses.
insert <file> | Provides the path of a text file that is to be included in the script.
help | Prints out abbreviated help information to the console.
quit(q) | Quits SLINK64 without saving anything.

Typical use
SLINK64 is automatically called when /link or /lgo is used on the FTN95 command line. The name of the executable or DLL can be supplied after /link (this is optional for executables but mandatory for DLLs). Also /stack can be included followed by the stack size as a number of megabytes. /map can also be used in this context. The WINAPP directive in the Fortran code creates a Windows application and this directive can optionally be followed by the name of a resource script. Alternatively a resource script can be included by placing the script after the main program by using the RESOURCES directive.

Here are the required SLINK64 commands for five slightly more complicated scenarios:

1) To link a simple program that uses a DLL: The file (say) ExtraDLL.dll is scanned for entry points but it isn't incorporated in MyProgram.exe - so MyProgram.exe will require the DLL somewhere on the path at runtime.

  lo MyProgram.obj
  lo ExtraDLL.dll
  file MyProgram.exe

2) To link a number of files to create a DLL that exports all subroutine/function names:

  lo file1.obj
  lo file2.obj
  lo file3.obj
  file MyLibrary.dll

3) To create a windows program with some ClearWin+ code that uses resources: The resources are prepared by:

   SRC MyResources.rc /r

Then the SLINK64 commands are:

  lo MyProgram.obj
  lo MyResources.res
  windows
  file MyProgram.exe

4) To create a static library of object code:

  lo sub1.obj
  lo sub2.obj
  lo sub3.obj
  file MyStaticLibrary.sl64

Note that files with the suffix .sl64 are static libraries made by SLINK64.

5) To use a static library, simply load it:

  lo main.obj
  lo MyStaticLibrary.sl64
  file result.exe

It is important to load a static library after any code that may reference the code within it, otherwise items that have not been referenced at the time the library is loaded, will not be included in the resultant file. A static library can be used in the creation of a DLL.

If you load a static library into a SLINK64 session that is itself creating a static link library, this will merge the entire contents of the library into the resultant library. It is even possible for both libraries to have the same name - in which case the library is updated with whatever other components are loaded by SLINK64.

Note that SLINK64 can make three different types of files - executable files (.EXE), dynamic link libraries (.DLL) and static libraries (.SL64), and that this is entirely determined by the suffix on the output file specified by the file command. If no suffix is supplied, .EXE is assumed.

Compatibility with SLINK
Most of the commands provided in the 32 bit linker SLINK can also be used with SLINK64. So users who are familiar with SLINK can usually use the same commands with SLINK64. In particular the SLINK commands 'dll', 'archive' and 'addobj', can also be used with SLINK64.


Conditional compilation

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

The constants _WIN32 and _WIN64 are predefined for use with the FTN95 CIF directive. For example:

 CIF(_WIN64)
  k = 64
 CELSE
  k = 32
 CENDIF
 print*, k

will print "64" if /64 (with /fpp) is used on the FTN95 command line.
This is particularly useful with CODE/EDOC blocks. In other contexts it is possible to use an equivalent run-time condition...

 IF(KIND(1_7) == 4)THEN
  k = 64
 ELSE
  k = 32
 ENDIF
 print*, k


Using Microsoft handles

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

Microsoft HANDLEs are addresses that become 64 bit integers rather than 32 bit integers when changing from 32 bit to 64 bit applications. The FTN95 KIND value 7 represents a 32 bit integer in 32 bit applications and a 64 bit integer in 64 bit applications.

Here is a list of ClearWin+ format codes and functions that require modification when changing to 64 bit compilation.

Format codes that output a Microsoft integer(7) handle
%hw handle of current window
%lc handle of previous control
%`cw insert ClearWin window
%`fr handle of current child window
%`og handle of OpenGL context

Format codes that require a Microsoft integer(7) handle as input
%fh use a Windows API font
%`bm draw a bitmap
%dw owner draw graphics
%`mi caption icon
%nw new window
%de disable another window

ClearWin+ functions returning integer(7) values
ADD_GRAPHICS_ICON@
CLEARWIN_INFO@
CREATE_CURSOR@
CREATE_BITMAP@
CREATE_ICON@
CREATE_SHARED_MEMORY@
CREATE_WINDOW@
DOWNLOAD@
GET_BITMAP_DC@
GET_GRAPHICS_DC@
GET_WINDOW_HANDLE@
HANDLE_FROM_CONTROL_NAME@
IDENTIFY_WINDOW_HANDLE@
IMPORT_BMP@
IMPORT_GIF@
IMPORT_PCX@
MAKE_BITMAP@
MAKE_ICON@
MAP_FILE_FOR_READING@
MAP_FILE_FOR_READ_WRITE@
MOVIE_PLAYING@
OPEN_INTERPROCESS_SHAREMEM@
OPEN_WAV_FILE_READ@
OPEN_WAV_FILE_WRITE@
SET_DEFAULT_WINDOW@
START_THREAD@
WINDOWS_INSTANCE@
WINDOW_HANDLE@

ClearWin+ subroutines returning an integer(7) value via its argument
GET_CURRENT_DC@

ClearWin+ subprograms with integer(7) input arguments (the first argument except where stated)
ADD_ACCELERATOR@
ADD_ACCELERATOR1@
ADD_MENU_ITEM@
ATTACH_BITMAP_PALETTE@ (both arguments)
CHANGE_BUTTON_TEXT@
CHANGE_HYPERTEXT@
CHANGE_PEN@
CLEAR_BITMAP@
IDENTIFY_WINDOW_HANDLE@
RELEASE_BITMAP_DC@
REMOVE_ACCELERATOR@
REMOVE_BITMAP@
REMOVE_ICON@
REPLACE_ENHANCED_MENU@
REPLACE_ENHANCED_POPUP_MENU@
RESIZE_WINDOW@
SELECT_GRAPHICS_OBJ_BY_WINDOW@
SELECT_PALETTE@ (second argument)
SET_CONTROL_VISIBILITY@
SET_HIGHLIGHTED@
SET_MAX_LINES@
SET_MOUSE_CURSOR_POSITION@
UPDATE_WINDOW@


Vector processing via SSE/AVX

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

FTN95 /64 creates machine code that makes some use of the SSE and AVX instruction sets (see https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions).

Note that code compiled using /OPTIMISE will not load on a machine that does not support AVX instructions.

Users can also provide direct SSE/AVX support via CODE/EDOC statements in their code.

Four "BLAS" type library routines (DOT_PRODUCT8@,DOT_PRODUCT4@,AXPY8@ and AXPY4@) are also provided and these make direct use of the SSE/AVX instruction sets. In addition, the library function USE_AVX@ can be called in order to instruct these routines to use AVX rather than SSE when the CPU and operating system make this possible.

REAL*8 FUNCTION DOT_PRODUCT8@(x,y,n)
REAL*8 x(n),y(n)
INTEGER*8 n

REAL*4 FUNCTION DOT_PRODUCT4@(x,y,n)
REAL*4 x(n),y(n)
INTEGER*8 n

SUBROUTINE AXPY8@(y,x,n,a)
REAL*8 x(n),y(n),a
INTEGER*8 n
(Y = Y + A*X)

SUBROUTINE AXPY4@(y,x,n,a)
REAL*4 x(n),y(n),a
INTEGER*8 n
(Y = Y + A*X)

INTEGER FUNCTION USE_AVX@(level)
INTEGER level
(Set level = 0 for SSE. Set level = 1 for AVX. The function returns the level that will be used by the current CPU/OS. The default level is 1 which means that AVX will be used when available otherwise SSE. If USE_AVX@(1) is called before an ALLOCATE statement then the resultant addresses will be 32 byte aligned. The USE_AVX@ level must be the same at a corresponding DEALLOCATE.)

For example:

  INTEGER(4),PARAMETER::n=100
  REAL(2) DOT_PRODUCT8@,prod,x(n),y(n)
  INTEGER USE_AVX@,level
  ! x = ...; y = ...
  level   prod = DOT_PRODUCT8@(x,y,n)


Assembler level programming

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

The AMD 64-bit architecture
This architecture was invented by AMD, and was later adopted by by Intel when their own Itanium 64-bit architecture was not received with enthusiasm. Intel use the term x86-64. It is the basis of most modern PCs, and is targeted by FTN95 when the /64 switch is used.

The AMD 64-bit architecture has 16 general purpose integer registers:

RAX, RCX, RDX, RBX, RSP, RBP, RSI, RDI, R8, R9, R10, R11, R12, R13, R14, R15.

The bottom eight registers correspond to the 32-bit register set, and retain some of the same functionality. Thus RSP is the stack pointer and descends as the stack expands, RCX, RSI and RDI are used for string operations just as they are in 32-bits, and RAX is used by convention to return integer function values. RBP does not correspond in function to EBP, however it is given a special function in Silverfrost code (explained later), and should not be modified in normal circumstances.

All these registers hold 64 bits (8 bytes) and can therefore hold a pointer to anywhere in the 64-bit address space.

64-bit programs can access two sets of different floating point registers - the old floating point stack of eight 80-bit registers, and a set of registers designated XMM0 - XMM15, and known as the SSE registers. These registers can hold multiple values simultaneously - four REAL*4 floating point values, or two REAL*8 values. They can also hold integer values. Thus these registers are 16 bytes in width. These registers do not 'know' what data they contain - so it is up to the programmer to keep track. In particular, if you load a REAL*8 value into an XMM register and wish to store it as a REAL*4, you must first use the appropriate conversion instruction.

Strangely, the old coprocessor stack instructions, do offer some functionality that is not present in the newer SSE instruction set - for example SIN and COS can be evaluated in one instruction.

Silverfrost CODE/EDOC conventions
Let us start with a simple executable example of a 64-bit CODE/EDOC sequence that simply sums a vector of REAL*8 values. It is not meant to be optimal because it does not use the parallel execution facilities of the SSE registers.

REAL*8 vec(3),ans
DATA vec/3.0d0,4.0d0,5.0d0/
CALL sum(vec,3,ans)
PRINT*,ans
END

SUBROUTINE sum(vec,n,ans)
INTEGER n
REAL*8 vec,ans
CODE
  MOV_Q RDX,=VEC    ! The '=' denotes a (non-immediate) constant or, as in this case, the address of an argument
  MOV_Q R14,=N      ! Remember all addresses are 64-bit - hence the use of MOV_Q
  MOVSX_Q R14,[R14] ! Instructions and register names are case insensitive
                    ! N is only a 32-bit integer, so it is sign extended to 64 bits
  XORPD XMM0,XMM0   ! This is one way to zeroise an XMM register it does a bitwise exclusive OR
1 ADDSD XMM0,[RDX]
  ADD_Q RDX,8       ! This uses an immediate constant
  DEC_Q R14
  JNE $1            ! Labels are denoted by a '$'
  MOV_Q RCX,=ans
  MOVDQU [RCX],XMM0 ! Store away the accumulated answer in the argument ANS
EDOC
END

This illustrates a variety of points

1) The instructions that operate on the integer registers can operate on 1, 2, 4, or 8 byte operands. These are distinguished by a suffix, thus the MOV instruction takes the forms MOV_B, MOV_H, MOV, MOV_Q.

2) Unlike the 32-bit code/edoc, the register name does not change when the operation operates on a smaller number of bytes.

3) Operations that work on 4 bytes of a register (MOV, ADD, etc) also clear the upper 4 bytes of the register, whereas 2-byte and 1-byte instructions do not change the other bytes of the register. This is a feature of the hardware, not a Silverfrost convention.

4) Labels are prefixed by a '$' when used, just as is the case in 32-bit mode.

5) When accessing a Fortran argument, you need to first access its address (an 8-byte quantity). The notation =N is used to access the address of argument N. The '=' notation can also be used to address a constant in memory, for example:

MOVSD XMM3,=2.0d0

6) The MOVSX_Q instruction sign extends a 32-bit integer to 64-bits. In situations where a number is known to be non-negative. This extension can be obtained for free using point 3 above.

In general a good way to learn to write instructions inside CODE/EDOC is to compile simple code samples with the /EXPLIST option, which will display the instructions generated by the compiler line by line in essentially the same format that you will use.

Referencing COMMON, MODULE, and ALLOCATE'd variables
Because most COMMON blocks are allocated as the program starts up (as are large arrays in MODULE's) the simplest way to access these objects, as well as explicitly ALLOCATE'd arrays, is to take their address before entering the CODE/EDOC. For example:

          COMMON/FRED/alpha,beta(100),gamma
          INTEGER*8 alpha,beta,gamma
          INTEGER*8 addressof_beta
          addressof_beta=loc(beta)
          CODE
            MOV_Q R10,addressof_beta
            MOV_Q [R10+8],42 !This sets beta(2) to the value 42
          EDOC

The 64-bit address space
The 32-bit address space provided a theoretical maximum 232 (4 x 109) addressable bytes. Correspondingly, the 64-bit address space offers a theoretical maximum 2^64 (1.8 x 1019) addressable bytes. This means that, rather like in the early days of the 32-bit architecture, when a typical computer might have vastly less than 232 bytes (4 GB) of memory, the virtual address space is only very sparsely populated. Indeed, the 64-bit virtual address space is so large that it isn't possible to provide page tables to cover the address space. This means that the amount of virtual address space available to a program is determined in a way that depends on the version of Windows in use, and the total amount of main memory on the computer (say 16 GB). This number is still extremely large. However, it is relevant if you use calls to VirtualAlloc to access high memory addresses in an absolute way.

Using the SSE registers for parallel computation
Instructions like MOVDQA will load a pair of REAL*8 numbers into an XMM register. Since these numbers are just bits, the instruction can also be used to move four REAL*4 numbers into an XMM register. However this instruction will fault if the data is not 16-bit aligned. This is problematic because REAL*4 and REAL*8 numbers are aligned wherever possible (EQUIVALENCE can prevent alignment) to 4 and 8 bytes respectively. In practice it turns out that the MOVDQU (which is reputed to be slower than MOVDQA) seems to run at the same speed for aligned data, and only somewhat slower for non-aligned data, but generates no alignment faults. It is also worth reading this discussion about alignment issues: http://lemire.me/blog/2012/05/31/data-alignment-for-speed-myth-or-reality/


Trapping and counting underflows

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

By default, floating point underflows do not raise a runtime exception. An initial call to PERMIT_UNDERFLOWS@(0_2) will cause underflows to be trapped.

SUBROUTINE PERMIT_UNDERFLOW@(opt)
INTEGER(2),INTENT(IN)::opt

Set opt=0 to trap underflows. Other values of opt cause underflows to be enabled.

When underflows are permitted, the total number of underflows can be returned by calling UNDERFLOW_COUNT@ but only after calling SET_SOFTWARE_UNDERFLOWS@(1) which adds a significant overhead and should not be used in production mode.

SUBROUTINE UNDERFLOW_COUNT@(count)
INTEGER,INTENT(OUT)::count

SUBROUTINE SET_SOFTWARE_UNDERFLOWS@(opt)
INTEGER,INTENT(IN)::opt

opt = 0 Use hardware to convert underflows to zero.
opt = 1 Use software to handle underflows - enabling underflow counting.
opt = 2 Treat underflows as errors.

The 32 bit routine MASK_UNDERFLOWS@ is not implemented for 64 bits.


Accessing a gFortran DLL from FTN95

Accessing a third party DLL from FTN95

  • Introduction to 64 bit FTN95
  • Further information about 64 bit FTN95
  • Using slink64 the 64 bit linker
  • Conditional compilation
  • Using Microsoft handles
  • Vector processing via SSE/AVX
  • Assembler level programming
  • Trapping and counting underflows
  • Accessing a third party DLL from FTN95

This example (provided by mecej4 on the Silverfrost Forum) uses a driver main program compiled with FTN95 and calls a routine compiled with gFortran. This returns a vector that contains the elements of an input vector but in reverse order.

The code for the DLL, file rvec.f90:

subroutine reverse_vec(x,y,n)
implicit none
integer, intent(in) :: n
real, dimension(n), intent(in) :: x
real, dimension(n), intent(out) :: y
integer :: i

do i=1,n
  y(n+1-i) = x(i)
end do

return
end subroutine reverse_vec

This is compiled into a DLL using gFortran 6.2-64bit:

gfortran -shared -o rvec.dll rvec.f90

The driver program, tvec.f90 is:

program tvec
implicit none
C_EXTERNAL reverse_vec 'reverse_vec_'
real :: x(4) = [1,2,3,4], y(4)
write(*,*)x
call reverse_vec(x,y,4)
write(*,*)y
end program tvec

Compile and link the driver using FTN95:

ftn95 tvec.f90 /64
slink64 tvec.obj rvec.dll /file:tvec

The DLL is quite big. That is because it has a fixed overhead of having to contain the parts of the gFortran runtime that the DLL routine needs. Also note that the DLL does not have to be produced from Fortran code or be generated using gFortran.


.NET platform

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Using FTN95 in Visual Studio and FTN95 Express

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Visual Studio options

Build Events

Select the Project Options dialog and select Build Events to see the following dialog.

From the tree on the left, select Build Events and Custom Build Steps.

Build Dependencies

Turning this option on will prevent FTN95 for Microsoft Visual Studio .NET from performing the usual checks on module dependencies when a project is built. Files will be built in the order in which they appear in the solution explorer. Checks are still made to determine if a file has to be built if Build is selected. This is done by checking the source file date/time stamp and comparing this with the object file date/time stamp. If the file time is newer than the object time then the file is built.

This option should normally be left as No. Module dependencies should be checked in most circumstances.

Build Events

Build events provide the opportunity to perform user defined tasks whilst the build process is underway. Typical uses would be to copy files to a specific location or run a batch file. If multiple tasks have to be perfomed during an individial build step a batch file should be written and the batch file run. Any syntax that can be used as a single line within a batch file can be used. When specifying a batch file to run, the syntax 'call batchfile.bat' should be used. Any paths specified are relative to the current working directory, this is by default the project directory.

Build events are ran at the specified time. If there is an entry for an event, that event is ran every build unless the specifed event is excluded by use of the option below each event.

If for any reason a process ran by a build event should stop responding, then selecting Cancel from the Build menu will stop the build event and any child processes that may have been started as part of the build event.

Pre-build step

This step is performed before references are updated and before any files are compiled.

Pre-link step

This step is performed after files have been compiled and before the linker is invoked.

Post-build step

This step is performed after the link process has completed.

Excluding Build Events

Build events are normally run if an entry is provided for a specific step. An option is provided under every build event to prevent a step from running. Change this option to Yes to prevent a step from being performed.


Using the debugger in Visual Studio

FTN95 is accompanied by a debugger for both Win32 and .NET platforms that is integrated into Microsoft Visual Studio and FTN95 Express. There is also an external debugger (see Using SDBG) for the Win32 platform.

In order to use the integrated debugger, you must select an appropriate project mode. The standard debugging modes are Debug and Checkmate. Checkmate is normally preferred (to get started using the debugger see A simple Fortran project). In both Debug and Checkmate mode it is recommended that you use the compiler options /FULL_DEBUG (in order to view Fortran PARAMETERs) and /STANDARD_ERROR_REPORTS (so that, when an exception occurs, the debugger stops at the relevant line rather than the exit point).

There are differences between Win32 and .NET which become apparent when debugging. Code that successfully compiles for Win32 may fail under .NET. For example, the type checking of subroutine arguments is stronger for .NET. In particular, the passing of Fortran character variables is more restrictive. Where possible there is something to be said for testing under both Win32 and .NET.

When using the debugger and stepping through code under .NET, entering a subprogram invokes the JIT compiler. In very unusual circumstances, code that successfully compiles with FTN95 may fail to pass the JIT compiler leading to a System.ExecutionEngineException on entry to the subprogram. The root of the problem could be anywhere in the subprogram and it may be necessary to comment out whole sections of the subprogram in order to locate the offending code.


Using the linker in Visual Studio

Command line options

The Silverfrost linker DBK_LINK, DBK_LINK2 or DBK_LINK4 (dependent on the version of the .NET Framework being targeted) is automatically invoked when you build an FTN95 project in Visual Studio or FTN95 Express. The form of the linker command line is hidden from the user but in exceptional circumstances it may be necessary to adopt command line options that are different from those that are supplied by default.

The linker command line options can be changed by using the Property Pages for the project. You can display the pages by clicking with the right mouse button on the name of the project in the Solution Explorer window and by selecting Properties from the popup menu.

Select Linker Options from the tree on the left hand side of the dialog.

The current Configuration and Platform are shown at the top of the dialog and these entries would not normally be changed.

Command line options are shown in tabular form. As you select each item, help information appears in the lowest rectangle.

For an MDL file, select Compiler Options from the left hand pane of this dialog and, in the Output File Type section, select MDL.

References to libraries

If a project makes calls to procedures that are located in a library then it is necessary to configure the linking command for the project so that the library is automatically linked in. Typically the library will take the form of another project within the current solution.

The connection is established by using the References tab within in the Solution Explorer window.

For the purposes of illustration let us create a library project within the current solution. To do this, click with the right mouse button on the name of the solution and select Add, New Project from the popup menu. Suppose this is called Project2. Now make Project2 into a .NET DLL by using the Property Pages. Select Compiler Options from the tree on the left of the Property Pages dialog for Project2 and change the Output File Type from EXE to DLL.

Now right click on the References for Project1

and select Add Reference.

In the dialog, select the Projects tab and double click on Project2. Close the dialog to complete the configuration process.


.NET Programming

FTN95 can create code for either a .NET platform or a Win32 platform. When working from Visual Studio you select the platform when a project is created. The platform can be changed from the Configuration Manager dialog (see A Simple Fortran Project). When working from a command line, by default FTN95 produces code for a Win32 platform whilst the command line switch /CLR selects the .NET platform.

With version 6.35 and above of FTN95 different versions of the .NET Framework can be targeted. To target version 2.0 of the .NET Framework use /CLR along with /CLR_VER 2 and to target version 4.0 of the .NET Framework use /CLR along with /CLR_VER 4. Note that versions 3.0 and 3.5 of the .NET framework are actually extensions to the core of 2.0.

For a Win32 platform, .OBJ files generated by FTN95 are linked using SLINK to produce a .EXE or .DLL file. This process is hidden from the user when working from Visual studio. The call to SLINK is also hidden when /LINK or /LGO are used with FTN95 on a command line.

For a .NET platform, .DBK files are generated by FTN95 and linked using DBK_LINK2 (for version 2 of the .NET Framework) or DBK_LINK4 (for version 4 of the .NET Framework) to produce a .NET assembly (a .EXE or .DLL file) or a .NET module (this is different from a Fortran module). The resulting assembly or module uses an intemediate language that is translated into machine instructions when it is run or installed. The software that does the translation is known as a JIT (Just In Time) compiler and is built into the .NET environment. Each individual .NET platform will have its own JIT compiler.

As of version 6.35 of FTN95, support for version 1.1 of the .NET Framework and DBK_LINK has been removed.

The .NET environment provides a much greater inter-operability between different computer languages and facilitates linking software to the web. It also allows software to be insulated from many of the vagaries of hardware because these matters can now be handled by the JIT compiler.

FTN95 can produce .NET code from existing Fortran programs. These must be either Standard conforming programs or programs that use only Silverfrost Fortran extensions (ClearWin+ programs must be rewritten for .NET). This means that, in many cases, all that you have to do is recompile your existing code in order to create a .NET application.

Targeting different versions of the .NET Framework

To target version 2.0 of the .NET Framework:

Use /CLR and CLR_VER 2 on the command line for FTN95 and use the linker DBK_LINK2. When using Visual Studio 2005 or 2008, version 2.0 of the .NET Framework is targeted by default.

To target version 4.0 of the .NET Framework:

Use /CLR and CLR_VER 4 on the command line for FTN95 and use the linker DBK_LINK4. When using Visual Studio 2010, version 4.0 of the .NET Framework is targeted by default.

Previous users of FTN95 may need to make any changes to build scripts if version 1.1 of the .NET Framework was being targeted using DBK_LINK. Support for version 1.1 of the .NET Framework and DBK_LINK has been removed as version 6.35.


Using the Silverfrost Resource Compiler

The .NET programmer can create Windows applications by including the WINAPP directive before the main program as follows.

WINAPP
PROGRAM Main
....
END PROGRAM Main

Although Silverfrost ClearWin+ can be used to produce Windows applications for Microsoft Windows (Win32) operating systems it is not portable to other operating systems. For portability use can be made of C# forms or Visual Basic .NET forms.

When using any of these approaches, the simplest way to include resources is to use a RESOURCES section in the FTN95 program code (see Resources in FTN95). The alternative is to make an explicit call to the Silverfrost Resource Compiler SRC on a command line.

When SRC is called it creates a permanent compilation of a resource script. With a few exceptions and a few additions, SRC uses the same resource script syntax as the Microsoft Resource Compiler RC. However, most .NET programmers will find that they only use the following kinds of resources:

BITMAP
ICON
CURSOR
IMAGE

Once a resource script has be written, it should be stored in a file with the .RC extension. The resource can then be compiled with a call to SRC of the form:

SRC RESOURCE /R

This command takes the file resource.rc as input and produces an object file called resource.res. The resulting object file can then be linked with other object files using DBK_LINK or DBK_LINK2.


Using the linker from a command line

With version 6.35 and above of FTN95 two versions of DBK_LINK are available, DBK_LINK2 and DBK_LINK4. DBK_LINK2 should be used when targeting version 2.0 (note that versions 3.0 and 3.5 of the .NET framework are actually extensions to the core of 2.0) and DBK_LINK4 should be used when targetting version 4.0 of the .NET Framework. Note that when using DBK_LINK4, the switch /CLR_VER 4 should also have been used on the command line for FTN95. Options on the command line for DBK_LINK2 and DBK_LINK4 are the same.

As of version 6.35, support for version 1.1 of the .NET Framework has been removed and DBK_LINK now only produces an error message indicating 1.1 is no longer supported.

The linking command takes the form:

DBK_LINK2 [options] [<output>.(EXE|DLL|MDL)] <file1>[.DBK] [<file2>[.DBK] ...]

or:

DBK_LINK4 [options] [<output>.(EXE|DLL|MDL)] <file1>[.DBK] [<file2>[.DBK] ...]

[options] can be omitted. A list of options can be obtained by issuing the command

DBK_LINK2 /?

or:

DBK_LINK4 /?

For information about MDL files see Signing an Assembly.

Any options can be followed by the name of the executable or DLL. If this is omitted, the first of the following list of .DBK files is used to provide the name of the executable or DLL. There must be at least one .DBK file in this list.

As an alternative to a .DBK file you can provide one .RES file in the list. A .RES file is output by the Silverfrost Resource Compiler SRC using a standard resouce script as input together with the /R command line switch. If you include a .RES file in this list then you cannot have a RESOURCES section in your FTN95 program (see Resources in FTN95).

In the simplest case a single file called MYPROG.F95 can be separately compiled and linked by using the following two commands:

FTN95 MYPROG /CLR /CLR_VER 2
DBK_LINK2 MYPROG

or:

FTN95 MYPROG /CLR /CLR_VER 4
DBK_LINK4 MYPROG

An alternative form for the linking command is

DBK_LINK2 @filename

or:

DBK_LINK4 @filename

where filename is the name of a file that contains the command line arguments.

Reference

/?
Displays the list of options.
/HELP is an alternative for /?.

/CC:[NameSpace.]ClassName
Specifies a different name for the global class. The default name is the name of the executable or DLL without its extension. This name is case sensitive. The option can also be used on the FTN95 command line when FTN95 is used with /LINK.
e.g. /CC:BloggsInc.SuperLib.Graphics.
/CC is short for /CONTAINING_CLASS.

/NB
Suppresses the Silverfrost copyright message
/NB is short for /NO_BANNER.

/NS
Makes the default base class not 'sealed'.
/NS is short for /NOT_SEALED.

/R:Assembly1[;Assembly2...]
Includes Assembly1 etc.<N> in the list of assemblies used in the search for external routines. e.g. /R:isymwrapper.dll;system.dll
/R is short for /REF.
Note that /REF must not reference a DLL via the global assembly cache (GAC). DLLs in the GAC should have alternative copies in a corresponding "redist" folder. Use the "redist" version and not the GAC version with /REF.

/S
Turns off all messages that are not error messages.
/S is short for /SILENT.

/STACK:<decimal size>
<DECIMAL number>Sets the hardware stack size for the executable. The default is 96MB.
Note that you cannot set the stack size for a DLL. It must be set in the executable that drives the DLL. If this is an FTN95 executable then you can use /STACK on the executable. If it is a C# executable then you can use the Microsoft utility called EditBin to adjust the hardware stack size after C# compilation (in this case the default is 1MB). Stack usage is dominated by local arrays. It can be reduced by making the arrays dynamic (ALLOCATABLE) or by applying the SAVE attribute.

/V:Major[.Minor[.Revision[.Build]]]
Sets the version number for the exe or dll.
e.g. /V:1.0.0.0
/V is short for /VER.


Floating point precision

In the INTEL architecture it is possible to configure the CPU to perform floating-point calculations at various precisions namely 80-bit (REAL(KIND= 3)), 64-bit (DOUBLE PRECISION, REAL(2)), and 32-bit (REAL(1)). Traditionally (Win32) Silverfrost Fortran has selected 80-bit precision for all internal floating-point calculations. When dealing with REAL(1) or DOUBLE PRECISION (REAL(2)) values, this extra internal precision can help to ensure that the least significant bit of a number is accurate. It also means that REAL(3) calculations are possible. The FTN95 compiler option /DREAL forces all single precision variables to DOUBLE PRECISION whilst /XREAL forces all single and double precision variables to REAL(3) (see also /DEFREAL_KIND).

In the .NET architecture Microsoft configure the CPU to operate at 64-bit precision. This can result in slight numerical differences when FTN95 .NET calculations are compared with Win32 calculations. It also means that the REAL(KIND=3) and COMPLEX(KIND=3) types are not available on a .NET platform. Similarly the /XREAL option cannot be used for .NET.


Fortran in an object oriented environment

In Fortran 95, a structure is defined as a derived type. The components of a derived type are data items and a derived type is simply a record consisting of components that are named and have a specified data type. Each instance of a derived type forms a new record.

In object-oriented languages, a structure becomes a class, with the defining feature that it can include methods (i.e. functions) in addition to data. An instance of a class is called an object (this is not to say that .NET objects are always instances of some class). When a method is called, the call is attached to an object and (when necessary) the compiler passes information about the object as an additional argument. In this respect Fortran cannot be described as an object-oriented language.

Again in object-oriented languages, the class data usually varies from one object to another. Such data is called instance data. In many languages, a class can also have static data. Such data is shared by all objects belonging to the class. Furthermore, a call to a method is usually dependent on the instance data and as such is called an instance method. In exceptional cases a method depends only on the static data and can be defined as a static method. In static methods there is no need for an additional argument because the instance data is not used in the call.

The .NET environment is primarily designed for object-oriented languages with the added constraint that all non-local variables must be members of a class. Fortran can be accommodated in this environment by identifying a project with a unique class and by making all the data and all the methods static members of this class (each instance of a derived type takes the form of static data).

When using FTN95 to compile a program for .NET, a class name is provided by the linker DBK_LINK or DBK_LINK2 and all of the data and the routines are placed in this class. By default this name is the name of the assembly (i.e. the executable or DLL) with the extension removed. This name is case sensitive. The DBK_LINK or DBK_LINK2 command line switch /CONTAINING_CLASS allows you to provide a different name. Similarly, when /LINK is used on the FTN95 command line and FTN95 calls DBK_LINK or DBK_LINK2 implicitly, the FTN95 command line switch /CONTAINING_CLASS can be used to provide an alternative name. Typically this name will contain a namespace component as well as a class name. For example:

FTN95 MYCODE /CLR /LINK /CONTAING_CLASS BloggsManufacturing.DesignRoutines

This creates the namespace 'BloggsManufacturing', the class 'DesignRoutines' within it, and makes all the Fortran routines into static methods of this class. Nested namespaces can also be specified using several dots in the name.

The name of the class becomes significant if the resulting library is called from other .NET languages, such as C#. A single Fortran project can only contain code for one class and the linker DBK_LINK or DBK_LINK2 can only be used to link code that is in the same class. If you required more than one class then you must have a separate project for each class.

Fortran data that appears in a MODULE or COMMON block is also defined as static data. This means for example that an executable and a library cannot share this kind of data. This is analogous to the situation on a Win32 platform where (by default) a Fortran executable cannot share this kind of data with a DLL.

Note that the structure of a .NET assembly can be displayed using the Microsoft ILDASM utility. This expands an assembly as a tree of information and it enables you to explore the namespaces and class names used in your code. It also enables you to study the intermediate language (IL) code generated by FTN95. However, in many cases several IL instructions are converted by the JIT compiler into just one native instruction. This means that the end result is often more efficient than the IL code implies.

The IL code is also listed by FTN95 when /EXPLIST is used on the command line. This listing is usually easier to follow because it is presented together with the Fortran code used to generate it. However, it does not specify where COMMON variables are stored.


Calling Fortran from other .NET languages

In Visual Studio a solution is formed from several projects. For example, a solution might contain a project to create an executable and another to create a library that is used by the executable. It is convenient to use the terms solution and project in this sense even though you may not be using Visual Studio.

The code for a project will usually be written in one programming language but a different language might be used for another project in the solution. For example a library written in Fortran might be called from an executable written in C#.

However, when mixing languages in this way, it is important to understand that not all Fortran types have exact equivalents inside .NET. For example, the Fortran CHARACTER type, with its fixed size and blank padding rules is not the same as a .NET string (which incidently also caters for UNICODE characters). Also Fortran multi-dimensional arrays are stored in a different order (i.e. column major order) and Fortran arrays are not necessarily zero based.

If your intention is to have a main program written in (say) C# and call an FTN95 DLL then it is important you tag the C# application as 32-bit. If you do not do this then on 64-bit operating systems the C# application may get JIT compiled in 64-bit mode. When a call is made to the FTN95 DLL then it will fail to JIT because it will force 32-bit mode. The result will be a program ending exception.

The linker DBK_LINK or DBK_LINK2 is used to link code produced by one or more calls to the FTN95 compiler. Calls to DBK_LINK or DBK_LINK2 are made a) during Visual Studio build processes, b) when DBK_LINK or DBK_LINK2 is used on a command line, and c) when FTN95 is called using /LINK or /LGO. DBK_LINK creates a file which is known as an assembly. The assembly file can have a .EXE or .DLL extension, and in the latter case it can be called by other software.

When you want a particular FTN95 routine to be callable from other .NET languages you can include an ASSEMBLY_INTERFACE directive in the FTN95 code. This directs the compiler to create a stub that can be used in a call to the routine from another language. The purpose of the stub is to resolve the differences that arise when a Fortran type is not compatible with its .NET equivalent. For example:

ASSEMBLY_INTERFACE(NAME="MyCalculation")

The resulting Fortran name for the routine will use only upper case letters (even when lower case letters are used in the code). In contrast, the external name (MyCalculation) is case sensitive.

Consider the following example:

SUBROUTINE CALC(A,B,C)
INTEGER A
CHARACTER(LEN= *)B
REAL(KIND=2)C(0:,0:)
ASSEMBLY_INTERFACE(NAME="MyCalc")

and suppose that the name of the resulting DLL is MyLib.dll.

CALC would be callable by the following C# fragment:

int a=1;
string b="xyz";
double[,]c={{1.0,2.0},{3.0,4.0},{5.0,6.0}};
MyLib.MyCalc(a,b,c);

You can use "Calc" instead of "MyCalc" as the interface name when calling from C# but not when calling from Visual Basic.

For Visual Basic, the interface name, when converted to upper case, must not be the same as the Fortran name of the subprogram.

You can think of the name MyCalc as a synonym for CALC but when MyCalc is called from other .NET languages, the following argument transformations are performed:

1. Fortran arrays are mapped to .NET arrays. The (column major) ordering is not changed because this transformation would be expensive for large arrays. Your code must allow for this difference. Thus the C# array element c[1,2] becomes C(2,1) in Fortran. Arrays are passed by reference.

2. Fortran CHARACTERs are mapped to System.String objects and passed by value (this means that changes made to a dummy argument are not passed back to the actual argument at the point of call).

3. Scalar INTEGER and REAL values are passed by value unless INTENT(OUT) or INTENT(INOUT) is used in which case the argument is passed by reference.

4. All other arguments, including objects (i.e. instances of a class, see .NET Objects), are passed by reference.

These transformations greatly simplify the calling of Fortran from other .NET languages.

The use of an ASSEMBLY_INTERFACE is not necessary when all of the arguments are scalar INTEGERs or REALs. However, the call (from C# say) must stipulate that all of the arguments are passed as 'unsafe' pointer types (using 'fixed' if necessary) and the name of the routine (in C#) must not use lower case letters.

It is simpler if you use an array index with a lower bound of zero when you declare Fortran array arguments. This makes them consistent with C# arrays. However, you can use a different lower bound. For example, if you declared a two-dimensional Fortran array with both indexes starting at 1 by using say C(:,:), then the C# element c[0,1] would map to C(2,1) (i.e. both indexes are increased by one and their order is reversed).

A C# string is converted into the corresponding Fortran CHARACTER string and any Unicode characters that cannot be represented in ASCII form are replaced according to the rules of System.Text.Encoding.Default. Any changes made to the string from within the Fortran code are not reflected back to the C# caller.

.NET objects (such as .NET strings and .NET arrays) are passed to your Fortran code without transformation. Passing objects avoids the overhead incurred when using the standard transformations and the resulting flexibilty can sometimes be used to resolve complex interfacing problems.

Note that, in a FTN95 program, you cannot declare a Fortran array whose elements are .NET objects. Such arrays can only be passed as .NET arrays from another non-Fortran assembly.

You can use the FTN95 complex number classes in C# and Visual Basic .NET. These are defined in ftn95lib.dll with the namespace Salford.Fortran. The class names are Complex8 (for single precision) and Complex16 (for double precision) and the public data members in both classes are called Real and Imaginary. Objects of these types can be passed to and from a Fortran DLL. Here is some sample C# code.

Salford.Fortran.Complex16 x = new Salford.Fortran.Complex16(1.0,1.0);
MessageBox.Show(x.ToString());


.NET Objects

In addition to the standard Fortran types described in Calling Fortran from other .NET languages, the .NET environment provides for what are called objects. An object is simply an instance of a class. .NET objects are similar in some respects to instances of Fortran derived types.

In what follows, readers who are familiar with Fortran 95 derived types and pointers may find it helpful to draw an analogy with the following fragment of code.

!Stage 1: Define a derived type.
TYPE(Circle)
 INTEGER x,y,r
END TYPE
!Stage 2: Declare a Fortran pointer to a Circle.
TYPE(Circle),POINTER::C
!Stage 3: Allocate memory and use the TYPE constructor.
ALLOCATE(C)
C=Circle(1,1,1)

FTN95 extends standard Fortran in order to enable you declare and use .NET objects. Currently it is not possible to define a class in the FTN95 code (i.e. there is no equivalent of Stage 1 for classes). The class must be defined externally in another (non-Fortran) assembly.

The FTN95 keyword OBJECT is used to declare an alias for an object. For example:

OBJECT("MySpace.TestClass") ALPHA

This is equivalent to Stage 2 and declares a variable called ALPHA, that will be used as an alias for a .NET object. The alias is as yet undefined (i.e. the variable is not yet ASSOCIATED with an object). The class (i.e. the structure of the object) is defined in another assembly (typically created using C#). The name of the class is TestClass and it is contained in the namespace MySpace. Namespaces and classes can be nested, so the string can contain several dot characters.

When you declare an alias for an object, the compiler must obtain a definition for its class from the assembly file in which the class is defined. This is automatic if the class is a system class (e.g. System.Console). In other cases names of assembly files must be given to the compiler as LIBRARY directives or by using the /LIBRARY command line option. The compiler will report an error if it cannot find a definition for the class.

Sample code is provided that illustrates how to use .NET classes. The Fortran Calculator sample illustrates calling Fortran code from C#, along with the Mandelbrot example.

See also Manipulating .NET objects.


Manipulating .NET objects

In what follows, readers who are familiar with Fortran 95 derived types and pointers may find it helpful to draw an analogy with the following fragment of code.

!Stage 1: Define a derived type.
TYPE(Circle)
 INTEGER x,y,r
END TYPE
!Stage 2: Declare a Fortran pointer to a Circle.
TYPE(Circle),POINTER::C
!Stage 3: Allocate memory and use the TYPE constructor.
ALLOCATE(C)
C=Circle(1,1,1)

In FTN95 code, the keyword OBJECT is used to declare an alias for an object whose class is defined externally (see .NET Objects). This is equivalent to Stage 2 in the above fragment. The use of OBJECT does not allocate memory for the object's data.

Typically classes are accompanied by one or more methods called constructors that initialise the object's data and define its initial state. In FTN95 the keyword NEW@ is used to allocate memory for an object's data and to call one of its constructors.

For example:

OBJECT("System.Object") OBJ
OBJ=NEW@("System.Object")

Using NEW@ performs the equivalent of Stage 3 in the above fragment. If a constructor takes arguments, these are added to the call to NEW@ after the class name of the .NET object ("System.Object" in this example).

Note that the use of OBJECT declares a variable of Fortran pointer type but leaves it undefined. Using NEW@ is equivalent to using ALLOCATE (i.e. a pointer assignment) followed by a call to the constructor.

As in this example, the class name that is used in NEW@ is usually the same as the class name that is used in OBJECT(...). However, .NET objects exist in an inheritance hierarchy and as a result the class name in NEW@ can be one that is derived from that used in OBJECT(...). Thus, the following code fragment is legal:

OBJECT("System.Object") OBJ
OBJ=NEW@("System.String")

because "System.String" is derived from "System.Object". After the call to NEW@, OBJ is an alias for a .NET string object.

The keyword CAST@ is used when creating an alternative alias for a .NET object as illustrated by the following fragment.

OBJECT("System.Object") OBJ
OBJECT("System.String") STR
OBJ=NEW@("System.String")
STR=CAST@(OBJ,"System.String")

The assignment in the last line is a pointer assignment that makes STR an alternative alias for OBJ (memory for the object has been allocated by using NEW@ on the line before). In a Standard Fortran context the assignment would take the form STR= >OBJ. STR and OBJ are alternative names for the same object in memory.

N.B. Although the above fragment illustrates a principle, it does not represent a practical method for accessing .NET strings. For further information see .NET string type.

An exception is raised (at runtime) if you use CAST@ with incompatible arguments (e.g. if "System.String" was not derived from "System.Object").

NEW@ can be called in the context of a call to another function. For example,

LIBRARY "MyLib.dll"
LIBRARY "System.Windows.Forms.dll"
ASSEMBLY_EXTERNAL(NAME="System.Windows.Forms.Application.Run") MyRun
CALL MyRun(NEW@("MyLib.MyForm"))

In this code MyRun is an alias for an overloaded static method. In one overloaded case, it can take a single argument that is a reference to a Microsoft Form. MyForm is assumed to be a class defined in MyLib that is derived from the Form class. NEW@ can be used in this context despite the fact that the argument does not provide a direct type match. This is because FTN95 type matching permits a match with a class that is derived from the given argument class.

In standard Fortran, P%NAME selects the data member called NAME for an instance P of a derived type. In FTN95, the '%' operator can also be used to access data members of .NET objects assuming that such members have meaningful Fortran types. For example:

OBJECT("System.String") STR
STR=NEW@("System.String","alpha")
PRINT*,STR%Length
END

In this case using a second string argument for NEW@ calls a constructor that initialises the string. Length is a data member of System.String so the value 5 (the length of "alpha") is printed. In fact Length is an example of a particular kind of data member that is called a property. A property is not accessed directly but via a method belonging to the class and as a result can be made to be read-only or write-only. In this case Length is read-only and the following fragment would fail to compile

STR%Length=7

If a simple (non-property) data member of a .NET object is passed as an argument to a routine then (since it is passed by reference) it can be used and/or altered by the routine. However, a property is first evaluated and stored locally before the address of the local store is passed by reference. Consider for example:

CALL FOO(STR%Length)

This code will compile and the routine FOO could both use and alter the associated dummy argument. However, any change will not be reflected back to STR. In other words the argument is effectively passed by value. See .NET string type for a much easier way to use .NET strings.

It is important to realise that Fortran variables are not case-sensitive. All names are converted by the compiler to upper case (only characters within quoted strings are case-sensitive). Thus STR%Length is exactly the same as STR%LENGTH. The compiler uses a case-insensitive search when it looks for a member of a .NET class. This is usually adequate, but an alternative syntax is provided to cater for classes that contain members that differ only by case. The alternative uses a quoted string. For example, STR%'Length' or STR%"Length". Only literal strings are permitted in this context. Character expressions and parameters cannot be used.

.NET classes can have both private and public data members and only public data members can be accessed directly from outside of the class (private members can only be accessed by and via the given methods of the class).


Calling .NET methods from Fortran

All .NET methods are contained in classes and to call a method from FTN95 code you must declare it using the FTN95 keyword ASSEMBLY_EXTERNAL. For example,

ASSEMBLY_EXTERNAL(NAME="System.Console.WriteLine") WRITELINE

An FTN95 LIBRARY directive must be included in the code to specify the relevant library. For example, Console.WriteLine is a static method contained in System.dll, and the directive takes the form:

LIBRARY "System.dll"

Within Microsoft Visual Studio .NET references may be added to a solution using the References node in the Solution Explorer as with other .NET projects. To add a reference simply right click the References node and choose Add Reference.

WRITELINE is thus a name for the System.Console.WriteLine method and can be called in the usual manner:

CALL WRITELINE("This will be output to the console")

This approach is appropriate for all static methods but instance methods require a refinement. Before the call you must create an object (i.e. an instance of the class) by using the keywords OBJECT and NEW@ as follows:

ASSEMBLY_EXTERNAL(NAME="System.Net.WebClient.DownloadFile") DOWNLOADFILE
OBJECT("System.Net.WebClient") WEBCLIENT
WEBCLIENT = NEW@("System.Net.WebClient")

The arguments for DOWNLOADFILE in the FTN95 code are the same as those for the method DownloadFile but in Fortran the name of the object is added as the first argument:

CALL DOWNLOADFILE(WEBCLIENT, url, file)

If a .NET method returns a value that can be interpreted as a Fortran INTEGER or REAL value then it can be used in the usual way in an expression or assignment statement. For example the following program uses the method IndexOf from the System.String class and prints the value 2 which is the zero-based index of "ph" in the string "alpha".

ASSEMBLY_EXTERNAL(NAME="System.String.IndexOf")
                        INDEXOF
OBJECT("System.String") STR,SUBSTR
STR=NEW@("System.String","alpha")
SUBSTR=NEW@("System.String","ph")
PRINT*,INDEXOF(STR,SUBSTR)
END

Note that, for clarity, the Fortran aliases above use only upper case letters. However, in your code you may prefer to use mixed case aliases that reflect the external name (FTN95, like all Fortran compilers, converts lower case names to upper case).


Garbage collection

All .NET objects are allocated in memory that is controlled by the system garbage collector. This means that C# programmers do not need to delete (DEALLOCATE) objects that they have created. When the memory allocated to a program runs low, the garbage collector determines those objects that are redundant and reclaims the associated memory. The garbage collector occasionally compacts memory to reduce excessive fragmentation. This involves adjusting pointer information and is invisible to the user.

Automatic garbage collection is not feasible with older languages like Fortran. This means that you must use ALLOCATE and DEALLOCATE in accordance with the Fortran 95 standard. In other words, in order to avoid memory leakage, every ALLOCATE must have a corresponding DEALLOCATE unless,

1) the ALLOCATEd variable is local to a routine and is not SAVEd and is not a TARGET (this is because Fortran 95 provides for automatic deallocation when a local variable goes out of scope) or

2) the execution of the program is about to terminate.

Note also that, although NEW@ is used to ALLOCATE memory for a .NET object, there is no equivalent (for objects) to DEALLOCATE. This means that in cases where deallocation is necessary, you must write your code in such a way as to enable the system garbage collector to do the deallocation automatically. Automatic garbage collection will only take place if the variable is local to a routine or is stored in a module (all COMMON/EQUIVALENCE variables, all arrays, and all ALLOCATED non-local variables are placed in memory that is not subject to garbage collection).

FTN95 uses .NET objects to implement Fortran input and output (and these objects are subject to automatic garbage collection). Otherwise FTN95 does not use .NET garbage collection except for OBJECTs created by the user within the Fortran program.


F2003 extensions

The following new features in the Fortran 2003 standard are available in FTN95. These extensions are automatically available when using FTN95. Use /-F2K in order to switch off the extensions.

1. TYPE_ALIAS

2. Square brackets in array constructors, for example

INTEGER :: a(5) = [1, 2, 3, 4, 5]

3. The command line intrinsics GET_COMMAND, COMMAND_ARGUMENT_COUNT, and GET_COMMAND_ARGUMENT.

4. Names of length up to 63 characters are permitted.

For .NET, note also:

The Fortran 2003 use of TYPE_ALIAS is extended in FTN95 to include .NET OBJECTs. For example:

TYPE_ALIAS decimal => OBJECT('System.Decimal')
TYPE(decimal) :: var1, var2


.NET arrays

A .NET array (DNA) consists of a header and a block of memory to hold the elements of the array. The header contains information about the array such as the rank and bounds for each dimension. This means that it is not possible to pass part of a DNA to another routine and treat this as another array because the head would be missing or invalid.

Fortran constructions such as EQUIVALENCEs that involve arrays can not be implemented using DNAs. Furthermore, DNAs are considerably less efficient to access than normal Fortran arrays, partly because the array bounds are always checked. For this reason, despite the advent of .NET, no fundamental change has been made in FTN95 with respect to the way in which Fortran arrays are implemented. They are implemented using portions of non-garbage collected memory just as on a Win32 platform.

FTN95 prevents you from declaring arrays whose elements are .NET objects because such objects would not be found by the garbage collector. However, it is possible to manipulate .NET arrays directly. They are objects in their own right and can be declared using the OBJECT keyword. For example:

OBJECT("System.String[]") STR1
OBJECT("System.String[,]") STR2

The variable STR1 is a one-dimensional DNA of strings, whilst STR2 is a corresponding two-dimensional DNA. Like all other objects, you must use NEW@ to allocate memory for a DNA before using it:

STR1=NEW@("System.String[]",10)
STR2=NEW@("System.String[]",10,20)

After executing these two lines of code, STR1 refers to a DNA with one index that is in the range 0:9 (note carefully the zero lower bound) and STR2 refers to a DNA with two indexes in the range (0:9,0:19). It is now possible to access these arrays using subscript syntax:

STR1(k)=mystr
STR2(k,m)="FRED"//STR1(j)

mystr is either a Fortran character string or a DNA. Objects stored in such arrays will be safe if a garbage collection is required.

You cannot use the Fortran substring syntax with a DNA. Also when you pass an element of a DNA to a routine, you will not have implicit access to subsequent elements as is sometimes the case with normal Fortran arrays.

It is important to note that DNAs can be created externally in which case NEW@ will not be used to create the array. For example, a DNA could be a member of a class. In which case the array will be created externally when NEW@ is used for an object of this containing class. Alternatively you might receive a .NET object as an argument in a routine and this object might contain an existing DNA.

See Object and string arrays for an easier, though less fexible way to access .NET arrays.


.NET string type

FTN95 for .NET provides a STRING type as an extension to standard Fortran. The keyword STRING is an alias for OBJECT('System.String') and all the features described below will also work on variables declared using the corresponding OBJECT syntax.

STRING can be used in much the same way as the standard CHARACTER type but represents a varying length string. STRING is similar to the ISO standard TYPE(ISO_VARYING_STRING) but it uses garbage collection and is UNICODE rather than ASCII.

When translating STRING objects to Fortran CHARACTER type, remember that not all UNICODE characters can be converted to ASCII. The current thread locale (set of conversion rules) is used for translation.

The standard intrinsic functions CHAR and LEN are extended to allow STRING type arguments. Although the standard intrinsic CHAR always returns a single character, when the extended CHAR is called with a STRING argument it returns a Fortran character string that is just large enough to hold the argument.

The FTN95 intrinsic function STRING@ is used to convert a value of almost any type into a STRING:

a) When you supply an argument that is a Fortran character string, STRING@ returns the string that includes any trailing spaces used for padding. Trailing spaces can be removed by first using TRIM.

b) For all other types STRING@ uses the ToString method of the class System.String to do the conversion. This means that numbers are converted to STRINGs using default .NET formats and this will be different from the result of using a list directed Fortran WRITE statement. Alternatively a WRITE statement can be used to convert a number to a Fortran string before using STRING@ to convert the result.

c) For a COMPLEX argument the ToString method is called on the real and imaginary parts.

d) Conversion from LOGICAL is not implemented but a construction of the form STRING@(MERGE('T' , 'F', value<EXP>)) may be appropriate.

The substring and concatenation operators (e.g. S(1:10)//'Hello') can be applied to STRING variables. Note that mixed STRING and CHARACTER expressions can be concatenated and assigned. FTN95 automatically promotes all CHARACTER objects to STRING before the concatenation/assignment. This means that these operators follow the System.String semantics rather than the CHARACTER ones (i.e. there is no space extension or truncation of any results.). Explicitly casting the STRING arguments using the extended CHAR function allows the standard Fortran semantics to be used with concatenation (e.g. CHAR(S(1:10))//'Hello').

Note that the STRING type is an immutable type. For example, the following is illegal:

STRING :: s
s = '123456'
s(1:4) = 'abcd'

The last line should be replaced by:

s = 'abcd' // s(5:)

Here is an example that uses the STRING type:

PROGRAM test
STRING :: s
s = 'Hello, everyone'
s = s(1:7) // 'World.'
CALL foo(CHAR(s), LEN(s))
END PROGRAM test

SUBROUTINE foo(c, j)
CHARACTER(LEN=*) :: c
INTEGER :: j
PRINT *, c, j, 1.0
CALL bar(STRING@(c), STRING@(j), STRING@(1.0, 'f'))
END SUBROUTINE foo

SUBROUTINE bar(s, t, u)
STRING :: s, t, u
PRINT '(3(1X, A))', CHAR(s), CHAR(t), CHAR(u)
END SUBROUTINE bar

This produces the output:

Hello, World. 13 1.00000
Hello, World. 13 1.00

Note that in STRING@(1.0,'f') there is a second argument that specifies a floating point format, otherwise the .NET Framework would have used "1" rather than "1.00" to represent 1.0. This also applies to COMPLEX arguments for STRING@. See the .NET Framework documentation for a complete list of possible formats.

When using COMPLEX numbers and an explicit format string, you must specify the real and imaginary parts using '{0}' and '{1}' respectively. For example, to force the printing of a decimal point, use '({0:f}, {1:f})'. This contrasts with the REAL case above which does not use curly brackets.

Note also that you must have explicit casts (using the CHAR intrinsic) to WRITE or PRINT a STRING. This conversion is read-only, so you cannot directly READ a STRING for example. To READ a STRING you must first READ it into a temporary CHARACTER string and then convert this to a STRING.

STRING@ is very useful for accessing values for .NET types that are not supported by FTN95, such as OBJECT('System.Decimal'). However, when converting to a CHARACTER string, it is better to avoid constructs like:

chr = CHAR(STRING@(obj))

Code generation is improved if you use a temporary STRING variable instead as follows:

STRING :: tmp
tmp = STRING@(obj)
chr = CHAR(tmp)

After this assignment, the expression (STRING@(chr) == tmp) will not necessarily evaluate to TRUE because tmp is a UNICODE string whilst chr is an ASCII string.

Limitations of the STRING type
1. FTN95 uses one-based indexing for the substring operator, but the System.String methods use zero-based indexing.

2. You cannot use DATA, BLOCK DATA or an initialisation expression to initialise a STRING object.

3. There is no intrinsic or I/O support for STRING apart from LEN and CHAR.

4. FTN95 passes all STRING arguments as if they were declared in C# as "ref string".


Object and string arrays

There is limited support for arrays of .NET objects declared using OBJECT or STRING. These differ from stanard Fortran arrays in that they are objects allocated on the managed (garbage collected) heap. These arrays must be declared with a zero lower bound on all dimensions. For example:

STRING :: s(0:9, 0:9)
OBJECT('System.Decimal') :: c(0:n)

This is exactly equivalent to:

OBJECT('System.String[,]') :: s
OBJECT('System.Decimal[]') :: c
s = NEW@('System.String[,]', 10, 10)
c = NEW@('System.Decimal[]', n+1)

An OBJECT array can be passed as an argument to a subroutine and (like a standard Fortran array) it can can take an assumed size or an assumed shape provided that the lower bounds are declared to be zero. An array of OBJECTs can also be used as an automatic array in a subroutine.

Note that

INTEGER(KIND=3) :: a(0:9)

and

OBJECT('System.Int32') :: a(0:9)

are equivalent arrays of 32-bit integers but they do not take the same form and are not handled in the same way. For a better performance, standard Fortran INTEGER arrays should be used whenever possible.

Limitations of OBJECT arrays
OBJECT arrays currently cannot appear in a MODULE, or in a COMMON block or have the SAVE attribute (either explicitly or implicitly via a DATA statement or variable initialisation).

Currently you cannot directly use the POINTER or ALLOCATABLE attribute in a declaration. For this you must use the first part of the equivalent syntax shown above. For example:

OBJECT('System.String[,]') :: s

declares a pointer to a two dimensional array of STRINGs.

Note that OBJECT arrays are allocated on the managed heap so there is no need to DEALLOCATE any variable that has been allocated using NEW@ (either implicitly or explicitly).

As yet OBJECT arrays cannot appear in array expressions (e.g. array-sections and whole-array expressions) or as whole-array arguments to any INTRINSIC (e.g. MATMUL and MAXVAL).


Derived types

A Fortran derived type (defined using a TYPE statement) is like a .NET object in some respects, but with important differences. In particular, a Fortran derived type can contain Fortran arrays or pointers to arrays. You can also have Fortran arrays whose elements are of a derived type.

As an extension to standard Fortran, FTN95 allows you to include an OBJECT (i.e. a Fortran pointer to a .NET object) as a component of a derived type with the following restrictions.

1. Variables that are based on derived types cannot be guaranteed to be scanned during garbage collection . For this reason, any derived type that includes an OBJECT is subject to the same restrictions as OBJECTs themselves. Thus, when automatic garbage collection is required to avoid memory leakage, variables of these derived types must be local to a routine or be stored in a module (for a global array you can use a .NET array instead).

2. Furthermore, a derived type that includes an OBJECT cannot include a Fortran array (or a pointer to a Fortran array) at the same time. This is because a derived type containing one or more OBJECT declarations is effectively a .NET object.


Threads

The .NET framework supports threads. This means that it is possible to have a program that is effectively doing several things at the same time. Multiple threads can be very useful but programs with threads are usually much more difficult to debug. Consequently they should be used sparingly.

When a program contains two or more threads its execution is analogous to the situation where multiple programs are running simultaneously. However the various threads share the same address space. On a typical single processor machine each active thread runs for a short period of time until it is swapped out to permit another thread to run. This can be useful, for example, when you want to control a GUI interface or access data over the Internet whilst a long numeric calculation is proceeding. Using threads in such circumstances can make your program much more responsive to user interaction.

Threading is also the key to exploiting the power of multi-processor machines. When a machine has several processors (typically two) several threads can literally run simultaneously - true parallel processing. This happens automatically if several processors are available.

Although it is possible to create and start a thread using calls to the .NET framework, FTN95 provides a shortcut:

SUBROUTINE CREATE_THREAD@(SUB,ICODE)
EXTERNAL SUB
INTEGER ICODE

SUB is the routine in your code that is called to start the thread. SUB is presented in the form of a subroutine that accepts one integer argument. The value that is used in the resulting call to SUB is the value of ICODE. Thus you can choose to start several threads using the same subroutine but with different values of ICODE to distinguish the cases. Here is a simple example of code to start a thread:

EXTERNAL foo
CALL CREATE_THREAD@(foo,42)
PRINT*,'Finishing main program.'
END

SUBROUTINE foo(m)
INTEGER m
PRINT*,'In foo ',m
END

In this example the two PRINT statements may execute in either order and this will typically vary from one run to another. This reflects the fact that the threads in your program run asynchronously. This program will continue to execute until all threads have terminated.

The first call to CREATE_THREAD@ in a program enables re-entrant Fortran I/O so that I/O on one thread does not cause a fault when it coincides with I/O on another thread. If you use I/O in several threads you must use different unit numbers unless you use the LOCK statement to prevent a swap before the I/O statement has finished. For example:

LOCK
PRINT*,........
END LOCK

If you use threads you must design your program in such a way that each thread can run independently. Moreover, it is important to note that a program that contain multiple threads might contain bugs that only show up intermittently (because the way in which threads interact can vary from one run to another). For this reason programs with multiple threads can be very hard to debug.

As an alternative to CREATE_THREAD@, the FTN95 routine CREATE_THREAD1@ provides for an additional argument that returns a handle for the thread. This handle can be used in calls to System.Threading.Thread methods and these enable the user to interact with a thread that is running. For example, a call can be made to System.Threading.Thread.Join in order to wait for a thread to terminate.

Here is the form of the interface for CREATE_THREAD1@:

SUBROUTINE CREATE_THREAD1@(SUB,ICODE,NEW_THREAD)
EXTERNAL::SUB
INTEGER::ICODE
OBJECT("System.Threading.Thread") NEW_THREAD

System.Threading.Thread.Join is a static method (see Calling .NET methods from Fortran) so it can be called using, for example,

ASSEMBLY_EXTERNAL(NAME="System.Threading.Thread.Join")T_JOIN
. . .
CALL T_JOIN(NEW_THREAD)

Here is an example that illustrates the use of CREATE_THREAD1@:

EXTERNAL foo
ASSEMBLY_EXTERNAL(NAME="System.Threading.Thread.Join") T_JOIN
OBJECT("System.Threading.Thread") NEW_THREAD
CALL CREATE_THREAD1@(foo,42,NEW_THREAD)
!Do some processing...
CALL T_JOIN(NEW_THREAD)
PRINT*,'Finishing main program.'
END

SUBROUTINE foo(m)
INTEGER m
PRINT*,'In foo ',m
END

In this example the output from the subroutine will appear before that from the main program.

Other thread methods are provided in addition to Join. These are described in the .NET documentation.

When using the .NET framework there are certain overheads that are incurred by multi-threaded programs. Because of this the linker DBK_LINK or DBK_LINK2 assumes by default that the code does not use multi-threading. The DBK_LINK or DBK_LINK2 command line option /MULTI_THREADED must be used to inform the linker that the code makes calls to either CREATE_THREAD@ or CREATE_THREAD1@. The same option can be employed with FTN95 when it is used with /LINK. If you do not use this option then an exception will be raised at runtime when either of these routines is called. You must also use the option /MULTI_THREADED when you create a thread directly using System.Threading.Thread methods, otherwise the resulting behaviour is undefined. This option is also required when a library is created if it contains a routine that is called on more than one thread.

If you need to start a number of threads you can used the /STACK option to reduce the default stack size per thread. /STACK is a DBK_LINK command line switch. It is also available on the FTN95 command line for use with /LINK or /LGO. The given (decimal) size of the stack refers to the number of bytes of virtual storage (i.e. address space) allocated to a single threaded program and to each thread of a multi-threaded program.

By default the stack size is set to 96 megabytes (this is over 100 million bytes; the default KIND for an INTEGER value and a REAL value each occupy 4 bytes). This large value is adequate for most (single threaded) Fortran programs even when they contain large local arrays (these are allocated on the stack). However, for multiple threads, this amount of memory is allocated for each thread and the default stack size can be unduly large. Conversely, single-threaded programs that contain exceptionally large local arrays may require a stack size that is larger than the default. You will find, however, that stack overflow exceptions are currently not well reported by the .NET framework.


Synchronising threads

Multi-threaded programs can share the same data and by default the switch from processing one thread to another can take place at any time. Sometimes it is necessary to protect shared data by making sure that a calculation in one thread is not interrupted by processing (that uses or changes the shared data) in another thread. One simple example of this is where two threads READ from (or WRITE to) the same Fortran unit. Another is where one thread must update a data structure that is used by another thread. The simplest way to achieve this is to use the LOCK statement:

LOCK
<some sensitive statements>
END LOCK

The system prevents a swap to another thread whilst the statements within a LOCK block are being executed. Once a block has been entered, other threads are forced to wait until the block has been completed.

In some cases it is useful to apply a more selective locking mechanism. A lock can be applied to any .NET object (typically stored in a FTN95 module). The object must be created (using NEW@) before a LOCK statement is applied:

OBJECT("System.Object") MY_OBJ
MY_OBJ=NEW@("System.Object")
...
LOCK(MY_OBJ)
! Some sensitive statements...
END LOCK

This form of the LOCK statement only operates in relation to other locked blocks (in a different thread) that refer to the same object.

Here are some rules for locking:

1. One lock has no effect upon other locks in the same thread.

2. Using the same lock a second time (i.e. nesting) has no effect.

3. If a locked block is exited prematurely (because an exception is raised) the corresponding lock is removed.

4. You must not enter or exit a locked block via a GOTO statement.

Programs with multiple threads can contain bugs that arise from the interaction of the various threads. In particular, if different threads use and change the same data, a program can produce results that vary from one run to another (because the results depend upon the order in which the threads have been executed). A temporary LOCK wrapped around a significant block of code can be used to identify a threading bug of this kind. The temporary lock forces the code to run serially thus preventing the possibility of a threading bug occurring in this part of the code.

It is also possible to synchronise threads at a lower level by directly calling methods in the System.Threading.Monitor class. These methods can be used to develop a more elaborate system of thread interaction. For example, you could perform a new task whilst waiting for data for the current task to become available.


Handling exceptions

The .NET framework supports exceptions. When a piece of code generates an error condition, the system raises an exception. By default, this will cause the program to terminate with a diagnostic message. However, if the code lies within a TRY block then it is possible to respond to the error and continue execution. The same is true if the error occurs within a subprogram that has been called from within a TRY block.

Raising an exception is an expensive process, so you should design your code so that exceptions are only raised under genuine error conditions. The practise of using exceptions as a device to perform non-local jumps should be avoided. In contrast, entering or leaving a TRY block has only a small overhead unless and until an exception is raised.

Here is a simple example of code containing a TRY block:

OBJECT("Fortran.StopException") myexception
PRINT*,'Program start'
TRY
  PRINT*,'Inside TRY'
  STOP 'Here we go'
  PRINT*,'This should never print'
  CATCH(myexception)
    PRINT*,'In CATCH block'
  FINALLY
    PRINT*,'In FINALLY block'
ENDTRY
PRINT*,'All done'
END

A TRY block is terminated by ENDTRY. The TRY statements in the block are followed by a CATCH block. A CATCH block is terminated by the beginning of another CATCH block or by FINALLY or by ENDTRY. A single FINALLY block (if present) is written at the end and is terminated by ENDTRY. Statements in a CATCH block are only executed when the corresponding exception is raised by one of the TRY statements at which point control is transferred to the CATCH block and any remaining statements in the TRY block are skipped.

The FINALLY block is always executed so terminating TRY statements that must not be skipped (when an exception is raised) should be written in the FINALLY block.

A STOP statement that has a message string raises an exception. Consequently the program above produces the following output:

Program start
Inside TRY
In CATCH block
In FINALLY block
All done

If the STOP statement is removed from the program an exception is not raised and the output is:

Program start
Inside TRY
This should never print
In FINALLY block
All done

Although this is an artificial example, it illustrates the fact that, when an exception is raised, the remaining TRY statements (before CATCH or FINALLY) are abandoned and control is passed to the CATCH block. In either case (whether or not an exception is raised) statements in a FINALLY block are then executed.

CATCH takes an argument that specifies the exception that is to be handled by the block. The system matches the kind of exception that has been raised with the argument of the CATCH block. The exception can match exactly (as in this example). Alternativley you can use a base class (e.g. System.Exception) when declaring the variable (myexception) in order to catch all exceptions that are members of the base class. See the .NET documentation for information about the relevant class members.

When an exception is raised and not caught the program terminates and with diagnostic information that includes the name of the exception. This name can be copied and written into the code so that the exception will be caught in future. See also Arithmetic overflow/underflow .

You can raise your own exceptions using a THROW statement. In C#, a throw takes an argument that is an expression (typically a variable) that evaluates to a .NET exception class. FTN95 recognises a similar syntax but for simplicity it also allows you to use a CHARACTER string variable as an argument to specify the name of the class directly.

Thus in FTN95 a THROW statement can take the form:

THROW <string_variable>

For example,

CHARACTER(LEN=20),PARAMETER::EXC="MyException"
THROW EXC

This string variable can also be used as the argument for the corresponding CATCH statement. (When you use THROW with a character string argument, FTN95 raises an exception using a class called Salford.Fortran.UserException. This class has a member that is a string variable whose value is the string that has been used as the argument for THROW.)

When using a CHARACTER string variable to THROW an exception it is still possible handle multiple exceptions. To do this you simply re-throw any exceptions that are not handled by the current CATCH. For example:

CHARACTER(LEN=20) EXC
TRY
  CALL DO_SOMETHING
  CATCH(EXC)
    !Handle two particular exceptions and throw the rest to a possible outer try block
    IF(EXC /= 'MyException_1' .AND. EXC /= 'MyException_5') THROW EXC
    CALL HANDLE_1
ENDTRY

These CHARACTER variables are standard Fortran strings so you should ensure that they are long enough to avoid truncation.


Arithmetic overflow/underflow

Overflow
On a Win32 platform, FTN95 always tests for floating point overflow. Integer overflow is tested in CHECKMATE mode only. Floating point underflow, which (depending on the algorithm) may or may not represent a true error, can optionally be trapped. This strategy reflects the fact that, for INTEL architectures, integer overflow detection is more expensive than floating point overflow detection.

When integers overflow (in Win32 or .NET code) the result is essentially meaningless and can be of either sign. On a .NET platform, the result of a floating point overflow is stored as one of two pseudo-numbers representling 'plus infinity' and 'minus infinity'.

The .NET framework caters for a range of platforms with differing CPUs. Because of this, automatic overflow checking for both integer and floating point quantities is only provided in CHECKMATE mode. When CHECKMATE is used, an exception is raised when overflow occurs. When CHECKMATE is not used, by default overflow is not detected and a calculation will continue using values that are meaningless.

FTN95 provides an intrinsic subroutine called CHECK_FINITE@. This routine takes a single REAL or COMPLEX scalar variable as an argument and raises an exception if the argument is not finite (a COMPLEX variable is deemed to be infinite if either the real or imaginary part is infinite). The exception can be handled by using a TRY block. Because of a potentially high overhead, CHECK_FINITE@ should only be called at selected points in the code and after calculations that are considered to be sensitive and liable to floating-point overflow.

In CHECKMATE mode, FTN95 automatically calls CHECK_FINITE@ after each floating-point calculation. For release mode your program can make calls to CHECK_FINITE@ at selected points in order to raise an exception if floating-point overflow occurs. Alternatively, for release mode the FTN95 command line option /OVERFLOW can be used to automatically call CHECK_FINITE@ after each floating point calculation.

Underflow
On a Win32 platform, FTN95 allows you to detect floating point underflow by either a) calling PERMIT_UNDERFLOW@(.FALSE.) or b) using /UNDERFLOW on the command line (in which case the call to PERMIT_UNDERFLOW@ is planted for you. If you do not permit underflow, an exception is raised at runtime when an underflow occurs.

Currently there is no mechanism available that allows FTN95 to implement PERMIT_UNDERFLOW@ for .NET. The only way to check for underflow is to test your program in Win32 mode.

Floating point numbers are represented using a significand and an exponent. Maximum precision is obtained by adjusting the exponent so that the leading binary digit of the significand is a one rather than a zero. A non-zero significand that has a leading zero is called a denormal. When the minimum exponent (typically 1E-38 for single precision) is reached, smaller numbers are accommodated by using denormals with decreasing precision until (typically at 1E-46 for single precision) all significant figures are lost and the value is truncated to zero.

Although for many purposes the effects of underflow can be ignored, it is important to note two factors:

a) As values become very small they will have fewer significant figures and (in particular) the different of two small values could easily become meaningless.

b) Calculations involving denormals will be significantly slower (particularly on a Pentium 4).


Conditonal compilation and detecting .NET at runtime

For an introduction to conditional compilation see Conditional compilation.

FTN95 uses IS_CLR@ in two different contexts.

1) As a macro in conditional compilation, and

2) as the name of an intrinsic function.

In both cases IS_CLR@ returns TRUE only if it is a .NET program (i.e. /CLR is on the command line).

Here is an example of its use in conditional compilation:

CIF (IS_CLR@)
  OBJECT('System.Int32') :: j
CELSE
  INTEGER :: j
CENDIF

Note that the FTN95 option /FPP is only required for a Win32 platform (when /CLR is not present, because it is implied by /CLR). /SPARAM and /VPARAM can be used for .NET but /SPARAM cannot be used to set the value of IS_CLR@.

Here is an example of the use of IS_CLR@ at runtime:

IF (IS_CLR@()) PRINT *, 'Running under .NET'

The compiler will issue a warning that the test will always or never succeed. This can be ignored.

The pre-processor can use .AND. and .OR. in very simple expressions. Note that .AND. and .OR. have equal precedence and that brackets cannot be used to group expressions. You must use a comparison if .AND. or .OR. are used. Thus the directive:

CIF (IS_CLR@ .AND. KIND == 3)

will produce an error and must be written:

CIF (IS_CLR@ == 1 .AND. KIND == 3)

Note also that continuations are ignored by the pre-processor. However, it does not truncate lines.

The pre-processor also supports CELSEIF and CERROR. The CERROR directive simply prints the given string as a compilation error and halts compilation. This can be used to trap invalid VPARAM combinations. For example:

CIF (IS_CLR@ == 1 .AND. KIND == 3)
  CERROR '"/VPARAM KIND 3" is not supported under .NET'
CELSEIF (KIND == 3)
  INTEGER, PARAMETER :: kind = 3
CENDIF


Releasing FTN95 .NET executables and DLLs

In order to use an FTN95 .NET executable or DLL on another machine the following components must be installed:

  • The .NET Framework must be installed.
  • salflibc.dll must be installed either on the PATH or in the application directory.
  • The FTN95 .NET runtime library must be installed. The use of a Windows Installer and installation to the Global Assembly Cache is recommended. All four files listed below must be present.
  • Your FTN95 .NET executable/DLL must be installed.

The .NET framework can be downloaded to the target machine from the Microsoft website or it can be included with your release (there is a redistributable framework installer available from Microsoft). The framework version number must be the same as or greater than that used for developing the release.

A copy of salflibc.dll must be shipped when using the current release of FTN95 .NET (a future release of FTN95 .NET will not require this DLL for .NET). salflibc.dll should be installed either on the PATH, or in the same directory as the executable/DLL. If there is more than one copy of salflibc.dll on the target machine, care should be taken to ensure that the appropriate version is used. The safest method is to install this DLL in the same directory as the executable/DLL.

A set of FTN95 .NET runtime libraries is also required. This set is installed on the developer machine as part of the FTN95 .NET installation and is placed in the Global Assembly Cache (GAC). Another copy of the set of library files will be found in the "Redist" sub folder for easy access when releasing your product. This set consists of three files:

ftn95lib.dll
ftn95lib.mdl
ftn95lib1.mdl

These files must be installed on the target machine.

There are two standard procedures for installing Silverfrost redistributable files.

a) All redistributable files can be placed in the application folder.

b) The three .NET runtime files above can be placed in the GAC and salflibc.dll placed on the path (c:\WINDOWS\System32\ is recommended). If the .NET runtime files are installed into the GAC then it is not enough to have salflibc.dll in the application folder. Installation into the GAC can be achieved by using the Windows Installer, available with Visual Studio .NET Professional, or by using a modern third party installer product. Alternatively the .NET Framework SDK utility called gacutil.exe can be used for this purpose.

When using the Visual Studio Windows Installer, the File System view should be selected. A special folder is added by right clicking on the File System on Target Machine node, one of these being the Global Assembly Cache Folder....

The above set of library files should be added to this folder (see the Windows Installer documentation for further information).


Attributes

The .NET environment allows so called "attributes" to be attached to a variety of program entities - such as routine names. These attributes can hold any amount of arbitrary information that can be interrogated at run time.

The FTN95 ATTRIBUTE statement is used to attach attributes to parts of a Fortran program. For example:

ATTRIBUTE(CLASS="Salford.Fortran.SalfordUserInfoAttribute",(/20,30,40/),TARGET="ROUTINE")

This will attach an attribute to the routine in which it is contained. Possible values for TARGET are:

"ROUTINE" - Attach attribute to routine under construction.

"CLASS" - Attach attribute to the containing class.

"ASSEMBLY" (the default target) - Attach attribute to the assembly as a whole.

The extra, non-keyword, arguments must be constant expressions and supply arguments to the attribute. In the above example one 3-element integer array argument is supplied.

If the routine contains an ASSEMBLY_INTERFACE statement, then TARGET="ROUTINE" attaches the attribute to the interface routine (which will be the externally visible name).

Attributes are classes and must already exist in the .NET environment or be created in C#, for example. For convenience, FTN95 provides the SalfordUserInfoAttribute (as used above), and this can take a scalar or 1-dimensional array of type INTEGER, REAL, DOUBLE, LOGICAL (converted to bool), or CHARACTER (converted to string).


Signing an assembly

There are three steps that need to be taken in order to use a key pair when signing an assembly created with FTN95.

1. Create a key by using the Microsoft .NET SDK tool sn.exe (Search in titles for "Creating a Key Pair").

2. Using FTN95, create an MDL rather than DLL. There are two ways to do this:

a) from Visual Studio, select the project Properties window and set the Output File Type in the Compiler Options to MDL, or

b) from the command line, invoke DBK_LINK, or DBK_LINK2 or DBK_LINK4 using MDL as the extension of the output file.

3. The .NET module can then be used as input to the Microsoft .NET assembly linker, al.exe. This Microsoft linker is used to sign a .NET assembly so that it can be placed in the Global Assembly Cache. Here is an example of a suitable command line:

al.exe infile.mdl /keyfile:key.snk /out:outfile.dll

This creates a .NET assembly called outfile.dll, signed with key.snk and including the file infile.mdl . For further information about al.exe see Assembly Linker.

For information about strong-named assemblies see Creating and Using Strong-Named Assemblies.


Visual ClearWin

ClearWin+ is the Silverfrost library for writing Win32 Windows applications. It has been available for a number of years and will continue to be available in its present form. It can be used to develop native Win32 applications or .NET applications running in a Win32 environment.

In contrast,Visual ClearWin is a Silverfrost product for Microsoft .NET that draws upon many of the design features of ClearWin+ and implements them in a Microsoft .NET environment. The defining feature of Visual ClearWin is that it uses the Microsoft Visual Studio WYSIWYG design view of a C# or Visual Basic form in order to create a form which is then used with standard Fortran code.

Visual ClearWin is based on a library of classes that is located in a namespace called Salford.VisualClearWin. The classes in this library are derived from the the Microsoft Forms library (System.Windows.Forms) which, in turn, provides a wrapper for the standard Windows API. Salford.VisualClearWin also accesses the Microsoft Drawing library (System.Drawing) which, in turn, provides a wrapper for the standard Windows GDI+.

Visual ClearWin provides the Fortran programmer with easy access to these two Microsoft libraries via a set of simple functions whilst, at the same time, maintaining the power and flexibility of the source libraries.

Microsoft Visual Studio includes a WYSIWYG Form designer that allows you to create a Form by selecting components from a toolbox and dropping them on to a design view. The code base for the design is provided automatically in either C# or Visual Basic. For the most part the illustrations in this guide use C#. However, Visual Basic can be used if this language is preferred.

In general a Visual Studio solution is made up of a number of projects. A simple Visual ClearWin solution contains two projects, one of which is written in Fortran, the other uses a design view in order to automatically generate C# or VB code. One of the projects creates an executable, the other a DLL that is accessed from the executable.

There are two possible approaches: one uses a Fortran DLL, the other uses a Fortran executable. In the past the first method has been employed by many programmers who have used a VB front end to access a Silverfrost Fortran DLL. Now C# can also be used as a front end. The second approach is equivalent to ClearWin+ and is based on a Fortran main program that accesses a C# (or VB) form in a DLL. The advantage of this approach is that, when the design view is used to create the form, you do not need to view or understand the underlying C# (or VB) code. Because of its simplicity, this second approach is adopted as standard in Visual ClearWin. However, many of the features of Visual ClearWin are also useful when using a Fortran DLL.

An interface to Visual ClearWin methods and parameters is provided in a Silverfrost Fortran module called VC. The names of all the functions and subroutines begin with "vc" and end with the @ symbol.


Getting started

Solution3 of the Visual ClearWin demonstration pack uses the illustration below. Once you have worked through this it is recommended that you proceed to Solution4 and so on. The demonstration pack includes a folder called "Solution". A simple way to start a Visual ClearWin solution is to copy this folder (making sure that the Fortran project is configured for one of the .NET modes such as Debug .NET).

This topic describes how to get started with Visual ClearWin. By working through the following instructions you can produce an application that looks like this.

When using the resulting application, a floating point value is entered into the Value box and the square of this value appears in the Result box when the button is clicked.

The solution consists of two projects; one contains a simple Fortran executable, the other a C# Form contained in a DLL. We start with the DLL because it contains names that are used in the Fortran code.

In Microsoft Visual Studio, create a New, Blank Solution and Add a New Project. For the type of project, select Visual C# Projects and Windows Application (you could use a Visual Basic Project if you prefer). When you do this, a new blank form is displayed in a design view. In the Properties of this project, under the General properties, select the Output Type to be a Class Library.

Now construct a form similar to that shown above. Use components from the Toolbox together with the mouse to design the form, selecting components from the toolbox and dragging a rectangle in the design view (you can pin the Toolbox open by clicking on the pin icon in the caption). Use the Properties Window for the form and for each component in order to create the visual attributes that you want. It is not necessary to view the code for the form.

The input and output boxes on the form must use a Visual ClearWin control called Double_Box. If this type of control is not visible in the Toolbox then you can add it by customizing the Toolbox as follows. Right click on the Toolbox and select Customize Toolbox. In the resulting dialog, select the tab for .NET Framework Components. Click on the Namespace header, scroll down to Salford.VisualClearWin and click on the check box for each of the Silverfrost controls that are listed. It should only be necessary to customise the Toolbox once.

In the properties for the button control, make sure that the DialogResult property is set to None.

In the References for this project, make sure that there is a reference to Salford.VisualClearWin.

Create a second project to contain the Fortran main program. Add a New Project and, for the type of project, select FTN95 Projects and FTN95 Visual ClearWin Application. In the Properties of this project, ensure that it uses the .NET platform and, in the Linker Options, that Yes is selected against Windows Application.

Open the Fortran file that has been added to the project for you and modify the template so that it becomes:

MODULE Form1
 USE VC
 TYPE(VCdialog) dlg1
 DOUBLE PRECISION x,y
CONTAINS
 INTEGER FUNCTION DoProcess()
  y=x*x
  DoProcess=0
 END FUNCTION DoProcess
END MODULE Form1

PROGRAM Main
 USE Form1
 dlg1=vcCreateDialog@("WindowsApplication1.Form1")
 CALL vcLinkDouble@(dlg1,"double_Box1",x)
 CALL vcLinkDouble@(dlg1,"double_Box2",y)
 CALL vcOnClick@(dlg1,"button1",DoProcess)
 CALL DisplayDialog@(dlg1)
END

In the References for this project, select Add Reference and add a reference to the C# project. Also make sure that there is a reference to Salford.VisualClearWin.

Ensure that the C# form is built before the Fortran main program by clicking on Project Build Order in the popup menu for the solution.

Now redirect the class library (DLL) in your existing Visual C# project so that it is sent to the folder used by your Fortran executable. To do this open the Properties dialog for the C# project and in the Build section of the Configuration Properties set the Output Path to "..\Project1\Debug\NET\" or its equivalent.

The strings that appear in the Fortran program use default names from the C# project. Theses are "WindowsApplication1" which is a misnomer for the C# DLL, "Form1" for the name of the Form, and "double_Box1", "double_Box2", and "button1" for controls in the Form.

The Fortran module called VC is a Silverfrost module that is used to access the Visual ClearWin library. vcCreateDialog@, vcLinkDouble@, vcOnClick@ and vcShowDialog@ relate to methods in this library. This library includes a class called Dialog that provides a wrapper for the Microsoft Forms class. dlg1 is an instance of this class.

vcCreateDialog@ creates a Dialog from the form contained in the C# project. The first call to vcLinkDouble@ identifies x with the value obtained from the input box in the form. The second call identifies y with the value in the output box.

vcOnClick@ connects a button click event to the function called ButtonClick. As a result of this code, when you enter a number in the input box at run time, the value is automatically copied to x. When you click on the button, the callback function is called and y is computed as the square of x. This value automatically appears in the output box because y is linked to it.

vcDisplayDialog@ makes the form visible and does not return until it is closed by the user.

This example illustrates the main features of Visual ClearWin. The design view of a C# (or VB) form is used to create the visible form. In addition to the features illustrated above, the design can include components such as images, menus, toolbars, status bars, and common dialog boxes. Standard controls such as list boxes, combo boxes, tree views, list views and tab controls can be populated at design time or (where necessary) at run time.

Static text is provided as a Label component and this can use various fonts and colours. An image is provided as a PictureBox component. An image file is then attached to the PictureBox using the Image property. This can use one of a number of image formats including BMP, ICO, JPEG and GIF (although the design view can sometimes lock when using a GIF image).

Links are programmed between the controls in a form and Fortran variables using methods such as vcLinkDouble@, vcLinkInteger@ and vcLinkText@. These provide dynamic linking. If two controls share the same Fortran variable then Visual ClearWin automatically updates one when the other is changed. Alternative methods such as vcGetInteger@ and vcSetInteger@ allow you to get and set values without dynamic linking.

An event in a form can be made to trigger a Fortran callback function. vcOnClick@ is used for click events on buttons, menu items and toobar buttons whilst vcOnEvent@ allows you to link other events to a callback.

vcCreateDialog@ is commonly called to create a form. For simple dialogs that require no linking etc. you can call vcShowMessageBox@ which combines vcCreateDialog@ with vcShowDialog@. The alternative is to call vcCreateMdiChild@. This is used to create a child from a MDI (Multi Document Interface) parent.

vcDisplayDialog@ is used to display a modal dialog. A modal dialog is one that must be closed before other dialogs in the application can be used. The alternative is to call the routine vcShow@ in order to display a modeless dialog. If we were to use vcShow@ in the above program it would return immediately and terminate the application. Modeless dialogs are used for child dialogs that can be left open. For example, vcCreateMdiChild@ should be followed by a call to vcShow@.

A set of demonstration solutions has been written to illustrate the main features of Visual ClearWin.

Solution1 | The application described above but using a C# executable. See A simple C# form.
Solution2 | The application described above but using a VB executable.
Solution3 | The application described above.
Solution4 | The application used in the "Factoriser" tutorial of ClearWin+.
Solution5 | Illustrates various controls.
Solution6 | Illustrates menus, toolbars, status bars and accelerator keys.
Solution7 | Illustrates graphics drawing (drawing lines, filling regions, drawing text and images).
Solution8 | Illustrates graphics drawing (pixel-by-pixel drawing).
Solution9 | Illustrates using common dialog boxes.
Solution10 | Illustrates a multiple document interface.
Solution11 | Illustrates a single document interface.
Solution12 | Illustrates populating a ListBox at run time.
Solution13 | Illustrates populating a ComboBox at run time.
Solution14 | Illustrates populating a ListView at run time.
Solution15 | Presents a fully functional tree editor that illustrates populating a TreeView at run time.
Solution16 | Presents an elementary Paint program that illustrates advanced features of the Drawing_Panel control.
Solution17 | Uses an Explorer_Box control to create a simple Internet Explorer program.
Solution18 | Uses an Explorer_Box to create a simple WYSIWYG HTML editor.
Solution19 | Uses an Explorer_Box to create a simple Help viewer.
Solution 20 | Illustrates enhanced menus.
Solution 21 | Illustrates a MDI based on a tab control.

Controls in your application are automatically given the standard Microsoft® Windows® XP style of appearance. This is done for you by the linker DBK_LINK which plants code that makes your application use ComCtl32.dll version 6 rather than the default version 5. The result is that when your application is run under Windows XP it will use this style. Most controls will then use the new style by default but controls that have the FlatStyle property (in particular the GroupBox control and controls derived from the ButtonBase class) must have this property set to FlatStyle.System. In exceptional circumstances you may wish to avoid the use of the Windows XP style. For example, at the time of writing, the XP style for tab controls is unfinished and does not display correctly when the tabs are along the bottom of the control. The style can be switched off by using /no_xp_style on the DBK_LINK command line (or the FTN95 command line if DBK_LINK is called from FTN95). For further information about XP styles see Using Windows XP Visual Styles.


Controls

It is recommended that controls be added to a form at design time using the Visual Studio form designer and Toolbox.

Any of the standard Microsoft controls can be selected from the Toolbox as indeed can any third party control. However, the following Silverfrost controls are designed specifically for use with Visual ClearWin.

Solution5 in the Visual ClearWin demonstration pack illustrates many of these controls.

Each Silverfrost control is derived from an existing Microsoft control and inherits its properties. Most can be linked directly to a Fortran variable or array. Some provide for automatic pivoting (this is an automatic sizing process that maintains the position of the top left corner of the control, see below). Other controls have the Persists property (this is an automatic save/load processes that uses the registry, see below).

Salford class | Base class | Fortran link | Pivoting | Persists | Other properties added to base class
Int32_Box | TextBox | Integer |  | Yes | Only accepts integer values.
Double_Box | TextBox | Double precision |  | Yes | Only accepts floating point values (see Additional information).
Decimal_UpDown | NumericUpDown | Double precision or integer |  | Yes | (Base class only accepts decimal values.)
Double_UpDown | DomainUpDown | Double precision |  | Yes | Only accepts floating point values.
Text_Box | TextBox | Character string | Yes | Yes |
Check_Box | CheckBox | Integer |  | Yes |
Radio_Button | RadioButton | Integer |  | Yes |
Combo_Box | ComboBox | Integer and/or character string | Yes | Yes | A DropDownList cannot be linked to a string.
List_Box | ListBox | Integer or integer array | Yes |  | Uses an array with multi selection.
CheckedList_Box | CheckedListBox | Integer array | Yes |  |
Tree_View | TreeView | Integer | Yes |  |
List_View | ListView | Integer or integer array | Yes |  | Uses an array with multi selection.
Track_Bar | TrackBar | Integer |  | Yes |
Tab_Control | TabControl | Integer | Yes | Yes |
Drawing_Panel | Panel |  | Yes |  | Provides run time drawing.
Group_Box | GroupBox |  | Yes |  |
RichText_Box | RichTextBox | Character string | Yes | Yes |
Explorer_Box | Explorer |  | Yes |  |
Color_Picker | PropertyGrid | Integer |  |  |

Silverfrost controls are characterised by a name containing an embedded underscore.

Additional properties provided by Silverfrost controls appear in the Data category in the Properties window.

Precision
An Int32_Box has a Digits property giving the maximum permitted number of decimal digits. A Double_Box and a Double_UpDown have an ExpFigs property giving the maximum number of decimal digits in the exponent part and a SigFigs property giving the maximum number of decimal digits in the significand. These precision properties must be selected before setting maximum and minimum values.

Maximum and minimum values
Silverfrost controls that accept numeric values have a Minimum and a Maximum value property. The range is determined initially by the precision properties but can then be adjusted to provide greater control over the input. Range checking can be switched off by setting both the Maximum and Minimum to zero.

Pivoting
Pivoting provides a simple alternative to the (Microsoft) Anchor property. When the FormBorderStyle property of the form is set to Sizable, the size of the form can be changed at run time by dragging the borders. Some Silverfrost controls allow for what is called pivoting. Pivoting fixes the position of the top left corner of the control and automatically adjusts the width and/or height of the control in order to maintain the original margins. The Pivoting property can be set to None, Full, Horizontal or Vertical where Full means both Horizontal and Vertical.

Note that the (Microsoft) Dock property also provides an automatic sizing mechanism of a different kind which is occasionally more appropriate. For example if you have a single control that is to occupy all of the form then it is often better to set the Dock property to Fill.

Automatic correcting
Silverfrost controls that accept numeric values have an AutoCorrect property that can be set to True or False. When switched on, auto-correction takes place when the user stops typing in a number and clicks on another control (that is, when the focus is lost). When an invalid number is present, auto-correction substitutes the last valid number recorded. For example, when using a Double_Box with ExpFigs set to 2 (say), if the user types in 1.0 then 1.0e and then changes the focus to another control, auto-correction will change 1.0e back to 1.0. At the same time a warning icon (with a tooltip message) appears alongside the control. If AutoCorrect is set to False, this squence would leave 1.0e in place and an error icon appears alongside the control. These controls also have an ioState output property. A zero value indicates a valid number.

Persists
Silverfrost controls that have the Persist property can automatically store data in the registry. It should only be used for data that the user can change at run time. If Persist is set to true then data is automatically saved when the form closes and is restored when it is recreated. The registry key name is formed using the Company and Product names defined in the file called AssembleInfo.cs. Edit this file to use your own names. The default names are "Silverfrost" and "Visual ClearWin". The name of the form and the name of the control are also used to create the key. Use the Registry editor if you need to independently view/edit the registry entries (from Visual Studio, select "OLE/COM Object Viewer" from the Tools menu and click on the "Run RegEdit" button on the Toolbar).

The data that is stored depends upon the type of control. When restored, this value replaces any value in the design view. The current value of the control is saved/restored except as follows:

Check_Box | The checked state is used.
Radio_Button | The on/off state is used.
Tab_Control | The tab index is used.
Combo_Box | The list of items and the text in the edit box is used.
Text_Box | The text is used but only single line edit boxes can persist.
RichText_Box | The text is used but only single line edit boxes can persist.

Additional information for Double_Box controls
At the time of writing there is a bug in Visual Studio that prevents the Forms designer from reading a C# script that includes a constant double value written in exponent form (e.g. 1E+60). The problem is limited to the Forms designer; the script will compile and run successfully. Also the problem is limited to C#; VB forms do not have this problem. If the designer fails to read your script, remove the lines that use the constant double values and restore them when you have finished the design.


Buttons

You can use a (Microsoft) Button control to place a button on a form and use its properties to specify its colour, text and background image. More importantly, select an appropriate value for the DialogResult property as follows.

The value None is used when you want a button click to do something without closing the form. All other values cause the form to close, at which point the Visual ClearWin function vcShowDialog@ (that displayed the form) will return with a corresponding integer value. For example, clicking on a button with a DialogResult value of OK causes vcShowDialog@ to return a value given by the parameter DialogResult_OK and so on.

You can link a button click event a callback function in your Fortran code by calling vcOnClick@. For example,

CALL vcOnClick@(dlg, "button1", DoProcess)

links the button with name button1 to the callback function DoProcess. dlg is the Visual ClearWin Dialog returned by the function CreateDialog that created the form. DoProcess is an integer function that you provide. It takes no arguments.


Menus

Solution6 in the Visual ClearWin demonstration pack illustrates standard menus whilst Solution20 illustrates enhanced menus. Enhanced menus are Visual ClearWin menus (called Main_Menu and Context_Menu) that have the same style as the menus in Microsoft Visual Studio. Enhanced menus have an associated ImageList and each menu item can be assigned an image taken from the list.

You can use the Visual Studio form design view to add a Main menu and Context menus to a form. A form will often have one Main menu and one Context menu that is attached to the form. Other Context menus can be included and attached to various controls in the form and/or to toolbar buttons in a toolbar.

The menu editor allows you to design the structure of the menu and to provide a name and text for each for each item. The name of an item can be linked to a process using a Fortran statement of the form:

CALL vcOnClick@(dlg, "menuItem1", DoProcess)

dlg is the Visual ClearWin Dialog returned by a call to vcCreateDialog@, menuItem1 is the name of the item in the design view, and DoProcess is the a Fortran callback function that carries out the processing.

The argument DoProcess can be replaced by a string corresponding to one of a number of standard callback functions. Better still, you can modify the name of the item in the design view as described in Standard callbacks.

You can add an image to a menu item at design time by using an enhanced menu. That is a Main_Menu rather than a MainMenu component or a Context_Menu rather than a ContextMenu. Create an ImageList and attach this as a property of the enhanced menu. In the ImageList you should select the TranparentColor property before adding images to the list. By using the selected background colour you will be able to adjust the appearance when a menu item is selected. The properties of a MenuItem in an enhanced menu includes a property that appears in the form "ImageIndex on menuName". This can be left blank or set to the zero-based index of an item in the ImageList attached to the menu. Enhanced menus also have additional properties for menu tips (see below) and for standard callbacks.

If you add a status bar to your form then you can provide "Menu tip" information. This information will appear in the status bar when the mouse hovers over the menu item. Menu tips are provided in the design view of a standard menu by adding an extension to the text of the menu item as follows. Menu items in extended menus have a separate property for a menu tip.

The text "Exit" is followed by a pipe symbol ( | ) and then the menu tip. At run time the tip appears in the status bar.

A menu item can be added at run time by making a call to vcInsertMenuItem@. For example,

CALL vcInsertMenuItem@(dlg,"newItem","menuItem1","Open",FileOpen,1)

inserts an item with name newItem after an existing item with name menuItem1. The item contains the text "Open" and calls the callback FileOpen. vcRemoveMenuItem@ is used to remove a given item.

Perhaps the most common use of dynamic menus is to provide a list of recent files. Note, however, that there is a standard callback function called RecentFiles that does this automatically.

A Menu tip for a dynamic menu item requires a Fortran statement of the form:

CALL vcMenuTip@(dlg,"newItem","Opens a file.")

whilst an accelerator key can be added using:

CALL vcSetMenuAccelerator@(dlg,"newItem","CtrlO")

CtrlO (Ctrl plus the letter O) takes the same form as in the drop down list for the Shortcut property of a menu item.

An image index for a dynamic menu item requires a Fortran statement of the form:

CALL vcMenuImage@(dlg,"newItem",3)

This uses the image with index 3 in the image list that is attached to the enhanced menu at design time.


Accelerator keys

Solution6 in the Visual ClearWin demonstration pack illustrates accelerator keys.

Accelerator keys are normally provided via the Shortcut property of the menu item in an existing menu. In this case it is not necessary to provide any further information.

If you do not want to display a menu item for a given accelerator key then you can do one of two things:

1. Add a hidden item to a context menu that is attached to the form and use the Shortcut property.

2. Allow Visual ClearWin to do this for you by using a Fortran statement of the form:

CALL vcAddAccelerator@(dlg,"accel1","CtrlA",DoProcess)

dlg is the Dialog created by a call to vcCreateDialog@, accel1 is the name of a new hidden menu item, CtrlA represents Ctrl+A, and DoProcess is the Fortran callback function for the process to be performed. CtrlA takes the same form as in the drop down list for the Shortcut property of a menu item.


Toolbars

Solution6 in the Visual ClearWin demonstration pack illustrates toolbars.

You can use the Visual Studio form design view to add toolbars to a form. Before adding any buttons, use the Toolbox to drop an image list on to the form and add suitable bitmaps for the toolbar buttons to the image list. Select this image list as a property of the toolbar and then use the Collection editor to add buttons to the toolbar.

Note: Create your bitmaps first and decide which colour you are going to use to represent the background. The simplest choice is to make the bitmap background white. Create your image list next and (before you add any images) set the TransparentColor property (to white if this is the colour you have used). Now add your bitmaps to the image list collection. If you follow this order of construction, the background colour at run time will be that for the toolbar (which is the same as the background colour of the form). Note also that, to get reasonable greyed images, you must set the ColorDepth property of the image list to Depth32Bit.

The name of a toolbar button can be linked to a process using a Fortran statement of the form:

CALL vcOnClick@(dlg, "toolBarButton1", DoProcess)

dlg is the Visual ClearWin Dialog returned by a call to vcCreateDialog@, toolBarButton1 is the name of the item in the design view, and DoProcess is the a Fortran callback function that carries out the processing.

The argument DoProcess can be replaced by a string corresponding to one of a number of standard callback functions. Better still, you can modify the name of the item in the design view as described in Standard callbacks.

A toolbar button can be given the style DropDownButton. When using this style you also specify a context menu to attach to the button.

In Visual ClearWin, you can also attach a control such as a combo box to a toolbar. To do this you use the Toolbox to drop the control on to the form. You can place it on the toolbar if you wish but its location and width are not important. Visual ClearWin will change the parent of the control and set its location and width if you add the following information in the Collection editor for the toolbar buttons.

Add a number of Separators or dummy (disabled) buttons to the toolbar, sufficient to mark out the space to be occupied by the control. The first and last spacer must be a Separator. For the Text property of the first and last spacer use the name of the control (e.g. comboBox1). Leave the Text of all the other Separators blank.

Alternatively you can change the parent of a control at design time but this requires some C# programming. To do this use spacers as above and use the design view to drop the control on to the form. Then, using the code view of the form, remove the control from the list of controls for the form and add it to the toolbar with a statement of the form:

this.toolBar1.Controls.AddRange(new System.Windows.Forms.Control[] {this.comboBox1});

After changing the parent of a control in this way you can set is size and location using the design view.

When using a Multiple Document Interface (MDI) you can attach a toolbar to the parent form at design time for use when there are no child windows open. Each type of MDI child can also have its own toolbar. In Visual ClearWin, the child toolbar is attached to the child at design time but replaces the parent toolbar at run time (when the child is active). See MDI applications for further details.


Status bars

Solution6 in the Visual ClearWin demonstration pack illustrates status bars.

You can use the Visual Studio form design view to add a status bar to a form. You can also add a collection to the status bar for various panels, each of which will have a name.

At run time you can display text in the status bar or one of its panels using a statement of the form:

CALL vcSetText@(dlg, "statusBar1", "Text to display")

When panels are included, use the name of a panel.

A status bar can be used to display Menu Tips. It can also be used to create and display a progress bar by using a statement of the form:

CALL Progress(dlg, 1)

This call displays the progress bar and each subsequent call adds a "blob" to the progress indicator. Finally,

CALL Progress(dlg, 0)

destroys the progress bar.


Text boxes

Text boxes are controls containing text. They are often employed to allow the user to enter text but can be set to be read-only with the effect that the text can only be changed under program control.

The following are standard text box controls: TextBox, Text_Box, RichTextBox and RichText_Box. The Int32_Box and Double_Box are specialised text boxes that contain numeric filtering with the result that the user is only allowed to enter valid numbers.

You can establish a connection between the text in a text box and a Fortran character string in one of two ways: a) by using vcLinkText@ (possibly with vcRefreshText@) or b) by using vcGetText@ with vcSetText@. The first of these approaches creates a continuous link between the control and a Fortran variable. In this context linking causes changes in the control to be reflected in the Fortran variable whilst refreshing causes changes in the Fortran variable to be reflected in the control. vcLinkText@ should not be used with multi-line controls because of the associated overhead.

In addition, the following functions are of special interest for text boxes.

vcAppendLine@ | Appends a line of text with a line feed to the end of a text control.
vcAppendText@ | Appends text to the end of a text control.
vcClear@ | Clears a control.
vcFindText@ | Finds a given string.
vcGetText@ | Gets all of the text or used with a line index to get a line of text from a control.
vcLoadText@ | Displays text from a file in a control.
vcPrintText@ | Prints all the text in a control.
vcReplaceText@ | Replaces the current selection with a given string.
vcSaveText@ | Save the text in a control to a file.
vcSetText@ | Sets all of the text or used with a line index to set a line of text in a control.

A text box can be filled with text in the design view of the form. Alternatively you can use vcAppendLine@ to add lines dynamically at run time. vcLoadText@ is used to read in a file.

If you use a text box as a text editor then it is important to note the limitations of these controls. A TextBox (Text_Box) uses plain monochrome text and is limited to the number of characters specified in the MaxLength property (set this to zero to remove the limit). A RichTextBox (RichText_Box) uses formatted text and is not limited in size. However, a RichTextBox of modest size will take an excessively long time to load from a file. There are other limitations, details of which will be found in the documentation for each function.

The following standard callbacks are of special interest for text boxes.

Cut | Cuts the selection to the clipboard.
Copy | Copies the selection to the clipboard.
Paste | Pastes the clipboard into the text.
Delete | Deletes the current selection.
SelectAll | Selects all the text.
Undo | Undo the last operation.
Redo | Redoes the last undo for rich text.
WordWrap | Toggles the word wrap property.
Font | Opens the common font dialog and sets the global font.
Bold | Sets a rich text selection to bold font.
Italic | Sets a rich text selection to italic font.
Underline | Sets a rich text selection to underline font.
Strikeout | Sets a rich text selection to strikeout font.

Solution10 and Solution11 in the demonstration pack contain text editors.


List boxes

The following are standard list box controls: ListBox, List_box, CheckedListBox and CheckedList_Box.

List boxes have a property (MultiSelect) that allows you to select more than one item at a time (checked list boxes always allow multiple check marks). The index of the selected item in a single selection list box can be connected to a Fortran integer. For multiple selection, an integer array is used.

You can establish a connection between the index of the current selection in a single selection list box and a Fortran integer in one of two ways: a) by using vcLinkInteger@ (possibly with vcRefreshInteger@) or b) by using vcGetInteger@ with vcSetInteger@. The first of these approaches creates a continuous link between the control and a Fortran variable. In this context linking causes changes in the control to be reflected in the Fortran variable whilst refreshing causes changes in the Fortran variable to be reflected in the control. For multiple selections use vcLinkIntegerArray@/vcRefreshIntegerArray@ or vcGetIntegerArray@/vcSetIntegerArray@.

In addition the following functions are of special interest for list boxes.

vcClear@ | Clears a control.
vcGetText@ | Used with a line index to get the text on that line.
vcInsert@ | Inserts or appends a line into a control.
vcRemove@ | Deletes a line in a control.
vcSetText@ | Used with a line index to set the text on that line.

A list box can be filled with lines in the design view of the form. Alternatively you can use vcInsert@ to append lines dynamically at run time.

Note that the effect of vcInsert@ depends on the Sorted property of the control. Also vcInsert@ has an optional argument that can be used to prevent duplicate items from being inserted.

Solution12 in the demonstration pack illustrates the dynamic population of a list box.


Combo boxes

ComboBox and Combo_Box are standard combo box controls.

You can establish a connection between the index of the current selection in combo box and a Fortran integer in one of two ways: a) by using vcLinkInteger@ (possibly with vcRefreshInteger@) or b) by using vcGetInteger@ with vcSetInteger@. The first of these approaches creates a continuous link between the control and a Fortran variable. In this context linking causes changes in the control to be reflected in the Fortran variable whilst refreshing causes changes in the Fortran variable to be reflected in the control.

Note that the internal index of a Combo_Box responds to the SelectionChangeCommitted event rather than SelectedIndexChanged. This means that the index does not change until the user clicks on an item and the drop down list is closed.

In addition the following functions are of special interest for combo boxes.

vcClear@ | Clears a control.
vcGetText@ | Used with a line index to get the text on that line.
vcInsert@ | Inserts or appends a line into a control.
vcRemove@ | Deletes a line in a control.
vcSetText@ | Used with a line index to set the text on that line.
vcPopulateFontCombo@ | Populates a ComboBox with the names of all the installed fonts.

A combo box can be filled with lines in the design view of the form. Alternatively you can use vcInsert@ to append lines dynamically at run time.

Note that the effect of vcInsert@ depends on the Sorted property of the control. Also vcInsert@ has an optional argument that can be used to prevent duplicate items from being inserted.

Solution13 in the demonstration pack illustrates the dynamic population of a combo box.


ListView controls

ListView and List_View are standard list view controls.

You can establish a connection between the index of the current selection in list view and a Fortran integer in one of two ways: a) by using vcLinkInteger@ (possibly with vcRefreshInteger@) or b) by using vcGetInteger@ with vcSetInteger@. The first of these approaches creates a continuous link between the control and a Fortran variable. In this context linking causes changes in the control to be reflected in the Fortran variable whilst refreshing causes changes in the Fortran variable to be reflected in the control.

In addition the following functions are of special interest for list view controls (row and column numbers relate to when the control is viewed in "Details" mode).

vcClear@ | Clears a control.
vcGetText@ | Used with a row index to get the label on that row or with a row and column index to get the text in a cell.
vcInsert@ | Inserts or appends a row into a control. Pipe symbols (|) are used to separate the text into individual cells.
vcRemove@ | Deletes a row in a control.
vcSetText@ | Used with a row index to set the label on that row or with a row and column index to set the text in a cell. A negative value for the column number causes a cell to be appended to the row.
vcImageIndex@ | Sets the image index for subsequent calls to vcInsert@.
vcSetState@ | Sets the current viewing state to one of "Details", "LargeIcon", "List", and "SmallIcon".

A list view can be filled with lines in the design view of the form. Alternatively you can use vcInsert@ to append lines dynamically at run time.

Solution14 in the demonstration pack illustrates the dynamic population of a list view control.

The following standard callbacks are of special interest for ListView controls:

Details | Selects the Details view.
LargeIcon | Selects the LargeIcon view.
List | Selects the List view.
SmallIcon | Selects the SmallIcon view.

If the LabelEdit property is set to true then you can add Fortran statements of the form:

CALL vcOnEvent@(dialog,"list_View1","BeforeLabelEdit",BeforeEdit)
CALL vcOnEvent@(dialog,"list_View1","AfterLabelEdit",AfterEdit)

If your callback function called BeforeEdit returns 1 (rather than zero) then the editing does not start.
If your callback function called AfterEdit returns 1 (rather than zero) then the old label is restored.


TreeView controls

TreeView and Tree_View are standard tree view controls. In contrast to Tree_View, a TreeView does not have an index associated with the selected node.

You can establish a connection between the index of the current selection in Tree_View and a Fortran integer in one of two ways: a) by using vcLinkInteger@ (possibly with vcRefreshInteger@) or b) by using vcGetInteger@ with vcSetInteger@. The first of these approaches creates a continuous link between the control and a Fortran variable. In this context linking causes changes in the control to be reflected in the Fortran variable whilst refreshing causes changes in the Fortran variable to be reflected in the control.

You can use a Tree_View for a tree that grows dynamically at run time but if you also attach an index to each node (by using vcLinkInteger@ etc. with the control) then the index will be "invalidated" each time you add or delete a node so, when you next use the index, it will have to be recalculated. This implies a significant overhead for large trees.

In addition the following functions are of special interest for tree view controls.

vcAppendNode@ | Appends a child node to the currently selected node.
vcClear@ | Clears a control.
vcGetNodeData@ | Gets data for the currently selected node.
GetNodeState@ | Gets the state of the currently selected node (checked, expanded etc.).
vcGetText@ | Gets the label of the currently selected node or, when used with an index, gets the label for that node.
vcImageIndex@ | Sets the image indexes for subsequent calls to vcInsertNode@.
vcInsertNode@ | Inserts a sibling node before the currently selected node.
vcLoadTree@ | Displays a tree from a file.
vcMoveNode@ | Moves the currently selected node in a given direction.
vcRemoveNode@ | Deletes the currently selected node.
vcSaveTree@ | Saves a tree to a file.
vcSelectParentNode@ | Selects the parent of the currently selected node.
vcSetNodeData@ | Sets user data for the currently selected node.
vcSetNodeState@ | Sets the state of the currently selected node (checked, expanded etc.).
vcSetText@ | Sets the label of the currently selected node or, when used with an index, sets the label for that node.

A tree view can be filled with nodes in the design view of the form. Alternatively you can use vcInsertNode@ and vcAppendNode@ to populate a tree dynamically at run time. vcAppendNode@ creates a child node and must be followed by vcSelectParentNode@ to go back to the parent.

A tree can be saved to a file using vcSaveTree@. A subquent call to vcLoadTree@ will restore the tree including the expanded/collapsed state of each node together with the node that was last selected.

Solution15 in the demonstration pack presents a fully functional tree editor and illustrates the dynamic population of a tree view control.

The following standard callbacks are of special interest for tree view controls:

Left | Moves the selected node to the left.
Right | Moves the selected node to the right.
Up | Moves the selected node up.
Down | Moves the selected node down.
ExpandAll | Expands all tree nodes.
CollapseAll | Collapses all tree nodes.

If the LabelEdit property is set to true then you can add Fortran statements of the form:

CALL vcOnEvent@(dialog,"tree_View1","BeforeLabelEdit",BeforeEdit)
CALL vcOnEvent@(dialog,"tree_View1","AfterLabelEdit",AfterEdit)

If your callback function called BeforeEdit returns 1 (rather than zero) then the editing does not start.
If your callback function called AfterEdit returns 1 (rather than zero) then the old label is restored.

Similar rules apply for BeforeSelect, AfterSelect, BeforeExpand, AfterExpand and so on.


PropertyGrid controls

The Microsoft PropertyGrid control forms the basis of the Properties dialog in Visual Studio. It is used extensively when designing a form using the Visual Studio forms designer. The control is of limited use (even to the C# programmer) because it displays the properties of an existing class. The Silverfrost Property_Grid control overcomes this limitation. It is based on the Microsoft PropertyGrid but includes a simple database that dynamically defines a pseudo class in order to display the desired collection of editable values.

The standard properties of a PropertyGrid (inherited by Property_Grid) allow you to switch off the control toolbar and/or the help facility. You can also elect to use the categorised or alphabetical listing of the properties. You are then left with a two column table consisting of labels in the left column together with editable cells of their values on the right. These values can be of various types including integers, double values, logical values and colours. However, like the PropertyGrid, the Silverfrost Property_Grid does not validate data on the fly (like the Int32_Box for example). Instead validation takes place when the focus is changed to a different property or to a different control.

Sample 22 in the Demonstration pack illustrates the use of a Property_Grid control. The GridAttributes property uses an array of string values to define each property that is to be displayed. Here is the list taken from this sample:

Integer|System.Int32|Numbers|Help for integer
Double|System.Double|Numbers|Help for double
String|System.String|Attributes|Help for string
Logical|System.Boolean|Attributes|Help for logical
Colour|System.Drawing.Color|Attributes|Help for colour
Font|System.Drawing.Font|Attributes|Help for font
Point|System.Drawing.Point|Attributes|Help for point|10,20

There are 4 or 5 fields on each line with the format:

<Label>|<Type>|<Category>|<Help info>|<Initial value>

Here is a view of part of the resulting control at run time. The <Label> provides a unique identifier for the property and is used in methods that are associated with the control. In the view shown, these appear in alphabetical order in the left hand column. The type of the data is given by the second field and the name of the category (not shown here) comes next followed by the string that is to appear in the description box (also not shown here). This database contains the initial value for the Point label. In this example, the other values are linked to variables in the Fortran program. The database is implemented at load time so values initialised in the Fortran program must not appear in the database.

For further information see the details of Sample 22.

The following functions are provided for use with Property_Grid controls.

vcLinkGridInteger@ | Links a property of type System.Int32 to a Fortran integer variable.
vcLinkGridDouble@ | Links a property of type System.Double to a Fortran real variable.
vcLinkGridText@ | Links a property of type System.String to a Fortran character string.
vcLinkGridBoolean@ | Links a property of type System.Boolean to a Fortran integer variable.
vcLinkGridColour@ | Links a property of type System.Drawing.Color to a Fortran integer variable.
vcLinkGridFont@ | Links a property of type System.Drawing.Font to a Fortran character string.

You can also use the PropertyValueChanged event to process property changes as illustrated in Sample 22.


Modeless Dialogs

A dialog is normally created using vcCreateDialog@ (an alternative is to use vcCreateMdiChild@). vcShowDialog@ or vcDisplayDialog@ is used to display a modal dialog. A modal dialog is one that must be closed before other dialogs in the application can be used. The alternative is to call vcShow@ in order to display a modeless dialog. Modeless dialogs are used for child dialogs that can be left open. For example, a text editor will often use a modeless dialog to enter text for a "Find" operation.

vcShowDialog@ does not return until the dialog is closed. vcShowDialog@ returns an integer that can be used to indicate the button that was pressed to close the dialog.

vcShow@ returns immediately and leaves the modeless dialog open. vcCloseDialog@ is used to close a modeless dialog.

When calling vcCreateDialog@ you can supply the owner as the first argument. If you do this then the child dialog will stay on top of its owner even when the owner is activated.

Typically if a child dialog is already open then another call to open it should bring it to the front and activate it. This effect can be programmed using the functions vcNullify@, vcIsNull@ and vcBringToFront@. At start up and in response to the "Closing" event a call can be made of the form:

CALL vcNullify@(FindDlg)

When about to open the dialog you can use:

IF(vcIsNull@(FindDlg))THEN
  FindDlg=vcCreateDialog@(OwnerDlg,"Resources.Form2")
  ! Code to configure FindDlg...
  CALL vcShow@(FindDlg)
 ELSE
  CALL vcBringToFront@(FindDlg)
ENDIF

Solution11 in the demonstration pack illustrates this feature.

There is currently no direct provision for docking dialogs. These are modeless dialogs that can be free floating or docked in the main application window. The features of a docked dialog (i.e. a docking dialog in its docked state) can be obtained by using a Panel control that is docked (see .NET Samples). A splitter window can then be attached to the edge of the Panel control to allow for local sizing (see Walkthrough).


Common dialogs

Common dialogs are used to select files for "Open" and for "Save As". They are also used for printing, for selecting a font and for choosing a colour.

Solution9 in the Visual ClearWin demonstration pack illustrates common dialogs.

In the Visual Studio form design view, select the common dialog that you want from the Toolbox. In the case of PrintDialog, PrintPreviewDialog and PageSetupDialog, you must also attach a PrintDocument component.

The following methods can be used to open common dialogs.

vcShowFiles@ | Opens a common Open or SaveAs dialog and reads a list of files into an array of character strings.
vcShowFilesDialog@ | Opens a common Open or SaveAs dialog and passes the file names to a specified callback function.
vcShowPrintDialog@ | Opens a Print, PrintPreview or PageSetup dialog. A prior call to vcOnPrintPage@ specifies a callback that prints each page in turn.
vcShowFontDialog@ | Opens the Font dialog and keeps the result in its own properties. A subsequent call to vcSetControlFont@, for example, uses the result to change the font of a control.
vcChooseFont@ | Combines vcShowFontDialog@ with vcSetControlFont@.
vcShowColourDialog@ | Opens a colour dialog using a colour value as both input and output.
vcChooseColour@ | Opens a colour dialog and sets the foreground colour of a specified control.

Some of the standard callbacks also use common dialogs.


Colour Picker

The ClearWin+ Color_Picker control is a button control that reveals a drop-down "Properties" style colour dialog. The button has an associated Colour property that is visible (browsable) at design time and gives the selected colour. It also has a corresponding integer Value property that is associated with the routines vcLinkInteger@, vcRefreshInteger@, vcSetInteger@ and vcGetInteger@. The alpha value in this integer is set to 255.

The button can be given Text and/or Image properties like other buttons. In addition, the property ColorPanelShow allows you to display a panel on the button that shows the colour selected. The location and size of this panel can be adjusted from the Properties dialog using the properties ColorPanelLocation and ColorPanelSize.

The use of this control is illustrated in solution 16 in the Visual ClearWin demonstration pack.


Standard callbacks

Solution10 in the Visual ClearWin demonstration pack illustrates standard callbacks.

Standard callbacks are callbacks that are provided by Visual ClearWin. They are defined by one of the following strings.

Exit | Closes the form.
New | Creates a new MDI child.
Open | Uses the standard Open dialog to open a file.
Save | Saves a file.
SaveAs | Uses the standard Save As dialog to save a file.
Print | Uses the standard Print dialog to print document.
PrintPreview | Uses the standard Print Preview dialog to preview a document.
PageSetup | Uses the standard Page Setup dialog to set the margins of a document.
RecentFiles | Adds a list of recently used files to a menu. RecentFiles4 limits the list to 4 files etc. The default limit is 8.
Close | Closes a child dialog (usually a MDI child).
Cascade | Cascades all MDI child windows.
TileHorizontal | Tiles all MDI child windows horizontally.
TileVertical | Tiles all MDI child windows vertically.
ArrangeIcons | Arranges the icons in a MDI parent window.
Cut | Cuts the text in an edit box to the clipboard by emulating Ctrl+X.
Copy | Copies the text in an edit box to the clipboard by emulating Ctrl+C.
Paste | Pastes the text from the clipboard into an edit box by emulating Ctrl+V.
SelectAll | Selects all of the text in an edit box by emulating Ctrl+A.
Delete | Deletes the selected text in an edit box by emulating Del.
Undo | Undoes the last action in an edit box by emulating Ctrl+Z.
Redo | Redoes the last undo in an edit box by emulating Ctrl+Y.
WordWrap | Toggles the Word Wrap property of an edit box.
Font | Calls the standard select font dialog in an edit box and changes the global font.
Bold | Toggles the bold state of selected text in a RichEdit control.
Italic | Toggles the italic state of selected text in a RichEdit control.
Underline | Toggles the underline state of selected text in a RichEdit control.
Strikeout | Toggles the strikeout state of selected text in a RichEdit control.
Left | Moves the selected tree node to the left.
Right | Moves the selected tree node to the right.
Up | Moves the selected tree node up.
Down | Moves the selected tree node down.
ExpandAll | Expands all tree nodes.
CollapseAll | Collapses all tree nodes.
Details | Selects the Details view for a ListView.
LargeIcon | Selects the LargeIcon view for a ListView.
List | Selects the List view for a ListView.
SmallIcon | Selects the SmallIcon view for a ListView.
DrawingCut | Cuts the current selection in a Drawing_Panel to the clipboard.
DrawingCopy | Copies the current selection in a Drawing_Panel to the clipboard.
DrawingDelete | Deletes the current selection in a Drawing_Panel.
DrawingSelectAll | Selects the whole drawing in a Drawing_Panel.
DrawingPaste | Pastes contents of the clipboard on to a Drawing_Panel ready for dragging to its destination.
DrawingPasteFrom | Displays the standard Open dialog and pastes a file on to a Drawing_Panel ready for dragging to its destination.
DrawingCopyTo | Displays the standard Save dialog and copies the current selection in a Drawing_Panel to the given file.
htm<id> | Issues the WebCommand <id> in an Explorer_Box.

In order to use the clipboard for images, your main Fortran program must have the System.STAThreadAttribute attribute. This can be assigned by including the following line in your main program.

ATTRIBUTE(class="System.STAThreadAttribute",target="ROUTINE")

Standard callbacks are normally invoked by clicking on a menu item or a toolbar button. This can be programmed by extending the name of the item in the design view.

For example, if the menu item with name menuItem1 is to be used to exit from the form then the name menuItem1 is extended to menuItem1_Exit . Here an underscore is followed by the name of the callback. Similarly, if a toolbar has a collection of buttons that includes one with the name toolBarButton1, extending this to toolBarButton1_Print attaches the button to the standard Print callback.

Alternatively you can use a Fortran statement of the form:

CALL vcOnClick@(dlg, "toolBarButton1", "Print")

If you use a menu item with a Shortcut then there is no need to attach a callback that merely emulates this Shortcut.

Within a callback function you can make a direct call to a standard callback function by using a statement of the form:

CALL vcStandardCallback@(dlg, "Font")

This is useful when you want to add other instructions before or after the standard callback.

If you call a standard callback by extending the name of a standard menu item or toolbar button (or by using an extended menu) and also CALL vcOnClick@ to add your own callback, then both callbacks are executed in turn with the standard callback coming first (in the case of a menu item you can add more than one callback in addition to the standard callback).

The standard callbacks Open, Save/SaveAs and Print/PrintPreview require additional programming. The callback New may also require additional programming. For example, Open causes the standard Open file dialog to be displayed and needs a process to apply to the file selected by the user (in order words, Open requires a callback to specify what is to be done with the file). Visual ClearWin allows you to provide a suitable process by raising an event. In the case of the Open callback the event is called Open_Child and you must include a Fortran statement of the form:

CALL vcOnEvent@(dlgChild, "Open_Child", LoadFile)

This statement normally appears between vcCreateDialog@ and vcShowDialog@ statements or between vcCreateMdiChild@ and vcShow@ statements. dlgChild is the Dialog, Open_Child is the Visual ClearWin event, and LoadFile is your Fortran callback that provides the process that is to be applied to the file. Within this callback you can get the name of the file by calling vcGetStringData@(dlgChild, "#FileName") or you can call a Visual ClearWin method (such as vcLoadText@ or vcLoadImage@) that uses this name automatically.

Both the standard callbacks New and Open raise a Visual ClearWin event called Create_Child. Open raises Create_Child before Open_Child. New raises only Create_Child. In the callback that you attach to Create_Child you can interrogate either #FileName or #FileType before creating a suitable object (a certain kind of MDI child for example). #FileType provides the extension of the selected file name (e.g. "txt", "rtf", "bmp" etc.). #FileType is set to "[None]" when Create_Child is raised by a call to New.

Both Save and SaveAs raise the event called Save_Child. The callback that you provide defines the saving process. It also uses #FileName for the name of the file and this information is used internally in the Visual ClearWin method vcSaveText@.

Both Print and PrintPreview use an existing Microsoft event that you can link into using the name Print_Child. Print uses a standard Print dialog that must be provided in the design view of your form. Similarly PrintPreview uses a standard PrintPreview dialog that appears in the design view. Both types of dialog must have an attached PrintDocument component selected from the Toolbox.

In the callback that you associate with Print_Child, you can make a single call to a Visual ClearWin method such as vcPrintText@ or PrintImage@. In other cases you must work at a lower level as follows.

Print_Child automatically handles the page numbering of printed documents associated with collating and multiple copies and provides you with the number of the current page and the number of the current copy. This and other information is obtained by a Fortran statement of the form:

pageNo = vcGetIntegerData@(dlgChild, "#PageNumber")

In this context, in addition to #PageNumber you can also use: #CopyNumber, #LeftMargin, #RightMargin, #TopMargin, #BottomMargin, #Height and #Width.

The standard callbacks Exit and Close can be used to fire up a warning message when a document has been changed but not saved. This requires you to set integer data using a statement of the form:

CALL vcSetIntegerData@(dlgChild, "#Modified", 1)

Any non-zero data value will do. In the case of a Text_Box control, for example, you could respond to the TextChanged event with:

CALL vcOnEvent@(dlgChild,"text_Box1","TextChanged",OnChange)

and call vcSetIntegerData@ in the OnChange callback.

For further information see MDI applications.


Graphics drawing

Solution7, Solution8 and Solution16 in the Visual ClearWin demonstration pack illustrate graphics drawing.

Visual ClearWin provides run time graphics drawing via the Silverfrost Drawing_Panel control (select this component from the Toolbox at design time and drop it on to the form). This control provides easy access to drawing functions in the Microsoft GDI+ library. A Drawing_Panel is similar to a PictureBox control in that it provides a bitmap buffer for automatic repainting. It also provides "pivoting", scroll bars and "graphics selections":

Pivoting
A Drawing_Panel control can be "pivoted" - in other words it can be automatically resized. You can respond to a change in size with a statement of the form:

CALL vcOnEvent@(dlg,"SizeChanged",Draw)

The methods that go with a Drawing_Panel control provide access to the standard GDI+ and for the most part use the same names as those in the System.Drawing namespace. Thus, for example, the Visual ClearWin function called vcDrawString@ implements one of the overloaded System.Drawing.DrawString methods. For this reason, much of the detailed documentation is ommitted from this guide and reference is made to the System.Drawing documentation.

Visual ClearWin drawing methods belong to the Silverfrost Drawing class. The current Drawing object is usually obtained by statements of the form:

TYPE(VCdrawing) d
d = vcGetDrawing@(dlg, "drawing_Panel1")

vcResetDrawing@ is an alternative to vcGetDrawing@. vcGetDrawing@ is also used to get the current printing device.

Scroll bars
In simple cases the size of the drawing in a Drawing_Panel is the same as the size of the control. However, the ScrollBars property of a Drawing_Panel allows you to use scrollbars when the drawing is too big for the control. When using scrollbars, you must also use the BitmapSize property to set the size of the bitmap buffer. If you leave this size as (0, 0) then the buffer is sized automatically.

Note that the .NET GDI+ library uses a (red, green, blue) packing order that is the reverse of the conventional order. It also adds an alpha attribute. A 32-bit colour value starts with the alpha attribute as the high byte, then the red component and so on.

Graphics selections
The Selection property of a Silverfrost Drawing_Panel is used to provide a moving line or box when the mouse is dragged over the control. The property takes one of the values None, Line, DashedFrame, ThickFrame, and FilledRectangle. This can be chosen at design time and also at run time by a call of the form:

CALL vcSetProperty@(dlg1,"drawingPanel1","PanelSelection",PanelSelection_Line)

As well as the PanelSelection property, you can also set the PanelSelectionButton property to change from the default left-hand mouse button (using PanelSelectionButton_Right and PanelSelectionButton_Middle) and the PanelSelectionColour property to change from the default background colour (black) to be used when reversing the line.

Your program must stipulate what action is to be taken when the mouse button is released. To do this you make a call of the form:

CALL vcOnEvent@(dlg1,"drawingPanel1","MouseUp",OnMouseUp)

and provide a callback function OnMouseUp. Within the callback function you can get the starting position and the current position of the mouse using:

x1 = vcGetDrawingData@(d,"MouseStartX")

with similar calls using "MouseStartY", "MouseX", and "MouseY" (d is the Silverfrost drawing object being used). All of coordinates are relative to the (0,0) scrolling position.

The drawing of a frame can be followed by a call to vcGraphicsSelection@ in order to display an adjustable selection frame. This can be used to perform standard operations such as copying the selection to the clipboard.

All of these features are illustrated in Solution16 in the demonstration pack.

Here is an overview of drawing methods. d is the Silverfrost Drawing object being used. All other arguments are integer values unless otherwise stated. Note that co-ordinates and dimensions used with strings are usually single precision real values.

Drawing Lines

CALL vcDrawLine@(d, x1, y1, x2, y2) | Draws a straight line from (x1,y1) to (x2,y2).
CALL vcDrawLines@(d, x, y, n) | Draws n straight lines. x and y are arrays defining the points.
CALL vcDrawRectangle@(d, x, y, width, height) | (x, y) is the top left corner.
CALL vcDrawPolygon@(d, x, y, n) | Draws a closed polygon. x and y are arrays defining the points.
CALL vcDrawEllipse@(d, x, y, width, height) | (x, y) is the top left corner of a bounding rectangle.
CALL vcDrawCurve@(d, x, y, n) | Draws a curve joining n points. x and y are arrays defining the points.
CALL vcDrawClosedCurve@(d, x, y, n) | Draws a closed curve joining n points. x and y are arrays defining the points.
CALL vcDrawArc@(d, x, y, width, height, startAngle, sweepAngle) | (x, y) is the top left corner of a bounding rectangle of given width and height.
CALL vcDrawBeziers@(d, x, y, n) | x and y are integer arrays defining the n points.
CALL vcLineRGB@(d, r, g, b) | Sets the (r, g, b) values for subsequent line drawing.
CALL vcLineARGB@(d, argb) | Sets the argb value for subsequent line drawing.
old = LineAlpha@(d, alpha) | Sets the alpha value for subsequent line drawing and returns the old value.
old = vcLineWidth@(d, width) | Sets the REAL(1) line width for subsequent line drawing and returns the old value.
old = vcLineDashStyle@(d, style) | style is an integer parameter.
old = vcLineStartCap@(d, style) | style is an integer parameter.
old = vcLineEndCap@(d, style) | style is an integer parameter.
old = vcCurveTension@(d, tension) | Sets the REAL(1) line tension in the range 0.0 to 1.0 and returns the old value. For DrawCurve and DrawClosedCurve.

Filling regions

CALL vcFillRectangle@(d, x, y, width, height) | (x, y) is the top left corner.
CALL vcFillDrawing@(d) | Fills the whole drawing rectangle with the current fill colour.
CALL vcClear@(d) | Fills the whole drawing rectangle with the current control background colour.
CALL vcFillEllipse@(d, x, y, width, height) | (x, y) is the top left corner of a bounding rectangle
CALL vcFillPolygon@(d, x, y, n) | Fills a closed polygon. x and y are arrays defining the points.
CALL vcFillClosedCurve@(d, x, y, n) | Fills a closed curve joining n points. x and y are arrays defining the points.
CALL vcFillPie@(d, x, y, width, height, startAngle, sweepAngle) | (x, y) is the top left corner of a bounding rectangle of given width and height.
CALL vcFillRGB@(d, r, g, b) | Sets the (r, g, b) values for subsequent filling.
CALL vcFillARGB@(d, argb) | Sets the argb value for subsequent filling.
CALL vcCurveWinding@(d, on) | A non-zero value switches winding on for FillClosedCurve.
old = vcCurveTension@(d, tension) | Sets the REAL(1) line tension for FillClosedCurve in the range 0.0 to 1.0 and returns the old value.

Drawing text

CALL vcDrawString@(d, string, x, y) | (x, y) are REAL(1) values for the position of the string.
CALL vcMeasureString@(d, string, x, y, width, height) | Returns the REAL(1) width and height of the string positioned at REAL(1) (x,y).
CALL vcStringDimensions@(d, width, height) | Sets the REAL(1) string width and height for subsequent calls to vcDrawString@. By default both these values are zero and string dimensions are not applied.
CALL vcStringFontName@(d, name) | Set the font name of the current font.
old = vcStringFontSize@(d, size) | Sets the REAL(1) size of the current font and returns the old value.
CALL vcStringFontStyle@(d, bold, italic, underline, strikeout) | Non-zero values for the integers bold, italic, underline and strikeout cause this attribute to be set for the current font.
CALL vcStringFormat@(d, format, attrib) | format is string taken from a list of named attributes. attrib is an integer parameter taken from a list of possible values for each attribute.
CALL vcStringRGB@(d, r, g, b) | Sets the current (r,g,b) colour value.
CALL vcStringARGB@(d, argb) | Sets the current argb value.
height = vcGetFontHeight@(d) | Gets the current font height as a REAL(1) value.
CALL SetFont@(d, control) | Sets the current font to that of the given control.

Drawing pixels (buffered drawing only)

r = vcSetPixel@(d, x, y, r, g, b) | Sets the current pixel colour to (r,g,b) and draws a pixel at (x,y). Returns zero if successful.
c = vcGetPixel@(d, x, y) | Gets the packed rgb value at (x,y), returning zero (black) if unbuffered.
r = vcDrawPixel@(d, x, y) | Draws the current pixel colour at (x,y). Returns zero if successful.
CALL vcInvalidatePixels@(d) | vcDrawPixel@ and vcSetPixel@ automatically keep a record of the rectangle invalidated by pixel drawing. In exceptional circumstances, vcInvalidatePixels@ can be used to invalidate and reset this rectangle.

Drawing images

r = vcDrawImage@(d, fileName [, x, y]) | Draws an image from the specified file at (x, y). The position is optional and set to zero by default. Returns zero if successful.
CALL vcDrawResource@(d, rscName, x, y) | Draws an image resource at (x,y). rscName is the name of an image resource in a Fortran resource script or an image (usually hidden) in the parent form.

Refreshing regions

CALL vcInvalidateRectangle@(d, x, y, width, height) | Used in exceptional circumstances to invalidate the given rectangle.
CALL vcUpdateDrawing@(d) | Used in exceptional circumstances to immediately update invalidated rectangles.


MDI applications

Multiple and Single Document Applications

A typical illustration of a multiple document interface (MDI) application is a text editor that can open several files simultaneously. Visual Studio is an example of an MDI. Older versions of Microsoft Word used a MDI but the latest versions create a new instance of the application for each file.

Solution10 in the demonstration pack illustrates a MDI application whilst Solution11 presents a single document interface (SDI).

Solution21 illustrates an alternative basis for a MDI application using a Silverfrost Tab_Control. This is described at the end of this topic.

In order to create a MDI application, create a form in the standard manner using the Visual Studio form design view. In the properties of the form, set IsMdiContainer to True.

Now write Fortran code to display the application. This is based on vcCreateDialog@ and vcDisplayDialog@ as for any other application.

Typically the application will Open a file or create a New file and display it in the parent window's client area. The MDI child that is created is based on a form designed for the given type of file. This form is designed in the same way as any other form. The only difference is that (in the Fortran code) it is displayed by calling vcCreateMdiChild@ and vcShow@. This will normally take place in a callback function for the MDI parent. A MDI parent can be used to display different types of MDI children; for example, one for text files and another for image files.

A number of standard callbacks are designed for MDI applications. See standard callbacks for further details.

You can attach a menu to the design of a MDI container for use when there are no child windows attached. You can also attach a menu to the design of a child form in such a way that this replaces the menu for the container when a child of this type is the active MDI child. The simplest way to do this is to use the MergeType called MergeItems for each menu title in the MDI container and the MergeType called Replace for corresponding titles in the child menu. All other items have their default MergeType (Add). In this context a menu title is an item that appears in the menu bar and not in a drop down sub menu.

You can attach a toolbar to the design of a MDI container for use when there are no child windows attached. You can also attach a toolbar to the design of a child form and Visual ClearWin will automatically replace the toolbar for the container when a child of this type is the active MDI child. This is limited to the case where the container and each type of child has just one toolbar.

You can drag and drop files on to a MDI or SDI application. Typically files can be selected in the standard file Explorer and dragged to a Visual ClearWin application. To enable drag and drop in your application requires three steps.

a) In the design view of the form, select the form and then set its AllowDrop property to true.

b) In the main program of your Fortran code, set the static thread attribute by including the line:

ATTRIBUTE(class="System.STAThreadAttribute",target="ROUTINE")

c) If your program uses the "Open" standard callback on a menu item and/or a toolbar button then no additional programming is required because Visual ClearWin drag and drop uses the same mechanism. The "Open" standard callback requires you to call vcOnEvent@ for the events Create_Child and Open_Child and, within the callback, to get the file name by calling vcGetStringData@ using "#Filename". Multiple files can be dropped and each file raises the above two events in turn. Multiple files are handled in a natural manner in a MDI. By default a SDI would open and close each file in turn and leave the last file in the list open. For further information about the "Open" standard callback see Standard Callbacks.

For more information on how to get started with muliple and single document interfaces, run Solution10 and Solution11. These samples can be used as a template for your application.

Using a Tab_Control as a MDI
Solution21 in the demonstration pack shows you how to create a MDI application based on a Silverfrost Tab_Control.

The approach is largely the same as that for a traditional MDI application as described above but the client area takes the form of a Tab_Control. At design time, drop a Tab_Control on to your form and set the IsMdiContainer property to true. The tab pages of this control are used to display various documents at run time. In the design view, each type of document (e.g. plain text, WYSIWYG HTML or graphics) has its own form that is used as a repository for an associaed menu, toolbar and tab page. The tab page is placed in a TabControl or a Tab_Control. At run time, Visual ClearWin transfers these components to the main application as and when required.

Tab page documents can be opened and closed (as in Microsoft Visual Studio) and the menu can display currently open files as well as recently closed files. You can also drag and drop files on to this kind of application as described above.

For further information run and experiment with Solution21.


Web browser

A Silverfrost Explorer_Box control provides easy access to a Microsoft Web Browser that can be used as a browser and also as simple HTML WYSIWYG editor.

When using an Explorer_Box control it is essential that you give your main program the static thread attribute by including the line

ATTRIBUTE(class="System.STAThreadAttribute",target="ROUTINE")

The use of this line with an Explorer_Box is illustrated in solutions 17, 18 and 19 of the Visual ClearWin demonstration pack.

The following functions can be used with an Explorer_Box:

vcWebNavigate@ | Browses to a given URL.
vcWebCommand@ | Issues a browser or HTML editing command.
vcWebQueryStatus@ | Gets the state of an HTML editing command.
vcWebQueryStatusWB@ | Gets the state of a browser command.
vcWebQueryString@ | Gets a string for an HTML edit state.
vcGetDocumentURL@ | Gets the current URL in a browser.
vcIsDocumentDirty@ | Indicates if a document has been modified during editing.
vcClipboardGetDataPresent@ | Tests if data is present on the clipboard.

As an alternative to vcWebCommand@, you can use a standard callback function with the string htm<id> where <id> is the integer identifier of the command. Standard callbacks are called using the subroutine vcStandardCallback@ or via the name of a menu item or toolbar button (see Standard Callbacks).

User's who have Microsoft Office installed on their machine can use this control to view and edit Microsoft Office documents such as Excel and Word documents.


Trouble shooting

Visual ClearWin programming errors usually appear at run time as unhandled exceptions related to Salford.VisualClearWin. The diagnostic information is usually sufficient to identify the error. Error reports use C# method names that do not use the "vc" prefix and the trailing @ symbol.

Some Visual ClearWin routines set an internal integer to indicate the error state. The error state can be obtained by calling vcLastError@ immediately after call to the routine. The relevant routines together with details of corresponding error state values appear in the documentation. Zero is used to indicate success.

.NET provides a very powerful programming environment but occasionally this intrinsic power can cause problems. The following comments may help you to overcome any problems.

1. Spurious build error messages sometimes mean that you need to rebuild the whole solution rather than build the current project.

2. The build order of projects in a solution is usually important. A DLL that is referenced by an application must be built first. To change the order, select Project Dependencies from the popup menu for the solution or one of its projects. In extreme cases it is sometimes possible to have two interdependent projects where neither will build before the other. This probably only occurs when there are interacting DLLs. This kind of problem can only be overcome by creating an intermediate bootstrap build with the critical dependencies removed or by redesigning the structure of the solution.

3. Occasionally a build problem can be fixed by removing and replacing one of the References in a project. This may be necessary, for example, if you upgrade your copy of Salford.VisualClearWin.dll.


Visual ClearWin Library Overview

Library Overview

Common arguments and attributes in Visual ClearWin functions
The Visual ClearWin library is written in C# and run-time error messages refer to the names of C# methods. Functions in the Silverfrost Fortran are identified by the C# name but with the prefix "vc" and the @ symbol at the end. Thus the method AddAccelator appears in Silverfrost Fortran as vcAddAccelerator@. This association of names is defined in VC.ins and VC.mod. You can define a different association if you wish but this help file and the sample programs use Silverfrost Fortran names.

The following arguments are common to many of these functions. They are described here to avoid repetition.

VCdialog dialog | This is an object returned by vcCreateDialog@ or vcCreateMdiChild@. It is an instance of a Visual ClearWin class that encapsulates the System.Windows.Forms class.
STRING controlName | This is the name of the current control as it appears in the design view of the Form.
VCdrawing drawing | This is an object returned by vcGetDrawing@. A drawing is normally associated with a Drawing_Panel control or with a printing process.
EXTERNAL callback | This is the name of an INTEGER FUNCTION that takes no arguments. It may literally be EXTERNAL but is usually a MODULE function.

Other arguments that are specified as having the STRING type are usually presented in programs as Fortran CHARACTER strings. These are automatically converted to .NET strings via an ASSEMBLY_EXTERNAL interface. Interfaces for the library appear in a file called VC.ins. This file also appears as a module in a file called VC.mod which is invoked via the Fortran statement "USE VC". The file called VC.ins also contains type and parameter definitions for Visual ClearWin.

The description of each function in the library often includes a line labelled "Controls" that lists the classes that can be used with this function. In some cases these are not literally controls but components such as menu items. To allow for future development, function names usually take a generic form even when their use is currently limited to one class of control.

The description of a function sometimes includes a line labelled "Error states". Such functions have an internal error state that is stored as a static integer. The value of this integer is returned by vcLastError@. vcLastError@ should be called when the primary function returns. The error state value persists until another function is called that has an error state.

Functions that are described as "static methods" correspond to static C# methods. Non-static methods are "instance methods" which in FTN95 require an object (such as a Visual ClearWin dialog or drawing) for the first argument.


Visual ClearWin Library

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


A

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcAddAccelerator@

Platform | .NET(including Win32)
Purpose | To attach an accelerator key to a callback function.
Syntax | SUBROUTINE vcAddAccelerator@(dialog, itemName, key, callback) VCdialog dialog STRING itemName, key EXTERNAL callback
Description | itemName is a unique name that you provide. This corresponds to the design-view name of a menu item but must be different from any existing name. key is the accelerator key as shown in the design-view properties of a menu item (e.g. "ShiftF1").
See also | vcRemoveAccelerator@


vcAppendLine@

Platform | .NET(including Win32)
Purpose | To append a line of text to the end of a text control.
Syntax | SUBROUTINE vcAppendLine@(dialog, controlName, text) VCdialog dialog STRING controlName, text
Controls | TextBox, Text_Box, RichTextBox, RichText_Box
Description | This routine is similar to vcAppendText@ but adds a linefeed to the text. text is the string to append.
See also |


vcAppendNode@

Platform

.NET(including Win32)

Purpose

To append a child node to the currently selected node of a TreeView.

Syntax

SUBROUTINE vcAppendNode@(dialog, controlName, label)
VCdialog dialog
STRING controlName, label

Controls

TreeView, Tree_View

Description

label is the text to use for the node label.

This routine adds a child node. To append a node to the end of a sibling list you can call vcSelectParentNode@ and then vcAppendNode@. Use vcInsertNode@ to insert a sibling node.

After the call the new node is automatically selected. The routine has no effect if no node is selected.

See also

vcInsertNode@, vcRemoveNode@, vcSelectParentNode@, vcMoveNode@


vcAppendText@

Platform | .NET(including Win32)
Purpose | To append text to the end of a text control.
Syntax | SUBROUTINE vcAppendText@(dialog, controlName, text) VCdialog dialog STRING controlName, text
Controls | TextBox, Text_Box, RichTextBox, RichText_Box
Description | text is the string to append.
See also | vcAppendLine@


vcARGB@

Platform | .NET(including Win32)
Purpose | To pack colour values into an integer.
Syntax | INTEGER FUNCTION vcARGB@(alpha, red, green, blue) INTEGER alpha, red, green, blue
Description | This is a static method. The byte (0 to 255) values are packed in order with the blue value being the least significant. This is the opposite order to that used before .NET. The alpha value indicates the transparency of the colour. The value 255 represents fully opaque and is used, for example, to replace the existing pixel colour with the new colour (thus, for simple drawings, use a value of 255). In some contexts (e.g. in the common colour dialog) the alpha value is not used. For details Search in titles for "Alpha Blending Lines and Fills".
Return value | Returns the packed integer value.


B

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcBlueValue@

Platform | .NET(including Win32)
Purpose | To get the blue component from a packed ARGB integer.
Syntax | INTEGER FUNCTION vcBlueValue@(colour) INTEGER colour
Description | This is a static method.
Return value | Returns the blue component of the given ARGB value.


vcBringToFront@

Platform | .NET(including Win32)
Purpose | To move the dialog to the front of the z-order.
Syntax | SUBROUTINE vcBringToFront@(dialog) VCdialog dialog
Description | This routine is normally used to re-activate a modeless dialog.


C

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcChooseColour@

Platform

.NET(including Win32)

Purpose

To open a common dialog and select a colour for the foreground of a given control.

Syntax

SUBROUTINE vcChooseColour@(dialog, controlName [,colorDlgName])
VCdialog dialog
STRING controlName, colorDlgName

Controls

Any control that has the ForeColor property.

Description

Opens the common colour dialog and sets the ForeColor of the given control to the selected colour.

You must use the design view of the Form to attach a colour dialog component. The name of this component is colorDlgName. This argument is optional and can be ommitted if there is only one common colour dialog.

See also

vcShowColourDialog@


vcChooseFont@

Platform

.NET(including Win32)

Purpose

To open a common dialog and select a font for the given control.

Syntax

SUBROUTINE vcChooseFont@(dialog, controlName [,fontDlgName])
VCdialog dialog
STRING controlName, fontDlgName

Controls

Any control that has the Font property.

Description

Opens the common font dialog and sets the Font of the given control to the selected font.

You must use the design view of the Form to attach a font dialog component. The name of this component is fontDlgName. This argument is optional and can be ommitted if there is only one common font dialog.

Note that if you set the Font property of a RichText control then the font is applied to all the text and not just to the selected text.

See also

vcShowFontDialog@, vcSetControlFont@, vcSetFontName@


vcClear@

Platform | .NET(including Win32)
Purpose | To clear a control.
Syntax | SUBROUTINE vcClear@(dialog, controlName) VCdialog dialog STRING controlName
Controls | TextBox, Text_Box, RichTexBox, RichText_Box, ComboBox, Combo_Box, ListBox, List_Box, CheckedListBox, CheckedList_Box, ListView, List_View, TreeView, Tree_View
Description | Removes all text from a text control, all items from a list or all nodes from a tree.
See also | vcClearDrawing@


vcClearDrawing@

Platform | .NET(including Win32)
Purpose | To fill a Drawing_Panel control using its BackColor.
Syntax | SUBROUTINE vcClearDrawing@(drawing) VCdrawing drawing
Controls | Drawing_Panel
Description | Used when drawing to a Drawing_Panel control to fill the drawing with the BackColor of the control. Has no effect if the drawing is not buffered.
See also | vcFillDrawing@


vcClipboardGetDataPresent@

Platform | .NET(including Win32)
Purpose | To determine if data of a given format is available on the clipboard.
Syntax | LOGICAL FUNCTION vcClipboardGetDataPresent@(format) STRING format
Description | This is a static function. Some standard formats are "Text", "Bitmap", "HTML Format" and "Rich Text Format".
Return value | Returns TRUE if data of the given format is present.


vcCloseDialog@

Platform | .NET(including Win32)
Purpose | To close a modeless dialog.
Syntax | SUBROUTINE vcCloseDialog@(dialog) VCdialog dialog
Description | Closes a modeless dialog that was displayed by a call to vcShow@. Alternatively a dialog is displayed as a modal dialog by calling vcShowDialog@. The modal property means that the dialog remains active and vcShowDialog@ does not return until it is closed by the user.
See also | vcShow@


vcCreateDialog@

Platform

.NET(including Win32)

Purpose

To create a dialog from a given Form.

Syntax

VCdialog FUNCTION vcCreateDialog@(formName)
STRING formName

Description

This is a static method.

formName is, for example, "Resources.Form1", where Resources is the name of a DLL that contains a Form called Form1. The file called Resources.dll must be located in the same directory as the current application. Typically this is a Debug or Release directory for the current Fortran project.

The VCdialog object that is returned can be treated as a handle to use in calls to other Visual ClearWin functions. Typically there will be a sequence of statements to configure the dialog terminating in a call to vcShowDialog@ or vcShow@.

Return value

Returns the VCdialog object that was created.

See also

vcCreateMdiChild@, vcShowDialog@, vcShow@, vcShowMessageBox@


vcCreateMdiChild@

Platform

.NET(including Win32)

Purpose

To create a MDI child dialog from a given Form.

Syntax

VCdialog FUNCTION vcCreateMdiChild@(formName)
STRING formName

Description

formName is, for example, "Resources.Form1", where Resources is the name of a DLL that contains a Form called Form1. The file called Resources.dll must be located in the same directory as the current application. Typically this is a Debug or Release directory for the current Fortran project.

The VCdialog object that is returned can be treated as a handle to use in calls to other Visual ClearWin functions. Typically there will be a sequence of statements to configure the dialog terminating in a call to vcShow@. It is not appropriate to use vcShowDialog@ in this context.

Return value

Returns the VCdialog object that was created.

See also

vcCreateDialog@, vcShow@


vcCurveTension@

Platform

.NET(including Win32)

Purpose

Set the curve tension for subsquent drawing.

Syntax

REAL(1) FUNCTION vcCurveTension@(drawing, tension)
VCdrawing drawing
REAL(1) tension

Description

Sets the curve tension in the range 0.0 to 1.0.

Return value

Returns the previous tension.

See also

vcDrawCurve@, vcDrawClosedCurve@, vcFillClosedCurve@


vcCurveWinding@

Platform | .NET(including Win32)
Purpose | To set the fill mode for subsequent drawing.
Syntax | SUBROUTINE vcCurveWinding@(drawing, on) VCdrawing drawing INTEGER on
Description | If on is zero the fill mode is set to Alternate otherwise Winding.
See also | vcFillClosedCurve@


D

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcDisplayDialog@

Platform

.NET(including Win32)

Purpose

To show a modal dialog.

Syntax

SUBROUTINE vcDisplayDialog@(dialog)
VCdialog dialog

Description

vcDisplayDialog@ is used after vcCreateDialog@. It is not normally used with vcCreateMdiChild@. The function does not return until the user closes the dialog. A parent dialog is disabled whilst the child is open.

vcShowDialog@ is identical to vcDisplayDialog@ but is a function. Use vcShowDialog@ if you need to know which button was clicked in order to close the dialog.


vcDrawArc@

Platform | .NET(including Win32)
Purpose | To draw an arc.
Syntax | SUBROUTINE vcDrawArc@(drawing, x, y, width, height, startAngle, sweepAngle) VCdrawing drawing INTEGER x, y, width, height, startAngle, sweepAngle
Description | Calls DrawArc using the current pen. (x, y) is the top left corner of the bounding rectangle. width and height are its dimensions. Angles are measured in degrees.
See also | vcLineRGB@, vcDrawEllipse@, vcFillPie@


vcDrawBeziers@

Platform

.NET(including Win32)

Purpose

To draw a series of Bézier splines.

Syntax

SUBROUTINE vcDrawBeziers@(drawing, x, y, n)
VCdrawing drawing
INTEGER,PARAMETER::n
INTEGER x(n), y(n)

Description

Calls DrawBeziers using the current pen and joins the point (x(1), y(1)) to (x(4), y(4)) using the intermediate points as data and so on.

Note that (for buffered drawing) vcDrawBeziers@ automatically invalidates a rectangle that bounds the points defining the curve but in extreme cases it is possible that the curve might extend beyond this rectangle. In which case it may be necessary to call vcInvalidateRectangle@ for the extended region.

See also

vcLineRGB@, vcDrawLines@, vcDrawPolygon@, vcDrawCurve@, vcDrawClosedCurve@


vcDrawClosedCurve@

Platform

.NET(including Win32)

Purpose

To draw a closed curve.

Syntax

SUBROUTINE vcDrawClosedCurve@(drawing, x, y, n)
VCdrawing drawing
INTEGER,PARAMETER::n
INTEGER x(n), y(n)

Description

Calls DrawClosedCurve using the current pen and the current curve tension. It joins the point (x(1), y(1)) to (x(2), y(2)) and so on.

Note that (for buffered drawing) vcDrawClosedCurve@ automatically invalidates a rectangle that bounds the points defining the curve but in extreme cases it is possible that the tension might cause the curve to extend beyond this rectangle. In which case it may be necessary to call vcInvalidateRectangle@ for the extended region.

See also

vcLineRGB@, vcCurveTension@, vcDrawCurve@, vcDrawBeziers@


vcDrawCurve@

Platform

.NET(including Win32)

Purpose

To draw a curve.

Syntax

SUBROUTINE vcDrawCurve@ (drawing, x, y, n)
VCdrawing drawing
INTEGER,PARAMETER::n
INTEGER x(n), y(n)

Description

Calls DrawCurve using the current pen and curve tension. It joins the point (x(1), y(1)) to (x(2), y(2)) and so on.

Note that (for buffered drawing) vcDrawCurve@ automatically invalidates a rectangle that bounds the points defining the curve but in extreme cases it is possible that the tension might cause the curve to extend beyond this rectangle. In which case it may be necessary to call vcInvalidateRectangle@ for the extended region.

See also

vcLineRGB@, vcCurveTension@, vcDrawClosedCurve@, vcDrawBeziers@


vcDrawEllipse@

Platform | .NET(including Win32)
Purpose | To draw an ellipse.
Syntax | SUBROUTINE vcDrawEllipse@ (drawing, x, y, width, height) VCdrawing drawing INTEGER x, y, width, height
Description | Calls DrawEllipse using the current pen. (x, y) is the top left corner of the bounding rectangle.
See also | vcLineRGB@, vcFillEllipse@


vcDrawImage@

Platform | .NET(including Win32)
Purpose | To draw an image from a file.
Syntax | SUBROUTINE vcDrawImage@(drawing, fileName [, x, y]) VCdrawing drawing STRING fileName INTEGER x, y
Description | Calls DrawImage using an image given by Image.FromFile. (x, y) marks the position on the drawing of the top left corner of the image. The coordinates are optional and default to zero. Most of the common image formats are supported including BMP, JPEG, GIF, PNG and TIF.
Error states | 1 = the file could not be opened 2 = the image could not be draw
See also | vcDrawResource@


vcDrawLine@

Platform | .NET(including Win32)
Purpose | To draw a line.
Syntax | SUBROUTINE vcDrawLine@ (drawing, x1, y1, x2, y2) VCdrawing drawing INTEGER x1, y1, x2, y2
Description | Calls DrawLine using the current pen. Draws a line connecting (x1, y1) to (x2, y2).
See also | vcLineRGB@, vcDrawLines@


vcDrawLines@

Platform | .NET(including Win32)
Purpose | To draw a sequence of lines.
Syntax | SUBROUTINE vcDrawLines@(drawing, x, y, n) VCW drawing INTEGER,PARAMETER::n INTEGER x(n), y(n)
Description | Calls DrawLines using the current pen. Draws a straight line from (x(1), y(1)) to (x(2), y(2)) and so on.
See also | vcLineRGB@, vcDrawPolygon@


vcDrawPixel@

Platform | .NET(including Win32)
Purpose | Draws a pixel.
Syntax | SUBROUTINE vcDrawPixel@(drawing, x, y) VCdrawing drawing INTEGER x, y
Description | Calls SetPixel using the current pixel colour. It fails if the drawing is unbuffered.
Error states | 1 = the pixel is out of range.
See also | vcSetPixel@, vcInvalidatePixels@


vcDrawPolygon@

Platform | .NET(including Win32)
Purpose | To draw a polygon.
Syntax | SUBROUTINE vcDrawPolygon@(drawing, x, y, n) VCdrawing drawing INTEGER,PARAMETER::n INTEGER x(n), y(n)
Description | Calls DrawPolygon using the current pen. Draws a straight line from (x(1), y(1)) to (x(2), y(2)) and so on to form a closed polygon. The final point does not need to be the same as the first point.
See also | vcLineRGB@, vcDrawLines@


vcDrawRectangle@

Platform | .NET(including Win32)
Purpose | To draw a rectangle.
Syntax | SUBROUTINE vcDrawRectangle@ (drawing, x, y, width, height) VCdrawing drawing INTEGER x, y, width, height
Description | Calls DrawRectangle using the current pen. (x, y) is the top left corner.
See also | vcLineRGB@, vcFillRectangle@


vcDrawResource@

Platform

.NET(including Win32)

Purpose

To draw a resource provided in a resource script or in a Form.

Syntax

SUBROUTINE vcDrawResource@(drawing, rscName, x, y)
VCdrawing drawing
STRING rscName
INTEGER x, y

Description

Calls DrawImage using an image extracted from the given resource. (x, y) is the position in the drawing of the top left corner of the image.

rscName can be the name of a resource given in the RESOURCES section of an FTN95 program. The type of resource is IMAGE (BITMAP is an alternative but is included in IMAGE). For example:

PROGRAM main
!...
END
RESOURCES
myImage IMAGE image.jpg

The alternative is to use the name of PictureBox component in a Form. Using the design view, attach a PictureBox component to the Form and specify an image file. Hide the image from normal viewing. rscName is the name of the component as it appears in the design view.

See also

vcDrawImage@


vcDrawString@

Platform | .NET(including Win32)
Purpose | To draw a string.
Syntax | SUBROUTINE vcDrawString@(drawing, text, x, y) VCdrawing drawing STRING text REAL(1) x, y
Description | Calls DrawString using the current string attributes (font, colour and format). (x, y) is the (single precision real) position in the drawing of the top left corner of the bounding rectangle. You can limit the dimensions of the string to be drawn by a prior call to vcStringDimensions@. In turn this can use information obtained from vcMeasureString@ or vcGetFontHeight@.
See also | vcStringFontSize@, vcStringFontName@, vcStringFontStyle@, vcStringRGB@, vcStringFormat@


E

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcExpandAll@

Platform | .NET(including Win32)
Purpose | To expand or collapse all the nodes in a tree.
Syntax | SUBRUOTINE vcExpandAll@(dialog, controlName, expand) VCdialog dialog STRING controlName LOGICAL expand
Controls | TreeView, Tree_View
Description | expand is set to TRUE to expand all the nodes in the tree or to FALSE to collapse all the nodes.


F

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcFillARGB@

Platform | .NET(including Win32)
Purpose | To set the ARGB value for subsequent filling processes.
Syntax | SUBROUTINE vcFillARGB@(drawing, argb) VCdrawing drawing INTEGER argb
Description | argb is the packed colour value with the alpha value as the most significant byte and the blue value as the least significant.
See also | vcFillRGB@


vcFillClosedCurve@

Platform

.NET(including Win32)

Purpose

To fill a closed curve.

Syntax

SUBROUTINE vcFillClosedCurve@(drawing, x, y, n)
VCdrawing drawing
INTEGER,PARAMETER::n
INTEGER x(n), y(n)

Description

Calls FillClosedCurve using the current brush, winding mode and curve tension. It joins the point (x(1), y(1)) to (x(2), y(2)) and so on.

Note that (for buffered drawing) vcFillClosedCurve@ automatically invalidates a rectangle that bounds the points defining the curve but in extreme cases it is possible that the tension might cause the curve to extend beyond this rectangle. In which case it may be necessary to call vcInvalidateRectangle@ for the extended region..

See also

vcFillRGB@, vcCurveWinding@, vcCurveTension@, vcDrawClosedCurve@


vcFillDrawing@

Platform | .NET(including Win32)
Purpose | To fill the drawing using the current brush.
Syntax | SUBROUTINE vcFillDrawing@(drawing) VCdrawing drawing
Description | Calls FillRectangle using the current brush and the dimensions of the drawing.
See also | vcClearDrawing@


vcFillEllipse@

Platform | .NET(including Win32)
Purpose | To fill an ellipse.
Syntax | SUBROUTINE vcFillEllipse@(drawing, x, y, width, height) VCdrawing drawing INTEGER x, y, width, height
Description | Calls FillEllipse using the current brush. (x, y) is the top left corner of the bounding rectangle.
See also | vcFillRGB@, vcDrawEllipse@


vcFillPie@

Platform | .NET(including Win32)
Purpose | To fill a sector of a circle.
Syntax | SUBROUTINE vcFillPie@(drawing, x, y, width, height, startAngle, sweepAngle) VCdrawing drawing INTEGER x, y, width, height, startAngle, sweepAngle
Description | Calls FillPie using the current brush. (x, y) is the top left corner of the bounding rectangle. width and height are its dimensions. Angles are measured in degrees.
See also | vcFillRGB@, vcDrawArc@


vcFillPolygon@

Platform | .NET(including Win32)
Purpose | To fill a polygon.
Syntax | SUBROUTINE vcFillPolygon@(drawing, x, y, n) VCdrawing drawing INTEGER,PARAMETER::n INTEGER x(n), y(n)
Description | Calls FillPolygon using the current brush. Fills the closed polygon obtained by drawing a straight line from (x(1), y(1)) to (x(2), y(2)) and so on. The final point does not need to be the same as the first point.
See also | vcFillRGB@, vcDrawPolygon@


vcFillRectangle@

Platform | .NET(including Win32)
Purpose | To fill a rectangle.
Syntax | SUBROUTINE vcFillRectangle@(drawing, x, y, width, height) VCdrawing drawing INTEGER x, y, width, height
Description | Calls FillRectangle using the current brush. (x, y) is the top left corner.
See also | vcFillRGB@, vcDrawRectangle@


vcFillRGB@

Platform | .NET(including Win32)
Purpose | To set the RGB value for subsequent filling processes.
Syntax | SUBROUTINE vcFillRGB@(drawing, r, g, b) VCdrawing drawing INTEGER r, g, b
Description | Sets the alpha value to 255 (fully opaque) and uses the supplied red, green and blue components. The values are packed into a 32 bit integer with the alpha value as the most significant byte and the blue value as the least significant.
See also | vcFillARGB@


vcFindText@

Platform

.NET(including Win32)

Purpose

To find a string in a text box control.

Syntax

INTEGER FUNCTION vcFindText@(dialog, controlName, str, options)
VCdialog dialog
STRING controlName, str
INTEGER options

Controls

Text_Box, RichTextBox, RichText_Box

Description

vcFindText@ searches for str. If it is found (by default) the first occurrence is highlighted and scrolled into view. options is given by adding together one or more of the parameters: FindText_MatchCase, FindText_WholeWord, FindText_Reverse, FindText_None and FindText_NoHighlight.

FindText_Reverse searches upwards rather than downwards.
FindText_None is used on its own and represents the combined default options.
FindText_NoHighlight means that a string that is found is not selected and scrolled into view.

For a forward search the search begins at the end of the current selection. For a reverse search it begins at the start of the current selection.

The search automatically wraps to the start or end of the document. Nominal error states indicate when this has happened.

Return value

Returns -1 if the string cannot be found, otherwise returns the zero-based index of the first character in the selection (i.e. the character index relative to the start of the document).

Error states

1 = the search has passed the end of the document
2 = the search has passed the beginning of the document


vcFocus@

Platform | .NET(including Win32)
Purpose | To set the focus to a given control.
Syntax | SUBROUTINE vcFocus@(dialog, controlName) VCdialog dialog STRING controlName
Controls | Any control that can take the focus.


G

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcGetActiveMdiChild@

Platform | .NET(including Win32)
Purpose | To get the currently active MDI child dialog.
Syntax | VCdialog FUNCTION vcGetActiveMdiChild@(dialog) VCdialog dialog
Return value | Returns the active child in a Multi Documnet Interface program.


vcGetCaption@

Platform | .NET(including Win32)
Purpose | To get the caption for a dialog.
Syntax | STRING FUNCTION vcGetCaption@(dialog) VCdialog dialog
Return value | Returns the caption as a string.
See also | vcSetCaption@


vcGetControlSize@

Platform | .NET(including Win32)
Purpose | To get the size of a given control.
Syntax | SUBROUTINE vcGetControlSize@(dialog, controlName, width, height) VCdialog dialog INTEGER width, height
Description | Returns the size of the given control in width and height.


vcGetDocumentURL@

Platform | .NET(including Win32)
Purpose | To get the current URL in a web browser.
Syntax | STRING FUNCTION vcGetDocumentURL@(dialog, controlNname) VCWDialog dialog STRING controlName
Controls | Explorer_Box
Description | When using an Explorer_Box as a web browser, vcGetDocumentURL@ will get the URL of the current web page. This function should be called in response to a "DocumentComplete" event.
Return value | Returns the current URL.
See also | vcWebNavigate@


vcGetDouble@

Platform | .NET(including Win32)
Purpose | To get the DOUBLE value for a control.
Syntax | REAL(2) FUNCTION vcGetDouble@(dialog, controlName) VCdialog dialog STRING controlName
Controls | Double_Box, Double_UpDown, Decimal_UpDown.
Return value | Returns the REAL(2) value associated with the given control.
See also | vcSetDouble@, vcLinkDouble@, vcRefreshDouble@


vcGetDoubleData@

Platform | .NET(including Win32)
Purpose | To get data stored in the dialog.
Syntax | REAL(2) FUNCTION vcGetDoubleData@(dialog, dataName) VCdialog dialog STRING dataName
Description | dataName identifies the data as used in a prior call to vcSetDoubleData@. Names beginning with # are reserved.
Return value | Returns the value stored using vcSetDoubleData@.
See also | vcSetDoubleData@


vcGetDrawing@

Platform | .NET(including Win32)
Purpose | To get a drawing object.
Syntax | VCdrawing FUNCTION vcGetDrawing@(dialog [,controlName]) VCdialog dialog STRING controlName
Controls | Drawing_Panel, PrintDocument
Description | controlName is the name of a Drawing_Panel. When it is ommitted the active print document is used.
Return value | Returns a drawing object for use in Visual ClearWin drawing functions.
See also | vcResetDrawing@


vcGetDrawingData@

Platform

.NET(including Win32)

Purpose

To get drawing data.

Syntax

INTEGER FUNCTION vcGetDrawingData@(drawing, dataName)
VCdrawing drawing
STRING dataName

Description

dataName identifies the data to be retrieved as follows. Mouse coordinate values include the current ScrollX and ScrollY values.

MouseX | the x pixel coordinate of the current mouse position
MouseY | the y pixel coordinate of the current mouse position
MouseStartX | the x pixel coordinate at the beginning of the current graphics selection
MouseStartY | the y pixel coordinate at the beginning of the current graphics selection
ScrollX | the value attached to the horizontal scrollbar
ScrollY | the value attached to the vertical scrollbar

Return value

Returns the data value.

See also

vcGraphicsSelection@


vcGetDrawingSize@

Platform | .NET(including Win32)
Purpose | To get the size of a drawing.
Syntax | SUBROUTINE vcGetDrawingSize@(dialog, controlName, width, height) VCdialog dialog STRING controlName INTEGER width, height
Controls | Drawing_Panel
Description | Returns the size in width and height. The dimensions are based on the size of the control adjusted to accommodate the style of the border.


vcGetFontHeight@

Platform | .NET(including Win32)
Purpose | To get the current font height in a drawing.
Syntax | REAL(1) FUNCTION vcGetFontHeight@(drawing) VCdrawing drawing
Return value | Returns the height of the current font in this drawing.


vcGetFontName@

Platform | .NET(including Win32)
Purpose | To get the name of the font for a given control.
Syntax | STRING FUNCTION vcGetFontName@ (dialog, controlName) VCdialog dialog STRING controlName
Controls | Any control that has the Font property.
Return value | Returns the name of the font family as a string.


vcGetInteger@

Platform | .NET(including Win32)
Purpose | To get the INTEGER value for a control.
Syntax | INTEGER FUNCTION vcGetInteger@(dialog, controlName) VCdialog dialog STRING controlName
Controls | Int32_Box, Check_Box, Radio_Button, TrackBar, Track_Bar, TabControl, Tab_Control, ListBox, List_Box, ComboBox, Combo_Box, List_View, Tree_View, ProgressBar, Decimal_UpDown, NumbericUpDown.
Return value | Returns the INTEGER value associated with the control. Depending on the type of control, this is either the value of the number displayed or the index of the currently selected item.
See also | vcSetInteger@, vcLinkInteger@, vcRefreshInteger@


vcGetIntegerArray@

Platform | .NET(including Win32)
Purpose | To get the array of selected items for a control.
Syntax | SUBROUTINE vcGetIntegerArray@(dialog, controlName, array) VCdialog dialog STRING controlName INTEGER array(:)
Controls | List_Box and List_View (when in multi-select mode), CheckedList_Box
Description | Populates the array with integer values obtained from the given control. The array must be large enough to accommodate all of the rows of the control. The elements of the array are set to 1 if the row is selected (or checked) otherwise zero. The first element of the array corresponds to the first row.
See also | vcSetIntegerArray@, vcLinkIntegerArray@, vcRefreshIntegerArray@


vcGetIntegerData@

Platform

.NET(including Win32)

Purpose

To get data stored in the dialog.

Syntax

INTEGER FUNCTION vcGetIntegerData@(dialog, dataName)
VCdialog dialog
STRING dataName

Description

dataName identifies the data as used in a prior call to vcSetIntegerData@ or as defined by Visual ClearWin data. Names beginning with # are reserved. Here is a list of reserved names:

#PageNumber | page number of current printing process
#CopyNumber | copy number of current printing process
#LeftMargin | left margin of current printing process
#RightMargin | right margin of current printing process
#TopMargin | top margin of current printing process
#BottomMargin | bottom margin of current printing process
#Height | page height of current printing process
#Width | page width of current printing process
#NodeItem | index of the currently selected Tree_View item
#Modified | marks a document as having changed since the last save
#Item | index of the current item in a label editing event
#Column | index of the current column in a column click event
#MouseButton | button pressed in a mouse event
#MouseX | x coordinate in a mouse event
#MouseY | y coordinate in a mouse event
#MouseClicks | number of clicks in a mouse event
#MouseDelta | number of detents in a mouse wheel event
#HelpRequestedMousePosX | x coordinate for a HelpRequested event
#HelpRequestedMousePosY | y coordinate for a HelpRequested event
#KeyUpDownKeyValue | keyboard value of a KeyUp or KeyDown event
#KeyUpDownModifiers | keyboard modifiers (ALT, CTRL, SHIFT) of a KeyUp or KeyDown event
#KeyPressKeyChar | keyboard character for a KeyPress event

Return value

Returns the value stored using vcSetIntegerData@.

See also

vcSetIntegerData@


vcGetNodeData@

Platform | .NET(including Win32)
Purpose | To get data for the currently selected node in a TreeView.
Syntax | STRING FUNCTION vcGetNodeData@(dialog, controlName) VCdialog dialog STRING controlName
Controls | TreeView, Tree_View
Description | This function gets data that was stored using vcSetNodeData@.
Return value | Returns the data in the form of a string.
Error states | 1 = a node is not selected 2 = data has not been stored in this node
See also | vcSetNodeData@, vcSetNodeState@, vcGetNodeFullPath@


vcGetNodeFullPath@

Platform

.NET(including Win32)

Purpose

To get the full path of the currently selected node in a TreeView.

Syntax

STRING FUNCTION vcGetNodeFullPath@(dialog, controlName)
VCdialog dialog
STRING controlName

Controls

TreeView, Tree_View

Description

The full path can be used to identify the currently selected node. It is a string consisting of the node label prefixed by the labels of all of its parent nodes in turn. The default separator is a single backslash character (\).

Note: If the tree does not change at run time then it is simpler to identify a node by its index (see vcLinkInteger@ and vcGetInteger@).

Return value

Returns the full path of the currently selected node.


vcGetPixel@

Platform | .NET(including Win32)
Purpose | The get the RGB value of a given pixel.
Syntax | INTEGER FUNCTION vcGetPixel@(drawing, x, y) VCdrawing drawing INTEGER x, y
Description | vcGetPixel@ fails if the drawing is unbuffered. The values are packed with blue as the least significant byte. The alpha component ommitted (i.e. set to zero).
Return value | Returns the packed RGB value for the given pixel.


vcGetStringData@

Platform

.NET(including Win32)

Purpose

To get data stored in the dialog.

Syntax

STRING FUNCTION vcGetStringData@(dialog, dataName)
VCdialog dialog
STRING dataName

Description

dataName identifies the data. Names beginning with # are reserved. Here is a list of current reserved names.

#Event | the event that triggered this callback
#Sender | the control/menu item/toolbar button that triggered this callback
#NodeFullPath | the full path of the currently selected tree node
#NodeLabel | the label of the currently selected tree node
#NodeData | the data for the currently selected tree node
#Label | the new label at the end of a label edit event
#FileName | the file name used (for example) in the Open and Save standard callbacks
#FileType | the file type used (for example) in the New standard callback (you can set this value)
#File | the file name supplied by vcShowFilesDialog@
#Caption | you set this value to specify an extended caption for a MDI child

Return value

Returns the value stored using vcSetStringData@.

See also

vcSetStringData@


vcGetText@

Platform

.NET(including Win32)

Purpose

To get the text for a control or meu item.

Syntax

STRING FUNCTION vcGetText@(dialog, controlName [, int rowIndex[, int columnIndex]])
VCdialog dialog
STRING controlName
INTEGER rowIndex, columnIndex

Controls

Any control that has the Text property. Also ListView, List_View, TreeView, Tree_View, menu item, StatusBarPanel.

Description

If the optional arguments (rowIndex and columnIndex) are ommitted, a ListView, List_View, TreeView or Tree_View yields the label of the currently selected item.

If a (zero-based) rowIndex but not a columnIndex is supplied then the text for the given row is returned. This can be used with the following controls: TextBox, Text_Box, RichTextBox, RichText_Box, ComboBox, Combo_Box, ListBox, List_Box, CheckedListBox, CheckedList_Box, ListView, List_View, Tree_View.

When both a rowIndex and columnIndex are supplied, vcGetText@ can only be used with a ListView or List_View control. Both indexes are zero based.

Return value

Returns the given string.

Error states

1 = rowIndex is too large
2 = columnIndex is too large

See also

vcSetText@, vcLinkText@, vcRefreshText@


vcGetTextFontFamily@

Platform | .NET(including Win32)
Purpose | To get the font name of the current selection in a RichText control.
Syntax | STRING FUNCTION vcGetTextFontFamily@(dialog, controlName) VCdialog dialog STRING controlName
Controls | RichText, Rich_Text
Return value | Returns the name as a string.


vcGetTextSize@

Platform | .NET(including Win32)
Purpose | To get the font size of the current selection in a RichText control.
Syntax | REAL(1) FUNCTION vcGetTextSize@(dialog, controlName) VCdialog dialog STRING controlName
Controls | RichText, Rich_Text
Return value | Returns the size as a single precision real value.


vcGraphicsCompositingMode@

Platform

.NET(including Win32)

Purpose

To specify how source colours are combined with background colours.

Syntax

INTEGER FUNCTION vcGraphicsCompositingMode@(drawing, mode)
VCdrawing drawing
INTEGER mode

Description

Calls CompositingMode. mode is one of the parameter values: CompositingMode_SourceOver and CompositingMode_SourceCopy.

SourceCopy overwrites the background. SourceOver blends with the background using the alpha component.

See also: Using Compositing Mode to Control Alpha Blending.

Return value

Returns the previous mode.


vcGraphicsCompositingQuality@

Platform | .NET(including Win32)
Purpose | To set the rendering quality level of composited images.
Syntax | INTEGER FUNCTION vcGraphicsCompositingQuality@(drawing, level) VCdrawing drawing INTEGER level
Description | Calls CompositingQuality. level is one of the parameter values CompositingQuality_Default, CompositingQuality_HighSpeed, CompositingQuality_HighQuality, CompositingQuality_GammaCorrected, CompositingQuality_AssumeLinear. See also:Drawing Opaque and Semitransparent Lines.
Return value | Returns the previous level.


vcGraphicsInterpolationMode@

Platform | .NET(including Win32)
Purpose | To set the interpolation mode.
Syntax | INTEGER FUNCTION vcGraphicsInterpolationMode@ (drawing, mode) VCdrawing drawing INTEGER mode
Description | Calls InterpolationMode. mode is one of the parameter values: InterpolationMode_Default, InterpolationMode_Low, InterpolationMode_High, InterpolationMode_Bilinear, InterpolationMode_Bicubic, InterpolationMode_NearestNeighbor, InterpolationMode_HighQualityBilinear, InterpolationMode_HighQualityBicubic. See also: Using Interpolation Mode to Control Image Quality During Scaling.
Return value | Returns the previous mode.


vcGraphicsSelection@

Platform

.NET(including Win32)

Purpose

To provide operations on a selected rectangular region of a drawing panel.

Syntax

SUBROUTINE vcGraphicsSelection@(dialog, controlName, operation)
VCdialog dialog
STRING controlName, operation

Controls

Drawing_Panel

Description

This routine is normally used after setting the Selection property of a Drawing_Panel to Dashed_Frame. This can be done at design time or at run time using a call of the form:

CALL vcSetProperty@(dlg1,"drawingPanel1","PanelSelection",PanelSelection_DashedFrame)

vcGraphicsSelection@ is first used in response to a MouseUp event with a call of the form:

CALL vcGraphicsSelection@(dlg1,"drawingPanel1","Show")

This displays a resizing frame whose size and position can be adjusted. Moving the frame also moves the enclosed drawing. vcGraphicsSelection@ is also used with the following operations many of which relate to the current position of the resizing frame.

Cut | Cuts the current selection to the clipboard.
Copy | Copies the current selection to the clipboard.
Delete | Deletes the current selection.
SelectAll | Selects the whole drawing.
Paste | Pastes contents of the clipboard ready for dragging to its destination.
PasteFrom | Displays the standard Open dialog and pastes a file ready for dragging to its destination.
CopyTo | Displays the standard Save dialog and copies the current selection to the given file.

These operations are also available as standard callbacks in the form "DrawingCut", "DrawingCopy", etc.

In order to use the clipboard your main Fortran program must have the System.STAThreadAttribute attribute. This can be assigned by including the following line in your main program.

ATTRIBUTE(class="System.STAThreadAttribute",target="ROUTINE")

See also

Graphics drawing, Standard callbacks, vcGetDrawingData@


vcGreenValue@

Platform | .NET(including Win32)
Purpose | To get the green component from a packed ARGB integer.
Syntax | INTEGER FUNCTION vcGreenValue@(colour) INTEGER colour
Description | This is a static method.
Return value | Returns the green component of the given ARGB value.


I

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcImageIndex@

Platform | .NET(including Win32)
Purpose | To select an image index for subsequent calls to certain ListView and TreeView functions.
Syntax | SUBROUTINE vcImageIndex@(dialog, index [, selectedIndex]) VCdialog dialog INTEGER index, selectedIndex
Controls | ListView, List_View, TreeView, Tree_View
Description | Selects the image index for subsequent additions to using certain ListView and TreeView functions. The optional selectedIndex argument is applied only to subsequent additions to TreeView controls. By default it has the same value as index.
See also | vcInsert@, vcAppendNode@, vcInsertNode@


vcInsert@

Platform

.NET(including Win32)

Purpose

To insert a row into a control.

Syntax

INTEGER FUNCTION vcInsert@(dialog, controlName, text, index [, caseSensitive])
VCdialog dialog
STRING controlName, text
INTEGER index, caseSensitive

Controls

ComboBox, Combo_box, ListBox, List_Box, CheckedListBox, CheckedList_Box, ListView, List_View

Description

index is the zero-based row index of the item before which the new row is inserted. If index is less than zero or greater than the number of existing items, then the row is appended to the end of the list (unless the control has the Sorted property that is set to true). text is the text/label to use.

If the control is a ListView or List_View and the text contains pipe symbols (|) then these are used to separate the text in the respective columns in the "Details" view of the control.

caseSensitive is an optional argument to use with a ListBox (List_Box) or ComboBox (Combo_box) control. If it is ommitted items are always inserted (the default value is -1). If it has the value 1 then a new item is inserted if it is different from any existing item in the list (the test for equality is case-sensitive). The same is true if it has the value zero but now the test is case-insensitive (thus "Item1" will not be inserted if "item1" is already in the list).

Return value

Returns the index of the inserted item or the duplicate item if one is already present.

See also

vcRemove@


vcInsertMenuItem@

Platform

.NET(including Win32)

Purpose

To insert a menu item at run time.

Syntax

SUBROUTINE vcInsertMenuItem@(dialog, newName, existingName, text, callback [, after])
VCdialog dialog
STRING newName, existingName, text
EXTERNAL callback
LOGICAL after

Controls

MenuItem

Description

Menus are normally constructed in the design view of the Form. In exceptional situations you may need a menu that has a structure that changes under program control. One common example of this a menu that includes a list of "Recent files" (this is implemented in the RecentFiles standard callback).

newName is a unique name that you provide that corresponds to the name of a menu item in a Form design view. existingName is a name from the design view or from an earlier call to this routine. text is the string to use in the item and callback is the name of the function to call when the user clicks on this item. after is optional and defaults to FALSE. When it is set to TRUE, the new item is inserted after the existing item.

See also

vcRemoveMenuItem@, vcSetMenuAccelerator@, vcMenuTip@, vcSetChecked@, vcSetEnabled@


vcInsertNode@

Platform | .NET(including Win32)
Purpose | To insert a node in a TreeView before the currently selected node.
Syntax | SUBROUTINE vcInsertNode@(dialog, controlName, label) VCdialog dialog STRING controlName, label
Controls | TreeView, Tree_View
Description | Inserts a sibling node before the currently selected node. It has no effect if a node is not selected. label is the text to use for the label.
See also | vcAppendNode@, vcRemoveNode@, vcSelectParentNode@, vcMoveNode@


vcInvalidatePixels@

Platform

.NET(including Win32)

Purpose

To invalidate an internal rectangle that bounds pixels that have been drawn.

Syntax

SUBROUTINE vcInvalidatePixels@(drawing)
VCdrawing drawing

Description

Pixels can be drawn to a buffered drawing by calling vcDrawPixel@ and/or vcSetPixel@. Calls to these two functions automatically update a rectangle that bounds all of the pixels that have been drawn since the last call to vcInvalidatePixels@.

A call to vcInvalidatePixels@ adds this rectangle to the list of rectangles that is processed when a paint event is implemented. Paint events normally occur without prompting but in exceptional circumstances you can force a paint event by calling vcUpdateDrawing@. For example, this may be necessary if your drawing commands are followed by a large amount of continuous processing.

See also

vcDrawPixel@, vcSetPixel@, vcUpdateDrawing@


vcInvalidateRectangle@

Platform

.NET(including Win32)

Purpose

To invalidate a given rectangle.

Syntax

SUBROUTINE vcInvalidateRectangle@(drawing, x, y, width, height)
VCdrawing drawing
INTEGER x, y, width, height

Description

Buffered drawing automatically causes the bounding rectangle to be invalidated. In exceptional cases the bounding rectangle is too small. For example, in a call to vcDrawClosedCurve@ the curve might extend beyond the bounding rectangle for some values of the curve tension. In such cases it may be necessary to call vcInvalidateRectangle@ for the extra regions.

If width or height is set to zero then the whole drawing is invalidated.

A call to vcInvalidateRectangle@ adds the given rectangle to a list that is automatically processed in response to a paint event. Paint events normally occur without prompting but in exceptional circumstances you can force a paint event by calling vcUpdateDrawing@. For example, this may be necessary if your drawing commands are followed by a large amount of continuous processing.

See also

vcUpdateDrawing@, vcInvalidatePixels@


vcIsChecked@

Platform | .NET(including Win32)
Purpose | To determine if a control or menu item is checked.
Syntax | LOGICAL FUNCTION vcIsChecked@(dialog, controlName) VCdialog dialog STRING controlName
Controls | Menu item, CheckBox, Check_Box, RadioButton, Radio_Button
Return value | Returns TRUE if the component is checked ("on" for a RadioButton) otherwise FALSE.
See also | vcSetChecked@


vcIsDocumentDirty@

Platform | .NET(including Win32)
Purpose | To test if an HTML document has been modified.
Syntax | LOGICAL FUNCTION vcIsDocumentDirty@(dialog, controlName) VCWDialog dialog STRING controlName
Controls | Explorer_Box
Description | This function is used in an HTML editor to test if the document has been modified since it was opened or last saved. The use of this function is illustrated in Solution 18 of the Visual ClearWin demonstration pack.
Return value | Returns TRUE if the document has been modified since it was last saved.


vcIsEnabled@

Platform | .NET(including Win32)
Purpose | To determine if a component is enabled.
Syntax | LOGICAL FUNCTION vcIsEnabled@(dialog, controlName) VCdialog dialog STRING controlName
Controls | Menu item, ToolBarButton, Timer, any control that has the Enabled property.
Return value | Returns TRUE if the component is enabled otherwise FALSE.
See also | vcSetEnabled@


vcIsNodeState@

Platform | .NET(including Win32)
Purpose | To get the state of the currently selected node in a TreeView.
Syntax | LOGICAL FUNCTION vcIsNodeState@(dialog, controlName, state) VCdialog dialog STRING controlName, state
Controls | TreeView, Tree_View
Description | state is one of "Checked", "Editing", "Expanded", "Selected", and "Visible". "Checked" can be used when a TreeView has the CheckBoxes property set to true. "Editing" indicates whether the label is currently being edited. "Expanded" indicates if the node is currently expanded or collapsed. "Selected" indicates if the node is selected. "Visible" indicates if the node can be seen. Alternatively the control must be scrolled to bring it into view.
Return value | Returns TRUE if a node is selected and the given state is true otherwise FALSE.
Error states | 1 = a node is not selected


vcIsNull@

Platform | .NET(including Win32)
Purpose | To test if an object is null.
Syntax | LOGICAL vcIsNull@(obj) OBJECT obj
Description | This is a static method. You can use this function (together with vcNullify@) to test if a Dialog is closed.
Return value | Returns TRUE if the object is null.
See also | vcNullify@


vcIsPushed@

Platform | .NET(including Win32)
Purpose | To determine if a ToolBarButton is pushed.
Syntax | LOGICAL FUNCTION vcIsPushed@(dialog, controlName) VCdialog dialog STRING controlName
Controls | ToolBarButton
Return value | Returns TRUE if the button is pushed otherwise FALSE.
See also | vcSetPushed@


vcIsTextState@

Platform | .NET(including Win32)
Purpose | To get the attributes of the current RichTextBox selection.
Syntax | LOGICAL FUNCTION vcIsTextState@(dialog, controlName, attribute) VCdialog dialog STRING controlName, attribute
Controls | RichTextBox, RichText_Box
Description | attribute is one of "Bold", "Italic", "Underline", and "Strikeout".
Return value | Returns TRUE if the attribute is true for the current selection or caret position, otherwise FALSE.


L

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcLastError@

Platform | .NET(including Win32)
Purpose | To get the error state of the last function called that has an error state.
Syntax | INTEGER FUNCTION vcLastError@()
Description | This is a static method. Some Visual ClearWin library functions have an internal error state that is stored as a static integer. The value of this integer is returned by vcLastError@. vcLastError@ should be called when the primary function returns. The error state persists until another function with an error state is called.
Return value | Returns zero if there was no error or a non-zero value representing the error. Error states are provided with the associated functions.


vcLineARGB@

Platform | .NET(including Win32)
Purpose | To set the ARGB value for subsequent line drawing.
Syntax | SUBROUTINE vcLineARGB@(drawing, argb) VCdrawing drawing INTEGER argb
Description | argb is the packed colour value with the alpha value as the most significant byte and the blue value as the least significant.
See also | vcLineRGB@


vcLineDashStyle@

Platform | .NET(including Win32)
Purpose | To set the dash style for subsequent line drawing.
Syntax | INTEGER FUNCTION vcLineDashStyle@(drawing, style) VCdrawing drawing INTEGER style
Description | style is one of the parameter values DashStyle_Solid, DashStyle_Dash, DashStyle_Dot, DashStyle_DashDot, DashStyle_DashDotDot, DashStyle_Custom.
Return value | Returns the previous style.
See also | vcLineStartCap@, vcLineEndCap@


vcLineEndCap@

Platform | .NET(including Win32)
Purpose | To set the end cap style for subsequent line drawing.
Syntax | INTEGER FUNCTION vcLineEndCap@(drawing, style) VCdrawing drawing INTEGER style
Description | style is one of the parameter values LineCap_Flat, LineCap_Square, LineCap_Round, LineCap_Triangle, LineCap_NoAnchor, LineCap_SquareAnchor, LineCap_RoundAnchor, LineCap_DiamondAnchor, LineCap_ArrowAnchor, LineCap_AnchorMask, LineCap_Custom.
Return value | Returns the previous style.
See also | vcLineStartCap@


vcLineRGB@

Platform | .NET(including Win32)
Purpose | To set the RGB value for subsequent line drawing.
Syntax | SUBROUTINE vcLineRGB@(drawing, r, g, b) VCdrawing drawing INTEGER r, g, b
Description | Sets the alpha value to 255 (fully opaque) and uses the supplied red, green and blue components. The values are packed into a 32 bit integer with the alpha value as the most significant byte and the blue value as the least significant.
See also | vcLineARGB@


vcLineStartCap@

Platform | .NET(including Win32)
Purpose | To set the start cap style for subsequent line drawing.
Syntax | INTEGER FUNCTION vcLineStartCap@(drawing, style) VCdrawing drawing INTEGER style
Description | style is one of the parameter values LineCap_Flat, LineCap_Square, LineCap_Round, LineCap_Triangle, LineCap_NoAnchor, LineCap_SquareAnchor, LineCap_RoundAnchor, LineCap_DiamondAnchor, LineCap_ArrowAnchor, LineCap_AnchorMask, LineCap_Custom.
Return value | Returns the previous style.
See also | vcLineEndCap@


vcLineWidth@

Platform

.NET(including Win32)

Purpose

To set the width for subsequent line drawing.

Syntax

REAL(1) FUNCTION vcLineWidth@(drawing, width)
VCdrawing drawing
REAL(1) width

Return value

Returns the previous width.


vcLinkGridBoolean@

Platform | .NET(including Win32)
Purpose | To link a Fortran variable to a property of a Property_Grid control.
Syntax | SUBROUTINE vcLinkGridBoolean@(dialog, controlName, label, k) VCdialog dialog STRING controlName, label INTEGER k
Controls | Property_Grid
Description | label is the name of a True/False property in a Property_Grid. k is a Fortran integer that is linked directly to the given property in the control. Automatic refreshing (see vcLinkInteger@) is always provided. See PropertyGrid Controls for further information.
See also | vcLinkGridInteger@, vcLinkGridDouble@, vcLinkGridText@, vcLinkGridColour@, vcLinkGridFont@


vcLinkGridColour@

Platform | .NET(including Win32)
Purpose | To link a Fortran variable to a property of a Property_Grid control.
Syntax | SUBROUTINE vcLinkGridColour@(dialog, controlName, label, k) VCdialog dialog STRING controlName, label INTEGER k
Controls | Property_Grid
Description | label is the name of a Color property in a Property_Grid (by default the alpha value is 255). k is a Fortran integer that is linked directly to the given property in the control. Automatic refreshing (see vcLinkInteger@) is always provided. See PropertyGrid Controls for further information.
See also | vcLinkGridInteger@, vcLinkGridDouble@, vcLinkGridText@, vcLinkGridBoolean@, vcLinkGridFont@


vcLinkGridDouble@

Platform | .NET(including Win32)
Purpose | To link a Fortran variable to a property of a Property_Grid control.
Syntax | SUBROUTINE vcLinkGridDouble@(dialog, controlName, label, x) VCdialog dialog STRING controlName, label REAL(2) x
Controls | Property_Grid
Description | label is the name of a property in a Property_Grid. x is a Fortran real variable that is linked directly to the given property in the control. Automatic refreshing (see vcLinkInteger@) is always provided but changes made by the user in the Property_Grid only take effect when the focus is changed to another property or another control. Also the data is not validated until the focus is lost. See PropertyGrid Controls for further information.
See also | vcLinkGridInteger@, vcLinkGridText@, vcLinkGridBoolean@, vcLinkGridColour@, vcLinkGridFont@


vcLinkGridFont@

Platform | .NET(including Win32)
Purpose | To link a Fortran variable to a property of a Property_Grid control.
Syntax | SUBROUTINE vcLinkGridFont@(dialog, controlName, label, font) VCdialog dialog STRING controlName, label CHARACTER(LEN=*) font
Controls | Property_Grid
Description | label is the name of a property in a Property_Grid. font is a Fortran character string that is linked directly to the given property in the control. Automatic refreshing (see vcLinkText@) is always provided. The character string "Arial, 9.25" corresponds to the 9.25pt font with typeface name "Arial". See PropertyGrid Controls for further information.
See also | vcLinkGridInteger@, vcLinkGridDouble@, vcLinkGridText@, vcLinkGridBoolean@, vcLinkGridColour@


vcLinkGridInteger@

Platform | .NET(including Win32)
Purpose | To link a Fortran variable to a property of a Property_Grid control.
Syntax | SUBROUTINE vcLinkGridInteger@(dialog, controlName, label, k) VCdialog dialog STRING controlName, label INTEGER k
Controls | Property_Grid
Description | label is the name of a property in a Property_Grid. k is a Fortran integer that is linked directly to the given property in the control. Automatic refreshing (see vcLinkInteger@) is always provided but changes made by the user in the Property_Grid only take effect when the focus is changed to another property or another control. Also the data is not validated until the focus is lost. See PropertyGrid Controls for further information.
See also | vcLinkGridDouble@, vcLinkGridText@, vcLinkGridBoolean@, vcLinkGridColour@, vcLinkGridFont@


vcLinkGridText@

Platform | .NET(including Win32)
Purpose | To link a Fortran variable to a property of a Property_Grid control.
Syntax | SUBROUTINE vcLinkGridText@(dialog, controlName, label, text) VCdialog dialog STRING controlName, label CHARACTER(LEN=*) text
Controls | Property_Grid
Description | label is the name of a property in a Property_Grid. text is a Fortran character string that is linked directly to the given property in the control. Automatic refreshing (see vcLinkText@) is always provided but changes made by the user in the Property_Grid only take effect when the focus is changed to another property or another control. See PropertyGrid Controls for further information.
See also | vcLinkGridInteger@, vcLinkGridDouble@, vcLinkGridBoolean@, vcLinkGridColour@, vcLinkGridFont@


vcLinkDouble@

Platform

.NET(including Win32)

Purpose

To link a Fortran variable to a property of a control.

Syntax

SUBROUTINE vcLinkDouble@(dialog, controlName, x [, refresh])
VCdialog dialog
STRING controlName
REAL(2) x
LOGICAL refresh

Controls

Double_Box, Double_UpDown, Decimal_UpDown

Description

A REAL(2) value in the Fortran code can be associated with a control by using either vcGetDouble@ with vcSetDouble@ or by using vcLinkDouble@ with vcRefreshDouble@.

vcLinkDouble@ is called only once when the form is configured (e.g. immediately after a call to vcCreateDialog@). It creates a continuous link with the effect that the Fortran variable is immediately and automatically updated each time a valid double value is entered into the control.

The optional argument refresh defaults to TRUE. vcRefreshDouble@ can be used to refresh relevant controls after a Fortran variable has been changed. However, when refresh is TRUE, relevant controls are automatically refreshed when every callback returns. This means that calls to vcRefreshDouble@ are not needed except in the exceptional situation where a significant amount of continuous processing occurs before the current callback returns.

vcLinkDouble@ also has the effect of linking two controls that share the same Fortran variable. Thus when a valid REAL number is entered into one control the same value will be automatically copied to the linked control.

See also

vcRefreshDouble@, vcGetDouble@, vcSetDouble@


vcLinkInteger@

Platform

.NET(including Win32)

Purpose

To link a Fortran variable to a property of a control.

Syntax

SUBROUTINE vcLinkInteger@(dialog, controlName, k [, refresh])
VCdialog dialog
STRING controlName
INTEGER k
LOGICAL refresh

Controls

Int32_Box, Check_Box, Radio_Button, Track_Bar, Tab_Control, List_Box, Combo_Box, List_View, Tree_View, Decimal_UpDown

Description

A INTEGER value in the Fortran code can be associated with a control by using either vcGetInteger@ with vcSetInteger@ or by using vcLinkInteger@ with vcRefreshInteger@.

vcLinkInteger@ is called only once when the form is configured (e.g. immediately after a call to vcCreateDialog@). It creates a continuous link with the effect that the Fortran variable is immediately and automatically updated each time a valid integer value is entered into the control.

The optional argument refresh has a default value of TRUE. vcRefreshInteger@ can be used to refresh relevant controls after a Fortran variable has been changed. However, when refresh is TRUE, relevant controls are automatically refreshed when every callback returns. This means that calls to vcRefreshInteger@ are not needed except in the exceptional situation where a significant amount of continuous processing occurs before the current callback returns.

vcLinkInteger@ also has the effect of linking two controls that share the same Fortran variable. Thus when a valid INTEGER number is entered into one control the same value will be automatically copied to a linked control. For example, an Int32_Box could be linked to a Track_Bar in this way.

When used with a Check_Box or Radio_Button, the integer represents the state of the control (1 for checked/on, otherwise zero). Note that you cannot link an integer to the checked state of a menu item.

When used with a List_Box, Combo_Box, List_View or Tree_View, the integer represents the zero-based index of the currently selected item. The value -1 means that no item is selected. The index for a Tree_View is provided internally by Visual ClearWin and is intended for use with static trees (i.e. trees that do not grow dynamically at run time).

See also

vcRefreshInteger@, vcGetInteger@, vcSetInteger@


vcLinkIntegerArray@

Platform

.NET(including Win32)

Purpose

To link a Fortran array to a property of a control.

Syntax

SUBROUTINE vcLinkIntegerArray@(dialog, controlName, array [, refresh])
VCdialog dialog
STRING controlName
INTEGER array(:)
LOGICAL refresh

Controls

List_Box, CheckedList_Box, List_View

Description

This routine is used with controls that can have multiple selections. A value of 1 for an array element indicates that the item with this index is currently selected.

An integer array in the Fortran code can be associated with a control by using either vcGetIntegerArray@ with vcSetIntegerArray@ or by using vcLinkIntegerArray@ with vcRefreshIntegerArray@.

vcLinkIntegerArray@ is called only once when the form is configured (e.g. immediately after a call to vcCreateDialog@). It creates a continuous link with the effect that the Fortran array is immediately and automatically updated each time an item is selected in the control.

The optional argument refresh has the default value FALSE. It is recommended that vcRefreshIntegerArray@ be used to refresh relevant controls after a Fortran array has been changed. However, if refresh is set to TRUE, relevant controls will be automatically refreshed when every callback returns. This will cause a significant overhead for large arrays.

See also

vcRefreshIntegerArray@, vcGetIntegerArray@, vcSetIntegerArray@


vcLinkText@

Platform

.NET(including Win32)

Purpose

To link a Fortran CHARACTER variable to a property of a control.

Syntax

SUBROUTINE vcLinkText@(dialog, controlName, text)
SUBROUTINE vcLinkTextEx@(dialog, controlName, text, refresh)
VCdialog dialog
STRING controlName
CHARACTER(LEN=*) text
INTEGER refresh

Controls

Text_Box, RichText_Box, Combo_Box

Description

A CHARACTER variable in the Fortran code can be associated with a control by using either vcGetText@ with vcSetText@ or by using vcLinkText@ with vcRefreshText@.

vcLinkText@ is called only once when the form is configured (e.g. immediately after a call to vcCreateDialog@). It creates a continuous link with the effect that the Fortran variable is immediately and automatically updated each time a text is changed in the control.

The vcLinkTextEx@ argument refresh represents two states; zero is used for FALSE, any other value represents TRUE. Its default value is TRUE for single line edit boxes and comboboxes otherwise FALSE. vcRefreshText@ can be used to refresh relevant controls after a Fortran variable has been changed. However, when refresh is set to TRUE, relevant controls are automatically refreshed when every callback returns. This means that calls to vcRefreshText@ are not needed except in the exceptional situation where a significant amount of continuous processing occurs before the current callback returns.

Note that vcLinkText@ (particularly with automatic refreshing) is not recommended for multi-line controls because the overhead could be significant.

vcLinkText@ also has the effect of linking two controls that share the same Fortran variable. Thus when the text is changed in one control the same text will be automatically copied to the linked control.

See also

vcRefreshText@, vcGetText@, vcSetText@


vcLoadImage@

Platform | .NET(including Win32)
Purpose | To display an image from a file in a Drawing_Panel.
Syntax | SUBROUTINE vcLoadImage@ (dialog, controlName [, fileName]) VCdialog dialog STRING controlName, fileName
Controls | Drawing_Panel
Description | Calls vcDrawImage@ using the drawing associated with the given Drawing_Panel. If fileName is ommitted then the file associated with the dialog is used. This is given by vcGetStringData@(dialog, "#FileName") and is used by standard callback functions such as Open, Save and SaveAs.
Error states | See vcDrawImage@


vcLoadText@

Platform

.NET(including Win32)

Purpose

To display text from a file in a control.

Syntax

SUBROUTINE vcLoadText@(dialog, controlName [, fileName])
VCdialog dialog
STRING controlName, fileName

Controls

TextBox, Text_Box, RichTextBox, RichText_Box

Description

Reads the file into the given control. If the control is a RichTextBox (or RichText_Box) and the file extension is .rtf then it is read as rich text. If fileName is ommitted then the file associated with the dialog is used. This is given by vcGetStringData@(dialog, "#FileName") and is used by standard callback functions such as Open, Save and SaveAs.

Warnings:
1. The process for loading an rtf file is exceedingly slow. A file of modest size might take several minutes to load. This is a Microsoft limitation.

2. Plain text files can be of any size provided you set the MaxLength to zero. The loading of large files might be rather slow. This is because vcLoadText@ is not yet fully optimised for plain text.

Error states

Reserved. A non-zero value indicates that the file could not be opened or that it has the wrong file format (perhaps an rtf file with an invalid header).

See also

vcSaveText@


vcLoadTree@

Platform | .NET(including Win32)
Purpose | To display a tree from a file in a TreeView control.
Syntax | SUBROUTINE vcLoadTree@(dialog, controlName [, fileName]) VCdialog dialog STRING controlName, fileName
Control | TreeView, Tree_View
Description | Reads the file into the given control. The format of the file is the same as that used by vcSaveTree@. If fileName is ommitted then the file associated with the dialog is used. This is given by vcGetStringData@(dialog, "#FileName") and is used by standard callback functions such as Open, Save and SaveAs.
Error states | 1 = the file could not be opened
See also | vcSaveTree@


M

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcMeasureString@

Platform | .NET(including Win32)
Purpose | To get the dimensions of text to be drawn.
Syntax | SUBROUTINE vcMeasureString@(drawing, text, x, y, width, height) VCdrawing drawing STRING text REAL(1) x, y, width, height
Description | Calls MeasureString using the current font and string format. (x, y) are input values giving the position of the top left corner of the bounding rectangle for the text. width and height are returned with the resulting dimensions. The string format is specified in a prior call to vcStringFormat@.
See also | vcGetFontHeight@, vcStringFormat@, vcStringFontSize@ etc.


vcMenuImage

Platform

.NET(including Win32)

Purpose

To specify the image for a menu item.

Syntax

SUBROUTINE vcMenuImage@(dialog, menuItemName, index)
VCdialog dialog
STRING menuItemName
INTEGER index

Description

Menu item images are normally specified at design time using enhanced menus. vcMenuImage@ can be used to change an image dynamically or to add an image following a call to vcInsertMenuItem.

index is the zero-based index of the image in the ImageList attached to the enhanced menu. menuItemName is the name of an existing menu item (either in the design view or in a prior call to vcInsertMenuItem@).

See also

vcInsertMenuItem@, vcSetMenuAccelerator@, vcMenuTip@


vcMenuTip@

Platform

.NET(including Win32)

Purpose

To specify a menu tip for a new menu item.

Syntax

SUBROUTINE vcMenuTip@(dialog, panelName, menuItemName, tip)
VCdialog dialog
STRING panelName, menuItemName, tip

Description

Menu item tips are normally specified at design time. vcMenuTip@ can be used to change a tip dynamically or to add a tip following a call to vcInsertMenuItem@.

Menu tips require a status bar. If the status bar has panels then the tip appears in the first panel. A tip for a given menu item automatically appears in the status bar when the menu item is highlighted by the user.

panelName is the name of a StatusBar and menuItemName is the name of an existing menu item (either in the design view or in a prior call to vcInsertMenuItem@).

See also

vcInsertMenuItem@, vcSetMenuAccelerator@, vcMenuImage@


vcMorePages@

Platform | .NET(including Win32)
Purpose | To control the printing of the PrintDocument that is currently being printed.
Syntax | SUBROUTINE vcMorePages@(more) LOGICAL more
Description | vcMorePages@ is used whilst a document is being printed to control the printing of further pages of the document. The current page and copy number can be obtained by calling vcGetIntegerData@. Given this information you can draw relevant page data to the drawing obtained by calling vcGetDrawing@. If this is the last page to be drawn then add a call to vcMorePages@(.FALSE.) in order to terminate the current printing process.


vcMoveNode@

Platform

.NET(including Win32)

Purpose

To move the currently selected node in a TreeView.

Syntax

SUBROUTINE vcMoveNode@(dialog, controlName, direction)
VCdialog dialog
STRING controlName, direction

Controls

TreeView, Tree_View

Description

direction is one of "Up", "Down", "Right", and "Left". The routine has no effect is no node is selected or if the move is not possible or is not permitted.

You cannot move a node below the end or above the beginning of the current list of siblings. The first child cannot be moved to the right.

See also

vcInsertNode@, vcAppendNode@, vcRemoveNode@


N

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcNullify@

Platform | .NET(including Win32)
Purpose | To set an object to null.
Syntax | SUBROUTINE vcNullify@(obj) OBJECT obj
Description | This is a static method. obj is any .NET object. You can apply this routine to a Dialog object in order to mark it as closed.
See also | vcIsNull@


O

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcOnClick@

Platform

.NET(including Win32)

Purpose

To specify a callback for a click event.

Syntax

SUBROUTINE vcOnClick@(dialog, controlName, callback)
SUBROUTINE vcOnClick@(dialog, controlName, stdCallback)
VCdialog dialog
STRING controlName, stdCallback
EXTERNAL callback

Controls

Menu item, Button, ToolBarButton, CheckBox, Check_Box, RadioButton, Radio_Button, ProgressBar

Description

vcOnClick@ is called once for each relevant control when the dialog is configured (e.g. immediately after a call to vcCreateDialog@).

callback is the name of the Fortran function that contains the code to be executed when the user clicks on the given item.

Standard callback functions are normally attached to menu item or toolbar buttons in the design view. However, you can also attach a standard callback in your code by setting stdCallback to its name.

vcOnClick@ is a special case of vcOnEvent@.

See also

vcOnEvent@


vcOnEvent@

Platform

.NET(including Win32)

Purpose

To specify a callback for a given event.

Syntax

SUBROUTINE vcOnEvent@(dialog, [controlName,] event, callback)
VCdialog dialog
STRING controlName, event
EXTERNAL callback

Description

vcOnEvent@ is called once for each relevant control and event when the dialog is configured (e.g. immediately after a call to vcCreateDialog@).

If controlName is present the event relates to this control otherwise it relates to the form.

event is the name of the event as it appears in the design-view Properties dialog. Select the form or a particular control and then, in the Properties dialog, click on the Events button (with the lightning image). You will then see a list of events such as "Click", "TextChanged", "KeyDown", "MouseDown" and "Resize", any of which can potentially be used. Internal interfaces are provided for most events but not necessarily all of them.


vcOnPrintPage@

Platform | .NET(including Win32)
Purpose | To specify a callback in which to draw to the current printer page.
Syntax | SUBROUTINE vcOnPrintPage@ (dialog, document, callback) VCdialog dialog STRING document EXTERNAL callback
Description | This routine provides the name of the callback function that is to be called whilst a PrintDocument is being printed. The callback is automatically called once for each printed page and you code specifies what is to be drawn. Within the callback, information such as the current page and copy number can be obtained by calls to vcGetIntegerData@ and the printer drawing is given by vcGetDrawing@. document is the name of a PrintDocument component attached in the design-view of the form.


P

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcPopulateFontCombo@

Platform | .NET(including Win32)
Purpose | To populate a ComboBox with the names of all the available fonts.
Syntax | SUBROUTINE vcPopulateFontCombo@(dialog, controlName) VCdialog dialog STRING controlName
Controls | ComboBox, Combo_Box
Description | Calls InstalledFontCollection and uses the result to populate the given ComboBox.


vcPrintDrawing@

Platform

.NET(including Win32)

Purpose

To print the drawing from the given Drawing_Panel.

Syntax

SUBROUTINE vcPrintDrawing@(dialog, controlName)
VCdialog dialog
STRING controlName

Controls

Drawing_Panel

Description

This routine can only be called during a printing process. A printing process can be started in one of two standard ways:

1. By using the "Print" standard callback. This raises the "Print_Child" event that you link into by calling vcOnEvent@(dialog, "Print_Child", OnPrint) where OnPrint is your callback function that calls vcPrintDrawing@.

2. By calling vcOnPrintPage@(dialog, document, OnPrint) and then vcShowPrintDialog@. vcOnPrintPage@ adds your callback (OnPrint) to the document information and should only be called once for each PrintDocument component. Your code for OnPrint can then call vcPrintDrawing@.

A call to vcPrintDrawing@ prints one page.


vcPrintText@

Platform

.NET(including Win32)

Purpose

To print all the text in the given text box control.

Syntax

SUBROUTINE vcPrintText@ (dialog, controlName)
VCdialog dialog
STRING controlName

Controls

TextBox, Text_Box, RichTextBox, RichText_Box

Description

This routine can only be called during a printing process. A printing process can be started in one of two standard ways:

1. By using the "Print" standard callback. This raises the "Print_Child" event that you link into by calling vcOnEvent@(dialog, "Print_Child", OnPrint) where OnPrint is your callback function that calls vcPrintText@.

2. By calling vcOnPrintPage@(dialog, document, OnPrint) and then vcShowPrintDialog@. vcOnPrintPage@ adds your callback (OnPrint) to the document information and should only be called once for each PrintDocument component. Your code for OnPrint can then call vcPrintText@.

A call to vcPrintText@ prints the whole document with automatic paging. There is no line wrapping and RichText is currently printed as plain monochrome text.


vcProgress@

Platform | .NET(including Win32)
Purpose | To provide a progress bar on a StatusBar.
Syntax | SUBROUTINE vcProgress@(dialog, yes) VCdialog dialog LOGICAL yes
Description | The first call takes the form vcProgress@(dialog, .TRUE.). This creates and displays an empty progress bar in the Form's StatusBar. If the StatusBar has panels then the progress bar is located in the first panel. Subsequent calls to vcProgress@ (with yes still set to TRUE) advances the progress indicator by one "blob" each time. Finally a call to vcProgress@(dialog, .FALSE.) hides the progress bar.


R

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcRedValue@

Platform | .NET(including Win32)
Purpose | To get the red component from a packed ARGB integer.
Syntax | INTEGER FUNCTION vcRedValue@(colour) INTEGER colour
Description | This is a static method.
Return value | Returns the red component of the given ARGB value.


vcRefreshDouble@

Platform | .NET(including Win32)
Purpose | To refresh controls that have been linked to a REAL(2) variable.
Syntax | SUBROUTINE vcRefreshDouble@(dialog, x) VCdialog dialog REAL(2) x
Controls | Double_Box, Double_UpDown, Decimal_UpDown
Description | vcRefreshDouble@ is only meaningful after a call to vcLinkDouble@ for the same variable x. If the call to vcLinkDouble@ did not provide for automatic refreshing then, when x has changed its value, vcRefreshDouble@ is used to refresh all controls that are linked to x. Automatic refreshing takes place when the callback returns. If there is a significant amount of continuos processing to be carried out before the callback returns then vcRefreshDouble@ can be called to avoid a delay.
See also | vcLinkDouble@


vcRefreshInteger@

Platform | .NET(including Win32)
Purpose | To refresh controls that have been linked to an INTEGER variable.
Syntax | SUBROUTINE vcRefreshInteger@(dialog, k) VCdialog dialog INTEGER k
Controls | Int32_Box, Check_Box, Radio_Button, Track_Bar, Tab_Control, List_Box, Combo_Box, List_View, Tree_View, Decimal_UpDown
Description | vcRefreshInteger@ is only meaningful after a call to vcLinkInteger@ for the same variable k. If the call to vcLinkInteger@ did not provide for automatic refreshing then, when k has changed its value, vcRefreshInteger@ is used to refresh all controls that are linked to k. Automatic refreshing takes place when the callback returns. If there is a significant amount of continuos processing to be carried out before the callback returns then vcRefreshInteger@ can be called to avoid a delay.
See also | vcLinkInteger@


vcRefreshIntegerArray@

Platform

.NET(including Win32)

Purpose

To refresh controls that have been linked to an INTEGER array.

Syntax

SUBROUTINE vcRefreshIntegerArray@(dialog, array)
VCdialog dialog
INTEGER array(:)

Controls

List_Box, CheckedList_Box, List_View

Description

vcRefreshIntegerArray@ is only meaningful after a call to vcLinkIntegerArray@ for the same array.

If the call to vcLinkIntegerArray@ did not provide for automatic refreshing then, when the array has changed, vcRefreshIntegerArray@ is used to refresh all controls that are linked to the array. Automatic refreshing takes place when the callback returns. If there is a significant amount of continuos processing to be carried out before the callback returns then vcRefreshIntegerArray@ can be called to avoid a delay.

See also

vcLinkIntegerArray@


vcRefreshText@

Platform | .NET(including Win32)
Purpose | To refresh controls that have been linked to a CHARACTER variable.
Syntax | SUBROUTINE vcRefreshText@(dialog, text) VCdialog dialog CHARACTER(LEN=*) text
Controls | Text_Box, RichText_Box, Combo_Box
Description | vcRefreshText@ is only meaningful after a call to vcLinkText@ for the same variable text. If the call to vcLinkText@ did not provide for automatic refreshing then, when text has changed its value, vcRefreshText@ is used to refresh all controls that are linked to text. Automatic refreshing takes place when the callback returns. If there is a significant amount of continuos processing to be carried out before the callback returns then vcRefreshText@ can be called to avoid a delay.
See also | vcLinkText@


vcRemove@

Platform | .NET(including Win32)
Purpose | To delete a line in a control.
Syntax | SUBROUTINE vcRemove@(dialog, controlName, index) VCdialog dialog STRING controlName INTEGER index
Controls | ComboBox, Combo_box, ListBox, List_Box, CheckedListBox, CheckedList_Box, ListView, List_View, Tree_View
Description | index is the zero-base index of the row to remove.
Error states | 1 = index is greater than or equal to the number of rows 2 = index is less than zero
See also | vcInsert@, vcClear@


vcRemoveAccelerator@

Platform | .NET(including Win32)
Purpose | To remove an accelerator key added using vcAddAccelerator@.
Syntax | SUBROUTINE vcRemoveAccelerator@(dlg, item) VCdialog dlg STRING item
Description | item is the item name used in vcAddAccelerator@.
See also | vcAddAccelerator@


vcRemoveMenuItem@

Platform | .NET(including Win32)
Purpose | To remove a menu item at run time.
Syntax | SUBROUTINE vcRemoveMenuItem@(dialog, existingName) VCdialog dialog STRING existingName
Controls | MenuItem
Description | existingName is the name used in a prior call to vcInsertMenuItem@.
See also | vcInsertMenuItem@


vcRemoveNode@

Platform | .NET(including Win32)
Purpose | To remove the currently selected node and its descendents from a TreeView.
Syntax | SUBROUTINE vcRemoveNode@(dialog, controlName) VCdialog dialog STRING controlName
Controls | TreeView, Tree_View
Description | The routine has no effect if no node is selected.
See also | vcAppendNode@, vcInsertNode@


vcReplaceText@

Platform | .NET(including Win32)
Purpose | To replace the currently selected text.
Syntax | SUBROUTINE vcReplaceText@(dialog, controlName, replacement) VCdialog dialog STRING controlName, replacement
Controls | TextBox, Text_Box, RichTextBox, RichText_Box
Description | Replaces the current selection with replacement. If there is currently no selection then the new text is inserted at the current caret position.


vcResetDrawing@

Platform | .NET(including Win32)
Purpose | To get and reset a drawing object.
Syntax | VCdrawing FUNCTION vcResetDrawing@(dialog, controlName) VCdialog dialog STRING controlName
Controls | Drawing_Panel
Description | controlName is the name of a Drawing_Panel. A buffered drawing is reset. This means that: 1. the line, fill and string colours for the control are reset to their default (design-view) values. 2. if the control has increased in size then the size of the internal bitmap is increased to fit. 3. the drawing is cleared using the BackColor of the control.
Return value | Returns a drawing object for use in Visual ClearWin drawing functions.
See also | vcGetDrawing@


S

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcSaveImage@

Platform | .NET(including Win32)
Purpose | To save a drawing to a file.
Syntax | SUBROUTINE vcSaveImage@(dialog, controlName [, fileName]) VCdialog dialog STRING controlName, fileName
Controls | Drawing_Panel
Description | Saves the drawing to the given file. If fileName is ommitted then the file associated with the dialog is used. This is given by vcGetStringData@(dialog, "#FileName") and is used by standard callback functions such as Open, Save and SaveAs.
Error states | 1 = the file could not be opened or the writing process failed.
See also | vcLoadImage@


vcSaveText@

Platform | .NET(including Win32)
Purpose | To save the text in a control to a file.
Syntax | SUBROUTINE vcSaveText@(dialog, controlName [, fileName]) VCdialog dialog STRING controlName, fileName
Controls | TextBox, Text_Box, RichTextBox, RichText_Box
Description | Saves the text in the control to the given file. If the control is a RichTextBox (or RichText_Box) and the file extension is .rtf then it is saved as rich text. If fileName is ommitted then the file associated with the dialog is used. This is given by vcGetStringData@(dialog, "#FileName") and is used by standard callback functions such as Open, Save and SaveAs.
Error states | 1 = the file could not be opened or the writing process failed.
See also | vcLoadText@


vcSaveTree@

Platform

.NET(including Win32)

Purpose

To save a tree to a file.

Syntax

SUBROUTINE vcSaveTree@(dialog, controlName [, fileName])
VCdialog dialog
STRING controlName, fileName

Controls

TreeView, Tree_View

Description

Saves the tree in the control to the given file. If fileName is ommitted then the file associated with the dialog is used. This is given by vcGetStringData@(dialog, "#FileName") and is used by standard callback functions such as Open, Save and SaveAs.

Information for each node in turn is stored in text form. This includes its label and data, the current expand/collapse state and the currently selected node. Here is the format:

Label|Level|State|ImageIndex|SelectedIndex|Data

Fields are separated by a pipe (|) symbpl. Label and Data are strings. Other items are integers. Level gives the level of the node in the tree (zero for a root node, 1 for the first child etc.) State is a combination of 1 (expanded) 2 (checked) and 4 (selected). ImageIndex is the zero-based index of the node icon in the ImageList attached to the control. SelectedIndex is usually the same as ImageIndex.

Error states

1 = the file could not be opened

See also

vcLoadTree@


vcSelectParentNode@

Platform | .NET(including Win32)
Purpose | To select the parent of the currently selected node in a TreeView.
Syntax | SUBROUTINE vcSelectParentNode@(dialog, controlName) VCdialog dialog STRING controlName
Controls | TreeView, Tree_View
Description | This routine has no effect if a node is not selected. If the node is at the top level then the selection is removed. This is the appropriate behaviour when it is used together with vcAppendNode@ in order to add a sibling node.
See also | vcAppendNode@


vcSetCaption@

Platform | .NET(including Win32)
Purpose | To set the caption for a dialog.
Syntax | SUBROUTINE vcSetCaption@(dialog, text) VCdialog dialog STRING text
Description | Sets the caption to the given text.
See also | vcGetCaption@


vcSetChecked@

Platform | .NET(including Win32)
Purpose | To set the checked state of a control or menu item.
Syntax | SUBROUTINE vcSetChecked@(dialog, controlName, state) VCdialog dialog STRING controlName LOGICAL state
Controls | Menu item, CheckBox, Check_Box, RadioButton, Radio_Button
Description | If state is FALSE the item is unchecked, otherwise checked ("on" for a RadioButton).
See also | vcIsChecked@


vcSetControlFont@

Platform

.NET(including Win32)

Purpose

To set the font in a control.

Syntax

SUBROUTINE vcSetControlFont@(dialog, controlName [, fontDlgName])
VCdialog dialog
STRING controlName, fontDlgName

Controls

Drawing_Panel, any control that has the Font property.

Description

Sets the font in the given control to the font obtained from the given font dialog. If the ShowColor property of the FontDialog is enabled then the ForeColor of the control is also set. If the control is a Drawing_Panel then the font for subsequent string drawing is also set accordingly.

fontDlgName is the name of a FontDialog component in the design-view of the form. If there is only one FontDialog component then this argument can be ommitted.

The font that is used will be the font given at design time or (if the FontDialog has been opened) the font selected by the user.

See also

vcChooseFont@, vcSetFontName@, vcShowFontDialog@


vcSetCursor@

Platform

.NET(including Win32)

Purpose

To set the Cursor property of a control at run time.

Syntax

SUBROUTINE vcSetCursor@(dialog, controlName, cursor)
VCdialog dialog
STRING controlName, cursor

Controls

Any control that has the Cursor property.

Description

The default cursor is set in the design-view of the form. This can be changed at run time by calling vcSetCursor@.

cursor is one of "Arrow", "Cross", "IBeam" etc. These are listed in the drop-down list for the Cursor property in the Properties dialog for the control in the design-view.


vcSetDouble@

Platform | .NET(including Win32)
Purpose | To set the DOUBLE value in a control.
Syntax | SUBROUTINE vcSetDouble@(dialog, controlName, x) VCdialog dialog STRING controlName REAL(2) x
Controls | Double_Box, Double_UpDown, Decimal_UpDown
Description | Sets the REAL(2) value in the given control.
See also | vcGetDouble@, vcLinkDouble@, vcRefreshDouble@


vcSetDoubleData@

Platform | .NET(including Win32)
Purpose | To set data stored in the dialog.
Syntax | SUBROUTINE vcSetDoubleData@(dialog, dataName, x) VCdialog dialog STRING dataName REAL(2) x
Description | dataName identifies the data for subsquent calls to vcGetDoubleData@. Names beginning with # are reserved.
See also | vcGetDoubleData@


vcSetEnabled@

Platform | .NET(including Win32)
Purpose | To set the enabled state of a component.
Syntax | SUBROUTINE vcSetEnabled@(dialog, controlName, state) VCdialog dialog STRING controlName LOGICAL state
Controls | Menu item, ToolBarButton, Timer, any control that has the Enabled property.
Description | If state is FALSE the component is disabled, otherwise it is enabled.
See also | vcIsEnabled@


vcSetFontName@

Platform | .NET(including Win32)
Purpose | To set the family name for the font in a control or FontDialog.
Syntax | SUBROUTINE vcSetFontName@(dialog, controlName, familyName) VCdialog dialog STRING controlName, familyName
Controls | FontDialog, any control that has the Font property.
Description | Use this routine to set the font in a control or to set the default name in a FontDialog before calling vcShowFontDialog@ or vcChooseFont@.
See also | vcChooseFont@, vcShowFontDialog@, vcSetControlFont@


vcSetInteger@

Platform | .NET(including Win32)
Purpose | To set the INTEGER value in a control.
Syntax | SUBROUTINE vcSetInteger@(dialog, controlName, k) VCdialog dialog STRING controlName INTEGER k
Controls | Int32_Box, Check_Box, Radio_Button, TrackBar, Track_Bar, TabControl, Tab_Control, ListBox, List_Box, ComboBox, Combo_Box, List_View, Tree_View, ProgressBar, Decimal_UpDown, NumbericUpDown
Description | Sets the INTEGER value in the given control. Depending on the type of control, this is either the value of the number displayed or the index of the currently selected item.
See also | vcGetInteger@, vcLinkInteger@, vcRefreshInteger@


vcSetIntegerArray@

Platform | .NET(including Win32)
Purpose | To set the array of selected items in a control.
Syntax | SUBROUTINE vcSetIntegerArray@(dialog, controlName, array) VCdialog dialog STRING controlName INTEGER array(:)
Controls | List_Box and List_View (when in multi-select mode), CheckedList_Box
Description | Sets the selected items in the control. The array must be large enough to accommodate all of the rows of the control. A row is selected (or checked) if the corresponding item in the array non-zero. The first element of the array corresponds to the first row of the control.
See also | vcGetIntegerArray@, vcLinkIntegerArray@, vcRefreshIntegerArray@


vcSetIntegerData@

Platform | .NET(including Win32)
Purpose | To set data stored in the dialog.
Syntax | SUBROUTINE vcSetIntegerData@(dialog, dataName, k) VCdialog dialog STRING dataName INTEGER k
Description | dataName identifies the data for subsquent calls to vcGetIntegerData@. Names beginning with # are reserved. See vcGetIntegerData@ for a current list of reserved names. Of these only #Modified can be used in vcSetIntegerData@.
See also | vcGetIntegerData@


vcSetMenuAccelerator@

Platform | .NET(including Win32)
Purpose | To set the accelerator key for a menu item at run time.
Syntax | SUBROUTINE vcSetMenuAccelerator@(dialog, newName, key) VCdialog dialog STRING newName, key
Description | Menu item accelerator keys are normally selected in the design view of the form. This routine is used to set the accelerator key for a dynamic menu item created using vcInsertMenuItem@ with the same newName. key is the accelerator key as shown in the design-view properties of a menu item (e.g. "ShiftF1").
See also | vcInsertMenuItem@, vcMenuTip@, vcRemoveMenuItem@,


vcSetNodeData@

Platform | .NET(including Win32)
Purpose | To set user data for the currently selected node in a TreeView.
Syntax | SUBROUTINE vcSetNodeData@(dialog, controlName, text) VCdialog dialog STRING controlName, text
Controls | TreeView, Tree_View
Description | text is the data to save in the currently selected node.
See also | vcGetNodeData@


vcSetNodeState@

Platform | .NET(including Win32)
Purpose | To set the state of the currently selected node in a TreeView.
Syntax | SUBROUTINE vcSetNodeState@(dialog, controlName, state [,value]) VCdialog dialog STRING controlName, state LOGICAL value
Controls | TreeView, Tree_View
Description | state is one of "Checked", "Expanded" and "Visible". value is optional and defaults to TRUE. "Checked" can be used when a TreeView has the CheckBoxes property set to true. "Expanded" is used to expand or collapse the node. "Visible" is used to scroll the node into view (value is not used in this case).


vcSetPixel@

Platform | .NET(including Win32)
Purpose | To draw a pixel.
Syntax | INTEGER FUNCTION vcSetPixel@(drawing, x, y, red, green, blue) VCdrawing drawing INTEGER x, y, red, green, blue
Description | Sets the current pixel colour and calls SetPixel. The pixel is not drawn if the drawing is unbuffered.
Return value | Returns zero if successful, 1 if the drawing is unbuffered and 2 if the pixel is out of range.
See also | vcDrawPixel@, vcInvalidatePixels@


vcSetProperty@

Platform

.NET(including Win32)

Purpose

To set a property at run time.

Syntax

SUBROUTINE vcSetProperty@(dialog, controlName, property, val)
VCdialog dialog
STRING controlName, property
INTEGER val

Controls

Any control.

Description

vcSetProperty@ is used with a Drawing_Panel control to:

1. Set the "PanelSelection" to one of the parameters PanelSelection_Line, PanelSelection_DashedFrame, PanelSelection_ThickFrame, and PanelSelection_FilledRectangle.

2. Set the "PanelSelectionButton" to a combination of PanelSelectionButton_Left, PanelSelectionButton_Right and PanelSelectionButton_Middle (these parameters can be added together to enable more than one button).

3. Set the "PanelSelectionColour" to the given ARGB value. This is the background colour used when reversing lines in the dragging process.

vcSetProperty@ can be used with any control to set the ForeColor and BackColor properties to the given ARGB value.


vcSetPushed@

Platform | .NET(including Win32)
Purpose | To set the pushed state of a ToolBarButton.
Syntax | SUBROUTINE vcSetPushed@(dialog, controlName, state) SUBROUTINE vcSetPushed@ (dialog, controlName, editboxName, attribute) VCdialog dialog STRING controlName, editBoxName, attribute LOGICAL state
Controls | ToolBarButton
Description | The first form of vcSetPushed@ sets the button to the pushed state if state is TRUE. In the second form of vcSetPushed@, attribute is one of "Bold", "Italic", "Underline" and "Strikeout". editboxName is the name of a RichTextBox or RichText_Box control. If the currently selected text editBoxName has the given attribute then the button called controlName is set to the pushed state otherwise it is not pushed.
See also | vcIsPushed@


vcSetRange@

Platform | .NET(including Win32)
Purpose | To adjust the maximum and minimum properties of a control at run time.
Syntax | SUBROUTINE vcSetRange@(dialog, controlName, min, max) VCdialog dialog STRING controlName INTEGER min, max
Controls | Int32_Box, TrackBar, Track_Bar, ProgressBar, Decimal_UpDown, NumericalUpDown.
Description | The default properties are normally set in the design view of the form. This routine is used to adjust the range at run time.


vcSetState@

Platform | .NET(including Win32)
Purpose | To set the viewing state of a ListView.
Syntax | SUBROUTINE vcSetState@(dialog, controlName, state) VCdialog dialog STRING controlName, state
Controls | ListView, List_View
Description | state is one of "Details", "LargeIcon", "List", and "SmallIcon".
See also | Standard callbacks: "Details", "LargeIcon", "List", and "SmallIcon".


vcSetStringData@

Platform | .NET(including Win32)
Purpose | To set data stored in the dialog.
Syntax | SUBROUTINE vcSetStringData@(dialog, dataName, text) VCdialog dialog STRING dataName STRING text
Description | dataName identifies the data for subsquent calls to vcGetStringData@. Names beginning with # are reserved. See vcGetStringData@ for a current list of reserved names. Of these only #FileType and #Caption can be used in vcSetStringData@.
See also | vcGetStringData@


vcSetText@

Platform

.NET(including Win32)

Purpose

To set the text in a control or menu item.

Syntax

SUBROUTINE vcSetText@(dialog, controlName, text [, rowIndex [, columnIndex]])
VCdialog dialog
STRING controlName, text
INTEGER rowIndex, columnIndex

Controls

Any control that has the Text property. Also menu item, ListView, List_View, TreeView, Tree_View, menu item, StatusBarPanel.

Description

If the optional arguments (rowIndex and columnIndex) are ommitted, a ListView, List_View, TreeView or Tree_View sets the label of the currently selected item.

If a (zero-based) rowIndex but not a columnIndex is supplied then the text for the given row is set. This can be used with the following controls: TextBox, Text_Box, RichTextBox, RichText_Box, ComboBox, Combo_Box, ListBox, List_Box, CheckedListBox, CheckedList_Box, ListView, List_View, Tree_View.

When both a rowIndex and columnIndex are supplied, vcSetText@ can only be used with a ListView or List_View control. Both indexes are zero based. vcSetText@ is mostly used with cells that already exist. However, if columnIndex is less than zero (or is equal to the number of existing cells on the row) then a new cell is appended to the given row. [Note that the control will have a fixed number of columns and cells can be added to a given row until all of the columns on that row are filled.]

Error states

1 = rowIndex is too large
2 = columnIndex is too large for the number of columns
3 = columnIndex is too large for the number of existing cells on this row

See also

vcGetText@, vcLinkText@, vcRefreshText@


vcSetTextFontFamily@

Platform | .NET(including Win32)
Purpose | To set the font name of the current selection in a RichText control.
Syntax | SUBROUTINE vcSetTextFontFamily@(dialog, controlName, fontName) VCdialog dialog STRING controlName, fontName
Controls | RichText, Rich_Text
Description | fontName must be the name of a font in the installed font collection.


vcSetTextSize@

Platform | .NET(including Win32)
Purpose | To set the font size of the current selection in a RichText control.
Syntax | SUBROUTINE vcSetTextSize@(dialog, controlName, size) VCdialog dialog STRING controlName REAL(1) size
Controls | RichText, Rich_Text


vcSetTimer@

Platform | .NET(including Win32)
Purpose | To adjust a timer interval at run time.
Syntax | SUBROUTINE vcSetTimer@(dialog, timerName, interval) VCdialog dialog STRING timerName INTEGER interval
Description | The initial timer interval is given in the design view properties of the form. This value can be adjusted at run time by calling vcSetTimer@. interval is the time between timer events in milliseconds. If this value is non-zero the timer is enabled otherwise it is disabled.
See also | vcSetEnabled@


vcShow@

Platform | .NET(including Win32)
Purpose | To show a modeless dialog.
Syntax | SUBROUTINE vcShow@(dialog) VCdialog dialog
Description | vcShow@ is used after vcCreateDialog@ and vcCreateMdiChild@. The routine returns immediately and does not wait until the user closes the dialog.
See also | vcShowDialog@


vcShowColourDialog@

Platform | .NET(including Win32)
Purpose | To display a common dialog.
Syntax | INTEGER FUNCTION vcShowColourDialog@(dialog, [dialogName,] colour) VCdialog dialog STRING dialogName INTEGER colour
Description | Displays the common colour dialog using the colour value for both input and output. dialogName is the name of a ColorDialog supplied as a component in the design view of the form. If the form has only one ColorDialog then this argument can be omitted.
Return value | Returns one of the parameter values DialogResult_OK and DialogResult_Cancel.


vcShowDialog@

Platform | .NET(including Win32)
Purpose | To show a modal dialog.
Syntax | INTEGER FUNCTION vcShowDialog@(dialog) VCdialog dialog
Description | vcShowDialog@ is used after vcCreateDialog@. It is not normally used with vcCreateMdiChild@. The function does not return until the user closes the dialog. A parent dialog is disabled whilst the child is open. vcDisplayDialog@ is a subroutine but otherwise is identical to vcShowDialog@.
Return value | Returns one of the parameter values DialogResult_OK, DialogResult_Cancel etc. These correspond to states in the DialogResult property of the button used to close the form.


vcShowFiles@

Platform

.NET(including Win32)

Purpose

To show a common dialog.

Syntax

SUBROUTINE vcShowFiles@(dialog, dlgName, files, length, size)
VCdialog dialog
STRING dlgName
INTEGER,PARAMETER::length
INTEGER size
CHARACTER(LEN=length) files(:)

Description

dlgName is the name of an OpenFileDialog or SaveFileDialog in the design view. files is a one-dimensional array to receive the files selected by the user. size is input as the maximum size of this array and is output as the number of files selected.

A SaveFileDialog can only select one file but an OpenFileDialog has the property Multiselect that allows multiple files to be selected.

vcShowFilesDialog@ is recommended for multiple selection because there is no limit to the number of files it can handle.

See also

vcShowFilesDialog@


vcShowFilesDialog@

Platform

.NET(including Win32)

Purpose

To show a common dialog.

Syntax

SUBROUTINE vcShowFilesDialog@(dialog, dlgName, callback)
VCdialog dialog
STRING dlgName
EXTERNAL callback

Description

dlgName is the name of an OpenFileDialog or SaveFileDialog in the design view. A SaveFileDialog can only select one file but an OpenFileDialog has the property Multiselect that allows multiple files to be selected.

callback is the name of a function that you provide. When the dialog is closed this function is called once for each file selected. The callback should obtain the name of the file by calling vcGetStringData@(dialog, "#File").

See also

vcShowFiles@


vcShowFontDialog@

Platform

.NET(including Win32)

Purpose

To display a common dialog.

Syntax

INTEGER FUNCTION vcShowFontDialog@(dialog [, dialogName])
VCdialog dialog
STRING dialogName

Description

dialogName is the name of a FontDialog supplied as a component in the design view of the form. If the form has only one FontDialog, this argument can be omitted.

If the user clicks on the OK button, the font is stored as a property of the FontDialog and is used in calls to vcSetFontName@.

Return value

Returns one of the parameter values DialogResult_OK and DialogResult_Cancel.

See also

vcSetFontName@, vcChooseFont@, vcSetControlFont@


vcShowItem@

Platform | .NET(including Win32)
Purpose | To show or hide a control or menu item.
Syntax | SUBROUTINE vcShowItem@(dialog, controlName, show) VCdialog dialog STRING controlName LOGICAL show
Controls | Menu item, any control that has the Show/Hide method.
Description | If show is FALSE the item is hidden otherwise it is shown.


vcShowMessageBox@

Platform

.NET(including Win32)

Purpose

To show a simple modal dialog.

Syntax

SUBROUTINE vcShowMessageBox@(formName)
STRING formName
SUBROUTINE vcShowMessageBox@(obj, [caption,] style)
OBJECT obj
STRING caption
INTEGER style

Description

This is a static method.

In the first syntax, vcShowMessageBox@ combines vcCreateDialog@ with vcShowDialog@ and is used for simple dialogs that do not need to be configured. formName is the name of the form (e.g. "Resources.Form1") as used in vcCreateDialog@.

In the second syntax, vcShowMessageBox@ calls MessageBox.Show and displays the standard system message box. If caption is ommitted, "Visual ClearWin" is used.

obj is typically a string or a simple variable that is automatically converted to a string. style is given by adding one of the parameters: MessageBox_OK, MessageBox_OKCancel, MessageBox_AbortRetryIgnore, MessageBox_YesNoCancel, MessageBox_YesNo, MessageBox_RetryCancel, to one of the parameters: MessageBox_Stop, MessageBox_Question, MessageBox_Warning, MessageBox_Information.

See also

vcCreateDialog@


vcShowPrintDialog@

Platform

.NET(including Win32)

Purpose

To show a common dialog.

Syntax

INTEGER FUNCTION vcShowPrintDialog@(dialog, dlgName)
VCdialog dialog
STRING dlgName

Description

dlgName is the name of a PrintDialog, PrintPreviewDialog, or PageSetupDialog in the design view of the form. Each of these must have an attached PrintDocument.

For a PrintDialog and a PrintPreviewDialog you must include a prior call to vcOnPrintPage@ in order to provide a callback that specifies what to print on each page.

When using a PageSetupDialog, any changes made by the user are stored in the properties of the PrintDocument and will be used in a subsequent printing process.

Because of the way print dialogs operate, the value returned by this function is usually redundant.

Return value

Returns one of the parameters DialogResult_OK and DialogResult_Cancel.


vcStandardCallback@

Platform

.NET(including Win32)

Purpose

To launch a standard callback.

Syntax

SUBROUTINE vcStandardCallback@(dialog, event [, sender])
VCdialog dialog
STRING event, sender

Description

Standard callbacks are usually attached to menu items and toolbar buttons in the design view of the form. Moveover this approach allows you to call a standard callback and to follow this with a call to your own callback using vcOnClick@.

In exceptional circumstances you may find it helpful to call a standard callback from your Fortran program using vcStandardCallback@. event is one of the standard callbacks such as "Exit" and "Cut".

Some standard callbacks such as "Open" and "Save" raise events that you can respond to by attaching your own callback with vcOnEvent@. Within your callback it is sometimes useful to call vcGetStringData@(dialog,"#Sender") to determine the originator of the event. In the present context the sender is given by the optional argument in vcStandardCallback@.


vcStartProcess@

Platform | .NET(including Win32)
Purpose | To create a new process and return without waiting for it to terminate.
Syntax | SUBROUTINE vcStartProcess@(command) STRING command
Description | This is a static method. command is the name of the executable file to be launched. If the full path is not provided then the path of the current application is used.


vcStringARGB@

Platform | .NET(including Win32)
Purpose | To set the ARGB value for subsequent string drawing.
Syntax | SUBROUTINE vcStringARGB@(drawing, argb) VCdrawing drawing INTEGER argb
Description | argb is the packed colour value with the alpha value as the most significant byte and the blue value as the least significant.
See also | vcStringRGB@


vcStringDimensions@

Platform | .NET(including Win32)
Purpose | To set the dimensions for subsequent string drawing.
Syntax | SUBROUTINE vcStringDimensions@(drawing, width, height) VCdrawing drawing REAL(1) width, height
See also | vcMeasureString@, vcDrawString@


vcStringFontName@

Platform | .NET(including Win32)
Purpose | To set the font family name for subsequent string drawing.
Syntax | SUBROUTINE vcStringFontName@(drawing, fontName) VCdrawing drawing STRING fontName
Description | fontName must be the name of a font that is in the installed font collection.
See also | vcChooseFont@, vcShowFontDialog@, vcSetControlFont@


vcStringFontSize@

Platform

.NET(including Win32)

Purpose

To set the font size for subsequent string drawing.

Syntax

REAL(1) FUNCTION vcStringFontSize@(drawing, size)
VCdrawing drawing
REAL(1) size

Return value

Returns the previous size.


vcStringFontStyle@

Platform | .NET(including Win32)
Purpose | To set the style for subsequent string drawing.
Syntax | SUBROUTINE vcStringFontStyle@(drawing, bold, italic, underline, strikeout) VCdrawing drawing LOGICAL bold, italic, underline, strikeout
Description | Attributes that are FALSE are switched off otherwise on.


vcStringFormat@

Platform

.NET(including Win32)

Purpose

To set the format for subsequent string drawing.

Syntax

SUBROUTINE vcStringFormat@(drawing, format, style)
VCdrawing drawing
STRING format
INTEGR style

Description

format is one of "Alignment", "FormatFlags", "LineAlignment", and "Trimming".

The "Alignment" style is one of the parameter values: StringAlignment_Near, StringAlignment_Center, StringAlignment_Far.

The "FormatFlags" style is one of the parameter values: StringFormatFlags_DirectionRightToLeft, StringFormatFlags_DirectionVertical, StringFormatFlags_FitBlackBox, StringFormatFlags_DisplayFormatControl, StringFormatFlags_NoFontFallback, StringFormatFlags_MeasureTrailingSpaces, StringFormatFlags_NoWrap, StringFormatFlags_LineLimit, StringFormatFlags_NoClip

The "LineAlignment" style is one of the parameter values: StringAlignment_Near, StringAlignment_Center, StringAlignment_Far.

The "Trimming" style is one of the parameter values: StringTrimming_None, StringTrimming_Character, StringTrimming_Word, StringTrimming_EllipsisCharacter, StringTrimming_EllipsisWord


vcStringRGB@

Platform | .NET(including Win32)
Purpose | To set the RGB value for subsequent string drawing.
Syntax | SUBROUTINE vcStringRGB@(drawing, r, g, b) VCdrawing drawing INTEGER r, g, b
Description | Sets the alpha value to 255 (fully opaque) and uses the supplied red, green and blue components. The values are packed into a 32 bit integer with the alpha value as the most significant byte and the blue value as the least significant.
See also | vcStringARGB@


T

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcToggleTextState@

Platform | .NET(including Win32)
Purpose | To toggle an attribute of the current selection in a RichText control.
Syntax | SUBROUTINE vcToggleTextState@(dialog, controlName, attribute) VCdialog dialog STRING controlName, attribute
Controls | RichText, Rich_Text
Description | attribute is one of "Bold", "Italic", "Underline", and "Strikeout".


vcToInteger@

Platform | .NET(including Win32)
Purpose | To convert a string to an integer.
Syntax | INTEGER FUNCTION vcToInteger@(text) STRING text
Description | This is a static method. It calls Parse to convert text to a decimal integer.
Return value | Returns the decimal integer value if text can be parsed otherwise zero.
Error states | 1 = text could not be parsed


U

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcUpdate@

Platform | .NET(including Win32)
Purpose | To force a paint event.
Syntax | SUBROUTINE vcUpdate@(drawing) VCdrawing drawing
Description | Calls Update for the parent control in order to raise a paint event. In most circumstances paint events are raised automatically when needed. If, however, you have changed a drawing and this change is followed in your code by a significant amount of further processing/drawing, then you can update the screen immediately by calling vcUpdate@ to raise a paint event.
See also | vcInvalidateRectangle@, vcInvalidatePixels@


W

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


vcWebCommand@

Platform

.NET(including Win32)

Purpose

To issue a command to a Microsoft Web Browser.

Syntax

INTEGER FUNCTION vcWebCommand@(dialog, controlName, id [, pvaIn])
VCWDialog dialog
STRING controlName
INTEGER id
OBJECT pvaIn

Controls

Explorer_Box

Description

A Silverfrost Explorer_Box provides easy access to a Microsoft Web Browser control that can be used as a browser and also as simple HTML WYSIWYG editor. The vcWebCommand@ function provides commands such as "Go Back" for browsing and "Make Bold" for editing.

id is an integer command identifier. Some commands require an input value pvaIn. When required it is usually a string.

A full list of id values can be obtained from the Microsoft documentation for the Exec function in the IOleCommandTarget interface. These commands have the IDM_ prefix. vcWebCommand@ also provides access to the Microsoft ExecWB function but in this case the id value is obtained by adding the offset 1000 to the Microsoft identifier used in the ExecWB command. These have the OLECMDID_ prefix. Microsoft have not implemented all of the commands that they list and in some cases Visual ClearWin uses a listed identifier but calls a different Microsoft function or provides its own coding. For examples of command identifiers that are known to work, see solutions 17, 18 and 19 in the Visual ClearWin demonstration pack.

Note that some commands are not fully functional. For example IDM_PRINT currently only works for local files. Also you cannot browse the Internet after viewing a local file.

Return value

vcWebCommand@ returns zero if successful or one of the Microsoft error parameters E_NOTIMPL, E_INVALIDARG, E_NOINTERFACE, E_FAIL, E_UNEXPECTED and OLECMDERR_E_CANCELED whose values are listed in the file VC.ins.


vcWebNavigate@

Platform | .NET(including Win32)
Purpose | To browse to a given URL.
Syntax | SUBROUTINE vcWebNavigate@(VCWDialog dialog, controlName, url) VCWDialog dialog STRING controlName, url
Controls | Explorer_Box
Description | url is a Uniform Resource Locator for a local web or image file (with prefix "file://"), a web page (usually with prefix "http://") or the name of a folder. Solution 17 in the Visual ClearWin demonstration pack illustrates a simple web browser.
See also | vcGetDocumentURL@


vcWebQueryStatus@

Platform

.NET(including Win32)

Purpose

To get a command state or the status of selected text in an HTML editor.

Syntax

INTEGER FUNCTION vcWebQueryStatus@(dialog, controlName, id)
VCWDialog dialog
STRING controlName
INTEGER id

Controls

Explorer_Box

Description

A Silverfrost Explorer_Box provides easy access to a Microsoft Web Browser control that can be used as a simple HTML WYSIWYG editor. In an HTML editor vcWebQueryStatus@ can be used (for example) to determine if the current selection is bold. A corresponding toolbar button could then be set to the pushed state. It can also be used to test if commands such as Cut, Copy, Undo and Redo are currently enabled.

For further information on command identifiers see vcWebCommand@.

The use of vcWebQueryStatus@ is illustrated in solution 18 of the Visual ClearWin demonstration pack.

vcWebQueryStatus@ provides access to the Microsoft QueryStatus function in the IOleCommandTarget interface.

Return value

Returns a combination of the following Microsoft parameters OLECMDF_SUPPORTED = 1, OLECMDF_ENABLED = 2, OLECMDF_LATCHED = 4. By inspecting the three least significant bits of the returned value you can determine if the command with the given id is a) supported b) enabled and c) toggled on. The standard Fortran function BTEST is useful in this context.

See also

vcWebQueryStatusWB@, vcWebQueryString@


vcWebQueryStatusWB@

Platform

.NET(including Win32)

Purpose

To get a command state in a web browser.

Syntax

INTEGER FUNCTION vcWebQueryStatusWB@(dialog, controlName, id)
VCWDialog dialog
STRING controlName
INTEGER id

Controls

Explorer_Box

Description

A Silverfrost Explorer_Box provides easy access to a Microsoft Web Browser control. In a browser the vcWebQueryStatusWB@ function can be used to determine if a command such as "Go Back" is enabled. This can be used to set the enabled state of a corresponding button on a toolbar.

For further information on command identifiers see vcWebCommand@.

The use of vcWebQueryStatusWB@ is illustrated in solution 17 of the Visual ClearWin demonstration pack.

vcWebQueryStatusWB@ provides access to the Microsoft QueryStatusWB function.

Return value

Returns a combination of the following Microsoft parameters OLECMDF_SUPPORTED = 1, OLECMDF_ENABLED = 2, OLECMDF_LATCHED = 4. By inspecting the three least significant bits of the returned value you can determine if the command with the given id is a) supported b) enabled and c) toggled on. The standard Fortran function BTEST is useful in this context.

See also

vcWebQueryStatus@, vcWebQueryString@


vcWebQueryString@

Platform

.NET(including Win32)

Purpose

To get the status of selected text in an HTML editor.

Syntax

INTEGER FUNCTION vcWebQueryString@(dialog, controlName, id, result)
VCWDialog dialog
STRING controlName, result
INTEGER id

Description

vcWebQueryString@ is similar to vcWebQueryStatus@ but has an additional argument (result) that is used to return a string. It can be used to get information about the current selection in an HTML editor such as the current font name and font size.

vcWebQueryString@ provides access to the Microsoft Exec function in the IOleCommandTarget interface. Its use is illustrated in solution 18 of the Visual ClearWin demonstration pack.

Return value

vcWebQueryString@ returns zero if successful or one of the Microsoft error parameters E_NOTIMPL, E_INVALIDARG, E_NOINTERFACE, E_FAIL and E_UNEXPECTED whose values are listed in the file VC.ins.

See also

vcWebQueryStatus@, vcWebQueryStatusWB@


Supported Features in FTN95 for .NET

The following table provides a list of supported features in FTN95 for Microsoft .NET

Data Types
Operators
Arrays
Program units
Arguments and Interfaces
Declaration of Program Units, Variables and Attributes
Executable Statements
Numeric Intrinsic Procedures
Mathematical Intrinsic Procedures
Character Intrinsic Procedures
Bit Manipulation Intrinsic Procedures
Inquiry Intrinsic Intrinsic Procedures
Data and Time Intrinsic Procedures
Array Intrinsic Procedures
Other Intrinsic Procedures
.NET Extensions

Data Types

Intrinsic Data Types | Supported in Silverfrost FTN95 .NET
1 byte INTEGER | Yes
2 byte INTEGER | Yes
4 byte INTEGER | Yes
8 byte INTEGER | Yes
4 byte REAL | Yes
8 byte REAL | Yes
16/10 byte REAL | NoSS2
8 byte COMPLEX | Yes
16 byte COMPLEX | Yes
32/20 byte COMPLEX | NoSS2
1 byte LOGICAL | Yes
2 byte LOGICAL | Yes
4 byte LOGICAL | Yes
8 byte LOGICAL | Yes
1 byte CHARACTER | Yes
Derived type | Yes
Literal Constants | Supported in Silverfrost FTN95 .NET
1 byte INTEGER | Yes
2 byte INTEGER | Yes
4 byte INTEGER | Yes
8 byte INTEGER | Yes
4 byte REAL | Yes
8 byte REAL | Yes
16 byte REAL | NoSS2
8 byte COMPLEX | Yes
16 byte COMPLEX | Yes
32/20 byte COMPLEX | NoSS2
1 byte LOGICAL | Yes
2 byte LOGICAL | Yes
4 byte LOGICAL | Yes
8 byte LOGICAL | Yes
1 byte CHARACTER | Yes
Binary | Yes
Octal | Yes
Hexadecimal | Yes
Derived Types | Supported in Silverfrost FTN95 .NET
Array component | Yes
ALLOCATABLE component | NoSS1
POINTER component | Yes
Component has derived type | Yes
Default initialise | Yes
Structure constructors | Yes

Example code

Operators

Operator | Supported in Silverfrost FTN95 .NET
+,-,*,/ | Yes
** | Yes
==,/=,.EQ.,.NE. | Yes
>,>=,<,<= | Yes
.NOT. | Yes
.OR.,.AND. | Yes
.EQV.,.NEQV. | Yes
// | Yes

Example code

Arrays

Arrays | Supported in Silverfrost FTN95 .NET
Explicit shape arrays | Yes
Allocatable arrays | Yes
Array pointers | Yes
Assumed-shape arrays | Yes
Assumed-size arrays | Yes
Automatic and adjustable arrays | Yes
Whole array | Yes
Subscript triplets | Yes
Vector subscripts | Yes
Array constructors | Yes

Example code

Program Units

Program Unit | Supported in Silverfrost FTN95 .NET
Main program | Yes
Modules | Yes
Module procedures | Yes
Using modules | Yes
Block data program units | Yes
Function subprogram | Yes
Subroutine subprogram | Yes
Recursive procedures | Yes
Pure procedures | Yes
Elemental procedures | Yes
Internal procedure | Yes

Example code

Arguments and Interfaces

Arguments | Supported in Silverfrost FTN95 .NET
Intent | Yes
Keywords | Yes
Optional | Yes
Dummy procedures | Yes
Procedure arguments | Yes
Alternate returns | Yes
Call by value | Yes
Call by address | Yes
Interface Block | Supported in Silverfrost FTN95 .NET
Generic Names | Yes
Defined Operations | Yes
Defined Assignment | Yes

Example code

Declaration of Program Units, Variables, and Attributes

Program Unit Declaration | Supported in Silverfrost FTN95 .NET
PROGRAM Statement | Yes
FUNCTION Statement | Yes
SUBROUTINE Statement | Yes
ENTRY Statement | Yes
MODULE Statement | Yes
END MODULE Statement | Yes
BLOCK DATA Statement | Yes
END BLOCK DATA Statement | Yes
CONTAINS Statement | Yes
Variable Type Declaration | Supported in Silverfrost FTN95 .NET
INTEGER Statement | Yes
REAL Statement | Yes
DOUBLE PRECISION Statement | Yes
COMPLEX Statement | Yes
LOGICAL Statement | Yes
CHARACTER Statement | Yes
TYPE Statement | Yes
CLASS Statement (F2003) | NoSS4
Initialisation | Yes
Attribute Declaration | Supported in Silverfrost FTN95 .NET
PARAMETER Statement | Yes
PUBLIC Statement | Yes
PRIVATE Statement | Yes
DIMENSION Statement | Yes
ALLOCATABLE Statement | Yes
SAVE Statement | Yes
INTENT Statement | Yes
OPTIONAL Statement | Yes
POINTER Statement | Yes
TARGET Statement | Yes
INTRINSIC Statement | Yes
EXTERNAL Statement | Yes
Other Declarations | Supported in Silverfrost FTN95 .NET
DATA Statement | Yes
COMMON Statement | Yes
EQUIVALENCE Statement | Yes
IMPLICIT Statement | Yes
NAMELIST Statement | Yes
TYPE Statement | Yes
SEQUENCE Statement | Yes
END TYPE Statement | Yes
UNION Statement | Yes
END UNION Statement | Yes
MAP Statement | Yes
END MAP Statement | Yes
INTERFACE Statement | Yes
END INTERFACE Statement | Yes
MODULE PROCEDURE Statement | Yes
USE Statement | Yes
FORMAT Statement | Yes
Statement Function Statement | Yes
PROCEDURE statement (F2003) | NoSS4
GENERIC statement (F2003) | NoSS4
TYPEALIAS statement (F2003) | Yes

Example code

Executable Statements

Constructs | Supported in Silverfrost FTN95 .NET
IF Construct | Yes
IF THEN Statement | Yes
ELSE IF Statement | Yes
ELSE Statement | Yes
END IF Statement | Yes
CASE Construct | Yes
SELECT CASE Statement | Yes
CASE Statement | Yes
END SELECT Statement | Yes
DO Construct | Yes
DO Statement | Yes
END DO Statement | Yes
CYCLE Statement | Yes
EXIT Statement | Yes
CONTINUE Statement | Yes
FORALL Construct | Yes
FORALL Construct Statement | Yes
END FORALL Statement | Yes
FORALL Statement | Yes
WHERE Construct | Yes
WHERE Construct Statement | Yes
ELSEWHERE Statement | Yes
END WHERE Statement | Yes
WHERE Statement | Yes
IF Statement | Yes
Arithmetic IF Statement | Yes
Assignment, Allocate | Supported in Silverfrost FTN95 .NET
Assignment Statement | Yes
Pointer Assignment Statement | Yes
ALLOCATE Statement | Yes
DEALLOCATE Statement | Yes
NULLIFY Statement | Yes
Control | Supported in Silverfrost FTN95 .NET
END Statement | Yes
END FUNCTION Statement | Yes
END PROGRAM Statement | Yes
END SUBROUTINE Statement | Yes
CALL Statement | Yes
GO TO Statement | Yes
RETURN Statement | Yes
STOP Statement | Yes
PAUSE Statement | Yes
Computed GO TO Statement | Yes
ASSIGN Statement | Yes
Assigned GO TO Statement | Yes
I/O Statements | Supported in Silverfrost FTN95 .NET
OPEN Statement | Yes
CLOSE Statement | Yes
READ Statement | Yes
PRINT Statement | Yes
WRITE Statement | Yes
BACKSPACE Statement | Yes
ENDFILE Statement | Yes
REWIND Statement | Yes
INQUIRE Statement | Yes

Example code

Numeric Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
INT | Yes
REAL | Yes
DBLE | Yes
CMPLX | Yes
AINT | Yes
ANINT | Yes
NINT | Yes
ABS | Yes
MOD | Yes
SIGN | Yes
DIM | Yes
DPROD | Yes
MAX | Yes
MIN | Yes
AIMAG | Yes
CONJG | Yes
MODULO | Yes
CEILING | Yes
FLOOR | Yes
EXPONENT | Yes
FRACTION | Yes
NEAREST | Yes
RRSPACING | Yes
SPACING | Yes
SCALE | Yes
SET_EXPONENT | Yes
MERGE | Yes
LOGICAL | Yes

Example code

Mathematical Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
SQRT | Yes
EXP | Yes
LOG | Yes
LOG10 | Yes
LOG2 | Yes
SIN | Yes
COS | Yes
TAN | Yes
ASIN | Yes
ACOS | Yes
ATAN | Yes
ATAN2 | Yes
SINH | Yes
COSH | Yes
TANH | Yes

Example code

Character Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
ACHAR | Yes
ADJUSTL | Yes
ADJUSTR | Yes
CHAR | Yes
ICHAR | Yes
INDEX | Yes
LGE | Yes
LGT | Yes
LLE | Yes
LLT | Yes
IACHAR | Yes
LEN_TRIM | Yes
REPEAT | Yes
SCAN | Yes
TRIM | Yes
VERIFY | Yes

Example code

Bit Manipulation Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
NOT | Yes
IAND | Yes
AND | Yes
IOR | Yes
OR | Yes
IEOR | Yes
XOR | Yes
ISHFT | Yes
ISHFTC | Yes
IBSET | Yes
IBCLR | Yes
BTEST | Yes
IBITS | Yes
MVBITS | Yes

Example code

Inquiry Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
LEN | Yes
ALLOCATED | Yes
BIT_SIZE | Yes
DIGITS | Yes
EPSILON | Yes
RADIX | Yes
TINY | Yes
HUGE | Yes
MAXEXPONENT | Yes
MINEXPONENT | Yes
KIND | Yes
PRESENT | Yes
PRECISION | Yes
RANGE | Yes
ASSOCIATED | Yes
LBOUND | Yes
UBOUND | Yes
SHAPE | Yes
SIZE | Yes

Example code

Date and Time Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
CPU_TIME | Yes
DATE_AND_TIME | Yes
SYSTEM_CLOCK | Yes

Example code

Array Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
DOT_PRODUCT | Yes
MATMUL | Yes
ALL | Yes
ANY | Yes
COUNT | Yes
MAXVAL | Yes
MINVAL | Yes
PRODUCT | Yes
SUM | Yes
PACK | Yes
RESHAPE | Yes
SPREAD | Yes
UNPACK | Yes
CSHIFT | Yes
EOSHIFT | Yes
TRANSPOSE | Yes
MAXLOC | Yes
MINLOC | Yes

Example code

Other Intrinsic Procedures

Function | Supported in Silverfrost FTN95 .NET
NULL | Yes
SELECTED_INT_KIND | Yes
SELECTED_REAL_KIND | Yes
TRANSFER | Yes
LOC | Yes
RANDOM_NUMBER | Yes
RANDOM_SEED | Yes

Example code

.NET Extensions

Extension | Supported in Silverfrost FTN95 .NET
Automatic exposure of routines to other .NET languages | Yes
Alias exposed routine name | Yes
Call .NET static functions | Yes
Declare .NET objects | Yes
Create .NET objects | Yes
Call .NET class methods | Yes
Intrinsic .NET String data type | Yes
Automatic .NET String to Fortran character variable conversion | Yes
Pass .NET objects as routine arguments | Yes
Cast .NET objects to child/parent class | Yes
Create and manage threads | Yes
Synchonise threads | Yes
Handle exceptions | Yes
Throw exceptions | Yes
Define a namespace/class for an assembly | Yes
Create arrays of .NET objects | Yes
Detect .NET/Win32 compilation at compile or run-time | Yes
Call native Win32 code | Yes

Restrictions on Silverfrost FTN95 .NET Code

Note | Restriction
SS1 | This is non-standard code which is not supported in FTN95 Win32 or .NET.
SS2 | The .NET framework does not support more than 64 bit precision.
SS4 | This Fortran 200X feature is not yet supported in the current version of FTN95.


ClearWin+

This section describes the binding from Silverfrost FTN95 compilers to the Microsoft Windows Applications Programming Interface (API). It also describes the Silverfrost ClearWin+ library. ClearWin+ offers an easy-to-use interface to the Windows API making rapid development of GUI possible in Fortran.

ClearWin+ is used together with a Silverfrost Win32 compiler in order to develop Windows applications that will run under the Windows family of operating systems. This guide describes how to write these Win32 applications.

The ClearWin+ library is located in the main FTN95 run-time libraries. For 32-bit program this DLL is called salflibc.dll, for 64-bit that DLL is clearwin64.dll. If you are developing an executable with the potential for multi-platform use then you must not use ClearWin+ except perhaps as a development/debugging tool. The release version of a multi-platform executable should not use ClearWin+. The alternative to ClearWin+ is to use a C# or Visual Basic form (see A simple C# form).

The guide does not try to describe or to document the Windows API, which is a subject too extensive to be covered here. Full documentation of the Windows API is provided with the Microsoft Windows Software Development Kit (SDK).

When installed, FTN95 includes some example programs that illustrate some of the more common operations that developers will need in order to produce Windows applications.

Enhancements to ClearWin+ that have been added after the preparation of this guide are described in a README and .ENH enhancement files on the CD and also in the BROWSE example program.

FTN95, Silverfrost C++, and ClearWin+ are trademarks of Silverfrost Ltd.
MS-DOS, Visual Basic, and Windows are all trademarks of Microsoft Corporation.


Introduction

Clearwin+ Introduction

Windows applications

The ClearWin+ library

How to use this guide


Windows applications

In this section:

  • Preface
  • Windows applications
  • The ClearWin+ library
  • How to use this guide

ClearWin+ is a library of functions and subroutines that enables developers to produce Windows applications very quickly. It can be used together with a Silverfrost compiler (FTN77, FTN95 or SCC) in order to produce Windows 32 and 64 bit applications for Windows XP and subsequent operating systems.

Many developers will see the need to take advantage of the graphics user interface (GUI) that is available in Windows environments in order to produce applications that are simple to use and professional in their appearance. At the same time there will be very few developers who have the time and interest to work through the long learning curve that is required in order to get to grips with the Windows API - a Microsoft library that can be used to write Windows applications. Silverfrost's solution to this dilemma is ClearWin+. ClearWin+ is designed to be used in a way that closely emulates traditional programming techniques. The complexities of the Windows API are avoided by using the ClearWin+ interface with the result that Windows applications can be developed in a very small fraction of the time that otherwise would be needed. The resulting programs are much shorter than equivalent Windows programs produced in other ways.


The ClearWin+ library

In this section:

  • Preface
  • Windows applications
  • The ClearWin+ library
  • How to use this guide

The ClearWin+ interface may be used at three levels:

At the first and simplest level, DOS programs that interact with the user via standard Fortran input and output statements (for example READ, WRITE and PRINT) may be recompiled to produce simple Windows applications with little or no modification to the source code. ClearWin+ will automatically create a window (called a ClearWin window) complete with scroll bars and manage it for the developer.

At an intermediate level, ClearWin+ can be used to provide a professional graphics interface, without incurring the burden of directly using the full Windows API. In particular, the WINIO@ function can be used to produce one or more fully featured GUI windows (called format windows) both quickly and easily. This function dispenses with the need to provide detailed resource scripts for menus, dialog boxes, etc.. It also largely eliminates the requirement for the user to provide complex call-back functions in order to control the interface. The effect is that much of the complexity of using the full API becomes transparent to the programmer. At this level, Windows API functions are rarely needed.

Finally at the lowest level, it is possible for the developer to use ClearWin+ to write programs that use Windows API functions. However, even those who are familiar with the Windows API will probably find it quicker and easier to work at the intermediate level using the ClearWin+ library.

A convention has been adopted in this guide of using mixed case names for the routines present in the Windows API (for example, CreateWindow, GetDC, GetTextMetrics). Routines in the ClearWin+ library do not use mixed case names.


How to use this guide

In this section:

  • Preface
  • Windows applications
  • The ClearWin+ library
  • How to use this guide

All integer constants and variables in this guide that are declared as INTEGER are assumed to be 32 bits long (i.e. INTEGER(KIND=3) or INTEGER*4). Real values are usually declared as DOUBLE PRECISION and assumed to be 64 bits long (i.e. REAL(KIND=2) or REAL*8).

An exception to this general rule occurs in the case of 64 bit applications that use what is described by Microsoft as a HANDLE. These are 32 bit integers in 32 bit applications but become 64 bit integers in 64 bit applications. The FTN95 type INTEGER (KIND=7) can be used in these circumstances.

This guide distinguishes between three types of window.

1) An API window is produced using only Windows API functions. The term does not imply any added functionality from the ClearWin+ library.

2) A ClearWin window is a window that has the added ability to make direct use of standard Fortran I/O (READ, WRITE and PRINT). The ClearWin window was the central feature of ClearWin versions 3.0 and 3.1 and is still of interest in the current version of ClearWin+. A ClearWin window example is used in Getting started.

3) A format window is a window that has been created using the ClearWin+ WINIO@ function. This function is the distinguishing feature of ClearWin+ (it is, to all intents and purposes, the "+" in ClearWin+). Like a ClearWin window, a format window also has added functionality which provides all of the standard GUI facilities in an easily programmed form - enabling the programmer to bypass the complexities of the Windows API. ClearWin+ tutorial provides a tutorial to get you started with format windows whilst the sections that follow it provide detailed information.

The guide includes a Glossary. Words that have a special meaning in the context of Windows and ClearWin+ are often presented in italic font and included in the Glossary.


Getting started

Introduction

Using FTN77 and FTN95


Simple Introduction

The Silverfrost FTN95 default installation includes a number of programs that illustrate the use of ClearWin+. These are installed to a folder of the form \Users\xxx\Documents\FTN95 Examples\clearwin. Particular attention should be given to the demonstration programs that illustrate the use of the ClearWin+ function winio@ and to the 'Browse' application that is typically found in \Program Files (x86)\Silverfrost\FTN95.

The following instructions explain how to compile, link and execute a very simple Windows application without using winio@.

Consider a program to calculate the squares of a sequence of numbers and print them out.

In Fortran this takes the form:

WINAPP
INTEGER idx
DO idx=1,10
PRINT *,idx,' Squared is ', idx*idx
ENDDO
END

Using your editor, type in the above program and save it as (say) test.for.

Open a DOS box and enter a command line of the form:

FTN95 TEST /LINK

This will produce an executable file called test.exe that can be run from the Program Manager in the normal way or by entering:

TEST

at the DOS box command line.

The above procedure will run your test program and display a window that presents the output. This program illustrates how ClearWin+ can be used to convert a simple DOS application without the need to attend to any Windows programming features. It automatically generates what is called a ClearWin window that handles the input and output in a Windows environment.

Further information about compiling and linking is given in Compiling and linking whilst ClearWin windows gives detailed information about using ClearWin windows. A major part of this guide deals with what are called format windows using winio@. Format windows provide a quick and easy method for developing fully featured Windows applications.


Using FTN95

Silverfrost compilers use 32 bit integers (unless configured otherwise). This guide assumes that integers are 32 bits long unless otherwise stated.

The examples in this guide have been written using Silverfrost Fortran 77 syntax. Since this syntax is a subset of Fortran 95, the programs can be used for the FTN95 compiler with little or no change. However, users of FTN95 may wish to use ClearWin+ modules instead of an include file called windows.ins. The relevant module is called mswin.mod which is accessed via the Fortran 95 statement:

USE MSWIN

mswin.mod makes reference to the following modules which can be used separately.

mswin32.mod | Windows API functions and parameters.
clrwin.mod | ClearWin+ functions and parameters.
msw32prm.mod | Windows API printer functions and parameters.


ClearWin+ Tutorial

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

This tutorial shows you how to develop a simple Windows application using a Silverfrost Fortran compiler and ClearWin+. It takes you through a step-by-step process leading to an interactive program that produces the factors of a user-supplied integer. This "Number Factoriser" is one of the demonstration programs that is supplied with ClearWin+. The full source code can be found in the file called factor.for.

The tutorial is based on a number of files called factor1.for, factor2.for, etc. that can be found in the ClearWin+ demonstration directory installed on your hard disk. These files present stages in the development of the full program. The files are listed in the tutorial together with a detailed line-by-line explanation of the purpose and effect of the code. The idea is that you should compile, link and run factor1.for and then read the explanation for this file. Then proceed to factor2.for and so on.


Step 1

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

Begin by opening a "Command Prompt" Window (DOS box).

Now use your text editor to list factor1.for.

Here is the text of factor1.for. Line numbers have been added so that each line can be referenced in the explanation below.

1 WINAPP 'CWP_ICO.RC'
2
3 PROGRAM factor1
4 IMPLICIT NONE
5 INCLUDE <windows.ins>
6 INTEGER ans
7 ans=winio@('%ca[Number Factoriser]')
8 END

You can compile and link this program with a command line of the form:

FTN95 FACTOR1 /LINK

This produces a Windows executable factor1.exe that can be run by typing

FACTOR1

from the DOS box command line.

Alternatively you can run the executable from the Program Manager.

factor1.for simply opens a format window with a caption like this:

The window may differ slightly in its appearance from one version of Windows to another.

The quickest way to terminate the application is to press Alt-F4.

Now that you have seen the application running, have a look at the code. Before looking at line 7, which is the key line in this program, let's get some preliminaries out of the way first.

Line 1 provides information for the linker that is called when you use /LINK on the compiler command line. It causes the linker to produce a Windows executable. For a Win32 application, the zero values on this line are redundant. (Some later compilers allow you to omit these values.)

cwp_ico.rc is the name of what is called a resource script that can be found in the same directory as factor1.for. This particular resource script provides information about an icon that is embedded in the application. In the program this "Window" icon is not used in the application itself but is simply available as a icon that identifies the application when it is installed in the Program Manager or its equivalent.

WINAPP must be the first compiler directive in the file and must appear before the main program.

Line 4 is recommended as a standard line for all programs and routines that use the file windows.ins. This line is a compiler directive that ensures that all variables are given an explicit type. It is included because the names of many of the Windows parameters are very long and consequently they are easy to misspell. Without this directive, such bugs are very hard to find. The file factor.for is too short for this to matter, but never-the-less we adopt the practice here as a matter of routine.

Line 5 is a call to include the file windows.ins. The diamond brackets indicate that the file is located within the Silverfrost compiler directory. This file contains type declarations for many of the ClearWin+ and Windows API routines and parameters. The only information of relevance to this particular main program is that winio@ returns an INTEGER result (in this guide, all integers are 32 bits long unless otherwise stated). Note that, if you are only using winio@ from the ClearWin+ library, then you will reduce the compilation time by replacing the INCLUDE line by

INTEGER winio@

This brings us to line 7 and the heart of this and most ClearWin+ applications. winio@ is a ClearWin+ function that allows you to create a format window that displays all manner of graphical user interface (GUI) objects such as menus, buttons, pictures, formatted text, list boxes and icons. It also allows you to specify what action is to be taken in response to the options that you present to the user. This means that this one function can be used to avoid the complexities of writing a GUI application based on calls to the standard API library combined with a detailed resource script and complex call-back functions.

The first (and in this case only) argument of winio@ is called a format string. In the present case the format string starts with %ca and this is an example of what is called a format code. The format code %ca stands for 'caption' and it supplies a title for the format window. The title itself appears in square brackets after the format code.

There are many format codes available and all of them are represented by a % sign and a two letter format code. Additional information is often supplied (as here) by adding text enclosed in square brackets. This text is called a standard character string. We shall see later that sometimes extra information is placed between the % sign and the two letters. In other cases the format code is allowed to collect information from additional arguments that are presented after the initial format string argument of winio@.

This brings us to the end of step 1 in our development process.


Step 2

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

Here is the text of factor2.for.

1 WINAPP 'CWP_ICO.RC'
2
3 PROGRAM factor2
4 IMPLICIT NONE
5 INCLUDE <windows.ins>
6 INTEGER ans,number
7 number=1
8 ans=winio@('%ca[Number Factoriser]&')
9 ans=winio@('%il&',1,2147483647)
10 ans=winio@('Number to be factorised: %rd',number)
11 END

Note that number has been added to line 6 and & has been inserted towards the end of line 8. Lines 7, 9 and 10 have also been included.

If you compile, link and run this program the output looks like this.

A flashing text cursor appears in the inner box and the user is able to enter any integer in the range from 1 to 2147483647. As before Alt-F4 terminates the application.

The "&" character in line 8 is simply a device to allow the description of the format window to continue in the next call to winio@ (on line 9 in this case). Using this device avoids long format strings with long lists of associated arguments.

Line 9 contains the format code %il. This specifies the integer limit for the input on line 10. %il takes two (INTEGER) values that are provided as extra arguments to winio@. The lower limit is 1 and the upper limit (2147483647) is the largest possible 32 bit integer. The "&" character allows continuation in the next winio@ call.

In line 9 the format string begins with some text that comes before the next format code which is %rd. This text is simply copied to the window. The text includes the space before %rd. Without the %il, the user would be able to enter negative or zero values which would not make sense in this application.

The %rd format code is used for user integer input. It creates an edit box and displays the value of the INTEGER variable (in this case number) that is provided as the next argument of winio@. The initial value of number in line 7 has been chosen to be in the permitted range. Users will find that they are only able to type in integers in this range. Each time a single digit is typed, number is updated so that it always holds the value that is visible on the screen.

Now we are ready for step 3.


Step 3

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

Now that we have a window and the user is able to input an integer, the next stage is to add a button to initiate the factorising process. factor3.for includes code for such a button. Here is the text:

1 WINAPP 'CWP_ICO.RC'
2
3 PROGRAM factor3
4 IMPLICIT NONE
5 INCLUDE <windows.ins>
6 EXTERNAL factoriser
7 INTEGER ans,number
8 number=1
9 ans=winio@('%ca[Number Factoriser]&')
10 ans=winio@('%il&',1,2147483647)
11 ans=winio@('Number to be factorised: %rd&',number)
12 ans=winio@('%ta%`^bt[Fac&torise]',factoriser)
13 END
14
15 INTEGER FUNCTION factoriser()
16 factoriser=1
17 END

Note that lines 6, 12 and 15 to 17 have been added to factor2.for. Also an "&" character has been inserted after %rd on line 11. We need to look at line 12 in detail. The other new lines simply declare an external function which for the moment merely returns the value 1.

When you compile, link and run this program the output looks like this.

But at the moment nothing happens when you click on the button.

Line 12 of the program uses the format code %bt to provide the button. The text on the button is given as a standard character string (in square brackets) The "&" character in "Fac&torise" has the visual effect of producing an underscore on the next letter ('t' in this case). The result is that 't' on the keyboard can be used as an alternative to clicking on the button when used in combination with the Alt key i.e. Alt-T.

Note that two special characters, a grave accent (`) and a caret character (^), have been included after the % sign. These are two out of a set of four characters called format modifiers (the others are the tilde (~) and the question mark (?)). As it happens, all four modifiers may be used with %bt, but the number of modifiers that a format code can take and the effect each modifier has varies from one format code to another.

In the present case of the button format %bt, the grave accent means that this button is the default button. The default button has a slightly different appearance and is the one that is selected when the Enter key is pressed.

The caret means that a call-back function (called factoriser in this case) is provided as the next argument of winio@. This is the function that is to be called when the user clicks on the button. Call-back functions that are used with winio@ must have no arguments and must return an integer value. It is advisable that this function be declared EXTERNAL.

Finally we note that a tab (represented by %ta) has been placed before the %bt format code. This has been used to separate the button from the text before it. Alternatively, you could simply use spaces.

A call-back function must return one of the following values:

0 or negative | Closes the format window.
1 | The window remains open and the whole window is refreshed to allow any changes to be displayed.
2 | The window is left open with no refresh. If anything needs to be updated before the call-back returns, a call to window_update@ is used to refresh individual components.
3 | Used only with %mg.


Step 4

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

The next thing we need is a child window in order to present the results of the factorising process. factor4.for includes the code for such a window but we shall leave out the code that calculates the results until the end. Here is the text of factor4.for:

1 WINAPP 'CWP_ICO.RC'
2
3 PROGRAM factor4
4 IMPLICIT NONE
5 INCLUDE <windows.ins>
6 EXTERNAL factoriser
7 INTEGER ans,number
8 CHARACTER*50 str
9 COMMON number,str
10 number=1
11 str=' '
12 ans=winio@('%ca[Number Factoriser]&')
13 ans=winio@('%il&',1,2147483647)
14 ans=winio@('Number to be factorised: %rd&',number)
15 ans=winio@('%ta%`^bt[Fac&torise]&',factoriser)
16 ans=winio@('%2nl%ob%42st%cb',str)
17 END
18
19 INTEGER FUNCTION factoriser()
20 INTEGER number
21 CHARACTER*50 str
22 COMMON number,str
23 WRITE(str,*)number
24 CALL window_update@(str)
25 factoriser=1
26 END

Lines 8, 9, 11, 16 and 19 to 26 have been added and as before an "&" character has been placed at the end of the format string on line 15.

When the program is compiled the result looks like this:

At the current state of development, when you click on the "Factorise" button, the number that has been entered is simply copied to the new child window.

The allocation of the variable number to a common block in lines 9, and 22, provides a method for passing this variable to the factoriser function. You will recall that call-back functions like factoriser do not have any arguments. Line 23 stores the value of number as a character string in str. str is also held in common because it is used for output on line 16:

ans=winio@('%2nl%ob%42st%cb',str)

On line 16, %2nl provides two line feeds so that the child window that follows is placed below the existing controls.

The %ob format code is used to open a box at the current position. It automatically marks the position of the top left-hand corner of a box that will be drawn when a corresponding %cb (close box) is encountered. %cb automatically marks the position of the bottom right-hand corner of the box. The box is simply provided as a border. The enclosed area has no special attributes. In the present case the box is used to enclose a string that is produced by the %st format. The string is located in str and the width of the associated area is 42 characters. However, the standard width of a character in this context will be the maximum width of all the characters of the proportionally spaced font.

Finally, line 24 has the effect of updating the string on the screen in order to reflect a change in the contents of str.


Step 5

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

Now we shall add a menu bar with an associated “About” dialog box in order to create factor5.for. Here is the text, but to make it easier to understand, only those parts of facror4.for that have changed are listed in full.

6 EXTERNAL factoriser,about
12 ans=winio@('%ca[Number Factoriser]&')
13 ans=winio@('%mn[&File[E&xit]]&','EXIT')
14 ans=winio@('%mn[&Help[&About Number Factoriser]]&',about)
15 ans=winio@('%il&',1,2147483647)
19 END
20
21 INTEGER FUNCTION factoriser()
28 END
29
30 INTEGER FUNCTION about()
31 IMPLICIT NONE
32 INCLUDE <windows.ins>
33 INTEGER ans
34 ans=winio@('%ca[About Number Factoriser]&')
35 ans=winio@('%fn[Times New Roman]%ts%bf%cnTutorial&',2.0D0)
36 ans=winio@('%ts%4nl&',1.0D0)
37 ans=winio@('%cnProgram written to demonstrate%2nl&')
38 ans=winio@('%ts%tc%cn%bfClearWin+&',1.5D0,RGB@(255,0,0))
39 ans=winio@('%tc%sf%2nl%cnby&',-1)
40 ans=winio@('%2nl%cnSalford Software&')
41 ans=winio@('%2nl%cn%9`bt[OK]')
42 about=1
43 END

A new call-back function called about has been added to line 6 and the code for this function has been added to the end of factor4.for in lines 30 to 43. The new menu bar has been included as lines 13 and 14 after the caption in line 12.

This is what the compiled program displays on the screen.

When you click on the “Help” menu and then on the “About Number Factoriser” item, you get the dialog box below.

Now for the details of how this effect is created. First look at lines 13 and 14 for the menu bar.

13 ans=winio@('%mn[&File[E&xit]]&','EXIT')
14 ans=winio@('%mn[&Help[&About Number Factoriser]]&',about)

The menu format is provided by %mn. Square backets enclose a list of menu topics, with each topic having an optional embedded list of associated menu items. There are two menu topics here, “File” and “Help”. These provide for two drop down menus each of which (in this example) has one item . The “&” character is used in the same way as on a button in order to provide an accelerator key.

Each menu item requires a call-back function and these are provided as further arguments to winio@. The first one ('EXIT') refers to what is called a standard ClearWin+ call-back function. When a standard call-back function is used, the code for the function is supplied by ClearWin+ rather than by the programmer. In this case the effect of calling the function is simply to close the application.

The second call-back function (about) is supplied by the progammer. In this case the about function displays a dialog box that describes the application. When the user clicks on the OK button, the dialog box closes but the application remains active. If about returned zero instead of a 2, the application would also close when the OK button was used.

All we need to do now is look at the new call-back function for the “About” dialog. Let’s concentrate on the format codes that we have not seen before in this tutorial.

%fn defines a new font for the text that follows. In this case the font is “Times New Roman” and this font is used for the subsequent text up to the %sf format code on line 39. %sf stands for “standard font” and has the effect of resetting all text attributes (font, size, colour, bold, italic, and underline) to the default settings.

%ts is used to set the text size. It takes one DOUBLE PRECISION argument. The value 2.0D0 on line 35 doubles the standard text size and then the standard size is restored on line 36 with the value 1.0D0. Line 38 uses a text size of one and a half times the standard and then the standard size is restored with %sf on line 39.

%bf on line 35 is used to provide bold faced font whilst %cn has the effect of centring the line of text in the dialog box. In this example %cn is cancelled by the next newline format (%nl). On line 38, %tc changes the colour of the text to red. The colour is provided by the call to the ClearWin+ function RGB@. RGB@ takes three INTEGER arguments in the range 0 to 255. These provide the red, green and blue intensities. Note that %ts comes before %tc and uses the 1.5D0 argument on line 38. %tc is also used on line 39. In this case the argument (-1) restores the system text colour. This is one of the screen colours that the user can set from the Control Panel in the Program Manager.

Finally line 41 produces the OK button. As before the grave accent makes this the default button, whilst the value 9 has the effect of widening the button to a 9 character width. This button does not have a call-back function. As a result, when the user clicks on the button, the format window closes. If there are a number of buttons like this, then the value returned by winio@ (ans in this case) gives the number of the button that was pressed.


Step 6

In this section:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Step 4
  • Step 5
  • Step 6

factor6.for contains the finished program. In this program the factoriser function has been developed to do the calculations needed to factorise the number that is supplied by the user. The details of this simple Fortran code are not of direct interest to us in this tutorial but here is the code for those who want to read it.

INTEGER FUNCTION factoriser()
INTEGER number,n,k
CHARACTER*50 str,val
COMMON number,str
WRITE(val,'(i11)')number
CALL trim@(val)
str='The factors of '//val(1:LENG(val))//' are: 1'
n=number
1 DO k=2,n
IF((n/k)*k.EQ.n)THEN
WRITE(val,'(i11)')k
CALL trim@(val)
CALL append_string@(str,', '//val)
n=n/k
IF(n.GT.1)GOTO 1
ENDIF
END DO
CALL window_update@(str)
factoriser=1
END

This is what the final program displays on the screen:

This brings us to the end of the tutorial. In this one demonstration program you have been introduced to some of the important format codes that come with winio@. More importantly you have been able to experience the ease with which it is possible to develop a GUI application with ClearWin+.


Format windows

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

This section presents an overview of the ClearWin+ function winio@ that was introduced in ClearWin+ tutorial. Further details are given in the following sections up to Format code reference which provides a detailed reference.

winio@ is used to lay out and control a window in order to include a wide variety of controls, child windows, toolbars, etc.. Of course, this task could be carried out by making direct use of the Windows API. Although the direct method does provide maximum flexibility, it also requires large amounts of complex coding in order to control the interface. In contrast, the winio@ function requires a bare minimum of code to achieve elaborate window interfaces.

Windows applications typically have a great deal of "low level" functionality. For example, a window with several input controls will let the user move between fields using the tab key or the mouse. Likewise, buttons change their appearance slightly when they acquire focus. Fortunately you do not need to write code to program this functionality into your application, as it is already supplied by ClearWin+.

The following example illustrates the power and flexibility of winio@. In this example winio@ is used to produce a window that includes a menu bar with associated standard call-back functions. The window contains a so-called edit box that is used to display and edit a file. The menu and edit box is fully functional. Three buttons are also shown on the right hand side of the window. These are used to illustrate how buttons are added to the window. As the example stands, clicking on any of these buttons has no effect since code for the corresponding processes has been omitted.

WINAPP
INCLUDE <windows.ins>
CHARACTER*129 file,new_file,help_file
INTEGER compile,link,run,i
EXTERNAL compile,link,run
help_file='myhelp.hlp'
i=winio@('%ca[Example]&')
i=winio@('%mn[&File[&Open]]&','EDIT_FILE_OPEN','*.*',
+ file)
i=winio@('%mn[[&Save]]&','EDIT_FILE_SAVE','*.*',
+ new_file)
i=winio@('%mn[[Save &As]]&','EDIT_FILE_SAVE_AS','*.*',
+ new_file)
i=winio@('%mn[[E&xit]]&','EXIT')
i=winio@('%mn[&Edit[&Copy]]&','COPY')
i=winio@('%mn[[Cu&t]]&','CUT')
i=winio@('%mn[[&Paste]]&', 'PASTE')
i=winio@('%mn[&Help[&Contents]]&','HELP_CONTENTS',
+ help_file)
i=winio@('%mn[[&Help on help]]&','HELP_ON_HELP',
+ help_file)
c--- Define a 30x10 edit box %eb ---
i=winio@('%ww%pv&')
i=winio@('%30.10eb[vscrollbar,hscrollbar]&','*',0)
c--- Define buttons that are to be dispalyed ---
i=winio@('%2nl %^7bt[&Compile]&',compile)
i=winio@('%2nl %^7bt[&Link]&', link)
i=winio@('%2nl %^7bt[&Run]', run)
END
c--- Call-back functions that do nothing ---
INTEGER FUNCTION compile()
compile=1
END
INTEGER FUNCTION link()
link=1
END
INTEGER FUNCTION run()
run=1
END

This is what the window looks like on the screen:

The reminder of this chapter and the following chapters up to and including Format code reference provide a detailed explanation of how to set out the parameters of winio@.


Call-back functions

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

A ClearWin+ call-back function takes no arguments and returns an integer result. As a result, such functions may be coded in C, C++, or Fortran.

When a call-back function returns, it indicates what is to happen next by its return value. A negative or zero value signals an exit and closes the parent format window. The corresponding call to winio@ will return the absolute value of this quantity. A return value of 1 will cause a full update of the format window so that any changes are made visible. This should be used sparingly because if a call-back is used repeatedly, then the whole display area may flicker due to the frequent screen updates. A more efficient approach is to use a return value of 2. This will not cause the format window to close nor will it update the window. In order to refresh any part of the display that needs to be refreshed, a call to WINDOW_UPDATE@ will suffice. This will also improve the response since only small sections of the display will be redrawn.

In summary return values can be:

< 0 | Closes associated window.
1 | Returns from call-back with display refresh.
2 | Returns from call-back with no refresh.
3 | Used with %mg only.
4 | Used with %bv and %lv only.
> 5 | Reserved for future use.

Tip

Returning a negative value can be very convenient. Consider a window with a list box and OK and CANCEL buttons. Typically it is required that a double click on a list box item will select that item and close the window as if the OK button had been pressed. To achieve this the list box call-back function should return -1, so that winio@ will return 1 as if the OK button had been pressed - thus saving a flag and more complex program logic.

It is often convenient to use one call-back function for a variety of reasons. Whenever a call-back function is invoked, ClearWin+ defines a string that specifies the reason for the call. This string is obtained by calling clearwin_string@('CALLBACK_REASON'). Testing the string makes it easy to determine the reason for the call. See CLEARWIN_STRING@ for further details.


Window formats

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

The ClearWin+ function winio@ has the following form:

INTEGER winio@(format,...)
CHARACTER(*) format

where the ellipses ... represents a list of arguments whose length depends on what appears in the character variable format. The character string is called a format string. The list must only contain arguments of type INTEGER, DOUBLE PRECISION, CHARACTER or EXTERNAL functions.

At its very simplest, winio@ may be used to display information:

WINAPP
INCLUDE <windows.ins>
DOUBLE PRECISION x,y
x=1.0
y=2.5
c--- %wf display a floating point value ---
i=winio@('X = %ta%wf%nlY = %ta%wf',x,y)
END

%wf is an example of a format code. The %wf format code displays a floating point value with six decimal places as the default. New lines are represented by %nl, and tabs %ta operate on a grid of 8-character intervals or by setting tab stops with the %tl format (see Tab location). %2nl (for example) is used for two new lines and %3ta (for example) is used for three tabs. Form-feed (%ff) has a special meaning in a format window. It moves the current position to the left margin, beneath any existing controls. The window is automatically constructed with a size to suit its contents.

%wd, %wx, %ws, %wc, %we, and %wg are alternatives to %wd & %wf with the following usage:

%wd | Integer output.
%wx | Hexadecimal integer output.
%ws | String output.
%wc | Character output.
%wf | Floating point output in decimal form.
%we | Floating point output in exponent form.
%wg | Floating point output in decimal or exponent form.

Each of these output format codes can be modified in order to control the manner in which the information is presented. Details are given in Data output.

By using the additional format codes described below and in the following sections, the resulting windows can prompt for and display a wide variety of information.

Each format code begins with the percent (%) character, followed by optional size information of the form n or n.m where n and m are integer constants (e.g. %6.4wd). n and/or m can be replaced by an asterisk "*" with the corresponding value(s) being supplied as one or two INTEGER arguments in the argument list. After the optional size information, a two-letter code is used to define the format. This two letter code is not case sensitive. Some format codes have mandatory size information. These sizes are represented by uppercase N and M in the text.

Four special characters, known as format modifiers, are often inserted after the size information and before the two-letter code. The first of these is the caret character (^) which indicates that a call-back function is supplied in the argument list (after any other arguments required by the format code). The tilde character (~) is used with certain format codes to control the disabling (greying) of the control. The grave accent character (`) is also used to modify the action of certain codes. These characters may only be used with the codes that define them as detailed in Format code reference.

The fourth character is the question mark (?) that is used with any format that defines a control (as opposed to formats such as %ww that modify the appearance of the window as a whole). The question mark signifies that a help string is supplied in the format. This string is displayed at the bottom of the window or as a help "bubble" whenever the user's cursor lies over the corresponding control. The text is either surrounded by square brackets, or a "@" character is placed in the format string to indicate that the help string is supplied as an extra argument. The text string that is supplied in either of these two forms is known as a standard character string.

Many format codes are supplied with a list of options. When used, these are placed in a comma-separated list and set between square brackets after the two-letter format code. For example

%gr[black,rgb_colours]

If none of the options are used then the list, together with the square brackets, may be omitted. However, if the option list is empty and a help string is required, then square brackets must be inserted to represent the empty list. These brackets are followed by the help string. For example:

%20.10?eb[][Edit box]

Here is an example that uses a help string. It prompts the user for an integer (%rd) and augments the window with an additional help string.

WINAPP
INCLUDE <windows.ins>
INTEGER n_ch
n_ch=0
i=winio@('No of children %?rd'
+ //'[How many children have you got?]',n_ch)
END

The following code would produce the same result:

CHARACTER*80 help
help='How many children have you got?'
n_ch=0
i=winio@('No of children %?rd@',n_ch,help)
END

Help strings may include line feed characters (char(10)) if necessary. The area to contain the help text will be sized to fit the dimensions of the largest string. The help text can be positioned at another location (e.g. inside a box) by using the %he format. Alternatively, %th for 'tooltip' help (see Bubble and tooltip help).

A toolbar requires a help string for each button (see the %tb example in Bitmap button and toolbar).

Calls to winio@ may become quite complex. For this reason, a method is available to continue a format over several calls to winio@. If the last character in a format string is an ampersand (&) character, this character is removed from the string and the format information is joined seamlessly to the next call to winio@.

For example:

i=winio@('Enter an integer %ta%rd%nl&',n)
i=winio@('Enter a second integer%ta%rd%nl&',m)
i=winio@('%cn%`bt[Done]')

This creates a single window containing two integer edit boxes together with a button.

Note that, using this technique, it is possible to build a dialog box with a structure that is controlled by your program logic. For example, if the user had already supplied a file name you could omit a file open box, possibly replacing it with a suitable message.

By default, a fixed size window created using winio@ has a maximum size of 1280x1280 pixels. This maximum can be increased by a prior call to the routine SET_MAX_DIALOG_SIZE@.

If you choose to write some routines in Fortran and others in C++, then the programming language that you use for the first call to winio@ for a given format window must be the same as that used in any continuation calls. However, it is possible to create one format window using Fortran and another using C++.

See Also

WINSTYLE@


Closing a window

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

ClearWin+ programs may create a number of windows, some of which might be open at the same time. A ClearWin+ program terminates when both a) the END point of the program (or its equivalent) is reached, and b) all windows created by the program have been closed by the user.

Normally the user is provided with a number of ways to close a window. There is usually a system menu with a 'Close' item (Alt+F4) at the top left of a window. Selecting this item is equivalent to clicking on the close box at the top right of a window. The programmer can use %cc with a call-back function to trap this event.

The programmer can also add an 'EXIT' item to a %mn menu. This item will either be linked to a call-back function provided in the program or to the standard 'EXIT' call-back.

Other exit routes can be provided via buttons (using for example %bt or %tt):

a) When you click on the button that has no call-back function attached, the parent window will close. If there is only one window open, the effect is the same as if the standard 'EXIT' call-back were attached to the button.

b) If there is no call-back function attached to a button and the associated window has been created within a call-back function, then the window will close. The affect on the window's parent will depend on the value returned by the call-back (see Call-back functions). A zero return will close the window's parent. The same is true for any call-back, not just those attached to buttons.

Another approach to window closure is to attach a control variable to a window. When a window (or dialog) is created, by default it will be equivalent to a modal dialog box. A modal dialog box is one that must be closed before other windows in the same application can be accessed. Any code that follows the winio@ calls for a particular modal dialog box, will not be processed until the user closes the dialog.

If you want more than one window to be accessible (the equivalent of a modeless dialog box) then you can use %lw (see Leave window open) to leave a window open and to attach a control variable to the window. The presence of %lw causes any code that follows the winio@ calls for a particular window to be processed immediately. ClearWin+ sets the value of a %lw control variable to -1 (minus one). If the control variable is subsequently set a non-negative value, the window will close when that variable is updated (see below).

Notes

1. %lw is used together with %fr and %aw to create a multi-document interface.

2. %cv also provides a control variable for use with %aw but in this case the window will be a child window and will not be left open.


Updating windows

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

Many of the format codes of the winio@ function take pointers to data that may change. For example, the bar control variable in the %br format will typically change as some time consuming process proceeds. Likewise, consider the following partial window definitions:

CHARACTER*50 myform
myform='TEST 1'
i=winio@('%ca@&',myform)

The address of the variable myform has been passed to winio@, and if the contents of the string myform alter, it is desirable to update the window accordingly. In general, if you alter data that is in use by a window, the window will be updated if it is obscured and restored for any reason.

However, to obtain an immediate update, the subroutine

SUBROUTINE WINDOW_UPDATE@(variable)

should be called. The argument is the variable whose value has changed. In reality the address of the variable is passed and this address must be the exact address originally passed to winio@. For example, in the above example, the address of the first character in the string would be passed to WINDOW_UPDATE@ using

CALL window_update@(myform)

The update would not work if the address of the second character (i.e. myform(2:2)) where passed, even though this address points to part of the caption. The WINDOW_UPDATE@ function will update all controls, captions, etc. that depend on the variable. It may also be used with a grey-control variable (see for example %bt, Button format), or the control variable associated with the %lw format. In the latter case, setting the control variable to a non-negative value means that the window will close.

Note that, in general, WINDOW_UPDATE@ will only update those objects that depend on the variable whose address is supplied. However, there is no guarantee that other portions of the display will not become updated in the process.

It is desirable that WINDOW_UPDATE@ be called at a sensible rate. Perhaps no more than once or twice per second for a given variable. Frequent updates may produce an unpleasant flicker.


Advanced use of format windows

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

It is convenient at this point to mention a few advanced approaches to ClearWin+ programming. If you are still unfamiliar with how to program with winio@, it would be better to skip this section for the moment.

There are three ways in which the usage of winio@ can be varied under program control. First, you can use winio@ statements within flow control constructs such as DO and IF constructs. Here is a simple example.

WINAPP
INTEGER, n,i,winio@
COMMON n
EXTERNAL cb_func
i=winio@('Number of lines: %4rd&',n)
i=winio@('%2nl%cn%^tt[Show]',cb_func)
END
c-------------------------------------------
INTEGER function cb_func()
INTEGER n,i,j,winio@
COMMON n
DO j=1,n
i=winio@('Line %wd%nl&',j)
ENDDO
i=winio@(' ')
cb_func=1
END

The first dialog box allows you to enter a number. Clicking on the button then produces another dialog box with the given number of lines of output. Notice that the format string within the DO loop is terminated by an ampersand (&) to allow the description of the dialog box to continue on the next loop. The final call to winio@, acts as a terminator. It contains only a format string with a single space character. The same idea can be used with other flow control constructs containing calls to winio@.

A second method for varying the use of winio@ under program control involves changes to the format string. The next example illustrates the idea.

WINAPP
INTEGER n,i,winio@
COMMON n
EXTERNAL cb_func
n=1
i=winio@('Format 1 or 2: %4rd&',n)
i=winio@('%2nl%cn%^tt[Show]',cb_func)
END
c-------------------------------------------
INTEGER function cb_func()
INTEGER n,i,j,winio@
COMMON n
CHARACTER*10 fmt
fmt='Invalid value %wd'
IF(n.eq.1) THEN
fmt='Format %wd'
ELSE if(n.eq.2) THEN
fmt='FORMAT %wd'
ENDIF
i=winio@(fmt,n)
cb_func=1
END

In this example, the choice of format string for the output depends on the value entered into the edit box. The illustration is not very useful in itself but it does point the way to the idea that it is possible to construct format strings dynamically under program control.

The third and final approach to the dynamic use of winio@ takes the last idea one stage further. As it is we cannot easily change the format codes within a format string because different format codes take different arguments in the winio@ call. For example, if %wd were changed to %wf in the above example, then the call to winio@ would require a real valued argument rather than an integer after the format string. Although you could solve this problem by using complex IF or CASE constructs, ClearWin+ provides an alternative and potentially more powerful approach via the following routines:

SUBROUTINE ADD_WINIO_INTEGER@(I)
INTEGER I

SUBROUTINE ADD_WINIO_FLOAT@(X)
DOUBLE PRECISION X

SUBROUTINE ADD_WINIO_CHARACTER@(S)
CHARACTER(*) S

SUBROUTINE ADD_WINIO_FUNCTION@(F)
EXTERNAL F

Using these routines, you create the argument list before calling winio@. After creating the list, you then call winio@ with the format string as its only argument. Here is a simple example.

WINAPP
INTEGER, n,i,winio@
COMMON n
EXTERNAL cb_func
n=1
i=winio@('Format 1 or 2: %4rd&',n)
i=winio@('%2nl%cn%^tt[Show]',cb_func)
END
c-------------------------------------------
INTEGER function cb_func()
INCLUDE <windows.ins>
INTEGER n,i
COMMON n
CHARACTER*20 fmt
DOUBLE PRECISION x
x=n
IF(n.eq.1) THEN
fmt='Integer %wd'
CALL add_winio_integer@(n)
ELSE
fmt='Real %wf'
CALL add_winio_float@(x)
ENDIF
i=winio@(fmt)
cb_func=1
END

This example is too simple to do justice to the concept but it is sufficient to point the way.


Format codes grouped by function

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function>
  • Alphabetical index of format codes

The following table presents the format codes under various headings. Details are given in Input and output Hypertext windows. A reference guide is presented in Format code reference. An index and summary of the format codes appears in the next section, in addition to the index at the end of this user's guide.

1) | Interactive I/O: | %co, %dd, %df, %dl, %dr, %fl, %il, %rd, %rf, %rs
2) | Controls: | %bb, %bc, %bn, %br, %bt, %bv, %bx, %el, %ga, %hx, %ib, %ld, %ls, %lv, %mb, %ms, %rb, %sb, %sl, %tb, %tt, %tv, %vx
3) | Bitmaps, Cursors, Icons: | %bi, %bm, %cu, %dc, %gi, %ic, %im, %mi, %si
4) | Menus and accelerator keys: | %ac, %em, %es, %mn, %pm, %sm, %em, %nw, %cm
5) | Layout and positioning: | %ap, %bd, %cn, %dy, %ff, %gd, %gp, %nd, %nl, %nr, %pv, %rj, %rp, %ta, %wi
6) | Boxes: | %cb, %ln,%ob, %gb
7) | Displaying text: | %bf, %eq, %fn, %gf, %ht, %it, %pd, %sd, %sf, %st, %su, %tc, %ts, %tl, %tx, %ul, %wb
8) | Help: | %he, %ht, %th, %wb
9) | Graphics: | %dw, %gr, %og, %pl
10) | Main window attributes: | %ca, %cc, %cv, %de, %lw, %mv, %nc, %ns, %sp, %sv, %sy, %sz, %wp, %ww
11) | Background colour | %bg
12) | Child windows: | %aw, %ch, %cl, %cw, %fr, %hw, %if, %lc, %ps, %sh, %uw
13) | Formats for call-back functions: | %cc, %fs, %ft, %mg, %mv, %rm, %sc
14) | Edit boxes: | %eb, %pb, %re, %tx
15) | Data output: | %pl, %gi, %ss, %wc, %wd, %we, %wf, %wg, %ws, %wx


Alphabetical index of format codes

In this section:

  • Introduction
  • Call-back functions
  • Window formats
  • Closing a window
  • Updating windows
  • Advanced use of format windows
  • Format codes grouped by function
  • Alphabetical index of format codes

The following table provides a list and summary of the special format codes. Details are given in Input and output Hypertext windows. A reference guide is presented in Format code reference.

%ac | Accelerator key format.
%ap | Absolute positioning of next control
%aw | Attach window format.
%bc | Button colour format - specifies the colour of the next %bt button.
%bd | Specifies all four window borders individually.
%bf | Switch to bold font.
%bg | Background colour format.
%bh | Bubble help format.
%bi | Supply an icon for the next button.
%bk | Allow a right mouse click to be used on the next %bt button.
%bm | Bitmap format draws a bitmap.
%bn | Split button.
%br | Bar format - draws a horizontal or vertical bar which is partially filled with a user-selected colour.
%bt | Button format - defines a button with text.
%bv | Hierarchical tree-view, alternative to %tv.
%bx | Adds a raised grey bar to a tool bar.
%ca | Caption format - defines the title of a dialog box.
%cb | Box close format - closes a box opened by %ob.
%cc | Closure control format - provides a link to a call-back function by which the user controls the action to be taken when a window is closed.
%ch | Child window format - inserts a child window.
%cl | Displays a colour palette.
%cn | Centring format - forces everything which follows it, up to the next new line or form-feed character, to be centred in the window.
%co | Control option format - used to modify subsequent %rd, %rf, and %rs boxes.
%cu | Establishes a cursor for the next control in a format.
%cv | Control variable format.
%cw | Embeds a ClearWin window.
%dc | Establishes a default cursor for the window.
%dd | Increase/decrease button for an integer.
%de | Disables some other window while the current window is active.
%df | Increase/decrease button for a floating point value.
%dl | Allows a call-back function to be called at regular intervals via a timer.
%dp | Parameter box format.
%dr | Drag and drop.
%dw | Owner draw box format - provides owner draw boxes.
%dy | Provides a vertical displacement by a non-integral number of character depth units.
%eb | Edit box format - presents a edit box in which a text file is displayed and modified.
%el | Inserts an editable combo box.
%ep | Parameter box format.
%eq | Equation format - inserts a mathematical equation in a window.
%es | Escape format - causes the program to exit when the Escape key is pressed.
%ew | Exit Windows format - provides a call-back function which is called when the user shuts down.
%fb | Remember current font for subsequent buttons.
%fd | To set the font to the default Windows 95 font.
%ff | Form feed. Move down to below any existing controls.
%fh | Font handle - use a font created by the API function CreateFont.
%fl | Floating point limit format - specifies the lower and upper limits for subsequent %rf formats.
%fn | Font name format - selects a font for subsequent text.
%fp | Parameter box format.
%fr | MDI frame format - defines a frame to contain child windows attached by %aw.
%fs | File selection format - specifies the working directory and file filter for subsequent file open call-backs.
%ft | File filter format - specifies filter information for subsequent file open call-backs.
%ga | Gang format - enables radio buttons and/or bitmap buttons to be ganged together so that if one is switched on the others are switched off.
%gb | Group box for use with %wi
%gd | Programmer's grid format - supplies a temporary grid to help with the positioning of controls.
%gf | Get font handle format.
%gi | Draws a (possibly animated/transparent) GIF image.
%gp | Get window position format - used to get the current co-ordinates of the window position.
%gr | Graphics format - provides a rectangular area for Silverfrost graphics routines.
%he | Help format - specifies the location of help information.
%ht | Hypertext document attachment.
%hw | Obtains the window handle of the format window.
%hx | Attaches a horizontal scroll bar to the next control.
%ib | Image bar - a replacement format for %tb.
%ic | Icon format - draws an icon.
%id | To identify a button..
%if | Initial focus format - specifies that the next control will have the initial focus.
%il | Integer limit format - specifies the lower and upper limits for subsequent %rd formats.
%it | Switch to italic font.
%lc | Obtain the control handle.
%ld | LED format - displays a round LED (a coloured disk with a black border).
%ln | Etched line
%ls | List box format
%lv | Listview format
%lw | Leave window open format - allows winio@ to return without closing the window that it creates.
%mb | Multi-button toolbar.
%mg | Message format - provides a call-back function for a given Windows message.
%mi | Minimise icon format - supplies the name of an icon resource to be used if the window is minimised.
%mn | Menu format - used to attach a menu to the window.
%ms | Defines a multi-selection box that stores its settings in an array. Similar to %ls
%mv | Move format - provides a call-back function that is to be called when the user moves or resizes the window.
%nc | New class name format - provides a specified class name for the application.
%nd | Never-down format - prevents controls from sliding down when sizing a window.
%nl | New line
%nr | Never-right format - prevents controls from sliding to the right when sizing a window.
%ns | Disable screen saver.
%nw | To change certain properties of an existing window..
%ob | Box open format - defines the top left hand corner of a rectangular box into which subsequent objects are to be placed until a corresponding %cb format is encountered.
%og | Graphics format - provides a rectangular area for OpenGL graphics routines
%pb | Parameter box format.
%pd | Is used to insert a Sterling pound symbol '£' regardless of editor mode.
%pm | Supplies a popup menu so that when the right mouse button is pressed in the main window a menu appears.
%ps | Property sheet - layer windows to produce a card index style.
%pv | Pivot format - used to create a pivotal point for any subsequent re-sizing of the window.
%rb | Radio button format - defines a radio button or check box with text supplied directly.
%rd | Integer input format - creates an edit box and displays an integer that can be updated.
%re | Creates an multi-line edit box.
%rf | Floating point input format - creates an edit box and displays a floating point value that can be updated.
%rj | Right justifying format - forces everything which follows it, up to the next new line or form-feed character, to be right justified in the window. A window margin, if any, is still applied.
%rm | Read message format - Provides the name of a call-back function to handle messages from another ClearWin+ application.
%rp | Relative position format - Sets the position of the next control relative to the current position.
%rs | Character string input format - creates an edit box and displays a character variable (i.e. a string) that can be updated.
%sb | Status bar.
%sc | Start-up call-back. Causes a call-back to be called once when a window is opened - useful for drawing initial %gr data.
%sd | Subscript text format.
%sf | Standard font format - resets to default text attributes after use of any combination of %bf, %it, %ul, %fn, and %ts.
%sh | Used with property sheet format.
%si | Standard icon format - defines a standard icon that is to be placed to the left of the block of text that follows the descriptor.
%sl | Produces a slider control using a floating point variable to determine its position.
%sm | System menu format.
%sp | Set window position format - used to initialise the position of the window on the screen.
%ss | Allows the settings of selected controls to be auto saved and loaded from an INI file.
%st | Variable string format - lays a string out in a field of n characters. The string is re-drawn each time the window is renewed.
%su | Superscript text format.
%sv | Allows the program to become a screen saver executable.
%sy | Style format - changes the style of a window.
%sz | Size window format.
%ta | Insert tab 8-character intervals or to predefined tab stops. See %tl.
%tb | Bitmap button and toolbar format - defines a bit mapped button or a whole tool-bar.
%tc | Sets the colour of subsequent text.
%th | Bubble help in the form of a 'Tool tip'.
%ti | To provide a taskbar icon in the system tray.
%tl | Sets up tab locations for use with %ta.
%tp | Parameter box format.
%ts | Text size format - used to scale the text font size either up or down.
%tt | Textual toolbar format.
%tv | Hierarchical tree - type view
%tx | Displays an array of text in a rectangular region, defined by its parameters.
%ul | Underline text.
%up | Parameter box format.
%uw | User window allows windows code to be interfaced to ClearWin+.
%vx | Attaches a vertical scroll bar to the next control.
%wb | Web browser.
%wc | Character output.
%wd | Integer output.
%we | Floating point output in exponent form.
%wf | Floating point output in decimal form.
%wg | Floating point output in decimal or exponent form.
%wi | To allow interactive window design.
%wp | Supplies the name of a wallpaper bitmap which is used as a back drop to its contents.
%ws | Character string output.
%ww | Window control format - causes the resultant window to look like a normal application window, rather than a dialog window.
%wx | Hexadecimal integer output.


Input and output

Interactive I/O

Data output


Interactive I/O

In this section:

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

Reading numbers or character strings from a window under ClearWin+ is very similar to reading data in a traditional program using READ. However, it is important to remember that each variable must be given an initial value before the window is created since a default value will appear as soon as the window is displayed.

Tip

Checkmate can be used to flag an error when a variable that has not been given a value is used.

Those controls that allow the user to edit text in a box (such as %rd) can also transfer text to/from the clipboard using the special ClearWin+ call-back functions 'CUT', 'COPY', 'PASTE', defined in the standard call-back functions described in Standard call-back functions.


Integer input

Integer input - %nrd

In this section:

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

%rd creates an edit box and displays the value of the corresponding (INTEGER) argument. The integer will be updated whenever the edit field is adjusted. The user will be prevented from creating an invalid or out of range integer (see Integer increase/decrease ). By default the edit box will be made large enough to hold integers of the current range, although the integer parameter n can be used to override this.

For example:

INTEGER p
i=winio@('%si*Enter an integer: %3rd',p)

A call-back function is supplied using the caret (^) modifier. This function is called whenever a change is made.

A grave accent format modifier (`) may be used to make the control read-only. In this form no surrounding box is supplied, and the value displayed can only be changed by the program, using WINDOW_UPDATE@ to reflect the changes.


Floating point input

Floating point input - %nrf

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

%rf creates an edit box and displays the value of the corresponding (DOUBLE PRECISION) argument. The number will be updated whenever the edit field is adjusted. The user will be prevented from creating an invalid or out of range number (see Floating point increase/decrease). Numbers are entered in decimal or exponent form. For example: -0.0748 or -7.48e-2.

By default the edit box will be made large enough to hold values in the current range, although the integer parameter n can be used to override this.

A call-back function is supplied using the caret (^) modifier. This function is called immediately a change is made.

For example, suppose you wanted to prompt for a complex number, and the user is allowed to supply this as an (x, y) pair or as an (r, θ) pair. The box should show the current number in both formats and any change in one format should be reflected in the other. Here is some sample code that has the desired effect.

WINAPP
DOUBLE PRECISION x,y,r,theta
COMMON x,y,r,theta
INTEGER i,winio@
EXTERNAL convert_to_xy,convert_to_polar
x=1.0D0
y=0.0D0
r=1.0D0
theta=0.0D0
i=winio@('%ca[Polar co-ordinates]%bg[grey]&')
i=winio@('%3tl&',5,15,21)
i=winio@(' %itx%`it=%ta&')
i=winio@('%^rf&',x,convert_to_polar)
i=winio@(' %ity%`it=%ta&')
i=winio@('%^rf&',y,convert_to_polar)
i=winio@('%ff %itr%`it=%ta&')
i=winio@('%^rf&',r,convert_to_xy)
i=winio@(' %fn[Symbol]%itq%sf =%ta&')
i=winio@('%^rf',theta,convert_to_xy)
END
c-----
INTEGER FUNCTION convert_to_polar()
DOUBLE PRECISION x,y,r,theta,tiny
COMMON x,y,r,theta
tiny=1.0D-6
r=SQRT(x*x+y*y)
IF(x.LT.tiny.AND.y.LT.tiny)THEN
theta=0.0
ELSE
theta=ATAN2(y,x)
ENDIF
convert_to_polar=1
END
c-----
INTEGER FUNCTION convert_to_xy()
DOUBLE PRECISION x,y,r,theta
COMMON x,y,r,theta
x=r*COS(theta)
y=r*SIN(theta)
convert_to_xy=1
END

A grave accent format modifier (`) is used to make the control read-only. In this form no surrounding box is supplied, and the value displayed can only be changed by the program, using WINDOW_UPDATE@ to reflect the changes.

The %co format is used to modify the way that %rf and %rd call-back functions behave.


Character string input format

Character string input format - %nrs

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

This format takes one character variable and displays it in a single line edit box so that the user can change it. Optionally, it can be modified with an integer n that sets the width of the box in characters. The edit box will then scroll horizontally when necessary. For multiple line edit boxes see %re (%re) and %eb (Edit box (%eb)).

For example:

CHARACTER*80 str
str='Initial string padded with spaces if needed'
i=winio@('%10rs',str)

It is important to note that because there is an obvious difference between the widths of characters e.g. 'i' and 'W', the width is specified in 'average characters'.

A grave accent format modifier (`) is used to make the control read-only. In this form no surrounding box is displayed, and the string can only be changed by the program, using WINDOW_UPDATE@ to reflect the changes. This should be used in place of %ws when it is necessary to display a string which needs to be updated. A similar effect is produced with %st. (see Variable string). The caret is added to provide a call-back function that will be called on every change to the edit window.


Control option format

Control option format - %co[option-list]

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

This format is used to modify the form of subsequent edit boxes associated with %rd, %rf, and %rs. Currently, four options are available:

check_on_focus_loss | Perform checks and call-back (and update the corresponding data item) with %rd, %rf, and %rs on loss of focus only. This is particularly valuable if numeric limits have been imposed by %il or %fl (see the Glossary for a definition of the focus).
data_border | Put a border round %rd, %rf, and %rs boxes (default).
full_check | Perform checks and call-back on %rd, %rf, and %rs for every change (default).
no_data_border | Omit border round %rd, %rf, and %rs boxes.

For example:

i=winio@('%co[no_data_border]%il%rd&',1,10,j)
i=winio@('%nl%co[data_border]%rd',k)

places a box around the second data area but not the first.


Integer increase/decrease format

Integer increase/decrease format - %dd

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

Supplies a spin control button to go with an %rd edit box. %dd takes one integer argument that specifies the amount the value in the edit box is to be increased or decreased when the user clicks on the control. The resulting value is always a multiple of the increase. A call-back function can be supplied with the corresponding %rd format. %dd may also be used with %rs.

For example:

INTEGER val,i
val=0
c--- %`rd displays an integer - not user changeable ---
i=winio@('%ca[Spin]%dd%`rd',5,val)
END


Floating point increase/decrease format

Floating point increase/decrease format - %df

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

Supplies an spin control button to go with a %rf edit box. %df takes one DOUBLE PRECISION argument that specifies the amount the value in the edit box is to be increased or decreased when the user clicks on the control. The resulting value is always a multiple of the increase. A call-back function can be supplied with the corresponding %rf format. For example

DOUBLE PRECISION x
INTEGER i,winio@
EXTERNAL cb_func
i=winio@('%df%^rf',1D0,x,cb_func)


Floating point limit format

Floating point limit format - %fl

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

Specifies the lower and upper limits (as DOUBLE PRECISION arguments) for subsequent %rf formats. The lower and upper limits are supplied as arguments.

For example:

DOUBLE PRECESION x
i=winio@('%fl%rf',0.0D0,10.0D0,x)

The lower limit should be specified with care unless %co[CHECK_ON_FOCUS_LOSS] is used. If, for example, the lower limit were 500.0 and the user desired to enter the value 525.0, the number would be rejected as soon as the first digit 5 is entered. If CHECK_ON_FOCUS_LOSS is not used then the lower limit should be chosen to avoid this problem.

%`fl can be used after %rf in order to remove the limits for the next %rf.


Integer limit format

Integer limit format - %il

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

Specifies the lower and upper limits (as INTEGER arguments) for subsequent %rd formats. As for %fl, the lower limit should be specified with care unless %co[CHECK_ON_FOCUS_LOSS] is used.

For example:

INTEGER p
p=0
i=winio@('%si*Enter a small positive integer:%il%rd',0,99,p)
END

%`il can be used after %rd in order to remove the limits for the next %rd.


Parameter box

Parameter box - %N.Mpb[options]

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

A parameter block is a control that has been designed for use in complex simulation programs where you may wish to browse a large set of parameter names and values, with the option to select a value and modify it. A parameter block is defined using %N.Mpb where N is the width of the block in average characters, and M is the number of lines in the control. The control will scroll if necessary to display all the parameters. %pb takes the option sorted to cause the parameters to be alphabetically sorted by name. After a parameter block has been defined, parameters can be attached by subsequent format codes as follows:

%dp - Integer parameter

%fp - Floating point parameter

%tp - Text parameter

%ep - Enumerated parameter (a set of named alternatives)

%up - User parameter (just activates a call-back)

Each of these format codes is followed by a standard character string that gives the text to appear in the box. The question mark (?) modifier can be used with any of the additional format codes as illustrated below but %pb itself takes no modifiers. If a question mark is used with a parameter, the associated help string is displayed when the cursor is positioned above that parameter. One use for the user parameter (%up) is to activate another parameter block to achieve a hierarchical effect.

The various parameter types are illustrated by the following example:

WINAPP
INCLUDE <windows.ins>
EXTERNAL action
INTEGER i,texture_type
DOUBLE PRECISION v,p,a
CHARACTER*8 textures(6)
CHARACTER*20 name
DATA textures/'Sticky','Messy','Dirty','Greasy','Slimy',
+ 'Very slippery'/
DATA /k1,k2,k4,k5,v,texture_type,a/1,2,4,5,4.5,4,35.4/
p=120.6
name='Black n Sticky 123'
i=winio@('%ww[casts_shaddow]%ca[Parameter setting]&')
i=winio@('Double click on the parameter you wish to'
+ //'change:%2nl&')
i=winio@('%30.8pb[sorted]&')
i=winio@('%dp[test1]&',k1)
i=winio@('%dp[test2]&',k2)
i=winio@('%ep[Oil texture]&',textures,6,texture_type)
i=winio@('%dp[Temperature (Deg C)]&',k4)
i=winio@('%dp[Carbon monoxide (%)]&',k5)
i=winio@('%fp[Curent (Amps)test6]&',a)
i=winio@('%10.3fp[Voltage]&',v)
i=winio@('%fp[Oil pressure (PSI)]&',p)
i=winio@(
1 '%?tp[Oil name][What is the official name of this oil?]&',
2 name)
i=winio@('%up[Special action]',action)
END

INTEGER FUNCTION action()
INCLUDE <windows.ins>
i=winio@('No special action available'
+ //'yet%2nl%cn%bt[Continue]')
action=2
END


Slider format

Slider format - %nsl[options]

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

This format, %sl, produces a vertical or horizontal (default) slider control n average characters wide. It takes three arguments which are all floating point values. The first is a variable to hold the current value, the second its lower limit and the third is the upper limit.

For example:

WINAPP
INTEGER i,winio@
DOUBLE PRECISION max,min,value,def
DATA max,min,def,value/10.0,0.0,1.0,5.0/
i=winio@('%ca[Slider]%bg[grey]%`cn&')
i=winio@('%20sl&',value,min,max)
i=winio@('%2nl Value is &')
i=winio@('%df%fl%6rf',def,min,max,value)
END


Data output

  • Interactive I/O
    • Integer input
    • Floating point input
    • Character string input
    • Control option format
    • Integer increase/decrease format
    • Floating point increase/decrease format
    • Floating point limit format
    • Integer limit format
    • Parameter box format
    • Slider format
  • Data output

Each of the format codes %wd, %wx, %wf, %we, %wg, %ws, and %wc, can be modified in order to control the way in which the information is presented in the dialog window. The modifiers are all optional and appear after the % sign with the following general form:

%[flags][width][.precision] code

where code is one of wd, wf, etc.

[width] represents a positive integer that specifies the minimum number of characters that are to be output. More characters will be output rather than truncate the result. Where fewer than the minimum are needed, by default the field is padded with spaces on the left. Note, however, that with a proportionally spaced font, padding may have little apparent effect.

[.precision] represents a full stop followed by a positive integer that specifies the precision of the output. For floating point values, this integer is usually the required number of decimal places in the output.

Alternatively the [width] and [.precision] values may be replaced with an asterisk (*).

For example:

%[flags][*.*] code

Integer values must then be supplied as arguments, one for each asterisk.

[flags] represents one or more of the characters: minus "-", zero "0", plus "+", and the hash symbol "#". These modifiers have various effects depending on the current format code. For example they are used to force left justification, to pad with zeros rather than spaces, and to force a plus sign for a non-negative result.

In the following examples Ñ is used to represent a space.

More:

%wc

%wd

%we

%wf

%wg

%ws

%wx

Save settings to .INI file - %ss[filename/section]


%wc

%wc is used for the output of a single character. The width modifier may be used to pad out a field with spaces and the minus flag will cause the character to be left justified in such a field.


%wd

%wd is used for the output of integer values.

format | output for i=123 | comment
%wd | 123 | minimum width
%6wd | ÑÑÑ 123 | minimum of 6 characters, right justified
%6.4wd | ÑÑ 0123 | shows 4 digits, with a leading zero
%-6wd | 123 ÑÑÑ | left justify
%06wd | 000123 | pad with zeros on the left
%+6wd | ÑÑ+123 | force a + sign when not negative

Use this format only for displaying formatted text output that does not need to be refreshed when a variable is modified. Otherwise use %`rd in conjunction with the WINDOW_UPDATE@ call. The grave accent makes the %rd format a read-only text display box. See also: %wf


%we

%we is used for the output of floating point values in exponent form. The exponent part (following the letter 'e') always contains a sign and two digits.

format | output for x=0.0126 | comment
%we | 1.2607000e-02 | 6 decimal places, otherwise minimum width
%14we | ÑÑ 1.260000e-02 | minimum of 14 characters, right justified
%10.2we | ÑÑ 1.26e-02 | 10 characters, 2 decimal places
%6.0we | Ñ 1e-02 | 6 characters, no decimal point
%-9.1we | 1.3e-02 ÑÑ | 9 characters, 1 decimal place, left justified
%010.3we | 01.260e-02 | right justified, padded with zeros
%+10.2we | Ñ+1.26e-02 | force a + sign when not negative
%#8.0we | ÑÑ 1.e-02 | forces a decimal point when the precision modifier is zero


%wf

%wf is used for the output of floating point values in decimal form. If you need to update the value on screen then consider using %`rf. See also %we, %wg

format | output for x=1.26 | comment
%wf | 1.260000 | 6 decimal places, otherwise minimum width
%10wf | ÑÑ 1.260000 | minimum of 10 characters, right justified
%6.2wf | ÑÑ 1.26 | 6 characters, 2 decimal places
%2.0wf | Ñ 1 | 2 characters, no decimal point
%-6.1wf | 1.3 ÑÑÑ | 6 characters, 1 decimal place, left justified
%07.3wf | 001.260 | right justified, padded with zeros
%+6.2wf | Ñ+1.26 | force a + sign when not negative
%#4.0wf | ÑÑ 1. | forces a decimal point when the precision modifier is zero


%wg

%wg is used for floating point values and has essentially the same effect as %wf unless the supplied value cannot adequately be represented in %wf form; in which case %wg has the same effect as %we. To be specific, the %we form is only used if the exponent is less than -4 or greater than or equal the precision value. Note, however, that with %wg, trailing zeros after a decimal point are removed. Where appropriate, the decimal point is also removed.

format | value | output | comment
%wg | 0.0126 | 0.0126 |
%10wg | 1.26e-4 | ÑÑ 0.000126 | exponent is -4
%.3wg | 126.7 | 126.7 | exponent is less than the precision
%9.2wg | 1.267e-5 | Ñ 1.27e-05 | exponent is less than -4
%7.2wg | 100.0 | ÑÑ 1e+02 | exponent is equal to the precision


%ws

%ws is used for the output of character strings.

format | string | output |
'Mr %ws Bloggs' | 'Frederick' | Mr Frederick Bloggs | (1)
'Mr %9ws Bloggs' | 'Fred' | Mr Fred Bloggs | (2)
'Mr %`9ws Bloggs' | 'Fred' | Mr Fred Bloggs | (3)
'Mr %.4ws Bloggs' | 'Frederick' | Mr Fred Bloggs | (4)
'Mr %-9ws Bloggs | 'Fred' | Mr Fred Bloggs | (5)

(1) minimum field width,
(2) minimum of 9 characters, right justified,
(3) right justified in a space the width of 9 characters
(4) maximum of 4 characters,
(5) minimum of 9 characters, left justified.


%wx

%wx is similar to %wd but is used to output hexadecimal values. A grave accent (`) modifier is used to specify an upper case letter hexadecimal output.


Save settings to .INI file

Save settings to .INI file - %ss[filename/section]

Saves the supplied variables to an .INI file that is automatically located in the Windows directory, not the current working directory (the format of an .INI file is illustrated below). When the program is rerun the variables stored in the .INI file will automatically be restored (whenever the windows containing the %rs, %rd or %rf controls are displayed). The file name string (without the extension .INI) must be supplied in square brackets followed by a (/) character and the section name that will be used in the .INI file. The item name (within the section) is formed automatically from the text that appears immediately before the (%rd, %rf, %rs) format code.

A control argument of type INTEGER must also be supplied. This is a 'save' control flag that prevents the automatic saving of values when set to zero. This is useful when an abort/abandon path is taken rather than a clean exit, thus preventing erroneous or incomplete data from being stored. %ss should be placed before the first (%rd, %rf, %rs) format code.

For example:

INTEGER num,save_control,i
CHARACTER*20 directory
save_control=1
num=0
directory=' '
i=winio@('%ss[file/section]&',save_control)
i=winio@('Users: %rd%nl&',num)
i=winio@('Path: %rs',directory)

If the user enters '12' and 'c:\temp' into the two edit boxes, this creates a file called file.ini in the Windows directory containing:

[section]
Users=12
Path=c:\temp


Button controls

Button format - %nbt[button_text]

Button colour - %bc[colour]

Button icon - %bi[icon_name]

Textual toolbar - %tt[button_text]

Radio button - %rb[button_text]

Bitmap button and toolbar - %n.mtb

Image button and image bar - %n.mib

Tool bar border - %bx

Gang format - %Nga


Button format

Button format - %nbt[button_text]

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

Note: The syntax for %bb is very similar to %bt and %bb is usually preferred. See also %bn.

This format defines a button where button_text represents a standard character string consisting of the text that is dsiplayed on the button. The text must either be enclosed in square brackets, or an @ symbol is used to indicate that the text is supplied as an argument. The buttons of a dialog box are numbered from 1. The winio@ function returns the number of a button used to close a window or zero if it was closed in some other way (this assumes the button does not have a call-back). Button names may include the "&" character in order to provide accelerator keys.

For example:

i=winio@('Idiot!%ta%bt[&Sorry]')

A grave accent (`) is used to indicate that the button is the default when the Enter key is pressed. A default button has a slightly different appearance.

The caret character (^) may be used to define a call-back function that is called when the user clicks on the button (or, if the button is the default button, when the user presses the Enter key).

For example:

INTEGER i,winio@
EXTERNAL func
i=winio@('Press this to see what happens &')
i=winio@('%^bt[PRESS]',func)
END
c---Function to do something---
INTEGER function func()
func=1
END

The buttons in a format window (both %bt and %tt) are numbered from 1 in the order in which they are defined in the format string. When the user clicks on a button that does not have a call-back function, the format window closes and the corresponding winio@ call returns the number of the button pressed. For example:

PRINT *,winio@('%bt[OK]%ta%bt[Cancel]')

outputs the value 1 if 'OK' is pressed, 2 if 'Cancel' is pressed and zero if the window is closed without clicking on a button.

Alternatively, if a button has a call-back function that returns a negative value, then clicking on the button causes the format window to close and the corresponding winio@ call returns this value made positive. For example:

INTEGER winio@,i,func
EXTERNAL func
i=winio@('%^bt[OK]%ta%bt[Cancel]',func)
PRINT *,i
END
INTEGER FUNCTION func()
func=(-1)
END

displays the value +1 if 'OK' is pressed, 2 if 'Cancel' is pressed and zero if the window is closed without clicking on a button.

Normally a button created with %bt is permanently enabled. However, if the tilde (~) format modifier is used then an extra INTEGER argument must be supplied (before any call-back function). This argument provides an integer that controls the state of the button. When this integer is zero the button is greyed and cannot be used. When this integer is 1 the button is enabled. Typically this control integer would be altered by code responding to another control. For example, after a successful file-opening, a number of options might be enabled. Note that there is no reason why the same control integer should not control several buttons and/or menu items.

For example:

WINAPP
INCLUDE <windows.ins>
INTEGER grey_cntrl
EXTERNAL open_f,save_f,save_as_f
COMMON grey_cntrl
c---Only the OPEN button is initially available
grey_cntrl=0
i=winio@( '%^bt[Open] &',open_f)
i=winio@('%~^bt[Save] &',grey_cntrl,save_f)
i=winio@('%~^bt[Save as]',grey_cntrl,save_as_f)
END
c---
INTEGER function open_f()
INTEGER grey_cntrl
COMMON grey_cntrl
grey_cntrl=1
open_f=2
END
.....

The width of the button, in average characters, can be supplied using the parameter n (e.g. %10bt[Save]) rather than this being determined by the width of its text. A button is created wide enough for at least n characters (possibly more, if the font is not mono-spaced). This enables a number of buttons of the same size to be created. %fn and %ts can be used before %bt in order to modify the button text. %bi is used to add an icon the a button whilst %bc is used to change its background colour.

The text on a button can be changed dynamically by calling change_button_text@.

The text on a button will be placed on more than one line if a line feed character (CHAR(10)) is spliced into the text at the appropriate point.

For example:

button_name='Press'//CHAR(10)//'here'
i=winio@('%bt@',button_name)


Button colour

Button colour - %bc[colour]

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

This format is used in order to specify the background colour for the next %bt button only. The colour is specified in the same way as for %bg (see Background colour). The grave accent modifier is used to allow the colour to be changed dynamically after the button has been formed (see %bc).

For example:

i=winio@('%ca[Button Colour]&')
i=winio@('%bc[red]&')
i=winio@('%bt[Button A] &')
i=winio@('%bc&',RGB@(128,255,0))
i=winio@('%bt[Button B]')


Button icon

Button icon - %bi[icon_name]

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

This format supplies the name of an icon resource (as a standard character string) for the next %bt button. For example: %bi[tea_icon]%bt[] where tea_icon is defined in an associated resource script (see Icon). In this example no text would appear on the button. However, in most cases you will probably want to supply button text to go with the icon.

For example:

%bi[tea_icon]%bt[Tea!]


Textual toolbar

Textual toolbar - %tt[button_text]

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

This format code is much the same as %bt, except that the button is not as tall. Also the width of the button is rounded up to one of a set of standard sizes. This makes it possible to produce a textual toolbar (using a sequence of %tt formats) as used, for example, in the standard Windows Help buttons "Contents", "Search", "Back", etc. When using this format you will probably want to remove the borders from the window using the no_border option of the %ww format.

For example:

WINAPP
INTEGER i,winio@
i=winio@('%ww[no_border]%ca[Textual toolbar]&')
i=winio@('%mn[Exit]&','EXIT')
i=winio@('%tt[Compile]%tt[Link]%tt[Run]&')
i=winio@('%bx&',0.0D0)
i=winio@('%bg[grey]&')
i=winio@('%pv%fr',400,100)
END

The text on a button can be changed dynamically by calling CHANGE_BUTTON_TEXT@.


Radio button

Radio button - %rb[button_text]

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

This format, %rb, defines a radio button. The button text is a standard character string. It takes a single INTEGER argument that is set to 0 or 1 according to whether the corresponding control is off or on. The grave accent (`) is used to change this control to a check box. Radio buttons can be ganged together (see Gang format) so that only one of a set is selected at any one time. Note that it is not "standard" Windows programming practice to gang check boxes together.

For example:

WINAPP
INTEGER i,winio@,r(2),c(3)
DATA r/1,0/c/1,2*0/
i=winio@('%ca[Radio buttons]%bg[grey]&')
i=winio@('Format:%nl&')
i=winio@('%2`ga&',r(1),r(2))
i=winio@('%ta%rb[PCX]%nl&',r(1))
i=winio@('%ta%rb[BMP]%2nl&',r(2))
i=winio@('Compression:%nl&')
i=winio@('%3`ga&',c(1),c(2),c(3))
i=winio@('%ta%`rb[High]%nl&',c(1))
i=winio@('%ta%`rb[Medium]%nl&',c(2))
i=winio@('%ta%`rb[Low]',c(3))
END

The caret character (^) is used in association with a call-back function and this will be called whenever the item is selected.


Bitmap button and toolbar

Bitmap button and toolbar - %n.mtb

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • %mb
  • Tool bar border - %bx
  • Gang format - %Nga

%tb has been superceded by %ib which in turn has been superseded by %mb. For new code use %mb instead.

This format defines a bit mapped button or a whole toolbar. The names of three bitmap resources representing the off state, on state, and depressed state should be supplied as character string arguments, followed by an INTEGER argument that represents the state (0 = off, 1 = on). In the absence of a call-back function, pressing the button toggles the state, but does not close the format window. The correct order for the arguments is as follows:

'BMPoff', 'BMPon', 'BMPdown', ControlVariable, Callback

Any button on the toolbar can be set to an inactive/disabled state by using the (~) tilde format modifier. An extra bitmap will be required to represent this state.

For example:

BMPoff', 'BMPon', 'BMPdown', 'BMPdisabled', ControlVariable,
GreyControlVariable, Callback

The caret character (^) is used in association with a call-back function and this will be called whenever the user clicks on the button.

In order to obtain the effect of a non-toggling button, simply specify the same bitmap for the on and off states, and supply a call-back function to respond to each button press. Note that bitmaps may look different on screens of different resolutions. Where necessary the program should supply the appropriate bitmaps for the resolution in use. Bitmaps can be created using the standard Microsoft "Paint" accessory.

Here is a simple example of the use of bitmap buttons:

WINAPP 0,0,'d20.rc'
INCLUDE <windows.ins>
INTEGER answer
i=winio@('Hello%ta%tb','BT_OFF','BT_ON','BT_DOWN',answer)
END

The file d20.rc contains:

BT_OFF BITMAP "BT1.BMP"
BT_ON BITMAP "BT2.BMP"
BT_DOWN BITMAP "BT3.BMP"

Using the optional parameters n and m it is possible to create a whole toolbar as a rectangular array of buttons n items across by m deep. For example, a 1-deep horizontal bar of 10 items would be represented by %10.1tb (or just %10tb) together with 30 bitmap resources as the corresponding arguments.

If call-back functions are used, these follow each set of bitmaps thus: 'off1', 'on1', 'down1', func1, 'off2', 'on2', 'down2', func2,... etc. If the "?" modifier is used, then n × m help strings must be provided. It is particularly valuable to provide such help in the case of toolbar buttons, since their meaning is not always obvious. The following example creates a 3-element horizontal toolbar with help information and call-back functions. The second button is initially set to the on state.

WINAPP 0,0,'d21.rc'
INCLUDE <windows.ins>
INTEGER b1,b2,b3
EXTERNAL func1,func2,func3
DATA b1,b2,b3/0,1,0/
i=winio@('%3.1?^tb[Apples][Oranges][Pears]',
1 'OFF1','ON1','DWN1',b1,func1,
2 'OFF2','ON2','DWN2',b2,func2,
3 'OFF3','ON3','DWN3',b3,func3)
END
c----
INTEGER function func1()
func1=1
END
....

The file d21.rc contains:

OFF1 BITMAP "BT1.BMP"
ON1 BITMAP "BT2.BMP"
DWN1 BITMAP "BT3.BMP"
OFF2 BITMAP "BT1.BMP"
ON2 BITMAP "BT2.BMP"
DWN2 BITMAP "BT3.BMP"
OFF3 BITMAP "BT1.BMP"
ON3 BITMAP "BT2.BMP"
DWN3 BITMAP "BT3.BMP"

Bitmap buttons can be ganged together (see %ga). A greyed bar can also be drawn around the tool bar (see Toolbar border).


Image button and image bar

Image button and image bar - %n.mib

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

%ib has been superceded by %mb. Consider using %mb for new code.

%ib provides an enhanced and simplified replacement for %tb. Like %tb, %ib can be used to create toolbars or rectangular arrays of image buttons. However, only one flat image is required for each button - all the variants are created automatically. Also, text can be automatically added to the image. Here is some sample code that illustrates the use of %ib.

WINAPP
INTEGER winio@,i
i=winio@('%ca[Image bar]%sy[3d]&')
i=winio@('%bd&',0.0D0,0.0D0,0.5D0,1.0D0)
i=winio@('%mn[File[Exit]]&','EXIT')
i=winio@('%3ib[flat]','cut/Cut',4,'CONTINUE',
+ 'copy/Copy',4,'CONTINUE', 'paste/Paste',4,'CONTINUE')
END

RESOURCES
cut BITMAP cut.bmp
copy BITMAP copy.bmp
paste BITMAP paste.bmp

The argument list for %ib consists of the following triplet repeated for each button in turn: bitmap_name, stat_ctrl, cb_func.

The first part of the string bitmap_name gives the name of a bitmap resource. If you want a string to be added to the bitmap then this must come next after an oblique ('/'). This string can include linefeed characters (char(10)).

The integer stat_ctrl is used to control the state of the button. The constant value 4 is used to describe a button that does not toggle, i.e. it is in the down state only whilst the mouse button is held down. For a button that toggles, use a variable that will take the value 1 when it is in the up state and the value 2 when in the down state. The state value 3 describes a button that is greyed and disabled. Every button has a call-back function cb_func.

The option flat gives a toolbar that is initially flat and grey. When the mouse cursor is above a button, the image becomes coloured and the button is raised or depressed depending on its state. When this option is not used the old style of button is obtained.

%ib is designed for bitmaps that have a grey background. If the image has a one-pixel border then the border colour is used as the background colour, otherwise the background is assumed to be light grey (192,192,192). This colour is translated into the current system COLOR_BTNFACE colour selected by the user from the Control Panel. In the above example, the image bitmaps are 48x24 pixels. This results in buttons of equal width when the strings are added. See %ib for further details..


Tool bar border

Tool bar border - %bx

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

This format will add a raised grey bar effect to any tool bar (created using %bt, %ib, %tt, or %tb) set at the top of the window. It takes one floating point argument that specifies the additional depth (in average characters) to be inserted above and below the bar.


Gang format

Gang format - %Nga

In this section:

  • Button format - %nbt[button_text]
  • Button colour - %bc[colour]
  • Button icon - %bi[icon_name]
  • Textual toolbar - %tt[button_text]
  • Radio button - %rb[button_text]
  • Bitmap button and toolbar - %n.mtb
  • Image button and image bar - %n.mib
  • Tool bar border - %bx
  • Gang format - %Nga

This format is most useful when used with %tb (see Bitmap button and toolbar). Using this format code, radio buttons and/or bitmap buttons (e.g. components of a toolbar) are ganged together. At any time at most one control in a gang will be switched on. The addition of a grave accent (`) makes sure that there is always one control switched on.

The parameter N must be present, and have a value greater than 1. N specifies the number of controls to be ganged. The argument list must contain N INTEGER arguments, that contain the N controlling integers. For example, in the toolbar example (see Bitmap button and toolbar), the three controls could be ganged together by modifying the code thus:

i=winio@('%3ga&',b1,b2,b3)
i=winio@('%3.1?^tb[Apples][Oranges][Pears]',
2 'OFF1','ON1','DWN1',b1,func1,
3 'OFF2','ON2','DWN2',b2,func2,
4 'OFF3','ON3','DWN3',b3,func3)

The ganging format code may be placed before or after the formats in which the control variables are actually used. A given variable may be used in more than one control. However, it is unusual for a variable to appear in more than one gang format for a given window. If it does then there must only be one variable that is common and the effect is to merge the two gang sets. If the grave accent is used on one of the gangs then it must be used on both.


Controls other than buttons

Bar format - %Nbr[options]

Horizontal and vertical scroll bars %hx and %vx

List box format - %n.mls[options]

Multiple selection box - %n.mms

List-view - %lv[options]

Tree-view - %N.Mtv[options]

Branch-view - %bv[options]

Colour palette - %cl[options]


Bar format

Bar format - %Nbr[options]

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

This format, %br, draws a horizontal or vertical bar which is partially filled with a given colour. The first argument is a DOUBLE PRECISION control variable that indicates the extent of the fill. This variable should have a value between 0.0D0 and 1.0D0 inclusive. The second argument is an (r,g,b) colour value given by RGB@. N is used to specify the length of the bar, in average characters, when fully filled.

If options are supplied they should be placed in square brackets and separated by commas. The following options are available:

left_right | Bar is drawn horizontally left to right (default).
right_left | Bar is drawn horizontally right to left.
top_bottom | Bar is drawn vertically from the top.
bottom_top | Bar is drawn vertically from the bottom.
no_border | No bar border is drawn.

The bar is updated by using the WINDOW_UPDATE@ function. This should be called at suitable intervals to provide a smooth progression. This is illustrated in the following example:

WINAPP
INCLUDE <windows.ins>
INTEGER ctrl
DOUBLE PRECISION d
d=0.0
i=winio@('%ca[Bar format]&')
i=winio@('Processing .....%2nl&')
i=winio@('%20br&',d,RGB@(255,255,0))
i=winio@('%lw',ctrl)
DO WHILE(d.LT.1.0)
DO i=1,100000
END DO
d=d+0.01
c---- The data has changed so prompt windows to ---
c---- update the bar display ---
CALL window_update@(d)
END DO
END

The above program will produce a horizontal bar which will extend to the right as the task proceeds.


Horizontal and vertical scroll bars

Horizontal and vertical scroll bars %hx and %vx

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

Both %hx and %vx have similar meaning and usage. %vx generates a vertical scroll bar on the right-hand side of the next control and %hx a horizontal scroll bar along the bottom of the next control. %hx and %vx should not be used with controls (like %eb and %cw) that have their own scroll bar mechanism. Three arguments must be supplied to both format codes. The first is an INTEGER argument that determines the 'page step'. This determines the amount the scroll box (also called the thumb) moves each time the left mouse button is pressed inside the scroll bar region. You would normally link this value to the effect of a 'page change' in the control. The second argument is the maximum value (call this max say) that the scroll bar may generate. The third argument holds the current value of the scroll bar. This is of type INTEGER and will be in the range 0 to (max - 1). A call-back function is provided when the caret modifier is used. See also %hx and %vx .


List box format

List box format - %n.mls

This format supplies a simple list-box facility. The corresponding arguments are an array of CHARACTER strings, an INTEGER argument giving the size of the array and an INTEGER argument that both sets the initial selection and returns the result.

For example:

INTEGER k
CHARACTER greek(4)*5
DATA (greek(i),i=1,4)/'alpha','beta','gamma','delta'/
k=1
i=winio@('Select a Greek letter: %7.3ls',greek,4L,k)
END

The characters "7.3" before "ls" specify the width of the list box (as the number of characters) and the depth of the list box (as the number of lines). Pre-setting k to 1 would cause "alpha" to be already highlighted when the window is displayed. If the user selects "beta", then k set to 2. If k were pre-set to zero, none of the items would be initially selected. If the user were to exit without making a selection, k would keep its pre-set value.

The grave accent (`) may be used with %ls to produce a drop-down combo box rather than a list box (for an editable combo box see %el ). The caret (^) character is used in association with a call-back function. This function will be called whenever an item is selected.

For example:

EXTERNAL ls_function
i=winio@('%^ls',array,6L,n,ls_function)

(See also the LISTBOX_ITEM_SELECTED parameter in clearwin_info@).


Multiple selection box

Multiple selection box - %n.mms

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

%ms creates a list box that allows the user to select more than one item at a time. It is similar to %ls but the variable returning the result is replaced by an integer array. The elements of this array should be initialised to a value of zero for initially de-selected items and to a value of 1 for selected items. The array is updated as the user changes the selection.

n and m are optional (m cannot be specified without n). n represents the width of the multiple selection box (as a number of characters) and m the depth (as the number of lines). %ms requires three arguments. The first is an array of CHARACTER strings; the second is the number of entries in the list; and the third is an array of type INTEGER. The two arrays must have the same number of elements. If the number of elements that are displayed is less than the number in the list then a vertical scroll bar is provided. If a call-back function is supplied then it is called each time the user selects an item.

The following program illustrates some typical cases:

WINAPP
INCLUDE <windows.ins>
INTEGER k,i
INTEGER ivec(7)
CHARACTER*10 things(7)
DATA things/'Apples','Bananas','Cherries','Grapes',
+ 'Oranges', 'Pears', 'Raspberries'/
c--- Set the initial values for the selections ---
DATA ivec/0,1,0,0,1,1,0/
i=winio@('%ca[Selecting things]&')
i=winio@('%3tl&',15,30,45)
i=winio@('%tc[red]Simple%taDrop-down%taScrolling%ta&')
i=winio@('Multiple selection%nl%tc[black]&')
i=winio@('%ls%ta&',things,7,k)
i=winio@('%`ls%ta&',things,7,k)
i=winio@('%10.3ls%ta&',things,7,k)
i=winio@('%ms&',things,7,ivec)
i=winio@('%ff%nlNote that the first three boxes are&)
i=winio@('coupled together%nl&')
i=winio@('because they share the result variable k')
END


List-view

List-view - %lv[options]

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

A list view control is a window that displays a collection of items, each item consisting of an optional icon and a label. List view controls provide several ways of arranging items and displaying individual items. One of the arguments for %lv is an integer variable in the range 0..3 that represents the type of view: 0=Icon view; 1=Report view; 2=Small icon view; 3=List view. In the report view, additional information about each item can be displayed in columns to the right of the icon and label. The Microsoft Explorer uses a list view in order to display directory information. Here is a Fortran 95 example that illustrates the concept. For further details see %lv.

INTEGER N
PARAMETER (N=20)
CHARACTER*36 info(N),Colour,icons*60
INTEGER rgb(N-1),sel(N-1),view,hwnd,winio@,RGB@
COMMON info,rgb,hwnd
EXTERNAL call_back
INTEGER call_back,i
sel=0;rgb=0
rgb(1)=RGB@(255,0,0)
rgb(2)=RGB@(0,255,0)
rgb(3)=RGB@(0,0,255)
rgb(4)=RGB@(0,255,255)
rgb(5)=RGB@(255,0,255)
rgb(6)=RGB@(255,255,0)
info(1)='|Colour_90|Red|Green|Blue'
info(2)=Colour('|ARed|', rgb(1))
info(3)=Colour('|BGreen|', rgb(2))
info(4)=Colour('|CBlue|', rgb(3))
info(5)=Colour('|DCyan|', rgb(4))
info(6)=Colour('|EMagenta|', rgb(5))
info(7)=Colour('|FYellow|', rgb(6))
view=1
icons='red,green,blue,cyan,magenta,yellow,blank'
i=winio@('%ww%sy[3d]%ca[Listview sample]&')
i=winio@('%mn[Views[Icon]]&', 'SET',view,0)
i=winio@('%mn[[Report]]&', 'SET',view,1)
i=winio@('%mn[[Small icon]]&','SET',view,2)
i=winio@('%mn[[List]]&', 'SET',view,3)
i=winio@('%pv%`^lv[edit_labels,single_selection]&',
+ 240,120,info,N,sel,view,icons,call_back)
i=winio@('%ff%cn%10`rs%lc','Selected colour',hwnd)
END

CHARACTER*36 FUNCTION Colour(name,rgb)
CHARACTER(*) name
INTEGER rgb,r,g,b
CHARACTER*3 rc,gc,bc
r=AND(255,rgb)
g=AND(255,RS(rgb,8))
b=AND(255,RS(rgb,16))
WRITE(rc,'(i3)') r
WRITE(gc,'(i3)') g
WRITE(bc,'(i3)') b
rc=ADJUSTL(rc)
gc=ADJUSTL(gc)
bc=ADJUSTL(bc)
WRITE(Colour,'(6a)') name,rc(1:LEN_TRIM(rc)),'|',
+ gc(1:LEN_TRIM(gc)),'|',bc(1:LEN_TRIM(bc))
END

INTEGER FUNCTION call_back()
INCLUDE <windows.ins>
INTEGER N
PARAMETER (N=20)
CHARACTER*36 info(N)
INTEGER rgb(N-1),hwnd,row
COMMON info,rgb,hwnd
CHARACTER*36 Colour,name
call_back=2
SELECT CASE(clearwin_string@('CALLBACK_REASON'))
CASE('SET_SELECTION')
row=clearwin_info@('ROW_NUMBER')
CALL set_control_text_colour@(hwnd,rgb(row))
CASE('END_EDIT')
name=clearwin_string@('EDITED_TEXT')
row=clearwin_info@('ROW_NUMBER')
info(row+1)(3:)=Colour(name(1:LEN_TRIM(name))//'|',rgb(row))
CALL window_update@(info)
END SELECT
END

RESOURCES
red ICON red.ico
green ICON green.ico
blue ICON blue.ico
cyan ICON cyan.ico
magenta ICON magenta.ico
yellow ICON yellow.ico
blank ICON blank.ico

The winio@ statement that generates the list-view is:

i=winio@('%`^lv[edit_labels,single_selection]&',
+ 240,120,info,N,sel,view,icons,call_back)

Here is an outline of the meaning of the symbols and variables used in this statement:

grave accent | a list of icons (called icons) is supplied
caret | a call-back function (called call_back) is supplied
edit_labels | an option that enables the names of the colours to be edited by the user
single_selection | an option that ensures that at most one colour can be selected at a time
240 | the initial width of the list-view in pixels
120 | the initial height of the list-view in pixels
info | an array of strings that defines each row; the first row defines the column headings; the first character on subsequent rows is an index (A, B, C,...) that selects an icon from the list of icons; different fields are separated by a pipe '|' symbol.
N | a parameter defining the maximum number of rows
sel | an integer array to mark the current selection
icons | a string of icon resources
call_back | a call-back function that is used when a selection is made and when the end of label editing is detected.


Tree-view

Tree-view - %N.Mtv[options]

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

%bv has superseded %tv. Consider using that control instead.

The %tv format is used to construct a hierarchical list box that is analogous to the type of control sometimes used to display a directory structure. %bv is a newer format that is similar to %tv but has more options (see below). %tv takes a CHARACTER array followed by an INTEGER argument giving the size of the array. The final argument is an INTEGER argument (call it sel) that is used to receive the index of the chosen item. The format modifiers N and M set the width and depth of the tree-view in 'average characters'. The control operates in a manner that is similar to a listbox except that the first two characters of each string have a special meaning. The first character must be a capital letter ('A' - 'Z') indicating the level of the item within the hierarchy. The second letter should be a 'C' if the item is to be displayed compactly (i.e. not displaying any children) and 'E' if the item is to be displayed expanded. Consider the following list of things:

AEFood
BEFruit
CCApples
CCPears
BCNuts
CCHazel nuts
CCBrazil nuts
AEDrink
BCAlcoholic
BCNon-alcoholic

The children of a node (together with any of their children, etc.) are placed immediately beneath the parent node. In the example shown the types of nuts would not immediately be shown because of the 'C' in 'BCNuts'. Any node is expanded and contracted by simply by clicking on it. Usually you would code 'C' for the second character of each string. This would produce an initial display showing only the top level. As nodes are expanded and contracted, the information is stored in the strings. This means that, if the strings are used to display the hierarchy a second time, the display will start from where it left off. You could even store the strings in a file so that the expanded state would be the same from one run to another.

Items with a lower case letter or a blank in the first position are ignored and never displayed. This provides a means to hide elements, or to provide space for the display to grow dynamically. If a node has no children you can use 'E' or 'C' - there is no difference.

Notice that it makes no sense for a level 2 item (say) to be followed immediately by a level 4 item. An item may not be followed immediately by its 'grandchildren'. This condition will be detected as an error. Conversely, a level may decrease by any amount.

%tv can take a call-back function. The call-back function may use the index of the chosen item (i.e. the argument sel) and can also get the value of CLEARWIN_INFO@(TREEVIEW_ITEM_SELECTED'). This value will be equal to 1 if the call-back is responding to a double click mouse event.

By default, the tree-view displays bullet marks to the left of the nodes. By using a grave accent with %tv, the bullet marks are replaced by icons. When the grave accent is used, the third character in each string is interpreted as an index ('A' - 'Z') into a list of icons. This icon list is supplied as an extra argument that consists of icon resources separated by commas (e.g. 'ICON1,ICON2,ICON3'). You should construct the icons in such a way that the image is confined to the top left 16 x 16 corner. The remainder of the icon should be filled with the transparent colour.

By providing a call-back that examines the expansion indicator (character two of each string) it is possible to change the icon index to reflect whether or not the icon is expanded. If you perform a change of this sort you should pass the main array to window_update@ to force the control to be updated.

The following example illustrates the use of tree-view controls:

WINAPP
BLOCK DATA
CHARACTER*30 contents(56)
INTEGER item
COMMON/C/contents
COMMON/I/item
DATA contents/
+ 'ACABook', 'BCAChapter 1', 'CCASection 1.1',
+ 'CCASection 1.2', 'CCASection 1.3', 'CCASection 1.4',
+ 'BCAChapter 2', 'CCASection 2.1', 'CCASection 2.2',
+ 'CCASection 2.3', 'CCASection 2.4', 'BCAChapter 3',
+ 'CCASection 3.1', 'CCASection 3.2', 'CCASection 3.3',
+ 'CCASection 3.4', 'BCAChapter 4', 'CCASection 4.1',
+ 'CCASection 4.2', 'CCASection 4.3', 'CCASection 4.4',
+ 'BCAChapter 5', 'CCASection 5.1', 'CCASection 5.2',
+ 'CCASection 5.3', 'CCASection 5.4', 'BCAChapter 6',
+ 'CCASection 6.1', 'CCASection 6.2', 'CCASection 6.3',
+ 'CCASection 6.4', 'BCAChapter 7', 'CCASection 7.1',
+ 'CCASection 7.2', 'CCASection 7.3', 'CCASection 7.4',
+ 'BCAChapter 8', 'CCASection 8.1', 'CCASection 8.2',
+ 'CCASection 8.3', 'CCASection 8.4', 'BCAChapter 9',
+ 'CCASection 9.1', 'CCASection 9.2', 'CCASection 9.3',
+ 'CCASection 9.4', 'BCAChapter 10', 'CCASection 10.1',
+ 'CCASection 10.2', 'CCASection 10.3', 'CCASection 10.4',
+ 'BCAChapter 11', 'CCASection 11.1', 'CCASection 11.2',
+ 'CCASection 11.3', 'CCASection 11.4'/
END

INTEGER FUNCTION test()
c--------------------------------------------------------------
c Call-back function sets the icon for
c each object according to whether it is expanded or not
c--------------------------------------------------------------
CHARACTER*30 contents(56)
INTEGER item
COMMON/C/contents
COMMON/I/item
CHARACTER*30 string
string=contents(item)
IF(string(2:2).EQ.'E')THEN
string(3:3)='B'
ELSE
string(3:3)='A'
ENDIF
CALL window_update@(contents)
test=2
END
c------------------------------------
c Main program - just call WINIO@
c------------------------------------
INCLUDE <windows.ins>
EXTERNAL test
CHARACTER*30 contents(56)
INTEGER item
COMMON/C/contents
COMMON/I/item
INTEGER a
a=winio@('%ww%ob%pv&')
a=winio@('%^`20.15tv&',
+ contents,56,item,'CLOSED_BOOK,OPEN_BOOK',test)
a=winio@('%cb%ff%nl%cn%`bt[OK]')
END

Link this with a resource file containing the following:

CLOSED_BOOK ICON BOOK1.ICO
OPEN_BOOK ICON BOOK2.ICO


Branch-view

Branch-view - %bv[options]

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

The %bv format is used to construct a hierarchical tree-view that is similar to %tv. %bv gives a control with a slightly different appearance. %bv has more options and is simpler to use because a call-back function is nolonger needed in order to change the image when expanding a node. Here is some sample code like that for %tv:

WINAPP
CHARACTER*30 contents(56),fmt*120
INTEGER item,i,winio@
DATA contents/
& 'AEBBook', 'BCAChapter 1', 'CCASection 1.1',
....
item=1
fmt='%`bv[has_buttons,has_lines,show_selection_always,'
& //'edit_labels,lines_at_root,paired_bitmaps]'
i=winio@('%ww%sy[3d]%pv&')
i=winio@('%ca[Branch-view]&')
i=winio@(fmt,200,160,contents,56,item,'CLOSED,OPEN')
END

RESOURCES
CLOSED BITMAP closeb.bmp
OPEN BITMAP openb.bmp

%bv uses 16x16 bitmaps. The character array called contents is constructed in the same way as for %tv. The option paired_bitmaps indicates that the list of bitmaps 'CLOSED, OPEN' is ordered such that the bitmap for an expanded node (OPEN) follows immediately after that for the corresponding collapsed node (CLOSE). For further details see %bv.


Colour palette

Colour palette - %cl[options]

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

The %cl format code allows the user to select from a set colours presented in a palette. The user can also change the palette. Note that the range of colours available depends on the video display and currently selected display mode.

This format takes one array argument of type INTEGER that holds the values of up to three selected colours (for, respectively, the mouse left button, the right button and the middle button - values that are not used return a shade of grey). These values are in the same format as the result of the RGB@ function.

WINAPP
INCLUDE <windows.ins>
INTEGER i,v(3)
i=winio@('%ca[colour palette] %cl',v)
i=winio@('%ca[colour mix result] The colour was %wd.',v(1))
END

The options are:

b1 | Left mouse button only
b2 | Left and right buttons (the default)
b3 | Left , right and middle buttons
title1 | Title above button boxes
title2 | Title above palette
iconic | Transparent and inverse transparent selection

See %cl for further details.


Bitmaps, Cursors, Icons

Bitmap - %bm[bitmap_name]

Cursor - %cu[cursor_name]

Default cursor - %dc[cursor_name]

Icon - %ic[icon_name]

Minimise icon - %mi[icon_name]

Standard icon - %nsisymbol

Using the handle of a resource


Bitmap

Bitmap - %bm[bitmap_name]

In this section:

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

This is similar to the icon format %ic (see Icon) but the picture is supplied as a simple bitmap. For example we could write:

i=winio@('This is a bitmap: %bm[tea_bitmap]')

and the resource script would include a line of the form:

tea_bitmap BITMAP "BT1.BMP"

The grave accent is used to specify that the bitmap is supplied via a handle rather than a name. A suitable handle is returned by make_bitmap@ or by the Windows API function LoadBitmap. If you want to use LoadBitmap to access one of the pre-defined bitmaps then you will need to create your own binding to LoadBitmap. For example:

INTEGER(7) h_bitmap
INTEGER OBM_DNARROW
PARAMETER (OBM_DNARROW=Z'7FF0'L)
STDCALL MyLoadBitmap 'LoadBitmapA' (VAL,VAL):INTEGER(7)
h_bitmap=MyLoadBitmap(NULL,OBM_DNARROW)
i=winio@('%`bm',h_bitmap)

A call-back function can be added to a bitmap by using the caret (^) format modifier.

The %im format is also available and works in the same way as %bm except that it can be used with JPEG and PCX as well as BMP resources.

The %gi format is also available and works in the same way as %bm except that it uses a GIF resource created from an image file stored in GIF format. GIF files are compressed and may be animated and/or partially transparent. They therefore make ideal eye-catching features.


Cursor

Cursor - %cu[cursor_name]

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

By default the mouse cursor is represented by an arrow except in graphics regions (such as %gr) where by default it is represented by a cross. Two formats are supplied to change the mouse cursor representation. %dc sets the default cursor for the window as a whole, and %cu sets the cursor for the next control in the window. Each is followed by a standard character string (i.e. a string in square brackets or an @ character indicating that the required string is supplied as an argument). The string should be the name of a CURSOR resource. By using a grave accent (`), you can use constants representing the standard Windows cursors. These constants are defined in windows.ins.

For example:

a=winio@('%`dc&',CURSOR_IBEAM)
a=winio@('%ob%`cu&',CURSOR_WAIT)
a=winio@('%gr&',100,100)
a=winio@('%cb%ff%nl%cn%`bt[OK]')

For further information see %dc.

%cu and %dc also have a more complex form in which several alternative cursors are supplied, together with an integer used to select the one to use. The integer should be in the range from 1 to the number of different cursors supplied.

For example:

INTEGER k
k=1
i=winio@('%3dc[CURSOR_1][CURSOR_2][CURSOR_3]',k)

Whenever the cursor is in the main window, its shape will be governed by the current value of k. The %cu format is used in a similar way.


Default cursor

Default cursor - %dc[cursor_name]

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

By default, winio@ supplies an arrow for the mouse cursor. The %dc format takes a standard character string giving the name of the cursor resource or, if a grave accent format modifier is used, it takes an argument that is one of the following constants representing built-in Windows cursors:

CURSOR_ARROW | Standard arrow cursor
CURSOR_IBEAM | Text I-beam cursor
CURSOR_WAIT | Hourglass cursor
CURSOR_CROSS | Cross hair cursor
CURSOR_UPARROW | Vertical arrow cursor
CURSOR_SIZE | A square with a smaller square inside its lower-right corner
CURSOR_ICON | Empty icon
CURSOR_SIZENWSE | Double-pointed cursor with arrows pointing Northwest and Southeast
CURSOR_SIZENESW | Double-pointed cursor with arrows pointing Northeast and Southwest
CURSOR_SIZEWE | Double-pointed cursor with arrows pointing west and east
CURSOR_SIZENS | Double-pointed cursor with arrows pointing North and South

For example:

i=winio@('%`dc',CURSOR_IBEAM)

whilst for a user defined cursor:

i=winio@('%dc[my_cursor]')

combined with a resource script that contains the line:

my_cursor CURSOR cursor.cur

The file cursor.cur is created using an image editor.

See the description of %cu (Cursor) for a further example of how %dc is used and how several different cursors can be used for different parts of the format window.


Icon

Icon - %ic[icon_name]

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

This format supplies the name of an icon resource (as a standard character string). It is drawn at the current position in the format window.

For example:

WINAPP 'd28.rc'
INCLUDE <windows.ins>
i=winio@('This is an icon: %ic[win_icon]')
END

In a separate file called d28.rc we have:

win_icon ICON window.ico

The caret (^) character is used to attach a call-back function to an icon. The function is called each time the user clicks on the icon.

Icons differ in one respect from bitmaps in that they may have transparent regions that make the image appear to sit on the background in the same way that text does.

If a grave accent (`) is used, the icon is supplied via an icon handle. A suitable handle is returned by MAKE_ICON@ or by the Windows API function LoadIcon. If you want to use LoadIcon to access one of the pre-defined icons then you will need to create your own binding to LoadIcon. For example:

STDCALL MyLoadIcon 'LoadIconA' (val,val):INTEGER
INTEGER(7) h_icon
h_icon=MyLoadIcon(NULL,IDI_QUESTION)
i=winio@('%`ic',h_icon)


Minimise icon

Minimise icon - %mi[icon_name]

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

This format, %mi, supplies the name of an icon resource (as a standard character string) to be used if the window is minimised. The %ww format must be used in order for it to be possible to minimise the window.

For example:

WINAPP 'd10.rc'
INCLUDE <windows.ins>
i=winio@('%wwDon''t be late for tea!%mi[tea_icon]')
END

The file d10.rc contains:

tea_icon ICON tea.ico


Standard icon

Standard icon - %nsisymbol

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

Defines a standard icon that is to be placed to the left of the block of text that follows the format code. symbol is one of "?", "*", "!", and "#". The icons given by these symbols are illustrated below.

For example:

i=winio@('%2si?%2si*%^2si!%2si#&,cb_icon)
i=winio@('%2nlThese are all the standard icons.&')
i=winio@('%2nl%cn%7bt[OK]')

The symbol is vertically centred to the left of n lines of text (the parameter n defaults to 1), and a half icon width is left blank to the right so as to leave an appropriate gap between the icon and subsequent text. Sound is added by attaching the "BEEP" call-back (see BEEP). Alternatively, you can call the API function MessageBeep before creating the format window.

The caret character (^) is used with %si in order to attach a call-back function. This function is called each time the user clicks on the icon. In the above example the '!' icon uses the call-back function cb_icon.


Using a resource in an external file

ClearWin+ controls that take the name of a bitmap, icon, or cursor resource can be given a string consisting of a external file name enclosed in curly brackets. The full path of the file is usually only needed when the image file is not in the same directory as the executable. Here is an example:

i=winio@('%bm[{bmpfile.bmp}]')

The file name must not begin with an integer.

If you use the same file name more than once and in the mean time the file has been changed then the resource will be reloaded from the file.

ClearWin+ will delete the resource when the program terminates.

You can use this feature to load animated cursors. For example:

i=winio@('%dc[{c:\windows\cursors\Globe.ani}]')

but under Windows NT you will need version 4 or later.


Using the handle of a resource

  • Bitmap - %bm[bitmap_name]
  • Cursor - %cu[cursor_name]
  • Default cursor - %dc[cursor_name]
  • Icon - %ic[icon_name]
  • Minimise icon - %mi[icon_name]
  • Standard icon - %nsisymbol
  • Using the handle of a resource

ClearWin+ controls that take the name of a bitmap, icon, or cursor resource, can be given a string consisting of a decimal integer enclosed in curly brackets (with no embedded spaces), for example {21542}. The number should be the decimal value of a Windows handle to an object of the appropriate type. If the handle is invalid the results will be unpredictable.

For example:

CHARACTER*32 icon(32),handle
icon(1)=...
...
icon(32)=...
WRITE(handle,'(i10.10)') make_icon@(icon)
i=winio@('%ic[{'//handle//'}]')

For %bm, %ic, %mi, %cu, and %dc it is easier to use a grave accent, supplying the handle as an integer argument. However, the above technique is useful for other format codes (e.g. %bi, %ti, %tb, %tv) and when format strings must be constructed dynamically under program control.


Menus and accelerator keys

Menu format - %mn[menu_specification]

Dynamic Menus

Popup menu - %pm[menu_specification]

System menu - %sm[menu_specification]

Enhanced menus and New Enhanced menus - %em

Accelerator key format - %ac[key]


Menu format

Menu format - %mn[menu_specification]

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

%mn is used to attach a menu to the window. This is best illustrated by an example:

i=winio@('%mn[&Alpha,&Beta[Beta1,Beta2,|,Beta3],&Gamma]',
+ cb1,cb2,cb3,cb4,cb5)

This format specifies five selectable items, three of which, Beta1, Beta2, and Beta3 are contained in a drop-down menu. A bar symbol ( | ) between Beta2 and Beta3 causes a separator to be drawn in the drop-down menu. The three top-level menu items (Alpha, Beta and Gamma) can be selected using accelerator keys Alt-A, Alt-B and Alt-G that are specified by the inclusion of the ampersand character (&) placed to the left of the character chosen to be the (unique) accelerator for this menu (a double ampersand (&&) is required if you want an ampersand to appear in the text). Five call-back functions are required as arguments corresponding to each selectable menu item. A call-back function is called when the corresponding menu item is selected.

Individual menu items may also be greyed (so that they are visible, but not usable). In order to grey an item, prefix its name with a tilde (~) and insert an INTEGER argument to provide a control integer. When the value of this integer is zero, the item is greyed and disabled, otherwise it is enabled. Note that it is not necessary to use a different control integer for every item. You can use one integer to control several menu items and/or buttons. The following example illustrates a 3-item menu, in which the middle item is greyed:

WINAPP
INCLUDE <windows.ins>
INTEGER drinker
EXTERNAL squash_func,beer_func,tea_func
drinker=0
i=winio@('%mn[Squash]&',squash_func)
i=winio@('%mn[~Beer]&',drinker,beer_func)
i=winio@('%mn[Tea]',tea_func)
END
c---- call back function ---
INTEGER FUNCTION squash_func()
squash_func=1
END
......

The hash character (#) is used to control the placement of a check mark (tick) at the front of a menu item. The corresponding control variable is set to the value 1 in order to display a check mark otherwise it is set to zero. Top level menu items cannot be checked.

The caret character (^) can be used before the menu text to indicate that a callback function will be supplied to control the greying and checking of the item. This is an alternative to supplying control variables for # and (or) ~ modifiers. The callback, which is placed before the regular menu callback is called before the menu is displayed. It should return 1 to enable the item, 0 to disable. If the menu item is to be checked then it should add 2 to the return value. In essence bit zero controls whether the menu item is enabled and bit one whether it is checked. For example:

INTEGER FUNCTION save_state()
!!! Return zero to grey/disable the menu item, 1 to enable.
!!! Add 2 to the return value in order to make the item checked.
saveState = 1
END FUNCTION saveState

i = winio@("%mn[[^Save]]",save_state, save_cb)

As an alternative to using the ampersand (&) before a character, an accelerator key may also be associated with a menu item and its corresponding call-back function as illustrated in the following example.

i=winio@('%mn[File[Open^Ctrl+F12]]',open_func)

The caret symbol ^ is used here as an alias for the tab character (CHAR(9)) and is followed by the key name. Valid key names are illustrated with the accelerator key format %ac below. The use of an accelerator key is is only permitted in sub-menus and should not be used in top level menus.

In order to continue a menu in a new winio@ statement, it is necessary to match opening square brackets with closing brackets on the line to be continued. Then use an appropriate number of opening square brackets on the next line. For example:

i=winio@('%mn[Test,File[Open]]&',f1,f2)
i=winio@('%mn[[Save],Help]',f3,f4)

is equivalent to

i=winio@('%mn[Test,File[Open,Save],Help]',f1,f2,f3,f4)

Help strings are provided by inserting a question mark (%?mn). All the strings are placed in order at the end of the format description, one for each item that has a call-back function. For example,

i=winio@('%?mn[File[New]][Start a new file]&',newfn)
i=winio@('%?mn[[Save]][Save this file]',savefn)

You can provide help strings that vary if the menu item is greyed. To do this start the help string with a pipe symbol '|' and use another to separate the initial enabled state from greyed. For example:

iw = winio@('%?mn[[~Save]][|Save is enabled|Save is disabled]&',doSave,savefn)

Separators also require a help string but this is not used.

See also: Dynamic Menus


Dynamic Menus

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

If you wish to add or remove menu items whilst the program is running then this is possible with the aid of a handle:

i=winio@('%mn[&Window[*]] &', handle)

The asterisk (*) causes %mn to provide a handle that is passed to either ADD_MENU_ITEM@ or REMOVE_MENU_ITEM@. Note that items are added to the end of the pop-down menu that contains the handle. You may have a number of handles for various pop-down menus.

Only one handle is required to create a menu with multiple entries. To detect which menu entry has been selected use CLEARWIN_STRING@('CURRENT_MENU_ITEM') to obtain the text of the menu item selected.

Here is some sample code that illustrates how to add a list of files to a file menu.

WINAPP
INCLUDE <windows.ins>
INTEGER i,ctrl,cb,cb0
INTEGER(7) handle
CHARACTER*129 fname
EXTERNAL cb,cb0
COMMON ctrl
i=winio@('%mn[File[New]]&',cb)
i=winio@('%mn[[Open]]&', cb)
i=winio@('%mn[[Save,|]]&', cb)
i=winio@('%mn[[*]]&',handle)
i=winio@('%lw',ctrl)
DO i=1,3
WRITE(fname,'(a,I1)') 'File',i
CALL add_menu_item@(handle,fname,1,0,cb)
ENDDO
CALL add_menu_item@(handle,CHAR(0),0,0,cb)
CALL add_menu_item@(handle,'Exit', 1,0,cb0)
END
c-----
INTEGER FUNCTION cb()
cb=1
END
c-----
INTEGER FUNCTION cb0()
INCLUDE <windows.ins>
INTEGER ctrl
COMMON ctrl
ctrl=0
CALL window_update@(ctrl)
cb0=1
END


Popup menu

Popup menu - %pm[menu_specification]

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

This format code, %pm, is almost identical to %mn but a popup menu is activated when the right mouse button is pressed in the format window. Please refer to %mn for general information on how to construct a menu.

In the example below a popup menu controls the mathematical operation carried out on two values that are provided by slider controls. The divide option is greyed out whenever the slider for the denominator gives zero. An attempt to divide by zero would cause a processor exception. This has been included to show how to use the tilde (~) character.

WINAPP
c-----Copy to pm.ins
INCLUDE <windows.ins>
INTEGER enable,mode,c(5)
DOUBLE PRECISION r,v1,v2
COMMON enable,mode,c,r,v1,v2
c-----End of pm.ins
DOUBLE PRECISION min,max,step
EXTERNAL calc,setmode
INTEGER i,calc,setmode
DO i=1,5
c(i)=0
ENDDO
min=0.0D0
max=100.0D0
step=1.0D0
enable=1
mode=3
c(mode)=1
v1=0.0D0
v2=1.0D0
i=winio@('%ww[no_border,no_maxbox]%ca[Popup]&')
i=winio@('%2.2ob[thin_panelled]&')
i=winio@('%^10sl%cb&',v1,min,max,calc)
i=winio@(' %dy&',0.3D0)
i=winio@('%df%^4rf%cb&',step,v1,calc)
i=winio@('%^10sl%cb&',v2,min,max,calc)
i=winio@(' %dy&',0.3D0)
i=winio@('%df%^4rf%cb&',step,v2,calc)
i=winio@('%ff%ob[status,thin_panelled]&')
i=winio@('%ta%dy%`7rf%cb&',0.3D0,r)
i=winio@('%pm[#Multiply]&', c(1),setmode)
i=winio@('%pm[~#Divide,|]&',enable,c(2),setmode)
i=winio@('%pm[#Add]&', c(3),setmode)
i=winio@('%pm[#Subtract]', c(4),setmode)
END
c ---------------------------------------
INTEGER FUNCTION setmode()
INCLUDE 'pm.ins'
CHARACTER*10 item
EXTERNAL calc
INTEGER i,calc
c(mode)=0
item=clearwin_string@('CURRENT_MENU_ITEM')
IF(item.EQ.'Multiply') mode=1
IF(item.EQ.'Divide') mode=2
IF(item.EQ.'Add') mode=3
IF(item.EQ.'Subtract') mode=4
c(mode)=1
i=calc()
setmode=2
END
c----------------------------------------
INTEGER FUNCTION calc()
INCLUDE 'pm.ins'
enable=1
IF(v2.LT.1D-6)THEN
enable=0
IF(mode.EQ.2) mode=5
ENDIF
IF(mode.EQ.1) r=v1*v2
IF(mode.EQ.2) r=v1/v2
IF(mode.EQ.3) r=v1+v2
IF(mode.EQ.4) r=v1-v2
IF(mode.EQ.5) r=0.0D0
CALL window_update@(r)
calc=2
END

See also %pm.


System menu

System menu - %sm[menu_specification]

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

This format code, %sm, is used to augment the system menu and is constructed in a manner similar to %mn. A grave accent modifier (`) is used in order to replace the menu rather than to add to it.

For example:

i=winio@('%sm[Alpha,~Beta]',Alpha_func,Beta_cntrl,Beta_func)

will add the menu items Alpha and Beta to the end of the system menu. Beta will be greyed when the control variable Beta_cntrl has a zero value. Alpha_func and Beta_func are the associated call-back functions. If a grave accent is supplied in the form %`sm, then the two menu items will replace the system menu.

The tab character CHAR(9) (or CHAR(20)) attaches an accelerator key to a particular menu item and its associated call-back function. The syntax is the same as that for %mn above.


Enhanced menus

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

See New enhanced menus for a simpler alternative.

A ClearWin+ window can have an enhanced standard menu (%`mn) as an alternative to a standard (%mn) menu. Enhanced popup menus (%`pm) are also available. An enhanced menu has more possibilities such as bitmap entries and is more flexible for programs that update menus on the fly or read them from configuration files. Any window can be given either a normal menu or an enhanced menu.

%`mn and %`pm each take one character argument, that describes the entire menu, and one call-back function that is used for all menu events.

Example

INTEGER i,winio@,cbfunc
EXTERNAL cbfunc
CHARACTER*256 fmt
fmt='[File[-bm[openbmp],-se,E&xit],Help[About]]'
i=winio@('%`mn',fmt,cbfunc)
END
!-------------------------------------------------------
INTEGER FUNCTION cbfunc()
INCLUDE <windows.ins>
CHARACTER*16 menuitem
menuitem=clearwin_string@('CURRENT_MENU_ITEM')
cbfunc=1
IF(menuitem.EQ.'File~Exit') cbfunc=0
END
!-------------------------------------------------------
RESOURCES
openbmp BITMAP open.bmp

The character string fmt illustrates a typical enhanced menu definition:

fmt='[File[-bm[openbmp],-se,E&xit],Help[About]]'

Here the '&' character performs the same accelerator key function as for standard menus. Special options preceded by a minus sign are available as follows:

-bm[xxx] | Represents a bitmap (loaded from a resource named xxx). In the example, the text 'Open' is part of the bitmap (the font is 8pt MS Sans Serif).
-se | Menu separator
-gr | Subsequent item is greyed out
-ch | Subsequent item is checked
-he[...] | Subsequent item has help information given between square brackets. This information can include newline characters.
-rc | Subsequent item has a radio button placed in front of it.

Notice that sub-menus are specified using nested square brackets - just as they are for standard menus.

The call-back function is invoked when the user selects a menu event. This function uses CLEARWIN_STRING@('CURRENT_MENU_ITEM') to determine which event is required. In the given example, when the user selects 'Exit' the string 'File~Exit' is returned. Strings are separated by a tilde '~' character and any '&' characters in the menu names are left in place. In the given example, selecting 'Open' generates 'File~openbmp'. (Menu items often represent recently opened files. File names might contain tilde '~' characters, however no ambiguity will occur because such items will always appear in terminal positions in the menu tree structure.)

Newline and carriage return characters are ignored between menu items. This means that a menu structure can conveniently be defined in a text file, read in and presented as an enhanced menu.

If an enhanced menu is to be altered (whether it be to alter the grey/check status of an item, or to add/remove entries etc.) the menu is simply replaced using one of the calls:

CALL REPLACE_ENHANCED_MENU@(HANDLE, MENU)
CALL REPLACE_ENHANCED_POPUP_MENU@(HANDLE, MENU)

where HANDLE is an integer (kind=7) that is the (%hw) window handle of the parent window and MENU is the replacement character argument. HANDLE can be zero, in which case the most recently created window is updated. It is an error to call these routines for a window that does not use %`mn or %`pm.


New enhanced menus

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

The format code %em allows you to put icons in the left hand column of menus. %em is used once for a given window and enables the use of icons for subsequent %mn and %pm menus. %em (before %mn and %pm) therefore provides an alternative to %`mn and %`pm.

When a window description contains %em, menu items can have the name of an icon resource before the text as in %mn[File[MY_ICON/Open]]. %mn[File[MY_ICON//Open]] has the same effect but the icon will not be greyed when the item is disabled. In all other respects, %mn and %pm remain unchanged.

By default %em provides a basic enhanced menu that enables you to add icons and nothing more. Otherwise you can use one or more of the following options.

w7 and w8 | provide default (Windows 7 and Windows 8) background colours for an item when it is highlighted.
background=#rrggbb | sets the background colour of an item when it is highlighted (rr represents hexadecimal digits for the red component etc.).
border=#rrggbb | sets the border colour of an item when it is highlighted
marginbits=MYBITMAP | sets the background bitmap for the icon margin when an item is NOT highlighted (MYBITMAP is the name of a bitmap resource).
bits=MYBITMAP | sets the background bitmap for the whole item when it is highlighted
theme1 | provides a theme that is similar to Plato v4.6x.
theme2 | provides a theme that is similar to Visual Studio 2010.
height=n | enhanced menu has a default height of 16 pixels and this height is automatically increased when an icon that is greater than 16x16 is added. This options allow for greater vertical spacing between menu items in the absence of larger icons.

Typically you can use a margin bitmap to provide a graded scale in vertical lines of colour. This bitmap could have any height but should be wide enough (say 40 pixels) for the whole margin. In the same way a background bitmap for a highlighted item could provide a graded scale in horizontal lines of colour. This bitmap could have any width but should be high enough (a little more than the size of the largest icon) for the whole item.

If you use %em with one of the theme options [w7], [w8], [theme1] or [theme2] then the number of visible characters in the name of the menu item is limited to a maximum of about 30.


Accelerator key format

Accelerator key format - %ac[key]

In this section:

  • Menu format - %mn[menu_specification]
  • Dynamic Menus
  • Popup menu - %pm[menu_specification]
  • System menu - %sm[menu_specification]
  • Enhanced menus and New Enhanced menus - %em
  • Accelerator key format - %ac[key]

%ac is used to attach an accelerator key to a specified call-back function. The key name is provided as a standard character string and the call-back function is an argument associated with %ac.

For example:

EXTERNAL call_back_func
i=winio@('%ac[Ctrl+Alt+P]',call_back_func)

Other examples of valid key names are Alt+Esc, Ctrl+Shift+Del, Esc, Alt+Enter, and Ctrl+F9. See %ac for further details. See also ADD_ACCELERATOR@.


Layout and positioning

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

Format windows, created using winio@, contain text and child windows called controls. Text and controls are presented in the order in which they appear in the format string. ClearWin+ automatically positions the text and controls in a window and adjusts the size of the window to suit its contents. This automatic positioning provides for a standard blank border within the window. This border surrounds all the text and controls. It can be removed by using %ww together with its no_border option.

Text and controls in a format string can be separated by one or more of the following format codes.

%nl | gives a new line
%ta | advances to the next tab position
%ff | advances to the left margin below any existing controls
%cn | centres text and controls on the current line
%rj | right justifies text and controls on the current line

%ta and %nl can be used with an integer modifier. For example, %2nl gives two new lines.

It is important to note that, if these codes appear within a %ob box, then the effect relates to the box rather than the window as a whole. Moreover, %ob boxes can be nested. As a result it is possible to exercise a fine control over the positioning of items within a window. In extreme cases, there are other mechanisms for adjusting the position of a given item.


Centre

Centre - %cn

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

%cn forces the text and controls that follow (up to the next %nl or %ff) to be centred in the window (or box). It is often used in conjunction with buttons.

For example:

WINAPP
INTEGER i,winio@
i=winio@('%ca[ClearWin+]%bg[grey]&')
i=winio@('%cn%si!Save current changes?%2nl&')
i=winio@('%tt[Yes] %tt[No] %tt[Cancel]')
END

The %cn format code can take a grave accent format modifier. This causes centring to apply to the remainder of the format window or box. Thus a whole window or a box full of centred items may be created very easily.

For example:

i=winio@('%`cnProgram to test prime numbers&')
i=winio@('%2nlWritten by Joe Bloggs%2nl%`bt[OK]')

If %cn is used within a box then it centres objects within that box.


Right justify

Right justify - %rj

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

%rj forces text and controls that follow (up to the next %nl or %ff) to be right justified.


Tab location

Tab location - %Ntl

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

This format code allows you to change the default tab locations. Distances are measured from the left-hand edge of the window or box using multiples of the width of an average character. N is the number of tabs to set and an argument is supplied for each location. For example, %4tl would take four integer arguments specifying the first four tab locations. A complex window layout might contain several %tl formats. Each %tl format takes effect for subsequent text and controls and cancels any previous one. If you use the grave accent modifier with %tl, then the tab locations are specified as DOUBLE PRECISION values.


Box format

Box format - %n.mob[options][title]

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

%ob is used to create boxes, to create a status bar, or to create a grid. Any of these can be filled with text and controls. %ob defines the top left hand corner of a rectangular box. Subsequent items are placed to the right and beneath this point until the box is closed with %cb. Every open box must be closed before the format string (plus any continuations) is complete. Boxes can be nested, one within another, in order to provide a fine control over the positioning of items in a window. A grave accent is used to indicate that the box and all items within it should have a darker (shaded) background.

%ob can be followed by options enclosed in square brackets. The options are:

named_c | Places a given title in the top line of the box (in the centre)
named_l | Places a given title in the top line of the box (on the left).
named_r | Places a given title in the top line of the box (on the right)
no_border | Creates an invisible box which is useful for grouping controls.
panelled | Creates a three-dimensional panel.
shaded | Equivalent to %`ob.
status | The box takes the form of a status bar.
thin_panelled | An alternative to panelled.
scored | Double line, three-dimensional shade effect.
depressed | Single line, three-dimensional shade effect.
raised | Single line, three-dimensional shade effect

A status bar is a strip (with the same colour as the face of a standard button) that is placed at the bottom of a window. A status bar is typically used to display help information. The status bar format should be used at the beginning of the first (normally the only) line of status information. For example, %ob[status]%he%cb would create a status bar and place help information in it. Although status bars can be made to cover more than one line (for example by using %he in a window in which some of the help strings extend over more than one line), the result tends to look ugly. No further controls should be specified after the final %cb that closes a status bar, unless they are positioned via a %ap format code (see Absolute position format - %ap).

A name that is to be placed in the top line of the box is provided as a standard character string. For example:

WINAPP
INTEGER i,winio@
i=winio@('%ca[Named boxes]%bg[grey]&')
i=winio@('%ob[named_l][Left]&')
i=winio@('%nl Box 1%cb&')
i=winio@('%ob[named_c][Centre]&')
i=winio@('%nl Box 2%cb&')
i=winio@('%ob[named_r][Right]&')
i=winio@('%nl Box 3%cb')
END

%ob can take integer modifiers in order to create a grid. For example, %2.3ob would create a grid two items across and three down. The contents of each grid component are terminated with %cb. Thus the above case would require six %cb format codes following it to close each component of the grid.

Note that, if you place %rd (say) in the grid, you might also choose to use %co[no_data_border] in order to remove the border from the %rd control.

Most of the %ob options may be uesd when %ob is used to create a grid. However, a grid box cannot be named.

For example:

WINAPP
CHARACTER*17 str
DOUBLE PRECISION val,min,max
INTEGER i,winio@
val=1.0
min=1.0
max=10.0
str='Salford Software'
i=winio@('%ww[no_frame]%ca[multiple regions]&')
c---Define a 2x2 box---
i=winio@('%2.2ob[panelled] %7bt[one] %cb&')
i=winio@(' %7bt[two] %cb&')
i=winio@(' %7bt[three] %cb&')
c---Ddefine a slider ---
i=winio@('%10sl[horizontal] %cb%nl&',val,min,max)
i=winio@('%2.1ob[status,thin_panelled]&')
i=winio@('%`4rf%cb&',val)
i=winio@('%`rs%cb',str)
END

%ob can be used with the option no_border to divide a window into a rectangular array of sub regions that are used to position text and controls within each region. As a simple example, suppose we wish to place two buttons (one below the other) to the right of some text. Here is some code that has the desired effect.

i=winio@('%2.1ob[no_border]%dy&',0.5D0)
i=winio@('Two buttons placed %nlto the right of text.%cb&')
i=winio@('%tt[OK]%nl%dy%tt[Cancel]%cb',0.3D0)

Notice that %dy has been used to provide vertical displacement. In this context, if the single argument for %dy were given the value 1.0D0 then the use of %dy would be equivalent to %nl.


Pivot

Pivot - %pv

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

In the absence of a pivot (%pv) a window will not re-size (except to minimise). A pivot may only be placed before a control that will re-size in response. It is an error to attempt to pivot any other type of control. The following controls will accept the pivot (more may be added later, but many controls are intrinsically fixed in size):

%eb | Edit boxes
%cw | Embedded ClearWin windows
%dw | Owner draw box
%fr | Frame for MDI child windows
%gr | Graphics box, must have metafile_resize or user_resize property.
%ht | Hypertext
%ls | List box controls (but not dropdown boxes using the grave accent)
%ms | Multiple selection boxes
%og | OpenGL graphics box.
%tv | Tree-view
%tx | Text array
%uw | User defined window

An alternative %pv mechanism is available but not recommended. The alternative is is obtained by calling SET_OLD_RESIZE_MECHANISM@. In this case, the %pv format code marks the position of a pivot point. Items to the right of this point move to the right as the window is widened, whilst items below the pivot point move downwards as the window is lengthened. %nr and %nd can be used in conjunction with this mechanism.


Get and set window position formats

Get and set window position formats - %gp, %sp

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

%gp takes two integers as arguments. When the window is created these integers are set to the screen x, y co-ordinates of the point where the %gp format is used. Typically these values are used to position other windows over appropriate parts of a main window by using the %sp format. It is also used for child windows. Each time the window is moved or re-sized the x, y pair is updated.

For example:

WINAPP
INTEGER x,y,winio@
COMMON x,y
EXTERNAL myfunc
i=winio@('Press this button to conceal it! &')
i=winio@('%gp&',x,y)
i=winio@('%^bt[Press]',myfunc)
END
c---
INTEGER FUNCTION myfunc()
INTEGER x,y,winio@
COMMON x,y
c--- Window will be positioned relative to the button
c--- control in the main window
i=winio@('%spHidden!',x-5,y-5)
myfunc=1
END


Absolute position

Absolute position format - %ap

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

This format code takes two integer arguments and positions the next control at the given (x, y) point. The units are the same as those used in the %gd format code described below. This format code is not recommended for general use. The following points should be noted if %ap is used:

· Try to place all the absolute positioned objects at the end of a format, or follow a %ap format with a %ff to enable the automatic control placement mechanism to recover.

· It is possible to place controls on top of each other using this format. This is usually undesirable unless all but one of the overlapping controls are given the 'hidden' attribute.

See also %rp and %dy.


Programmer grid

Programmer grid format - %gd

In this section:

  • Introduction
  • Centre - %cn
  • Right justify - %rj
  • Tab location - %Ntl
  • Box format - %n.mob[options][title]
  • Pivot - %pv
  • Get and set window position formats - %gp, %sp
  • Absolute position format - %ap
  • Programmer grid format - %gd

%gd is for program development only. It overlays a grid over the window and any items within it. This enables controls to be positioned using the %ap format. The grid is marked in small intervals corresponding to the average character size of the default font, with major divisions every 10 such units. The grid starts at the left and top margins, but extends over the right and bottom margins, since this may help in the placement of further controls.


Text and files

Displaying text

Edit boxes

File selection and filter


Displaying text

Font name - %fn[font_name]

Get font - %gf

Font attributes - %it, %bf, %ul

System font - %sf

Font default - %fd

Subscript - %sd

Superscript - %su

Text size - %ts

Text colour _ %tc

Variable string _ %N.mst

Sterling pound symbol - %pd

Mathematical equation - %eq[equation]


Font name

Font name - %fn[font_name]

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%fn is used to select a font for subsequent text and controls.

For example:

winio@('This is an example of %fn[Times]Times%sf font.')

This causes the word "Times" to appear in Times font with the remainder of the sentence in system font. %sf is used to reset all text attributes to the system font.


Get font

Get font - %gf

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%gf takes one INTEGER(7) variable that receives the current font handle. This handle can then be used in any Windows API function that requires a font handle.

For example:

INTEGER(7) h_font
i=winio@('%ts%gf',2.0D0,h_font)


Font attributes

Font attributes - %it, %bf, %ul

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

These format codes (%it, %bf and %ul) are used to begin italic, bold face, and underlined text respectively. Each code takes the grave accent modifier (`) in order to terminate the corresponding attribute.

For example:

i=winio@('Uses %bfbold face%`bf for emphasis')

%sf (system font) is used after any combination of these format codes in order to restore the sytem font.


System font

System font - %sf

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%sf resets the text attributes and is used after any combination of %bf, %it, %ul, %fn, and %ts.

%sf can also take a grave accent (`), %`sf selects the scaleable font that is used in menus and controls. %ts (see below) can be used after %`sf in order to set the size of the scaleable font. %`sf followed by %ts with a scale factor of about 1.15 will produce readable text (see also USE_WINDOWS95_FONT@).


Font default

Font default - %fd

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%fd sets the font to the default Windows font.


Subscript

Subscript - %sd

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

A font must be selected using %fn, before %sd is used. All text following %sd will be in subscript style. A grave accent (%`sd) is used to return to the previous font setting.

For example:

i=winio@('%fn[arial] Water is H%sd2%`sdO')


Superscript

Superscript - %su

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box _ %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

A font must be selected using %fn, before %su is used. All text following %su will be in superscript style. A grave accent (%`su) is used to return to the previous font setting.

For example:

i=winio@('%fn[arial]Einstein said %tsE=MC%su2%`su.',1.8D0)

This is the result of the examples above for %su and %sd used together. In general, scaled down fonts are undesirable as they may become unreadable in lower screen resolutions.


Text size

Text size - %ts

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour _ %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%ts takes one DOUBLE PRECISION argument that is used to scale the size of any text that follows until the next %ts or %sf format code. The default value of this argument is 1.0. Values of the argument in the range from 0 to 1.0 are used to scale down, whilst values greater than 1.0 are used to scale up. Note that the system font cannot be scaled, so %fn must always be used before %ts (also see Font name - %fn[font_name]).

For example:

i=winio@('%fn[Courier New]%tsThis is larger',1.5D0)


Text colour

Text colour - %tc

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

By default, the text in a format window is coloured using the 'window text' colour that the user can select from the Control Panel in the Program Manager. This colour is returned by GetSysColor(COLOR_WINDOWTEXT). %tc is used to specify the text colour for subsequent text and controls (until another %tc overrides it). %tc takes one integer argument which is typically created using RGB@.

For example:

INTEGER RGB@
i=winio@( '%tcRed&', RGB@(255,0,0))
i=winio@(' %tcGreen&',RGB@(0,255,0))
i=winio@(' %tcBlack', RGB@(0,0,0))

It is often desirable to base the new colour on the default set by calling GetSysColor (see the description of %bg in Background colour for details of how to do this). An argument value of -1 resets the colour to the 'window text' colour.

Alternatively one of the standard colours (black, white, grey, red, green, blue, and yellow) can be specified by enclosing the colour name in square brackets (for example: %tc[red]).

Note that the text colour for a given control can be changed dynamically (after the window has been created) by calling the subroutine SET_CONTROL_TEXT_COLOUR@.


Variable string

Variable string - %N.mst

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

This format code takes one character string argument and lays out the string in a field of N characters. The string is redrawn each time the window is renewed. For this reason, the size N must be specified and must be the maximum number of characters required. The number of lines m is optional and defaults to 1. For example, %20.2st provides for 20 characters on each of two lines. Use the WINDOW_UPDATE@ function (see Updating windows) in order to force a change to become visible. %st is similar to %`rs.


Sterling pound symbol

Sterling pound symbol - %pd

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%pd will ensure that a pound '£' symbol appears correctly on the chosen output device. Note that the '£' symbol is represented differently in the OEM and ANSI character tables.


Mathematical equation

Mathematical equation - %eq[equation]

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%eq is provided to enable mathematical equations to be drawn. It is followed by a standard character string (i.e. a string in square brackets, or an '@' symbol with a string as an argument). It takes two integer arguments which are the width and depth of the equation in pixels. If the contents of the equation are not going to change, then the width and depth are set to zero, forcing the size of the region to be defined by the equation. Equations may also be included in hypertext (see Hypertext windows).

Equations are strings with the three characters {;} reserved. The following symbols can be included in strings:

{alpha} | {beta}
{gamma} | {delta}
{epsilon} | {phi}
{pi} | {zeta}
{psi} | {sigma}
{theta} | {kappa}
{lambda} | {iota}
{rho} | {mu}
{nu} | {omega}
{chi} | {tau}
{infinity} | {plus_minus}
{ge} | {proportional}
{curly_d} | {le}
{ne} | {identically_eq}
{approximately_eq} | {such_that}
{vector_sum} | {empty_set}
{set_intersection} | {set_union}
{proper_subset} | {subset}
{belongs_to} | {not_belongs_to}
{for_all} | {there_exists}
{del} | {sqrt}
{semicolon} |

The names of these special symbols are case sensitive, and the Greek characters also exist as upper case characters. In this context only the first character is upper case.

In addition, a number of more complex constructions are supplied. In the list below , the asterisk "*" stands for any equation string:

{sup *} | Superscript or exponent
{sub *} | Subscript
{divide *;*} | Division written with a horizontal bar
{sum *} | Summation without upper limit
{sum *;*} | Summation with both limits
{integral } | Indefinite integral
{integral *} | Integral with lower limit only
(integral *;*} | Full definite integral.
{symbol nnn} | Character number nnn (decimal) from the symbol font.

Note that the body of the sum or integral will be placed after the closing curly brace. Spaces are important in the above constructions.

Badly formed equations will normally cause a Clearwin+ error. However, if a grave accent modifier is specified (%`eq), the error will be suppressed.

Excessive nesting of constructs such as 'sup' or 'sub', that reduce the font size, may result in unreadable equations.

Here are a few well known equations and chemical formulae as examples:

 WINAPP
INTEGER i,w,winio@
CHARACTER*80 s(4)
s(1)='H{sub 2}SO{sub 4}'< BR> s(2)='E=mc{sup 2}'<
            BR> s(3)='{del}.B=0'
s(4)=
+'{sum n=1;{infinity}}{divide 1;n{sup 2}}={divide {pi}{sup 2};6}'
i=winio@('%ca[Equations]%bg[grey]&')
DO i=1,4
w=winio@('%ob%eq@%cb&',s(i),0,0)
ENDDO
w=winio@(' ')
END

Equations are constructed using symbols from the Times New Roman and Symbol fonts.

These same equation strings may be used in hypertext (%ht) embedded between <equation> and </equation>. The string between these delimiters is treated as a pure equation - no mark-up codes are recognised. So, for example, the '<' symbol should be written as it is.


UTF-8 characters

ClearWin+ can display UTF-8 multi-byte characters. Fortran programs use standard CHARACTER variables to hold the UTF-8 encoded character strings. These should be written into files that are saved using Code Page 65001 "UNICODE (UTF-8 without signature)". See for example "Advanced Save Options" in Plato. It is important to omit the signature otherwise FTN95 will not compile the file.

A new subroutine informs the ClearWin+ library that UTF-8 characters may be included.

SUBROUTINE ENABLE_UTF8@(enable)
INTEGER enable

'enable' is an input value set to a non-zero value to enable UTF-8 encoding or zero to disable. The default state is OFF.

Limitations: UTF-8 encoded characters cannot be used with %eb nor %pl. The behaviour with %og has not been tested.

Note: A suitable font (such as Courier New) must be used in order to display UTF-8 characters. The font can be set using %fn but the controls %cw and %pb require the option [local_font] before %fn takes effect.


Edit boxes

Edit box _ %eb

Text array - %N.Mtx[options]


Edit box

Edit box (%eb)

%N.Meb[options]

Standard call-back functions

Colouring the text and background

Text search:

Text search/replace:

Buffer positioning:

Undo operations:

Opening a file:

Inserting text:

Moving around the display:

Deleting text:

Marking blocks:

New CLEARWIN_INFO@ parameters

Clipboard cut/paste

Scroll position


Text array

Text array - %N.Mtx[options]

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

Text arrays, %tx, provide a convenient way to display a grid of characters with 'attributes' to achieve an effect analogous to that achieved under DOS by writing to the screen buffer. A text array can respond to keyboard and mouse input via its call-back function by using CLEARWIN_INFO@ (see below), updating the array as necessary. The text array format takes two character strings and two integer modifiers N, and M.

For example:

WINAPP
CHARACTER*800 text,attr
INTEGER k,winio@
text='Test colour'
CALL char_fill@(attr,char(0))
CALL char_fill@(attr(1:4),char(1))
CALL char_fill@(attr(6:11),char(2))
k=winio@('%60.8tx&',text,attr,80L,10L)
k=winio@('%tc[blue]%ty[red]%tc[yellow]%ty[green]')
END

In the above example, the text array text is displayed in the box as an 80 x 10 array of which initially only 60 x 8 is visible. The size of the control can be varied if it is preceded by a pivot (%pv) in a variable sized window. The attr array contains attribute numbers stored using CHAR(i) where 0 < i < 255. Zero is the default attribute (usually black on white), others are defined by subsequent %tc[fgcolour] %ty[bgcolour] format pairs. The first %tc%ty pair defines colour index 1and so on. fcolour is the foreground colour of the text, and bgcolour is the background. In the above example, the word 'Test' appears as blue on a red background whilst the word 'colour' appears as yellow on a green background. The colour can be specified as an RGB@ value in the argument list if the colour in brackets is omitted. Changes in font attributes (underlining, etc.) are not possible with %tx.

%tx may have a call-back functino that can use the following CLEARWIN_INFO@ strings:

TEXT_ARRAY_CHAR | value of key pressed
TEXT_ARRAY_DEPTH | holds the new value on resizing
TEXT_ARRAY_MOUSE_FLAGS | mouse button press information
TEXT_ARRAY_RESIZING | text array window dimension change
TEXT_ARRAY_WIDTH | holds the new value on resizing
TEXT_ARRAY_HEIGHT | holds the new value on resizing
TEXT_ARRAY_X | location x when the mouse is pressed in %tx
TEXT_ARRAY_Y | location y when the mouse is pressed in %tx

The TEXT_ARRAY_RESIZING parameter is set to one only in a call-back responding to a re-sizing event. The next two parameters in the table only have meaning in this context. They supply the new size of the control in average characters.

The TEXT_ARRAY_X and TEXT_ARRAY_Y parameters give the mouse position in characters from the top left corner, and are zero based. The mouse flags, that contain information about which mouse button (if any) is depressed, can be obtained by a call to GET_MOUSE_INFO@. The option FULL_MOUSE_INPUT is specified in order to force the call-back function to be called whenever the mouse moves over the control.

TEXT_ARRAY_MOUSE_FLAGS uses bitwise flags as follows:

MK_LBUTTON | 1 | Left mouse button depressed
MK_LBUTTON | 2 | Right mouse button depressed
MK_SHIFT | 4 | Keyboard shift key depressed
MK_CONTROL | 8 | Keyboard control key depressed
MK_MBUTTON | 16 | Middle mouse button depressed

By default, the call-back function is called when a keyboard character is received while the control has the focus. The character is placed in the parameter TEXT_ARRAY_CHAR. If the option FULL_CHAR_INPUT is specified, the call-back function receives each keystroke using the Microsoft VK_ parameters (defined in the file windows.ins). The call-back is invoked for each key press and each key release. In the latter case TEXT_ARRAY_CHAR parameter has the top bit set. The parameter TEXT_ARRAY_CHAR will be zero when not in use. To respond to ALT key combinations you should use the %ac facility rather than tracking the ALT key with FULL_CHAR_INPUT. This is because messages associated with the release of the ALT key might be delayed until the next key is pressed. The option USE_TABS may be used to cause the tab key to be passed to the call-back rather than performing its normal Windows function of moving between controls.

The system font is used in a %tx control, unless %fn appears before %tx. If %fn is used then a mono-spaced font (such as Courrier New) should be selected because the text array must be aligned both vertically and horizontally.

Note that the text array is not re-dimensioned if the control is re-sized. Re-sizing simply changes the region that is visible.

The text array control ( %tx) is used extensively in the 32 and 64-bit debuggers SDBG and SDBG64.


File selection and filter

File selection _ %fs[path]

File filter _ %ft[name][filter]


File selection

File selection - %fs[path]

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%fs together with the related %ft format code (see below), changes the default file selection used by a subsequent FILE_OPENR or FILE_OPENW call-back function (see FILE_OPENR). The information is used in the standard Windows dialog displayed by these call-back functions. %fs is followed by a standard character string, that is either:

a) the path name of a directory to be used rather than the current working directory (e.g. C:\TEST), or

b) a complete file selection specification (e.g. C:\TEST\*.EXE).

In the latter case the file filter information, displayed at the bottom of the standard 'file open' dialog, is replaced by the specified filter.

WINAPP
CHARACTER*129 filenm
INTEGER i,winio@
COMMON filenm
EXTERNAL disp_name
filenm=' '
i=winio@('%fs[c:\dbos.dir\*.wri]&')
i=winio@('%mn[&File[&Open]]&','FILE_OPENR',filenm,disp_name)
i=winio@('%mn[[E&xit]]','EXIT')
END

INTEGER FUNCTION disp_name()
CHARACTER*129 filenm
INTEGER i,winio@
COMMON filenm
i=winio@('%ws %`bt[OK]',filenm)
disp_name=1
END


File filter

File filter - %ft[name][filter]

In this section:

  • Displaying Text
    • Font name - %fn[font_name]
    • Get font - %gf
    • Font attributes - %it, %bf, %ul
    • System font - %sf
    • Font default - %fd
    • Subscript - %sd
    • Superscript - %su
    • Text size - %ts
    • Text colour - %tc
    • Variable string _ %N.mst
    • Sterling pound symbol - %pd
    • Mathematical equation - %eq[equation]
  • Edit Boxes
    • Edit box - %eb
    • Text array - %N.Mtx[options]
  • File selection and filter
    • File selection - %fs[path]
    • File filter - %ft[name][filter]

%ft is used to change the default filter for subsequent use of the FILE_OPENR and FILE_OPENW call-back functions (see FILE_OPENR). The information is used in the standard Windows dialog displayed by these call-back functions. Two standard character strings are required after %ft. The first is the name of the filter (e.g. 'Executable files'). The second is the specification (e.g. '*.EXE').

For example:

i=winio@('%ft@@','Executable files','*.EXE')

Alternatively,

i=winio@('%ft[Executable files][*.EXE]')

If the grave accent modifier is used with %ft, the filter information replaces the existing information, otherwise it is added at the front of any existing filter information. The default filter selects all files.

You cannot change the name and filters dynamically by using %fs and %ft with variable character strings. See GET_FILTERED_FILE@.


%eb[options]

%N.Meb[options]

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

This format code, %eb, provides a text editor and is by far the most complex format available. However, many applications will not require any of the embellishments detailed below. Note that %rs and %re are simpler to use but are limited to 32768 characters.

Two arguments are required, a pointer to the buffer containing the text to be edited, and an integer specifying the maximum size of the buffer. The text should be terminated by the null (CHAR(0)) character, and new lines should consist of carriage return/line feed pairs. This does not use the standard Windows edit control and as a result there is no limit (other than the total available memory) to the size of the text area. If the second argument (the length of the buffer) is set to zero, the edit box allocates its own memory for the buffer, re-sizing it as required.

%60eb denotes an edit box that displays 60 characters on one line (which is the same as %60.1eb). %60.20eb denotes an edit box that displays 60 characters by 20 lines.

The text itself has the format of a normal DOS text file (lines of text separated by a carriage return/line feed character pair) with a closing a null terminator. The edit box can also handle text lines separated by carriage return characters only, providing this is used consistently.

In order to read/write data to a file in this format the file should be opened in binary mode.

For example:

WINAPP
CHARACTER*1000 buffer
CHARACTER*80 fname
INTEGER(2) handle,err_code
INTEGER bytes_read,nbytes,winio@
fname='myfile'
CALL openr@(fname,handle,err_code)
CALL readf@(buffer,handle,1000,bytes_read,err_code)
CALL closef@(handle,err_code)
i=winio@('%60.20eb',buffer,1000)
CALL openw@(fname,handle,err_code)
nbytes=INDEX(buffer,CHAR(0))-1
CALL writef@(buffer,handle,nbytes,err_code)
END

The only null character in the string must be at the end. You must include the null character when calculating the length of a string. In the above example, the Fortran INDEX intrinsic function has been used to obtain the size of the edit buffer. An alternative method is given below. Note that OPENR@ etc. are Silverfrost Fortran library routines.

[options] is a list of items surrounded by square brackets and separated by commas. The entire (square-bracketed) list may be omitted if no options are required.

hscrollbar | Supply and control a horizontal scroll bar.
limited_hscrollbar | Like hscrollbar but the user is prevented from scrolling horizontally until all characters have disappeared.
vscrollbar | Supply and control a vertical scroll bar.
no_hscroll | Inhibit all horizontal scrolling.
no_vscroll | Inhibit all vertical scrolling.
alt_edit | Changes the action of Del, Backspace, and Enter keys so that they never split or join lines.
fixed_font | Uses a fixed font for the edit box, rather than the default variable font. (However, it is preferable to use %fn, with a monospaced font such as Courier New, before %eb in the format string.)
hook_focus | Causes the call-back to be called every time the box gains or loses the focus. Note that the over use of this option can cause annoying effects for the user and more importantly an infinite loop may be started if the result of an object gaining a focus is the shift of that focus to another object!
use_tabs | Uses tabs in the edit box in the normal way for an editor. Otherwise tabs are used to cycle through the various controls in the parent window.
no_frame | Removes the line around the edit box without removing the blank border (no_border removes both). This option is particularly useful for edit boxes which fill a window.
no_border | Omit the blank border that by default is placed between the text and the surrounding box.
read_only | Prevents the user from changing the text. The cursor can still be used to scroll through the text.
user_colours | The call-back function is invoked in such a way that the colours used for text and its background can be modified. This facility could be used, for example, to produce an editor which highlighted certain keywords. The use of this option is described further below.
extended | Allows CLEARWIN_STRING@('CALLBACK_REASON') to be used within a call-back function. For %eb the possible returns include 'DATA_ALTERATION'.
undo | Causes the edit box to save information to enable changes to be 'undone'. By default all changes are recorded and can be undone in reverse order. The program can also restrict the amount of undo information by calling a function. The standard call-back function 'EDIT_UNDO' is used to perform one level of undo each time it is invoked. Menus or buttons attached to this call-back will automatically become grey when no more undo information is available. The undo mechanism can reverse changes made using the keyboard/ mouse or by calling any of the edit-box related functions. However changes made by directly altering the buffer and calling WINDOW_UPDATE@ will not be recorded and cannot be reversed.
no_cursor_snap | By default if, when you move the cursor up or down, you end up off the end of the line, the cursor will snap back to the end of the line. For some purposes, such as when you are using block marks (see below), this is inconvenient. Use the no_cursor_snap option to leave the cursor in free space on the end of the line.
report_double_clicks | Responds to a mouse (left) double click by calling the call-back function rather than by marking a word.
report_right_clicks | Responds to a mouse right click by calling the call-back function rather than by looking for a pop-up menu.

EDITINFO

The edit box maintains a set of variables in a structure (called an EDIT_INFO structure) that controls the operation of the box. Normally these variables are hidden. However, much more detailed control of the edit box can be obtained by using the grave accent edit modifier and by supplying an array of the form:

INTEGER info(24)

Note that the array size and offsets are for 32 bit applications (see below).

If more than one edit box is open, each one must have its own EDIT_INFO structure.

The following example illustrates the use of this structure, making use of the following identifiers:

Offset | Label | Description
1 | h_position | Cursor horizontal character position.
2 | v_position | Cursor vertical character position.
3 | last_line | Total number of lines in the buffer.
4 | buffer (INTEGER(7) | Address of edit buffer.
5 | size | Size of buffer contents (excluding null terminator).
6 | max_buffer_size | Size of memory block.
7 | current_position (INTEGER(7)) | Address of the position corresponding to eb_h_position/eb_v_position.
8 | selection (INTEGER(7)) | Address of selected text if any.
9 | n_selected | Number of selected characters.
10 | vk_key | Set to VK_TAB etc. if this handles a key press.
11 | vk_shift | Shift state corresponding to key.
12 | active | Set to the number of the edit box (1 if only one edit box is open) when a call-back is invoked, reset afterwards. This value is used to identify which edit box is associated with the current use of a call-back function.
13 | modified | Set to 1 each time the buffer is modified.
14 | closing | Set when buffer is about to be closed.
15 | n_chars_to_colour | Count of characters to colour.
16 | text_to_colour (INTEGER(7) | Address within buffer for region to colour.
17 | text_colours (INTEGER(7)) | Address of foreground colours.
18 | background_colours (INTEGER(7)) | Address of background colours.
19-24 |  | Reserved for future enhancements.

NB. For 64 bit applications, addresses (shown as INTEGER(7) in the above table) become 64 bit integers so the offsets and size for the integer array must be adjusted accordingly. As a result it is simpler to use the TYPE that is named edit_info that is defined in clearwin.ins and used in the corresponding standard modules.

Although this structure is passed to most of the functions described below, you will not normally need to know its contents nor should you normally need to manipulate the buffer yourself. (You can do so it you wish, but you must remember to update the contents consistently and to make use of WINDOW_UPDATE@ at appropriate intervals.)

The following example takes the last example above and adapts it so that a) the edit box allocates its own buffer with address eb_buffer and b) the eb_modified flag is checked before a prompt to save the edited file.

WINAPP
INTEGER(2) handle,err_code
INTEGER i,winio@
INTEGER info(24),
1 eb_h_position, eb_v_position, eb_last_line,
2 eb_buffer, eb_buffer_size, eb_max_buffer_size,
3 eb_current_position,eb_selection, eb_n_selected,
4 eb_vk_key, eb_vk_shift, eb_active,
5 eb_modified, eb_closing, eb_reserved(10)
EQUIVALENCE
1 (eb_h_position, info(1)), (eb_v_position, info(2)),
2 (eb_last_line, info(3)), (eb_buffer, info(4)),
3 (eb_buffer_size, info(5)), (eb_max_buffer_size,info(6)),
4 (eb_current_position,info(7)), (eb_selection, info(8)),
5 (eb_n_selected, info(9)), (eb_vk_key, info(10)),
6 (eb_vk_shift, info(11)),(eb_active, info(12)),
7 (eb_modified, info(13)),(eb_closing, info(14)),
8 (eb_reserved, info(15))
i=winio@('%60.20`eb','*',0,info)
IF(eb_modified.EQ.1)THEN
i=winio@('%cnSave changes?%2nl%6bt[Yes] %6bt[No]')
IF(i.EQ.1)THEN
CALL openw@('myfile',handle,err_code)
CALL writef@(CCORE1(eb_buffer),handle,eb_buffer_size,
+ err_code)
ENDIF
ENDIF
END

Note the use of the Silverfrost-supplied intrinsic function CCORE1 to return the character string at the given address.

The Silverfrost-supplied intrinsic function LOC can be used when the address of a variable is required. For example, if an edit buffer is provided, the following fragment of code would give the position of any selected text in the window relative to the beginning of the file.

CHARACTER*1000 buffer
INTEGER position,info(24)
.....
i=winio@('%60.20`eb',buffer,1000,info)
position=eb_selection-LOC(buffer)

Note also that, if an edit buffer is provided, a call-back function can be used to monitor the size of the text in the buffer and to make a call to GET_STORAGE@ if it is getting full. If the buffer overflows, the system will generate a fatal error.

%eb can take the caret (^) format modifier to indicate that a call-back function is supplied (after the address of the EDIT_INFO structure if any). This function is called whenever the contents of the box change, a key is pressed, or the cursor is moved. If the call-back function does not handle the response to control keys such as Delete, BackSpace, etc., then it should return a zero value.

This format code can also use the tilde (~) format modifier to indicate that a grey control variable is supplied. This variable should precede the call-back function (if any) in the argument list.

An edit box will almost certainly contain information that the user will not wish to lose, so it is a good idea to use the %cc format to monitor the closure of the main window.


Standard call-back functions

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

The following standard call-back functions (described in Standard call-back functions) can be used with a %eb edit box.


Colouring the text and background

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

The grave accent is used with %tc in order to provide the text colour for a %eb edit box. %`tc then takes an integer argument which is the RGB value for the text colour. This colour can be changed under program control. Here is some sample code that illustrates the concept:

INTEGER clr
clr=RGB@(255,255,0)
...
i=winio@('%`tc&', clr)
i=winio@('%20.20eb', buffer, 10000)
...

In order to update the colour of the whole text in the edit box, the following code would appear in a call-back (obvously, you could use RGB@ instead of GetSysColour):

...
clr=GetSysColor(COLOR_HIGHLIGHT)
CALL window_update@(clr)

In order to change the colours of selected parts of the text dynamically, you should supply the user_colours option to %eb (use %^`eb[user_colours] in a winio@ call) together with an EDIT_INFO array and a call-back function.

Extra invocations of your call-back function will be made for each line of text when it is about to be displayed. This call-back will be indicated by a non-zero value of the n_chars_to_colour component of the EDIT_INFO array. In this case text_colours and background_colours are the addresses of arrays of 4-byte colour values, such as those created by using RGB@. These values will have already been initialised to the default values including colour changes associated with text selection, but you are able to modify the values as required. Note that the colours may be adjusted by display drivers using a limited number of colours.

It is very important to ensure that the function which alters the display colours does not itself perform any screen I/O. At the point when the colouring request is made, Windows has issued a WM_PAINT message, and Windows will become unstable if this rule is not followed.

Since the colours are stored as 4-byte integers, this leaves the top byte of each colour otherwise unused (it is set to zero by RGB@). With %eb, you can set the following bits in the foreground colour:

Z'40000000' | Force underline.
Z'20000000' | Force italic.
Z'10000000' | Force bold.
Z'08000000' | Hide the character.

These bits only add attributes, so if the basic font for the edit box has been set bold (say) the bold bit will have no effect. The 'hide character' bit removes the corresponding character (and the space it occupies) from the screen. This is useful for implementing magic text sequences to achieve special effects. For example, suppose you were writing a program to display some text containing URL's. If you surrounded the URL's with some special character sequences to identify them:

$$$https://www.silverfrost.com$$$

your program could recognise these sequences and make them invisible while changing the colour/attributes of the characters comprising the URL.

The following functions have been added to help manipulate edit boxes:


Text search

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

INTEGER FUNCTION FIND_EDIT_STRING@(E,STR,BACKWARDS,WHOLE_WORD, &
CASE_SENSITIVE,SELECT_RESULT)
INTEGER E(24) ! EDIT_INFO block
CHARACTER(*) STR ! String to seek
LOGICAL BACKWARDS ! Set TRUE to perform backward search
LOGICAL WHOLE_WORD ! Set TRUE to seek a whole word
LOGICAL CASE_SENSITIVE ! Set TRUE when case must match
LOGICAL SELECT_RESULT ! Set TRUE to leave result selected

This function searches for the specified string and returns 1 if successful and zero otherwise. Typically you would supply a search menu item on a window containing an edit box. In the call-back function associated with that menu you would display a dialog box to obtain the string (%rs) and some of the various flags (%rb) and then call FIND_EDIT_STRING@. Although designed for %eb, this function may also be useful when searching for a sub-string in a string obtained from some other source.

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Text search/replace

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

INTEGER FUNCTION FIND_REPLACE_EDIT_STRING@(E,STR,REPLACEMENT, &
BACKWARDS,WHOLE_WORD,CASE_SENSITIVE,REPLACE_ALL)
INTEGER E(24) ! EDIT_INFO block
CHARACTER(*) STR ! String to search for
CHARACTER(*) REPLACE ! Replacement string
LOGICAL BACKWARDS ! True to perform backward search
LOGICAL WHOLE_WORD ! Seek a whole word
LOGICAL CASE_SENSITIVE ! Case must match
LOGICAL REPLACE_ALL ! Continue until the end or begining of file

This function searches for the specified string and replaces it with the replacement string. The function returns a count of the number of replacements made.

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Buffer positioning

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

INTEGER FUNCTION SCROLL_EDIT_BUFFER@(E,HPOS,VPOS)
INTEGER E(24) ! EDIT_INFO block
INTEGER HPOS
INTEGER VPOS

This function positions the buffer at a given point and returns 1 if successful and zero otherwise.

INTEGER FUNCTION ADVANCE_EDIT_BUFFER@(E,N)
INTEGER E(24) ! EDIT_INFO block
INTEGER N ! Count of characters to move

This routine moves the pointer through an edit buffer character by character. The carriage return/line feed character pair are treated as one. N can be set to a negative value in order to move backwards through the buffer. The number returned is the number of character positions moved. Thus unless the start or end of the buffer was encountered, the value of N will be returned unchanged.

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Undo operations

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

SUBROUTINE UNDO_EDIT_CHANGE@(E)
INTEGER E(24) ! EDIT_INFO block

Performs one level of undo operation. A single undo may reverse the effects of several function calls. Direct user interactions with the edit box are tagged so that one user command is reversed at each step (even though it may be implemented in several steps). Other operations should be tagged as required using NEXT_EDIT_OPERATION@ described next.

SUBROUTINE NEXT_EDIT_OPERATION@(E)
INTEGER E(24) ! EDIT_INFO block

Calling this function indicates to the edit box that future changes are to be considered to belong to a new user operation. Typically you would call this routine at the head of a menu call-back function that was about to change the edit buffer in some way. If you perform a long series of changes without calling this function, they will all be reversed as a block if the user performs an undo operation.

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Opening a file

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

INTEGER FUNCTION OPEN_EDIT_FILE@(E,FILE)
INTEGER E(24) ! EDIT_INFO block
CHARACTER(*) FILE ! Name of file to open

This function discards any existing information in the edit buffer and reads the contents of the specified text file into the buffer. It returns 1 on success and zero if it was unable to open the file. To use this function successfully you are advised to specify a zero buffer size with %eb to obtain a dynamically allocated buffer. Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Inserting text

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

SUBROUTINE INSERT_EDIT_STRING@(E,STR)
INTEGER E(24) ! EDIT_INFO block
CHARACTER(*) STR ! String to insert

Inserts the given string (including any trailing blanks) into the buffer at the current point and advances the current point to beyond the insertion. To insert a new line into data containing carriage return-line feeds (i.e. the binary image of a file) you should insert carriage return (decimal 13) followed by line feed (decimal 10). Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Moving around the display

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

SUBROUTINE EDIT_MOVE_HOME@(E)
INTEGER E(24) ! EDIT_INFO block

Moves the cursor to the start of the line (as if the HOME) key had been pressed.

SUBROUTINE EDIT_MOVE_END@(E)
INTEGER E(24) ! EDIT_INFO block

Moves the cursor to the end of the line (as if the END key had been pressed).

SUBROUTINE EDIT_MOVE_TOF@(E)
INTEGER E(24) ! EDIT_INFO block

Moves the cursor to the top of the file (as if CTRL-HOME had been pressed).

SUBROUTINE EDIT_MOVE_BOF@(E)
INTEGER E(24) ! EDIT_INFO block

Moves the cursor to the bottom of the file (as if CTRL-END had been pressed).

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Deleting text

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

INTEGER FUNCTION EDIT_DELETE_LINES@(E,N)
INTEGER E(24) ! EDIT_INFO block
INTEGER N ! No of lines to delete

This function deletes N lines starting at the current position. It returns the number of lines actually deleted, which may be less than N if the end of the buffer is encountered.

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


Marking blocks

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

SUBROUTINE EDIT_OPEN_LINE_MARK@(E)
INTEGER E(24) ! EDIT_INFO block

This starts a line-mode selection. Initially the selection covers the current line, but it can be extended upwards or downwards by moving the cursor key. The selected area can be cut/paste in the same way as an ordinary character selection.

SUBROUTINE EDIT_OPEN_BLOCK_MARK@(E)
INTEGER E(24) ! EDIT_INFO block

This starts a block (or column) selection. To use this you probably want to use the no_cursor_snap option (see above) since the user will be creating and manipulating rectangular regions on the screen.

SUBROUTINE EDIT_CLOSE_MARK@(E)
INTEGER E(24) ! EDIT_INFO block

This will close a selection of either type.

Alternatively you can pass the window handle instead of the EDIT_INFO.

See also: EDIT_INFO


CLEARWIN_INFO@ parameters

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

An extra CLEARWIN_INFO@ parameter has been added to help programs with several edit boxes.

'ACTIVE_EDIT_BOX' returns the address of the EDIT_INFO array of the currently active edit box. Notice that this edit box might not have focus if, for example, the user had just moved to a menu item.

'EDIT_KEY' returns the ASCII value of the last key pressed. This information can be obtained in response to a return of 'DATA_ALTERATION' from CLEARWIN_STRING@('CALLBACK_REASON'). In order to activate this feature you must use the %eb[extended]. The call-back is called after the change has been made so you will need to use one of the above editing functions if you want to undo the key press.


Clipboard cut/paste

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

The address of an EDIT_INFO structure associated with an edit box can also be passed to the following functions:

INTEGER FUNCTION EDIT_CLIPBOARD_COPY@(E)
INTEGER FUNCTION EDIT_CLIPBOARD_CUT@(E)
INTEGER FUNCTION EDIT_CLIPBOARD_PASTE@(E)
INTEGER FUNCTION EDIT_REFRESH@(E)

The first three functions perform the indicated clipboard operation using the current cursor position and current selected text in the edit box. They would typically be called from an edit menu call-back. The last function informs the edit control that the contents of the buffer have been replaced. In each case the function returns one if successful, and zero otherwise.


Scroll position

In this section:

  • %N.Meb[options]
  • Standard call-back functions
  • Colouring the text and background
  • Text search
  • Text search/replace
  • Buffer positioning
  • Undo operations
  • Opening a file
  • Inserting text
  • Moving around the display
  • Deleting text
  • Marking blocks
  • New CLEARWIN_INFO@ parameters
  • Clipboard cut/paste
  • Scroll position

The address of an EDIT_INFO structure associated with an edit box can also be used to get the cursor position of the top left corner of the window and to scroll vertically to make a given line appear as the first line.

SUBROUTINE EDIT_WINDOW_TOP_LEFT@(E,HPOS,VPOS)
SUBROUTINE SET_EDIT_FIRST_LINE@(E,VPOS)
INTEGER E(24) ! EDIT_INFO block
INTEGER HPOS,VPOS

In the first of these two routines, a return value of (-1) indicates an error condition.


Help

In this section:

  • Introduction
  • Tooltip help - %th
  • Help format - %n.mhe

The question mark "?" is used as a format modifier in order to signify that a help string is supplied. By default, the help string is displayed at the bottom of the window. The help string is either surrounded by square brackets, or an "@" character is placed in the format string to indicate that the help string is supplied as an extra argument. In addition to "?", %th and %he are used to change the manner in which a help string is presented.


Bubble and tooltip help

Bubble and tooltip help - %bh and %th

  • Introduction
  • Bubble and tooltip help - %bh and %th
  • Help format - %n.mhe

%bh takes an INTEGER argument that is a control variable. When this variable is non-zero, help text is supplied in the form of a "bubble" whenever the mouse cursor lies over the control in question. To enable users to switch such help on and off, simply supply a button with a call-back function that changes the integer control variable.

For example.

INTEGER switch,i
COMMON switch
EXTERNAL toggle
CHARACTER*60 hlp
hlp='Toggle bubble help On/Off'
c--- Define a button with help attach the help ---
c--- string with an @ symbol ---
switch=0
i=winio@('%^?bt[Start]@%bh',toggle,hlp,switch)
END

INTEGER FUNCTION toggle()
INTEGER switch
COMMON switch
switch=1-switch
toggle=2
END

A grave accent can be added to %bh. This has the effect of generating a short delay before the help bubble appears.

%th is used as an alternative to %`bh. %th provides a help bubble in the form of a "tooltip".


Help format

Help format - %n.mhe

  • Introduction
  • Tooltip help - %bh and %th
  • Help format - %n.mhe

By default, help information (associated with the "?" format modifier) is displayed at the bottom of the window. When %he is used, the point at which %he appears in a format string specifies the location of the help information. The information could (for example) be placed inside a box.

In the form %he (without the integer modifiers), the area for the help string will be sized to fit the largest help string so far encountered. If further help strings are supplied after %he, their lengths should not exceed this size. In most cases help boxes are best placed at the bottom of a window. However, if necessary, an earlier help string could be padded with spaces in order to increase its size.

%20he fixes the size of the area to 20 standard characters on one line, whilst %20.3he has the same width but occupies 3 lines.

In the following example the help information is placed in a box below the %rd edit box.

INTEGER n_ch
CHARACTER*32 str,hlp
n_ch=0
str='No of children:'
hlp='How many children have you got?'
i=winio@('%21st%?rd@%2nl&',str,n_ch)
i=winio@('%ob%he%cb',hlp)


Window attributes

Caption - %ca[title]

Window handle - %hw

Control handle - %lc

Leave window open - %lw[option]

Start-up call-back - %sc

Child window - %ch

Control variable - %cv

Create MDI frame - %fr

Attach window - %aw

Drag and drop - %dr

Set window position - %sp

Set window size - %sz

Window style - %ww[options]

Background colour - %bg[colour]

ClearWin window - %N.Mcw[options]

Property sheet - %Nps

Property sheet child - %sh

Closure control format - %cc

Delayed auto recall - %dl

Wallpaper - %wp[bitmap]

User window - %uw[class_name]

Screen saver - %sv

Disable screen saver - %ns

Taskbar icon - %ti


Caption

Caption - %ca[title]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%ca defines the title for a format window. The title is supplied as a standard character string.

For example:

i=winio@('%ca[Error]')

The caption will be re-drawn whenever the window is refreshed. This means that if the title is supplied in the argument list (signified by the "@" character in the format string) then the window title can be changed dynamically by changing the contents of the string and calling WINDOW_UPDATE@.


Window handle

Window handle - %hw

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%hw is used to return the window handle of the format window being created. This will be the same as the handle returned by a call to CLEARWIN_INFO@('LATEST_FORMATTED_WINDOW'). %hw takes one integer (kind=7) argument for the return value.


Control handle

Control handle - %lc

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%lc is similar to %hw and provides the window handle of the control immediately preceding %lc in the format string.


Leave window open

Leave window open - %lw

By default, winio@ does not return until the window that it creates is closed. Occasionally it is useful to create a window that remains open while the program takes other actions. %lw causes winio@ to return as soon as it has created the window (the return value of winio@ is not used in this case). The format takes one INTEGER argument that can be used to close the window. This integer, known as the control variable, is set to -1 while the window is still active. It is very important that the control variable used to receive the result does not cease to exist before the window closes. Hence it is necessary to use a variable that is either global (appears in the main program, a COMMON block or MODULE) or static (appears in a SAVE or DATA statement).

%lw is also used to create a child window that is to be inserted within another window that includes %ch. The grave accent (`) is used in this context. In this case the window is not displayed until the control variable is passed to the window containing %ch. See %ch below for an example of this procedure. A child window may be used only once. If it is not used it will be destroyed when the program terminates.

A window that has been left open by means of %lw can be closed by setting its control variable to a non-negative value and by passing the address of the control variable to window_update@. Setting the control variable to -2 will close the window after a short delay.

For example:

INTEGER control
i=winio@('Processing - please wait%lw',control)
CALL do_something_complex()
control=0
CALL window_update@(control)

It is possible to use %lw in conjunction with graphics drawing using %gr, %og or %dw. This provides a means of drawing to a region after it has been created. However, it is recommended that code to draw to a graphics region be placed in a call-back function attached to %sc.


Start-up call-back

Start-up call-back - %sc

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%sc takes one call-back function which is called only once when the window is first displayed. It has several uses, one of which could be to display a start-up message.


Child window

Child window - %ch

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%ch inserts a child window created by %`lw in a previous call to winio@. The format takes a single INTEGER argument that is the control variable of the child window.

Child windows are automatically restored on top of their parent and are constrained to lie within it. If they have a caption (as they will by default) they can be moved by the user. Child windows created in this way are fixed in size and location (relative to the parent window). Here is a simple example:

INTEGER control_var
i=winio@('%ww[no_frame]%`lw',control_var)
i=winio@('This is a child window%2nl%ch',control_var)


Control variable

Control variable - %cv

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%cv is used to establish a control variable for a window that does not use %lw. It takes an INTEGER control variable as an argument. This is used to enable another window to attach itself as a child using the %aw format.


Create MDI frame

Create MDI frame - %fr

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%fr is used in a parent window to define a frame into which child windows are placed. These windows can be moved and re-sized within this MDI (multi-document interface) frame. The format takes two integer arguments that define the width and height of the frame in pixels. A MDI frame can be preceded by the pivot (%pv), in which case it will expand as the window expands. There is an example using %fr appears with %aw.

A grave accent (`) can be added to %fr to cause it to maintain a handle identifying the currently selected child window. An extra integer (kind=7) argument is supplied to hold the returned handle. The integer will be zero if there is no child window. When a child window is created, the handle is obtained by using %hw (see Window handle - %hw). A comparison may then be made between the handle updated by %fr and those previously returned by %hw.


Attach window

Attach window - %aw

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%aw attaches the window as an MDI child of a parent. The parent must contain an MDI frame (%fr). %aw takes an INTEGER argument that is a control variable attached to the parent window (the parent must already exist). If the parent window does not use %lw, and therefore does not have a control variable, use %cv in the parent window. In general the child window should have a caption so that it can be moved, maximised, minimised, etc. within the frame. This means that you should not use the %ww no_caption option in this context.

The following code provides the basis of a simple "multipad" editor using %fr and %aw.

WINAPP
INTEGER ctrl,winio@
EXTERNAL open_func
CHARACTER*128 fname
COMMON ctrl
fname='*.for'
i=winio@('%ww[no_border]&')
i=winio@('%mn[&File[&Open]]&',
+ 'FILE_OPENR[Open]',fname,'+',open_func,'EDIT_FILE',fname)
i=winio@('%mn[[E&xit]]&','EXIT')
i=winio@('%pv%fr&',400L,300L)
i=winio@('%lw',ctrl)
END
INTEGER FUNCTION open_func()
COMMON ctrl
INTEGER ctrl,winio@
i=winio@('%pv%aw&',ctrl)
i=winio@('%20.8eb[no_border]','*',0L)
open_func=1
END

Details of the standard call-back functions FILE_OPENR, +, EDIT_FILE, and EXIT are given in Standard call-back functions.


Drag and drop

Drag and drop - %dr

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%dr takes a call-back function that is called when a file is dropped on to a window. If a collection of files is dropped, the call-back is called for each file in turn. This can be achieved, for example, by the following actions:

· Open the File Manager or Explorer and select one or more files.

· Drag the files to the format window containing %dr.

· Use CLEARWIN_STRING@('DROPPED_FILE') in the call-back associated with %dr.

For example, a text editor could use this feature by opening the droppped file for editing.

The following code illustrates how %dr works:

WINAPP
INTEGER i,winio@
EXTERNAL drop_func
i=winio@('%ca[Drag and drop]%bg[grey]&')
i=winio@('Drop files here....&')
i=winio@('%dr',drop_func)
END
c --------------------------------------------------
INTEGER FUNCTION drop_func()
INCLUDE <clearwin.ins>
CHARACTER*129 filename
INTEGER i
filename=clearwin_string@('DROPPED_FILE')
i=winio@('%ca[Dropped file]%bg[grey]&')
i=winio@('%`20rs&',filename)
i=winio@('%2nl%cn%tt[Next file]')
drop_func=2
END


Set window position

Set window position - %sp

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

This format code, %sp, is used to initialise the position of the window on the screen. Integer arguments x and y are used to specify the position of the top left-hand corner of the window in screen co-ordinates.

For example:

i=winio@('%si?%spWhy is this stuck in the corner',0L,0L)

If more than one position format is used, the positions are added vectorially. This is particularly useful in conjunction with the get window position format %gp.


Set window size

Set window size - %sz

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%sz takes two INTEGER variables (w,d) in the form:

INTEGER w,h
i=winio@('%sz',w,h)

w and h are usually given zero values in the program before the first call to winio@. Zero values are ignored by winio@. (w,h) subsequently hold the current pixel width and height of the window. These values will change when the window is sized. When the window is closed, the latest values can be stored (in a configuration file for example) and used the next time the same window is opened. In this way you can recreate the window size that was last used. A maximised window is configured in the same way because specific values are used to represent this state.


Window style

Window style - %ww[options]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

This format code causes the resultant window to look like an application window, rather than a dialog window. The window can be maximised, etc.. %ww can be followed by an option list enclosed in square brackets (use an empty list if options are not used and the next character in the format string is an open square bracket '['). The following options are available:

casts_shadow | This option produces a window that casts a shadow. It is most effective when used in conjunction with no_frame and no_caption.
no_caption | Omit the caption from the window.
no_maxminbox | Omit the maximise and minimise boxes from the window.
no_maxbox | Omit the maximise box.
no_minbox | Omit the minimise box.
no_sysmenu | Omit the box at the top left that is used to produce the system menu.
no_border | Omit the blank border that normally surrounds the window contents, but leave the frame itself. Using this option you can, for example, force a tool bar (textual or bit-mapped) to be placed immediately beneath the menu.
no_frame | Omit the window frame and the blank border that normally surrounds the window contents. This option is particularly useful with certain types of child window.
no_edge | This option is like no_frame except that it leaves the default border (an empty space around the edge of the window).
topmost | Forces the window to stay on top, even if another application gets control. This is sometimes useful when it is necessary to execute another application without the user losing sight of the current window.
maximise (or maximize) | Displays the window as a maximised window.
minimise (or minimize) | Displays the window as a icon.


Background colour

Background colour - %bg[colour]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%bg is used with or without the grave accent modifier. Without the modifier, %bg changes the background colour of the main window. With the modifier, %`bg changes the background colour of the next (and only the next) control (used for example with %rd, %rf, %rs, %eb, %ls). %`bg is not used for buttons. For buttons use %bc.

By default a main window uses the background colour that the user can select from the Control Panel in the Program Manager. This colour is returned by GetSysColor(COLOR_WINDOW).

The new colour can be supplied as one of the standard colours: black, white, grey, red, green, blue, and yellow (for example: %bg[yellow]). Alternatively %bg takes one integer argument that has a value given by RGB@.

For example:

i=winio@('%bg',RGB@(0,255,255))

It is often desirable to base the new colour on the default by calling GetSysColor. In other words, you could create an alternative shade of the default background colour by unpacking the integer returned by GetSysColor and by modifying one or more of the (red, green, blue) components. For example:

INTEGER color,red,green,blue
color = GetSysColor(COLOR_WINDOW)
red = AND(color,255)
green = AND(RS(color,8), 255)
blue = AND(RS(color,16),255)
color = RGB@(red,green,blue+50)
i = winio@('%bg',color)

This will deepen the blue component of the background colour (the new value is assumed to be less that 256). RS and AND are Silverfrost-supplied intrinsic functions (in Fortran 90/95 you can use the standard intrinsics ISHFT and IAND).


ClearWin window

ClearWin window - %N.Mcw[options]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

Using %cw you can embed a ClearWin window (as described in ClearWin windows) in a format window. The window is created N characters wide and M deep but this can be changed by the user if the pivot format (%pv) is included. %cw takes one argument that is the Fortran unit number that you wish to associate with the window. Alternatively, if you pass zero, the ClearWin window is created as the default stream. By default the window has no caption and is not scrollable. The options vscroll and/or hscroll are used to provide vertical and horizontal scroll bars. If a caption, etc. is required (for example to make the window movable), then %cw must be embedded in a child window which is itself embedded in the main window.

A grave accent (`) is used with %cw to obtain a handle. This handle is returned via an integer (kind=7) argument. The handle is used in calls to associated routines e.g. SET_MAX_LINES@.

Although a ClearWin window can be used for both input and output, it is normally wise to perform input using other format codes and to use ClearWin windows for scrolling results. ClearWin windows are also very useful while debugging a program.

The call-back functions CUT, COPY and PASTE will work from within a window defined by %cw.


Property sheet

Property sheet - %Nps

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

Property sheets represent a way of presenting two or more 'sheets' of data in a form that resembles a card index. Each sheet is set up as a separate window using %sh. %sh produces a child window that is hidden from view until connected to a property sheet control using %ps. The property sheet can also have a call-back function that is called each time the visible sheet is changed. A SHEET_NO parameter is provided (see CLEARWIN_INFO@) so that it is possible to determine the sheet that is topmost. When the sheet is first displayed, the SHEET_NO is set to 1 and the call-back is also called. A grave accent modifier is supplied to %ps in order provide a control variable. This variable is used set the initial sheet (at a value other than one which is the default) and to change the sheet number under program (rather than user) control (see %ps for further details). The control variable must be given the SAVE attribute or be a global variable (e.g. stored in a module or common block).

If %ca is used to provide a caption for the property sheet, then the character '&' will have the effect of generating an accelerator key (this will only work for the %ps format).

If an individual sheet is closed (e.g. by placing a button without a callback function in the sheet) then the parent window will close.

WINAPP
INTEGER h1,h2,i,winio@
CHARACTER*120 notes
CHARACTER*20 name,telephone
notes=' '
name=' '
telephone=' '
c--First property sheet
i=winio@('%sh&',h1)
i=winio@('%fn[MS Sans Serif]%ts&',0.90D0)
i=winio@('%ca[&Telephone]%dy&',0.6D0)
i=winio@('%2.2ob[no_border]&')
i=winio@('Name:%cb&')
i=winio@('%12rs%cb&',name)
i=winio@('Telephone: %cb&')
i=winio@('%12rs%cb',telephone)
c--Second property sheet
i=winio@('%sh&',h2)
i=winio@('%ca[&Notes]&')
i=winio@('%fn[MS Sans Serif]%ts&',0.90D0)
i=winio@('%20.3re',notes)
c---Display the combined sheets
i=winio@('%ca[Property sheet]%bg[grey]&')
i=winio@('%2ps',h1,h2)
END


Property sheet child

Property sheet child - %sh

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

This format code is used with %ps. %sh is placed in a format string for a child window and an argument is provided that links the sheet to its parent %ps control. This variable is also an input argument for %ps. See %ps for an example.


Closure control format

Closure control format - %cc

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

Sometimes, especially when an edit box is displayed, it is desirable to control the closure of a window. %cc takes a call-back function as its argument. This function is called before the window closes (for whatever reason). If it returns a positive value the window is not closed. If a grave is used (%`cc) then the associated call-back function is called after the window is closed. A single window could use both %cc and %`cc.


Delayed auto recall

Delayed auto recall - %dl

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%dl allows a given call-back function to be called at regular intervals. It takes a DOUBLE PRECISION argument that is the number of seconds to wait between calls followed by the given call-back.

The following code produces a window that displays its message for two seconds before closing:

i=winio@('%dl%si!Testing',2.0D0,'EXIT')

Note: Timing messages are only received while the program is idle.


Wallpaper

Wallpaper - %wp[bitmap]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%wp takes the name of a bitmap resource. bitmap is a standard character string. %wp "wallpapers" the window with the bitmap before the text and controls are drawn.

For example:

WINAPP 0,0,'chitz.rc'
INTEGER i,winio@
i=winio@('%ca[Wallpaper]%wp[chitz]&')
i=winio@('%bg[grey]%fn[Times New Roman]&')
i=winio@('%cn%obClearWin+%cb')
END

where the resource script chitz.rc contains:

chitz BITMAP c:\windows\chitz.bmp

%wp is most effective in windows that contain only graphical objects. If the bitmap is smaller than the dimensions of the window, it will be repeated horizontally and vertically to fill the space. Therefore, your bitmap should either be sufficiently large, or it should contain a pattern that is designed to repeat, like the standard Windows wallpaper bitmaps. A grave accent (`) is added to %wp in order to ensure that the window will be expanded to hold at least one copy of the bitmap.


User window

User window - %uw[class_name]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%uw enables existing Windows code to be interfaced with ClearWin+. Given a registered Windows class (that will have its own Windows procedure), a window can be embedded in a format window by using %uw. %uw is followed by a standard character string giving the name of the class. It also takes the following arguments:

1) the INTEGER width of the child in pixels,

2) the INTEGER height of the child in pixels,

3) the Window style (This will be OR-ed with WS_CHILD. In general, no border or caption will be specified, as these will normally be applied to the main window e.g. using %ca.)

4) the extended window style (often zero),

5) an INTEGER (kind=7) to receive the handle for the resultant child window.


Screen saver

Screen saver - %sv

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

By using %sv it is possible to create a screen saver. A format window that includes %sv will close as soon as it receives mouse or keyboard input. The executable should be renamed to a <filename>.SCR file, placed in the Windows directory and then selected as the current screen saver from the Control Panel. Apart from its obvious use, a screen saver can be used to perform a lengthy calculation. To ensure the calculation is continued from where it was interrupted, the %cc (window closure format) should be used to trap the closure and perform file I/O.

For example:

WINAPP
INCLUDE <windows.ins>
INTEGER xres,yres,g_handle,r,g,b,i
COMMON xres,yres,g_handle,r,g,b
EXTERNAL redraw_screen
DOUBLE PRECISION secds
secds=1.0
r=20
g=64
b=11
xres=clearwin_info@('screen_width')
yres=clearwin_info@('screen_depth')
c --- %bg background colour
i=winio@('%sv%bg[black]&')
c --- Define a window that takes the Whole display area
i=winio@('%ww[no_caption,no_maxminbox,no_sysmenu,'
+ // 'no_frame,no_border,topmost]&')
i=winio@('%`gr[rgb_colours,black]&',xres,yres,g_handle)
c --- Use a periodic delayed callback to initiate updates
i=winio@('%dl',secds,redraw_screen)
END
c ---------------------------------------------------------
INTEGER FUNCTION redraw_screen()
INCLUDE <windows.ins>
INTEGER xres,yres,g_handle,r,g,b,loop
COMMON xres,yres,g_handle,r,g,b
CALL select_graphics_object@(g_handle)
DO loop=1,yres
CALL draw_line_between@(0,loop,xres,loop,RGB@(r,g,b))
r=r+1
g=g+3
b=b+5
IF(r.GT.255) r=0
IF(g.GT.255) g=g-255
IF(b.GT.255) b=b-255
ENDDO
redraw_screen=1
END


Disable screen saver

Disable screen saver - %ns

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

%ns is designed to cause screen saver activity to be inhibited while the window is open. If your application opens a window and then performs a long calculation, there is a danger that a screen saver will cut in when your program yields, even temporarily. This is because the operating system considers the system to be idle if there is no input for a set period of time. Many screen savers are very CPU intensive and will starve your program of CPU resources. Use %ns to eliminate this problem.


Graphics

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

ClearWin+ includes a library of drawing routines for drawing lines and text, for filling areas, for copying images, etc.. These routines do not have an explicit argument referring to the 'surface' on which the drawing is to take place. Instead, drawing routines are applied to what is called the current drawing surface. This drawing surface can be:

1) one of a number of rectangular areas of the screen generated by %gr,

2) one of a number of printer bitmaps (created for example by OPEN_PRINTER@),

3) an internal drawing surface created by CREATE_GRAPHICS_REGION@ or NEW_GRAPHICS_REGION@ (that is, a bitmap that is created for copying to another drawing surface).

When it is necessary to distinguish one surface from another, the programmer provides a unique integer identifier and the routine SELECT_GRAPHICS_OBJECT@ is used to provide the switch. This chapter describes drawing surfaces created using %gr and create_graphics_region@. Printer surfaces are described in Using the printer.

%gr is one of three graphics format codes provided by ClearWin+. The others are %og (used to create a region in which OpenGL routines are used; described here) and %dw (used to create a region in which Windows API functions are used; described at the end of this chapter). Using these formats it is possible to embed your graphics in a window together with other controls. The ClearWin+ library of drawing routines is used only with %gr. Thus, only %gr (not %og and %dw) generates a drawing surface.


Graphics format

Graphics format %gr[options]

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

There are two colour modes for ClearWin+ drawing routines: (a) VGA colour mode, designed to emulate the EGA and VGA palette registers and used to port legacy code to Windows and (b) RGB colour mode, the native Windows colour mode.

Initially, to assist in the porting of legacy code, the default colour mode was set as VGA colour mode. However, it is recommended that all new programs should use RGB colour mode and (from FTN95 version 7.00) this is the default. There are three ways to change the colour mode.

1. The default is changed to VGA colour mode by calling SET_RGB_COLOURS_DEFAULT@(0) at the beginning of the program.

2. Alternatively, when creating a drawing surface using %gr, you can include the option VGA_COLOURS (see below).

3. In either case you can change the colour mode for a particular drawing surface by calling USE_RGB_COLOURS@.

%gr can be followed by a list of options that is any valid combination of the following:

BLACK, WHITE, RED, BLUE, YELLOW, GREY (or GRAY)

Specifies the initial background colour of the drawing surface. Otherwise this defaults to the background colour of the surrounding window.

COLOUR=#rrggbb

COLOR=#rrggbb

Specifies the intial background colour of the drawing surface where rr represents hexadecimal digits for the red component etc..

METAFILE_RESIZE USER_RESIZE KEEP_ASPECT_RATIO

Options specifying the behaviour of the graphics area as it is re-sized.

RGB_COLOURS

Selects RGB colour mode. This is the default for ClearWin+ releases from FTN95 version 7.00.

VGA_COLOURS

Selects VGA colour mode. This is the default for ClearWin+ releases before FTN95 version 7.00.

FULL_MOUSE_INPUT

Specifies that mouse movements and mouse button releases should be notified to the call-back function, not just clicks and double clicks.

POPUP

Used with FULL_MOUSE_INPUT in order to enable a %pm popup menu that is otherwise disabled.

BOX_SELECTION

LINE_SELECTION

FREE_SELECTION

Specifies the initial selection mode, that controls the behaviour when the user presses the left mouse button and drags the mouse over the graphics area. These options are useful for interactive programs.

USER_SURFACE

A Win32-only option to enable software to access the in-memory copy of the graphics area so as to modify it at the highest possible speed. This option is particularly useful for image processing software.

FLUSH

Used with %sy 3d styles to re-align the %gr border.
SMOOTH8 Use 8x8 box filter box filter anti-aliasing
HSCROLL, VSCROLL

Adds scrolling options. Previously %vx and %hx could be used with %gr but provided scroll bars as separate controls. The new options create scroll bars that are built into the control and as a result have all of the expected "hot track" characteristics of a scroll bar.

%gr[hscroll] uses the same data as %hx whilst %gr[vscroll] uses the same data as %vx. This is accommodated by presenting %hx with its data before %gr[hscroll] and %vx with its data before %gr[vscroll]. The only restriction is that the %hx and %vx information must not include callback functions. For example:

integer iw,page,range,pos
integer,external::cb
iw = winio@("%vx&", page, range, pos)
iw = winio@("%^gr[vscroll]",400,300,cb)

The values used for 'page' and 'range' determine the y offset of the origin when drawing to the graphics region. Typically the adjustment could be y = y-pos*range. In this way, %gr can be used to display a snapshot of a larger graph by redrawing the area required. Alternatively a full sized graphics region could be created off-screen, with areas copied to the %gr region as required.

%gr creates a 'control' that is a rectangular graphics area (a drawing surface) that will be filled by subsequent calls to ClearWin+ drawing routines. In the absence of %gr, using drawing surface routines causes ClearWin+ to create a separate window containing a drawing surface together with a button to close the window. This is analogous to the automatic creation of a ClearWin window for standard Fortran I/O. The various options to the %gr format are explained in this and subsequent sections of the chapter.

%gr takes two arguments that provide the pixel width and height of a rectangular area. You may want to vary these values depending on the resolution of the user's screen. The pixel width and depth of the screen is obtained by calling CLEARWIN_INFO@ using SCREEN_WIDTH and SCREEN_DEPTH.

The %gr options consisting of simple colour names (such as black) supply an initial background colour that would otherwise default to the background colour of the surrounding window.

For example:

INTEGER ctrl,i
i=winio@('%ww%gr[black]&',400L,300L)
i=winio@('bt[OK]%lw',ctrl)
CALL draw_line_between@(100,100,300,200,RGB@(255,0,0))

This will draw a red line on a black background. In this example, %lw has been used to leave the window open so that code to draw to the drawing surface can follow. A alternative approach is to provide a startup call-back function using %sc and to place the graphics code in the call-back. This approach is usually preferred unless you need to use %lw for other reasons.

If more than one drawing surface is to be drawn (either within one window, or on different windows) then a grave accent modifier is supplied to %gr and a third argument is required to input an integer identifier that you provide. This identifier is used in the subroutine SELECT_GRAPHICS_OBJECT@ in order to select the current drawing surface.

The following example creates two drawing surfaces and draws to each in turn.

INTEGER ctrl,hnd1,hnd2
DATA hnd1,hnd2/1,2/
c ----Graphics handles are input values to %gr ---
c
i=winio@('%`gr&',400L,300L,hnd1)
i=winio@('%`gr&',400L,300L,hnd2)
i=winio@('%ww%lw',ctrl)
i=select_graphics_object@(hnd1)
CALL draw_line_between@(100,100,300,200,RGB@(0,0,255))
i=select_graphics_object@(hnd2)
CALL draw_filled_ellipse@(200,150,75,50,RGB@(255,0,0))

As an alternative to using %`gr, you can can call GET_CURRENT_GRAPHICS_REGION@ immediately after the %gr has been used to return a HANDLE to the surface. You can then use SELECT_GRAPHICS_REGION@ to select that surface.

Other drawing surfaces can be set up to write an image to memory or to write output to the printer. The graphics calls in the above program can also be used on such surfaces. Details appear later in this chapter and in Using the printer.


Basic graphics primitives

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Once a %gr drawing surface has been created, the following functions are used to draw in the space:

DRAW_LINE_BETWEEN@ | Draws a straight line between two points.
DRAW_CHARACTERS@ | Draws text.
DRAW_ELLIPSE@ | Draws an ellipse.
DRAW_FILLED_ELLIPSE@ | Fills an ellipse.
DRAW_FILLED_POLYGON@ | Fills a polygon.
DRAW_FILLED_RECTANGLE@ | Fills a rectangle.
DRAW_POLYLINE@ | Draws a number of connected straight lines.
DRAW_RECTANGLE@ | Draws a rectangle.
DRAW_POINT@ | Sets a pixel colour.
SET_LINE_STYLE@ | Sets attributes for line drawing.
SET_LINE_WIDTH@ | Sets the width for line drawing.


Drawing text

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Text may be added to a %gr drawing surface by using DRAW_CHARACTERS@, for example,

CALL draw_characters@('Time (Secs)',350,380,RGB@(255,255,255))

The initial font is the current font in the format window, but it can be changed by using the following routines. These operate on the currently selected drawing surface.

Note that generally only TrueType fonts can have their appearance varied in all of the ways shown below.

BOLD_FONT@ | Selects/deselects bold font.
CHOOSE_FONT@ | Displays a font selection dialog box.
GET_FONT_NAME@ | Can be repeatedly called to obtain the name of all installed fonts on the system.
GETFONTSIZE@ | This returns the LOGFONT character width and height for a given font handle.
GET_TEXT_SIZE@ | Gets the dimensions of a given string.
GETTEXTSIZE@ | Gets the dimensions of a given string on a given control.
ITALIC_FONT@ | Selects/deselects italic the font.
ROTATE_FONT@ | Rotates the font anticlockwise by a given angle in degrees.
SCALE_FONT@ | Multiplies the font size.
SELECT_FONT@ | Selects a font by name.
SIZE_IN_PIXELS@ | Specifies the font size in pixels.
SIZE_IN_POINTS@ | Specifies the font size in points.
UNDERLINE_FONT@ | Selects/deselects underlined font.

The following program demonstrates the use of these routines

WINAPP
INCLUDE <clearwin.ins>
INTEGER i,ictrl,s_width,s_depth,g_width,g_depth,colour
c--- Get width and height of screen
s_width = clearwin_info@('SCREEN_WIDTH')
s_depth = clearwin_info@('SCREEN_DEPTH')
c--- Size of graphics area
g_width = 2.0*s_width/3.0
g_depth = 2.0*s_depth/3.0
c--- Graphics window
i=winio@('%ww%ca[WINDOWS FONTS]&')
i=winio@('%mn[&Exit]&','EXIT')
i=winio@('%gr[black,rgb_colours]&',g_width,g_depth)
i=winio@('%lw',ictrl)
c--- Select Windows font 'Modern' (default attributes)
c--- Draw in intense white
CALL select_font@('Modern')
CALL draw_characters@('1: select_font:modern',
+ 350,380,RGB@(255,255,255))
c--- Multiply size of font by 2
c--- Draw in yellow
CALL scale_font@(2.0D0)
CALL draw_characters@('2: This is scale_font',
+ 300,300,RGB@(255,255,0))
c--- Underline font
c--- Draw in intense cyan
CALL underline_font@(1)
CALL draw_characters@('3: This is underline_font',
+ 280,200,RGB@(0,255,255))
c--- Italic font
c--- Draw in intense green
CALL italic_font@(1)
CALL draw_characters@('4: This is italic_font',
+ 300,100,RGB@(0,255,0))
c--- Specify the size of the font in pixels
c--- Draw in cyan
CALL size_in_pixels@(20,10)
CALL draw_characters@('5: This is size_in_pixels',
+ 350,50,RGB@(127,0,127))
c--- Specify the size of the font in points
c--- Draw in intense blue
CALL size_in_points@(20,10)
CALL draw_characters@('6: This is size_in_points',
+ 10,50,RGB@(0,0,255))
c--- Rotate the font by 70.0 degrees
c--- Draw in intense magenta
CALL rotate_font@(70.0D0)
CALL draw_characters@('7: This is rotate_font:70',
+ 80,450,RGB@(255,0,255))
c--- Undo underline font
c--- Draw in intense cyan
CALL underline_font@(0)
CALL draw_characters@('8: This is undo underline_font',
+ 150,450,RGB@(0,255,255))
c--- Embolden the font
c--- Draw in intense white
CALL bold_font@(1)
CALL draw_characters@('9: This is bold_font',
+ 220,350,RGB@(255,255,255))
c--- User selected font, default colour black (0)
c--- Draw in intense white
colour=0
CALL choose_font@(colour)
CALL draw_characters@('10: This is choose_font',
+ 300,450,colour)
END

Note how CHOOSE_FONT@ allows user selection of font style, underline, overstrike, size and colour.


Re-sizing a graphics surface

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

It is often desirable to allow a graphics area to be re-sized by the user by altering the size of the window in which it is contained. Like all ClearWin+ controls, by default the drawing surface created by %gr will have a fixed size. However, %gr can take a pivot, enabling it to be re-sized. Unlike other simple controls, the desired effect of re-sizing a graphics area is not obvious. ClearWin+ offers the choice of either re-drawing the image from scratch (with different contents if you wish) or of letting the system re-scale the existing graphics.

A %gr region will change size when the enclosing window is re-sized if it is preceded by a pivot format (%pv) and provision has been made to re-draw the graphics by one of the following two methods:

1) If the user_resize option is given to %gr and a call-back function is supplied (i.e. %^gr[user_resize]) then, when the window is re-sized, the whole area will be blanked out and the call-back function will be called. It is assumed that this function will re-draw the contents of the box. The function can determine that a re-draw is required by calling CLEARWIN_STRING@ using callback_reason. This will return the string resize if a re-size is occurring. The CLEARWIN_INFO@ parameter GRAPHICS_RESIZING will also return 1 if a re-size is occurring, but this has been superseded by the general purpose callback_reason mechanism. The CLEARWIN_INFO@ parameters GRAPHICS_WIDTH and GRAPHICS_DEPTH are used to return the new size of the area. For convenience the box is assumed to be re-sized immediately it is created, so it is only necessary to draw your graphics in one place in your code. Here is some sample code:

WINAPP
INTEGER i,winio@
EXTERNAL draw
i=winio@('%ww%pv%^gr[user_resize,rgb_colours]',80L,25L,draw)
END

INTEGER FUNCTION draw()
INCLUDE <windows.ins>
INTEGER x,y,resize
resize=clearwin_info@('GRAPHICS_RESIZING')
IF(resize.EQ.1)THEN
x=clearwin_info@('GRAPHICS_WIDTH')
y=clearwin_info@('GRAPHICS_DEPTH')
CALL draw_line_between@(0,0,x,y,RGB@(255,0,0))
ENDIF
draw=2
END

2) An alternative method for re-sizing a %gr region is to supply the option metafile_resize to the %gr format code. In this case, a record (stored in a Windows object known as a meta-file) of all graphics operations is made and the result is re-played at the new box size. This approach is clearly the easiest to program, however there are two factors to consider before using this technique.

a) The number of graphics operations being sent to the region must not be unreasonably large since each graphics call will be recorded for re-play. For example, a fractal drawing program (that continued to draw more detail for as long as it ran) could not use this technique because it would ultimately run out of memory.

b) Also some images may not respond well to such automatic re-scaling. This is because floating point co-ordinates are truncated to integers when the original image is drawn. When scaled, they are truncated a second time. In general, line drawing will still look good, but images drawn pixel by pixel are probably best re-sized by method 1.


The %gr call-back function

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Simple graphics operations can be performed without the use of a call-back function. However, you will need a call-back function if you want to respond to mouse changes, or to icon movements, or if you want to redraw in response to a re-size event.

If a call-back function is supplied with %gr, it will be called for a variety of reasons, conveniently distinguished using CLEARWIN_STRING@('CALLBACK_REASON'). Here is the full set of reasons for calling the call-back function:

MOUSE_LEFT_CLICK MOUSE_MIDDLE_CLICK MOUSE_RIGHT_CLICK | These reasons are given after the corresponding mouse button has been pressed and released. In FULL_MOUSE_INPUT mode, these call-back reasons occur when the key is pressed.
MOUSE_LEFT_RELEASE MOUSE_MIDDLE_RELEASE MOUSE_RIGHT_RELEASE | These reasons only occur if the option FULL_MOUSE_INPUT is used with %gr. They occur when the corresponding mouse button is released.
MOUSE_DOUBLE_CLICK | This reason is given when two successive left mouse clicks have occurred within the interval defined as a double click. Individual mouse LEFT_MOUSE_CLICK events will also be generated.
RESIZE | Given when the USER_RESIZE option is used and the window has just been created or re-sized. Usually the call-back function will draw or re-draw the image.
DRAG_AND_DROP | Given when an icon has been dragged and dropped on to the graphics area.

Tip

Many systems are configured so that the middle mouse button is inactive, even though it is physically present on the mouse. For this reason it is better to avoid relying on this button.

Once the reason for the call-back has been established, additional information can be obtained by calling CLEARWIN_INFO@. You can use GRAPHICS_MOUSE_X and GRAPHICS_MOUSE_Y to obtain the pixel co-ordinates of the mouse event that caused the call-back. Also GRAPHICS_MOUSE_FLAGS gives full information about the state of the mouse keys (this is most useful when the FULL_MOUSE_INPUT %gr option is used). The mouse flags are bitwise significant as follows:

1 | Left button pressed
2 | Right button pressed
4 | Shift key pressed
8 | Control key pressed
16 | Middle button pressed

Tip

Using the FULL_MOUSE_INPUT option it is possible to respond to a mouse press by altering parts of your image, reversing these changes when the key is released again. This can give a very dynamic feel to your program. Remember, however, that any operations you perform at this point should not take too long, otherwise the mouse response will become sluggish.


Graphics selections

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Consider the task of writing a simple paint program. Such programs often allow the user to hold down the left mouse key in order to open up a box that is used to select an area. Alternatively, the effect of dragging the mouse could be to create a line rather than a box.

%gr drawing surfaces have an associated 'selection mode'. This mode tells ClearWin+ what to do if the mouse is dragged (by the left button) over the area. The mode can be set using the BOX_SELECTION, LINE_SELECTION or FREE_SELECTION options on the %gr format code. The mode can also be changed dynamically using the SET_GRAPHICS_SELECTION@ function. This operates on the current drawing surface. The argument to this function takes the following values:

0 | default - no selection
1 | box selection
2 | line selection
4 | invisible box selection

When a selection is enabled, dragging the mouse with the left button depressed opens an XOR drawn box or line. A program obtains the co-ordinates using GET_GRAPHICS_SELECTED_AREA@. Typically you would call this function on the release of the left mouse (or possibly in response to a button press) so that the program would respond to the final position of the line or box.

The following example uses BOX_SELECTION. When the left mouse button is released, the program draws a diagonal line using the box position and dimensions. If the shift key is held down, a copy of the box is produced instead of a line. Alternatively, if the control key is held down, an ellipse is drawn to fill the box.

WINAPP
INTEGER i,winio@
CHARACTER*80 fmt
EXTERNAL gr_func

i=winio@('%ww[no_border]%ca[Box Selection]%sy[3d_depressed]&')
fmt='%^gr[black,box_selection,full_mouse_input,rgb_colours]'
i=winio@(fmt,200,200,gr_func)
END

INTEGER FUNCTION gr_func()
INCLUDE <windows.ins>
INTEGER x1,y1,x2,y2,a,b,flags,grey
LOGICAL IsUp,WasDown
DATA WasDown/.FALSE./

flags=clearwin_info@('graphics_mouse_flags')
IsUp=AND(flags,MK_LBUTTON).EQ.0

IF(IsUp.AND.WasDown)THEN
grey=RGB@(170,170,170)
CALL get_graphics_selected_area@(x1,y1,x2,y2)
CALL set_graphics_selection@(0)
IF(AND(flags,MK_SHIFT).EQ.MK_SHIFT)THEN
CALL draw_filled_rectangle@(x1,y1,x2,y2,grey)
ELSEIF(AND(flags,MK_CONTROL).EQ.MK_CONTROL)THEN
a=0.5*(x2-x1)
b=0.5*(y2-y1)
CALL draw_filled_ellipse@(x1+a,y1+b,a,b,grey)
ELSE
CALL draw_line_between@(x1,y1,x2,y2,grey)
ENDIF
CALL set_graphics_selection@(1)
ENDIF
WasDown=.NOT.IsUp
gr_func=1
END


Drawing device independent bitmaps

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

When using %gr and its associated drawing surfaces (including internal and printer drawing surfaces) there are two sets of routines for processing device independent bitmaps (DIBs). The first set uses a CHARACTER array supplied by the programmer. The second uses a handle supplied by ClearWin+. (See also Using image resources.)

Using a 24 bit per pixel array

The following routines are used to handle device independent bitmaps:

GET_DIB_SIZE@ | Gets parameters from a bitmap or JPEG file.
GET_DIB_BLOCK@ | Extracts a rectangular block from a bitmap or JPEG file.
PUT_DIB_BLOCK@ | Saves a rectangular block to a bitmap or JPEG file.
DISPLAY_DIB_BLOCK@ | Displays a block on the current drawing surface.
RECOVER_DIB_BLOCK@ | Recovers the block from the current drawing surface.

GET_DIB_SIZE@ obtains information about an existing .BMP file. The file name is an input argument that should have the .BMP suffix. The file name may be a full path name. If the routine succeeds, an error code is returned with the value zero whilst other arguments return the width and height (in pixels) of the image contained in the file. The number of bits per pixel is also returned as one of the following values:

1 | Monochrome black and white image
4 | 16-colour image
8 | 256-colour image
24 | Full colour image in which each pixel is represented by eight bits per red/green/blue value.

GET_DIB_BLOCK@ extracts a rectangular block (that could be the whole image) from a given file into an array. The first index of the array is the colour index in the order (red, green, blue). Displacements AX and AY into the array are typically zero but they can be set to other values if, for example, the array is to be composed of a montage of several blocks. Arguments W and H represent the width and height of the block to be transferred, whilst DX, DY represent the displacement (again typically zero) into the image in the file.

DISPLAY_DIB_BLOCK@ transfers a rectangular block of given size (W x H) from the array at a position (AX, AY) to a position (X, Y) on the current drawing surface (e.g. a %gr region or a printer). Two arguments named FUNCTION and MODE are normally set to zero. An argument for the error status is returned as zero if the process is successful.

PUT_DIB_BLOCK@ transfers a rectangular block from an array to given file, destroying any previous contents. Displacements AX and AY into the array are typically zero, whilst arguments W and H are the width and height of the image to be created. An argument for the number of bits per pixel is currently ignored and should set to 24. This routine always writes BMP files with 24 bits per pixel.

The use of these routines is best illustrated by a simple example. The following example reads a BMP file, alters the array to draw a red line through the image, displays the result, and writes a new BMP file with the modified image.

WINAPP
INCLUDE <windows.ins>
CHARACTER*50 file
CHARACTER a(3,1024,1024)
INTEGER hres,vres,nb_colours,ier,i,k,control
c--- Note - you may need to alter this path
file='c:\windows\setup.bmp'
CALL get_dib_size@(file,hres,vres,nb_colours,ier)
IF(ier.NE.0.OR.hres.GT.1024.OR.vres.GT.1024) STOP 'TROUBLE'
CALL get_dib_block@(file,a,1024,1024,0,0,hres,vres,0,0,ier)
IF(ier.NE.0) STOP 'TROUBLE'
c--- Draw a diagonal red stripe over the image
k=MIN(hres,vres)
DO i=1,k
a(1,i,i)=char(255)
a(2,i,i)=char(0)
a(3,i,i)=char(0)
ENDDO
c--- Display the image
i=winio@('%gr%lw',hres,vres,control)
CALL display_dib_block@(0,0,a,1024,1024,0,0,hres,vres,0,0,ier)
c--- Write the image away to another file
file='c:\temp\junk.bmp'
CALL put_dib_block@(file,a,1024,1024,0,0,hres,vres,24,ier)
END

The example is written in Fortran 77 with the array A declared to be 'sufficiently large'. With Fortran 90 you can use an allocatable array instead. Note that the resulting BMP file will typically be larger than the original because the colours will have been expanded to 24 bits per pixel.

Using a DIB handle

An alternative approach is to use routines that transmit a handle for a device independent bitmap.

The routines IMPORT_BMP@, IMPORT_PCX@, GET_SCREEN_DIB@ and CLIPBOARD_TO_SCREEN_BLOCK@ each return a handle to a DIB. This handle is then used in DIB_PAINT@, PRINT_DIB@ (now superceded by DIB_PRINT@), EXPORT_BMP@ and EXPORT_PCX@. When it is no longer needed the associated memory can be released using RELEASE_SCREEN_DIB@.

You can also use WRITE_GRAPHICS_TO_BMP@ and WRITE_GRAPHICS_TO_PCX@ in order to write the current drawing surface to a file.

Here is a simple program that uses some of these routines:

WINAPP
INCLUDE <windows.ins>
INTEGER hres,vres,nbbp,ercode,hdib,ctrl,i,width,height
CHARACTER*50 file
file='c:\windows\setup.bmp'
CALL get_dib_size@(file,hres,vres,nbbp,ercode)
IF(ercode.NE.0) STOP 'Size error'
hdib=import_bmp@(file,ercode)
IF(ercode.NE.0) STOP 'Import error'
i=winio@('%gr[rgb_colours]%lw',hres,vres,ctrl)
ercode=dib_paint@(0,0,hdib,0,0)
IF(ercode.EQ.0) STOP 'Paint error'
call draw_line_between@(0,0,hres,vres,RGB@(255,0,0))
IF(open_printer@(7).EQ.1)THEN
CALL get_graphical_resolution@(width,height)
ercode=print_dib@(7,0,0,width,height,hdib,0,0,hres,vres)
IF(ercode.EQ.0) STOP 'Print error'
ercode=close_printer@(7)
IF(ercode.EQ.0) STOP 'Close printer error'
ENDIF
CALL release_screen_dib@(hdib)
END

This program imports a bitmap and then creates a drawing surface on the screen using %gr. The bitmap is drawn to the screen and a red line is draw across it. The standard printer dialog is then displayed via a call to OPEN_PRINTER@. If the user clicks on the OK button, the routine returns the value 1 and the current graphics device is now the printer with device handle 7. The bitmap is drawn to this device. Calling CLOSE_PRINTER@ sends the image to the printer.


Using image resources

The following routines can be used to paste image resources on to a drawing surface and to export a drawing surface to an image resource file. (See also Drawing device independent bitmaps.)

IMPORT_IMAGE@ | Pastes an image (BMP, JPEG, GIF, PCX or PNG) on to a drawing surface using an internal resource or an external file.
EXPORT_IMAGE@ | Exports a copy of a drawing surface to a image file (BMP, JPEG, GIF, PCX or PNG).


Direct manipulation of the graphics surface

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Every call to a drawing surface routine involves one or more calls the Windows API in order to perform the operation. This is usually not a problem when high level operations such as line drawing are being performed. However, it might be desirable to bypass this mechanism and construct the surface directly, particularly in applications that manipulate images and that must therefore operate at the pixel level. This is possible by specifying the USER_SURFACE option with %gr.

When this option is used, an INTEGER(KIND=7) variable is placed immediately after the two size parameters. This variable will receive the address of a buffer containing the graphics contents stored using 3 bytes per pixel. By manipulating this array you can change the graphics surface directly. The INTEGER variable should be passed to WINDOW_UPDATE@ after such a manipulation to cause the screen to be updated.

Later versions of ClearWin+ may accelerate some function calls (such as DRAW_LINE_BETWEEN@) by using this direct access method if USER_SURFACE is coded, but at present this is not the case.

The USER_SURFACE option implies the RGB_COLOURS option and must not be mixed with METAFILE_RESIZE, although it can be combined with USER_RESIZE. A trade-off is involved here. The user surface will usually require more memory than the device dependent bitmap that ClearWin+ normally uses to implement %gr. Also each re-draw of the window will be slower. However, if you implement pixel-by-pixel graphics by directly manipulating the buffer, you will see a substantial speed improvement over making calls to DRAW_POINT@. If USER_SURFACE is combined with USER_RESIZE then the surface pointer variable will be updated each time the window is re-sized. It is important not to copy this variable and so use an obsolete version of the pointer. The row of the buffer has a layout corresponding to the following array:

INTEGER*1 buffer(3,width)

The first index covers the colours as follows:

1 | Blue
2 | Green
3 | Red

After each row a few bytes of padding are added if necessary to make the row a multiple of four bytes. The next row then follows. This layout is imposed by the Windows operating system and not by ClearWin+.

Here is a simple Fortran example:

WINAPP
INCLUDE <windows.ins>
EXTERNAL draw
INTEGER(7) ptr
COMMON ptr
ia=winio@('%ww%pv%^gr[black,user_resize,'//
+ 'user_surface]',256,256,ptr,draw)
END

INTEGER FUNCTION draw()
INCLUDE <windows.ins>
INTEGER(7) ptr
COMMON ptr
INTEGER width,depth,m,i,q,x,y,full_on,pad_width
IF(clearwin_info@('graphics_resizing').eq.1)THEN
width=clearwin_info@('graphics_width')
depth=clearwin_info@('graphics_depth')
m=MIN(width,depth)
c--- Calculate width in bites of one row
c--- remembering to round up to nearest 4 bytes
pad_width=ls(rs(3*width+3,2),2)
c--- Draw a diagonal yellow line
DO i=1,m
x=i-1
y=i-1
c--- Compute index into array
q=3*x+pad_width*y
full_on=255
c--- Red component
CORE1(ptr+q+2)=full_on
c--- Green component
CORE1(ptr+q+1)=full_on
ENDDO
ENDIF
draw=2
END

Note that it is possible (and often very useful) to mix calls to ClearWin+ graphics routines and direct manipulation of the pixel buffer. If you do this you must call the API function GdiFlush() to ensure that the effect of any previous function calls have 'flushed through' before you manipulate the buffer directly. If you intend to perform all your graphics by direct buffer manipulation this need not concern you.

If you want to display a large image but do not have the screen space to do so or if you are producing a graphics and text output window, the routine SCROLL_GRAPHICS@ will be of great use. This routine will allow you to scroll graphics in any direction by any displacement.


Off-screen graphics

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Sometimes, it is useful to build up graphics information in memory, rather than on the screen. For example, such information might be subsequently copied to the screen at several locations, or written to a file. A complex drawing could be built up off screen whilst displaying other information. When complete, the drawing can be displayed.

In ClearWin+ there are two approaches to this issue each with its own set of routines. The first creates an internal drawing surface using CREATE_GRAPHICS_REGION@ and is described below. The other approach uses what is called a virtual screen and is described in the ClearWin+ User's Supplement. Mixing routines from the two sets may not produce the desired result.

An internal drawing surface uses the following set of routines together with the DIB routines listed in the section in Drawing device independent bitmaps.

COPY_GRAPHICS_REGION@ | Copies from one designated surface to another.
CREATE_GRAPHICS_REGION@ | Creates a drawing surface of a given size. Use NEW_GRAPHICS_REGION@ to also specify the size.
DELETE_GRAPHICS_REGION@ | Releases the memory for a drawing surface.
GRAPHICS_TO_CLIPBOARD@ | Copies a surface to the clipboard.
SCROLL_GRAPHICS@ | Scrolls a drawing surface.
SELECT_GRAPHICS_OBJECT@ | Selects an existing drawing surface.

Here is a short program that creates a drawing surface using CREATE_GRAPHICS_REGION@, selects the surface by using SELECT_GRAPHICS_OBJECT@ copies a bitmap and writes a message into it. The current screen area is then selected by another call to SELECT_GRAPHICS_OBJECT@ allowing subsequent graphics drawing to be directed to the screen. When a button is clicked the internal surface is copied to the screen using COPY_GRAPHICS_REGION@.

WINAPP
IMPLICIT NONE
INCLUDE <windows.ins>
INTEGER i,ictrl,width,depth,ierr,hdib
INTEGER g_handle,r_handle,white
PARAMETER (g_handle=7,r_handle=8)
CALL set_rgb_colours_default@(1)
width=2.0*clearwin_info@('SCREEN_WIDTH')/3.0
depth=2.0*clearwin_info@('SCREEN_DEPTH')/3.0
white=RGB@(255,255,255)
i=winio@('%ww%ca[Off-Screen Regions]&')
i=winio@('%mn[&Exit]&','EXIT')
i=winio@('%lw&',ictrl)
i=winio@('%`gr[black]',width,depth,g_handle)
ierr=create_graphics_region@(r_handle,width,depth)
ierr=select_graphics_object@(r_handle)
hdib=import_bmp@('c:\windows\setup.bmp',ierr)
ierr=dib_paint@(0,0,hdib,0,0)
CALL release_screen_dib@(hdib)
CALL draw_characters@('This was drawn off screen',
+ 100,100,white)
ierr=select_graphics_object@(g_handle)
CALL draw_characters@('This was drawn to a window',
+ 100,100,white)
i=winio@('%bt[Show Off-Screen Block]')
ierr=copy_graphics_region@(g_handle,0,0,width,depth,
+ r_handle,0,0,width,depth,SRCCOPY)
END


Graphics icons

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

It is possible to supply the user with more interesting ways to interact with your graphics area than merely clicking with the mouse. A %gr drawing surface can have an icon resource 'attached' to it. The icon can be moved freely around the graphics window with the mouse. Control of the icon is maintained by the call-back function attached to %gr.

ADD_GRAPHICS_ICON@ is used to attach an icon resource (defined in a resource script) to the current screen drawing surface. A NAME argument is used to stipulate the resource. X and Y variables are used as arguments that hold the initial location of the image. These variables also hold the new position when the image is moved. The call-back function for %gr can modify the X and Y values if required. In this way it is possible to 'lock' the image on to a horizontal or vertical plane by repeatedly setting either X or Y to a constant value.

The width and height arguments of ADD_GRAPHICS_ICON@ should be set to zero except when the icon image is less than 32x32 pixels. A smaller icon is constructed by starting at the top-left corner and by filling the remaining unused area with the 'transparent' colour. In this case, if you do not specify the correct size of the icon then the unused area will be detected by the mouse.

CLEARWIN_INFO@('DRAGGED_ICON') returns the handle of the icon that has moved. This handle is initially obtained as the value returned by ADD_GRAPHICS_ICON@.

When the icon is dropped, CLEARWIN_INFO@('DROPPED_ICON') returns the handle of the associated icon. A graphics icon can be removed with a call to REMOVE_GRAPHICS_ICON@.

The following program draws a horizontal scale with an icon that can be dragged across it. The resource script attaches an icon file to the 'arrow_r' resource in the program. The Windows API function ClipCursor is used to provide a clipping rectangle for the mouse cursor when the left mouse button is held down over the icon. The Silverfrost intrinsic CORE4 is used to pass a NULL pointer to ClipCursor.

WINAPP 0,0,'gr15x.rc'
INCLUDE <windows.ins>
INTEGER i,x,y
COMMON x,y
EXTERNAL start_cb,gr_cb
x=46
y=50
i=winio@('%ww[no_border]%ca[Movable icon]&')
i=winio@('%`cu&',CURSOR_ARROW)
i=winio@('%^gr[grey,rgb_colours,full_mouse_input]&',
+ 300,100,gr_cb)
i=winio@('%sc',start_cb)
END

INTEGER FUNCTION start_cb()
INCLUDE <clearwin.ins>
INTEGER i,x,y,xx,green
COMMON x,y
i=add_graphics_icon@('arrow_r',x,y,10,26)
green=RGB@(0,255,0)
CALL draw_line_between@(50,y,251,y,green)
DO xx=50,245,5
CALL draw_line_between@(xx,y-5,xx,y,green)
ENDDO
DO xx=50,250,50
CALL draw_line_between@(xx,y-10,xx,y,green)
ENDDO
start_cb=1
END

INTEGER FUNCTION gr_cb()
INCLUDE <windows.ins>
INTEGER mx,my,mf,x0,y0,w0,h0,x,y,hwnd,rc(4)
COMMON x,y
LOGICAL L,WasDrag,IsDrag
DATA WasDrag/.FALSE./
CALL get_mouse_info@(mx,my,mf)
IsDrag=clearwin_info@('dropped_icon').NE.0
IF(.NOT.WasDrag.AND.IsDrag)THEN
IF(mx.GE.x.AND.mx.LE.x+10.AND.my.GE.50.AND.my.LE.75)THEN
hwnd=clearwin_info@('latest_formatted_window')
CALL get_window_location@(hwnd,x0,y0,w0,h0)
rc(1)=x0+48
rc(2)=y0+70
rc(3)=x0+256
rc(4)=y0+95
L=ClipCursor(rc)
WasDrag=.TRUE.
ENDIF
ENDIF
IF(WasDrag.AND..NOT.IsDrag)THEN
L=ClipCursor(CORE4(0))
WasDrag=.FALSE.
ENDIF
y=50
IF(x.LT.46) x=46
IF(x.GT.246)x=246
gr_cb=1
END


Windows graphic modes

This article discusses topics which may not be relevant to your systems. It contains discussions of technology which is now largely obsolete. In particular virtually all displays at this time are 24-bits or higher and do not have or need a colour-palette.

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

Between any Windows application and the display hardware there exists a program called a display driver. For every different make of video card there is a different display driver that is either from the Windows installation disks or from the video hardware manufacturer.

From the programmers perspective all drivers should appear the same as all Windows programs must communicate to the video display hardware via the Windows GDI interface. Drivers, on the other hand, will differ dramatically from display card to display card because the structure and types of messages required to control the video display hardware differ for each card. A video driver therefore insulates the programmer from the complexities of hardware.

Windows supports several common display mode resolutions:

640 x 480 x 16 or 256 colours

This is the most compatible mode as all Windows compatible PCs are capable of displaying at this resolution. However, it is very low quality and is now hardly ever used.

800 x 600 x 16 or 256 colours

This is a popular mode as text is readable and there is a larger display area to work with.

1024 x 768 x 16 or 256 colours

This normally used with monitors that are more than 14 inches wide. It is by far the clearest resolution but may suffer from slow updates if the display card is not of the accelerated type.

In 16 colour mode Windows uses a set palette. It holds 'general' colours that are of most use. If the program requires shades or colours that do not exist in the palette, Windows will attempt to dither that colour. Dithering gives a quick effect that often matches the desired colour. It is done by placing pixels of different colours next to each other so that when the user is a suitable distance away from the screen the pixels will appear to be a third colour.

In 256 colour modes there are 256 unique palette entries. Each palette entry is made by setting a red, a green and a blue component. In this mode, when a pixel is written, a value between 0 .. 255 is placed in the display memory. When the display is refreshed the red, green and blue values are 'looked up' and sent to the screen.

There have recently been several new display colour 'depths' added as new hardware has been designed. These high colour modes store the colours directly in the display memory thus avoiding the need for a palette at all. The two most common colour depths are 65535 and 16.7 million. These depths allow each pixel to be set to any one of the possible colours.

If you want to use a wide range of colours whilst avoiding the complexities of managing a palette, one solution is to restrict the usage of your application to desktops operating in high colour mode. For this purpose, you can use the function HIGH_COLOUR_MODE@ to test if the desktop is set to operate in high colour mode.

A call to CLEARWIN_INFO@('SCREEN_NUM_COLOURS') will give the number of colours for the desktop unless this number is greater than 256 (the value 8192 represents all values greater than 256, i.e. a high colour device). A list of palette functions is given in Graphics functions(palette). These are documented in the ClearWin+ User's Supplement.

If the desktop graphics device is not a high colour device, when you draw to the screen, the colour that you get will not always be exactly the colour you specify in the program. This may cause difficulties if you read a pixel from the screen and try to match the colour with one that you have used earlier to draw to the screen. The following program illustrates the problem together with one method of solution. The program draws a set of 'traffic lights'. When the user clicks on any part of the picture, the colour for that part cycles through the sequence: red, amber, green, black.

WINAPP
INTEGER i,winio@
EXTERNAL fill_cb,start_cb
i=winio@('%ww[no_border,no_maxminbox]&')
i=winio@('%sy[3d_depressed]&')
i=winio@('%^gr[black,rgb_colours]&',100,250,fill_cb)
i=winio@('%sc',start_cb)
END
c------------------------------------------------------------
INTEGER FUNCTION start_cb()
INCLUDE <clearwin.ins>
INTEGER i,white
CALL set_line_width@(2)
white=RGB@(200,200,200)
CALL draw_rectangle@(1,1,99,249,white)
DO i=50,200,75
CALL draw_ellipse@(50,i,32,32,white)
ENDDO
start_cb=1
END
c----------------------------------------------------------
INTEGER FUNCTION fill_cb()
INCLUDE <clearwin.ins>
INTEGER x,y,d,f,red,green,black,amber,white,colour,a
CALL get_mouse_info@(x,y,d)
CALL get_rgb_value@(x,y,colour)
red= get_matched_colour@(RGB@(255,0,0))
green=get_matched_colour@(RGB@(0,255,0))
amber=get_matched_colour@(RGB@(255,168,0))
white=get_matched_colour@(RGB@(200,200,200))
black=0

IF(colour.EQ.black)THEN
f=red
ELSEIF(colour.EQ.red)THEN
f=amber
ELSEIF(colour.eq.amber)THEN
f=green
ELSE
f=black
ENDIF
CALL fill_surface@(x,y,colour,f)
fill_cb=1
END

An alternative solution is to use GET_NEAREST_SCREEN_COLOUR@ in place of GET_MATCHED_COLOUR@. The effect is the same but you will probably get a different amber colour on the screen for the following reasons.

When you draw to a screen drawing surface, ClearWin+ filters the colour through its logical palette in order to find an optimum match (we are assuming the device is not a high colour device). When ClearWin+ calls a Windows API drawing function, the result is then filtered through the system palette. Now suppose we call one of the drawing surface functions (such as FILL_SURFACE@) but instead of using a simple RGB value, we use the return from GET_NEAREST_SCREEN_COLOUR@. The effect is to apply the system palette filtering first and this over-rides the ClearWin+ colour optimisation.

The automatic ClearWin+ colour filtering described above may have the effect of slowing the output produced on a drawing surface. You can switch this filtering off by calling USE_APPROXIMATE_COLOURS@(1). When the filtering is switch off, use GET_MATCHED_COLOUR@ in order to get the filtered colour for a particular RGB triplet. This colour is then used in the drawing routines.


Owner draw box format

Owner draw box format - %dw[options]

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

The %dw format allows you to access the Windows GDI directly to prepare a bitmap for display. This is a low level method that has been provided primarily for the integration of certain existing packages. It does not use ClearWin+ drawing routines (that is, it does not generate a drawing surface).

The format takes one argument that is a handle to a device context acquired by calling the ClearWin+ function GET_BITMAP_DC@. This handle accesses a bitmap that is drawn to using standard Windows API functions. It is never necessary to re-paint the area because the bitmap remains in existence even if the window is obscured.

The device context will continue to exist (together with its associated bitmap) until released with the ClearWin+ function RELEASE_BITMAP_DC@. At normal program termination the system will automatically release device contexts acquired by GET_BITMAP_DC@, so it is only necessary to use RELEASE_BITMAP_DC@ in complex programs that manipulate many graphics bitmaps.

For example:

WINAPP
INCLUDE <windows.ins>
INTEGER(7) my_dc
my_dc=get_bitmap_dc@(50,50)
CALL MoveTo(my_dc,0,0)
CALL LineTo(my_dc,50,50)
i=winio@('%dw %bt[OK]',my_dc)
c--- The next line is not necessary unless ---
c--- many device contexts will be acquired ---
CALL release_bitmap_dc@(my_dc)
END

Note that you can continue to change the graphics in the bitmap after the window has been displayed (from call-back functions, or using the %lw format to leave the window in place) provided that WINDOW_UPDATE@(HDC) is used to update the screen, where HDC is the handle of the device context. Other routines that operate in terms of a handle to a device context are listed in Graphics functions(device context).

When it is created, the bitmap will be filled with the default background window colour (i.e. it will be invisible unless displayed inside a shaded box). The colour can be changed with a call to the standard Windows API FillRect function.

It is possible to change the pen associated with a device context acquired by calling the ClearWin+ function GET_BITMAP_DC@, without worrying about deleting used pens. This is performed by calling the ClearWin+ CHANGE_PEN@. The first argument in this function is a device context acquired by calling GET_BITMAP_DC@ followed by three other arguments similar those supplied to the Windows API CreatePen function.

Currently the option list, if present, may contain:

user_resize | %dw can take the option user_resize, which allows it to be re-sized as the pivot item of a window. In this form, %dw does not take a handle from GET_BITMAP_DC@ as an argument, but two integers specifying the initial width and depth of the desired owner-draw region. A call-back function must be supplied in this case. When the call-back function is called, it can check the CLEARWIN_INFO@ parameter GRAPHICS_RESIZING to determine that it is being called to re-draw the image (the image is deemed to be re-sized once as it is created, so all the drawing code can be placed in the call-back).
 | The call-back function should use CLEARWIN_INFO@ to obtain GRAPHICS_DC, GRAPHICS_WIDTH, and GRAPHICS_DEPTH. Traditional Windows programmers should note that although your function will be called to re-draw the image each time the size changes, you will not be called each time a WM_PAINT message is processed. For example, if the image is obscured and then exposed again without change, your function will not be called.
full_mouse_input | With this option the %dw call-back function is called each time the mouse is moved, or a button is pressed or released within the area of the control. Otherwise the call-back function only responds to mouse input when the user clicks on the control.

You can use GET_MOUSE_INFO@ to obtain mouse data from within a %dw call-back function.


Updating the screen

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

By default a call to a graphics function will not produce an instantaneous update of the screen. Instead ClearWin+ waits until you have finished your current sequence of graphics calls from within your callback (i.e. it waits until the application is idle). This mechanism is suitable for most circumstances. However, a call to the routine PERFORM_GRAPHICS_UPDATE@ will cause an immediate update should this be required.

When your application is in an idle state or a call to PERFORM_GRAPHICS_UPDATE@ is made, changes to the graphics buffer are copied to the screen. ClearWin+ keeps track of the smallest rectangle to enclose the changed areas and updates only this region. As a result, if your program updates information at opposite corners of a large graphics region (as an extreme example) it may be faster to insert calls to PERFORM_GRAPHICS_UPDATE@ so that each small region is updated separately.

If you use %dw, ClearWin+ cannot automatically detect the smallest rectangle to be updated and so by default it updates the whole of the graphics region whenever a change is made. A call to the routine SET_UPDATE_RECTANGLE@(x1,y1,x2.y2) sets the update rectangle making the program run faster. Once used, this routine must be called whenever the update rectangle changes.


Using GDI+

In this section:

  • Introduction
  • Graphics format %gr[options]
  • Basic graphics primitives
  • Drawing text
  • Re-sizing a graphics surface
  • The %gr call-back function
  • Graphics selections
  • Drawing device independent bitmaps
  • Direct manipulation of the graphics surface
  • Off-screen graphics
  • Graphics icons
  • Windows graphic modes
  • Owner draw box format - %dw[options]
  • Updating the screen
  • Using GDI+: anti-aliasing and opacity

You can access some features of GDI+ using a %gr format code. In particular you can utilise anti-aliasing and use opacity. Simply turning on anti-aliasing will give your graphics a much smoother look. In some cases you may need to do some work to get the most out of these features. The %gr options [smooth4] and [smooth8] provide a simple and direct way to add anti-aliased smoothing to existing code. smooth4 uses an 8x4 box filter whilst smooth8 uses an 8x8 box. It is possible that simply adding a smooth4 or smooth8 option to %gr will provide the functionality required. ClearWin+, however, allows more control if it is required. The additional functionality that GDI+ bring falls into broadly two main areas: Anti-aliasing and opacity.

Anti-aliasing

Anti-aliasing is a process whereby pixels next to drawn lines are modified to produce a smoother effect. For example, if a circle was drawn in red the standard algorithm will produce a set of red pixels that approximate a circle. The actual pixels coloured red will appear jagged when view closely. When the same pixel is drawn using an anti-aliased algorithm then extra coloured pixels are used to give the illusion of a smoother line. On a screen display the effects can be dramatic with the anti-aliased graphics looking much cleaner and less jagged.

The following simple program illustrates how turning on anti-aliasing can improve a program's output. More precise control can be achieved using the SET_SMOOTHING_MODE@ library routine.

 PROGRAM main
 use clrwin
 INTEGER iw
 integer ctrl
 integer last_x, last_y, mid_y
 integer new_x, new_y
 integer :: parameter, width = 500, height = 250, gutter = 20
 real sinx
 iw=winio@('%ca[sin(x)]&')
 ! set up the surface to draw onto. Remove [smooth4] to see what anti-aliasing has given you
 iw=winio@('%gr[smooth4]&', width, height)
 iw=winio@('%lw', ctrl)
 ! draw axes
 mid_y = height / 2
 call draw_line_between@(gutter, gutter, gutter, width-gutter, 0 )
 call draw_line_between@(gutter, mid_y, width-gutter, mid_y, 0 )

 do i = 0,width-(2*gutter)
   ! make the width of the x-axis span 0..2pi. REAL(width-(2*gutter) is the width of that axis
   sin_x = sin((i/REAL(width-(2*gutter)))*2*3.1415926)
   new_y = mid_y + sin_x*(mid_y-gutter)
   if (i > 0) then
     call draw_line_between@(gutter+i-1, last_y, gutter+i, new_y, RGB@(255,0,0) )
   end if
   last_y = new_y
 end do
END PROGRAM main
No anti-aliasing

output with no anti-aliasing
Anti-aliasing

output with anti-alaising

Opacity

By varying opacity you can allow some of the background to show through when you draw onto a surface. you can either set the overall opacity through a call to SET_OPACITY@ or you can set it on a call by call basis using the nARGB@ function to create the colour. In the example below two sets of three circles are overlapped. The right hand set has the opacity set. The left hand set has just one circle drawn with opacity.

PROGRAM main
 use clrwin
 INTEGER iw
 integer ctrl
 real sinx
 iw=winio@('%ca[ATV]&')
 iw=winio@('%gr[smooth4]&', 220, 110)
 iw=winio@('%lw', ctrl)
 call draw_filled_ellipse@(40, 40, 30, 30, RGB@(255,0,0) )
 call draw_filled_ellipse@(70, 40, 30, 30, RGB@(0,255,0) )
 ! draw this circle with opacity
 call draw_filled_ellipse@(55, 70, 30, 30, nARGB@(192,0,0,255) )
 ! set general opacity to 50%
 call set_opacity@(128)
 call draw_filled_ellipse@(150, 40, 30, 30, RGB@(255,0,0) )
 call draw_filled_ellipse@(180, 40, 30, 30, RGB@(0,255,0) )
 call draw_filled_ellipse@(165, 70, 30, 30, RGB@(0,0,255) )
END PROGRAM main
Opacity Test

output with no anti-aliasing

The following existing routines have been extended to use the opacity and smoothing parameters:

DRAW_LINE_BETWEEN@
DRAW_RECTANGLE@
DRAW_FILLED_RECTANGLE@
DRAW_ELLIPSE@
DRAW_FILLED_ELLIPSE@
DRAW_POLYLINE@
DRAW_FILLED_POLYGON@
DRAW_CHARACTERS@ (with SELECT_FONT@ etc.)
GET_TEXT_SIZE@

The following routines have been added and take DOUBLE PRECISION values for co-ordinate points and sizes:

DRAW_LINE_BETWEEND@
DRAW_RECTANGLED@
DRAW_FILLED_RECTANGLED@
DRAW_ELLIPSED@
DRAW_FILLED_ELLIPSED@
DRAW_POLYLINED@
DRAW_FILLED_POLYGOND@
DRAW_CHARACTERSD@
GET_TEXT_SIZED@
SET_LINE_WIDTHD@


Scalable vector graphics

Scalable vector graphics (.svg files)

Why SVG?

Although it has been possible to output graphics to JPG and PNG files from FTN95 programs for a long time, the Scalable Vector Graphics (SVG) format offers some exciting new possibilities. Like other image formats, SVG images can be displayed on websites, but the data they contain corresponds to the raw vectors that compose most images, and the coordinates of these vectors are stored to REAL*8 precision, rather than relating to actual pixels. Thus these images can be shrunk or blown up many times without losing their quality. However, when JPG or PNG images are expanded many times, they become pixelated. More subtly, if a JPG image is created at a certain size, it can't be reduced without considerable loss of quality.

SVG is an example of XML, and is thus a text file (or a ZIP file if it has a file suffix of SVGZ). This means that the data it contains can also be accessed for use in other ways, and also that it is fairly easy to make SVG files in other ways. With care, it is possible to edit an SVG file to perform minor changes to a graph, such as change the title, change the colours, etc. This is particularly useful when preparing theses, books, or scientific papers. It is instructive to open an SVG file using a text editor, to get a better idea of how they are structured.

Because SVG images can be shrunk or expanded at will, they are ideal for creating a variety of types of collages, such as a graph containing a mathematical equation positioned in an unused portion of the graphical space.

Some SVG files can also be read into ClearWin+ applications and displayed. However because the SVG standard is very large and complex, ClearWin+ is restricted to inputting a few types of SVG image. Namely:

1) SVG files previously output from ClearWin+.
2) SVG files prepared from TEX files in a specified way (see below).
3) SVG files prepared in other ways using the same restricted syntax as those created by ClearWin+.

If you examine an SVG file created by ClearWin+, you will see that it is identified by 'ClearWin_output="1"' within the SVG construct. If you add this to an SVG file created in some other way, this will signify that it is suitable for reading back into ClearWin+.

Creating SVG files from graphics programs

Starting with a program that displays graphics on the screen, replace the winio@ call (with its associated %gr) with a call of the following form:

    ANS=OPEN_SVG@("MySVGOutput.svg",800,600)

This will open the given file, which will be emptied and readied to receive exactly the same graphics calls that you would use to display your graph to the screen. It returns 1 if the process succeeds.

It is vital to close the SVG file when it is complete:

    CALL CLOSE_SVG@(0)

Without this call, the SVG file will be left incomplete when your program finishes, and it will not be usable.

The second and third arguments of OPEN_SVG@ are the width and height of the notional window into which graphics calls will put their data. Thus with the above call to OPEN_SVG@, if your program contains the following graphics call:

    DRAW_LINE_BETWEEND@(0.0D0,0.0D0,799.0D0,599.0D0,255)

then displaying the resultant SVG file will contain a diagonal red line from the top left corner (0,0) to the bottom right corner (799,599). However, the file can be displayed on a much larger (or smaller) surface without loss of resolution.

ClearWin+ now contains a full set of primitive functions - such as DRAW_LINE_BETWEEND@ - that take REAL*8 arguments. You don't need to use these, but remember that you don't want your calculations to be rounded to integer values as a result of calling the older functions that take integer arguments, otherwise the rounding error will be visible if the SVG file is ultimately displayed in a large format, such as a poster. Functions using the D suffix can still be called to prepare non-SVG graphics, so the preparation of your graphics can be identical whatever the destination.

Reading SVG files previously output by ClearWin+

At any point where you could call a graphics primitive, you may make a call of the following form:

    CALL IMPORT_SILVERFROST_SVG@("Something.svg",X_OFFSET,Y_OFFSET, SCALE)

X_OFFSET, Y_OFFSET and SCALE are REAL*8 quantities that specify the the position of the top left corner of the SVG image. The scale argument would typically be 1.0d0, but as explained above, an SVG file can be displayed at any resolution by adjusting this argument.

The image will be drawn into the currently open drawing surface.

Reading TEX files into ClearWin+

Files ending with a .TEX suffix are assumed to contain mathematical formulae or other objects that are designed to be processed by LATEX. In order to use this feature it is necessary to install MIKTEX implementation of LATEX, which should be included in the PATH environment variable. Other implementations may well work, but the feature has only been tested with MIKTEX.

To read a TEX file into ClearWin+ graphics, make a call of the following form:

    CALL IMPORT_TEX_OBJECT@("MyStuff.tex",X_OFFSET,Y_OFFSET, SCALE,WIDTH,HEIGHT)

The system calls MIKTEX commands to convert the tex file into a corresponding SVG file. This feature is experimental, and may not always be successful. The SVG file is then read into a graphics area in the same way as above, with an important difference:

The conversion to TEX results in a large white space border, which is removed before the image is displayed. Therefore the REAL*8 arguments, WIDTH and HEIGHT return the size of the image that is actually drawn into the graphics area.

Normally the SVG file is deleted before this call returns, but it can be retained using a prior call to

    CALL SAVE_TEX_SVG_CONVERSION@()

Since conversions from TEX can take a few seconds, one use of this function is to save the SVG file and use it rather than the TEX file when executing your program.

Sample Program

Here is a sample program illustrating a call to IMPORT_TEX_OBJECT@. The file called formula.tex is not included.

WINAPP
INCLUDE <windows.ins>
DOUBLE PRECISION graphics_width,graphics_depth,scale,x_disp,y_disp
INTEGER x1,y1,x2,y2,k,control,border
  control=-1
  k=winio@("%gr[smooth4]%lw",640,480,control)
  x_disp=100.0d0; y_disp=100.0d0; scale=1.5d0
  CALL set_svg_option@("Silent_Tex")
  CALL import_tex_object@("formula.tex",x_disp,x_disp,scale,graphics_width,graphics_depth)
  border=5
  x1=x_disp-border; x2=x_disp+graphics_width+border
  y1=y_disp-border; y2=y_disp+graphics_depth+border
  CALL draw_line_between@(x1,y1,x2,y1,255)
  CALL draw_line_between@(x1,y2,x2,y2,255) call draw_line_between@(x1,y1,x1,y2,255)
  CALL draw_line_between@(x2,y1,x2,y2,255)
END

Sample Program

Clearwin+ can be used to generate SVG files by calling OPEN_SVG@ before drawing the graphics (this is analogous to generating printer output).

INTEGER FUNCTION OPEN_SVG@(FILE, NX, NY)
CHARACTER(*) FILE
INTEGER NX,NY

INTEGER FUNCTION OPEN_SVG1@(FILE, NX, NY, ID)
CHARACTER(*) FILE
INTEGER NX,NY,ID

INTEGER FUNCTION CLOSE_SVG@(ID)
INTEGER ID

NX and NY specify the bounding box into which the graphics are to be drawn. FILE is the path of the file. If ID is zero then the current "drawing surface" is selected when the file is closed otherwise ID is the user's identifier of the graphics object to be selected (see SELECT_GRAPHICS_OBJECT@). Both functions return 1 on success or zero on failure. Note that ID is an input value in OPEN_SVG1@.

Here is a sample program...

INCLUDE <windows.ins>
INTEGER i,icolor,ans
DOUBLE PRECISION x1, x2, y1, y2, x(3), y(3)
  ans = open_svg@("sample.svg",800,600)
!!! i = winio@("%gr%lw",800,600,ictrl)
  x1 = 200.0d+00; y1 = 200.0d+00; x2 = 200.0d+00; y2 = 500.0d+00
  CALL set_line_width@(10)
  icolor = RGB@(128,128,128)
  CALL draw_line_betweenD@(x1, y1, x2, y2, icolor)
  x1 = 200.0d+00; x2 = 600.0d+00; y1 = 200.0d+00; y2 = 200.0d+00
  icolor = RGB@(255,0,0)
  CALL set_line_style@(PS_GEOMETRIC+PS_ENDCAP_SQUARE+PS_JOIN_ROUND)
  CALL draw_line_betweenD@(x1, y1, x2, y2, icolor)
  x(1) = 300.0d+00; x(2) = 500.0d+00; x(3) = 300.0d+00
  y(1) = 300.0d+00; y(2) = 400.0d+00; y(3) = 500.0d+00
  icolor = RGB@(0,0,255)
  CALL set_line_style@(PS_GEOMETRIC+PS_ENDCAP_SQUARE+PS_JOIN_MITER)
  CALL draw_polylineD@(x, y, 3, icolor)
  x(1) = x(1)+100.0d+00; x(2)=x(2)+100.0d+00; x(3)=x(3)+100.0d+00
  CALL set_line_style@(PS_GEOMETRIC+PS_ENDCAP_SQUARE+PS_JOIN_ROUND)
  CALL draw_polylineD@(x, y, 3, icolor)
  x1 = 200.0d+00; x2 = 600.0d+00; y1 = 50.0d+00; y2 = y1
  icolor = RGB@(0,255,0)
  CALL set_line_style@(PS_GEOMETRIC+PS_ENDCAP_SQUARE)
  CALL set_line_width@(20)
  CALL draw_line_betweenD@(x1, y1, x2, y2, icolor)
  y1 = 100.0d+00; y2 = y1
  CALL set_line_style@(PS_GEOMETRIC+PS_ENDCAP_ROUND)
  CALL draw_line_betweenD@(x1, y1, x2, y2, icolor)
  y1 = 150.0d+00; y2 = y1
  CALL set_line_style@(PS_GEOMETRIC+PS_ENDCAP_FLAT)
  CALL draw_line_betweenD@(x1, y1, x2, y2, icolor)
  ans = close_svg@(0)
END

The EditSVG utility

EditSVG is a Silverfrost application that can be used to compose images from a number of SVG sources. You can use the menu to open SVG files previously written by ClearWin+, or TeX files. The latter are converted to SVG files before being read in. TVG and TeX files may also be dragged and dropped on to the main window.

The next step is to position each image by clicking on it and dragging it into position. It is possible to use the menu to display a grid to help with this process. The grid can either be passive, or act to snap each image into alignment as it is moved. By right clicking on an image, it is possible to shrink or expand it as required.

Remember that, because these images are derived from SVG's, they scale very well, producing results as illustrated in the examples below.

There is no particular order to the operations - you can adjust everything until the result is as desired. As you drag the images, the one being dragged will overlay any others, with the exception that, if an image totally obscures another image, this will pop to the top. You can then use the menu to save the result to another SVG file.

After this step you can either close the program, or you can continue to work on the images on the screen, and save more results.

Examples

One powerful feature of the Clearwin+ SVG implementation is the ability to drag and drop LaTeX source code directly onto a graph in order to label the title or legends using mathematical equations. Equations and chemical formulas can also be added to a graph in this way to illustrate the graph contents.

PDF documents containing numerous worked examples along with LaTeX code are available from https://simfit.org.uk/tutorials.html and some selected graphs from this document follow.

First note that, although all the SVG functionality available within Silverfrost FTN95 can be accessed using the subroutine calls described previously, the utility EditSVG provides the ability to easily manipulate SVG and TEX files. This is distributed with FTN95 as a free standing executable, but can also be opened directly using the Fortran code

 CALL EDITSVG_DRIVER

which then displays an interface to EditSVG that also provides links to several test files that illustrate SVG functionality. These can be used from this interface by pressing the [Demo] button on the file-open control, giving easy access to a selection of demonstration files from the folder

 C:\Program Files (x86)\Silverfrost\Simdem\dem

Case 1: Planting a graph as an inset into the body of a main plot

Consider an experiment where fitting one then two exponential functions has been undertaken to estimate goodness of fit and where model discrimination has also been assisted by alternatively plotting in semi-log space.

To create the finished plot the file "exfit_normalplot.svg" is first read into EditSVG followed by the file "exfit_logplot.svg", using the option to trim extraneous white space, then finally scaling the logplot and re-positioning it to create the finished plot "exfit.svg".

Case 2: Importing LaTeX source into a graph

The first figure below illustrates using LaTeX source to add a mathematical equation to a graph, the second the result after adding a chemical formula, and the third using LaTeX for a plot legend.

The LaTeX source for the normal cumulative distribution is

      \documentclass[12pt]{article}
      \usepackage{amsmath,bm}
      \pagestyle{empty}
      \begin{document}
      \Large
      \[
         \frac{1}{\sigma \sqrt{2\pi}}
         \int\limits_{-\infty}^x
         \exp -\left\{
         \frac{1}{2} \left( \frac{t-\mu}{\sigma} \right)^2 \right\}\,dt
      \]
      \end{document}

and, when a file containing this code is input into EditSVG to add to the cumulative distribution plot, the LaTeX is used to create a SVG file with extraneous white space trimmed off, which is always necessary for TEX files. All that remains is to re-position and scale the formula.

The LaTeX source for the y-axis label on the beta distribution plot is shown next.

      \documentclass[12pt]{article}
      \usepackage{amsmath}
      \usepackage{graphicx}
      \pagestyle{empty}
      \begin{document}
      \Large
      \rotatebox{90}{$ f_X(x:\alpha,\beta) = \frac{\Gamma(\alpha +
      \beta)}{\Gamma(\alpha)\Gamma(\beta)}x^{\alpha - 1}(1 - x)^{\beta - 1}$}
      \end{document}

Case 3: Creating collages

By using EditSVG it is possible to import several files and then proceeed to scale the individual files and arrange them into an appropriate array of sub-graphs.

When the sculptured end product has been created it is then possible to create an export-image file (*.ISVG) which simply contains the filenames, scaling factors, and coordinates. Importing such files into EditSVG then re-creates the collage.

The first collage contains a number of LaTeX scripts for mathematical expressions and chemical structures. These were input sequentially then scaled and rearranged.

The second collage just contains two files, first the LaTeX source for the maths defining the binomial and Poisson distributions.
Then a SVG file containing the bar chart for testing the Goodness of Fit of a Poisson distribution to observed frequencies was added.

Finally, note that if you use the Fortran code

CALL EDITSVG_DRIVER

then choose to input a number of SVG files using a library file, an open-file dialogue will appear from which you can press the [Demo] button and open the library file "SVG_collage.tfl", which will cause an ISVG file generated from this library file to be input into EditSVG. Then you can create a collage and practise moving the SVG files displayed to create a collage that can be exported as SVG or PNG. Note that a grid can be displayed with snap-to nearest-corner functionality to assist lining up the rows and columns of the collage.


OpenGL

In this section:

  • Introduction
  • OpenGL - %og[options]
  • The conversion of a Red Book example
  • Using a printer with OpenGL
  • References
  • Online information

OpenGL provides a relatively simple, platform independent, way to produce complex (possibly animated) 2 or 3-dimensional images. Lighting and perspective effects are easily introduced, although in order to achieve high performance, full ray tracing (which produces shadows and effects caused by multiply scattered light rays) is not available. The performance of OpenGL is sufficient that it is often used for 3-D animation. The following two books explain the use of OpenGL without going into platform-specific details:

OpenGL Programming Guide (Red Book)

OpenGL Reference Manual (Blue Book)

See the end of this section for further details. OpenGL is available via two DLLs that may already be installed on your PC.

This section does not present a tutorial on OpenGL nor does it describe the OpenGL API. You are advised read the official "Red Book" learning guide to OpenGL, and to visit the OpenGL web site at http://www.OpenGL.org.

Examples in the Red Book are simplified by the use of a specially designed and written auxiliary OpenGL library (called GLAUX). GLAUX provides an easy way to open a window with the OpenGL attributes that you require. However, it is limited in its use of mouse, keyboard and message handling and has the overwhelming disadvantage you cannot attach menus or buttons. Also, it only allows one window to be opened. ClearWin+ is very similar to GLAUX with regard to the ease with which OpenGL windows can be opened. However, ClearWin+ has none of the above restrictions. Nevertheless, the Red Book examples provide a convenient tutorial approach to learning how to call the OpenGL library from ClearWin+. Much of this section is devoted to discussing how to convert the the Red Book examples that use GLAUX to ClearWin+.


OpenGL

OpenGL - %og[options]

In this section:

  • Introduction
  • OpenGL - %og[options]
  • The conversion of a Red Book example
  • Using a printer with OpenGL
  • References
  • Online information

In order to open an OpenGL window with ClearWin+, you must use the %og format code:

i=winio('%og[static]')

%og takes an list of options consisting of any valid combination of the following:

double | This option is used for animation and causes OpenGL output to be sent to an in-memory buffer until the swap_opengl_buffers@ subroutine is called. This helps to reduce flicker at the expense of requiring more memory.
depth16 | Specifies 16 bits of depth buffering.
depth32 | Specifies 32 bits of depth buffering.
stencil | Stencil buffer. The stencil buffer is used to define masks used to prevent part of image being drawn. For example, OpenGL only allows convex polygons to be filled. More complex polygons require the use of the stencil buffer.
accum | The accumulation buffer is used to accumulate images for effects such as anti-aliasing motion blur, depth of field etc.
user_resize | Same as %gr usage.
static | Used to redraw window after it has been partially revealed.

Any combination of these attributes is permitted. Depth buffering is an option that can be omitted. If both depth16 and depth32 are specified, depth32 takes effect.

These attributes, with the exception of static, are directly analogous to the GLAUX equivalent. For example, the GLAUX attribute AUX_ACCUM is the same as the ClearWin+ attribute ACCUM.

Converting examples written using GLAUX to ClearWin+ is, therefore, relatively straight forward. Most of the differences arise through language choice rather than by the use of ClearWin+. A Fortran program will inevitably have a slightly different structure from a C program.


The conversion of a Red Book example

In this section:

  • Introduction
  • OpenGL - %og[options]
  • The conversion of a Red Book example
  • Using a printer with OpenGL
  • References
  • Online information

The example in listing 1.2 of the Red Book, simple.c is reproduced below. Each line in the source is numbered to aid description.

1 /* simple.c */
2
3 #include <GL/gl.h>
4 #include <GL/glaux.h>
5 #include <stdlib.h>
6
7
8 int main(int argc, char** argv)
9 {
10 auxInitDisplayMode (AUX_SINGLE | AUX_RGB);
11 auxInitPosition (0, 0, 500, 500);
12 auxInitWindow ("Simple OpengGL Sample");
13
14 glClearColor (0.0, 0.0, 0.0, 0.0);
15 glClear(GL_COLOR_BUFFER_BIT);
16 glColor3f(1.0, 1.0, 1.0);
17 glMatrixMode (GL_PROJECTION);
18 glLoadIdentity ();
19 glOrtho(-1.0, 1.0, -1.0, 1.0, -1.0, 1.0);
20 glBegin(GL_POLYGON);
21 glVertex2f(-0.5, -0.5);
22 glVertex2f(-0.5, 0.5);
23 glVertex2f(0.5, 0.5);
24 glVertex2f(0.5, -0.5);
25 glEnd();
26 glFlush();
27 _sleep (10000);
28 return(0);
29 }

When converting to Fortran, lines 1 to 9 may be ignored. Lines 10 to 12 describe the window properties to GLAUX. These properties are:

AUX_SINGLE single buffered. This is ClearWin+ default and is not necessary in the ClearWin+ version.

AUX_RGB use RGB colours. ClearWin+ only supports RGB colours for OpenGL. Colour index modes are unsuitable for shading and anti-aliasing and so are not supported.

0, 0 initial window position. This is specified using %sp in ClearWin+.

500, 500 initial window size. This is specified using %og in ClearWin+.

"Simple OpenGL Sample" window caption.

In addition, GLAUX windows may be closed using the Escape key. Specify this with %es using ClearWin+.

ClearWin+ uses %lw to allow a window to stay open when the winio@ call returns. If %lw were not specified, the drawing commands following would have no effect.

Lines 10 to 12 are replaced with the following calls to winio@. The ampersands at the end of every line are used to combine several winio@ calls into one format window.

c----Allows the user to close the window with the <esc> key
i=winio@('%es&')
c----Window caption
i=winio@(%ca[Simple OpengGL Sample]&')
c----Sets initial window position to (0,0)
i=winio@('%sp&',0,0)
c----Makes the same style of window as GLAUX
i=winio@('%ww[no_border]&'
c----Creates the OpenGL window and returns leaving it open
i=winio@('%og[static]%lw',500, 500,ctrl)

This may all be combined into:

i=winio@('%es%ca[Simple OpengGL Sample]&')
i=winio@('%sp%ww[no_border]%og[static]%lw',
& 0,0,500,500,ctrl)

The use of line 28 with the Red Book example is to keep the window open for 10 seconds before closing it. This is unnecessary since the ClearWin+ window will stay open anyway until the user closes it. Note that the integer variable, ctrl is required since we have used %lw but that the variable itself is unused.

The Fortran include files clearwin.ins and opengl.ins must be included at the top of the main program.

The remainder of the program is virtually unchanged. The full ClearWin+ version appears below.

PROGRAM Simple
INCLUDE <clearwin.ins>,nolist
INCLUDE <opengl.ins>,nolist
REAL t1,t2
INTEGER i, ctrl
i=winio@('%es%ca[Simple OpengGL Sample]&')
i=winio@('%sp%ww[no_border]%og[static]%lw',
& 0, 0, 500, 500, ctrl)
CALL glClearColor (0.0, 0.0, 0.0, 0.0)
CALL glClear(GL_COLOR_BUFFER_BIT)
CALL glColor3f(1.0, 1.0, 1.0)
CALL glMatrixMode(GL_PROJECTION)
CALL glLoadIdentity()
CALL glOrtho(-1d0, 1d0, -1d0, 1d0, -1d0, 1d0)
CALL glBegin(GL_POLYGON)
CALL glVertex2f(-0.5, -0.5)
CALL glVertex2f(-0.5, 0.5)
CALL glVertex2f( 0.5, 0.5)
CALL glVertex2f( 0.5, -0.5)
CALL glEnd()
CALL glFlush()
END

As can be seen, the OpenGL calls and their positions are unchanged. A couple of calls to winio@ have replaced the calls to GLAUX. Overall, the two programs are very similar. This will be reinforced but qualified when we look at other examples.

More:

Argument types

Call-backs and initialisation

Animation and multiple windows


Using a printer with OpenGL

In this section:

  • Introduction
  • OpenGL - %og[options]
  • The conversion of a Red Book example
  • Using a printer with OpenGL
  • References
  • Online information

When using OpenGL, the quality of the printer output and the rendering of colour are especially important and it is recommended that you check your printer driver settings, ensuring (for example) that you are using the highest setting for the number of dots per inch.

The following functions are provided to enable you to print OpenGL images.

OPEN_GL_PRINTER@

OPEN_GL_PRINTER1@

PRINT_OPENGL_IMAGE@


The GLUT library

The OpenGL standard only addresses issues directly related to the display of 2 and 3-dimensional scenes. It does not address matters of user interaction (mouse/keyboard) or the relation between OpenGL and the underlying Windows system. Although the %og format solves all these problems, many existing OpenGL applications are written in terms of an additional library of functions known as GLUT. A DLL called GLUT32.DLL is available for Windows and is part of the Silverfrost compiler distribution.

Many of the GLUT routines, such as those that construct models of entire objects, are directly callable once an OpenGL window has been opened using %og. Other functions are declared in OPENGL.INS in such a way that the GLUT function is replaced by an equivalent function in the ClearWin+ library. Usually the only change that is required to make a GLUT/OpenGL Fortran program work under ClearWin+ is to include OPENGL.INS in any routine that makes GLUT calls. In particular, GLUT routines such as glutCreateWindow (that create a window containing an OpenGL display) can be used with the %og format.

Calls to functions such as glutMotionFunc (that supply callback routines for mouse input) work both on windows created with an explicit call to winio@ using %og and with windows created by calls to GLUT. If %^og is used (to specify a ClearWin+ callback function) the GLUT callback (if any) is called, followed by the ClearWin+ callback function (normally one would use only one set of callbacks, either ClearWin+ or GLUT).

By using the GLUT function glutCreateMenu it is possible to dynamically associate a menu with left and/or right mouse clicks inside the OpenGL area. This can be freely mixed with %mn/%sm (that create menus on the window itself), but should not be combined with popup menus (%pm).

GLUT addresses the problem of creating multiple OpenGL displays simultaneously and it is possible to create multiple displays using GLUT and ClearWin+. Using ClearWin+ you can create a window containing two or more %og controls, or you can create multiple independent windows each containing %og controls. For this purpose it is necessary to specify which OpenGL display will respond to OpenGL or GLUT function calls at any given time. By using the grave modifier (%`og) you supply one extra integer argument (immediately before the callback function, if any) that receives a handle known as a 'rendering context'. This handle is passed to SET_OPENGL_CONTEXT@ in order to switch between the various active OpenGL controls:

SUBROUTINE SET_OPENGL_CONTEXT@(C)
INTEGER(7) C

Note that the context argument to %`og is not filled in until the %og window is created.

In a %og callback function the CLEARWIN_INFO@ parameter OPENGL_DEVICE_CONTEXT reflects the OpenGL control that invoked the callback. Thus within a callback function (created using %^og or GLUT) OpenGL/GLUT calls will automatically relate to the window from which the function was invoked. After the callback function is complete the context will revert to its previous state.

The following GLUT function calls, which all relate to special hardware such as joysticks, are not currently implemented. Although these functions exist in the GLUT32.DLL, calling them will not produce useful results:

GLUTSPACEBALLMOTIONFUNC
GLUTSPACEBALLROTATEFUNC
GLUTSPACEBALLBUTTONFUNC
GLUTBUTTONBOXFUNC
GLUTDIALSFUNC
GLUTTABLETMOTIONFUNC
GLUTTABLETBUTTONFUNC
GLUTTIMERFUNC

A manual describing the GLUT library can be found at https://openglut.sourceforge.net/group__api.html.


References

In this section:

  • Introduction
  • OpenGL - %og[options]
  • The conversion of a Red Book example
  • Using a printer with OpenGL
  • References
  • Online information

• Woo, Mason, Jackie Neider, and Tom Davis. OpenGL Programming Guide: The Official Guide to Learning OpenGL, Version 1.1.Reading, MA: Addison Wesley Longman Inc. 1997. ISBN 0-201-46138-2.

• OpenGL Architecture Review Board; Renate Kempf and Chris Frazier, editors. OpenGL Reference Manual. The Official Reference Document for OpenGL, Version 1.1. Reading, MA: Addison Wesley Longman Inc. 1996. ISBN 0-201-46140-4.

• Fosner, Ron. OpenGL Programming for Windows95 and Windows NT. Reading, MA: Addison Wesley Longman Inc. 1996.

• Wright Jr., Richard S. and Michael Sweet. OpenGL Superbible: The Complete Guide to OpenGL Programming for Windows NT and Windows 95. Waite Group Press. 1996.

• Angel, Edward. Interactive Computer Graphics: A top-down approach with OpenGL. Reading, MA: Addison Wesley Longman Inc. 1997. ISBN 0-201-85571-2.


Online information

In this section:

  • Introduction
  • OpenGL - %og[options]
  • The conversion of a Red Book example
  • Using a printer with OpenGL
  • References
  • Online information

Reference pages for OpenGL are available at

https://www.opengl.org/

https://www.khronos.org/opengl/

https://learnopengl.com/Getting-started/OpenGL

http://www.opengl-tutorial.org/

https://docs.microsoft.com/en-us/windows/win32/opengl/opengl

The OpenGL web site contains links to a variety of articles, the OpenGL specification, and the OpenGL usenet mailing list.

Other items are available to members of the Microsoft Developer Network. Online versions of technical articles are also available on the Microsoft Developer homepage.


SIMPLEPLOT

In this section:

  • Introduction
  • A simple example
  • %pl options
  • Direct calls to SIMPLEPLOT
  • Native %pl, SIMPLEPLOT without the DLL

SIMPLEPLOT is a library of 32-bit FORTRAN subroutines designed and marketed by BUSS Ltd. to produce pictures of data with speed and accuracy. The basic SIMPLEPLOT library offers a wide range of facilities for drawing Cartesian and polar graphs. Extensions are available for contouring and surface pictures, presentation graphics for high quality output and representations of 3D data.

ClearWin+ provides access to SIMPLEPLOT via a dynamic link library (simple.dll) that is distributed with Silverfrost compilers. Access to this library is available by using the winio@ function together with the %pl format code. %pl is designed to be similar to %gr.

In this section we shall look at three elementary programs that illustrate the essential features of the interface between ClearWin+ and SIMPLEPLOT. The first two examples illustrate an automatic mode of access. This is by far the easiest way to access the SIMPLEPLOT library from ClearWin+. The final example shows you how to make direct calls to the SIMPLEPLOT library. Further information about SIMPLEPLOT can be found in the documentation provided by BUSS Ltd.

For 64-bit applications, ClearWin+ provides a native 2D graph drawing facility via the same %pl interface. Details of features peculiar to the native mode are provided here.


A simple example

In this section:

  • Introduction
  • A simple example
  • %pl options
  • Direct calls to SIMPLEPLOT
  • Native %pl, SIMPLEPLOT without the DLL

In our first example we create a window and draw a quadratic curve within it.

c--Simple1.for
WINAPP
INTEGER N,winio@,i
PARAMETER(N=11)
REAL*8 x(N),y(N)
c--Create the data to be plotted.
DO i=1,N
x(i)=i-1
y(i)=x(i)**2
ENDDO
c--Plot the data.
i=winio@('%ca[SIMPLEPLOT-Quadratic]%bg[grey]&')
i=winio@('%pl[x_array]&',400,250,N,x,y)
i=winio@('%ff%nl%cn%tt[OK]')
END

%pl is like %gr and takes the basic form:

winio@('%pl[options]',width,height)

width and height represent the pixel dimensions of a SIMPLEPLOT graphics region within the window. Some of the options take additional arguments. In this example, the option called x_array takes three arguments namely the number of points N followed by an array of x co-ordinates and an array of y co-ordinates.

Following the usual ClearWin+ convention, all real data is passed as DOUBLE PRECISION values. However, SIMPLEPLOT uses single precision, so data values should not exceed the single precision range.


%pl options

In this section:

  • Introduction
  • A simple example
  • %pl options
  • Direct calls to SIMPLEPLOT
  • Native %pl, SIMPLEPLOT without the DLL

The following options are available for use with %pl in automatic mode:

Option | Description
SCALE=LINEAR | Specifies a Cartesian plot with linear x and y data. This is the default.
SCALE=LOG_LINEAR | Specifies a Cartesian plot with linear x and log y data.
SCALE=LINEAR_LOG | Specifies a Cartesian plot with log x and linear y data.
SCALE=LOG_LOG | Specifies a Cartesian plot with log x and log y data.
N_GRAPHS=<n> | Specifies the number of graphs to be drawn on the same axes (the default is N_GRAPHS=1)
X_AXIS=<text> | Specifies text for x-axis label (the default is X_AXIS=X)
Y_AXIS=<text> | Specifies text for y-axis label (the default is Y_AXIS=Y)
TITLE=<text> | Specifies the title for graph (by default there is no title).
X_ARRAY | Specifies that an array of x values is supplied. If this option is not specified then the first x value together with a constant increment must be supplied.
Y_MIN=<value> | Specifies the minimum y value. By default this is computed from the data.
Y_MAX=<value> | Specifies the maximum Y value. By default this is computed from the data.
COLOUR=<name> | Specifies the colour of the plot (red, black, blue, etc.). The first use of COLOUR refers to the first plot, the second to the second plot and so on.
COLOR=<name> | The same as COLOUR.
STYLE=<n> | STYLE=0 gives a smooth plot. With STYLE=1, points are plotted using small squares and the relevant colour. The first use of STYLE refers to the first plot, the second to the second plot and so on.

Additional options for use with native %pl are described here.

Note that where text is supplied for the label of an axis or for the title, this text is terminated by the next comma, space or square bracket. In order to include commas, spaces or square brackets in the text you should enclose it in single or double quotation marks.

Here is a program that uses some of these options.

c---Simple2.for
WINAPP
INTEGER i,x,winio@,N
PARAMETER(N=1000)
REAL*8 p1,p2,p3,y(N)
c---Prepare the data.
p1=1.5
p2=150.0
p3=15
x=0
DO i=1,N
y(i)=p1*sin(x/p3)*exp(-x/p2)
x=x+1
ENDDO
c---Display a window containing the graph.
i=winio@('%ww[no_border]%ca[SIMPLEPLOT-Damped wave]%pv&')
i=winio@('%pl[x_axis=Time(Miliseconds),'
+//'y_axis=Amplitude,title="Sample plot",colour=red]',
+ 400,300,N,0.0D0,1.0D0,y)
END

In this case, since the option X_ARRAY is not used, the argument list for %pl includes the initial value of x (0.0D0) and the increment for x (1.0D0). Note also that %ww and %pv are used with %pl. As a result, the window can be sized and the graph is redrawn to fill the window. The output is illustrated below.

Here is a fragment of code that shows how to plot two graphs on one set of axes.

i=winio@('%pl[X_AXIS=Time(Miliseconds),Y_AXIS=Amplitude,'//
+ 'TITLE="Sample",N_GRAPHS=2,COLOUR=red,COLOUR=blue,X_ARRAY]',
+ 300,300,N,xarr,yarr1,yarr2)

There is one x-array for the two y-arrays. The first graph would be red in colour and the second blue.

Note that the arrays of data supplied to %pl usually need to be available for as long as the window is displayed. In particular, the data will be re-plotted if the window is re-sized. It is also possible to call the routine SIMPLEPLOT_REDRAW@ to force all such plots to be re-drawn using whatever values are currently present in the arrays. SIMPLEPLOT_REDRAW@ is a subroutine that takes no arguments.


Direct calls to SIMPLEPLOT

In this section:

  • Introduction
  • A simple example
  • %pl options
  • Direct calls to SIMPLEPLOT
  • Native %pl, SIMPLEPLOT without the DLL

For 32-bit applications, as an alternative to the automatic mode described above, %pl can take the form:

winio@('%pl[user_drawn]',width,height)

width and height give the pixel dimensions of a SIMPLEPLOT graphics region. There are no other arguments to go with %pl. Direct calls can be made to the SIMPLEPLOT library from within a %sc call-back. Alternatively you could use %lw and put the library calls after the set of winio@ statements that describe the window.

Here is a simple example that illustrates this approach. Another direct approach using %dw is illustrated here.

c--Simple3.for
WINAPP
INTEGER winio@,i,StartCB
EXTERNAL StartCB
i=winio@('%sy[no_border]%ca[User drawn]&')
i=winio@('%pl[user_drawn]&',400,300)
i=winio@('%sc',StartCB)
END
c--The start-up callback
INTEGER FUNCTION StartCB()
INCLUDE 'CLEARWIN.INS'
INTEGER N,i
PARAMETER(N=101)
REAL x(N),y(N)
c--Create the data.
DO i=1,N
x(i)=i-1
y(i)=x(i)**2
ENDDO
c--Call SIMPLEPLOT routines to plot the graph.
CALL INITSP
CALL PAGE(12.0,10.0)
CALL CHSET(-11)
CALL NEWPAG
CALL TITLE7('Higher','Centre','Sample')
CALL SCALES(0.0,10.0,1,0.0,100.0,1)
CALL AXGRID('*Cartesian',1,-1)
CALL NEWPIC
CALL AXIS7('XCartesian','x-axis')
CALL AXIS7('YCartesian','y-axis')
CALL BRKNCV(x,y,N,-1)
CALL SIMPLEPLOT_REDRAW@
StartCB=1
END

When you link this program you must link with simple.dll.

Notice that this window cannot be re-sized. As a result the x and y arrays for the data can be local to the start-up call-back function. Further information about the SIMPLEPLOT routines that are used in this example can be found in the documentation provided by BUSS Ltd.


Native graph plotting

In this section:

  • Introduction
  • A simple example
  • %pl options
  • Direct calls to SIMPLEPLOT
  • Native %pl, SIMPLEPLOT without the DLL

The option [native] is available with %pl for 32-bit applications. It may also be used for 64-bit applications where it becomes the default. The graph plotting for native %pl is provided by ClearWin+ and does not use the external 32-bit SIMPLEPLOT library/DLL.

The only limitation of native %pl is that the option [user_drawn] is not available. However, the user is able to draw directly to a native %pl graph as outlined below.

The native %pl uses the same "drawing surface" as %GR and automatically uses the smoothing features of GDI+. This results in new options that allow graphs to be drawn using such features as anti-aliasing.

A native %pl inherits...

a) the current font from %fn;
b) the font style from %it etc.;
c) the font size from %ts;
d) the text colour from %tc; and
e) the background colour from %`bg.

A title is drawn using the current font size. The x and y captions use a slightly reduced font size, whilst the numbers at the tick marks are reduced a little further.

The style options [style=0] (link data points with lines) and [style=1] (draw box symbols at data points) are still provided but new options "link" and "symbol" are preferred...

   [link=none]    Don't join data points.
   [link=lines]   Join data points with straight lines (the default).
   [link=curves]  Join data points with curves.
   [link=columns] Join columns from the x-axis to the data points.
   [link=bars]    Join bars from the y-axis to the data points.
   [symbol=0]     Don't draw symbols at data points (the default).
   [symbol=1]     Draw boxes.
   [symbol=2]     Draw triangles.
   [symbol=3]     Draw up-side-down triangles.
   [symbol=4]     Draw rhombuses.
   [symbol=5]     Symbols 2 and 3 together.
   [symbol=6]     Draw filled boxes.
   [symbol=7]     Draw filled triangles.
   [symbol=8]     Draw filled up-side-down triangles.
   [symbol=9]     Draw filled rhombuses.
   [symbol=10]    Draw circles.
   [symbol=11]    Draw discs.
   [symbol=12]    Draw pluses
   [symbol=13]    Draw Xs

Native options that are set once for each %pl
(d represents a decimal digit, fval is a floating point number).

[native] | Uses ClearWin+ rather than the SIMPLEPLOT DLL.
[width=d] | Specifies the line width (default 1).
[symbol_size=d] | Specifies the size of symbols (default 8x8). This can be used for each graph in turn or just once to change all graphs.
[smoothing=d] Specifies the smoothing mode,where d is in the range 0 to 5 .
(default 0, 4 and 5 provide for anti-aliasing).
[dx=fval] | Specifies the preferred interval between x tick marks.
[dy=fval] Specifies the preferred interval between y tick marks.
dx and dy are only for linear scales and will not always be adopted.
[x_sigfigs=d] | Specifies the number of significant figures to use when drawing the numbers at the x tick marks (default 2).
[y_sigfigs=d] | Specifies the number of significant figures to use when drawing the numbers at the y tick marks (default 2).
[independent] | Specifies that x-data values differ from one graph to the next. See below.
[framed] | Adds a box with tick marks as a frame.
[frame] | Like [framed] but draws the xy-axis caption and tick values outside of the frame
[x_max=fval] | Specifies the maximum x data value.
[x_min=fval] | Specifies the minimum x data value.
[margin=d] | Specifies the margin value in pixels for all margins.
[margin=(d,d,d,d)] | Specifies values in pixels for the left, top, right and bottom margins.
[axes_pen=d] | Specifies the pen width for the axes (value must be 2,3 or 4).
[tick_len=d] | Specifies the length of the tick marks.
[fixed_aspect] | Maintains the initial aspect ratio as the window is resized.
[external_ticks] | Implies [framed] and draws tick marks externally to the frame.
[gridlines] | Provides a rectangular grid based on tick marks.
[stacked] | Treats the y data for different graphs as one large array with the values for the second graph added to the end of those for the first and so on (similarly for independent x arrays). If each graph has the same number of points then this is equivalent to using a 2-dimensional array with the data values in the first dimension and the index ranging from 1 to n_graphs in the second dimension.
[external] | The image does not have an associated parent window but is drawn to the current graphics object. The image could for example be drawn to an existing %gr object or via a call to open_printer@. Printers typically have a relatively high resolution so %pl[external] automatically adjusts certain default values (e.g. various line widths) in order to compensate. See also: PRINT_GRAPHICS@
[full_mouse_input],
[box_selection],
[line_selection],
[free_selection] 		Can be used with the native %pl as for %gr. Related routines such as set_graphics_selection@ and get_graphics_selected_area@ may also be used.
[hscroll], [vscroll]

Adds scrolling options. Previously %vx and %hx could be used with %pl but provided scroll bars as separate controls. The new options create scroll bars that are built into the control and as a result have all of the expected "hot track" characteristics of a scroll bar.

%pl[hscroll] uses the same data as %hx whilst %pl[vscroll] uses the same data as %vx. This is accommodated by presenting %hx with its data before %pl[hscroll] and %vx with its data before %pl[vscroll]. The only restriction is that the %hx and %vx information must not include callback functions. For example:

integer iw,page,range,pos
integer,external::cb
iw = winio@("%vx&", page, range, pos)
iw = winio@("%^pl[vscroll]",400,250,N,x,y,cb)

The values used for 'page' and 'range' determine the y offset of the origin when drawing to the graphics region. Typically the adjustment could be y = y-pos*range. In this way, %gr can be used to display a snapshot of a larger graph by redrawing the area required. Alternatively a full sized graphics region could be created off-screen, with areas copied to the %gr region as required.

The option [independent] provides for independent x-data for each graph. In this case the number of data points must be presented as a variable (for one graph) or as an array (for one or more graphs) where the array index corresponds to the order in which the graphs are coded. This is also the case for the optional x-start and x-increment data. As a result, these values can be changed after a window has been formed.

Native options that are set for each graph in turn.

[pen_style=d]] | Sets the dash style for each line in turn (default zero. These are the Microsoft constants PS_SOLID etc.).
[link=...] | See above.
[symbol=d] | See above.
[symbol_size=d] | Specifies the size of symbols (default 8x8). This can be used for each graph in turn or just once to change all graphs.
[frame_pen=dval] | Takes an integer dval for the pen width of the frame. This is now independent of [axes_pen=dval].
[title_hfont=hval] Takes an integer(7) hval for the HFONT of the title. hval can be obtained via %gf and used in a new routine called winop_hdl@ as illustrated here...
            integer(7) hTitleFont
            ...
            iw = winio@("%fn[Verdana]%ts[1.2]%it%gf%sf&",hTitleFont)
            CALL winop_hdl@("%pl[title_hfont]",hTitleFont)
[function=fun] Takes a REAL*8 FUNCTION fun(x) with REAL*8 argument x, and uses this in place of the y array of data values as illustrated here...
            DOUBLE PRECISION,EXTERNAL::f
            INTEGER,PARAMETER::N=100
            DOUBLE PRECISION x_start,dx
            ...
            CALL winop_fun@("%pl[function]",f)
            iw = winio@("%pl",400,300,N,x_start,dx)

winop_hdl@ and winop_fun@ belong to a set of routines that complement winop@. These are used to simplify the coding of options that require a dynamic value. Here is the current set:

            SUBROUTINE WINOP_INT@(fmt, dval)
            SUBROUTINE WINOP_FLT@(fmt, fval)
            SUBROUTINE WINOP_CLR@(fmt, cval) !for colours
            SUBROUTINE WINOP_STR@(fmt, sval)
            SUBROUTINE WINOP_HDL@(fmt, hval)
            SUBROUTINE WINOP_FUN@(fmt, fun)
            CHARACTER(*) fmt,sval
            INTEGER dval,cval
            DOUBLE PRECISION fval
            INTEGER(7) hval
            DOUBLE PRECISION FUNCTION fun(x)
            DOUBLE PRECISION x

In native mode, %^pl can be used to provide a callback function that will be called after ClearWin+ has drawn the graph(s). This will occur initially and (if %pv is used) when the window is resized. The callback function can draw directly to the graph by using %gr drawing routines such as DRAW_CHARACTERS@.

The options list for %PL can become quite long. A routine WINOP@ is provided so that the options can be preloaded one or more at a time. For example:

  call winop@("%pl[native,title=Graph]")
  call winop@("%pl[style=0,x_array]")
  i = winio@('%pl&',400,250,N,x,y)
  ...

The drawing of a graph can be delayed in one of three alternative ways:

1) By setting all of the y-data values to zero.

2) By setting [link=none] and using the default [symbol=0].

3) By providing the number of data points as a variable and setting it initially to zero.

Correspondingly when the graph is required to be drawn,

1) set the corresponding y-data values, or

2) change the "link" value (see below), or

3) change the number of data points

and then call SIMPLEPLOT_REDRAW@().

The following functions can be called after a window has been formed in order to change the data.

      INTEGER FUNCTION CHANGE_PLOT_INT@(id, option, index, dval)
      INTEGER FUNCTION CHANGE_PLOT_DBL@(id, option, index, fval)
      INTEGER FUNCTION CHANGE_PLOT_CHR@(id, option, index, sval)
      INTEGER id,index,dval
      CHARACTER(*) option, sval
      REAL*8 fval

id is the identifier used with %`PL and SELECT_GRAPHICS_OBJECT@. If there is only one active object then id can be set to zero.
index corresponds to the number of the graph (starting at 1). Set this to zero when the dval/fval/sval applies to all graphs.
dval, fval and sval represent the value to be changed. In two cases this will be an array.
option usually mirrors one of the %PL options and is one of:

          "x_min"     fval - for all graphs
          "x_max"     fval - for all graphs
          "y_min"     fval - for all graphs
          "y_max"     fval - for all graphs
          "dx"        fval - for all graphs
          "dy"        fval - for all graphs
          "x_axis"    sval - for all graphs
          "y_axis"    sval - for all graphs
          "title"     sval - for all graphs
          "color"
          "colour"    dval - for each graph in turn
          "pen_style" dval - for each graph in turn
          "symbol"    dval - for each graph in turn
          "link"      dval - for each graph in turn (0=none, 1=lines, 2=curves)
          "x_data"    fval x-data array which varies from one graph to the next when [independent]
          "y_data"    fval y-data array for each graph in turn

The functions return zero on success or a non-zero error code. CLEARWIN_STRING@("ERROR_REPORT") describes the cause of a failure.

The routine CLEARWIN_OPTION@ can be called in order to change the way that these errors are reported...

          CLEARWIN_OPTION@("hide_error")  ClearWin+ does not generate a direct message. This is the default.
          CLEARWIN_OPTION@("show_error")  ClearWin+ reports an error in a "message box" and continues.
          CLEARWIN_OPTION@("fatal_error") ClearWin+ reports an error in a dialog box together with a trace back and exits.

The following routine can be called from within a %pl callback function in order to get the pixel coordinates of a particular point relative to the axes.

            INTEGER FUNCTION GET_PLOT_POINT@(x,y,xpix,ypix)
            REAL*8 x,y           (input values)
            REAL*8 xpix,ypix     (output values)

There is also the inverse function GET_PLOT_DATA@. This is for use with [full_mouse_input] and gets the (x,y) values for a given point on the screen. The point is retrieved by calling clearwin_info@ using "GRAPHICS_MOUSE_X" and "GRAPHICS_MOUSE_Y".

            INTEGER FUNCTION GET_PLOT_DATA@(ix,iy,x,y)
            INTEGER ix,iy        (input values)
            REAL*8 x,y           (output values)

GET_PLOT_POINT@ and GET_PLOT_DATA@ return zero on success or a non-zero error code.

Additional notes

1. If ClearWin+ draws a title or axis caption at an inappropriate point then its position can be adjusted. For example [title=My Graph@(4.8)] using a decimal point, draws "My Graph" at a point that is adjusted 4 pixels to the right and 8 pixels down from its default position.

2. If an axis caption is not supplied then the defaults are lower case "x" and "y". Setting [x-axis=@] or [y-axis=@] prevents ClearWin+ from drawing the caption which could then be drawn using a callback function.

3. %`PL provides for a user identifier for the %PL control that can be used in a call to SELECT_GRAPHICS_OBJECT@ but this call is not needed within a %^PL callback because the corresponding object will already be selected.

4. Options like y_min, y_max and dy are intended for small adjustments to the results provided by ClearWin+. For example if the range of y was from 1 to 99, then for a better presentation you could set y_min=0.0 and y_max=100.0. Similarly if the tick marks turn out to be at intervals of 11 (say) then you could set dy=10.0.

Here are two sample programs that illustrates many of these features:

Example 1

      WINAPP
      USE clrwin
      INTEGER N,i
      PARAMETER(N=10)
      REAL*8 x(N),y(N)
      DO i=1,N
        x(i)=0.1d0*(i-1)
        y(i)=x(i)*x(i)
      ENDDO
      i=winio@('%ca[Quadratic]%pv&')
      i=winio@('%`bg[white]&')
      CALL winop@("%pl[title=Graph]")
      CALL winop@("%pl[width=2]")
      CALL winop@("%pl[y_max=0.9]")
      CALL winop@("%pl[x_array]")
      CALL winop@("%pl[link=curves]")
      CALL winop@("%pl[symbol=9]")
      CALL winop@("%pl[colour=red]")
      CALL winop@("%pl[pen_style=2]")
      i=winio@('%pl&',400,250,N,x,y)
      i=winio@('%sf%ff%nl%cn%tt[OK]')
      END

Example 2

      WINAPP
      MODULE mydata
        USE clrwin
        INTEGER,PARAMETER::link_none=0,link_lines=1,link_curves=2
        INTEGER,PARAMETER::all_graphs=0,graph1=1
        INTEGER,PARAMETER::n=1000
        LOGICAL shown
        DOUBLE PRECISION y(n)
      CONTAINS
      INTEGER FUNCTION show()
        INTEGER errstate
        errstate = change_plot_int@(0,"link",graph1,link_curves)
        if(errstate /= 0) print*, clearwin_string@("ERROR_REPORT")
        errstate = change_plot_int@(0,"colour",graph1,RGB@(255,0,0))
        errstate = change_plot_dbl@(0,"y_max",all_graphs,1.5d0)
        shown = .true.
        CALL simpleplot_redraw@()
        show = 2
      END FUNCTION show
      INTEGER FUNCTION clear()
        INTEGER errstate
        errstate = change_plot_int@(0,"link",graph1,link_none)
        shown = .false.
        CALL simpleplot_redraw@()
        clear = 2
      END FUNCTION clear
      INTEGER FUNCTION legend()
        IF(shown .AND. clearwin_string@("CALLBACK_REASON") == "PLOT_ADJUST") THEN
          CALL draw_characters@("Legend:..", 300, 100, 0)
          CALL draw_line_between@(300,120,360,120,RGB@(0,0,255))
        ENDIF
        legend = 2
      END FUNCTION legend
      END MODULE mydata

      PROGRAM main
      USE mydata
      INTEGER i,x
      DOUBLE PRECISION p1,p2,p3
      p1=1.5d0
      p2=150.0d0
      p3=15d0
      x=0
      DO i=1,n
        y(i)=p1*sin(x/p3)*exp(-x/p2)
        x=x+1
      ENDDO
      shown = .false.
      i=winio@('%ww[no_border]%ca[Damped wave]%pv&')
      i=winio@('%mn[Edit[Show, Clear]]&', show, clear)
      i=winio@('%fn[Tahoma]&')
      i=winio@('%ts&', 1.1d0)
      i=winio@('%tc&',rgb@(0,0,80))
      i=winio@('%it&')
      i=winio@('%`bg&',rgb@(230,255,225))
      CALL winop@("%pl[native]")
      CALL winop@('%pl[title="Sample plot"]')
      CALL winop@("%pl[x_axis=Time(Milliseconds)]")
      CALL winop@("%pl[y_axis=Amplitude@(-4.0)]")
      CALL winop@("%pl[smoothing=4]") ! anti-aliasing
      CALL winop@("%pl[link=none]")   ! delay drawing
      i=winio@("%^pl",500,400,n,0.0d0,1.0d0,y,legend)
      END


Using the printer

In this section:

  • Introduction
  • Selecting a printer
  • Customising the printer dialog box
  • Printer graphics
  • Using a metafile to print multiple copies

One of the advantages of the Windows operating system is its built-in support for a wide range of printers. ClearWin+ caters for three different types of printer output:

  • Simple text output to the printer
  • HTML text output
  • Graphics output

Before you can send output to the printer it is usually necessary to prompt the user to select the printer to use (this also gives users the opportunity to cancel the print request). There are several methods to obtain this information each of which is described in the topics that follow.

The resolution of a printer varies from one machine to another, but typically printers offer a much finer resolution than even a high quality graphics driver. This means that screen images must be re-drawn for a printer after determining the resolution of the printer selected by the user. If you are using bitmap images as part of your printer output, you may need to use a higher resolution image on the printer than on the screen.

If you send simple text to the printer it will look rather plain because a single font will be used. However, this is sometimes useful for debugging purposes. It is almost as easy to send HTML output to the printer, and this is the recommended method for producing professional printed output from ClearWin+.

For printed output using OpenGL see Using a printer with OpenGL.


Selecting a printer

In this section:

  • Introduction
  • Selecting a printer
  • Customising the printer dialog box
  • Printer graphics
  • Using a metafile to print multiple copies

Using a standard call-back function

In most Windows applications, such as Word for Windows, a standard printer dialog box is produced in response to a user button press or menu activation. Several ClearWin+ standard call-back functions are supplied to perform this task, each of which takes another call-back as an additional argument. The standard printer dialog is automatically displayed and the call-back will contain your code to write or draw to the printer. This call-back will only be called if the user selects a printer from the dialog (as opposed to pressing the Cancel button).

PRINTER_OPEN | Takes an integer Fortran unit number and another callback function as arguments. Displays a dialog box to select the printer and connects it to the given Fortran unit number.
PRINTER_OPEN1 | This also takes a Fortran unit number and another call-back function as arguments. It uses the printer previously selected using PRINTER_OPEN.
HTML_PRINTER_OPEN | This takes a Fortran unit number and another call- back function. It displays a dialog box to select the printer and connects it to the given Fortran unit number.
HTML_PRINTER_OPEN1 | This also takes a Fortran unit number and another call-back function. It uses the previously selected printer.
GPRINTER_OPEN | This takes another call-back as argument and displays a dialog box to select the printer. The printer is connected as the current drawing surface for the duration of the call-back, which should perform the required graphics operations.
GPRINTER_OPEN1 | This operates in the same way as GPRINTER_OPEN, except that a previously opened printer is used.

For example, here is a program that will respond to the button press by prompting the user for a printer and printing 'Hello'.

EXTERNAL printer
i=winio@('Press this button to print a page: ')
i=winio@('%^bt[Print]&','PRINTER_OPEN',7,printer)
i=winio@('%2nl%cn%bt[OK]')
END
c-----
INTEGER FUNCTION printer()
WRITE(7,*)'Hello'
CLOSE(7)
printer=2
END

Notice that the unit is closed before the call-back function exits. Typically, the call-back function should return a value of 2 to indicate that the associated window should stay open without a screen update. However, other call-back return values may be used as described in Clearwin+ call-back functions.

Using the HTML_PRINTER_OPEN or HTML_PRINTER_OPEN1 standard call-backs it is easy to generate pleasantly formatted text output to the printer. This mechanism uses the same subset of HTML as that used by %ht except that one mark-up <PB> is added to set a page break. Here is a simple example:

WINAPP
INTEGER i,winio@
EXTERNAL test
i=winio@('%sc','HTML_PRINTER_OPEN',7,test)
END
c---
INTEGER FUNCTION test()
WRITE(7,'(a)')'<h1>The output</h1>'
WRITE(7,'(a)')'This is <i>Italic</i>.<p>'
WRITE(7,'(a)')'And this is <b>Bold</b>.<p>'
CLOSE(7)
test=2
END

The standard call-backs GPRINTER_OPEN and GPRINTER_OPEN1 do not connect the printer to a Fortran unit number, but rather they create a drawing surface that becomes the current drawing surface. The call-back that is an additional argument to these standard call-backs is used to draw to this surface. The current drawing surface reverts to the previous surface (if any) at the end of the call-back. An example is given in Printer graphics.

Using OPEN_PRINTER@ etc. to create a drawing surface

Alternatively, you can use explicit function calls to create a drawing surface and to attach it to a printer for graphics drawing:

OPEN_PRINTER@ | Displays the standard printer dialog to enable graphics output to be sent to a printer.
OPEN_PRINTER1@ | Re-opens a graphics printer using settings from a previous call to OPEN_PRINTER@.
OPEN_PRINTER_TO_FILE@ | Displays the standard printer dialog to enable graphics output to be sent to a file.
OPEN_PRINTER1_TO_FILE@ | Sends graphics output to a file supplied as an argument.
PRINT_GRAPHICS@ | Manages calls to OPEN_PRINTER@ and CLOSE_PRINTER@. A supplied callback is used to print the graphics

Each of these functions returns zero if the user cancels the operation, and each takes a user identifier as input that is used to switch between drawing surfaces using SELECT_GRAPHICS_OBJECT@. An example is given in Using a metafile to print multiple copies.


Customising the printer dialog box

In this section:

  • Introduction
  • Selecting a printer
  • Customising the printer dialog box
  • Printer graphics
  • Using a metafile to print multiple copies

ClearWin+ uses the standard Windows dialog box to interrogate the user, in each of the above approaches. This has the advantage that the style of the box will take on the 'look and feel' of the operating system in use and will be familiar to your users.

Note that by default Windows uses a new Print dialog. The following ClearWin+ function can be called to force the old Print dialog to be used:

INTEGER FUNCTION USE_OLD_PRINT_DIALOG@( SET )
INTEGER SET

Input a value of SET=1 to use the the old dialog. SET=0 restores the default. The function returns the former state of SET.

In order to change the default behaviour of the printer dialog box you can call PRINTER_DIALOG_OPTIONS@ in order to specify the information that is to be requested in the printer dialog box when it opened using PRINTER_OPEN etc. or open_printer@ etc. (also you can obtain the values selected by the user with calls to CLEARWIN_INFO@).

PRINTER_DIALOG_OPTIONS@ takes nine integer arguments referred to as A1 to A9. The following table indicates the changes that are possible:

Feature | CLEARWIN_INFO@ parameter for result | Default behaviour | Remarks
Print to file | - | Available, initially not checked | If a printer is selected with this option checked, the user will be prompted for a file name. No programming action is required to support this feature. This box will be hidden if A2 is non-zero, and will be initially checked if A9 is non-zero.
Selection | PRINTER_SELECTION | Available, initially not checked | This is a radio button which is used to indicate that only selected material is to be printed. It is up to you to read the parameter and act on it as required. This box will be greyed out (not hidden) if A3 is non-zero, and will be initially selected if A6 non-zero.
Page numbers | PRINTER_FIRST_PAGE PRINTER_LAST_PAGE | Available, set to 1,1. | This enables a range of pages to be selected in various ways. The control is disabled if A2 is non-zero. If all pages are selected the range is returned as 1-32767. If A5 is non-zero the range selection option will be initially selected. If A8 is non-zero the all-pages option will be initially selected.
Collate | PRINTER_COLLATE | Available | This control is always available. Some printer drivers support this option explicitly and the program is not informed of the selection because no action is required. If the parameter is set, an appropriate response is required from the program. If A7 is non-zero the collate box is initially checked.
Copies | PRINTER_COPIES | Available | This control is always available. Some printer drivers support this option explicitly and the program is not informed of the selection because no action is required. If the number of copies is greater than 1, the program should reproduce the output.
Default warning | - | Will occur | A warning will be generated if the user has no printer selected as the default. This wil be suppressed if A4 is non-zero.

Also CLEARWIN_INFO@('PRINTER_PAGENUMBERS') returns 1 if the 'Page Range' is set to 'Pages'.

At most one of A5, A6, A8 should be set non-zero, as they select mutually exclusive options. These defaults work for both built in call-backs and explicit routine calls.

Four other CLEARWIN_INFO@ parameters are also used to control the initial appearance of the printer dialog box. These parameters are set using SET_CLEARWIN_INFO@. The parameters are:

PRINTER_DEFAULT_MIN_PAGE

PRINTER_DEFAULT_MAX_PAGE

PRINTER_DEFAULT_FROM_PAGE

PRINTER_DEFAULT_TO_PAGE

In some situations it may be necessary to set these parameters in a multiple call-back, for example:

i=winio@('%^bt[Print]','+',set_printer_info,'PRINTER_OPEN',10)

where set_printer_info is a user-defined function that makes appropriate calls to set_clearwin_info@.


Printer graphics

In this section:

  • Introduction
  • Selecting a printer
  • Customising the printer dialog box
  • Printer graphics
  • Using a metafile to print multiple copies

Here is a simple program that uses the standard call-back GPRINTER_OPEN to respond to a button press and draws a diagonal line across the entire page. GPRINTER_OPEN creates a drawing surface and an additional call-back argument is used to contain code to draw to this surface.

WINAPP
INTEGER i,winio@
EXTERNAL test
i=winio@('%^bt[Open]','GPRINTER_OPEN',test)
END
c---
INTEGER FUNCTION test()
INCLUDE <windows.ins>
INTEGER xmax,ymax
CALL get_graphical_resolution@(xmax,ymax)
CALL draw_line_between@(0,0,xmax-1,ymax-1,15)
test=2
END

Notice that the call to GET_GRAPHICAL_RESOLUTION@ will work for all types of drawing surfaces. This means that the same code can be used to generate graphics output to the screen and to the printer.

Notice also that by default the drawing surface for the printer uses VGA rather than RGB mode. So in this example, the colour for DRAW_LINE_BETWEEN@ is provided as a colour index (15 represents intense white in this program) rather than an RGB value. Normally RGB mode is preferred and this requires a prior call of USE_RGB_COLOURS@(0,.true.) (see the example in Using a metafile to print multiple copies).

By using open_printer@ etc., it is possible to have two drawing surfaces, one attached to the screen and the other to a graphics printer or plotter. In the following example one identifier is attached to a %gr region (a screen drawing surface) whilst a second identifier is attached to a graphics printer drawing surface.

INTEGER ctrl,hnd1,hnd2
DATA hnd1,hnd2/1,2/
i=winio@('%`gr&',400L,300L,hnd1)
i=winio@('%ww%lw',ctrl)
j=select_graphics_object@(hnd1)
CALL draw_line_between@(100,100,300,200,15)
k=open_printer@(hnd2)
j=select_graphics_object@(hnd2)
CALL draw_filled_ellipse@(200,150,75,50,2)
k=close_printer@(hnd2)

As usual, open_printer@ generates a standard "Open Printer" dialog box from which the user selects a graphics printer or plotter. Subsequent calls to ClearWin+ drawing routines are written to this drawing surface and the output is generated when the ClearWin+ routine CLOSE_PRINTER@ or the routine NEW_PAGE@ is called.

Notes:

• OPEN_PRINTER@ etc. may be used independently of winio@.

• In the above example, j and k can be used to test for the success of the associated function calls.

• Printer surfaces will use GDI+ features if they are turned on.

• PRINT_GRAPHICS@ will help manage printing.


Using a metafile to print multiple copies

In this section:

  • Introduction
  • Selecting a printer
  • Customising the printer dialog box
  • Printer graphics
  • Using a metafile to print multiple copies

Here is another sample program which (like the above example) shows how to draw to a screen drawing surface in parallel with output to a graphics printer or plotter. In this case the image is scaled according to which device is used. Multiple copies are printed by calling DO_COPIES@ but this routine requires a metafile recording of the current image before it is called.

INCLUDE <windows.ins>
REAL scaling
INTEGER i,wc,res,ncopies
INTEGER screen_height,printer_height
INTEGER screen_width,printer_width
INTEGER screen_id,printer_id
EXTERNAL graphics
COMMON scaling,screen_id,printer_id
CALL set_rgb_colours_default@(1)
scaling=1.0
c--- Give id numbers to the screen and printer
screen_id=1
printer_id=2
c---
i=winio@('%ww%ca[Salford graphics]&')
i=winio@('%`gr[black]&',640,480,screen_id)
i=winio@('%`bt[OK]%lw',wc)
CALL graphics()
CALL get_graphical_resolution@(screen_width,
+ screen_height)
c--- Select printer and start document
res=open_printer@(printer_id)
IF(res.NE.0)THEN
CALL use_rgb_colours@(printer_id,.true.)
CALL get_graphical_resolution@(printer_width,
+ printer_height)
c--- Scaling factor for printer
scaling=printer_width/screen_width
c--- Open metafile to record printer drawing
CALL open_metafile@(printer_id)
CALL graphics()
c--- Stop recording
CALL close_metafile@(printer_id)
c--- Make copies of the page
ncopies=2
CALL do_copies@(printer_id,ncopies)
c--- Print document
res=close_printer@(printer_id)
CALL select_graphics_object@(screen_id)
scaling=1.0
ENDIF
END

SUBROUTINE graphics()
INCLUDE <windows.ins>
INTEGER x(10),y(10)
INTEGER hpol,z,xa,xb,err
REAL scaling
INTEGER screen_id,printer_id
COMMON scaling,screen_id,printer_id
CALL set_line_width@(3)
c--- Select font
CALL set_text_attribute@(101,3*scaling,0,0)
xa=300*scaling
xb=350*scaling
CALL draw_characters@('HELLO',xa,xb,RGB@(255,255,255))
CALL set_line_width@(1)
z=200*scaling
CALL draw_line_between@(0,0,z,z,RGB@(255,0,0))
CALL draw_line_between@(0,z,z,0,RGB@(0,255,0))
c--- Ellipse
z=100*scaling
xa=80*scaling
xb=40*scaling
CALL draw_ellipse@(z,z,xa,xb,RGB@(255,0,0))
xa=60*scaling
CALL draw_filled_ellipse@(z,z,xa,xb,RGB@(0,0,255))
c--- Polyline
x(1)=230*scaling
y(1)=20*scaling
c--- .... Code for x(2..4) and y(2..4)
x(5)=x(1)
y(5)=y(1)
CALL draw_polyline@(x,y,5,RGB@(255,0,0))
c--- Polygon
x(1)=30*scaling
y(1)=250*scaling
c--- .... Code for x(2..4) and y(2..4)
x(5)=30*scaling
y(5)=250*scaling
CALL draw_filled_polygon@(x,y,5,RGB@(255,0,0))
END


Hypertext windows

Full Web Browser %wb

Hypertext %N.Mht

Conditional Hypertext

Linking to the web


Hypertext

Hypertext %N.Mht

In this section:

  • Full Web Browser %wb
  • Hypertext %N.Mht
  • Conditional Hypertext
  • Linking to the web

Most programmers and many users will be familiar with the use of Web Browsers such as Internet Explorer. Such browsers display information that has been encoded as ASCII files containing Hypertext Markup Language (HTML). A subset of HTML forms the basis for ClearWin+ hypertext windows.

Hypertext windows provide a way of building very easy to use GUI applications. A hypertext window contains text with hypertext links, that enable users to switch between pages (by clicking on highlighted text and images) or to initiate parts of your program. A hypertext window is created using %ht and can be surrounded by other controls as required.

For example, the format %70.20ht[introduction] would create a hypertext window of a width sufficient to display 70 average width characters and 20 rows. The text would be supplied by a prior call to ADD_HYPERTEXT_RESOURCE@ with the name of a hypertext resource, say 'start', containing the required initial topic called 'introduction'. This would be defined as a resource thus:

start HYPERTEXT "myfile.htm"

You must use the Silverfrost resource compiler SRC for hypertext files, rather than the Microsoft compiler RC. By default, SRC is automatically invoked when a program containing the WINAPP directive is compiled.

The file called browse.htm, that is built into the ClearWin+ browser program, is available as an example program and is an excellent illustration of a hypertext file. Note that hypertext resources are stored in a compressed format, which is not accessible to your users if they choose to binary edit your program file.

The HTML text is displayed in the window that is both left and right justified with scroll bars if necessary. The %ht format may be preceded by a pivot format (%pv) so that the text area changes size as the window is adjusted by the user.

Mark-up codes are contained within diamond brackets < >. For example, a paragraph end is marked using <P>. Mark-up codes are case insensitive. Some codes define a condition that pertains until cancelled by a corresponding mark-up starting with a '/' character. For example, bold face text is preceded by <B> and followed by </B>. Special characters (such as the diamond brackets used to define mark-up codes) are encoded as follows:

&LT; or &lt; produces '<'

&GT; or &gt; produces '>'

&AMP; or &amp; produces '&'

Hypertext files may contain portions of text that are included conditionally, under program control. This is called conditional hypertext. The browse program uses this feature to change the text depending on the programming language selected from the corresponding menu item.

The following HTML codes are currently available in ClearWin+:

<TITLE> ... </TITLE>

This supplies a title to a topic. The title will be placed in the caption of the format window using %ht.

<H1> ... </H1>

Supplies a principle heading to the text. The text will be enlarged and centred. Although the other heading styles (H2 .. H6) may be used, they currently operate in the same way as H1. This may change in future versions of the software.

<HTML> ... </HTML>

In standard HTML these codes are almost redundant. They optionally enclose the entire text. However they are vital for ClearWin+ hypertext as they are used to delimit separate topics. Each topic should be surrounded by these tags and contain a DOC tag.

<DOC name="doc_name">

This defines the topic name, and has no analogue in non-ClearWin+ HTML. Each topic should have a distinct name enclosed in double quotation marks as shown.

<a HREF="name"> ... </a>

This is an HTML anchor that encloses text (or an image) that will be highlighted in blue and will react to a left mouse click. Note that standard HTML anchors have a somewhat more general syntax. The name will usually be another topic name (defined by DOC). If the name does not correspond to a topic and a call-back function is supplied with %ht, then the call-back function will be called. The function can determine the text on the anchor by calling CLEARWIN_STRING@('CURRENT_TEXT_ITEM'). In this way, it is possible to execute code in response to a mouse click.

Hypertext can also contain Uniform Resource Locators (URL's) that link to the web, for example <a href="https://www.silverfrost.com"> or to local files, for example <a href="file:///c:\myproj\test.htm">. Local files must have the .HTM or .HTML extension. Alternatively, if the file has a .EXE extension, it will be executed (see also USE_URL@ and INTERNET_HYPERLINK standard call-back function). By using file URLs, it is possible to create complex webs of inter-related documents without having all the information stored in the executable file.

<P>

Marks the end of paragraph. Subsequent text will start on a fresh line with a small gap separating it from the previous text.

<BR>

Forces a line break with no extra gap.

<HR>

Rules a horizontal line across the page.

<B> ... </B>

Creates bold text.

<U> ... </U>

Creates underlined text.

<I> ... </I>

Creates italic text.

<RED> ... </RED>

Sets the text colour. Other available colours are BLUE, BLACK, GREEN, WHITE, and YELLOW. Hypertext links are coloured blue by default so you may want to avoid the use of this text colour (although the colour of a link can be changed by nesting a colour change inside the link). These are not standard HTML mark-ups.

<FONT SIZE="font_size" FACE="font_face"> ... </FONT>

Sets the font SIZE and/or FACE.

<IMG SRC="name" ALIGN="align_option">

Using this mark-up you can insert a bitmap into your text. name should be the name of a BITMAP resource you have added in the list of included resources (quotation marks are required), and align_option should be one of TOP, MIDDLE, BOTTOM. The alignment specification is optional and the default is BOTTOM. This determines the way in which the image is aligned with the surrounding text. By embedding an image in an anchor construct you can display an image that responds to mouse clicks. GIF files may be used in this context (see %gi, for further information). JPEG files may also be used where name should be the name of an IMAGE resource.

<UL> ... </UL>

Text embedded between these mark-up codes is considered to form an unordered list. Each list item is preceded by a <LI> mark-up and will start on a fresh line with a bullet mark. Lists embedded in lists will nest to the right.

<OL> ... </OL>

Produces an ordered list numbered from 1.

<IF name> ... </IF> - See conditional hypertext below.

<PB>

Sets a page break for use with HTML_PRINTER_OPEN, see Selecting a printer.

A format window can contain at most one hypertext control. It may also contain other controls, menus, etc. as desired. It is, however, possible to embed several child windows, each containing hypertext, within a single parent window. Only one hypertext control per window is allowed because the window provides certain services to the control. Thus the containing window will be displayed with vertical scroll bars if the hypertext is too long for the space provided. Note that this happens entirely automatically. It is an error to attempt to attach vertical scroll-bars (%vx) to a window containing hypertext. Horizontal scroll bars are never needed, since hypertext is always adjusted to fit the width available.

A standard call-back function 'PREVIOUS_TEXT' is available within a window containing hypertext. This would normally be attached to a menu item and causes the hypertext window to 'go back' one topic. A menu item attached to this call-back will be automatically greyed if the hypertext is at the top level.

A call-back function 'TEXT_HISTORY' is available. When invoked it displays a history box associated with a hypertext control in the window. The user can choose to switch to any previously viewed hypertext topic. It is an error to invoke this call-back from a window that does not contain hypertext.

A call-back function 'COPY_TEXT' is also available. When invoked it copies all of the text in the current topic to the clipboard.

By default, hypertext windows are given a grey background, although this can be changed using %`bg. In most cases it is desirable to give the parent window a matching grey background using %bg[GREY].

The title of a window containing hypertext will consist of any explicit title (%ca) followed by the title of the current hypertext topic (as supplied by the <TITLE>) mark-up separated by a hyphen (-).

If there are syntax errors in your mark-up codes, such errors will be reported at run time rather than when the resource is compiled. A error dialog box will appear showing the offending code together with a few lines of the text that follows it.

If a call-back function is supplied to %ht, this function will be called when a jump is made to a topic that has not been defined. Alternatively, a grave accent (`) is supplied in order to ensure that the call-back will be called the first time and each time the hypertext topic changes. The call-back function can then interrogate the following CLEARWIN_STRING@ parameters:

CURRENT_TEXT_ITEM
CURRENT_TEXT_DOCUMENT
CURRENT_TEXT_TITLE

Equation character strings, that follow the rules for %eq (see Mathematical equation), may also be used in hypertext documents. Equation strings are embedded between <equation> and </equation>. The string between these delimiters is treated as a pure equation - no mark-up codes are recognized in this context. So, for example, the '<' symbol should be written as it is.

Here is a list of other standard markups that are accepted:

<body>
<listing>
<li>
<pre>
<cite>
<strong>
<em>
<var>
<xmp>
<code>


Conditional Hypertext

In this section:

  • Full Web Browser %wb
  • Hypertext %N.Mht
  • Conditional Hypertext
  • Linking to the web

The ClearWin+ BROWSER program uses conditional hypertext to display different information depending on the programming language selected.

For example:

Call the <if Fortran> WINIO@ <else> winio </if> function to display a window.

This uses an named integer parameter with the name 'Fortran', set up using the SET_CLEARWIN_INFO@ function. The <if> clause is selected if the parameter is non-zero. The <else> clause is optional. Conditional constructs can be nested, and may contain arbitrary amounts of other mark-up codes and text.

If a call-back function changes the value of a parameter referenced in a conditional construction, it should either return 1 (to cause all controls in the window to be updated) or use WINDOW_UPDATE@ to ensure that the hypertext is updated.

To get a working example of the use of this format code, open the browse.htm file and the associated program browse.cpp.

For example:

WINAPP 0,0,'resource.rc'
...
c--- Only call the next line once.---
CALL add_hypertext_resource@('hyperhelp')
i=winio@('%ca[Hypertext help system]&')
i=winio@('%ww%bg[grey]%pv&')
i=winio@('%^60.22ht[Introduction]',callback)

Where resource.rc contains:

hyperhelp HYPERTEXT 'helpfile.htm'

A summary of ClearWin+ hypertext functions is given in Hypertext functions.


Linking to the web

In this section:

  • Full Web Browser %wb
  • Hypertext %N.Mht
  • Conditional Hypertext
  • Linking to the web

When whole URLs (i.e. URLs with '://' embeded in their name) are used within a <a>HREF=...</a> link in a (%ht) hypertext document, the default web browser is invoked to process the link.

A ClearWin+ routine is also available to perform this task:

SUBROUTINE USE_URL@(URL)
CHARACTER(*) URL

This routine uses the Windows shell to open the URL. As a result it can be used to 'open' other objects such as a file with a name that has a registered extension (e.g. .DOC files). You can use this routine in a ClearWin+ window call-back function (attached to a menu item or button) in order to create a link to a web site or document.

This facility is also available via the INTERNET_HYPERLINK standard call-back function.

There is also a routine to read the contents of a URL (assuming the machine has access to the internet):

SUBROUTINE READ_URL@(URL,FILE,MODE,ERROR)
CHARACTER(*) URL
CHARACTER(*) FILE
INTEGER MODE
INTEGER ERROR

If this routine succeeds (i.e. an internet connection is available and the URL can be accessed), ERROR is set to zero and the data from the URL is transferred to the specified file (which can be a full path name). If MODE=0, the data is assumed to be text and new lines are converted to DOS style. If MODE=1, binary data is assumed.

The URL can be quite general. In particular, you can use an FTP address assuming anonymous access is possible, or an HTTP address with extra information attached. For example, you could query a search engine directly using this routine.

If necessary, the system will dial up the service provider to process this call. By default the connection will not be closed after the transfer has completed. The following call will close a modem connection if one exists.

CALL BREAK_MODEM_CONNECTION@

The function DOWNLOAD@ is similar to READ_URL@ but reads the download into memory.


Standard call-back functions

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • Standard call-back functions are used with ClearWin+ format (winio@) windows. They are functions with no arguments and return an integer result. A returned zero or negative value causes the parent window to close. The corresponding call to winio@ will return the same value made positive. A returned value of 1 leaves the window open and updates the whole display area to reflect any changes in the data. This is not normally the most suitable return value because frequent returns can cause the screen to flicker. A returned value of 2 leaves the window open but does not update it. This value is best for repetitive display updates but you must update the parts of a window that have changed by calling window_update@ (see Updating windows). The call-back function used with %mg may also return the value 3 (see %mg).

    A number of frequently used call-back functions can be specified as character strings that denote standard call-back functions. (Note that there is never any confusion between a pointer to one of these character strings and a genuine function pointer, because all functions start with a distinctive sequence of machine instructions. The system decides whether the supplied pointer points to a function or to one of the special strings described below. If the supplied pointer points to an illegal address, this will cause an immediate program fault to be reported.)

    Standard call-back functions usually appear within the argument list that follows the format string in a call to winio@. Some standard call-back functions require additional arguments that are placed in the winio@ argument list immediately after the string that denotes the standard call-back. The following functions are available.


ABOUT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This takes one character string argument (which may include newline characters) and displays a simple "about" box. Each line of the text is centred, and an OK button is supplied for the user to close the box.


BEEP

BEEP[sound option]

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • If you require a button to make a (Windows) beep sound this call-back will provide a quick and simple way of doing so. It may be most useful when used in conjunction with the call-back joiner '+'. It takes one of the following five possible arguments:

    [EXCLAMATION]

    [QUESTION]

    [HAND]

    [OK]

    [ASTERISK]

    These correspond to the warning icons built into Windows (see Standard icon).

    For example:

    i=winio@(' %^bt[PRESS] ', '+' , 'BEEP[MBOK]', cb_openfile )


CASCADE

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • If this function is invoked from a window containing a MDI frame (%fr). The child windows created with %aw are cascaded leaving the active window at the top.


CONFIRM_EXIT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This call-back function takes one character string argument and displays it as a yes/no question. It is designed to be used with a button or menu option that will exit a window. If the user responds yes, the function returns zero, thus closing the window with the return number of the original button. If the user responds no (the default response) the window remains open. If a window closure call-back (%cc) has been specified, the %cc call-back is called before the closure takes place.

    See also

    EXIT


COPY, CUT, PASTE

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • These three call-back functions transfer information between the edit box (%eb, %rd, %rf, %fs, or %re) that has the focus and the clipboard. Typically, they are used as the call-back function for an edit-copy/cut/paste menu item. These call-back functions require no additional winio@ arguments.

    Menu items and buttons attached to these callback functions are greyed according to circumstances. For example, a control associated with the CUT function would be greyed if no text were currently marked as selected on the screen. However, if the control has a grey control variable then this variable takes precedence.

    Apart from %eb, standard accelerator keys (Ctrl+C, Ctrl+X, and Ctrl+V) can also be used for COPY, CUT and PASTE.


COPY_TEXT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The COPY_TEXT call-back can only be invoked from a format window that includes %ht. When invoked, it copies of all of the text in the current topic to the clipboard.


CONTINUE

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This function returns a non-zero value which therefore leaves the window open. It is used as a dummy when no action is required.


EDIT_FILE

In this section:

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This is used with %eb and takes one character string argument that is the file name of the file to be opened. Unlike EDIT_FILE_OPEN, the standard Windows 'file open' dialog is not presented.


EDIT_FILE_OPEN

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This standard call-back is used with %eb and takes a character string argument containing a file pattern (e.g. '*.TXT'). A second character string argument (called fname say) is required for the resultant file name (of size 129). A standard Windows 'file open' dialog is displayed and the resultant file is written to fname. The file is then displayed in a %eb edit box that is included in the current format window, replacing any text already there. This standard call-back must only be used in a format window containing one and only one %eb edit box. The corresponding edit box is usually supplied with a buffer length of zero when it is set up, so that the system allocates the buffer and adjusts its size as necessary.

    An example program appears in A simple text editor.

    See also

    EDIT_FILE, EDIT_FILE_SAVE


EDIT_FILE_SAVE

EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • These call-back functions operate on a %eb edit box in same same manner as EDIT_FILE_OPEN. If an edit box has not been filled using EDIT_FILE_OPEN, EDIT_FILE_SAVE operates like EDIT_FILE_SAVE_AS and displays the standard 'file save' dialog. Each call-back takes two character string arguments: one for the file pattern and the other for the resultant file name (see EDIT_FILE_OPEN above). The contents of the edit box are written to the file but the edit box is not closed.

    An example program appears in A simple text editor.


EDIT_UNDO

The EDIT_UNDO callback performs one undo operation on a %re or %eb control.


EXIT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This closes the window. If a window closure call-back (%cc) has been specified, the %cc call-back is called before the closure takes place.

    See also

    CONFIRM_EXIT


DEC

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This takes one INTEGER variable as an argument and subtracts 1 from the variable each time DEC is called. Any controls that use this variable are automatically updated.


FATAL

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The FATAL call-back terminates the program at once without performing any of the normal cleanup activities. Typically this is attached to the OK button in a window that displays a fatal error condition. Use this only if the program is likely to be corrupt and where performing a normal cleanup might hang the system.


FILE_OPENR

FILE_OPENR[caption]

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • FILE_OPENR is used to display the standard Windows 'file open' dialog. It takes a character string argument which is a buffer to receive the file name selected by the user from the dialog. Initially this buffer must be preset to be either blank or have the form '*.abc' otherwise the behaviour of FILE_OPENR is indeterminate. A call-back function should follow the buffer in the argument list. This call-back is called if the user selects a file (as opposed to pressing cancel, etc.).

    For example:

    EXTERNAL cb
    INTEGER cb
    CHARACTER*129 str_file
    str_file=' '
    i=winio@('%^bt[Open file]', 'FILE_OPENR[Open]', str_file, cb)

    The value returned to the calling winio@ is the return value of this call-back function, or 1 if no file is selected (so that the underlying window is kept open). By default (if the file name string is initially blank) the file selection box starts by displaying all files from the current directory. However, this and several other default actions of FILE_OPENR can be modified by the prior use of the %fs and %ft formats or by setting the file name string to the form '*.abc' before the call. For an example of the use of the FILE_OPENR and "+" call-back functions see the description of the %aw format in Attach window. See also %fs and %ft in File selection and filter.


FILE_OPENW

FILE_OPENW[caption]

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • FILE_OPENW is analogous to FILE_OPENR but allows the user to type in a new file name, since it is assumed that the file is required for writing.


GPRINTER_OPEN

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • GPRINTER_OPEN is used to produce output on a graphics printer or plotter. It operates in a manner similar to PRINTER_OPEN. However, GPRINTER_OPEN takes only one argument which is a call-back function supplied in the program. This call-back function will use drawing surface routines to produce the graphics output (see Graphics).

    Note that graphics printing and plotting can also be carried out using OPRN_PRINTER@.

    See also

    PRINTER_OPEN, PRINTER_OPEN1, Selecting a printer


HELP_CONTENTS

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • HELP_CONTENTS takes one character string argument giving the full path name of a help file (.HLP or .CHM). The file is opened at its contents page. When the main window closes, the help window will also be closed if it has been left open.


HELP_ON_HELP

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • HELP_ON_HELP provides the standard help-on-help information. This also takes a character string argument giving the name of a help file.


HELP_LOOKUP

HELP_LOOKUP and HELPLOOKUP

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • HELP_LOOKUP takes two character string arguments giving the full path name of a help file (.CHM) followed by the keyword that identifies the topic to display. The keyword must appear in the (.HHK) keyword file of the Microsoft project used to build the .CHM help file. When the main window closes, the help window will also be closed if it has been left open.

    In this context the Fortran the character variable for HELP_LOOKUP and the second keyword argument must be null terminated, for example by concatenating with char(0). An alternative callback called HELPLOOKUP does not require a terminating null. It also takes a snapshot of the keyword so that, when used in a menu item, the keyword is defined at the point where the menu is created.

    Keywords containing spaces must be enclosed in quotation marks. Literal strings can use double quotes within a single quoted string.


HTML_PRINTER_OPEN

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • HTML_PRINTER_OPEN provides for the output of text with embedded HTML markups. See Selecting a printer for further details.


INC

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • INC takes one INTEGER variable as an argument and adds 1 to this variable each time INC is called. Any controls that use this variable are automatically updated.


INTERNET_HYPERLINK

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • INTERNET_HYPERLINK takes one CHARACTER string argument which is the full URL of a file on the web. For example:

    i=winio@('%^bt[Silverfrost]','INTERNET_HYPERLINK','https://www.silverfrost.com')

    See also USE_URL@.


MINIMISE, MAXIMISE and RESTORE

In this section:

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • These three callbacks minimise, maximise or restore the current window.


PRINT_ABORT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • PRINT_ABORT is used to cancel a print job whilst it is being spooled.


PRINTER_OPEN

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • PRINTER_OPEN displays the standard Windows 'Print' dialog that enables the user to select a printer. The function takes two arguments. The first is an integer that is the Fortran unit number on which to open the printer. The second argument is a call-back function supplied in the program. If the printer is successfully selected, the call-back function is called. (The value returned by the call-back becomes the value returned by the enclosing winio@. Hence, a return value of 1, for example, has the effect of keeping the parent window open). If no printer is selected, PRINTER_OPEN returns 1 to keep the window open. The call-back function should perform print operations using standard Fortran output statements (for example, WRITE) on the specified unit number. It is necessary to CLOSE the unit number in order to dispatch the output to the printer.

    See also

    PRINTER_OPEN1, GPRINTER_OPEN, Selecting a printer


PRINTER_OPEN1

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • PRINTER_OPEN1 has the same purpose and takes the same arguments as PRINTER_OPEN but does not display the standard Windows 'Print' dialog. Instead it uses the default printer or the printer that was selected in an ealier call to PRINTER_OPEN.

    See also

    PRINTER_OPEN, GPRINTER_OPEN, Selecting a printer


PRINTER_SELECT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • PRINTER_SELECT displays the standard Windows 'Print' dialog and is used in conjunction with the standard call-back PRINTER_OPEN1 or the routine OPEN_PRINTER1@.


PRINTER_SETUP

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • PRINTER_SETUP displays the standard Windows 'Print' dialog in setup mode and is used in conjunction with the standard call-back PRINTER_OPEN1 or the routine OPEN_PRINTER1@.


SELECT_ALL

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • SELECT_ALL has no arguments and selects all of the text in the current %eb edit box.


SET

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The SET call-back takes two arguments each of type INTEGER. When the call-back is called, the first argument is set to the value of the second at the time when winio@ is called. SET returns the value 1 so that any necessary updates take place. Here is an example.

    WINAPP
    INTEGER v,w,winio@,x,ctrl
    v=0
    x=1
    w=winio@('%`cn%^tt[Set]&','SET',v,x)
    w=winio@('%2nl%4rd&',v)
    w=winio@('%lw',ctrl)
    x=2
    END

    The variable v is initially zero and takes the value 1 (rather than 2) when the button is clicked. The SETF callback performs the same operation on floating-point numbers.


SETF

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The SETF call-back takes two arguments each of double precision type. When the call-back is called, the first argument is set to the value of the second at the time when winio@ is called. SETF returns the value 1 so that any necessary updates take place. Here is an example.

    WINAPP
INTEGER w,winio@,ctrl
DOUBLE PRECISON v,x
                v=0d0
x=1d0
w=winio@('%`cn%^tt[SetF]&','SETF',v,x)
w=winio@('%2nl%4rf&',v)
w=winio@('%lw',ctrl)
x=2
END

    The variable v is initially zero and takes the value 1 (rather than 2) when the button is clicked. The SET callback performs the same operation on integers.


SOUND

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • If you require a sound that is not one of the standard system sounds (see BEEP above) and a sound card is installed, you can include small sound samples previously stored in standard wave file format (.WAV). The wave file must be included in a resource script or in the resource section of the program. For example:

    MySound SOUND dognoise.wav

    The following code illustrates how the sample is played back.

    i=winio@('%^bt[Bark]', 'SOUND', 'MySound')


STOP call-back

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • This call-back function closes the window and terminates the program.


SUPER_MAXIMISE

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The SUPER_MAXIMISE (the spelling SUPER_MAXIMIZE is also accepted) call-back is used to expand a window so that only the client area is visible. This is useful to enable a graphic display to be shown on the entire screen. Programs that use this call-back should provide an accelerator key or other means to exit from this mode (there will be no standard or system menu visible).


TEXT

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The TEXT call-back can only be invoked from a format window that uses %ht. It provides a quick way of displaying text in a window. The text itself is provided in a character string that is placed in the winio@ argument list after this call-back.


TEXT_HISTORY

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The TEXT_HISTORY call-back can only be invoked from a format window that includes %ht. A dialog box is displayed that shows the hypertext history and allows the user to select an earlier topic.


TOGGLE

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The TOGGLE call-back is used to toggle an INTEGER variable between 0 and 1. The variable follows the call-back in the winio@ argument list.


TILE_HORIZONTALLY

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • If this function is invoked from a window containing a MDI frame (%fr). The child windows created with %aw are tiled horizontally across the MDI frame.


TILE_VERTICALLY

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • If this function is invoked from a window containing a MDI frame (%fr). The child windows created with %aw are tiled vertically down the MDI frame.


+

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • Sometimes it is useful to invoke more than one call-back function at once. The "+" call-back function takes two subsequent call-back functions as arguments and calls each in turn. The return value from the "+" call-back function is the return from the second call. For an example of the use of the "+" and FILE_OPENR call-back functions see the description of %aw in Attach window. Note that the result of clearwin_string@('CALLBACK_REASON') reflects the original reason for the call-back and not "+".


A simple text editor

In this section:
  • ClearWin+ call-back functions
  • ABOUT
  • BEEP[sound option]
  • CASCADE
  • CONFIRM_EXIT
  • COPY, CUT, PASTE
  • COPY_TEXT
  • CONTINUE
  • EDIT_FILE_OPEN
  • EDIT_FILE
  • EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS
  • EDIT_UNDO
  • EXIT
  • DEC
  • FATAL
  • FILE_OPENR[caption]
  • FILE_OPENW[caption]
  • GPRINTER_OPEN
  • HELP_CONTENTS
  • HELP_ON_HELP
  • HELP_LOOKUP
  • HTML_PRINTER_OPEN
  • INC
  • INTERNET_HYPERLINK
  • MINIMISE, MAXIMISE & RESTORE
  • PRINT_ABORT
  • PRINTER_OPEN
  • PRINTER_OPEN1
  • PRINTER_SELECT
  • PRINTER_SETUP
  • SELECT_ALL
  • SET
  • SETF
  • SOUND
  • STOP
  • SUPER_MAXIMISE
  • TEXT
  • TEXT_HISTORY
  • TILE_HORIZONTALLY
  • TILE_VERTICALLY
  • TOGGLE
  • +
  • A simple text editor

    • The following example uses a number of the above call-back functions. It implements a simple editor.

    WINAPP
    INTEGER i,winio@
    CHARACTER*129 file,new_file,help_file
    help_file='myhelp.hlp'
    i=winio@('%mn[&File[&Open]]&','EDIT_FILE_OPEN','*.*',file)
    i=winio@('%mn[[&Save]]&', 'EDIT_FILE_SAVE','*.*',new_file)
    i=winio@('%mn[[Save &As]]&',EDIT_FILE_SAVE_AS','*.*',new_file)
    i=winio@('%mn[[E&xit]]&', 'EXIT')
    i=winio@('%mn[&Edit[&Copy]]&','COPY')
    i=winio@('%mn[[Cu&t]]&', 'CUT')
    i=winio@('%mn[[&Paste]]&', 'PASTE')
    i=winio@('%mn[&Help[&Contents]]&','HELP_CONTENTS',help_file)
    i=winio@('%mn[[&Help on help]]&', 'HELP_ON_HELP', help_file)
    i=winio@('%60.20eb','*',0)
    END


Format code reference

This section provides a detailed reference to format codes that can be used with winio@. New features are continuously being added to ClearWin+, details of which can be found in the enhancements files on the distribution disks.

An introduction to format windows and the winio@ function is presented in Window formats. It includes general information about format strings and the form of a format code; about format modifiers, option lists, standard character strings, and help strings. It also describes the general order in which components appear in the format string and in the winio@ argument list. Please note that lowercase n and m are used to represent optional size modifiers, whilst uppercase N and M denote mandatory size modifiers (e.g. %br).


%ac

Purpose | To define an accelerator key.
Syntax | winio@('%ac[key_description]',cb_func) external cb_func
Description | key_description is a standard character string (can be replaced by @ and a winio@ argument) that may include key words of the form: Ctrl, Shift, Alt, Esc, Del, Enter, Left, Right, Up, Down, PgUp, PgDn, Tab, Home, End, F1 etc.. Character keys must be combined with one or more of Ctrl, Shift and Alt, but Ctrl+Alt+character is reserved for use by the system.
Example | winio@('%ac[Ctrl+Shift+Del]',cb_func)
See also | %mn, add_accelerator@


%ap

Purpose

To set the absolute position of the next control.

Syntax

winio@('%ap', ix, iy)
integer ix,iy(input)
winio@('%`ap',rx, ry)
double precision rx,ry (input)

Modifiers

Grave accent (`) - use DOUBLE PRECISION real rather than INTEGER input.

Description

The units of measurement corresponds to the average width and the height of the default font. Use with care as this format overrides the normal mechanism to prevent controls overlapping.

Example

winio@('%ap', 2L, 6L)

See also

%rp, %gd, %ob, %nl, %ff, %dy


%aw

Purpose

To attach a MDI child to a parent window.

Syntax

winio@('%aw', ctrl)
integer ctrl (input)

Description

Used in conjuction a frame (%fr). ctrl is a variable associated with %lw or %cv in the frame. %aw can be used with %pv.

Notes

a) The system menu will contain Ctrl-F4 to close a child window (as opposed to the parent window), and Ctrl-F6 to move to the next MDI child.

b) As additional children are added to a frame these windows are offset with respect to the origin to make all windows visible. This offset is not reset to zero when all the children in a frame are closed.

c) If the standard call-back function 'CASCADE' is invoked from a window containing a MDI frame, this will cascade the child windows with the active window left at the top.

Example

See Attach window.

See also

%fr, %lw, %cv, %pv


%bb

%bb replicates the syntax of %bt but has certain advantages.

1. %bt does not always respond to the application of an XP theme when a manifest is used (or when this is the default) so it can appear to be out-dated. For example, this is the case when an icon is used with %bt or the background colour is changed from the default.

2. %bb is simpler to use when an icon is added and, unlike %bt, icons are not limited to the size 32x32.

The only limitation of %bb when compared with %bt is that it will not accept multi-line text.

%bb[MY_ICON/Button text] provides a button that displays the icon resource MY_ICON followed by the text "Button text". %bb[MY_ICON//Button text] is the same but the icon will not be greyed when the button is disabled.

Like %bt, %bb can be used with %bi, %bc, %bu, %`bc, and %`bu. It can also take an accelerator key on a character prefixed by an ampersand and can take an integer (e.g. %6bb[OK]) in order to set the width of the text. You can use %bb with or without an icon or with an empty text part.


%bc

Purpose

To specify the background colour of the next %bt or %bb button.

Syntax

winio@('%bc[colour]')
winio@('%bc', colour_value)
integer colour_value (input)

Modifiers

Grave accent (`) - allows colour_value to be changed dynamically.

Description

colour is one of: black, white, grey, red, green, blue, and yellow. Alternatively one of the additional named colours listed for %bg can be used.

colour_value is typically a value returned by RGB@. If the grave accent is used, this value can be changed after the button has been displayed. colour_value is then passed to WINDOW_UPDATE@ in order to update the screen.

%bu is similar to %bc but is used to specify the foreground (text) colour.

Example

winio@('%bc', RGB@(120,120,0))
winio@('%bc[white]')

See also

%bt, %tt, %bg


%bd

Purpose | To specify all four window borders individually.
Syntax | winio@('%bd', left, top, right, bottom) double precision left,top,right,bottom (input)
Description | The units of measurement correspond to the average width and the height of the default font. The exact size of each border can be set using this format. A negative value leaves the corresponding border unchanged.


%bf

Purpose | To switch to bold font.
Syntax | winio@('%bf')
Modifiers | Grave accent (`) - use the grave to switch off.
Description | %bf is cancelled by %`bf, %fn and %sf.
See also | %it, %ul, %sf


%bg

Purpose

Background colour format.

Syntax

winio@('%bg[colour]')
winio@('%bg', colour_value)
integer colour_value (input)

Modifiers

Grave accent (`) - set the colour of the next control.
Tilde (~) - set the colour of an %ob.

Description

colour is one of: black, white, grey, red, green, blue, and yellow. Alternatively one of the following additional named system colours can be used: scrollbar, background, activecaption, inactivecaption, menu, window (use this for the default window background), windowframe, menutext, windowtext, captiontext, activeborder, inactiveborder (use this for dialog box backgrounds), appworkspace (use this for the MDI backdrop), highlight (use this when you are adding your own draw focus), highlighttext, btnface, btnshadow, greytext, btntext, inactivecaptiontext, and btnhighlight. The definition of these colours depends on the user's desktop configuration (if you require the actual value for an RGB colour, use the API function GetSysColor with the named colour parameters defined the file windows.ins; e.g. COLOR_BTNFACE).

colour_value is typically a value returned by RGB@.

Use without the grave modifier to set the background colour of the main window. Use with the grave modifier to set the background colour of the next control (e.g. %rd, %rf, %rs, %ls, but not %bt).

Use with the tilde modifier within a %ob cell in order to set its background colour. When used with (say) %sy[no_border] and %1.2ob, it can be used to produce a split window with different background colours

Example

winio@('%bg', RGB@(120,120,0))
winio@('%bg[white]')
winio@('%bg[btnface]') !the default button face colour.

See also

%bc, %wp


%bh

Purpose | To provide a bubble help system.
Syntax | winio@('%bh',ctrl) integer ctrl (input)
Modifiers | Grave accent (`) - introduces a delay before the message appears.
Description | Set ctrl to 1 in order to enable help messages and to 0 in order to disable messages.
See also | %he, %th


%bi

Purpose | To supply an icon for the next %bt or %bb button.
Syntax | winio@('%bi[icon_name]')
Description | icon_name is a standard character string (can be replaced by @) that provides a name appearing in a resource script.
Notes | icon_name can constructed from a known Windows handle (see Using the handle of a resource).
Example | winio@('%bi[myicon]') myicon ICON file.ico (resource file)
See also | %ic


%bk

Purpose | To allow a right mouse click to be used on the next %bt button.
Syntax | winio@('%bk')
Description | %bk can be used before %^bt with the result that the associated call-back function is also called with a right mouse click. To differentiate between right and left mouse button clicks use CLEARWIN_STRING@('CALLBACK_REASON').


%bm

Purpose

To draw a bitmap.

Syntax

winio@('%bm[bitmap_name]')
winio@('%`bm', handle)
integer(7) handle (input)

Modifiers

Grave accent (`) - use a Windows API bitmap handle.

Caret (^) - the call-back is called when the user clicks on the bitmap.

Question mark (?) - a help string is supplied.

Description

bitmap_name is standard character string (can be replaced by the @ symbol) giving the name appearing in a resource script.

handle is a value returned by a modified form of the API function LoadBitmap.

bitmap_namecan also take the form of an integer handle surrounded by curly brackets or the name of an external file surrounded by curly brackets.

%`bm[static] gives a "static" image rather than a control that can have a callback function. The image can be supplied as an argument that has the value returned by a call to LoadResource@.

Example

winio@('%bm[mybitmap]')
mybitmap BITMAP file.bmp (resource file)

See also

%ic,%gi,%im


%bn

Purpose

A split button.

Syntax

winio@('%nbn[button_options]')
winio@('%~nbn[button_options]', grey_ctrl)
integer grey_ctrl (input)

Modifiers

Tilde (~) - used to add a grey control.

Grave accent (`) - used to make this the default button (one for each dialog).

Caret (^) - the call-back function is called when the user clicks on the button.

Question mark (?) - a help string is supplied.

Description

%bn is an alternative to %bt and %bb. In particular %bn can be used to present split buttons (with a down icon that is typically used for menus). It can also have the Microsoft "Notes" style of button with a green arrow, title and notes. %bn takes the same modifiers as %bt and its width can be modified in the same way via a leading integer value. Here are the options that can be used with %bn.

[text=Caption] | The caption for the button. "text=" can be omitted if this is the first option in a list.
[icon=IconResource] | The name of an icon resource to provide an icon (possibly with the "notes" style below).
[notes=Notes] | Provides a green arrow (or your icon). The caption appears as a title with the text "Notes" below it.
[split] | A split button normally linked to a prior %cm menu.
[font=FontName] | The font name.
[font_size=d] | The font size d which is a double precision value as in %ts.
[vfill=d] | A double precision value d that allows for additional vertical fill to provide greater depth.
[colour=rgbValue] | The text colour. Cannot be used with [icon] or [notes].
[bk_colour=rgbValue] | The background colour. Cannot be used with [icon] or [notes].
[return=v] | An integer value that can be used as the winio@ return when a button is used (without a callback) in order to close a window.

See also

%bx


%br

Purpose

To draw a horizontal or vertical bar which is partially filled with a user-selected colour.

Syntax

winio@('%Nbr[options]', fill, colour_value)
double precision fill (input)
integer colour_value (input)

Modifiers

Question mark (?) - a help string is supplied.

Description

fill specifies the amount of fill in the range 0 to 1 inclusive.

colour_value is the RGB value of the fill colour.

N is a integer constant giving the length of the bar in average characters.

options may include no_border and percentage, and one of left_right, right_left, top_bottom, bottom_top. percentage adds a progress indicator (in the form of a percentage) to a horizontal bar only.

[panel=val] has been added to attach the bar to a %sb panel. val is the integer value of a %sb panel. The progress bar is given [ms_style] attribute and appears in the given panel of the status bar.

Example

winio@('%15br[bottom_top]', fill, RGB@(200,200,0))

See also

%sl


%bt

Purpose

To insert a standard button.

Syntax

winio@('%nbt[button_text]')
winio@('%~nbt[button_text]', grey_ctrl)
integer grey_ctrl (input)

Modifiers

Tilde (~) - used to add a grey control.

Grave accent (`) - used to make this the default button (one for each dialog).

Caret (^) - the call-back function is called when the user clicks on the button.

Question mark (?) - a help string is supplied.

Description

n is an optional positive integer which is used to specify the width of the button.

grey_ctrl is set to 1 to enable the button and 0 to disable (grey) it.

button_text is a standard character string (can be replaced by @) and can include an ampersand (&) to mark an accelerator key. To change the text dynamically use %lc and CHANGE_BUTTON_TEXT@.

The background colour can be specified using %bc and the text font and size can be specified using %fn and %ts. Other effects can be obtained by using %lc.

Example

winio@('%`?~^10bt[OK][Click when done]', grey, cb_func)

See also

%tt, %bc, %bi, %ts, %fn, %lc, %bn


%bu

Purpose

To specify the text colour of the next %bt or %bb button.

Syntax

winio@('%bu[colour]')
winio@('%bu', colour_value)
integer colour_value (input)

Modifiers

Grave accent (`) - allows colour_value to be changed dynamically.

Description

colour is one of: black, white, grey, red, green, blue, and yellow. Alternatively one of the additional named colours listed for %bg can be used.

colour_value is typically a value returned by RGB@. If the grave accent is used, this value can be changed after the button has been displayed. colour_value is then passed to window_update@ in order to update the screen.

%bc is similar to %bu but is used to specify the background colour.

Example

winio@('%bu', RGB@(120,120,0))
winio@('%bu[white]')

See also

%bc


%bv

Purpose

To insert a hierarchical tree.

Syntax

winio@('%bv[options]',width,height,items,num_items,sel )
winio@('%`bv[options]',width,height,items,num_items,sel,bmp_str )
character(*) items(num_items ) (input/output)
integer num_items (input parameter)
integer sel (input/output)
integer width,height (input)
CHARACTER(*) bmp_str (input)

Modifiers

Grave accent (`) - used to provide a list of bitmaps.

Caret (^) - call-back function is provided.

Question mark (?) - a help string is supplied.

Description

%bv (branch view) provides a tree view that is similar in some respects to %tv but the %bv control has a different appearance and %bv has more options. It also shares common features with %lv.

width and height provide the dimensions of the control in pixels.

num_items is an integer constant giving the number of nodes in the tree. Nodes with blank data are not displayed in the control. This means that the number of nodes that are displayed can be changed under program control.

items is an array of num_items character strings, each string describing a node in turn (see the example below).

sel is an integer that provides the index of the node that is currently selected.

If a grave accent is provided, bmp_str is a character string giving a list of 16x16 bitmap resources in the form 'bmp1,bmp2'. If a bitmap has a one-pixel border of a certain colour, then this colour is used as a mask for the bitmap. Pixels with the mask colour are replaced by the background colour. The default mask is white.

%bv can take a pivot (%pv). Also the right mouse button can be used to trigger a popup menu (%pm) defined in the parent window. The background colour for %bv is white and at the moment this cannot be changed.

Example

CHARACTER*80 items(4)
INTEGER sel
items(1)='AEBBook'
items(2)='BCAChapter 1'
items(3)='CCASection 1.1'
items(4)='CCASection 1.2'
sel=1
i=winio@('%`bv',200,200,items,4,sel,'bmp1,bmp2')

As for %tv, the first character in each string provides the index for the level of the node. The second character marks the node as either expanded (E) or collapsed (C). The third character is only required if a list of bitmaps is provided and gives the index to select a bitmap from the list.

Options

edit_labels | Allows the text for a node to be edited.
show_selection_always | Always show the selection, if any, even if the control does not have the focus.
no_border | Displays the control without a border.
has_lines | The tree is displayed with nodes joined by lines.
lines_at_root | The root node also has a line to its left. Use this with has_buttons if you need buttons at the first level.
has_buttons | +/- expansion buttons are displayed.
paired_bitmaps | 'Expanded'/'collapsed' bitmaps are paired in the list.
sort | Sorts all levels of the tree into dictionary order.
use_icons | Forces the use of icons rather than bitmaps.
4bits | Icons have 16 colours. The default is 256 colours (8-bit colour).
24bits | 24-bit colour icons.
mouse_click | Adds the CALLBACK_REASON callled "MOUSE_CLICK" for a single mouse click.

Label editing

edit_labels enables label editing and requires a call-back function that can test for the call-back reasons 'BEGIN_EDIT', 'END_EDIT' and 'EDIT_KEY_DOWN'.

With BEGIN_EDIT you can get the index of the selected node by the call clearwin_info@('ROW_NUMBER'). If the call-back function returns the value 4 then editing of this node is prevented.

With EDIT_KEY_DOWN you can validate each character as it is typed. Use clearwin_info@('KEYBOARD_KEY') to get the key and/or clearwin_string@('EDITED_TEXT') to get the resulting string with the character inserted. If the call-back function returns the value 4 then the character is not accepted. If you want to translate the input key to another key then the call-back function must return the ASCII character code (31<code<256) of the translated key.

With END_EDIT you can get the result of the edit by the call clearwin_string@('EDITED_TEXT'). If the call-back function returns the value 4 then the new label is rejected the original label is restored. Otherwise, unlike %lv, the edit is accepted and your data is automatically updated. You cannot delete a node by accepting a blank entry.

Expanding a node

When a node is expanded or collapsed, the call-back function is called with the reason 'ITEM_EXPANDED'. You can respond to this (as for %tv) by changing the bitmap index and calling window_update@(items). However, it is simpler and much faster if you use the option paired_bitmaps. If you provide this option, each 'expanded' bitmap must follow immediately after the corresponding 'collapsed' bitmap in the list. Also the bitmap change is automatically done for you and your data is automatically modified to reflect the change. You can save and restore the data if you want to reload the control with the same expanded state.

Call-back reasons

ITEM_EXPANDED | A node has been expanded or collapsed (see above).
BEGIN_DRAG | An item is being dragged.
BEGIN_EDIT | A label is about to be edited (see above).
DROP_TARGET | As an item is dragged across the control different items become the target of the drag. CLEARWIN_INFO@('ROW_NUMBER') identifies the new target. This will change as the mouse moves.
EDIT_KEY_DOWN | The user has pressed a keyboard key during a label edit. clearwin_info@('KEYBOARD_KEY') provides the key code (see above).
END_DRAG | An item has been dragged.
END_EDIT | A label has been edited (see above).
SET_SELECTION | A node has been selected. clearwin_info@('ROW_NUMBER') provides the index.
MOUSE_DOUBLE_CLICK | The user has double-clicked using the left mouse button. clearwin_info@('ROW_NUMBER') provides the index.
KEY_DOWN | The user has pressed a keyboard key. clearwin_info@('KEYBOARD_KEY') provides the key code.
MOUSE_CLICK | The user has single-clicked using the left mouse button (requires the option [mouse_click]).

Example

See Branch-view.

See also

%tv, %ls, %ms, %pb, %ps.


%bx

Purpose

To add a raised grey bar to a tool bar.

Syntax

winio@('%bx', depth)
double precision depth (input)

Description

%bx is used, particularly after %tt, %ib or %tb, in order to provide a grey toolbar at the top of the window. depth is measured as a fraction of the character height and this amount is added to the height, one half above and one half below the buttons.

%bx can only be used once in any window. Its use is not restricted to %tt and %tb. %bx creates a grey background from the point where it is used to the top of the window. It automatically removes the border (as in %ww[no_border]) and the grey background spans the width of the window.

See also

%ib, %tb, %tt, %ln


%ca

Purpose

To provide a caption for the window or property sheet.

Syntax

winio@('%ca[caption]')

Modifiers

Grave accent (`) - when used, the minimum width of the window is not limited by the width of the caption and part of the caption may be hidden.

Description

caption is a standard character string (can be replaced by @).

In order to change the caption dynamically use the @ symbol and follow a change in the string variable by a call to window_update@. Alternatively use the API function SetWindowText together with %hw.

When used with %sh in a property sheet, the caption can include an ampersand (&) to mark an accelerator key.

%mi can be used to set the associated icon.

Example

winio@('%ca[Edit Window]')

See also

%sh, %mi


%cb

Purpose | To close a box that has been opened using %ob.
Syntax | winio@('%cb')
See also | %ob


%cc

Purpose | To control the closure of a window.
Syntax | winio@('%cc',cb_func) external cb_func
Modifiers | Grave accent (`) - the call-back is called after the window has closed rather than before..
Description | Provides a link to a call-back function by which the user controls the action to be taken just before a window is closed. If a grave is used (%`cc) then the associated call-back function is called immediately after the window is closed. You can use both %cc and %`cc in one window. The call-back function should return zero to allow the closing to continue. Other return values will halt the close down.
See also | %lw, %ew


%ch

Purpose

Child window format - inserts a child window.

Syntax

winio@('%ch[options]',ctrl)
integer ctrl (input)

Description

ctrl is a variable used with %`lw. The options available are

hscrollbar | Display a horizontal scroll-bar
vscrollbar | Display a vertical scroll-bar
When scroll-bars are shown then the controls are presented in a sheet (%sh) followed by a main window that uses %ch with %sz to set the size. Use %ww[not_fixed_size] to provide a pivoting action to the main window.

Example

program main
integer ii, ctrl, wd, ht
!child window with controls...
ii=winio@("%sh&",ctrl)
!Add your controls here...
ii=winio@(" ")
!Main window to display child with vertical scroll bar...
wd = 280; ht = 150
ii=winio@("%sz&",wd,ht)
ii=winio@("%ch[vscrollbar]",ctrl)
end program

See also

%lw


%cl

Purpose

To display a colour palette.

Syntax

winio@('%cl[options]',colour_values)
integer colour_values(3) (output)

Description

Up to three values can be returned from the resulting dialog box, the first for the left mouse button, the next for the right button and the third for the middle button.

options may be one or more of:

b1 | Left mouse button only
b2 | Left and right buttons (the default)
b3 | Left, right and middle buttons
title1 | Title above button boxes
title2 | Title above palette
iconic | Transparent and inverse transparent selection

Example

winio@('%cl[b3,title2=Palette]',colour_values)


%cm

Purpose | To supply the a popup menu for the next control.
Syntax | winio@('%cm[menu_spec]', ...)
Modifiers | Question mark (?) - All the strings are placed in order at the end of the format description, one for each and every menu item that has a call-back function. Caret (^) - callback to control grey and check.
Description | It provides a popup menu for the next control in the winio@ list and is constructed in exactly the same way as %pm (which provides the default popup menu for the whole window). This provides a simpler alternative to %nw %pm. %cm can be used with %em. It does not take a grave accent.
Example | integer check,enable iw = winio@("%?cm[#~Exit][Click to exit]",check,enable,"EXIT")
Notes | Introduced with FTN95 8.20.
See also | %nw


%cn

Purpose | To centre text and controls in the window.
Syntax | winio@('%cn')
Modifiers | Grave accent (`) - extends the scope to the remainder of the window.
Description | %cn is principally used on text and buttons. It forces everything which follows it, up to the next new line or form-feed character, to be centred in the window. When used within a box (%ob) the centring applies within that box.
See also | %rj


%co

Purpose | To modify subsequent %rd, %rf, %rs, %re, %el boxes.
Syntax | winio@('%co[options]')
Description | options is a list containing one or more of:

check_on_focus_loss | Perform checks, calls the call-back, and updates the corresponding data item only when focus is transferred to another control. This is particularly valuable if numeric limits have been imposed by %il/%fl.
data_border | Put a border round data boxes (default).
full_check | Perform checks and call-back every change (default).
right_justify | Align the text to the right border. Not for %el.
left_justify | Align the text to the left border (default).
no_data_border | Omit border round data boxes. Not for %el.
warn_on_edit | *Changes the error icon for a user edit to a warning icon.
alert_on_update | *Changes from no icon to an error icon for a programmed update.
warn_on_update | *Implies [alert_on_update] and changes the error icon to a warning icon.
limit_on_update | *Implies [alert_on_update] and causes the associated variable to be corrected.
stet_on_update | *Implies [alert_on_update] but prevents the display from being corrected.

Options that are marked with an asterisk (*) provide alternatives to the default action for %~il and %~fl when an out-of-range value is either a) input by a user keyboard edit or b) provided by a programmed update to the associated variable (e.g. together with a call to window_update@).
The default action for a user edit is: error icon shown, display is not corrected, associated variable corrected.
The default action for a programmed update is: no icon is shown, display is corrected, associated variable is not corrected.

Example | winio@('%co[check_on_focus_loss]')
See also | %rd, %rf, %rs, %re, %el


%cu

Purpose

Establishes a cursor for the next control in a format.

Syntax

winio@('%cu[cursor_name]')
winio@('%`cu', const)
integer(7) const (input)
winio@('%Ncu[name1][name2] . . . [nameN]',sel)
winio@('%`Ncu', const1, const2, . . ., constN, sel)
integer sel, const1, const2, . . ., constN (input)

Modifiers

Grave accent (`) - cursor is specified by using a ClearWin+ parameter from windows.ins.

Description

cursor_name is a standard character string (can be replaced by @) that is used to identify a cursor via a resource script.

The alternative uses a grave accent modifier together with const which is one of:

CURSOR_ARROW | Standard arrow cursor
CURSOR_IBEAM | Text I-beam cursor
CURSOR_WAIT | Hourglass cursor
CURSOR_CROSS | Cross hair cursor
CURSOR_UPARROW | Vertical arrow cursor
CURSOR_SIZE | A square with a smaller square inside its lower-right corner
CURSOR_ICON | Empty icon
CURSOR_SIZENWSE | Double-pointed cursor with arrows pointing Northwest and Southeast
CURSOR_SIZENESW | Double-pointed cursor with arrows pointing Northeast and Southwest
CURSOR_SIZEWE | Double-pointed cursor with arrows pointing west and east
CURSOR_SIZENS | Double-pointed cursor with arrows pointing North and South

If const is not one of these values then it is assumed to be a valid Windows API handle of an existing cursor (cf. %bm and %ic).

Another pair of alternatives uses a positive integer N to provide a selection of N different cursors. In this case the variable sel is given a value in the range 1 .. N in order to specify a particular cursor. sel can also be set to zero in which case the cursor is hidden from view. A zero value is particularly useful when calling SET_GRAPHICS_SELECTION@.

The examples below illustrate the first pair of alternatives.

cursor_name can also take the form of an integer handle surrounded by curly brackets or the name of an external file surrounded by curly brackets.

Example

winio@('%cu[mycursor]')
mycursor CURSOR file.cur      (resource file)

winio@('%`cu',CURSOR_IBEAM)

See also

%dc, set_cursor_waiting@


%cv

Purpose | To set a control variable for a window.
Syntax | winio@('%cv',ctrl) integer ctrl (output)
Description | %cv has the same effect as %lw but does not leave the window open. The returned value of ctrl can be used with %aw.
See also | %aw, %lw


%cw

Purpose

To insert a ClearWin window.

Syntax

winio@('%N.Mcw[options]', fortran_unit)
winio@('%`N.Mcw[options]', fortran_unit, handle)
integer fortran_unit (input)
integer(7) handle (output)

Modifiers

Grave accent (`) - used to return a Microsoft handle for the window.

Question mark (?) - a help string is supplied.

Description

N is the width and M the depth of the window in average characters.

%cw can take a pivot (use %pv before %cw) in order to size the window at run time.

fortran_unit is the unit number of the input/output stream.

handle can be used with routines such as SET_MAX_LINES@.

If a caption, etc. is required (for example to make the window movable) the %cw format should be embedded in a child window which is itself embedded in the main window.

%cw is a read-only control that is used for output and in particular for debugging.

The standard call-back function COPY can be used in this context but the %cw control must have the focus when the command is issued. For this reason COPY should be attached to an accelerator key (%ac) or perhaps to a menu item.

options can be one or both of vscroll and hscroll in order to provide scroll bars. Also local_font is required if %cw is to adopted the current %fn and %ts.

See also

%uw


%dc

Purpose | Establishes a default cursor for the window.
Syntax | winio@('%dc[cursor_name]') winio@('%`dc', const) integer(7) const (input) winio@('%Ndc[name1][name2] . . .[nameN]',sel) winio@('%`Ndc', const1, const2, . . . , constN, sel) integer sel, const1, const2, . . . , constN (input)
Modifiers | Grave accent (`) - cursor is specified by using a ClearWin+ parameter from windows.ins.
Description | cursor_name is a standard character string (can be replaced by @) used to identify a cursor via a resource script. The alternative uses a grave accent modifier together with const which is one of:

CURSOR_ARROW | Standard arrow cursor
CURSOR_IBEAM | Text I-beam cursor
CURSOR_WAIT | Hourglass cursor
CURSOR_CROSS | Cross hair cursor
CURSOR_UPARROW | Vertical arrow cursor
CURSOR_SIZE | A square with a smaller square inside its lower-right corner
CURSOR_ICON | Empty icon
CURSOR_SIZENWSE | Double-pointed cursor with arrows pointing Northwest and Southeast
CURSOR_SIZENESW | Double-pointed cursor with arrows pointing Northeast and Southwest
CURSOR_SIZEWE | Double-pointed cursor with arrows pointing west and east
CURSOR_SIZENS | Double-pointed cursor with arrows pointing North and South

Another pair of alternatives uses a positive integer N to provide a selection of N different cursors. In this case the variable sel is given a value in the range 1 .. N in order to specify a particular cursor. It is not necessary to call WINDOW_UPDATE@ when sel is changed. The examples below illustrate the first pair of alternatives.

cursor_name can also take the form of an integer handle surrounded by curly brackets (integer kind=7) or the name of an external file surrounded by curly brackets.

Example

    winio@('%dc[mycursor]')
    mycursor CURSOR file.cur      (resource file)
    winio@('%`dc',CURSOR_IBEAM)

See also

%cu


%dd

Purpose

To insert a spin wheel for an integer edit box (%rd) or a string edit box (%rs).

Syntax

winio@('%dd', step)
integer step (input)

Description

%dd can be used with %rd in order to provide an attached spin wheel.

step is the size of the increase/decrease. The resulting %rd value will be a multiple of step. Any call-back function should be attached to %rd. %dd is placed before the %rd to which it refers.

%dd can also be used with %rs. In this case it should have a non-zero step value (which is ignored). The subsequent %rs box should have a call-back function which uses CLEARWIN_STRING@('CALLBACK_REASON') to identify the reasons 'SPIN_UP' and 'SPIN_DOWN'. The call-back function must provide the response to the spin (for example, by cycling through the days of the week).

The value of the step can be changed dynamically by using the function SET_INCREMENT@. This function returns the old value for the increment or zero on failure.

SUBROUTINE SET_INCREMENT@( HWND, STEP )
INTEGER(7) HWND
DOUBLE PRECISION STEP

hwnd is the Windows handle of the controls obtained using %lc.

Example

winio@('%dd', 1L)

See also

%rd, %il, %rs, %df


%de

Purpose | To disable some other window while this window is active.
Syntax | winio@('%de',hwnd) integer hwnd (input)
Description | %de is used to force some other window to be disabled while the current window is active. This is the default behaviour for other ClearWin+ windows unless %ww is used. This format is particularly useful in situations in which there are non ClearWin+ windows present.


%df

Purpose

To insert a spin wheel for a floating point value.

Syntax

winio@('%df', step)
double precision step (input)

Description

%df can be used with %rf in order to provide an attached spin wheel.

step is the size of the increase/decrease. The resulting %rf value will be a multiple of step. Any call-back function should be attached to %rf.

The value of the step can be changed dynamically by using the function SET_INCREMENT@. This function returns the old value for the increment or zero on failure.

SUBROUTINE SET_INCREMENT@( HWND, STEP )
INTEGER(7) HWND
DOUBLE PRECISION STEP

hwnd is the Windows handle of the controls obtained using %lc.

Example

winio@('%df', 1.0D0)

See also

%rf, %fl, %dd


%di

Purpose | To allow ClearWin+ to use dialog resources.
Syntax | winio@('%di', DIALOG_ID) INTEGER DIALOG_ID
Modifiers | Grave accent (`) - use the grave to switch off.
Description | %di allows the use of dialogs created with a dialog editor It takes one integer argument DIALOG_ID which should be the dialog identifier in the resource script.
See also | Using dialog resources


%dl

Purpose

To set a call-back function to be called at regular intervals via a timer.

Syntax

winio@('%dl',interval,cb_func)
double precision interval (input)
external cb_func

Description

interval is the minimum time in seconds between calls. A call is made at idle time (e.g. awaiting input) and when YIELD_PROGRAM_CONTROL@ is called. A given window can have more than one timer.

Notes

The timer delay used with %dl can be changed dynamically using the following routines.

SUBROUTINE CHANGE_TIMER_INTERVAL@( HWND, INTERVAL )
INTEGER(7) HWND
DOUBLE PRECISION INTERVAL

SUBROUTINE SET_TIMER@( HWND, INTERVAL, CALLBACK )
INTEGER(7) HWND
DOUBLE PRECISION INTERVAL
INTEGER,EXTERNAL::callback

SUBROUTINE KILL_TIMER@( HWND, CALLBACK )
INTEGER(7) HWND
DOUBLE PRECISION INTERVAL
INTEGER,EXTERNAL::callback

HWND is the handle of the parent window (obtained using %hw). INTERVAL is the replacement for the value used with %dl.

Example

winio@('%dl', 2.0D0, cb_func)


%dp

Purpose | To provide an integer parameter to a parameter block.
Syntax | winio@('%dp[Item Name]', CURRENT) INTEGER CURRENT
Modifiers | ? - provide help after first string
Description | %dp is designed to be used with %pb
See also | %pb, %ep, %fp, %tp, %up.


%dr

Purpose | To provide a call-back that is called when a file or a group of files is dragged and dropped onto the window.
Syntax | winio@('%dr',cb_func) external cb_func
Description | Use a call to CLEARWIN_STRING@('DROPPED_FILE') within the call-back in order to get the name of the file that has been dropped. If there is more than one file then the call-back function is called for each in turn. You can use CLEARWIN_INFO@('DROPPED_COUNT') to get the number of files that have been dropped (call this n say) and then use CLEARWIN_INFO@('DROPPED_CURRENT') to get the index of the current file in the range from 1 to n.
Notes | A negative or zero return value in the call-back function for %dr cannot be used in the normal way to close the parent window.
Example | See Drag and drop.
See also | %fs, %ft, GET_FILTERED_FILE@


%dw

Purpose | To insert an owner draw graphics box.
Syntax | winio@('%dw[options]', context) integer(7) context (input)
Modifiers | Caret (^) Question mark (?) - a help string is supplied.
Description | context is value returned by a call to GET_BITMAP_DC@. %dw will take a pivot (%pv). See Owner draw box format for further details.
See also | %gr


%dy

Purpose | To provide a vertical displacement by a non-integral number of character depth units.
Syntax | winio@('%dy',d) double precision d (input)
Description | %dy is used to force a vertical displacement by a possibly fractional number of character depths. The displacement is calculated in terms of the initial font size, regardless of any %ts formats that may have been used. The displacement can be negative, but unlike %rp, the normal mechanism will operate to prevent two controls overlapping, so %dy cannot be used to place a control over something else.
Notes | A value for d of 0.5D0 is equivalent to a half line feed. %dy has no effect when there is no space for the next item to move into.
See also | %ap, %rp


%eb

Purpose

To insert an edit box.

Syntax

winio@('%N.Meb[options]',buffer, buff_size)
winio@('%`N.Meb[options]',buffer, buff_size, edit_info)
character(*) buffer (input/output)
integer buff_size (input)
integer edit_info(24) (input/output)

Modifiers

Caret (^) - the call-back function is called when a key is pressed or the mouse is moved.

Question mark (?) - a help string is supplied.

Grave accent (`) - the program supplies edit information. The array name edit_info is placed in the argument list after any grey control variable and before any call-back function. This is an EDIT_INFO block which can be used to manipulate the edit box.

Tilde (~) - adds a variable that controls the grey (enable/disable) state. The variable should precede the call-back function (if any) in the argument list.

Description

An edit box created using %eb provides a wide range of advanced text editing features. See Edit box topics for details.

N represents the width of the box in average characters. M represents the depth which, if omitted, defaults to 1.

buffer is a character string for the text which must be terminated with chr(0).

buff_size is the size of the buffer. A zero value may be supplied to allow the edit box to allocate its own memory re-sizing as required (buffer is ignored).

%eb will take a pivot (%pv).

If the caret modifier (^) is used and the call-back function does not handle the response to control keys such as Delete, Backspace, etc., then it should return a zero value.

Routines such as OPEN_EDIT_FILE@ that take an EDIT_INFO block as their first argument can now alternatively use the Windows handle (HWND) of the control for this first argument. This handle is typically obtained by using %lc.

The following functions may be used with this enhanced control. These functions take an INTEGER(7) value HWND, typically obtained via %lc. If HWND is zero (0_7) then the control that has the current focus is used.

INTEGER FUNCTION GetEditText@(HWND, BUFFER, SIZE)
INTEGER(7) HWND
CHARACTER(*) BUFFER
INTEGER SIZE
 Gets the contents of the control. Returns zero if the HWND is not valid or the buffer is not large enough. SIZE is the size of the buffer. Edit controls are limited to a maximum of 32K characters.

INTEGER FUNCTION OpenEditFile@(HWND, FILENAME)
INTEGER(7) HWND
CHARACTER(*) FILENAME
 Opens and reads the text file into the control and associates the control with this FILENAME. Return zero if the HWND is not valid or the file cannot be opened and read. This function can be used in a callback associated with the "FILE_OPENR" standard callback and the %ft format code for file "filters".

INTEGER FUNCTION EditFileSave@(HWND)
INTEGER(7) HWND
 The function uses the file name associated with the control if it has one, otherwise it opens a standard "Open file" dialog and creates the file association. No action is taken if an association exists and the text has not changed. Returns zero if the HWND is not valid or the file cannot be saved. File "filters" can be provided via the %ft format code.

INTEGER FUNCTION EditFileSaveAs@(HWND)
INTEGER(7) HWND
 The function opens a standard "Open file" dialog to get a full path for a file and then saves it, creating a new file association for the control. Returns zero if the HWND is not valid or the file cannot be saved. File "filters" can be provided via the %ft format code.

INTEGER FUNCTION EditFileClosePrompt@(HWND, CAPTION, MESSAGE)
INTEGER(7) HWND
CHARACTER(*) CAPTION,MESSAGE
 Used when closing the control's window (e.g. within a %cc callback). If the text has changed since the last "save" operation then a dialog is presented prompting for a save before closing. The possible responses are Yes, No and Cancel. CAPTION is the title for the prompting dialog and MESSAGE is its message. If %s is used within this MESSAGE string then %s is replaced by the short name of the associated file if there is one. The function returns zero for "No" and one for "Yes" when the save is successful. This return value can be used directly as the return value of a %cc callback.

INTEGER FUNCTION EditFileModified@(HWND)
INTEGER(7) HWND
 Returns 1 if the text has been changed since the last save operation, otherwise it returns zero.

See also

%cc


%el

Purpose

To insert an editable combo box.

Syntax

winio@('%n.mel[option]',items,num_items,cur_item)
winio@('%~n.mel[option]',items,num_items,cur_item,grey_ctrl)
character*n items(num_items) (input)
integer num_items (input parameter)
character*n cur_item (input/output)
integer grey_ctrl (input)

Modifiers

Caret (^) - call-back function is called when the user selects an item.

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

%co[check_on_focus_loss] can be used with %el.

Description

This control is similar to %`ls but cur_item is a string for the current text rather than the index of the selected item.

If a call-back is supplied, option can be set to [extended]. The result is that the call-back is called when the list drops down or closes up. These events must be detected from the call-back by calling CLEARWIN_STRING@ with the argument 'CALLBACK_REASON' which returns 'DROPDOWN' or 'CLOSEUP'.

Using CLEARWIN_INFO@ with the argument 'EDITABLE_LISTBOX_INDEX' provides the index of the list-box item that has been selected by the user. If this value is obtained within the %el callback function then you may need to add the option %el[extended] in order to ensure that the callback function is called every time an item is selected.

The option [height=n] sets the pixel height of individual items to 'n' pixels. The default value is 16. An asterisk can be used and the value passed in the argument list.

See %ls for further details.

See also

%ls, %ms, %lv, %pb, %ps


%em

Purpose | To enable a window have enhanced menus.
Syntax | winio@('%em[options]')
Description | See New enhanced menus.
See also | %mn, %pm


%ep

Purpose | To provide an enumerated set of parameters to a parameter block.
Syntax | winio@('%ep[Item Name]', VALUES, N, CURRENT) CHARACTER*(*) VALUES INTEGER N, CURRENT
Modifiers | ? - provide help after first string
Description | %ep is designed to be used with %pb
See also | %pb, %dp, %fp, %tp, %up


%eq

Purpose

To insert a mathematical equation in a window.

Syntax

winio@('%eq[equation]', width, height)
integer width, height (input)

Modifiers

Grave accent (`) - avoids a fatal error condition when the equation is not correctly constructed.

Description

width and height provide the dimensions in pixels of a box enclosing the equation. If the equation is fixed, zero values can be supplied and the size will be automatically adjusted to fit the contents.

equation is a standard character string (can be replaced by @) that uses the standard character set except for the three characters {;} that are used to define special symbols. See Mathematical equation for further details.

Example

winio@('%eq[E=MC{sup 2}]',0L,0L)


%es

Purpose | To cause the window to close when the Escape key is pressed.
Syntax | winio@('%es')
Description | This is equivalent to winio@('%ac[Esc]','EXIT').
See also | %ac


%ew

Purpose

To specify a call-back function to be called if the user shuts down the Windows session (exit Windows) whilst the program is running.

Syntax

winio@('%ew',cb_func)
external cb_func

Description

The call-back function could be used to ask the user if results are to be saved before the session ends, etc.. If the call-back function returns zero, the shut-down is allowed to proceed. Any other value will abort the shut-down and leave the application running.

Note that if your program allows shut-down to proceed, other applications that are still running may still elect to abort the shut-down.

See also

%cc


%fb

Purpose | To select a font for use with all subsequent buttons.
Syntax | winio@('%fb')
Description | If %fn is used to select a font (optionally with %ts, %tc, %bf, %it and %ul) then following this by %fb (with no arguments) will cause the font to be remembered for use with all subsequent buttons unless and until %fb is used again.
See also | %fn


%fd

Purpose | To set the font to the default Windows 95 font (Windows 95/98 only).
Syntax | winio@('%fd')
Description | This will produce a Windows 95 font, but note that your users can change the size/appearance of this font using the display properties applet, so check your application with a range of settings to ensure that it displays well.
See also | %fn, %sf


%ff

Purpose | Form feed. To move down to below any existing controls.
Syntax | winio@('%ff')
See also | %nl, %ta, %ob


%fh

Purpose | To use a Windows API font.
Syntax | winio@('%fh',handle) integer(7) handle (input)
Description | handle is the font handle of a font created by, for example, the Windows API function CreateFont. %fh makes this the current font for the window.
See also | %fn


%fl

Purpose

To specify the lower and upper limits for subsequent %rf formats.

Syntax

winio@('%fl', lower, upper)
winio@('%`fl')
double precision lower, upper (input)

Modifiers

Grave accent (%`fl) - cancels an earlier %fl and restores the limits to the minimum and maximum for the data type.

Tilde (%~fl) - the limits are not applied to the displayed %rf integer value but (on error) an alert icon appears and the text colour changes to red. The associated %rf variable is the same as when not using the tilde (the value is set at the lower or upper limit).

Description

lower is the lower limit and upper is the upper limit.

Example

winio@('%fl', 0.0D0, 10.0D0)

See also

%rf, %df, %co[check_on_focus_loss], SET_FLOAT_LIMITS@


%fn

Purpose

To select a font for subsequent text.

Syntax

winio@('%fn[font_name]')

Description

font_name is a standard character string (can be replaced by @) that provides the name of a font that is in the user's system.

%fn cancels %bf but not %it and %ul.

Example

winio@('%fn[Times New Roman]')

See also

%sf, %ts, %bf, %it, %ul


%dp

%fp

Purpose | To provide an floating point parameter to a parameter block.
Syntax | winio@('%fp[Item Name]', CURRENT) DOUBLE PRECISION CURRENT
Modifiers | ? - provide help after first string
Description | %fp is designed to be used with %pb
See also | %pb, %dp, %ep, %tp, %up


%fr

Purpose | To define a MDI frame to contain child windows attached by %aw.
Syntax | winio@('%fr', width, height) winio@('%`fr', width, height, ctrl) integer width, height (input) integer(7) ctrl (output)
Modifiers | Caret (^) - call-back function is called when the topmost child window changes. Grave accent (`) - used to provide access to the handle of the current child window.
Description | width and height give the width and height of the frame in pixels. If %fr is preceded by %pv then the frame can be re-sized at run time. ctrl is returned as the handle of the currently selected child window (see %hw) or zero if none is selected. A given window cannot contain more than one frame.
Notes | The call-back function is called with the 'reason' MDI_PAGE_TURN (see CLEARWIN_STRING@) whenever the topmost child window changes. Typically this would be used in conjunction with the grave accent to get the handle of the topmost window in a variable.
Example | See Attach window.
See also | %aw, %hw, %pv


%fs

Purpose

To specify the working directory and file filter for subsequent file open/save call-backs.

Syntax

winio@('%fs[path_name]')

Description

path_name is a standard character string (can be replaced by @) giving the current working directory which optionally may include a wild-card. %fs cannot be used to change the path dynamically at run time (use get_filtered_file@ instead).

Example

winio@('%fs[c:\project\*.txt]')

See also

%ft, GET_FILTERED_FILE@, set_open_dialog_path@


%ft

Purpose

To specify filter information for subsequent file open call-backs.

Syntax

winio@('%ft[filter_type][wild_card]')

Modifiers

Grave accent (`) - used to start again rather than add to earlier %ft information.

Description

filter_type is the description of the type of file, wild_card represents the file extension of the files to be listed in the standard file-open and file-save dialog boxes. filter_type and wild_card are standard character strings (can be replaced by @) but %ft cannot be used to change this information dynamically at run time (use GET_FILTERED_FILE@ instead).

%ft can be used more than once to supply a number of different filters.

Example

winio@('%ft[Text files][*.txt]')

See also

%fs, GET_FILTERED_FILE@, SET_OPEN_DIALOG_PATH@


%ga

Purpose

To enable radio buttons and/or bitmap buttons to be ganged together so that if one is switched on, all the others are switched off.

Syntax

winio@('%Nga',state1, state2, . . , stateN)
integer state1, state2, . ., stateN (output)

Modifiers

Grave accent (`) - used to specify that one control is always on.

Tilde (~) - the list of "state controls" is replaced by a single array.

Description

N is a positive integer greater than 1. state1 . . stateN are the on/off state controls for radio buttons and/or bitmap buttons defined elsewhere. A given state variable can be used in more than one control (%rb and/or %tb). However, it is unusual for a variable to appear in more than one %ga format for a given window. If it does then there must only be one variable that is common and the effect is to merge the two gang sets. If the grave accent is used on one of the gangs then it must be used on both.

Example

winio@('%3ga',rb1, rb2, rb3)

See also

%rb, %tb


%gb

Purpose | A group box.
Syntax | winio@('%gb[title]', wd, ht ) integer wd, ht
Description | Provides a group box similar to a single %ob/%cb that is designed to work with %wi. 'wd' and 'ht' are the initial pre-design pixel width and height of the box. The %gb font, font size and font colour can be set in the usual way but a %`bg background colour will only be applied to the group title.
Notes | Added to FTN95 at version 8.20
See also | %wi


%gd

Purpose | To supply a temporary grid to help with the positioning of controls.
Syntax | winio@('%gd')
Description | The grid is placed at positions corresponding to the units in %ap.
See also | %ap


%gf

Purpose | To get the handle of a font.
Syntax | winio@('%gf',font_hdle) integer(7) font_hdle (output)
Description | font_hdle is returned as the handle of the current font. This handle can be used in calls to Windows API functions that need a font handle.


%gi

Purpose

To draw a (possibly animated/transparent) GIF image.

Syntax

winio@('%gi[gif_name]')

Modifiers

Caret (^) - the call-back is called when the user clicks on the image.

Question mark (?) - a help string is supplied.

Description

gif_name is a name appearing in a resource script if type GIF. The resource compiler stores such resources in a non-GIF format (for legal reasons). The GIF file can be animated and/or partially transparent.

A call-back can be supplied to receive single and double clicks. The call-back function can interrogate the CLEARWIN_INFO@ parameters GIF_MOUSE_X and GIF_MOUSE_Y to determine where within the image the click occurred. This means that a medium to large image can contain regions which respond in different ways to mouse clicks. Co-ordinates are in pixels relative to the top left of the image. Note that if the GIF image is displayed at another screen resolution, these pixel co-ordinates will consistently refer to the same point in the image.

Example

winio@('%gi[my_gif]')

my_gif GIF file.gif      (resource file)

Notes

A GIF file can contain more than one image frame, and each image can specify the duration for which it is shown. Animations can be one-shot, repeated for a finite number of times, or (most usefully) cycled indefinitely. Many image processing and paint tools will create simple (non-animated) GIF files, and these can be assembled into animated GIFs using a variety of tools, such as the Microsoft GIF Animator, available from the Microsoft Web site. GIF files are commonly available on the internet. MATHEMATICA can export graphics as GIF files.

A GIF image contains size information, so none is required with the format.

Hypertext (%ht) containing images normally refers to BITMAP resources. However, if a particular named resource is not found as a bitmap, ClearWin+ will look for the corresponding GIF resource. This means that GIFs (possibly animated/transparent) can also be used in hypertext.

Animations require memory and processing time, so it might be unwise to use a large and complex animation on a 'please wait' screen that is displayed while a lengthy operation is being performed. Obviously, slower animations are less expensive than rapid ones. Also, for the animation to be maintained, it is important that very lengthy calculations are broken up with calls to temporary_yield@.

One way to reduce the performance cost of many animations is to exploit the fact that much of an image may remain the same from frame to frame. Consider for example an animated ballot paper. It might be that only the region that contains the cross would actually need to change. It is possible to assemble a GIF consisting of one full image and a series of patches, which will obviously require less memory and processing resources than the corresponding set of full images. If you decide to proceed this way your program will remain unchanged, it will simply require more work with the image processing tools.

On 16 or 256 colour systems, GIF images are displayed without the use of a palette. This is to avoid some of the problems with Windows when two or more processes compete for the use of the palette. GIF images are best viewed in a high colour mode. If in doubt it is worth switching your screen to 256 colour mode to ensure that your graphic looks acceptable. You can read the CLEARWIN_INFO@ parameter, SCREEN_NUM_COLOURS do determine what to do at run time.

GIF images may be used to provide fancy buttons that attract attention because of their animation, to provide front cover screens for programs, and to add colour and interest. Larger images can even be used as image maps by reading the click co-ordinates, as explained above.

The GIF resources are decompressed by the resource compiler and recompressed by a different method. This means that your executables and the DLL salflibc.dll do not contain any code related to the processing of the GIF format. For this reason we have not supplied any routines to enable you to export graphics to GIF files. However, if you want to incorporate your graphics in animated GIFs this is still possible. Simply create a series of still images as BMP files, convert them to GIFs using a shareware image processing program, and assemble the result as an animated GIF.

See also

%ic,%bm


%gp

Purpose | To get the current co-ordinates of the window position.
Syntax | winio@('%gp', x, y) integer x, y (output)
Modifiers | Grave accent (`) - used only in conjunction with %aw in order to provide co-ordinates that are relative to an enclosing MDI frame.
Description | x and y are returned as the co-ordinates in pixels of the current position in the window relative to the top left-hand corner (0,0) of the window. These values can be used with %sp.
See also | %sp


%gr

Purpose

To provide a rectangular area for use with drawing surface routines.

Syntax

winio@('%gr[options]', width, height)
winio@('%`gr[options]', width, height, uid)
integer width, height, uid (input)

Modifiers

Grave accent (`) - used to input a user identifier for the graphics area.

Caret (^) - used to supply a call-back function.

Question mark (?) - a help string is supplied.

Description

width and height provide the pixel dimensions of the area. uid is a programmer-supplied identifier to distinguish between different graphics areas.

%gr can be preceded with %pv in order to re-size the area at run time. For more details about this very versatile feature you should see the section: Graphics Topics and drawing surfaces.
Options

BLACK, WHITE, RED, BLUE, YELLOW, GREY (or GRAY)

Specifies the initial background colour of the drawing surface. Otherwise this defaults to the background colour of the surrounding window.

COLOUR=#rrggbb

COLOR=#rrggbb

Specifies the intial background colour of the drawing surface where rr represents hexadecimal digits for the red component etc..

METAFILE_RESIZE USER_RESIZE

Options specifying the behaviour of the graphics area as it is re-sized. See later in this chapter.

RGB_COLOURS

Selects rgb colour mode. This is the default for ClearWin+ releases including and after FTN95 7.00.

VGA_COLOURS

Selects vga colour mode. This is the default for ClearWin+ releases before FTN95 7.00.

FULL_MOUSE_INPUT

Specifies that mouse movements and mouse button releases should be notified to the call-back function, not just clicks and double clicks.

POPUP

Used with FULL_MOUSE_INPUT in order to enable a %pm popup menu that is otherwise disabled.

BOX_SELECTION
LINE_SELECTION
FREE_SELECTION

Specifies the initial selection mode, that controls the behaviour when the user presses the left mouse button and drags the mouse over the graphics area. These options are useful for interactive programs.

USER_SURFACE

An option to enable software to access the in-memory copy of the graphics area so as to modify it at the highest possible speed. This option is particularly useful for image processing software.

FLUSH

Used with %sy 3d-styles to re-align the %gr border.
SMOOTH4 | Use high-resolution 8x4 box filter anti-aliasing
SMOOTH8 | Use 8x8 box filter box filter anti-aliasing
HSCROLL, VSCROLL

Adds scrolling options. Previously %vx and %hx could be used with %gr but provided scroll bars as separate controls. The new options create scroll bars that are built into the control and as a result have all of the expected "hot track" characteristics of a scroll bar.

%gr[hscroll] uses the same data as %hx whilst %gr[vscroll] uses the same data as %vx. This is accommodated by presenting %hx with its data before %gr[hscroll] and %vx with its data before %gr[vscroll]. The only restriction is that the %hx and %vx information must not include callback functions. For example:

integer iw,page,range,pos
integer,external::cb
iw = winio@("%vx&", page, range, pos)
iw = winio@("%^gr[vscroll]",400,300,cb)

The values used for 'page' and 'range' determine the y offset of the origin when drawing to the graphics region. Typically the adjustment could be y = y-pos*range. In this way, %gr can be used to display a snapshot of a larger graph by redrawing the area required. Alternatively a full sized graphics region could be created off-screen, with areas copied to the %gr region as required.

See also

%dw


H

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


%he

Purpose

To specify the location of help information.

Syntax

winio@('%n.mhe[options]')

Description

If %he, %bh and %th are not used, help information (obtained using the question mark modifier with certain format codes) is placed at the bottom of the window. %he specifies the current position as the required position for help information.

n and m are optional (m cannot be specified without n). m defaults to 1. They specify the width and depth of the area to take the help string measured in average character units.

The option [flush] can be used when the parent window has a %sy 3d style with the result that the %he border is re-aligned. You can also set the background colour to that of a frame using
winio@('%`bg[inactiveborder]%he[flush]').

See also

%bh, %th, %bg


%ht

Purpose

To attach a hypertext document.

Syntax

winio@('%N.Mht[start_topic]')

Modifiers

Caret (^) - called when a jump is made to a topic that does not exist.

Grave accent (`) - used to enable the given call-back function to be called every time a topic is changed.

Description

N and M are the width and depth of the viewing area measured in average character units. %ht may be preceded by %pv in order to allowing re-sizing at run time.

start_topic is a standard character string giving the name of the first topic to be viewed.

The hypertext document is attached by a call to ADD_HYPERTEXT_RESOURCE@.

For further information see Hypertext windows.

Example

call add_hypertext_resource@('help')
winio@('%pv%^60.20ht[Contents]',cb_func)

help HYPERTEXT file.htm      (resource file)

See also

%pv


%hw

Purpose | To return the handle of the current window.
Syntax | winio@('%hw', handle) integer(7) handle (output)
Description | The returned value can be used in calls to Windows API functions and is the same as that given by CLEARWIN_INFO@('LATEST_FORMATTED_WINDOW'). You can test if the current window has the focus by calling CLEARWIN_INFO@('FOCUS_WINDOW').
See also | %lc


%hx

Purpose

To attach a horizontal scroll bar to the next control.

Syntax

winio@('%hx', page_step, max_val, cur_val)
integer page_step, max_val (input)
integer cur_val (input/output)

Modifiers

Caret (^) - the call-back is called when the user clicks on the scroll bar.

Description

cur_val is the value that corresponds to the position of the scroll box (also called the thumb). It returns a value between zero and max_val - 1.

page_step is the amount that cur_val is to be increased/decreased when the user clicks on the scroll bar (other than on the thumb). For a document, page_step will be set to the number of lines that are to be displayed in the window and max_val should be set to n - page_step, where n is the total number of lines in the document.

With %hx and %vx the three arguments cur_val, page_step and max_val can be passed as variables and changed dynamically with a call to WINDOW_UPDATE@.

A call to CLEARWIN_INFO@('INTERMEDIATE_SCROLL') will determine if the callback was called whilst the thumb was moving. A return value of 1 indicates movement whilst zero indicates that the thumb is stationary. Both of these events occur at the end of a move.

%hx and %vx should not be used with controls like %eb and %cw which have their own scroll bar mechanism.

Example

winio@('%^hx', 5L, 20L, pos, cb_func)

See also

%vx


%ib

Purpose

To insert a image button or image bar.

Syntax

winio@('%n.mib[options]',bitmap_name,stat_ctrl,cb_func,...)
CHARACTER(*) bitmap_name
integer stat_ctrl
external cb_func

Modifiers

Question mark (?) - A help string for each button is placed in order (in square brackets) after the options (use empty brackets for the options list if it is blank).

Description

This format has been superseded by %mb. For new code consider using %mb instead.

%ib provides an enhanced and simplified replacement for %tb. Like %tb, %ib can be used to create toolbars or rectangular arrays of image buttons. However, only one flat image is required for each button - all the variants are created automatically. Also, text can be automatically added to the image.

%n.mib creates block of buttons n buttons wide and m deep. n and m are optional and both default to 1. When n is used m is optional. The arguments consist of the following triplet repeated for each button in turn: bitmap_name, stat_ctrl, cb_func. Note that every button has a call-back function.

bitmap_name is the name of a bitmap resource. If text is to be added to the image, the name is followed by a forward slash and then the text. For example, here is the code for a single button with some text:

i=winio@('%ib','my_button/Press me',ctrl,cb)

The button text can include newline characters:

'my_button/Press'//CHAR(10)//'me'

The integer variable stat_ctrl encodes the state of the button with 1=up, 2=down, 3=greyed, and 4=push button. States 1 and 2 are used with a button that toggles up and down, i.e. a button that requires two separate clicks to return it to the up state. Each time the user presses and releases a button that is not greyed, the call-back function is invoked with call-back reason 'BUTTON_PRESS'. If you decide to use the same call-back function for several buttons you can use CLEARWIN_INFO@('BUTTON_NUMBER') to establish which button was pressed (buttons are numbered along the rows starting at 1).

A call-back function (or any other code) can alter the control variable stat_ctrl and pass it to WINDOW_UPDATE@ to change the state of a button. For example, you could disable/enable a button. Passing any of the control variables belonging to a given %ib toolbar will update the entire block.

%ib[flat] produces a different style of button that pops up and becomes coloured when the mouse is moved over it. %ib[coloured] is similar but active buttons remain coloured by default.

%ib is designed for bitmaps that have a grey background. If the image has a one-pixel border (using just one colour) then this border colour is used as the background colour, otherwise the background is assumed to be light grey (192,192,192). This light grey colour is then translated into the current system COLOR_BTNFACE colour. This can be selected by the user from the Control Panel. The default value varies from one Windows operating system to another.

Images are padded as required to produce a rectangular array, however for best results you should make the images the same size. Alternatively you can use one of the following two mechanisms to produce a rectangular array.

a) The option [const_width] causes the width of each button to be equal to the maximum width of all the buttons whilst the option [const_height] causes the height of each button to be equal to the maximum height of all the buttons. [const_width] is redundant when used on a single column of buttons. [const_height] is redundant when used on a single row of buttons.

b) By adding a ^ modifier to %ib you can specify an overall callback function for the control in addition to the individual callback functions that are required for each button. The overall callback is placed after the other arguments. Currently the only call of this function is before the window is displayed and has the callback reason 'SIZE_ADJUST'. The callback function can call the following function to adjust the toolbar layout:

SUBROUTINE ADJUST_IB_SIZES@(XW,YW,OPT)
INTEGER XW(*),YW(*),OPT

The arrays should be large enough to cover the corresponding dimension of the %ib toolbar. If OPT is zero this routine copies the maximum width of each column into XW and the maximum depth of each row into YW. If OPT is non-zero this data is copied in the opposite direction. Thus the callback function should make an opt=0 call to obtain the data, modify it (e.g. by setting each array to its maximum value, or implementing some scheme which rounds to a small number of sizes) and return it using opt=1. All sizes are in pixels.

Using %bx causes button groups to be anchored when sizing a window that uses a pivot (%pv).

The option [mouse_hover] enables mouse sensitivity with the result that the button callback function is invoked with call-back reason 'MOUSE_ENTER' when the mouse begins to hover over the button. Also the reason 'MOUSE_LEAVE' is provided when the mouse ceases to hover over the button. This allows you to create fly-out toolbars and menus. For a menu, you can create a blank enhanced popup menu in the form

i=winio@('%`pm&',"[]",cb)

Then, in your callback function for the button, you can replace and display the enhanced popup menu with a call to the subroutine DISPLAY_IB_MENU@. This routine takes the same arguments as REPLACE_ENHANCED_MENU@. The result is that ClearWin+ displays a dropdown menu below the button as soon as the mouse is moved over it. In this context, if you are also using [flat] then it should be combined with [coloured].

See also

%bt, %tt, %bx, %mb, Image button and image bar.


%ic

Purpose

To draw an icon.

Syntax

winio@('%ic[icon_name]')
winio@('%`ic', handle)
integer(7) handle (input)

Modifiers

Grave accent (`) - use a Windows API handle.

Caret (^) - the call-back function is called when the user clicks on the icon.

Question mark (?) - a help string is supplied.

Description

icon_name is a standard character string (can be replaced by @) associated with a icon file in a resource script.

handle is a value returned by a modified form of the API function LoadIcon.

Icons can include transparent regions where the background can be seen. They can be of any size. Standard sizes are 16x16, 32x32, 48x48 and 64x64 pixels. Icons can be monochrome or use 16 or 256 colours.

icon_name can also take the form of an integer handle surrounded by curly brackets (this is integer kind=7) or the name of an external file surrounded by curly brackets.

%`ic[static] gives a "static" image rather than a control that can have a callback function. The image can be supplied as an argument that has the value returned by a call to LoadResource@.

Example

winio@('%^ic[myicon]',cb_func)

myicon ICON file.ico      (resource file)

See also

make_icon@,%bm,%gi


%id

Purpose

To identify a button.

Syntax

winio@('%id', N)
integer N

Description

specify the button number (ID) of the next %bt, %tt or %bb button. The button number provides the winio@ return value when a button is clicked and the button is not given a callback function. So %id values can be used in conjunction with the winio@ return value when button callback functions are not needed. By default, button numbers are provided automatically in the order that the buttons are defined.

%id takes one integer argument which must not be negative. A zero value can be used with, for example, %bt[Cancel] since this is equivalent to clicking on the dialog "Close" button.

Note that the following two forms are equivalent because the "EXIT" standard callback returns zero.

iw = winio@("%id%bt[Cancel]", 0)
iw = winio@("%^bt[Cancel]", "EXIT")

Notes

Added to FTN95 at version 7.00


%if

Purpose | To specify that the next control will have the initial focus.
Syntax | winio@('%if')
See also | ADD_CURSOR_MONITOR@, REMOVE_CURSOR_MONITOR@, CLEARWIN_INFO@('FOCUSSED_WINDOW')


%il

Purpose

To specify the lower and upper limits for subsequent %rd formats.

Syntax

winio@('%il', lower, upper)
winio@('%`il')
integer lower, upper (input)

Modifiers

Grave accent (%`il) - cancels an earlier %il and restores the limits to the minimum and maximum for the data type.

Tilde (%~il) - the limits are not applied to the displayed %rd integer value but (on error) an alert icon appears and the text colour changes to red. The associated %rd variable is the same as when not using the tilde (the value is set at the lower or upper limit).

Description

lower is the lower limit and upper is the upper limit.

Example

winio@('%il', 0L, 10L)

See also

%rd, %dd, %co[check_on_focus_loss], SET_INTEGER_LIMITS@


%im

Purpose | To draw an image.
Syntax | winio@('%im[image_name]')
Modifiers | Caret (^) - the call-back is called when the user clicks on the image. Question mark (?) - a help string is supplied.
Description | image_name is standard character string (can be replaced by the @ symbol) giving the name appearing in a resource script. %im is like %bm but can be used with PNG, JPEG, BMP, and PCX resources and files.
Example | winio@('%im[myimage]') The resource file contains one of the following three lines: myimage IMAGE imagefile.png myimage IMAGE imagefile.jpg myimage IMAGE imagefile.bmp myimage IMAGE imagefile.pcx Alternatively, using an external file enclosed in curly brackets: winio@('%im[{imagefile.jpg}]')
See also | %ic,%gi,%bm


%it

Purpose | To switch to italic font.
Syntax | winio@('%it')
Modifiers | Grave accent (%`it) - used to switch off the effect.
Description | %it is cancelled by %`it and %sf.
See also | %bf %ul, %sf


%lc

Purpose | To return the handle of the previous (last) control.
Syntax | winio@('%lc', handle) integer(7) handle (output)
Description | The returned value can be used in calls to Windows API functions. For example controls that do not have grey control variable can be greyed by using %lc to obtain the window handle and then calling the API function EnableWindow.
See also | %hw


%ld

Purpose

To display a round LED symbol (a coloured disk with a black border).

Syntax

winio@('%ld[options]', rgb_value)
integer rgb_value (input)

Description

rgb_value is usually set by a call to RGB@. By supplying a variable for rgb_value the value can be changed dynamically with a call to window_update@.

options can take the keyword square in order to change from a disk to a square shape and/or the keyword blinking to provide a flashing effect by switching between the given colour and black at approximately half second intervals.

Example

winio@('%ld', RGB@(255,0,0))


%ln

Purpose | To draw a horizontal line.
Syntax | winio@('%n.mLN')
Description | %ln provides a horizontal etched line. Unlike %bx it can be used anywhere in a dialog. Its general form is %n.mLN where n and m are optional integers. If both n and m are omitted or n = 0 then the line spans the whole of the dialog up to the margins. Otherwise n is the width in average characters. When present, m is the depth of the "control" in average characters, otherwise m defaults to 1. %ln is a simple "control". It can't be used within a %ob/%cb box and it does not respond to resizing.
See also | %bx


%ls

Purpose

To insert a list box or combo box.

Syntax

winio@('%n.mls[options]',items,num_items,cur_item)
winio@('%~n.mls[options]',items,num_items,cur_item,grey_ctrl)
character*n items(num_items) (input)
integer num_items (input parameter)
integer cur_item (input/output)
integer grey_ctrl (input)

Modifiers

Grave accent (`) - used to provide a drop-down combo box (for editable lists see %el).

Caret (^) - call-back function is called when the user selects an item.

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

Description

n and m are optional (m cannot be specified without n). n represents the width of the list-box in characters and m the depth. n and m can be replaced by asterisks (*) in which case the values of n and m must be supplied as the first two arguments in the argument list.

num_items is the number of items in the list.

cur_item is the item number that is selected in the range zero to num_items both on input and output. Zero signifies that no item is selected.

items is an array of text entries, one for each item. Blank entries at the end of the list are not displayed. This means that you can use blank entries to create a list that can be changed dynamically.

If the grave accent is used and a call-back is supplied, option can be set to the [extended]. The result is that the call-back is called when the list drops down or closes up. These events must be detected from the call-back by calling CLEARWIN_STRING@('CALLBACK_REASON') which returns 'DROPDOWN' or 'CLOSEUP'.

For a list box (i.e. when a grave accent modifier is not used), the option [hscrollbar] provides a horizontal scroll bar whilst the option [multicolumn] provides a multiple column output (see List box format).

If a grave accent is used (%`ls) and the parent window uses %sy[3d_thin] then %ls can be given the option [no_border] to reduce the thickness of the border.

The option [limit_height] takes an additional double precision argument (before any callback function). This argument takes a value that should be less than one. The maximum height of the control will be limited to this proportion of the screen height.

The option [height=n] sets the pixel height of individual items to 'n' pixels. The default value is 16. An asterisk can be used and the value passed in the argument list. For example to set the height to 24 you could write:
winio@('%12.4LS[height=24]',items,7,currentItem) or
winio@('%12.4LS[height=*]',24,items,7,currentItem)

An alternative to %ls[height=v] described is [vertical_fill=v]. [height=n] is limited by not being sensitive to the current font. The alternative [vertical_fill=v] uses a double precision value v and makes the depth of an item equal to (1.0+v)*ht where ht is the pixel height of the current font. The same option can also be used with %ms and %el.

The option [no_box] removes the rectangular box that surrounds the control.

The option [hover] highlights items as the mouse cursor moves over them.

If the grave accent modifier is not used, %ls can be preceded by a pivot %pv.

grey_ctrl is 1 (enabled) or 0 (disable/greyed). Any call-back function must be placed after this control variable.

Notes

The %ls control is limited to a total of 32768 characters. The maximum number of characters for each item is 512.

Example

character*10 names(4)
winio@('%^`ls', names, 4L, sel, cb_func)

See also

%el, %ms, %lv, %pb, %ps


%lv

Purpose

To include a list view control.

Syntax

winio@('%lv[options]',width,height,items,num_items,sel,view)
winio@('%`lv[options]',width,height,items,num_items,sel,
view,icon_str)
character(*) items(num_items) (input/output)
integer num_items (input parameter)
integer sel(num_items-1) (input/output)
integer width,height,view (input)
character(*) icon_str (input)

Modifiers

Grave accent (`) - used to provide a list of icons or an integer array of check box states.

Caret (^) - call-back function is provided.

Question mark (?) - a help string is supplied.

Description

A list view control is a window that displays a collection of items, each item consisting of an optional icon and a label. List view controls provide several ways of arranging items and displaying individual items. For example, additional information about each item can be displayed in columns to the right of the icon and label. This arrangement is called a report view. Microsoft Explorer uses a list view control in order to display directory information.

width and height provide the dimensions of the control in pixels.

num_items is an integer constant giving the number of rows in the report view + 1 (for the header). Blank rows are not displayed in the control. This means that the number of rows that are displayed can be changed under program control. The first blank row terminates the input.

items is an array of num_items character strings the first describing the column headers and widths, then one string describing each row in turn (see the example below).

sel is an integer array whose elements are set to 1 if the item is selected otherwise to zero.

view is an integer variable in the range 0..3 that represents the type of view. 0=Icon view; 1=Report view; 2=Small icon view; 3=List view. These are available even when no icons are provided.

If a grave accent is provided, icon_str is a character string giving a list of icon resources in the form 'icon1,icon2'.

%lv can take a pivot (%pv). Also the right mouse button can be used to trigger a popup menu (%pm) defined in the parent window.

Example

CHARACTER*80 items(4)
INTEGER sel(3),view
items(1)='|Header_100|_50'
items(2)='|AItem1|Data1'
items(3)='|BItem2|Data2'
items(4)='|BItem3|Data3'
sel(1)=1;sel(2)=0;sel(3)=0;view=1
i=winio@('%`lv',300,200,items,4,sel,view,'icon1,icon2')

Here we have 3 rows with 2 columns. items(1) provides data for the column headings and widths. The first character defines the separator between the data for each column. In this example, the first column has the caption "Header". A trailing underscore followed by an integer provides the pixel width of the column. If this is omitted then the length of the text defines the width (a plus sign placed before the integer makes the heading centred whilst a minus sign makes it right justified). In this example the second column header is blank and the second column width is 50 pixels. The number of characters (80 in this case) must be sufficient to allow ClearWin+ to add the column width to each heading (4 characters per column).

items(2) provides data for the first row of a report. Again the first character defines the separator. The second character defines the icon as an index (A,B,C...) into the list of icons 'icon1,icon2' (when a grave accent is used). Next comes the label and then the data for column two etc..

Options
single_selection | Allows only one item at a time to be selected. By default Shift and Control keys can generate multiple selections.
edit_labels | Allows item text to be edited (first column in report view).
no_column_headers | Column headers are not displayed in report view (items(1) is still needed for column widths)
show_selection_always | Always show the selection, if any, even if the control does not have the focus.
no_border | Displays the control without a border.
no_label_wrap | Displays the item label on a single line in an icon view.
align_top | Items are top-aligned in icon and small icon view.
align_left | Items are left-aligned in icon and small icon view.
edit_cells | Allows all columns in the report view to be edited (see below).
user_font | Use the current (%fn) font rather than the default.
grid_lines | Displays grid lines when edit_cells is not used.
full_row_select | Selects a full row in a report view rather than just the item in the first column.
check_boxes | Replaces icons in a report view with check boxes. Use a grave accent and an integer array of state values instead of an icon string.
go_down_on_return | Used with edit_cells in a report view with the result that pressing the return key (when editing a cell) moves down the column.
4bit | Icons have 16 colours. The default is 256 colours (8-bit colour).
24bit | 24-bit colour icons.

Label editing
edit_labels enables label editing and requires a call-back function that can test for the call-back reasons 'BEGIN_EDIT','END_EDIT' and 'EDIT_KEY_DOWN'.

With BEGIN_EDIT you can get the index of the selected item by the call CLEARWIN_INFO@('ROW_NUMBER'). If your call-back function returns the value 4 then editing of this item is prevented.

With EDIT_KEY_DOWN you can validate each character as it is typed. Use CLEARWIN_INFO@('KEYBOARD_KEY') to get the key and/or CLEARWIN_STRING@('EDITED_TEXT') to get the resulting string with the character inserted. If the call-back function returns the value 4 then the character is not accepted. If you want to translate the input key to another key then the call-back function must return the ASCII character code (31<code<256) of the translated key.

With END_EDIT you can get the result of the edit by the call CLEARWIN_STRING@('EDITED_TEXT'). Having validated the label, you should then get the index using CLEARWIN_INFO@('ROW_NUMBER') and reconstruct the relevant row of the items array by adding an icon identifier and extra column data as required (otherwise the original data will be restored). Creating a blank row in response to a label edit is not recommended.

Selecting a view
It is possible to create a menu item or a toolbar button that changes the view state (Icon view, Report view, Small icon view, List view). Here is some sample code for the associated call-back function.

INTEGER FUNCTION change_view()
INTEGER view
COMMON view
view=view-1
IF(view < 0) view=3
CALL window_update@(view)
change_view=2
END

Column widths
If the last column does not extend to the right of the control then ClearWin+ will adjust the width of this column so that it fills the area.

If a column width is changed at run time then ClearWin+ stores the new width in row 1 of the data. This means that the adjusted widths will be used when the control is redrawn. If you want to use the same widths when the program is re-used then you will need to save and restore the modified data.

Cell editing
The option edit_cells is effective in a report view where it over-rides edit_labels. By using edit_cells you can edit the data in any column. A grid is displayed resulting in a spreadsheet appearance. The call-back function can be used to prevent the editing of any given cell and to validate each input character and as well as the final result. For this purpose edit_cells uses the call-back reasons BEGIN_EDIT, EDIT_KEY_DOWN and END_EDIT etc. as in edit_labels. The only difference is that unlike edit_lables, edit_cells initially responds to a single mouse click.

CLEARWIN_INFO@('ROW_NUMBER') and CLEARWIN_INFO@('COLUMN_NUMBER') identify the cell that is being edited.

When editing cells, use the arrow keys to move vertically and CTRL with arrow keys to move horizontally. This movement will step over any cells that are disabled. The selection array (with one element for each row) contains the row number of the current selection. However, when validating input it is simpler to use CLEARWIN_INFO@('COLUMN_NUMBER').

Call-back reasons
BEGIN_DRAG | An item is being dragged.
BEGIN_EDIT | A label is about to be edited (see above).
DROP_TARGET | As an item is dragged across the control different items become the target of the drag. CLEARWIN_INFO@('ROW_NUMBER') identifies the new target. This will change as the mouse moves.
EDIT_KEY_DOWN | The user has pressed a keyboard key during a label or cell edit. CLEARWIN_INFO@('KEYBOARD_KEY') provides the key code (see above).
END_DRAG | An item has been dragged.
END_EDIT | A label has been edited (see above).
SET_SELECTION | A item has been selected. CLEARWIN_INFO@('ROW_NUMBER') provides the index.
COLUMN_CLICK | The user has clicked on a column header. CLEARWIN_INFO@('COLUMN_NUMBER') provides the index.
MOUSE_DOUBLE_CLICK | The user has double-clicked using the left mouse button. CLEARWIN_INFO@('ROW_NUMBER') provides the index.
KEY_DOWN | The user has pressed a keyboard key. CLEARWIN_INFO@('KEYBORAD_KEY') provides the key code.
CHECKBOX_CHANGE | The user has clicked on a check box. CLEARWIN_INFO@('ROW_NUMBER') provides the index and CLEARWIN_INFO@('LISTBOX_ITEM_SELECTED') provides the state.

In response to a column click you might choose to sort the items using the given column index. Having reconstructed the data, you should then make a call to WINDOW_UPDATE@(items) in order to view the new order.

See also

%ms, %ls, %el


%lw

Purpose

To allow winio@ to return without closing the window that it creates.

Syntax

winio@('%lw[option]', ctrl)
integer ctrl (output)

Modifiers

Grave accent (`) - used to delay the creation of the window until ctrl has been passed to %ch.

Description

Using %lw causes winio@ to return whilst leaving the window open. ctrl is a control variable that is returned with the value -1. Subsequently the window can be closed by setting ctrl to zero (or a positive value) and calling WINDOW_UPDATE@(ctrl). Setting ctrl to -2 will cause the window to close after after a short delay. This can be used to seamlessly modify a window by closing the window and then recreating it with similar features and the same position and size.

%lw can take the option owned ( %lw[owned] ). This option defines certain properties of the window in relation to its parent. The "owned" properties are those of a window that does not use %lw, namely that the parent cannot overlay the child and, if the parent is closed, the child automatically closes. For these properties to be meaningful the parent must be created using %ww. Also %lw[owned] must be used in the definition of a child window that appears in a call-back function of the parent.

Notes

If the control variable is declared within a subroutine then it is usually necessary to give it the SAVE attribute. Alternatively %lw can be combined with %wt which ensures that the process of closing the window is completed before returning control to the caller.

See also

%ch, Leaving windows open, STOP_WHEN_WINDOWS_CLOSE@


%mb

Purpose

Multi-button toolbar.

Syntax

winio@("%*mb[options], N, BITMAP_INDEX, BUTTON_STYLE, [BITMAP_NAME,] [BUTTON_STATE,] [BUTTON_ORDER])
integer,parameter::N
integer BITMAP_INDEX(N), BUTTON_STYLE(N), BUTTON_STATE(N), BUTTON_ORDER(N)
character(*) BITMAP_NAME

Modifiers

Grave accent (`) - used with the optional BITMAP_NAME argument that gives the name of a bitmap resource. The bitmap image provides a strip of images, one for each button. If the modifier is omitted then the control uses standard Microsoft image strips.

Tilde (~) - used with the optional BUTTON_STATE argument that describes the state of the each button.

Caret (^) - one callback function is provided and is used for all buttons.

Question (?) - one help string is provided. This contains "tooltip" help text for each button in turn.

- the argument called BUTTON_ORDER is for use with the option [adjustable].

Description
  • N is the maximum number of items in the toolbar, including buttons, separators and hidden buttons.
  • The argument called BITMAP_INDEX provides an array of zero based indexes when selecting an image from an image strip. So if BITMAP_INDEX(4)=7 then the 8th image in the strip will be used for the 4th button.
  • The argument called BUTTON_STYLE provides an array of Microsoft button styles such as TBSTYLE_BUTTON (=0) and TBSTYLE_SEP (=1). TBSTYLE_BUTTON gives a simple button whilst TBSTYLE_SEP provides a separator between buttons. TBSTYLE_DROPDOWN (=8) adds drop-down functionality to a simple button.
  • The argument called BITMAP_NAME requires the grave accent (`) and is used when an image strip is supplied. The name is that of a bitmap resource made up of button images. The depressed and greyed state button images are generated automatically by the control. By default these will be 16x16 images one after another in a horizontal strip. The option [bt_wd=w] provides for a button width w other than 16 whilst the option [bt_ht=h] provides for a button height other than 16. The option [ILC_bits=hex] represents parameters in the Microsoft ImageList_Create function and defaults to the hexadecimal value hex = ILC_COLOR24+ILC_MASK. The default mask colour is 0xC0C0C0 which is the same as using the option [mask=#C0C0C0]. This mask is the "transparent" bitmap background colour to use when creating the bitmap.
  • If the grave accent is not used then %mb uses one of three standard Microsoft image strips. By default this corresponds to the Microsoft parameter IDB_STD_SMALL_COLOR (=0) that provides "standard" 16x16 images. The option [view] changes this to IDB_VIEW_SMALL_COLOR whilst [hist] gives IDB_HIST_SMALL_COLOR. Any one of these three can be increased in size to 24x24 bit images by adding the option [large].
  • The argument called BUTTON_STATE requires the tilde modifier (~) and provides an array of Microsoft button state values such as TBSTATE_ENABLED (=4). If the modifier and argument are not provided then all buttons will be automatically enabled. The state array can be changed at runtime but the change must be followed by a CALL to window_update@(BUTTON_STATE) in order to apply the change.
  • The argument called BUTTON_ORDER requires the option [adjustable] which allows the toolbar to be customised at runtime. Array elements can be initialised to -1 and will contain the user's ordering (with zero represently the first button displayed) after runtime customising. This ordering can be saved for the next time the toolbar is used.
    To change the order at runtime, hold down the shift key and drag a button to a different position in the toolbar or hide it by dragging it off the toolbar. Alternatively double click on the toolbar in order to open a "Customise" dialog.
  • The argument called BUTTON_ORDER must be added when the option [adjustable] is used. If the button order is changed at runtime then the BUTTON_ORDER array receives the new order and this array can be saved for the next time the application is run. The array can be filled initially with the value -1 in order to apply the programmed ordering. If the BUTTON_STATE value of an item is initalised to TBSTATE_HIDDEN+TBSTATE_ENABLED then the item will not be displayed but will be available in the "Customise" dialog.
  • By default the toolbar appears at the top of the "client" area. The option [bottom] provides the style CCS_BOTTOM whilst the option [left] provides the style CCS_LEFT. Up to three toolbars can be used at one time but they must be in different positions. When using %mb, the default %bg background colour is set to "button face" colour and this cannot be changed when using [left].
  • The option [border] adds the style WS_BORDER whilst other toolbar styles may be added via the option [style_bits=hex] where hex is a hexadecimal value such as [style_bits=200] (which is TBSTYLE_WRAPABLE=0x0200).
  • The option [arrows] adds the extended style TBSTYLE_EX_DRAWDDARROWS that controls the appearance and behaviour of a TBSTYLE_DROPDOWN button. With this option an arrow is drawn. Clicking on the button provides a "command" whilst clicking on the arrow provides a "notification" (see below). Without this option, the arrow is not drawn and clicking on the button provides a "notification".
  • The question modifier (?) requires a single help string presented in the standard way. For example, if it is presented in square brackets after the options then it might take the form [|Cut|Copy||Paste]. In this example the first pipe character (|) is used to indicate the character used to divide the string into a list. The tooltip help strings are then "Cut", "Copy" and "Paste" with a blank in the third position for a button separator.
  • The option [strings] has the effect is to replace what otherwise would be tooltips by text below each button bitmap. Another option, [list] can be used with [strings] and the result is that the text appears to the right of each button bitmap rather than below it. The character string for the texts is constructed in the same way as you would construct tooltips and this string appears at the end of the list of winio@ arguments for %mb as it would do for %?mb. The combination represented by %?mb[strings] is not permitted.
  • The caret modifier (^) requires a single callback function for the whole toolbar that uses the following callback "reasons". These are returned by a call to clearwin_string@("CALLBACK_REASON"):
    "MB_COMMAND" | This is the response to a TBSTYLE_BUTTON or TBSTYLE_DROPDOWN "command". CLEARWIN_INFO@("MB_BUTTON") provides the index of the button using the original order starting at button number 1 and including any separators. The callback should return the standard 0, 1 or 2 values to "close", "update" or "continue".
    "MB_DROPDOWN?" This is the response to a TBSTYLE_DROPDOWN "notification". CLEARWIN_INFO@("MB_BUTTON") provides the index as for "MB_COMMAND". A typical response is to provide a drop-down menu as, for example,
    iw = winio@("%nw&",mbCtrl)
iw = winio@("%pm[Item 1,Item 2, Item 3]",cb1,cb2,cb3)
    where mbCtrl is the INTEGER(7) value associated with %lc and used immediately after %mb. Typically the callback will return zero (TBDDRET_DEFAULT) to inform the control to continue with its default response.
    "MB_CUSTOMISE?" | Used with [adjustable] to notify the user has used a double click to open the "Customise" dialog. If the callback returns zero then the action is inhibited. Otherwise return 2.
    "MB_HELP" | Used with [adjustable] to notify the user has clicked on the Help button in the "Customise" dialog.
    "MB_DELETE?" | Used with [adjustable] to notify the user has started to move a button. If the callback returns zero then the action is inhibited. Otherwise return 2.
    "MB_INSERT?" | Used with [adjustable] to notify the user has finished moving a button. If the callback returns zero then the action is inhibited. Otherwise return 2.

Notes

Introduced with FTN95 8.20.

See also

%tb, %ib


%mg

Purpose

To provide a call-back function for a given Windows message.

Syntax

winio@('%mg', msg_no, cb_func)
integer msg_no (input)
external cb_func

Description

This format provides direct access to specified Windows messages. It should be used with care since it is possible to interfere with other ClearWin+ processing.

msg_no is the message number of the message to be processed. User numbers should begin at WM_USER +1000. cb_func is the call-back function that is to be called when the message is received. The call-back function can use CLEARWIN_INFO@ with the strings 'MESSAGE_HWND', 'MESSAGE_WPARAM', and 'MESSAGE_LPARAM' in order to get the standard arguments for a Windows call-back function.

When writing the %mg call-back function, use a return value of 3 if you want ClearWin+ to apply the default processing of the message msg_no. Other values have the usual effect (zero closes the window etc.) but cause the default processing to be bypassed. Occasionally the internal Windows dialog procedure that processes messages requires a particular return other than the default value which is zero (e.g. under certain conditions when using WM_NOTIFY). In this case you should make a call to the subroutine:

SUBROUTINE SET_MG_RETURN_VALUE@(MSG)
INTEGER MSG

before returning. This subroutine takes one integer argument which is the value to be returned by the internal Windows dialog procedure.

See also

%rm


%mi

Purpose

To supply the name of an icon resource to be used in the caption and when the window is minimised.

Syntax

winio@('%mi[icon_name]')
winio@('%`mi', handle)
integer(7) handle (input)

Modifiers

Grave accent (`) - use a Windows API handle.

Description

icon_name is a standard character string (can be replaced by @) associated with the name of an icon file in a resource script.

handle is a value returned by a modified form of the API function LoadIcon.

icon_name can also take the form of an integer handle surrounded by curly brackets (this is integer kind=7) or the name of an external file surrounded by curly brackets.

Example

winio@('%mi[myicon]')

myicon ICON file.ico      (resource file)

See also

make_icon@, %ic


%mn

Purpose | To attach a menu to the window.
Syntax | winio@('%mn[menu_spec]', . . .)
Modifiers | Question mark (?) - All the strings are placed in order at the end of the format description, one for each and every menu item that has a call-back function. Grave accent (`) - Creates an enhanced menu (see Enhanced menus.). Caret (^) - callback to control grey and check.
Description | See Menu format.
Notes | If you want the percentage character % to appear in the text of a menu item then you must put %% in the code.
See also | %pm, %sm


%ms

Purpose

To include a multi-selection box.

Syntax

winio@('%n.mms[options]', items, num_items, sel)
character*n items(num_items) (input)
integer num_items (input parameter)
integer sel(num_items) (input/output)

Modifiers

Grave accent (`) - used to provide multiple selection using the CTRL and SHIFT keys and mouse dragging.

Caret (^) - call-back function is called when the user selects an item.

Question mark (?) - a help string is supplied.

Description

n and m are optional (m cannot be specified without n). n represents the width of the list-box in characters and m the depth.

The option [height=n] sets the pixel height of individual items to 'n' pixels. The default value is 16. An asterisk can be used and the value passed in the argument list. If you include a help string in square brackets then you must also include a (possibly empty) options list.

num_items is the number of items in the list. If m is less than num_items then a scroll bar is presented.

sel is an array whose elements are set to 1 if the item is selected otherwise to zero.

items is an array of text entries, one for each item. Blank entries at the end of the list are not displayed. This means that you can use blank entries to create a list that can be changed dynamically.

%ms will take a pivot %pv.

Example

character*10 names(4)
integer sel(4)
winio@('%^`ms', names, 4L, sel, cb_func)

See also

%ls, %el, %lv, %pb, %ps


%mv

Purpose

To provide a call-back function that is to be called when the user moves or resizes the window.

Syntax

winio@('%mv', cb_func)
external cb_func

Modifiers

Grave accent (`) - without the grave the call-back is for a moving window; with the grave the call-back is for a resizing window.

Description

The call-back function is also called when the window is created (if two are used, one for moving and one for re-sizing, then both are called).

The call-back function will typically call the Clearwin+ function GET_WINDOW_LOCATION@ in order to determine the new size and position.

Note that certain window operations involve both moving and resizing. For example if the user drags the top-left corner, then the window is both moved and resized ('moving' changes the co-ordinates of the top left corner, 'resizing' changes the width and/or height).

See also

GET_WINDOW_LOCATION@


%nc

Purpose

To provide a specified class name for the application.

Syntax

winio@('%nc[class_name]')

Description

class_name is a standard character string (can be replaced by @) that specifies the new class name. Some applications display the class name in their output.

Notes

The Windows API function FindWindow can be used in order to get a (integer kind=7) handle to another application from its class name. The handle can then be used to target messages. If you want the current application to act as such a target you can specify the class name using %nc.

Example

winio@('%nc[myappclass]')

See also

send_text_message@, %rm


%nd

Purpose | To prevent controls from sliding down when sizing a window.
Syntax | winio@('%nd')
Modifiers | Grave accent (`) - used to switch off the effect.
Description | Used with %pv and %ww under the old re-sizing mechanism (see Pivot).
See also | set_old_resize_mechanism@, %ww, %nr


%nl

Purpose | To insert new lines.
Syntax | winio@('%mnl')
Description | m is the number of new lines to insert. m is optional and defaults to 1. To move directly below a control or graphics area use %ff instead.
Example | winio@('%3nl')
See also | %ff, %cn, %rj


%nr

Purpose | To prevent controls from sliding right when sizing a window.
Syntax | winio@('%nr')
Modifiers | Grave accent (`) - used to switch off the effect.
Description | Used with %pv and %ww under the old re-sizing mechanism (see Pivot).
See also | SET_OLD_RESIZE_MECHANISM@, %ww, %nd


%ns

Purpose | To disable a screen saver whilst the current window is open.
Syntax | winio@('%ns')
See also | %sv


%nw

Purpose

To change certain properties of an existing window.

Syntax

winio@('%nw', handle)
integer(7) handle (input)

Description

handle is the %hw output from a window that has already been created. If the handle is set to zero then %nw uses the currently active window.

%nw allows you to change the properties of an existing window. In particular you can use %nw to define or redefine %mn and %pm menus on the fly. This includes %em enhanced menus but not old enhanced menus (%`mn and %`pm).

Alternatively handle could be the handle of a particular control (%lc) in an existing window (by using winio@ in a %sc callback for example). %nw %pm will then provide a popup menu for the associated control.

See also

New enhanced menus.


%ob

Purpose

To open a box.

Syntax

winio@('%ob[options][title]')
winio@('%n.mob[options][title]')

Modifiers

Grave accent (`) - provides a shaded background.

Description

Defines the top left hand corner of a rectangular box into which subsequent objects are to be placed until a corresponding %cb format is encountered.

title is optional and is a standard character string that is used with an option from the options list that sets a title to the box.

options is can be one or more of:

named_c | Splices a name into the top line of the box (in the centre)
named_l | Splices a name into the top line of the box (on the left).
named_r | Splices a name into the top line of the box (on the right)
named | The same as named_c.
nameless | Occupies the same vertical space as named_c etc. but has no name.
no_border | Create an invisible box which is useful for grouping controls.
invisible | The same as no_border.
panelled | This replaces the simple line box with a 3-dimensional panel.
thin_panelled | Similar to panelled but perhaps a slightly more attractive effect.
shaded | This has the same effect as the use of the grave accent.
status | This provides a box in the form of a status bar.
bottom_exit | Begins the next control below this box rather than to the right.
scored | Double line, 3-dimensional shade effect.
depressed | Single line, 3-dimensional shade effect.
raised | Single line, 3-dimensional shade effect
rounded | Rounded corners
line_colour | Provides the RGB value for the line colour of a simple box. The value is provided as winio@ argument (after the box name when a name is used).

When n and m are used, %ob creates a rectangular grid of boxes (n across, m down) each requiring its own %cb. Thus %3.2ob would require six %cb codes. A title cannot be supplied for a grid of boxes. When used with the option no_border, this provides a mechanism for positioning text and controls within rectangular sub regions of the window (see Box format for a simple example).

%ap can be used before %ob in order to specify the position of the box from the %ap arguments.

Notes

%ob boxes can be nested, one within another, in order to provide a fine control over the positioning of items in a window.

The options scored, depressed and raised should not be used with a background colour of white or black (grey is typical).

Example

winio@('%ob[named_r][Results]')

See also

%ap


%og

Purpose | To create an OpenGL graphics region.
Syntax | winio@('%og[options]', width, height) integer width, height (input)
Description | %og takes two arguments namely the pixel width and pixel height of the region and sets up an OpenGL graphing region. %og only works on Win32 and x64 platforms, and requires the presence of associated DLLs. See OpenGL for further details.


%pb

Purpose

To insert a parameter box.

Syntax

winio@('%N.Mpb[options]')

Modifiers

Question mark (?) - can be attached to %dp, %fp, %tp, %ep and %up.

Description

N is the width of the box in average characters. M is the number of lines in the control which will include a scroll bar if M is not large enough.

options can be omitted or can take the value sorted to specify that the parameters are to be alphabetically sorted by name.

After a parameter block has been defined parameters can be attached by subsequent formats thus:

%dp - Integer parameter

%fp - Floating point parameter

%tp - Text parameter

%ep - Enumerated parameter (a set of named alternatives)

%up - User parameter (just activates a call-back)

Each of these codes is followed by a standard character string that provides the text to be displayed. See Parameter box for further information.

See also

%ls, %ms, %ps


%pd

Purpose | To insert a Sterling pound symbol '£'.
Syntax | winio@('%pd')


%pl

Purpose

To create a 32 bit SIMPLEPLOT graphics region or a native 64 bit graph.

Syntax

winio@('%pl[options]', width, height)
integer width, height (input)

Modifiers

Question mark (?)

Caret (^) - used to supply a call-back function.

Description

In order to use the 32 bit SIMPLEPLOT graphics drawing library, the executable must have access to a DLL called simple.dll. This DLL is supplied with Silverfrost compilers. When making direct calls to the SIMPLEPLOT library (see the user_drawn option), the program must also be linked using the DLL.

Native ClearWin+ 64-bit graph plotting is also available using the options described below together with the further information provided here.

width and height represent the pixel dimensions of a SIMPLEPLOT graphics region within the window. Information about the options that are available is provided here. Some of the options take additional arguments. Data that is real must be passed as double precision values despite the fact that the SIMPLEPLOT library uses only single precision arithmetic.

Data that is provided via additional arguments should normally be available throughout the life time of the window. This enables the window to be re-drawn, for example after a re-sizing operation.

For an example showing the graph being updates see: 'Simpler Graph' in our GitLab example repository.

See also

%gr, %og, %dw, Native graphs


%pm

Purpose

To supply a popup menu.

Syntax

winio@('%pm[menu_spec]', ...)

Modifiers

Question mark (?) - All the strings are placed in order at the end of the format description, one for each and every menu item that has a call-back function.

Grave accent (`) - Creates an enhanced menu (see Enhanced menus.).

Caret (^) - callback to control grey and check.

Description

Provides a popup menu so that when the right mouse button is pressed in the main window a menu appears. The menu does not appear when the mouse points to a control within the main window.

The CLEARWIN_INFO@ parameters, POPUP_X and POPUP_Y reflect the position of the mouse at the point at which %pm was invoked. These values are screen coordinates before any subsequent movement to select a particular menu item. They can be used in a user function that is called when a popup menu item is selected.

Notes

If you want the percentage character % to appear in the text of a menu item then you must put %% in the code.

See also

%mn, %sm, Popup menu, Menu format


%ps

Purpose

To produce layered windows in a card-index style (property sheet).

Syntax

winio@('%Nps[option]', sheet1, sheet2, . . . , sheetN)
winio@('%`Nps[option]', sheet1, sheet2, . . . , sheetN, sheet_n)
integer sheet1, sheet2, . . . , sheetN (input)
integer sheet_n (input/output)

Modifiers

Grave accent (`) - provides for a variable (sheet_n) to set and return the current sheet number. sheet_n must be SAVEd or global (e.g. in a module or common block).

Caret (^) - the call-back function is called each time the sheet is changed and when the first sheet is initially displayed.

Tilde (~) - the list of "state controls" is replaced by a single array.

Description

N is the number of sheets. sheet1 to sheetN are variables that have been introduced when defining the various %sh sheets.

Each sheet is set up using a complete winio@ format and %sh.

CLEARWIN_INFO@('SHEET_NO') can be used to return the current visible sheet number which is initially set to one. Alternatively, a grave accent modifier can be supplied in order to set the initial sheet (at a value other than one) and to change the sheet number under program (rather than user) control. The program can change the sheet number by changing sheet_n and calling see_propertysheet_page@(sheet_n).

%ca can be used with %sh to provide a caption. The caption can include an accelerator key indicator '&' which operates in the same way as in a menu or on a button to select the sheet.

If a call is made to the Windows API function EnableWindow to disable one sheet, then that sheet will no longer be selectable unless/until the window is re-enabled. If the sheet that is currently visible is disabled, another sheet will not automatically be selected. However, when another sheet is selected, a disabled sheet will not be re-selectable.

option can be set to the keyword ms_style in order to use a Microsoft tab control instead of the internal ClearWin+ control (the appearance of the Microsoft tab control is changed by using the XP manifest). option can also be set to the keywords bottom and hot_track both of which imply ms_style. [bottom] places the tabs at the bottom of the control whilst [hot_track] changes the appearance of the tab when the mouse hovers over it.

A new option [frame] has been added at version 8.40. This provides a blank tabbed control to which tabs can be added at runtime and thus provides an alternative to the %fr multi-document format. %sh sheets are required when defining %ps but these only provide templates for subsequent calls to a function NEW_TAB@(INDEX, CAPTION) where INDEX is the index of the sheet (in the order they are defined in the program) and CAPTION is the caption to use for the tab.

Both %ps and its %sh sheets can take a pivot to allow for resizing. Initial tests have focused on sheets that contain a single %re, %eb or %gr control. For %re and %eb, the function EditFileClosePrompt@ can be called with the first argument set to -1 (i.e. -1_7). This provides a prompt for all associated tabs that are open.

In this context, %sh sheets can include a main menu (%mn). When a tab is selected, this menu becomes the main menu for the application. The main window and the sheets can also include %mb toolbars that work in the same way - adjusting to the currently active tab.

A new option [tooltips] can be used with [frame]. This activates tooltips for the tab captions. ClearWin+ will then provide default tooltips which can be over-ridden by calling SET_TAB_TOOLTIP@ immediately after creating a tab.

When defining a %sh sheet, the %if format code should be used to indicate the control with the initial focus. The Windows handle (HWND) of this control is used in the following associated functions.

INTEGER(7) NEW_TAB@(INDEX,CAPTION)
INTEGER INDEX
CHARACTER(*) CAPTION
 If INDEX=1 then the first %sh sheet defined in the program is used by the call and so on. CAPTION is the caption for the tab. Returns the Windows HWND of the control with the initial focus (%if).

INTEGER(7) CURRENT_TAB@()
 Returns the Windows HWND of the control with the initial focus (%if) in the currently selected tab.

INTEGER(7) DELETE_TAB@
 Deletes the currently selected tab and returns the Windows HWND of the deleted control with the initial focus (%if).

SUBROUTINE SET_TAB_TOOLTIP@(TIP)
CHARACTER(*) TIP
 Called immediately after creating a new tab in order to change its tooltip from the default. Requires %ps[tooltips].

Notes

In some contexts sheet1 etc. must be accessible after the property sheet has been closed. In which case they could, for example, be given the SAVE attribute. Alternatively %ps can be combined with %wt which ensures that the process of closing the window is completed before returning control to the caller.
If an individual sheet is closed (e.g. by placing a button without a callback function in the sheet) then the parent window will close.

See also

%sh


%pv

Purpose | To allow certain controls to be re-sized under user control.
Syntax | winio@('%pv')
Description | Use %pv before %eb, %fr, %dw, %gr, %cw, etc. so that the control can be re-sized at run time. A thick frame is added to the window to enable it to be resized.
See also | %eb, %fr, %dw, %gr, %cw


%rb

Purpose

To define a radio button or check box.

Syntax

winio@('%rb[button_text]', ctrl)
winio@('%~rb[button_text]', ctrl, grey_ctrl)
integer ctrl (input/output)
integer grey_ctrl (input)

Modifiers

Grave accent (`) - provides a check box rather than a radio button.

Caret (^) - call-back is called when the control is selected.

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

Description

button_text is a standard character string (can be replaced by @) for the text attached to the radio button. To change the text dynamically use %lc and the API function SetWindowText.

ctrl is 1 (on) or 0 (off).

grey_ctrl is 1 (enabled) or 0 (disable/greyed). A call-back function (if present) is placed after this control variable.

%rb can be used in conjunction with the gang format code %ga. Note that it is not conventional to gang check boxes.

Example

winio@('%rb[Button 1]', rb1)

See also

%ga


%rc

Purpose | To register a command for %mb or in general.
Syntax | winio@('%rc', btn_index, cb_func ) INTEGER btn_index EXTERNAL cb_func
Modifiers | Caret (^) - An additional callback that controls the greying of the associated button.
Description | The toolbar control %mb takes just one callback function and this is designed to respond to the "callback reason" MB_COMMAND. Having a single callback can be limiting especially if there are lots of buttons on a toolbar. %rc allows you to register a callback for any individual button. 'btn_index' is the index of the button; numbering starts at 1 and you must include any separators in the numbering. 'cb_func' is the callback to be called when the button is pressed and can of course be a standard callback. The callback can be run programmatically using DO_COMMAND@.
See also | %mb, DO_COMMAND@


%rd

Purpose

To create an edit box and display an integer that can be updated.

Syntax

winio@('%nrd[option]', value)
winio@('%~nrd[option]', value, grey_ctrl)
integer value (input/output)
integer grey_ctrl (input)

Modifiers

Grave accent (`) - makes the control read-only (no box is supplied, see %co).

Caret (^) - the call-back is called when a change is made (see also %co).

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

Description

n is optional and specifies the number of average width characters in the displayed output. Only values in range can be entered (see %co). The range can be set using %il.

If %`rd is specified, then the value presented can only be changed by the program using window_update@(value).

grey_ctrl is 1 (enabled) or 0 (disable/greyed). A call-back function (if present) is placed after this control variable.

option can be set to the keyword initially_blank in order to create an edit box that is initially empty (see notes below). In addition it can also take the keyword radix=n where n is the number base for the displayed value. n must be in the range 2 to 36.

The standard call-back functions 'COPY', 'CUT', and 'PASTE' can be used in this context by attaching them to menu items and/or accelerator keys.

When %dd is used before %rd, a spin wheel is added (see %dd for details).

The subroutine set_highlighted@ can be called to select all of the text in the edit box. It takes one INTEGER(7) argument which is the handle given by %lc.

Notes

The [intially_blank] option can be reset dynamically using a call to the routine:

SUBROUTINE UNBLANK_CONTROL@( HWND )
INTEGER(7) HWND

W is the handle for the control obtained using %lc. The routine is used to selectively switch off this property at runtime.

See also

%il, %dd, %co, %tc, SET_HIGHLIGHTED@, SET_CONTROL_TEXT_COLOUR@


%re

Purpose

To create an multi-line edit box and display a character variable (i.e. a string).

Syntax

winio@('%N.Mre[options]', buffer)
winio@('%~N.Mre[options]', buffer, grey_ctrl)
character(*) buffer (input/output)
integer grey_ctrl (input)

Modifiers

Grave accent (`) - makes the control read-only (scroll bars are disabled).

Caret (^) - the call-back is called when a change is made.

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

Description

This control is similar to %rs but is multi-line. It has a buffer limit of 32K characters. Buffers larger than 32K may be used but will not automatically be updated when changes are made and require an explicit call to GetEditText@ (see below) in order to update the buffer..

N represents the width of the box in average characters. M represents the depth which should not be less than 2.

buffer is a character string for the text (maximum of 32*1024 characters). If buffer has zero length (e.g. winio@("%30.20re","")) then the control uses its own buffer. The content of this buffer can be retrieved by calling GetEditText@ (see below)

%re uses the standard Microsoft edit control which responds directly to the accelerator keys Ctrl+C, Ctrl+V, Ctrl+X and Ctrl+Z (for a single undo). It also has its own standard pop-up menu. Standard callbacks "EDIT_FILE_OPEN", "EDIT_FILE_SAVE", "EDIT_FILE_SAVE_AS" and "EDIT_UNDO" have been added analogous to the existing standard callbacks for %eb. These are in addition to the existing "CUT", "COPY" and "PASTE".

The following options are available:

UPPERCASE | Alphabetical characters (a . . z) are converted to upper case and displayed and stored as upper case.
LOWERCASE | Alphabetical characters (A . . Z) are converted to lower case and displayed and stored as lower case.
CENTRE_TEXT | Text is always centred on every line.
RIGHT_TEXT | Text is right justified on every line (the default is left justified text).
NO_HSCROLL | The text will not scroll to the right past the end of the window. The text will auto wrap.
NO_VSCROLL | The text will not scroll beyond the bottom of the window.
HSCROLLBAR | A horizontal scroll bar is added - do not use with NO_HSCROLL.
VSCROLLBAR | A vertical scroll bar is added - do not use with NO_VSCROLL.
KEEP_FOCUS | When the user tabs between windows, normally the focus will be lost, however with KEEP_FOCUS the selected text will remain selected.
NO_ADDITIONAL_DEPTH | Removes the standard spacing between this control and the next line.

The following functions may be used with this enhanced control. These functions take an INTEGER(7) value HWND, typically obtained via %lc. If HWND is zero (0_7) then the control that has the current focus is used.

INTEGER FUNCTION GetEditText@(HWND, BUFFER, SIZE)
CHARACTER(*) BUFFER
INTEGER SIZE
 Gets the contents of the control. Returns zero if the HWND is not valid or the buffer is not large enough. SIZE is the size of the buffer. Edit controls are limited to a maximum of 32K characters.

INTEGER FUNCTION OpenEditFile@(HWND, FILENAME)
CHARACTER(*) FILENAME
 Opens and reads the text file into the control and associates the control with this FILENAME. Return zero if the HWND is not valid or the file cannot be opened and read. This function can be used in a callback associated with the "FILE_OPENR" standard callback and the %ft format code for file "filters".

INTEGER FUNCTION EditFileSave@(HWND)
 The function uses the file name associated with the control if it has one, otherwise it opens a standard "Open file" dialog and creates the file association. No action is taken if an association exists and the text has not changed. Returns zero if the HWND is not valid or the file cannot be saved. File "filters" can be provided via the %ft format code.

INTEGER FUNCTION EditFileSaveAs@(HWND)
 The function opens a standard "Open file" dialog to get a full path for a file and then saves it, creating a new file association for the control. Returns zero if the HWND is not valid or the file cannot be saved. File "filters" can be provided via the %ft format code.

INTEGER FUNCTION EditFileClosePrompt@(HWND, CAPTION, MESSAGE)
CHARACTER(*) CAPTION,MESSAGE
 Used when closing the control's window (e.g. within a %cc callback). If the text has changed since the last "save" operation then a dialog is presented prompting for a save before closing. The possible responses are Yes, No and Cancel. CAPTION is the title for the prompting dialog and MESSAGE is its message. If %s is used within this MESSAGE string then %s is replaced by the short name of the associated file if there is one. The function returns zero for "No" and for "Yes" when the save is successful. This return value can be used directly as the return value of a %cc callback.

INTEGER FUNCTION EditFileModified@(HWND)
 Returns 1 if the text has been changed since the last save operation, otherwise it returns zero.

Notes

The %rs PASSWORD option is not available with %re. %re can take a pivot (%pv). %co can be used with %re.

See also

%rs, %eb, %co


%rf

Purpose

To create an edit box and display a floating point value that can be updated.

Syntax

winio@('%nrf[option]', value)
winio@('%~nrf[option]', value, grey_ctrl)
double precision value (input/output)
integer grey_ctrl (input)

Modifiers

Grave accent (`) - makes the control read-only (no box is supplied, see %co).

Caret (^) - the call-back is called when a change is made (see also %co).

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

Description

n is optional and specifies the number of average width characters in the displayed output. Only values in range can be entered (see %co). The range can be set using %fl. Values are entered in decimal or exponent form.

If %`rf is specified, then the value presented can only be changed by the program using WINDOW_UPDATE@(value).

grey_ctrl is 1 (enabled) or 0 (disable/greyed). A call-back function (if present) is placed after this control variable.

option can be set to the keyword initially_blank in order to create an edit box that is initially empty (see notes below). It can additionally take a format specifier to provide greater control in how the value is displayed. This takes the form [fmt=<format_specifier>] and is analagous to the formatting of %wf, %we and %wg. For example %rf[fmt=0.4e] is equivalent to %0.4we. In other words, we simply omit the '%' and the 'w'. The result in this case is an exponent form with 4 decimal places and 5 significant figures. See %wf for more details on the format_specifier.

The standard call-back functions 'COPY', 'CUT', and 'PASTE' can be used in this context by attaching them to menu items and/or accelerator keys.

When %df is used before %rf, a spin wheel is added (see %df for details).

The subroutine SET_HIGHLIGHTED@ can be called to select all of the text in the edit box. It takes one INTEGER(7) argument which is the handle given by %lc.

Notes

The [intially_blank] option can be reset dynamically using a call to the routine:

SUBROUTINE UNBLANK_CONTROL@( HWND )
INTEGER(7) HWND

W is the handle for the control obtained using %lc. The routine is used to selectively switch off this property at runtime.

%rf accepts the input of a comma. This is transcribed to a decimal point.

See also

%fl, %df, %co, %tc, SET_HIGHLIGHTED@, SET_CONTROL_TEXT_COLOUR@


%rj

Purpose | To right justify text and controls.
Syntax | winio@('%rj')
Description | %rj forces everything that follows it, up to the next new line or form-feed character, to be right justified in the window. A window margin, if any, is still applied. When %rj is used within a box (%ob), the format applies only to that box.
See also | %cn, %nl, %ff


%rm

Purpose | To provide the name of a call-back function to handle messages from another ClearWin+ application.
Syntax | winio@('%rm', cb_func) external cb_func
Description | If one application uses the subroutine SEND_TEXT_MESSAGE@ to send text to a second application, the second application should use %rm to supply the name of a call-back function to handle the message and send a reply.
See also | SEND_TEXT_MESSAGE@, REPLY_TO_TEXT_MESSAGE@, CLEARWIN_STRING@('MESSAGE_TEXT').


%rp

Purpose

To set the position of the next control relative to the current position.

Syntax

winio@('%rp', ix, iy)
integer ix,iy (input)
winio@('%`rp',rx, ry)
double precision rx,ry (input)

Modifiers

Grave accent (`) - use real rather than integer input.

Description

The units of measurement correspond to the average width and the height of the default font.

Example

winio@('%rp', 8L, 0L)

See also

%ap, %gd, %ob, %nl, %ff


%rs

Purpose

To create an single-line edit box and display a character variable (i.e. a string).

Syntax

winio@('%nrs[options]', string)
winio@('%~nrs[options]', string, grey_ctrl)
character(*) string (input/output)
integer grey_ctrl (input)

Modifiers

Grave accent (`) - makes the control read-only (no box is supplied, see %co).

Caret (^) - the call-back is called when a change is made (see %co).

Question mark (?) - a help string is supplied.

Tilde (~) - adds a variable that controls the grey (enable/disable) state.

Description

For the equivalent multi-line edit box see %re.

n is optional and specifies the number of average width characters in the displayed output. The output will scroll horizontally within the specified width if necessary.

If %`rs is specified, then the string presented can only be changed by the program using WINDOW_UPDATE@(value).

grey_ctrl is 1 (enabled) or 0 (disable/greyed). If a call-back function is used, it is placed after this control variable.

The standard call-back functions 'COPY', 'CUT', and 'PASTE' can be used in this context by attaching them to menu items and/or accelerator keys.

When %dd is used before %rs, a spin wheel is added (see %dd for details).

The subroutine SET_HIGHLIGHTED@ can be called to select all of the text in the edit box. It takes one INTEGER(7) argument which is the handle given by %lc.

The following options are available:

PASSWORD | An asterisk (*) appears on the screen for each character typed whilst the string is correctly stored.
UPPERCASE | Alphabetical characters (a . . z) are converted to upper case and displayed and stored as upper case.
LOWERCASE | Alphabetical characters (A . . Z) are converted to lower case and displayed and stored as lower case.
NO_ADDITIONAL_DEPTH | Removes the standard spacing between this control and the next line.

See also

%st, %co, %re, %eb, %tc, SET_HIGHLIGHTED@, SET_CONTROL_TEXT_COLOUR@


%sb

Purpose

To provide a status bar.

Syntax

winio@('%Nsb' [,iar])

Modifiers

Grave accent (%`sb) - indicates that the first panel of the status bar is to be used for help strings.

Description

N is optional. When N > 1, it specifies the number of panels and iar is an integer array specifying the width (in average characters) of each panel in turn. The width of the last panel is set automatically to extend to the right hand edge of the window. When N is not provided, iar is also omitted, resulting in just one panel. A grave accent can be applied and indicates that the first panel of the status bar is to be used for help strings.

The option [tooltips] can be used and provides a tooltip when the pane in the status bar is not wide enough to display all of the text supplied. Otherwise it has no effect. The text for the tooltip is simply a copy of the text supplied for the pane via a call to SET_STATUS_TEXT@. The option has no effect when used with the first pane of a %`sb control where the displayed text is controlled by menu help information.

A new routine SET_STATUS_TEXT@ can be called to set the text in a given panel.

            SUBROUTINE SET_STATUS_TEXT@(hwnd, panelID, text)
            INTEGER(7) hwnd
            INTEGER panelID
            CHARACTER(*) text
hwnd is the Windows handle obtained from %lc (written in the code after %sb) and panelID is the zero based index of the panel to write to.

Notes

Added to FTN95 at version 8.30

See also

%ob, %br


%sc

Purpose

To provide a call-back function when a window is initially displayed.

Syntax

winio@('%sc', cb_func)
external cb_func

Description

Causes a given call-back to be called once only when a window is initially displayed (for example, for drawing initial %gr data).

Notes

If %gr (say) has a call-back function that receives the RESIZE message from CLEARWIN_INFO@('CALLBACK_REASON'), this message is received before the %sc call-back is called.

Call-back functions can often be shared by different format codes within one format window. For example, a call-back associated with %sc may also be suitable for %mv.


%sd

Purpose

To provide subscript text.

Syntax

winio@('%sd')

Modifiers

Grave accent (`) - cancels the effect of an earlier %sd.

Description

This format code cannot be applied to the default font so select a font and then enclose the text that is to be subscripted between %sd and %`sd.

Example

winio@('%fn[arial]Water is H%sd2%`sdO')

See also

%su


%sf

Purpose | To return to the standard font.
Syntax | winio@('%sf')
Modifiers | Grave accent (`) - Windows 95 only (see System font).
Description | Resets to default text attributes after use of any combination of %bf, %it, %ul, %fn, and %ts.
See also | %bf, %it, %ul, %fn, %ts, USE_WINDOWS95_FONT@


%sh

Purpose

To create a property sheet.

Syntax

winio@('%sh', var)
integer var

Description

Each time %sh is used, it creates a window that is to be linked to %ps. var forms the link with %ps (via its address).

Each sheet can be provided with a caption using %ca. In this situation the caption can include an ampersand (&) to mark an accelerator key.

Notes

In some contexts the variable var must be accessible after the property sheet has been closed. In which case it could, for example, be given the SAVE attribute.

See also

%ps, %ca


%si

Purpose | To insert a standard icon.
Syntax | winio@('%nsisymbol')
Modifiers | Caret (^) - call-back is called when the user clicks on the icon. Question mark (?) - the help string goes after the symbol.
Description | Defines a standard icon that is to be placed to the left of the block of text that follows %si. symbol is one of:

! | hazard '!' road sign
? | question mark in bubble
* | information 'i' in bubble
# | stop 'X' on disc.
X | 16x16 hazard icon
Q | 16x16 question icon
I | 16x16 information icon
W | 16x16 stop icon

N is optional and can be added in order to centre the icon vertically to the left of n lines of text.

Example

winio@('%si#')

See also

%ic


%sl

Purpose

To insert a slider control.

Syntax

winio@('%Nsl[option]', value, min, max)
double precision min, max (input)
double precision value (input/output)

Modifiers

Caret (^) - call-back is called repeatedly as the user moves the slider or when an arrow key is pressed.

Question mark (?) - a help string is supplied.

Description

N is mandatory and sets the length of the control in average character units.

value is the current value represented by the slider in the range min to max. This value can also be accessed by a call-back function whilst the slider is being moved.

The following options can be used:
vertical | Provides a vertical bar.
horizontal | Provides a horizontal bar (the default).
ms_style | Uses a Microsoft trackbar control and takes INTEGER rather than DOUBLE PRECISON arguments.
The following options can also be used with the INTEGER version of %sl and imply [ms_style]. The resulting Microsoft style is shown in brackets.
both | The trackbar control displays tick marks on both sides of the control, top and bottom for a horizontal bar, left and right for a vertical bar (TBS_BOTH).
top_or_left | A horizontal bar has tick marks on top. A vertical bar has tick marks to the left Otherwise tick marks are bottom (when horizontal) or right (when vertical). (TBS_TOP or TBS_LEFT)
no_ticks | No tick marks are displayed
auto_ticks | The bar has a tick mark for each increment in its range of values (TBS_AUTOTICKS)
tick_frequency=v | v is an integer and the bar has tick marks with this frequency
thumb_length=v | v is an integer giving the pixel length of the slider (TBS_FIXEDLENGTH)
selection_min=v1 | The bar is displayed differently with only part of the range enabled
selection_max=v2 | v1 and v2 are integers that specify the sub-range to be used. (TBS_ENABLESELRANGE)
tooltips=top | For a horizontal bar. Current value appears top right. (TBS_TOOLTIPS with TBTS_TOP)
tooltips=bottom | For a horizontal bar. Current value appears bottom right. (TBS_TOOLTIPS with TBTS_BOTTOM)
tooltips=left | For a vertical bar. Current value appears left of the slider. (TBS_TOOLTIPS with TBTS_LEFT)
tooltips=right | For a vertical bar. Current value appears right of the slider. (TBS_TOOLTIPS with TBTS_RIGHT)
border | A border is provided (WS_BORDER)

The slider will respond to the arrow keys on the keyboard.

The value returned by CLEARWIN_INFO@('LATEST_VARIABLE') can also be used with %sl.

Example

winio@('%20sl', x, 0.0D0, 10.0D0)

See also

%br

Notes

ms_style and the associated options were introduced with FTN95 8.40.


%sm

Purpose | To modify the system menu.
Syntax | winio@('%sm[menu_spec]', . . .)
Modifiers | Grave accent (`) - used to replace rather than add to the existing system menu. Question mark (?) - All the strings are placed in order at the end of the format description, one for each and every menu item that has a call-back function.
Description | See System menu.
Notes | If you want the percentage character % to appear in the text of a menu item then you must put %% in the code.
See also | %mn, %pm


%sp

Purpose

To set the position of a window.

Syntax

winio@('%sp', x, y)
integer x, y(input)

Modifiers

Grave accent (`) - used in a call-back function to give the position relative to the position of the event that resulted in the call.

Description

x and y represent the position of the top left corner of the window in screen co-ordinates. Typically these values are returned by %gp.

Example

winio@('%sp', 200L, 100L)

See also

%gp


%ss

Purpose

To save and load settings using an INI file.

Syntax

winio@('%ss[filename/section]', ctrl)
integer ctrl (input)

Description

%ss is used before %rd, %rf, or %rs in order to automatically save and restore data in these controls.

filename/section is a standard character string (can be replaced by @).

filename is the stem of a file with the .INI extension that is stored in the standard Windows directory.

section is the name of a section in the INI file. This name appears in square brackets at the head of a section in the file.

The item name for the data is automatically formed from the text that appears immediately before the control. Spaces are removed from the text in order to form the name. See Save settings to .INI file for further details.

ctrl is set to 1 to enable saving and to 0 to disable saving.

Example

winio@('%ss[app1/block2]', ctrl)

See also

%rd, %rf, %rs


%st

Purpose

To insert a variable string.

Syntax

winio@('%N.mst', string)
character *(*) string (input)

Modifiers

Grave accent (`) - right justifies the string in the field.

Description

Lays out a string out in a field N average characters wide and m deep. m is optional and defaults to 1 but N must be specified The string is read-only (unlike %rs, the string cannot be changed by the user). It can, however, be changed by the programmer. The change is followed by a call to WINDOW_UPDATE@(string) in order to make a change visible. The string is re-drawn each time the window is renewed. (%`rs provides a similar effect.)

When used as the last item in a status bar, the control will automatically expand to fill the remaining space.

Example

winio@('%20st', str)

See also

%`rs


%su

Purpose

To provide superscript text.

Syntax

winio@('%su')

Modifiers

Grave accent (`) - cancels the effect of an earlier %su.

Description

This format code cannot be applied to the default font. You must select a font and then enclose the text that is to be superscripted between %su and %`su.

Example

winio@('%fn[arial]Einstein said E=MC%su2%`su.')

See also

%sd


%sv

Purpose | To create a screen saver executable.
Syntax | winio@('%sv')
Description | A window whose definition includes %sv will close as soon as it receives mouse or keyboard input. See Screen saver for further information.
See also | %ns


%sy

Purpose | To change the style of a dialog box.
Syntax | winio@('%sy[options]')
Description | By default, a format window that uses neither %ww nor %sy has a caption bar but does not have: a) system menu, b) a minimise box and c) a maximise box. Such a window is called a dialog box and by default has a double frame that is raised. This means that a dialog box cannot be maximised, minimised or re-sized. %sy is used to change the style of such a dialog box. The list includes options for changing the border of the window. This refers to the space that, by default, is provided by ClearWin+ to surround the text and controls within a window (as in %bd). Do not confuse this border with the frame of the window that is determined by the Windows API style. At least one of the following options must be included:

no_border | Removes the white border - like %ww[no_border]
thin_border | Produces a half-size white border.
3d | Provides a three-dimensional style for subsequent controls in the window (see below).
3d_thin | Like 3d but provides a Windows 95 style edge for controls.
3d_raised | Like 3d but provides a raised thin edge for controls.
3d_depressed | Like 3d but provides a depressed thin edge for controls.
no_sysmenu | Omit the box at the top left which can be used to produce the system menu.
independent | Makes the window independent of other windows in the program that are already open. This can be used to create several windows between which the user can move at will (that is, there is no implied window hierarchy in this case).
toolwindow | Prevents the window from appearing in the windows taskbar and hides it from the windows that appear when the user presses Alt+Tab.

 | The 3d style has an effect on the position of subsequent controls and must be used before the controls are defined. Some controls are not affected (for example, buttons are not changed). The window is created using the standard button face colour for its background with the controls appearing in relief. With %sy[3d], by default %ob boxes are given the scored property provided the raised and depressed properties are not used with %ob. %ob[shaded] boxes are rendered as %ob[depressed] boxes.
See also | %ww


%sz

Purpose

To size a window.

Syntax

winio@('%sz', width, height)
integer width, height (input/output)

Description

width and height are variables whose current values specify the pixel width and height of the window. When non-zero values are supplied, these are used to specify the initial width and height of the window. If the window is re-sized (see %ww) then the variables width and height are automatically updated accordingly.

Alternatively, if zero values are supplied, the window is given a default size that suits its contents. width and height will be updated to these values and will also be changed when the window is re-sized. If code is added to save these settings, then the values can be used when the same window is next opened.

Special values are used to represent a maximised window. Consequently, if the dimensions of a maximised window are saved and used to re-open the window, the window will be restored in its maximised state.

See also

%sp


%ta

Purpose

To skip to the next tab stop.

Syntax

winio@('%nta')

Description

Tab stops can be used for text and for controls. Default tab stops are at 8-average character width intervals. The default settings can be changed by using %tl.

n is an optional positive integer which defaults to 1. It provides an alternative to multiple consecutive applications of %ta.

Example

winio@('%3ta')

See also

%tl


%tb

Purpose

To insert a bitmap button or toolbar.

Syntax

winio@('%tb', off, on, down, stat_ctrl)
winio@('%~tb', off, on, down, disab, stat_ctrl, grey_ctrl)
character(*) off, on, down, disab (input)
integer stat_ctrl,grey_ctrl (input/output)
winio@('%n.mtb', . . . )

Modifiers

Tilde (~) - adds a grey control option.

Caret (^) - the call-back function is called when the user clicks on the button. The function name is added to the end of the list of arguments for a given button.

Question mark (?) - A help string for each button is placed in order (in square brackets) after 'tb'.

Description

This control has been superseded by %ib which in turn has been superseded by %mb. For new code consider using %mb instead.

off, on, down and disab provide the names of bitmap resources through a resource script.

stat_ctrl is set to 1 when the button is on and to 0 when the button is off.

grey_ctrl is set to 1 when the button is enabled and to 0 when it is disabled (greyed).

n and m are optional and both default to 1. When n is used .m is optional. These provide for a toolbar n buttons wide and m deep. A full set of arguments are required for each button (scanning in order across the rows of buttons) using the same order of arguments as for a single button.

For further information see Tree-view.

Notes

Bitmap resource names can be constructed from known Windows (integer kind=7) handles (see Using the handle of a resource).

Example

winio@('%tb', 'off', 'on', 'dwn', stat)
off BITMAP bt1.bmp      (resource file)
on  BITMAP bt2.bmp
dwn BITMAP bt3.bmp

See also

%bt, %tt, %ga, %bx, %ib, %mb


%tc

Purpose

To set the colour of subsequent text.

Syntax

winio@('%tc[colour]')
winio@('%tc', rgb_value)
integer rgb_value (input)

Modifiers

Grave accent (`) - used with an integer argument in order to set the text colour for %eb (see Colouring the text and background).

Description

colour must be one of black, white, grey, red, green, blue and yellow.

rgb_value is typically obtained by a call to RGB@. Using the value (-1L) resets the colour of subsequent text to its default value.

Notes

The text colour for a given control can be changed dynamically (after the window has been created) by calling the subroutine SET_CONTROL_TEXT_COLOUR@.

Example

winio@('%tc[red]')
winio@('%tc', RGB@(200,200,0))

See also

%fn, %ts, %bf, %it, %ul, and the Windows API call GetSysColor(COLOR_WINDOWTEXT)


%th

Purpose

To provide "tooltip" help.

Syntax

winio@('%th[options]', ctrl)
integer ctrl (input)

Modifiers

Grave accent (`) - provides "What's this" style context sensitive help.

Description

%th specifies that help strings will appear in volatile rectangular boxes adjacent to the associated control when the mouse is over the control. There is a programmed delay before the help string appears. ctrl is set to 1 to make the help tooltip visible and zero to hide it.

If a grave accent modifier is used, a question mark button appears on the caption bar of the window. When the user clicks on this button, the mouse cursor changes to an arrow with a question mark. If the user then clicks on a control that has help information, the above tooltip help window pops up.

You cannot use %th and %`th is the same window.

A window that uses %`th cannot have a maximise button or a minimise button.

The option [at_cursor] causes the tooltip to be displayed relative to the current mouse position rather than relative to the control.

The option [no_callback_hide] prevents the tooltip from being hidden when a callback function is called. The default action is for the tooltip to be hidden whilst the callback is invoked.

The option [delay] allows you to set the time interval between the mouse entering a control and a tooltip appearing. An additional integer argument provides the delay in milliseconds. For example,
winio@('%th[delay]', 1, 500)
specifies a 1/2 second delay. The default is 1500ms.

The option [ms_style] provides for a Microsoft style tooltip. It also allows you to change the tooltip text at run-time using the routine SET_TOOLTIP_TEXT@

The option [balloon] provides a tooltip in the shape of a balloon.

When used with a grave accent, [ms_style] provides context sensitive help with the conventional Microsoft appearance.

See also

%he, CHANGE_HELP_TEXT@


%ti

Purpose

To provide a taskbar icon in the system tray.

Syntax

winio@('%ti[icon_name][tooltip]',cb_func)
external cb_func

Description

Under Windows 95/NT 4.0 (and later operating systems) there is a region on the taskbar (sometimes erroneously called the "system tray") to the right where some programs place an icon - usually because they are in a quiescent state. This area is typically used by the modem, speaker volume control, and clock. These icons usually display some text if the mouse is placed over them and respond to mouse clicks by becoming active in some way. Win32 ClearWin+ programs can use this area via the %ti format code.

This format takes two standard strings (the icon resource and help text respectively) and a call-back function. The call-back function will be called for all mouse actions over the taskbar icon. The different mouse actions can be distinguished by using CLEARWIN_STRING@('CALLBACK_REASON').

Typically, the call-back function should respond to clicks (or perhaps double clicks) only. A window containing a %ti format will be invisible apart from the taskbar icon, so there is no point in adding other controls to a %ti window. However, in other ways a %ti window is analogous to an ordinary window. In particular, if the call-back function returns a zero or negative number, the window will close and the icon will be removed from the taskbar. Closure can also be effected using %lw by setting the associated control variable to a zero value and passing it to WINDOW_UPDATE@.

Notes

icon_name can contructed from a known Windows (integer kind=7) handle (see Using the handle of a resource).

Example

winio@('%ti[my_icon][Click here]',cb)

Within the call-back function:

IF(clearwin_string@('CALLBACK_REASON').EQ.'MOUSE_LEFT_CLICK')THEN
 . . .
 cb=0
ENDIF


%tl

Purpose

To set up tab locations for use with %ta.

Syntax

winio@('%Ntl', pos1, pos2, . . . , posN)
integer pos1, pos2, . . . , posN (input)
winio@('%N`tl', pos1, pos2, . . . , posN)
double precision pos1, pos2, . . . , posN (input)

Modifiers

Grave accent (`) - use real rather than integer values.

Tilde (~) - list of tab locations is replaced by a single array

Description

Tab positions are measured in average character widths. All values are measured from the left-hand edge of the window. Each %tl maintains its effect until the next %tl. Use %ta to move to the next tab position.

Example

winio@('%3`tl', 10.5D0, 20.5D0, 30.5D0)

See also

%ta, %ap, %ob


%ts

Purpose

To set the text size.

Syntax

winio@('%ts', size)
double precision size (input)

Description

size is the scaling factor that defaults to 1.0. Values between zero and 1.0 cause the font to be scaled down. Values greater than 1.0 cause it to be scaled up. The default can be restored by using a size of 1.0 or by using %sf.

%fn must be used before %ts because the standard font cannot be scaled.

Notes

CLEARWIN_INFO@('SYSTEM_FONT_HEIGHT') returns the height of the standard system font in logical units. This can be used to detect whether the user is has set the Control Panel, Display Properties to Small Fonts (=16) or Large Fonts (=20) or Other...

Example

winio@('%ts', 1.5D0)

See also

%sf, %fn, %tc, %bf, %it, %ul


%tp

Purpose | To provide a text parameter to a parameter block.
Syntax | winio@('%tp[Item Name]', CURRENT) CHARACTER(*) CURRENT
Modifiers | ? - provide help after first string
Description | %tp is designed to be used with %pb
See also | %pb, %dp, %fp, %ep, %up


%tt

Purpose

To insert a textual toolbar.

Syntax

winio@('%tt[button_text]')
winio@('%~tt[button_text]', grey_ctrl)
integer grey_ctrl (input)

Modifiers

Tilde (~) - adds a grey control.

Grave accent (`) - specifies that this is the default button.

Question mark (?) - the help string is placed in square brackets after [button_text].

Caret (^) - the call-back function is called when the user clicks on the button.

Description

%tt is similar to %bt but provides a button that is not as deep and whose width is rounded to one of a set of standard sizes.

button_text is a standard character string (can be replaced by @).

%tt is typically used with %ww[no_border] and/or %bx.

To change the text dynamically use %lc and CHANGE_BUTTON_TEXT@.

Example

winio@('%?^tt[Cancel][Help text...]',cb_func)

See also

%bt, %ib, %tb, %bx


%tv

Purpose

To insert a hierarchical tree.

Syntax

winio@('%N.Mtv[options]', tree, nitems, sel)
character(*) tree(nitems) (input/output)
integer nitems (input parameter)
integer sel (input/output)
winio@('%`N.Mtv[options]', tree, nitems, sel, icon_str)
character(*) icon_str (input)

Modifiers

Grave accent (`) - for programmer supplied icons.

Caret (^) - call-back function that is called when the user selects an item.

Description

This format has been superseded by %bv. For new code consider using %bv instead.

N and M are not optional and specify the width and depth of the area in average characters.

tree is a character array of nitems.

sel is the index of the item selected by the user.

icon_str is a character string giving a list of icon resources in the form 'icon1,icon2'.

options can take the keyword fixed_font which causes the control to use a fixed font for the names of the tree nodes. This can be useful in cases where the node names are intended to line up. options can also take the keyword keep_focus to prevent the focus from shifting from the selected item. This is similar to the effect produced by a list box.

If variable_size is included as one of the options, nitems is treated as a variable that subsequently can be modified and updated by a call to WINDOW_UPDATE@. However, the size cannot be increased above its initial value. Since blank elements in the input array are ignored, the only reason to use this feature is to reduce the processing time (and therefore possible flicker) when using a very large array, most of whose elements are blank.

For further details see Tree-view.

Notes

Icon resource names can be constructed from known Windows (integer kind=7) handles (see Using the handle of a resource).

Example

winio@('%^`20.16tv',tree,15L,sel,'cl_book,op_book',cb)
cl_book ICON book1.ico      (resource file)
op_book ICON book2.ico

See also

%bv, %ls, %ms, %pb, %ps, SEE_TREEVIEW_SELECTION@


%tx

Purpose

To display an array of text with attributes in a rectangular region.

Syntax

winio@('%N.Mtx[options]', text, attrib, ncols, mrows)
character text(ncols,mrows) (input)
character attrib(ncols,mrows) (input)
integer ncols, mrows (input parameter)

Modifiers

Caret (^) - the call-back is called when a keyboard character is pressed and the control is in focus. The program can then update the text array.

Description

The text array text is displayed in a box with ncols columns and mrows rows. Initially only N columns and M rows are visible and a scroll bar is provided.

Attributes for each character are provided through the array attrib, with each character set to a colour index value in the range 0 to 255. Colour indexes are defined in order by (%tc, %ty) format pairs. %tx can be preceded by a pivot (%pv).

options can include:

full_mouse_input | The call-back function is called whenever the mouse moves over the control.
full_char_input | The call-back function is called for each key-press and each key release using Micosoft VK_ parameters.
use_tabs | Pressing the tab key does not move to the next control; instead, a tab key press is available to the %tx call-back.
no_popup_menu | Used to disable %pm within this control and to make the right mouse click available to the this control if required.

See Text array for further details.

Example

winio@('%^60.15tx', text, attrib, 80, 20, cb_func)

See also

%eb


%ty

Purpose

To set the background colour in a text array.

Syntax

winio@('%ty[colour]')
winio@('%ty', rgb_value)
integer rgb_value (input)

Description

colour must be one of black, white, grey, red, green, blue and yellow.

rgb_value is typically obtained by a call to RGB@. Using the value (-1L) resets the colour of subsequent text to its default value.

Notes

%ty codes are paired with %tc codes with %ty providing the background and %tc the foreground to a %tx.

Example

winio@('%60.8tx&',text,attr,80L,10L)
winio@('%tc[blue]%ty[red]%tc[yellow]%ty[green]')

See also

Text array - %N.Mtx[options]


%ud

Purpose

To provide a user data for a control.

Syntax

winio@('%ud', loc(data1))

Description

%ud allows user data to be associated with a given control. It can be useful when inside a callback to be able to retrieve data that is not directly a property of the control. For example, if you have buttons that launch reports you may want to store details about which report to run with the button. %ud allows you to do this. %ud takes an INTEGER(7) argument that is the location of the associated data. It works like %lc in that it relates to the previous control in the winio@ list.

The address of this data can be retrieved by calling CLEARWIN_INFO@ or by calling GET_USER_DATA@. A call to CLEARWIN_INFO@ can be made from within a callback function for the associated control. It takes the form

INTEGER(7) addr
addr = CLEARWIN_INFO@("USER_DATA")

If %ud is placed before any controls then that data relates to the window itself. This data can be retrieved by using CLEARWIN_INFO@("USER_WINDOW_DATA").

See also

GET_USER_DATA@, SET_USER_DATA@


%ul

Purpose | To switch to underlined text.
Syntax | winio@('%ul')
Modifiers | Grave accent (`) - switches off underlined text.
Description | %ul is cancelled by %`ul and %sf.
See also | %bf, %it, %sf


%up

Purpose | To provide a user callback to a parameter block.
Syntax | winio@('%up[Item Name]', CB_FUNC) EXTERNAL CB_FUNC
Modifiers | ? - provide help after first string
Description | %up is designed to be used with %pb
See also | %pb, %dp, %fp, %tp, %ep


%uw

Purpose | To allow Windows API code to be interfaced to ClearWin+.
Syntax | winio@('%uw[class]', width, height, style, xstyle, hwnd) integer width, height, style, xstyle (input) integer(7) hwnd (output)
Description | class is the name of a registered class with its own Windows procedure. width and height define the dimensions of the window in pixels. style is the Windows style (WS_CHILD is automatically included with style). xstyle is the extended Windows style (typically zero). hwnd is returned as the handle of the resultant child window.
See also | %cw


V

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


%vx

Purpose

To attach a vertical scroll bar to the next control.

Syntax

winio@('%vx', page_step, max_val, cur_val)
integer page_step, max_val (input)
integer cur_val (input/output)

Modifiers

Caret (^) - the call-back is called when the user clicks on the scroll bar.

Description

cur_val is the value that corresponds to the position of the scroll box (also called the thumb). It returns a value between zero and max_val - 1.

page_step is the amount that cur_val is to be increased/decreased when the user clicks on the scroll bar (other than on the thumb). For a document, page_step will be set to the number of lines that are to be displayed in the window and max_val should be set to n - page_step, where n is the total number of lines in the document.

With %hx and %vx the three arguments cur_val, page_step and max_val can be passed as variables and changed dynamically with a call to window_update@.

A call to CLEARWIN_INFO@('INTERMEDIATE_SCROLL') will determine if the callback was called whilst the thumb was moving. A return value of 1 indicates movement whilst zero indicates that the thumb is stationary. Both of these events occur at the end of a move.

%hx and %vx should not be used with controls like %eb and %cw which have their own scroll bar mechanism.

Example

winio@('%^vx', 5L, 20L, pos, cb_func)

See also

%hx


%wb

Purpose

To provide an interface to Internet Explorer.

Syntax

winio@('%N.Mwb[resource_or_url]')

Description

Provides direct access to the Microsoft Internet Explorer engine. This means that, unlike %ht, %wb can use any form of script provided only that it could be viewed in Internet Explorer. As with %ht, the basic form for %wb is:

winio@('%N.Mwb[resource_or_url]')

N and M provide the dimensions in the same way as for %ht.

Within the square brackets you can provide a URL, for example [http://forums.silverfrost.com/index.php] or [file://C:\MyDir\Myfile.html] or [file://C:\MyDir\Myfile.html#MySection].

For access to a document (MyDoc.htm) within a .chm file (MyChm.chm), the URL would take the form:

[its:C:\\MyDir\\MyChm.chm::MyDoc.htm]

Alternatively you can provide the name of an HTML resource within the square brackets, for example [myhtml] together with a resource script containing a line of the form:

myhtml HYPERTEXT "C:\MyDir\Myfile.html"

For third-party compilers use HTML in place of HYPERTEXT.

There are a list of standard callbacks associated with %wb

"wbCopy" | Copy the selected text to the clipboard
"wbSelectAll" | Select all the text
"wbSaveAs" | Open a "Save As" dialog
"wbOpen" | Open a dialog to navigate to a chosen URL
"wbGoForward" | Revisit a page after going back
"wbGoBack" | Revisit the previous page
"wbGoHome" | Go to the IE "Home" URL on the current machine
"wbRefresh" | Refresh the current page
"wbStop" | Stop an ongoing action (e.g. downloading)
"wbHistory" | View a dialog showing the page history in the current session in order to revisit a chosen page

The function wbCommand@ that can be used to navigate to a given URL or to directly call one of the above %wb standard callbacks.

%wb can take a callback function that is called before every URL navigation. The CLEARWIN_STRING@ "CALLBACK_REASON" is "HYPERTEXT_LINK" at which point the CLEARWIN_STRING@ "CURRENT_URL" provides the URL. The callback should return the value 2 in order to complete the navigation. Alternatively the value 3 will cancel the navigation and can be used to perform some other task in response to the hyperlink.

Unlike %ht, a given window can contain more than one %wb control.

%wb is much more versatile than %ht. When compared with %ht, its only limitation is that images can not be embedded within a resource script and must be provided either as external files or as direct data. See for example http://www.websiteoptimization.com/speed/tweak/inline-images/ which provides a markup of the form...

<img src="data:image/gif;base64, ...raw data inserted here..." width="16" height="14" alt="embedded folder icon">

Depending on the operating system, the internal dialog for "wbHistory" may look better when you include a standard manifest file in your resource script...

1 24 default.manifest

Example | program WebPage use clrwin integer iw integer,external::cbForum,cbWeb iw=winio@("%ww[no_border]%ca[New HTML]&") iw=winio@("%pm[Back,Forward,History,Copy,Forum]&", & & "wbGoBack", "wbGoForward", "wbHistory", "wbCopy", cbForum) iw=winio@("%pv%60.30^wb[http://www.silverfrost.com]", cbWeb) end integer function cbForum() use clrwin integer r r = wbCommand@("http://forums.silverfrost.com") cbForum = 2 end function integer function cbWeb() use clrwin character(len=256)::reason,url reason = clearwin_string@("CALLBACK_REASON") url = clearwin_string@("CURRENT_URL") print*, reason(1:len_trim(reason)), " = ", url(1:len_trim(url)) cbWeb = 2 end function
See also | %ht


%wc

Purpose | To display a character.
Syntax | winio@('%wc', ch) character ch (input)
Description | See Data output.


%wd

Purpose | To display an integer.
Syntax | winio@('%wd', v) integer v (input)
Description | See Data output.


%we

Purpose | To display a real value.
Syntax | winio@('%we', v) double precision v (input)
Description | See Data output.


%wf

Purpose | To display a real value.
Syntax | winio@('%wf', v) double precision v (input)
Description | See Data output, %wf specifics.


%wg

Purpose | To display a real value.
Syntax | winio@('%wg', v) double precision v (input)
Description | See Data output, %wg specifics.


%wi

Purpose

To allow interactive window design.

Syntax

winio@('%wi', ID)
integer ID (input)

Description

%wi enables the user to adjust and fix the exact position and size of every item in a window. %wi provides a window with a unique user ID (for example, the value 10). The designed windows are stored in a .rcx file.

iw = winio@("%wi&", 10)

You enter a design mode by adding a tilde modifier (~), removing it to lock the design when finished:

iw = winio@("%~wi&", 10)

When you run the application with the tilde applied, you will be able to select items with a mouse click and move them by dragging. If the Ctrl key is held down when clicking on an item then it remains selected and its size and position can be changed by using the arrow keys:

  • Right arrow - move to the right one pixel
  • Left arrow - move to the left
  • Up arrow - move up
  • Down arrow - move down

With the Ctrl key applied:

  • Right arrow - increase the width
  • Left arrow - decrease the width
  • Up arrow - increase the depth
  • Down arrow - decrease the depth

With the Shift key applied, the pixel change is increased from 1 to 10. New controls can be dropped on to the window by selecting from a (right click) menu. These can be resized and repositioned. Also their properties can be changed from a one of three property dialogs:

  1. properties that are common to many controls. This includes the selection of a callback function, setting text attributes, providing a "help" string, etc. (open this via the Ctrl+P accelerator key).
  2. for each control for properties that are not common. For example, for an integer edit box you can choose the integer variable to associate with the control (open this via the RETURN accelerator key).
  3. properties of the control in response to the main window being resized (cf. %pv format code). This allows you to choose one or two "anchor" points at the corners of a control. A corner that is anchored maintains its margin with respect to the main window as it is resized (open this dialog via the Ctrl+R accelerator key).

With the controls defined in a .rcx resource script, the only remaining requirement is to pass the associated variables so that the window can be linked up with the Fortran code. For example, a %rd format code has an associated integer variable (N say) where the result is stored. Now that %rd appears in the resource script and not in a winio@ call, we need an independent way to pass N. New format codes are provided for this purpose:

iw = winio@("%qd[N]", N)

%qd is the new format code and [N] provides the name of the variable as it appears in the design process and in the resulting .rcx resource script. It is natural to use N as the name of the variable N provided that it is unique when designing, but any name can be used.

Other similar codes are illustrated by:

iw = winio@("%qf[X]", X) !double precision X
iw = winio@("%qs[STR]", STR) !character variable STR
iw = winio@("%qc[CB]", CB) !callback function CB
iw = winio@("%qh[HWND]",HWND) !Microsoft HANDLE HWND
iw = winio@("%12qd[ARR]",ARR) !an array of integers ARR(12)
iw = winio@("%*qd[ARR]",N,ARR) !an array of integers ARR(N)
iw = winio@("%12qs[STR]", STR) !a character variable array STR(12)
iw = winio@("%*qs[STR]", N,STR) !a character variable array STR(N) When designing, you will be able to link to any of the variables that have been predefined in this way. In addition you can link to any images that are already present in an associated .rc resource script (or the RESOURCES block of the FTN95 code).

You can test a design without exiting design mode. Use the accelerator key Ctrl+T in order to run another instance of the application in its finished (not designing) state. The new instance will start up on top of the design window. Be careful to shut down the test before going back to designing.

When designing, you can allocate a popup menu to a given control. For this purpose, a new mechanism is provided for defining a menu via calls to winio@...

%qi defines a named menu item together with its caption, callback and other attributes. %qm takes a list of these names and groups them together to form a popup menu. Adding a grave accent, %`qm, allows you to provide a caption to the list with the result that a popup menu becomes a "submenu". %qm can then be used to form the various kinds of menu that are needed as illustrated here: iw = winio@("%~#?qi[iOpen][Open a file]", "Open", enable, check, cb)
[iOpen] | iOpen is the design name of the item
[Open a file] | the help string (optional with the ? modifier)
"Open" | the caption for the menu item
enable | an integer variable controlling the grey state (optional with the ~ modifier)
check | an integer variable controlling the check state (optional with the # modifier)
cb | the associated callback function

iw = winio@("%qm[Pop1]&", "iCopy,iPaste")
Pop1 | the name of the popup menu as it appears when designing
iCopy | the name of an existing "Copy" menu item
iPaste | the name of an existing "Paste" menu item

The name #pm in %qm[#pm] is reserved and used to define the main popup menu (cf. %pm). The name #sm in %qm[#sm] is reserved and used to define the systems menu add-on (cf. %sm). The name #rm in %qm[#rm] is reserved and used to define the systems menu replacement (cf. %`sm).

A main menu can be defined like this: w = winio@("%`qm[sm1]&", "File", "iOpen,|,iExit")
iw = winio@("%`qm[sm2]&", "Edit", "iCopy,iPaste")
iw = winio@("%qm[#mn]&", "sm1,sm2") %`qm[sm1] provides a submenu, with name sm1, caption "File", and item list "iOpen,|,iExit". The pipe symbol "|" provides a menu separator. #mn is the reserved name for the main menu constructed from the list "sm1,sm2" of submenus (cf. %mn).

Enhanced menu are available as before by using %em and by adding the name of an icon to a menu item caption.

Dynamic menus (where items are added at runtime by calling add_menu_item@) are constructed by using a %qi item name that begins with an asterisk. For example the following uses the name *Extn: integer(7) hMenu
iw = winio@("%qi[*Extn]&", hMenu)
iw = winio@("%`qm[sm1]&", "File", "iOpen,|,*Extn,|,iExit")
...
call add_menu_item@(hMenu, "File name 1", 1, 0, cb1)

Some additional points:

  • Multiple items can be selected by holding down the Ctrl key.
  • To resize the main window, you must now select "Resize the design" from the popup menu. Then the main window is given a thick frame which temporarily allows resizing
  • A toolbar appears above the window and this allows you to take various actions. A right mouse click provides the same actions via a popup menu. For example, if a single item is selected then "Align right" will move that item to the right hand (%bd) border. Whilst if multiple items are selected then "Align right" will align all of the items with the first item that was selected.
  • The main window can be resized or moved but only its size is retained in the design. Use a right mouse button click and select "Resize design" to enable resizing.
  • The height of a list box or a combo box cannot be adjusted in this way.
  • %mb toolbars (see below) cannot be moved.
  • Some items necessarily have a fixed width and height.
  • A design session is ended by closing the window, using the x icon in the top right corner. You are prompted to save your changes. The accelerator key Ctrl+S also provides a "save" action, whilst Ctrl+Z ends the session. If your executable is named myapp.exe then design data is saved in a text file called myapp.rcx with the same path.
  • When the design is complete, the ~ must be removed and the .rcx file may be added to the executable as a "LAYOUT" resource. RESOURCES
    1 LAYOUT "myapp.rcx"     The value 1 and the keyword LAYOUT may not be changed.
  • It is recommended that you use the tilde modifier with only one %wi window at a time and particularly when a window is a %sh child sheet for a %ps tabbed control. For %ps, you can apply the %~wi to the main window in order to set its position and size. Then (with %wi in the main window) use %~wi on any one of the %sh sheets in order to design the contents of any of the sheets.
  • If you want to add more items to a window after initial designing, then it is necessary to give each new item a unique ID using a new format code %ci, otherwise the existing design data will not apply. For example... iw = winio@("%ci&", 100)
    iw = winio@("%bt[OK]&, cb)     gives this button the ID value of 100. Auto-generated IDs start at the value 300 so these must be avoided. Alternatively new items and text can be added to the end of the winio@ list.
  • All positioning format codes such as %nl, %ff, etc. become redundant after designing and %ob/%cb box formats have limited use.
  • %wi cannot be used with a MDI %fr and is unlikely to be useful if the window can be resized at runtime.
  • A new format code %gb[Group name] is available for use with %wi. It provides a group box that is similar to a single %ob/%cb. For example.. iw = winio@("%gb[Group name]", wd, ht) where wd and ht are integer values that provide the initial (pre-design) pixel width and height. The %gb font, font size and font colour can be set in the usual way but a %`bg background colour will only be applied to the group title.

See also

%gb

Notes

Added to FTN95 at version 8.20


%wp

Purpose

To supply the name of a wallpaper bitmap.

Syntax

winio@('%wp[bitmap_name]')

Modifiers

Grave accent (`) - ensures that, if necessary, the window is expanded to hold at least one copy of the bitmap.

Tilde accent (~) - plain text placed on top of the wallpaper will be transparent. In other words the text will have the wallpaper as background.

Description

bitmap_name is a standard character string (can be replaced by @). The bitmap is used as a back drop to the contents of the window and, if necessary, is repeated horizontally and vertically to fill the space.

Example

winio@('%wp[wallpaper]')
wallpaper BITMAP file.bmp      (resource file)

See also

%bg


%ws

Purpose | To write a string.
Syntax | winio@('%ws', s) character(*) s (input)
Description | See Data output.


%ww

Purpose

To change the style of a window.

Syntax

winio@('%ww[options]')

Description

By default, a format window that uses neither %ww nor %sy has a caption bar but does not have: a) system menu, b) a minimise box and c) a maximise box. Such a window has a double frame that is raised.

%ww is used to change the style a window. If %ww is used without any of its options, the resulting window has a caption bar that includes: a) system menu, b) a minimise box and c) a maximise box. Such a window has a single frame that is not raised.

The list of options given below includes options for changing the border of the window. This refers to the space that, by default, is provided by ClearWin+ to surround the text and controls within a window (as in %bd). Do not confuse this border with the frame of the window that is determined by the Windows API style.

A window that uses %ww can be re-sized if a pivot (%pv) is also included.

options can be one or more of:

no_caption | Omit the caption from the window.
no_maxminbox | Omit the maximise and minimise boxes from the window.
no_maxbox | Omit the maximise box.
no_minbox | Omit the minimise box.
no_sysmenu | Omit the box at the top left which can be used to produce the system menu.
no_border | Omit the blank border which normally surrounds the window contents, but leave the frame itself. Using this format you can, for example, force a tool bar (textual or bit-mapped) to be placed immediately beneath the menu.
thin_border | Produces a half-size white border.
no_frame | Omit the window frame and the blank border which normally surrounds the window contents. This option is particularly useful with certain types of child window.
no_edge | This option is like no_frame except that it leaves the default border i.e. an empty space around the edge of the window.
naked | Equivalent to no_frame with no_border and no_caption.
volatile | The window closes when the focus is lost.
inactive | Disables the window.
invisible | Hides the window.
fixed_size | Prevents the user from resizing the window.
not_fixed_size | Allows the user to resize the window. Provides an alternative to %pv which implies not_fixed_size.
topmost | Forces the window to stay on top, even if another application gets control. This is sometimes useful when it is necessary to execute another application without the user losing sight of the window of the main application.
maximise (or maximize) | Displays the window as a maximised window.
minimise (or minimize) | Displays the window as a icon.
super_maximise (super_maximize) | Displays only the client area (requires an accelerator key attached to the Escape key that restores the normal window).
independent | Makes the window independent of other windows in the program that are already open. This can be used to create several windows which the user can move between at will and where there is no implied window hierarchy.
toolwindow | Prevents the window from appearing in the windows taskbar and hides it from the windows that appear when the user presses Alt+Tab.

Example

winio@('%ww[no_border, maximise]')

See also

%sy


%wx

Purpose | To display a hexadecimal value.
Syntax | winio@('%wx', v) integer v (input)
Description | See Data output.


Using dialog resources

This section contains a concise guide on how to use the %di format code. It assumes that you are already familiar with format windows and the winio@ function.

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

The format code %di enables you to use a dialog resource created with a resource editor such as that provided by Microsoft Visual Studio. A dialog is designed visually and saved in the form of a .rc resource script and a .h header file. The script can be used in a WINAPP statement or as FTN95 RESOURCES and the header file is converted to Fortran and used as a INCLUDE file in the program. A utility called fParam.exe provides this conversion.

In ClearWin+, a dialog resource provides the following:

  1. the caption for the window,
  2. the initial font,
  3. the dimensions of the dialog and the position of all controls,
  4. all static text,
  5. all bitmaps and icons (as references to other items in the resource script).

%di takes one integer argument which is a dialog indentifier in the resource script. It also modifies the use of a subset of ClearWin+ formats such as %rd, %rb and %ls. These appear after %di and each one takes an additional integer argument which is the identifier of a control in the script. This additional argument is always the first argument for the format code. The subset of ClearWin+ formats is listed under Resource components.


What you need

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

In order to use the %di format code you will need the following tools and components:

  1. A resource editor such as that provided by Microsoft Visual Studio.
  2. The Microsoft version of the header file called windows.h.
  3. A copy of the Silverfrost resource compiler SRC (included with FTN95).
  4. A copy of the Silverfrost C header file commctrl.h.

It is recommended that you begin with the given set of samples that illustrate the use of %di. This concise guide is provided as a supplement to these samples.


Getting started

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

  1. Ensure the FTN95 utilities and examples components are installed. By default these are installed in the 'FTN95 Examples' folder inside your standard Windows documents folder.
  2. Use the sample in the subdirectory clearwin\di\s1Start.
    Open resource.rc using your resource editor.
    If you want to add more buttons etc. use the default control identifiers provided by Visual Studio. These take the form IDOK, IDCANCEL, IDB_BUTTON1 etc. which represent integers defined the a header file. Some of these appear in windows.h (and windows.ins). Use the default IDC_STATIC identifier for static text.
  3. Open dialog.f90 in your text editor.
  4. Build the executable using the supplied build.bat.


How %di works

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

%di causes ClearWin+ to load the resource and extract initial information such as the caption and the initial font. When the window is fully defined in the program (at the end of a winio@ statement with no continuation symbol), ClearWin+ merges the information in the program with that provided in the resource.

All the static information is contained in the resource, whilst the program contains details of those controls that need to use variables. For example, a simple Edit Box can be included in the resource and linked via its identifier to (say) a %rd format in the program. %rd requires an integer variable to hold the result. The position and dimensions of the control are defined in the resource so %rd simply links the control identifier to a variable in the program.

ClearWin+ initially makes no distinction between a window that uses %di and one that does not. In both cases it determines the position of each piece of text and each control on the fly as the components are added. When the window description in the program is complete, %di repositions existing components and adds additional components from the resource. The ordering of these components is given by the order in the program followed by the order in the resource (i.e. those items in the resource that are not found in the program). The latter order can be seen by reading the text of the resource script or by using the menu item "Layout" followed by "Tab Order" in the Dialog resource editor. This order does not affect the positioning of the text and controls in the resulting dialog but may be significant if a particular control ends up either partially or totally hidden by other controls. For example, this might happen if you place one Group Box on top of another.


The %di format in detail

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

In what follows id is used to represent an integer control identifier expressed in the dialog editor in the form IDC_STATIC, IDC_BUTTON1 etc. and accessed in the program via an INCLUDE statement.

Components 1 to 5 below appear only in the dialog resource editor. That is they appear in the resource script and not in the program code.

  1. The caption and intial font
    These are provided in the Properties of the dialog.
  2. Text
    Text is inserted using Static text components. The current font is used unless the text is given a unique id and a string resource is provided with the same id. Here is an example of such a string:

    Times New Roman,12,(0,0,255),(0),Bold,Italic

    Items are separated by commas. The name of the font is optionally followed by the size in points then a triplet for the text colour and one for the background colour (a single zero represents the default); then optionally, in any order, Bold, Italic and Underline. These three are not case sensitive and only the first character is significant.
  3. Bitmaps, Icons, standard Icons and jpeg images
    Bitmaps and Icons must first be imported into the resource. For simpicity you can use the default id (IDB_BITMAP1, IDI_ICON1 etc.). You can then edit the dialog and select a Picture component from the Controls toolbox. Position this component in the dialog and use the default id for the picture (IDC_STATIC). Select the correct type (Bitmap or Icon) and select an image id (IDB_BITMAP1 etc) from the "Image" combobox. Standard icons are obtained by selecting an icon Picture component with id=IDC_STATIC. In the "Image" combobox enter one of the following numeric values.

    Value

    Symbol

    32513

    Stop sign

    32514

    Question mark

    32515

    Hazard sign

    32516

    Information sign

    32517

    Windows logo

    One way to import a jpeg image is to open the resource script as text and to type in:

      jpegname IMAGE DISCARDABLE "image.jpg"

    In the dialog editor, insert a Static Text component with the text set to %im[jpegname]. The simple Border style is automatically converted to the extended Client edge style. The simple Sunken style can be used to give a visual impression of the space used.
  4. Group Boxes
    These provide a visual effect only and are not referred to in the program code.
  5. Simple buttons that do not use a callback function or grey control.
    These need only appear in the resource. The "Tab order" is only significant when the value returned by winio@ is used to indicate which button was pressed on exit.
    Icons can be attached to buttons (equivalent to %bi) if the button is given an id that is identical to that of an icon in the resource script. To change the font or background colour you must include the %bt in the program and use %bc and %'bg.

    The following codes can be used with %di. With the exception of %sh and %sm, and the possible exception of %mn and %pm, it is recommended that %di should appear before all other format codes. Other arrangements may be possible but the outcome is reserved.

    In most cases %tc, %ts and %`bg can be used in the program to change the control text colour, text size and background colour. %`ts has been added. This takes no arguments and restores the text size to the size before the previous %ts.
    Except where stated, parameters in the program that determine the width and depth of the control are nolonger required. Additional styles and extended styles can often be added using the resource.
  6. An "Edit Box" component is used to link to the formats %rd, %rf, %rs, %re and %st
    The box automatically has a "Client edge" style and currently this cannot be switched off.
  7. A "Button" component is used to link to formats %bt and %tt that have a callback and/or a grey control.
    Other details are the same as for item 5 above.
  8. A "Radio button" component is used to link to the format %rb.
    Radio buttons can be ganged together (equivalent to %ga) by using the resource "Tab Order" and by marking the first button and the one after the last with the "Group" attribute. If one of the control variables is preset to 1 then the effect is the same as using %`ga (one control is always on). If all of the control variables are preset to zero then the effect is the same as using %ga.
  9. A "Check box" component is used to link to the format %`rb.
    Check boxes can be ganged together using the same technique as for radio buttons (see item 8 above).
  10. A "Listbox" component is used to link to the formats %ls, %ms and %pb.
    A string resource with the same id as a Listbox can be used the specify the entries in a %ls or %ms list. Here is an example:

      $Apples$Bananas$Oranges$Pears$

    The first character ($ in this example) denotes the item separator. A character array of suitable size must be declared in the program.
  11. A "Combobox" component is used to link to the formats %`ls and %el.
    The Combobox can be populated by using the Data tab in the Combo Box Properties dialog. Alternatively a string resource with the same id as a Combobox can be used the specify the entries in the list (as in a Listbox). A character array of suitable size must be declared in the program.
  12. A "Listview" component is used to link to the format %lv.
    A string resource with the same id as a Listview can be used the specify the entries in the list (as in a Listbox). A character array of suitable size must be declared in the program. The item separator for rows must be different from the item separator for columns.
  13. A "Treeview" component is used to link to the formats %bv and %tv (%bv is preferred).
    A string resource with the same id as a Treeview can be used the specify the entries in the list (as in a Listbox). A character array of suitable size must be declared in the program.
  14. A "Progress bar" component is used to link to the format %br.
    Changing the extended styles has no effect. See the note 7 for new options.
  15. A "Static Text" component is used to provide a place marker for the graphics format %gr.
    Give the component a unique id (IDC_STATIC1 etc.) and give it a simple border to visualise its dimensions. Set the text itself to %gr. The width and height of the region are nolonger included in the program but are specified in the resource. The program must respond to these values by supplying a start up callback %sc (say) in which the dimensions are obtained using CLEARWIN_INFO@('GRAPHICS_WIDTH') and CLEARWIN_INFO@('GRAPHICS_DEPTH'). The graphics image is drawn using these values. This is similar to the way in which the %gr option [user_resize] is used however in simple cases it is not necessary to attach a callback function to %gr.
  16. The scheme for %gr is also used for %og, %pl, %eb, %cw, %fr and %sl but in these cases the resizing is automatic.
    i.e. use "Static Text" with the text set to the format code. A slider is given a "Button face" background colour.
  17. A "Static Text" component is used to provide a place marker for the formats %ib, %tb, %eq, %cl, %tx, %gi and %ld.
    The scheme is the same as for %gr etc. but in these cases the width and height are fixed. In the case of %tx, you must provide all of the usual arguments in the program as well as the id.
  18. A "Static Text" component with the text set to %he is used instead of %he in the program to mark the position, width and height of an Edit box for help text. %he cannot appear in the program and (if help strings are provided for controls and/or menu items) this component must appear in the dialog resource (unless %th is used). The Edit box might be shown in the form of a status bar at the foot of the dialog and given the sunken attribute (say) to make it visible.
  19. A "Tab Control" component is used to link to at upgraded version of the format %ps.
    The corresponding %sh dialogs are given the "Child" style in the dialog resource and %ca is used in the program (see Samples\s8tab). The name of an icon resource can be appended (following a back-slash) to the caption (e.g. %ca[Telephone\icon1]) and %?sh[Telephone numbers] gives a MS style tooltip for the sheet which becomes visible when the Tooltips style is selected. The size of each %sh dialog is set in the resource. The size of all the sheets can be made exactly the same by viewing and editing the resource script as text. By default the size of the %ps control is also set in the resource (see note 6).
  20. A "Static Text" component (with any text) can be linked with %wc, %wd, %we, %wf, %wg, %ws, or %wx in the program.
    Give the text a unique id and use the same id (before the usual argument) in the program.
  21. A "Date Time Picker" component can be linked to a new format %dt (see note 8).
  22. A "Month Calendar" component can be linked to a new format %mc (see note 9).


How to use %di with menus

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus/li>
  • Resource components for format codes
  • Notes

There is no change in the provision for %ac. These cannot be read from accelerator tables in a resource.

It is possible to use the existing mechanism to provide menus (%mn, %pm and %sm) or enhanced menus but only if the menu is fully defined before using %di. When using %mn in this way it is a good idea to add a dummy menu to the resource script and to attach this to the dialog in the Dialog Properties. In this way the positioning of dialog components will be correctly adjusted to allow for the menu bar.

A simpler approach for standard and popup menus (%mn and %pm) is to construct the menu in the resource editor as follows. This approach cannot be used for system menus (%sm).

For simplicity use the default id values that are automatically generated by the menu editor. Accelerator key information can be added after the item text by using a tab character (\t) and this information is automatically added to the accelerator key table (note that accelerator key action is not automatically disabled when the coresponding menu item is disabled).

Help strings can be inserted into the "Prompt" edit box.

A standard menu (%mn) constructed in this way must be attached to the dialog as one of the "Dialog Properties". The first use of %pm in the program code for a dialog must provide the menu identifier:

  wr=winio@('%pm&',IDR_MENU2)

In the menu editor, a popup menu must start with a dummy top level item (call this Pop1 etc., say). The actual popup menu will be the submenu of Pop1. (Note that you can use the right mouse button in the menu editor and select "View as popup" but this setting is neither appropriate nor helpful in this context.)

When a standard menu or popup menu is constructed in the resource, each menu item id must be linked to a callback function in the program. The structure of the menu and the item text are given in the resource.

In the program, %mn and %pm are used in a different way from normal. The format codes must appear after %di. Here is an example:

wr=winio@('%di&', IDD_DIALOG1)
wr=winio@('%mn&', ID_FILE_OPEN,open_cb)
wr=winio@('%~mn&',ID_FILE_SAVE,grey,save_cb)
wr=winio@('%`mn&',ID_FILE_EXIT,check,'EXIT')

In this context %mn and %pm always take an integer id and a callback function. The id must be unique to the memu item. Even if a popup menu item duplicates the action of a standard menu item, they must have different id values. This also applies to menus in different windows if an appliction has more than one window open.

A tilde (~) is added for a grey control variable and a grave is added for a check control variable.

A grey control must preceed a check control in the argument list.

A question mark can be added for help text as an alternative to using the menu resource.....

wr=winio@('%?mn[Quit the application]&',ID_FILE_EXIT,'EXIT')

A menu that is defined as a resource can also include small bitmaps. When used, the bitmap replaces the check mark in a menu item and normally has the same size (12x12 pixels for "Small Fonts" display). If the id is the same as the id for a bitmap in the resource then the bitmap is automatically loaded into the item.

Menu items defined in the program can be ommitted from all menu resources and dynamically inserted after the window has been defined. Two routines can be used in this context:

SUBROUTINE INSERT_MENU_ITEM@(text, progID, rscID)
INTEGER progID, rscID
CHARACTER(*) text

SUBROUTINE DELETE_MENU_ITEM@(progID,Before)
INTEGER progID,Before

text is the character string for the new menu item.

progID is the id corresponding to a %mn item in the program linking to a callback function and possibly grey and check controls. If progID=0 a separator is inserted.

rscID is the id of an item that is in the resource (this must not be a separator and the popup menu cannot be empty).

If rscID=progID then the item is replaced and its grey state is toggled only if it does not have a grey control. To delete a separator set Before=1 and set progID for the item after the separator otherwise set Before=0.

Accelerator keys, help strings and bitmaps can also be employed in this context.

One approach is to use a place marker in the resource which is initially greyed (e.g. it might be set in the resource to "Recent files"). For a place marker, use INSERT_MENU_ITEM@ with Insert=0 to change the first item added. Also, instead of removing the last of the items that have been added, use INSERT_MENU_ITEM@ again (with the text set for example to "Recent files") and disable the item.


Resource components for format codes

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

In the following table, a "Place marker" means Static text with the text set to the format code.

Format | Component
(Text) | Static text
(Bitmap) | Picture
(Icon) | Picture
(Box) | Group box
%br | Progress bar
%bt | Button
%bv | Treeview
%cl | Place marker
%cw | Place marker
%eb | Place marker
%el | Combobox
%eq | Place marker
%fr | Place marker
%gi | Place marker
%gr | Place marker
%ht | Not available
%ib | Place marker
%im | Place marker(includes the resource name)
%ld | Place marker
%ls | Listbox
%`ls | Combobox
%lv | Listview
%ms | Listbox
%og | Place marker
%pb | Listbox
%pl | Place marker
%ps | Tab control
%rb | Radio button
%`rb | Check box
%rd | Edit box
%re | Edit box
%rf | Edit box
%rs | Edit box
%sh | Child dialog
%sl | Place marker
%st | Edit box
%tb | Place marker
%tt | Button
%tv | Treeview
%tx | Place marker
%wc | Static text
%wd | Static text
%we | Static text
%wf | Static text
%wg | Static text
%ws | Static text
%wx | Static text


Notes

In this section:

  • Using dialog resources
  • What you need
  • Getting started
  • How %di works
  • The %di format in detail
  • How to use %di with menus
  • Resource components for format codes
  • Notes

  1. An important characteristic of dialog boxes is that their appearance and size depends on the user's desktop display properties. In particular, the end user can select "Small Fonts", "Large Fonts" or "Other" in the Advanced settings of the Display Properties. When a resource editor is used to design a dialog, the positioning of text and controls can be expected to be consistent whatever size of font is used except when the width and height of a component is fixed. Bitmaps, icons and toolbars are examples of components that have fixed dimensions.

  2. The requirement to specify a designated component type for each format code (in the table for resource components ) might be regarded as being unnecessary in the sense that, if a component has a unique id, then this is sufficient to link it to a format code in the program. However, this limitation is often required so that additional relevant styles and extended styles can be imported from the resource.

  3. Some format codes are not easy to use with the Microsoft dialog editor. More specifically, if a component has a fixed size which is not known to the dialog editor (e.g. a jpeg image), then some iteration is required to get the positioning correct. If you have access to a Spy utility then you can run your program and leave it running, using the Spy utility to get the required size and adjust the component in the design viewer accordingly. A similar problem arises if the font size of Static text is changed from the default size.

  4. Although the dialog resource editor displays a large number of style options for the dialog and its controls, in practise only a small number are relevant and useful. Be careful not to experiment by selecting a number of options at random without compiling and running the program after each change. It is possible to obtain a state where the dialog will not load, then back-tracking to a safe state might prove difficult.

  5. The introduction of the %di format has opened up a very large number of options to the ClearWin+ programmer, only a relatively small number of which can be tested before release. Please report any outcomes that are clearly wrong. In addition, some limitations have been imposed in the initial design of %di which can easily be removed if there is a demand. For example, it has been assumed that %di will not be used with a pivot (%pv). Otherwise %ww options like 'maximise' would become useful.

  6. With the introduction of %di, the property sheet format %ps has also been extended. In its new form it can take options which cause the Microsoft tab control to be used instead of the ClearWin+ property sheet control.
    The simplest of these options is %ps[ms_style] and this becomes the default when %ps is used with %di. If you want to use %di with the ClearWin+ control then you must put %ps[alt_style] in the program and the size of the control will be set by ClearWin+ rather than by the size in the resource. When using %di you simply set the styles in the editor and use only %ps (without any options) in the program. When not using %di, the following options are currently available:

    ms_style

    uses the Microsoft tab control

    bottom

    implies ms_style and puts the tabs at the bottom

    hot_track

    implies ms_style and the tab text changes colour when touched by the mouse

  7. Similarly two new options have been added for %br.

    smooth

    gives a smooth progress bar and is the default when %di is not used

    not_smooth

    gives a broken progress bar and is the default when %di is used,
    not_smooth has no effect when [percentage] is used.

  8. The "Date Time Picker" format %dt can only be used with %di.
    As well as an integer argument for the identifier, %dt takes an argument which is an integer array with 8 items (see Samples\s11date). This array contains the system time as follows:

    item 1

    year

    item 2

    month (January=1)

    item 3

    day of the week (Sunday=0)

    item 4

    day of the month

    item 5

    hour

    item 6

    minute

    item 7

    second

    item 8

    millisecond

    The array is automatically filled with the current date and time when the window is opened and the user can select a new date and time. %dt takes no options and can be used with the usual ? and ^ modifiers. Styles can be set using the resource editor.

  9. The "Month Calendar" format %mc takes exactly the same form as %dt.
    Styles can be selected using the resource editor but the "Day states" style can only be implemented by interacting directly with the control whilst the "Multi-select" style is explicitly excluded from ClearWin+. Programmers who have the time and interest can use the advanced features of the Month Calendar control by sending the messages described in the Microsoft MSDN documentation available from the Microsoft website.

  10. The tool help format %th has been extended (see Samples\s12tips) and includes options to select Microsoft styles:

    ms_style

    use the Microsoft tooltip (implies at_cursor and no_callback_hide)

    always_tip

    ms_style with tooltips activated even when the control does not have the focus

    no_prefix

    ms_style with ampersands (&) not stripped from the text

    no_animate

    ms_style without initial sliding (when sliding can be disabled)

    no_fade

    ms_style without fading (when fading is available)

    balloon

    ms_style with balloon effect (when balloon effect is available)

    centre_tip

    ms_style with tooltips centred on each control rather than below right of the mouse cursor

    The delay feature in %th also works when using ms_style.
    If these new styles are used, it is necessary to call WINDOW_UPDATE@ if and when the on/off variable associated with %th is changed.

    The following subroutine can be used to change the toolip text dynamically:

    SUBROUTINE SET_TOOLTIP_TEXT@(hwnd,tip)
    INTEGER(7) hwnd
    CHARACTER*(*) tip

    hwnd is the handle of the control (from %lc) whose tooltip is to be changed to tip.


Compiling and linking

Compiler options and directives for Windows

SLINK commands

Using the Silverfrost Resource Compiler

FTN95


Compiler options and directives for Windows

In this section:

  • Compiler options and directives for Windows
  • SLINK commands
  • Using the Silverfrost Resource Compiler
  • FTN95

This section describes the compiler options and directives that are provided for the purpose of creating Windows executable programs. Information about other compiler options and directives will be found in the user guide for your Silverfrost compiler.

Using ClearWin+, a Windows application can be created in one of two ways. One approach is to compile the main program using the /WINDOWS command line option and then run the linker separately (other routines that have not been compiled with /WINDOWS may also be linked in). Further details of this approach are given below. The other method is to use one of the compiler command line options /LINK and /LGO and to insert the WINAPPcompiler directive into the program code before the main program.

The WINAPP directive takes the form:

WINAPP resource_file

The /WINDOWS command line option becomes redundant when this directive is used. When used, WINAPP should be the first compiler directive in the file and must appear before the main program. WINAPP can take either no arguments or one argument. If the resource script file is specified, the SRC resource compiler is invoked (see Using the Silverfrost Resource Compiler) to compile the resource script. If it is not specified, the application will simply be marked as a Windows application rather than a Console application.

For Win32 applications, the resource file name must have a different stem (i.e. the part before the extension) from all the other source file names. For example, do not use prog.rc with prog.for. If you did not obey this rule, both files would be compiled into prog.obj and one would overwrite the other.

Resources are automatically appended to the executable or DLL being created. However, by default ClearWin+ only searches for resources in the current executable. Calling the subroutine USE_RESOURCE_LIBRARY@ causes ClearWin+ to also search in a given DLL. The call takes the form:

CALL USE_RESOURCE_LIBRARY@('MYLIB')

where mylib.dll is the name of the DLL.

Fortran 77 routines that use ClearWin+ and/or the Windows API should include the line

INCLUDE <windows.ins>

unless the routine only refers to winio@ or RGB@ (say) which can be declared as INTEGER in the routine. Note the use of "<" and ">" to denote that the default directory for system include files should be searched. The file called windows.ins references three other files as follows:

INCLUDE <clearwin.ins>
INCLUDE <win32api.ins>
INCLUDE <win32prm.ins>

These files are installed into the INCLUDE sub-directory of your chosen installation directory (the default installation directory is c:\win32app\salford). Where appropriate, clearwin.ins can be used in place of windows.ins in your program. This will reduce the amount of processing at compile time.

Fortran 90/95 routines can alternatively make use of the file mswin.mod instead of windows.ins via the statement

USE MSWIN

The source file for mswin.mod references three other files as follows:

MODULE mswin
USE msw32prm
USE mswin32
USE clrwin
END MODULE mswin

Where appropriate, clrwin can be used in place of mswin in your program. This will reduce the amount of processing at compile time.

It is recommended that you use the IMPLICIT NONE statement at the start of any routine that uses the windows.ins file. Without IMPLICIT NONE, a mispelt Windows parameter (some are very long) will not be detected at compile time. Such bugs are very hard to find in the Windows environment.

Tip

Of necessity, the three include files and the equivalent module files contain many thousands of lines of declarations in order to provide you with full access to all the ClearWin+ functions and the Windows API. Once you are familiar with the concepts described in this guide, you may find it helpful to create your own include or module file that contains only those declarations that are used by your programs. If you use IMPLICIT NONE, and remove references to windows.ins or msmod, the compiler will report all usage of undeclared variables and functions. You can then search the relevant include or module files for the missing names and, using a text editor, build up your own include or module file. Note that ClearWin+ routines (whose names usually end in an "@" character) will appear in a C_EXTERNAL statement in order to provide the compiler with a reference to a routine in the run time library. If you take the time to make your own include or module file, the benefits of much faster compilation will be immediately obvious, especially if your program contains many sub-programs that use these include or module files.

Unlike a Console application, a Windows application does not create or inherit a console (i.e. a DOS box), and any default input/output is directed to a ClearWin window (which can be embedded inside other windows using %cw). Although a simple ClearWin+ window can be displayed from a Console application, the rules concerning which Windows API calls will work from within a Console application are ill-defined (ClearWin+ calls all ultimately resolve into API calls). Therefore, it is recommended that all ClearWin+ applications should be set up as Windows applications using the WINAPP directive.


SLINK commands

In this section:

  • Compiler options and directives for Windows
  • SLINK commands
  • Using the Silverfrost Resource Compiler
  • FTN95

If the /LINK and /LGO compiler command line options are not used, SLINK must be called in order to link programs.

If your application uses a resource script (resource.rc say) then it must be separately compiled using the Silverfrost Resource Compiler SRC. This generates the object file resource.obj which can then be loaded in the same way as other object files.

The following example shows the commands required to compile and link a simple Windows application from a file myapp.for using FTN95:

FTN95 MYAPP /WINDOWS

SRC RESOURCE

SLINK
LO MYAPP
LO RESOURCE
FILE

Note

a) Because myapp.obj and resource.obj are both used in the SLINK commands it is evident that we cannot use myapp.rc as the name of the resource.

b) If there is more than one file of source code in addition to myapp.for then the first to be loaded must contain the main program and be marked as a Windows application either by using the /WINDOWS compiler option or by including the WINAPP directive.

c) Not more than one resource object can be loaded.

d) A SLINK command line of the form:

subsystem windows,major.minor

specifies the Windows GUI style to use. The default is now

subsystem windows,4

The former Windows 3.10 subsystem can also be obtained by setting the environment variable

LINK_SUBSYSTEM=3


Using the Silverfrost Resource Compiler

In this section:

  • Compiler options and directives for Windows
  • SLINK commands
  • Using the Silverfrost Resource Compiler
  • FTN95

If a program uses a resource script and neither of the compiler options /LGO and /LINK are used to compile and link the program, then the Silverfrost Resource Compiler SRC must be used to compile the resource script. An alternative method can also be used with FTN95 (see Resources in FTN95).

When SRC is called it creates a permanent compilation of the resource script. With a few exceptions and a few additions, SRC uses the same resource script syntax as the Microsoft Resource Compiler RC. However, most ClearWin+ programmers will find that they only use the following kinds of resources:

BITMAP
ICON
CURSOR
GIF
HYPERTEXT
SOUND

Once a resource script has be written, it should be stored in a file with the .RC extension. The resource can then be compiled with a call to SRC of the form:

SRC RESOURCE

This command takes the file resource.rc as input and produces an object file called resource.obj. This means that resource must not be used as the stem for both a Fortran filename and resources in the same directory and project. The resulting object file can then be linked with other object files using SLINK as follows.

SLINK
LO MYAPP
LO RESOURCE
FILE


Resources in FTN95

In this section:

  • Compiler options and directives for Windows
  • SLINK commands
  • Using the Silverfrost Resource Compiler
  • FTN95

Using FTN95, it is possible to append resource directives to the end of a program using the RESOURCES directive. Everything after this directive (up to the end of the file) is treated as resources and passed to the SRC command. The result is combined with the object code produced by FTN95. In order to use the RESOURCES directive, the SRC command must be available on the PATH. All the resources for a program must be supplied in one place.

Here is a simple example:

WINAPP
INTEGER i,winio@
i=winio@('%ca[A beautiful bitmap]&')
i=winio@('%bm[mybitmap]%2nl%cn%`bt[OK]')
END
RESOURCES
mybitmap BITMAP c:\bitmaps\pic1.bmp

It is important to note that the RESOURCES directive will only work when either /LINK or /LGO is used on the FTN95 command line. As a result, the directive will not work in a Plato project. When using Plato in "project" mode (rather the single file mode) the resources must be listed in a .rc resource script which must be added to the list of "Source files" in the "Project Explorer" window.

File names that contain spaces must be enclosed in double quotes.

The SRC compiler processes strings as C strings where the backslash is an escape character. So a backslash in the path for a file must appear as "\\".


Using ClearWin+ with third party Fortran compilers

Introduction

ClearWin+ is accessible from third party 64 bit Fortran compilers. Any third party 64 bit Fortran compiler that passes character variable arguments in the same way as FTN95 can be used and this includes gFortran, Intel Fortran and 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 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 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 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 what is now a significant number of 200x 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.

The standard Silverfrost interfaces to ClearWin+ routines are provided in code form for copying to the local project folder. These must be used instead of, for example, INCLUDE <clearwin.ins> and USE clrwin.

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$, and so on. Note that @ can be replaced globally by $ except where it appears within string quotation marks.

Source code to interface with the ClearwIn+ library is provided in the compiler sub-folder FTN95\Soure64 and these files can be copied into the current project or they can be used to create a ClearWin+ interface library for fx64. Note that the command line option /DOLLAR_MOD must be included when compiling with FTN95.

Second, ClearWin+ INCLUDE and USE statements must be changed as indicated in the following table...

Old | New | Source64 file
INCLUDE <clearwin.ins> | USE clrwin$ | clrwin.f95
INCLUDE <win32api.ins> | USE mswinapi$ (See note 1) | mswinapi.f95
INCLUDE <win32prm.ins> | USE mswinprm$ | mswinprm.f95
INCLUDE <windows.ins> | USE mswin$ (See note 2) | mswin.f95
INCLUDE <opengl.ins> | USE opengl$ | opengl.f95
USE clrwin | USE clrwin$ | clrwin.f95
USE mswin32 | USE mswinapi$ (See note 1) | mswinapi.f95
USE msw32prm | USE mswinprm$ | mswinprm.f95
USE mswin | USE mswin$ (See note 2) | mswin.f95
  • Note 1: The source code in this case is not complete and only provides a template for further development.
  • Note 2: This module merely calls upon the modules clearwin, winapi and winprm so "Note 1" also applies to the winapi part.

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 modules define an INTEGER KIND called CW_HANDLE that matches the environment. This means that relevant HANDLEs should be declared with type INTEGER(CW_HANDLE). Note, however, that some HANDLEs described in old ClearWin+ documentation do not represent Microsoft HANDLEs and these are invariably INTEGER*4. This includes the %gr identifier 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 Source64 files for the ClearWin+ modules.

When calling winio$, FTN95 constructs and passes an initial additional argument that describes the types of the arguments that follow. For third-party compilers, ClearWin+ does not have this information so it uses a peeking process to create it. This works well except for callback functions that can be presented as either user callbacks or as standard ClearWin+ callbacks that appear in the form of literal quoted strings such as "EXIT". In order to safely disambiguate these two forms it is recommended that the winio$ argument "EXIT" be changed to CB$("EXIT") etc.. This changes "EXIT" to "CLEARWIN+EXIT".

Changes required for specific ClearWin+ format codes

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

%lw | %lw leaves the window open (a modeless dialog). In some contexts the window may close prematurely in which case a call can be made of 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 | The existing HYPERTEXT keyword can be used resource scripts. Is HTML is an alternative.
%cw | External WRITE/PRINT statements (for %cw) will not work directly with fx64 but it is possible to use an internal WRITE (to a character variable str, say) and then call cw_write$(unit, str). An alternative is to use %re together with an internal WRITE and then to call EditWriteLn$(hwnd, str) where hwnd is obtained from %lc.
%og | Stricter type checking in gFortran means that some scalar arguments (to OpenGL functions) must be changed to one-element arrays.
%di | has occasional limitations when using the related resource compiler.
%gr | Some very old (DBOS) routines have not been ported to x64.
%pl | Options such as [x-array] that change the number of arguments, must appear in a winio$ call rather than a winop$ call.

In some very unusual cases, the peeking process mention above may not scan winio$ format codes correctly. In which case, %za and %zz can be added to mark the beginning and end of a Window. %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.

If a manifest file is used in order to provide an XP theme for the controls then it may necessaey to change the markup code in the manifest file in order to include

<assemblyIdentity processorArchitecture="*"/>

Parallel Development using FTN95

One set of source files can normally be used for both FTN95 and fx64. 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

Using Plato

See Using gFortran or iFort.

Translating FTN95

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

  1. LS(i, shift) becomes ISHFT(i, shift)
  2. RS(i, shift) becomes ISHFT(i, -shift)
  3. LENG(str) becomes LEN_TRIM(str)
  4. CORE1, CORE2, CORE4, FCORE4, DCORE8 and CCORE1 have been ported without change of name but cannot take a zero argument.
  5. LOC can be used in some compilers without change.
  6. TEST_BIT@ becomes TEST_BIT$
  7. SET_BIT@ becomes SET_BIT$
  8. CLEAR_BIT@ becomes CLEAR_BIT$
  9. FILES@ becomes FILES$
  10. GET_FILES@ becomes GET_FILES$

Deployment

The DLL clearwin64.dll 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 by searching for mysys64.


ClearWin Introduction

In this section:

  • Introduction
  • Simple programs
  • Explicit ClearWin window creation
  • Text output to ClearWin windows
  • Getting text from a ClearWin window
  • Obsolete ClearWin window functions

This section describes the attributes of a ClearWin window. A summary of functions that can be used with ClearWin windows is given in ClearWin window functions. Details of these functions can be found in the Library reference.

A ClearWin window has the attributes of a Windows window but has added functionality. In particular a ClearWin window can be used in association with the standard Fortran I/O routines READ, WRITE and PRINT.

Note that a ClearWin window is not the same as a window created with winio@ (which is called a Format window). It is, however, possible to embed a ClearWin window in a Format window (see ClearWin window).

Graphics can be drawn to a ClearWin window by using get_graphics_dc@ and by calling Windows API drawing functions (details are given in the ClearWin+ User's Supplement). However, it is recommended that graphics objects should be drawn to a format window created using %gr or %og.

A ClearWin window (that is not embedded in a format window) can be created by calling CREATE_WINDOW@ (this function returns a standard Windows handle). DESTROY_WINDOW@ is used to kill the window and CLEAR_WINDOW@ clears any I/O text that appears in the window. However, it does not clear graphics that have been drawn to the associated device context. UPDATE_WINDOW@ is called to "invalidate" a ClearWin window and hence redraw it. Various other routines can be used to control the font of the text and to get and set the handle for default I/O, whilst OPEN_TO_WINDOW@ can be used to attach a Fortran unit number to a particular ClearWin window.

As an alternative to using a Fortran READ statement, the programmer can access a ClearWin window keyboard buffer via the routines: FEED_WKEYBOARD@, FLUSH_WKEYBOARD@, GET_WKEY@, GET_WKEY1@, and WKEY_WAITING@.

It is strongly recommended that either the routine SET_ALL_MAX_LINES@ or the routine SET_MAX_LINES@ be used before creating a ClearWin window (including default ClearWin windows). These routines are used to limit the amount of memory that is used by a ClearWin window. See below for further details.


Simple programs

In this section:

  • Introduction
  • Simple programs
  • Explicit ClearWin window creation
  • Text output to ClearWin windows
  • Getting text from a ClearWin window
  • Obsolete ClearWin window functions

Using ClearWin+, simple programs can be compiled unchanged. As soon as standard output is generated which would have gone to the screen, or the program attempts to read from the keyboard, a ClearWin window is set up by the ClearWin+ system. Successive lines of output are written to this window (entitled Output), which scrolls when necessary. The window acts like a terminal, so keyboard input is echoed in the window. The window can be scrolled, moved, or resized by the user. The system retains the information output to the window so that WM_PAINT messages can be handled without any special programmer action. As an example, here is a complete application program to calculate square roots:

WINAPP
DOUBLE PRECISION d
DO WHILE(.TRUE.)
READ *,d
PRINT *,SQRT(d)
ENDDO
END

Notice that this program does not require an explicit exit path. Each time it pauses for input, the system will be prepared to accept a window close request (Alt-F4). When your program exits, its window will remain open until closed by the user in order to ensure that the user has time to read the output.

Because ClearWin+ must store away every line that you send to a window - to cater for possible repaint requests or user scroll operations - it is important to limit the amount of output to manageable proportions. Store is consumed from the heap and is reclaimed when the ClearWin window is closed or cleared. It is recommended that the routine SET_ALL_MAX_LINES@ (or SET_MAX_LINES@) be used to limit the amount of store that is consumed.

In a similar way, DOS applications that contain calls to the Silverfrost graphics library can also be compiled unchanged. In this case ClearWin+ will automatically create a simple format window for the drawing.


Explicit ClearWin window creation

In this section:

  • Introduction
  • Simple programs
  • Explicit ClearWin window creation
  • Text output to ClearWin windows
  • Getting text from a ClearWin window
  • Obsolete ClearWin window functions

When ClearWin+ creates a ClearWin window for you it is created full screen by default. Also, the window uses the Windows system fixed font (referred to as SYSTEM_FIXED_FONT in the Windows documentation). In general, it is better to create a ClearWin window explicitly so that you have a handle to it and you can exert more control. For example, the following would create a half-size window in the centre of the screen:

WINAPP
INCLUDE <windows.ins>
INTEGER(7) win
INTEGER xsize,ysize,xpos,ypos
xsize=clearwin_info@('screen_width')/2
ysize=clearwin_info@('screen_depth')/2
xpos=xsize/4
ypos=ysize/4
win=create_window@('Moon landing',xpos,ypos,xsize,ysize)
...

The first ClearWin window that you create will be the parent window. When this window is closed the program will terminate.

Once you have created it, you can inform the system that your window is the default ClearWin window, thus:

CALL set_default_window@(win)

A ClearWin window can also be attached to a specified Fortran unit, for example:

CALL open_to_window@(7,win)
WRITE(7,'(a)') 'Testing'

Fortran units connected to ClearWin windows are opened for input and output. When you close such a unit, the corresponding window is closed and all the heap storage required to hold the output is returned to the system.

When your program terminates, the ClearWin windows that it has created will remain open for viewing, scrolling etc. until closed by the user (e.g. by pressing Alt-F4).


Text output to ClearWin windows

In this section:

  • Introduction
  • Simple programs
  • Explicit ClearWin window creation
  • Text output to ClearWin windows
  • Getting text from a ClearWin window
  • Obsolete ClearWin window functions

Textual window input/output uses, by default, a Windows font called SYSTEM_FIXED_FONT output in black. You are not limited to the use of this font; Windows can write text in a wide variety of fonts and colours. You simply use appropriate Windows API routines to create one or more fonts and then attach them to a window.

In order to create a new font, it is usually best to start with the parameters defining the system font and modify them to obtain what you require.

For example:

WINAPP
INCLUDE <windows.ins>
INTEGER lfheight,lfwidth,lfescapement,
+ lforientation,lfweight,lfitalic,lfunderline,
+ lfstrikeout,lfcharset,lfoutprecision,
+ lfclipprecision,lfquality,lfpitchandfamily
CHARACTER*80 lffacename
INTEGER newfont
CALL get_system_font@(lfheight,lfwidth,lfescapement,
+ lforientation,lfweight,lfitalic,lfunderline,
+ lfstrikeout,lfcharset,lfoutprecision,
+ lfclipprecision,lfquality,lfpitchandfamily,lffacename)
c--- Alter the default parameters to double the size
c--- and specify italic.
lfheight=2*lfheight
lfwidth =2*lfwidth
lfitalic=1
c--- CreateFont is a Windows API function...
newfont=CreateFont(lfheight,lfwidth,lfescapement,
+ lforientation,lfweight,lfitalic,lfunderline,
+ lfstrikeout,lfcharset,lfoutprecision,
+ lfclipprecision,lfquality,lfpitchandfamily,lffacename)

CALL set_default_font@(newfont)
...

The default font used by a ClearWin window (SYSTEM_FIXED_FONT) can be changed by a call to either SET_DEFAULT_PROPORTIONAL_FONT@ or to SET_DEFAULT_FONT@. These routines will alter the default font used by ClearWin+ on all ClearWin windows created subsequent to the call. The original default can be restored by a call to SET_DEFAULT_TO_FIXED_FONT@.


Getting text from a ClearWin window

In this section:

  • Introduction
  • Simple programs
  • Explicit ClearWin window creation
  • Text output to ClearWin windows
  • Getting text from a ClearWin window
  • Obsolete ClearWin window functions

It is possible to extract the data placed into a ClearWin window by calling:

INTEGER FUNCTION GET_CLEARWIN_TEXT@(HWND,BUFFER,COPY)
INTEGER(7) HWND
INTEGER COPY
CHARACTER(*) BUFFER

HWND is the handle of ClearWin window in question. To obtain the handle of the default window use:

HWND=GET_DEFAULT_WINDOW@( )

If COPY is zero, the function returns the length of the required buffer but no data is copied. If COPY is 1, the data is also copied to the buffer.


Obsolete ClearWin window functions

In this section:

  • Introduction
  • Simple programs
  • Explicit ClearWin window creation
  • Text output to ClearWin windows
  • Getting text from a ClearWin window
  • Obsolete ClearWin window functions

The following functions are considered to have been superseded by the introduction of winio@ in ClearWin+.

ADD_FORTRAN_WINDOW_CALLBACK@ | Adds a call-back function for a given ClearWin window and message.
ADD_TEXT_DESCRIPTOR@ | Adds a text descriptor to a window.
ADD_WINDOW_MENU@ | Sets the menu in a given window.
ATTACH_FORTRAN_MENU@ | Loads a named menu from the program resource.
GET_FILENAME@ | Displays a dialog box from which a filename can be selected.
GET_GRAPHICS_DC@ | Returns a device context to a bitmap.
MAKE_DIALOG_BOX@ | Creates and display a given dialog box.
SET_WIN_ESCAPE@ | Sets the escape character for a specified ClearWin window.


Using the Windows API

Calling Windows API routines from Fortran

The Fortran STDCALL statement

The Fortran STOP and PAUSE statements

Using Windows API structures from Fortran


Calling Windows API routines from Fortran

In this section:

  • Calling Windows API routines from Fortran
  • The Fortran STDCALL statement
  • The Fortran STOP and PAUSE statements
  • Using Windows API structures from Fortran

As the Windows API is based upon C++, it is easier to use the API from a C++ program. However, it is possible to program the API from Fortran but Fortran data structures do not easily map on to the data structures that are used by the Windows API. One way forward, is to employ mixed language programming, keeping your existing Fortran as far as possible unchanged, and using C++ to provide an interface to the Windows API.

Programmers who are not familiar with C++ will probably prefer to avoid learning a new language. If this is the case, the following points should be kept in mind when calling Windows API functions from Fortran.

All Windows API routines which do not take the address of a routine as an argument (or return one as a result) are available for calling from Fortran. Owing to the fact that the Windows API routines are written in C++, it is necessary to use the Silverfrost Fortran statement STDCALL to declare access to Win32 API routines. Examples of STDCALL statements can be seen in the file win32api.ins.

Each pointer argument to a Windows API routine has been specified as a WINREF or WINSTRING (the latter in the case of character arguments that need converting to null-terminated C-strings) and the actual argument should be a variable or array to which the pointer refers. The defintion of STDCALL appears below.


The Fortran STDCALL statement

In this section:

  • Calling Windows API routines from Fortran
  • The Fortran STDCALL statement
  • The Fortran STOP and PAUSE statements
  • Using Windows API structures from Fortran

The STDCALL declaration allows the Fortran programmer to call Win32 API routines written in C++.

The syntax of the declaration for a STDCALL function is as follows:

STDCALL name ['alias'] [(desc , ... )] [:restype]

where:

name
is the name by which it will be called in the Fortran program.

alias
is the C++ Windows API name (or the required __stdcall function name ). Note that this appears in single quotes and is case-sensitive.

desc
is an argument descriptor, and is either REF, VAL, STRING, INSTRING, or OUTSTRING.

STRING, INSTRING and OUTSTRING may be followed optionally by an integer in parentheses. This integer specifies the maximum length for the corresponding argument in the C routine, in each case where the length of the corresponding Fortran character object cannot be determined (i.e. the actual argument is CHARACTER(*) ). If the integer is not specified, then a default value of 256 (bytes) is assumed for the maximum length of the string.

restype
is the type of the function. If this does not appear then the function does not return a result (equivalent to the C type void). Valid types are INTEGER, REAL, DOUBLE PRECISION, COMPLEX, DOUBLE COMPLEX, LOGICAL and STRING. INTEGER, REAL and LOGICAL may be followed by a length specifier of the form "*n". If the function result is declared to be of type STRING then the function result should be assigned to a variable of type CHARACTER.

Some examples of valid STDCALL declarations are:

STDCALL SUB1, SUB2
STDCALL SUB2 'GetAttr':INTEGER
STCALLL CSUB3(REF,STRING(20)):STRING
STDCALL SUB4 'GetSize' (REF,VAL,VAL,INSTRING,OUTSTRING(100))

If no argument specifiers are specified, then default argument linkage is assumed. This is as follows:

Arrays:
by reference (i.e. as a pointer)

INTEGER and REAL scalars:
by value

LOGICAL:
by value, as an integer of the appropriate length, 1 representing .TRUE. and 0 representing .FALSE.

CHARACTER objects:
Copied to a compiler defined temporary variable. A trailing null is added to the end of the significant length of the string (i.e. there are no trailing spaces). The temporary variable is then passed by reference. In addition, if the actual argument is a scalar or array element, the result in the temporary variable is copied back, and padded to the right with blanks if necessary. This is equivalent to the STRING linkage descriptor described below.

Where linkage descriptors are specified, the number of arguments in each call must agree with the number of descriptors specified. The various categories of objects which may correspond to particular argument descriptors are as follows:

Numeric and LOGICAL scalars:
Value or reference (VAL or REF)

Arrays, externals, dummy procedures:
Reference (REF)

CHARACTER objects:
Reference or string (REF, STRING, INSTRING or OUTSTRING)

The three variants of the STRING descriptor are as follows:

STRING
The corresponding argument is both input and output, and is copied to a temporary variable on entry to the routine (with a trailing null inserted at the end of the significant length), and if the argument is a scalar or array element, is copied back to the actual argument, blank padded to the right if necessary.

INSTRING
The corresponding argument is an input argument with respect to the external routine. The argument is only copied to the temporary variable, and not copied back.

OUTSTRING
The argument is returned by the external routine. The temporary variable is set up to be the length of the corresponding scalar or array element plus one, or of specified or default (256) length if the corresponding argument is CHARACTER(*), but the value is only copied out. Obviously, this descriptor is only appropriate where the actual argument is a scalar or array element.

When it is required to pass a NULL pointer to a string, the value 0 (zero) should be used.

Some Windows API functions allow a particular argument to take two different types in different circumstances. For example, an LPSTR in some circumstances and an integer in others. This is outside the scope of the STDCALL mechanism. If this feature affects you then you should copy the STDCALL statement for the relevant API and modify it to have a different Fortran name and argument list, but keeping the same called name.

A common example is the Windows API function LoadCursor which is used to load either a cursor defined in the program resource or a predefined system cursor. This has the following definition:

HCURSOR WINAPI LoadCursorA(HANDLE hInstance,LPSTR lpCursorName)

When used to load a cursor from the program resource, hInstance is the instance handle of the application. lpCursorName is a character string containing the name of the cursor in the program resource. This form of the function will have the STDCALL declaration :

STDCALL LOADCURSOR 'LoadCursorA' (VAL, INSTRING):INTEGER*4

When used to load a predefined system cursor, the first argument hInstance is set to zero and the second argument lpCursorName is an integer containing one of a number of predefined values which specifies the cursor to be loaded. This form of the function will have the STDCALL declaration :

STDCALL LOADCURSOR 'LoadCursorA' (VAL, VAL):INTEGER*4

However, having two differing STDCALL statements for the same Fortran function is not allowed. The solution is to change the Fortran name. For example

STDCALL LOADCURSOR1 'LoadCursorA' (VAL, INSTRING):INTEGER*4

STDCALL LOADCURSOR2 'LoadCursorA' (VAL, VAL):INTEGER*4

The same situation arises with some other functions that have the form as LoadCursor, for example LoadBitmap and LoadIcon.

A further example is given by the Windows API printer Escape function which can take many different forms. One of these has the following form:

int WINAPI Escape(hdc, GETTECHNOLOGY, NULL, NULL,lpTechnology)

lpTechnology is an LPSTR (long pointers to strings) so the STDCALL declaration for this form of the function for use in a Fortran program would be:

STDCALL ESCAPE 'Escape' (VAL, VAL, VAL,INSTRING,
+ OUTSTRING):INTEGER*4

A second form of this Escape function is:

int Escape(hdc, SETCOPYCOUNT, sizeof(int),
lpNumCopies, lpActualCopies)

lpNumCopies, and lpActualCopies are both LPINT (long pointers to integers) so the STDCALL declaration for this form of the function would be:

STDCALL ESCAPE 'Escape' (VAL, VAL, VAL, REF, REF):INTEGER*4

As before, having two differing STDCALL statements for the same Fortran function is not allowed and the solution is to change the Fortran name. For example

STDCALL ESCAPE1 'Escape' (VAL, VAL, VAL,INSTRING,
+ OUTSTRING):INTEGER*4
STDCALL ESCAPE2 'Escape' (VAL, VAL, VAL, REF,REF):INTEGER*4


The Fortran STOP and PAUSE statements

In this section:

  • Calling Windows API routines from Fortran
  • The Fortran STDCALL statement
  • The Fortran STOP and PAUSE statements
  • Using Windows API structures from Fortran

You may wish to trap the STOP or PAUSE Fortran statements for your own additional processing. These standard Fortran routines call upon other routines named STOP@ and PAUSE@ respectively and the user may provide alternative definitions for these routines to over-ride the system defaults.

In order to do this you should provide your own STOP@ subroutine with the following specification:

SUBROUTINE STOP@(MESSAGE)
CHARACTER(*) MESSAGE

When you have completed your 'clean up' operation in STOP@ you should call on the system routine EXIT@1 as the last instruction within STOP@ to allow ClearWin+ to 'clean up' before termination (EXIT@1 has no arguments and does not return to the calling routine).

SUBROUTINE EXIT@1()

Similarly, you may also provide your own version of the PAUSE@ routine with the specification:

SUBROUTINE PAUSE@(MESSAGE)
CHARACTER(*) MESSAGE

The default PAUSE@ message action uses the MessageBox function to put up a MODAL dialog box captioned 'Pause' with a STOP icon, a single OK button and the pause message which is a argument in the standard PAUSE routine. This default action may be modified if the user writes his own PAUSE@ routine. No call-on (like the call to EXIT@1 above) is necessary or possible.

A routine called ABORT@ is available for use when the program needs to terminate because of an error condition.


Using Windows API structures from Fortran

In this section:

  • Calling Windows API routines from Fortran
  • The Fortran STDCALL statement
  • The Fortran STOP and PAUSE statements
  • Using Windows API structures from Fortran

The difficulty of accessing Windows API structures from Fortran can be alleviated by the use of Fortran statement functions and Fortran EQUIVALENCE statements.

For example, suppose the text metrics for the system font are required in order to determine the size of a main window before it is created. This requires finding the height of a single line of text. The Windows API function GetTextMetrics returns the metric properties of the system font in a structure, TEXTMETRICS. The specific fields of interest are tmHeight and tmExternalLeading.

Examining the windows.h file, it will be seen that the structure length is 29 bytes. In order to represent this in Fortran, any array may be used, provided its length is at least 29 bytes. In the interests of efficiency it is a good idea to keep 4-byte alignment, so an array 32 bytes long might be used to hold the structure. After the call to GetTextMetrics, the relevant field values may be extracted by use of statement functions, using the address of the structure as the argument. For example:

INTEGER*1 TEXTMETRICS(32)
INTEGER*2 line_hght,tmHeight,tmExternalLeading
INTEGER*4 atm
. . .
tmHeight(i)=CORE2(i+0)
tmExternalLeading(i)=CORE2(i+8)
. . .
got_tm=GetTextMetrics(hwnd,TEXTMETRICS)
atm=LOC(TEXTMETRICS)
line_hght=tmHeight(atm)+tmExternalLeading(atm)

CORE2 and LOC are Silverfrost Fortran intrinsic functions.

The use of EQUIVALENCE statements is illustrated in Edit box (%eb).


Programming tips

In this section:

  • Introduction
  • Tricks with boxes
  • Debugging with an auxiliary terminal
  • Recording mouse and keyboard events
  • Breaking into the debugger

This section contains a collection of coding ideas for experienced users of ClearWin+. The topics presented here are in no particular order and do not fit comfortably in other parts of the manual.


Tricks with boxes

In this section:

  • Introduction
  • Tricks with boxes
  • Debugging with an auxiliary terminal
  • Recording mouse and keyboard events
  • Breaking into the debugger

The %ob format has a number of uses. Consider what happens if you use %3.4ob[invisible]. In this case the grid structure will be invisible, but the contents of the various cells will still be laid out in a rectangular pattern.

Boxes can be nested, so some or all of the entries in this lattice can also be boxes.

Invisible boxes can be used to create groupings of controls. For example, suppose you had a format string such as:

"%10.3ls%bt[Case 1]%nl%bt[Case 2]%nl%bt[Case 3]%nl%bt[Case 5]"

Because the list box is not very deep, it is quite likely that the first one or two buttons would appear to the right of the list box, while the rest would be separated underneath the box. Obviously you could solve the problem by right justifying all the buttons, but that might not be what was required. A better solution is to surround the buttons with an invisible box.

While you are developing a window it may be a good idea to make all boxes visible, so as to understand the layout. When everything is right you can add the invisible option to the %ob format.


Debugging with an auxiliary terminal

In this section:

  • Introduction
  • Tricks with boxes
  • Debugging with an auxiliary terminal
  • Recording mouse and keyboard events
  • Breaking into the debugger

A common problem encountered while developing Windows applications is that temporary debugging output tends to interfere with the appearance of the application. Although ClearWin+ connects the standard output to a large window for debugging purposes, this can be less than satisfactory because the debug window may obscure part of the program under development. A very effective alternative is to connect the RS232 port to an old fashioned 'dumb' terminal (these can be obtained second hand very cheaply) or to a cheap PC (an AT or XT will do - anything with an RS232 port). If you use a PC you will need to execute a command on the PC to read the RS232 port to the screen (e.g. TYPE COM2). Output can be sent to the RS232 terminal even in the most sensitive parts of a Windows program, such as while the program is responding to the WM_PAINT message (e.g. while a %eb box is requesting re-colouring).

You can use any COM port, but typically COM1 is connected to the mouse and COM2 is free, so we will assume you are using COM2 in what follows. To write to the COM2 port simply open the file COM2 and write to it - these names are reserved by Windows and do not correspond to ordinary file names. It is important to ensure that the COM port has been set up with the same baud rate as the terminal. Typically you should include a suitable MODE command in the autoexec.bat file (e.g. MODE COM2:9600,n,8,1). If in doubt as to whether the link is working, try piping a command from a DOS box to the port, e.g. DIR > COM2.

Great care should be taken to remove all debugging output to RS232 ports before shipping an application. Failure to do this may cause interference with modems or other devices attached to your user's PC.

The following routines are used to send output to an auxiliary terminal:

SUBROUTINE SET_RS232_COMM_STREAM@(PORT)
INTEGER PORT

SUBROUTINE RS232_PRINT_HEX@(MESSAGE, VALUE)
CHARACTER(*) MESSAGE
INTEGER VALUE

SUBROUTINE RS232_PRINT_DEC@(MESSAGE, VALUE)
CHARACTER(*) MESSAGE
INTEGER VALUE

SUBROUTINE RS232_WRITE_NEWLINE@()

The following routines do not produce a new line:

SUBROUTINE RS232_WRITE_DECIMAL@(VALUE)
INTEGER VALUE

SUBROUTINE RS232_WRITE_HEXADECIMAL@(VALUE)
INTEGER VALUE

SUBROUTINE RS232_WRITE_DOUBLE@(VALUE)
REAL(2) VALUE

SUBROUTINE RS232_WRITE_STRING@(STR)
CHARACTER(*) STR

PORT is the COM port number which defaults to the value 2 (i.e. COM2). The string MESSAGE is used to identify the integer VALUE when it is displayed on the terminal.


Recording mouse and keyboard events

In this section:

  • Introduction
  • Tricks with boxes
  • Debugging with an auxiliary terminal
  • Recording mouse and keyboard events
  • Breaking into the debugger

A simple method is available to enable mouse and keyboard actions within a ClearWin+ application to be recorded and replayed. This facility should be thought of as a debug/test facility as it cannot be made totally reliable if the circumstances of the playback differ from those of the recording. In particular, mouse positions will differ if playback occurs at a different screen resolution (see below). The format of recorded files may also vary between versions of ClearWin+.

Recording is enabled by calling START_CLEARWIN_RECORDER@. This subroutine takes one CHARACTER variable specifying the name of the file to hold the recording. Recorded operations are written to the file immediately (rather than being buffered) to help in situations in which the application aborts. Recording stops when STOP_CLEARWIN_RECORDING@ is called, or when the application terminates. The file is created as a text file, and here are some typical contents:

<LEFT_MOUSE_DOWN,BT008/1,95,24>
<LEFT_MOUSE_UP,BT008/1,95,24>
<LEFT_MOUSE_DOWN,BT005/2,24,13>
<LEFT_MOUSE_UP,BT005/2,24,13>
<LEFT_MOUSE_DOWN,MAIN/1,4,1>
<LEFT_MOUSE_UP,MAIN/1,4,1>

Each event occupies one line of the file and starts with a name for the event. The second field names the control receiving the input. For example, the first two lines refer to button number 8 of the first ClearWin+ window. A name in this form is known as a fully qualified control name. Observe that the first two letters of a control name are derived from the format used to create it. Sometimes a user clicks on the main window rather than a control. In this case the 'control name' field has the form shown in the last two lines above. The last two fields for mouse operations are the co-ordinates of the mouse relative to the control in question.

Note that this scheme at least means that some mouse operations, such as button clicks, are unaffected by changes in screen resolution. The reason why recorded input does not make explicit reference to Windows handles is that different handle numbers will be supplied by Windows each time a program is run.

The control naming scheme is effective whether or not recording has been enabled. The following two routines can be used to convert between control names and the corresponding Windows handles:

INTEGER(7) HANDLE_FROM_CONTROL_NAME@(NAME)
CHARACTER(*) NAME

CHARACTER*10 CONTROL_NAME_FROM_HANDLE@(H)
INTEGER(7) H

These routines will generate incorrect results if they are given bad arguments.

The subroutine START_CLEARWIN_PLAYBACK@ can be used to play back a recorded file. This subroutine takes one CHARACTER variable specifying the name of the file that holds the recording. When play back is completed, normal mouse and keyboard input is resumed.

It is vital that the playback does not deviate from the recording in any way. For example, if your application displays an extra window if some file is present, then that file must be either present for both the recording and playback, or absent for both.

The problem of mouse actions being sensitive to the screen resolution and font sizes is ameliorated somewhat by the following:

a) Menus, edit boxes, and text arrays store additional information that stores the data in a resolution-insensitive form. This facility may be extended to cover more controls in future.

b) Mouse co-ordinates are always stored relative to the control in which they occur. This means that, for example, a mouse click at point (40,50) in a graphics area of some fixed resolution will be recorded correctly.


Breaking into the debugger

In this section:

  • Introduction
  • Tricks with boxes
  • Debugging with an auxiliary terminal
  • Recording mouse and keyboard events
  • Breaking into the debugger

Under Win32, pressing CTRL-BREAK or CTRL-SCROLL-LOCK will break to the debugger if an application is awaiting input from within a ClearWin+ window. No action is taken if the program is not running under the debugger. This feature is effective with either the normal debugger (SDBG) or the machine level debugger (SUSWT32).


Library overview

ClearWin window functions

Clipboard functions

File mapping functions

Format window functions

General functions

Graphics functions (bitmaps,cursors,icons)

Graphics functions (device context)

Graphics functions (device independent bitmap)

Graphics functions (font,text)

Graphics functions (lines,fill)

Graphics functions (metafiles)

Graphics functions (palette)

Graphics functions (printer,files)

Graphics functions (screen,regions)

Hypertext functions

Information functions

Mouse functions

Movie functions

Standard dialog functions

Sound functions

Useful API functions


ClearWin window functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

This section summarises the functions that can be used with ClearWin windows. This type of window is described in ClearWin windows.

CLEAR_WINDOW@ | Clears a given ClearWin window to its given background colour.
CREATE_WINDOW@ | Creates and displays a ClearWin window.
DESTROY_WINDOW@ | Closes and destroys a displayed ClearWin window.
FEED_WKEYBOARD@ | Inserts a key into the keyboard buffer.
FLUSH_WKEYBOARD@ | Empties the keyboard buffer.
GET_CLEARWIN_TEXT@ | Get text from a ClearWin window.
GET_DEFAULT_WINDOW@ | Returns the handle of the current default ClearWin window for standard I/O.
GET_WKEY@ | Gets a key from the keyboard buffer.
GET_WKEY1@ | Gets a key from the keyboard buffer but does not wait.
OPEN_TO_WINDOW@ | Attaches a ClearWin window to a Fortran unit.
SET_ALL_MAX_LINES@ | Sets the maximum number of lines to be stored for all ClearWin windows.
SET_MAX_LINES@ | Sets the maximum number of lines to be stored for a given ClearWin window.
SET_DEFAULT_FONT@ | Sets the default standard I/O font for ClearWin windows.
SET_DEFAULT_TO_FIXED_FONT@ | Resets the default standard I/O font for ClearWin windows to "System Fixed".
SET_DEFAULT_PROPORTIONAL_FONT@ | Sets the default standard I/O font for ClearWin windows to "System".
SET_DEFAULT_WINDOW@ | Sets the default ClearWin window for standard I/O.
UPDATE_WINDOW@ | Redraws a ClearWin window.
WIN_COUA@ | Outputs n characters from a string to a ClearWin window.
WIN_GETCHAR@ | Reads a character from the keyboard.
WIN_GETLINE@ | Reads a line of text from the keyboard.
WKEY_WAITING@ | Checks if the keyboard buffer is not empty.


Clipboard functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

CLIPBOARD_TO_SCREEN_BLOCK@ | Copies a bitmap on the clipboard to a DIB.
COPY_FROM_CLIPBOARD@ | Copies data from the clipboard.
COPY_TO_CLIPBOARD@ | Copies data to the clipboard.
GRAPHICS_TO_CLIPBOARD@ | Copies a drawing surface to the clipboard.
METAFILE_TO_CLIPBOARD@ | Sends a metafile to the clipboard.
PLAY_CLIPBOARD_METAFILE@ | Plays a clipboard metafile on the current drawing surface.
SIZEOF_CLIPBOARD_BITMAP@ | Gets the size of the bitmap on the clipboard.
SIZEOF_CLIPBOARD_TEXT@ | Gets the size of text on the clipboard.


File mapping functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

MAP_FILE_FOR_READING@ | Maps a file to memory.
MAP_FILE_FOR_READ_WRITE@ | Maps a file to memory.
UNMAP_FILE@ | Closes a file map.


Format window functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

The following functions are primarily for use with WINIO@.

ADD_CURSOR_MONITOR@ | Names a call-back function that monitors which window or control has the cursor.
ADD_FOCUS_MONITOR@ | Names a call-back function that monitors which window or control has the focus.
ADD_KEYBOARD_MONITOR@ | Names a call-back function that monitors the use of the keyboard.
ADD_MENU_ITEM@ | Creates a dynamic menu using %mn.
CHANGE_BUTTON_TEXT@ | Dynamically changes the text on a %bt or %tt button.
DISPLAY_POPUP_MENU@ | Activates a popup menu defined using %pm.
FREEZE_WINDOW_CONTENTS@ | Temporarily freezes the display of a window whilst multiple changes are made to its appearance.
GET_MOUSE_INFO@ | Obtains the position of the mouse, the mouse buttons, and the keyboard shift keys at the time when the last owner-draw (%^dw) or graphics region (%^gr) call-back function was called.
GET_WINDOW_LOCATION@ | Gets the location and size of a given window.
MOVE_WINDOW@ | Moves a window given its handle.
PERMIT_ANOTHER_CALLBACK@ | Allows another call-back function to be called.
PERMIT_CALLBACK_IN_WINDOW@ | Allows another call-back function to be called in a specified window.
REMOVE_CURSOR_MONITOR@ | Releases a call-back function that monitors which window or control has the cursor.
REMOVE_FOCUS_MONITOR@ | Releases a call-back function that monitors which window or control has the focus.
REMOVE_MENU_ITEM@ | Removes a dynamically attached %mn menu item.
REPLY_TO_TEXT_MESSAGE@ | Replies to a message from an application that uses SEND_TEXT_MESSAGE@
RESIZE_WINDOW@ | Resizes a window given its window handle.
SEE_PROPERTYSHEET_PAGE@ | Sets the sheet number for %ps.
SEE_TREEVIEW_SELECTION@ | Ensures that the current %tv item is visible.
SEND_TEXT_MESSAGE@ | Sends a message to an application that uses %rm.
SET_CLEARWIN_STYLE@ | Modifies the default styling controls for format windows
SET_CONTROL_TEXT_COLOUR@ | Changes the colour of a text control.
SET_CONTROL_VISIBILITY@ | Shows or hides a control or window.
SET_HIGHLIGHTED@ | Selects all of the text in a %rd, %rf or %rs edit box.
SET_MAXIMUM_DIALOG_SIZE@ | Increases the maximum permitted dimensions for a fixed sized window.
SET_OLD_RESIZE_MECHANISM@ | Reverts to the old ClearWin+ resizing strategy.
UNFREEZE_WINDOW_CONTENTS@ | Restores a window after using FREEZE_WINDOW_CONTENTS@.
USE_RESOURCE_LIBRARY@ | To specify the name of a DLL that contains resources.
WINSTYLE@ | Provide a default style for all subsequent winio@ windows.


General functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

ABORT@ | Used to terminate a program in the event of an error.
FIND_FILE@ | Searches for a specified file.
GET_OS_VER@ | Gets version information for the compatible mode operating system.
GET_WOW_VER@ | Gets version information for the machine operating system.
HIBYTE@ | Gets the top 8 bits of a 16 bit integer.
HIWORD@ | Gets the top 16 bits of a 32 bit integer.
LOBYTE@ | Gets the bottom 8 bits of a 16 bit integer.
LOWORD@ | Gets the bottom 16 bits of a 32 bit integer.
SCC_LIB_VERSION@ | Gets a sequence number for the DLL that contains the ClearWin+ library.
START_PROCESS@ | Starts a new process.
TEMPORARY_YIELD@ | Yields program control.
WINDOWS_95_FUNCTIONALITY@ | Tests if Windows 95 is in use.
YIELD_PROGRAM_CONTROL@ | Yields program control.


Graphics functions

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Graphics functions (images,cursors,icons)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

IMPORT_IMAGE@ | Imports an (BMP, JPEG, GIF, EMF, or PCX) image from an internal resource or an external file into a graphics window.
EXPORT_IMAGE@ | Exports a rectangular region in a graphics window to an image (BMP, JPEG, GIF PCX, EMF or PNG) file.
ADD_GRAPHICS_ICON@ | Places a movable icon in a graphics window.
GET_IM_INFO@ | Obtains information from a graphics file.
MAKE_BITMAP@ | Embeds a bitmap in program code.
MAKE_ICON@ | Embeds an icon in program code.
REMOVE_GRAPHICS_ICON@ | Removes an icon created using ADD_GRAPHICS_ICON@.
SET_CURSOR_WAITING@ | Produces a temporary hour-glass cursor.

See also Graphics functions (device independent bitmap).


Graphics functions (device context)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

The following routines transmit a handle to a device context and are particularly associated with the %gr and %dw formats described in (Graphics). GET_BITMAP_DC@ returns a handle for use with %dw whilst GET_CURRENT_DC@ returns a handle for a device context created by using %gr. These routines allow ClearWin+ to be used with Windows API functions and as such are unlikely to be of interest to a majority of ClearWin+ programmers.

ACTIVATE_BITMAP_PALETTE@ | Ensures that the palette is set correctly for the current window.
ATTACH_BITMAP_PALETTE@ | Attaches a palette to a DC.
CHANGE_PEN@ | Changes the pen in a device context acquired through GET_BITMAP_DC@.
CLEAR_BITMAP@ | Clears a bitmap device context acquired by GET_BITMAP_DC@.
GET_BITMAP_DC@ | Creates a device context for use with %dw.
GET_CURRENT_DC@ | Gets the current graphical device context.
RELEASE_BITMAP_DC@ | Releases a bitmap device context acquired by GET_BITMAP_DC@.


Graphics functions (device independent bitmap)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

Using a 24 bit per pixel array

DISPLAY_DIB_BLOCK@ | Displays an array on the screen.
GET_DIB_BLOCK@ | Reads a BMP or JPEG file into an array.
GET_DIB_SIZE@ | Gets information from a BMP or JPEG file.
PUT_DIB_BLOCK@ | Saves an array to a BMP or JPEG file.

Using a handle

CLIPBOARD_TO_SCREEN_BLOCK@ | Copies a bitmap on the clipboard to a DIB.
DIB_PAINT@ | Displays a DIB.
DIB_PRINT@ | Prints a device independent bitmap.
EXPORT_BMP@ | Exports a DIB to a BMP file.
EXPORT_GIF@ | Exports a DIB to a GIF file.
EXPORT_PCX@ | Exports a DIB to a PCX file.
GET_SCREEN_DIB@ | Copies part of a graphics area.
IMPORT_BMP@ | Reads in a BMP file.
IMPORT_PCX@ | Reads in a .PCX file.
IMPORT_GIF@ | Reads in a .GIF file.
PRINT_DIB@ | Obsolete, use DIB_PRINT@.
RELEASE_SCREEN_DIB@ | Releases memory for a DIB.

See Drawing device independent bitmaps for further details.


Graphics functions (font,text)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

BOLD_FONT@ | Makes text on a drawing surface bold.
CHOOSE_FONT@ | Displays a standard Windows dialog box so that the user can select a font and its colour.
DRAW_CHARACTERS@ | Draws text on a drawing surface.
FONT_METRICS@ | Gets the system metrics for the default font and the current drawing surface.
GET_FONT_ID@ | Gets the font identifier for the current drawing surface.
GET_FONT_NAME@ | Returns the name of a loaded font.
GETFONTSIZE@ | This returns the LOGFONT character width and height for a given font handle.
GET_SYSTEM_FONT@ | Gets the attributes of the system font.
GET_TEXT_SIZE@ | Gets the dimensions of a given character string.
GETTEXTSIZE@ | Gets the dimensions of a given string on a given control.
ITALIC_FONT@ | Makes text on a drawing surface italic.
ROTATE.FONT@ | Rotates the font being used on a drawing surface.
SCALE_FONT@ | Scales the font being used on a drawing surface.
SELECT_FONT@ | Selects a font for a drawing surface.
SELECT_FONT_ID@ | Selects a font for a drawing surface.
SIZE_IN_PIXELS@ | Sets the font size for a drawing surface.
SIZE_IN_POINTS@ | Sets the font size for a drawing surface.
UNDERLINE_FONT@ | Underlines text on a drawing surface.
USE_WINDOWS95_FONT@ | Sets the default font to Windows 95 font (Windows 95 only).


Graphics functions (lines,fill)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

The following routines draw to the current drawing surface . The colour value that is used will depend on the selected colour mode for the surface (either RGB mode or VGA mode). See Graphics for details.

CLEAR_SCREEN@ | Clears a drawing surface.
DRAW_BEZIER@ | Draws a Bezier spline.
DRAW_ELLIPSE@ | Draws an ellipse.
DRAW_FILLED_ELLIPSE@ | Fills an ellipse.
DRAW_FILLED_POLYGON@ | Fills a polygon.
DRAW_FILLED_RECTANGLE@ | Fills a rectangle.
DRAW_LINE_BETWEEN@ | Draws a straight graphics line.
DRAW_POINT@ | Sets the colour of a pixel..
DRAW_POLYLINE@ | Draws a number of connected straight lines.
DRAW_RECTANGLE@ | Draws a rectangle.
FILL_SURFACE@ | Fills a area with a given colour.
FILL_TO_BORDER@ | Fills a area with a given colour.
GET_GRAPHICS_SELECTED_AREA@ | Gets the current screen 'rubber-band' rectangle.
GET_POINT@ | Gets the colour of a pixel..
SET_GRAPHICS_SELECTION@ | Selects a screen 'rubber-band' mode.
SET_LINE_STYLE@ | Sets the line style.
SET_LINE_WIDTH@ | Sets the line width.


Graphics functions (metafiles)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

A metafile is a device independent representation for graphics images. You need to open a metafile if you use either DO_COPIES@ or PRINT_GRAPHICS_PAGE@ to print a graphics image (an example appears in Using a metafile to print multiple copies).

CLOSE_METAFILE@ | Closes a previously opened metafile.
DO_COPIES@ | Produces multiple printer copies using a metafile.
METAFILE_TO_CLIPBOARD@ | Sends a metafile to the clipboard.
OPEN_METAFILE@ | Records graphics sequences so that they can be replayed to the printer.
PLAY_CLIPBOARD_METAFILE@ | Plays a clipboard metafile on the current drawing surface.
PRINT_GRAPHICS_PAGE@ | Prints a drawing surface using a metafile.


Graphics functions (palette)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

GET_DISPLAY_BITS@ | Gets the number of screen colours.
GET_MATCHED_COLOUR@ | Gets the closest match on the current drawing surface.
GET_NEAREST_SCREEN_COLOUR@ | Gets the closest screen colour match from the system palette.
GET_RGB_VALUE@ | Gets the RGB value of the colour of a pixel on the current drawing surface.
HIGH_COLOUR_MODE@ | Tests if the screen is a high colour device.
SET_RGB_COLOURS_DEFAULT@ | Changes the global default colour mode.
USE_APPROXIMATE_COLOURS@ | Switches off colour matching.
USE_RGB_COLOURS@ | Switches between VGA colour mode and RGB colour mode on a drawing surface.

The following functions access an intenal ClearWin+ palette - a logical palette that is attached to the device context of each drawing surface. Palettes are redundant if the graphics device is a high colour device (i.e. has more than 8 bits per pixel). These functions are unsupported and nolonger documented.

GET_COLOURS@ | Accesses palette data.
GET_PCL_PALETTE@ | Accesses palette data.
LOAD_PCL_COLOURS@ | Loads standard PCL colours.
LOAD_STANDARD_COLOURS@ | Loads standard VGA colours.
PERFORM_COLOURS@ | Implements a palette change.
SET_COLOURS@ | Loads given palette data.


Graphics functions (printer,files)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

CLOSE_PRINTER@ | To output to a graphics printer or plotter.
CLOSE_PRINTER_ONLY@ | Closes a graphics printer or plotter without output.
GET_PRINTER_ORIENTATION@ | Gets the printer orientation as portrait or landscape.
NEW_PAGE@ | Provides a new page on the current drawing surface.
OPEN_GL_PRINTER@ | Begins OpenGL output to a graphics printer.
OPEN_GL_PRINTER1@ | Begins OpenGL output to a graphics printer.
OPEN_PRINTER@ | Begins output to a graphics printer or plotter.
OPEN_PRINTER_TO_FILE@ | Begins output to a file.
OPEN_PRINTER1@ | Begins output to a graphics printer or plotter.
OPEN_PRINTER1_TO_FILE@ | Begins output to a file.
PRINT_OPENGL_IMAGE@ | Prints an OpenGL image.
SELECT_PRINTER@ | Configures and selects the active printer.
SET_PRINTER_ORIENTATION@ | Sets the printer orientation to portrait or landscape.

See also Graphics functions (metafiles).


Graphics functions (screen,regions)

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

Regions

COPY_GRAPHICS_REGION@ | Copies one drawing surface to another.
CREATE_GRAPHICS_REGION@ | Creates a drawing surface.
DELETE_GRAPHICS_REGION@ | Removes a drawing surface.
GRAPHICS_TO_CLIPBOARD@ | Copies a drawing surface to the clipboard.
SCROLL_GRAPHICS@ | Scrolls a drawing surface.
SELECT_GRAPHICS_OBJECT@ | Selects a drawing surface.
EXPORT_IMAGE@ | Writes a drawing surface to an image file.
IMPORT_IMAGE@ | Pastes an image on to a drawing surface from a file or an internal resource.

These are used together with the DIB functions listed in Graphics functions (device independent bitmap). An alternative set of routines uses the concept of a virtual screen (a legacy from DOS programming). The alternative set is described in the ClearWin+ User's Supplement.

Other routines

GET_GRAPHICAL_RESOLUTION@ | Gets the width and height of the current drawing surface.
GRAPHICS_WRITE_MODE@ | Selects replace/XOR mode before writing to a drawing surface.
PERFORM_GRAPHICS_UPDATE@ | Refreshes a drawing surface's display.


Hypertext functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

The following routines can be used in association with the %ht format described in Hypertext windows.

ADD_HYPERTEXT@ | Adds text to the hypertext system.
ADD_HYPERTEXT_RESOURCE@ | Opens a hypertext resource that is included in a resource file.
CHANGE_HYPERTEXT@ | Changes the topic in a hypertext control.
USE_URL@ | Opens a web document or any file that has a registered extension.


Information functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

The following routines can be used in association with the winio@ function.

CLEARWIN_FLOAT@ | Interrogates the state of the ClearWin+ environment.
CLEARWIN_INFO@ | Interrogates the state of the ClearWin+ environment.
CLEARWIN_STRING@ | Obtains string information from ClearWin+.
CLEARWIN_VERSION@ | Gets the current ClearWin+ version information.
SET_CLEARWIN_FLOAT@ | Sets or change a floating point value associated with a named string.
SET_CLEARWIN_INFO@ | Sets or change an integer value associated with a named string.
SET_CLEARWIN_STRING@ | Sets or change a string value associated with a named string.

See also General functions.


Mouse functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

GET_MOUSE_INFO@ | Gets the mouse position, mouse state and keyboard state.
SET_MOUSE_CURSOR_POSITION@ | Sets the mouse position relative to a given window.


Movie functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

MOVIE_PLAYING@ | To test if a video is still playing.
SHOW_MOVIE@ | To show a video.


Sound functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

These functions require a sound card such as Sound Blaster. Note that simple WAV resources can be played using the 'SOUND' standard call-back function.

CLOSE_CD_TRAY@ | Closes an open CD-drive tray.
CLOSE_WAV_FILE@ | Closes a WAV file opened by OPEN_WAV_FILE_READ@ or OPEN_WAV_FILE_WRITE@
GET_TRACK_LENGTH@ | Returns the length of a CD track.
OPEN_CD_TRAY@ | Opens a CD-drive tray.
OPEN_WAV_FILE_READ@ | Opens a WAV file for reading in sections.
OPEN_WAV_FILE_WRITE@ | Opens a WAV file for reading in sections.
PLAY_AUDIO_CD@ | Plays the audio CD from the current position.
PLAY_SOUND@ | Sends a sample to the audio output device.
PLAY_SOUND_RESOURCE@ | Sends a resource SOUND to the current audio device.
RECORD_SOUND@ | Records sound from the sound input device.
SET_CD_POSITION@ | Sets the position of the CD read head to TRACK + MILLISECONDS (offset).
SET_SOUND_SAMPLE_RATE@ | Sets the sampling speed.
SOUND_PLAYING@ | Tests for ongoing sound output.
SOUND_RECORDING@ | Tests if a recording is being made.
SOUND_SAMPLE_RATE@ | Returns the current sound sampling rate.
STOP_AUDIO_CD@ | Stops audio playback from the CD.
WAV_FILE_READ@ | Reads a WAV file as a samples wave-form.
WAV_FILE_WRITE@ | Stores any recorded data.
WRITE_WAV_FILE@ | Stores any recorded data.


Standard dialog functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

BROWSE_FOR_FOLDER@ | Displays a dialog box from which the user can select a folder.
CHOOSE_COLOUR@ and CHOOSE_COLOUR_EX@ | Displays a standard Windows dialog box so that the user can select a colour.
CHOOSE_FONT@ | Displays a standard Windows dialog box so that the user can select a font and its colour.
DEFINE_FILE_EXTENSION@ | Allows application registry.
GET_FILTERED_FILE@ | Accesses the standard 'open' dialog box.
GET_MULTIPLE_FILENAMES@ | Accesses the standard 'open' dialog box to open multiple files.
SET_OPEN_DIALOG_PATH@ | Sets the initial directory before displaying the standard file open dialog box.

See also standard call-back functions (Standard call-back functions).


Useful API functions

In this section:

  • ClearWin window functions
  • Clipboard functions
  • File mapping functions
  • Format window functions
  • General functions
  • Graphics functions (bitmaps,cursors,icons)
  • Graphics functions (device context)
  • Graphics functions (device independent bitmap)
  • Graphics functions (font,text)
  • Graphics functions (lines,fill)
  • Graphics functions (metafiles)
  • Graphics functions (palette)
  • Graphics functions (printer,files)
  • Graphics functions (screen,regions)
  • Hypertext functions
  • Information functions
  • Mouse functions
  • Movie functions
  • Standard dialog functions
  • Sound functions
  • Useful API functions

The following API functions are simple to use and are occasionally useful in ClearWin+ programs. Details can be found in Microsoft SDK documentation.

BringWindowToTop | Brings the specified window to the top of the "Z order".
ClipCursor | Confines the mouse cursor to a given rectangle. Use CORE4(0) to represent the NULL pointer. Use an integer array to represent the RECT structure.
CopyFile | Copies one file to another.
CreateProcess | For simplicity use START_PROCESS@.
EnableWindow | Enables/disables a window.
FindWindow | Finds the handle of a window from its class name and/or its title.
GetDeskTopWindow | Gets the window handle of the screen.
GetWindowLong | Gets window parameters such as style and extended style.
GetWindowText | Gets the title of a window.
IsIconic | Tests if a window is minimised.
IsWindowVisible | Tests if a window is visible.
IsZoomed | Tests if a window is maximised.
MoveWindow | Changes a window's position and dimensions.*
PathFindOnPath | Searches for a specified file looking in standard system directories and on the environment PATH.
SetWindowLong | Sets window parameters such as style and extended style.
SetWindowPos | Changes a window's position, dimensions and state.*
SetWindowText | Sets the title of a window.
ShellExecute | Opens or prints a file (e.g. accesses a website, see USE_URL@).
ShowWindow | Changes a windows state: visible, minimised, etc.
WinExec | Starts another application (see also START_PROCESS@).
WinHelp | Displays a Windows help file.

* See also GET_WINDOW_LOCATION@ and its associated notes.


Library reference

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ABORT@

Platform

Win32, x64

Purpose

To terminate a program in the event of an error.

Syntax

SUBROUTINE ABORT@( )

Description

Normally when a program terminates - e.g. by executing a STOP statement, or by encountering the END statement in the main program - any windows that are open are left open until the user closes them and call-back functions continue to be called to service the open windows.

Sometimes, if for example a serious error is detected, it may be necessary to terminate the program immediately in which case the subroutine ABORT@ should be called.

See also

EXIT subroutine, EXIT callback


ACTIVATE_BITMAP_PALETTE@

Platform | Win32, x64
Purpose | To ensure that the palette is set correctly for the current window.
Syntax | SUBROUTINE ACTIVATE_BITMAP_PALETTE@( DC ) INTEGER DC
Description | This subroutine restores the current palette that the device context is using. This is usually handled by Clearwin+.
See also | ATTACH_BITMAP_PALETTE@, CLEAR_BITMAP@, CREATE_BITMAP@, GET_BITMAP_DC@


ADD_ACCELERATOR@

Platform | Win32, x64
Purpose | To associate an accelerator key with a given window.
Syntax | SUBROUTINE ADD_ACCELERATOR@( HWND, KEY_NAME, F ) INTEGER(7) HWND CHARACTER(*) KEY_NAME EXTERNAL F
Description | This associates the callback function F with the named key (see the definition of %ac in Accelerator key format for details of the names of keys). HWND is the handle of the window which you can obtain using %hw when the window is created. If a previous accelerator definition for this key in this window exists then it is removed.
Notes | You could use this routine if you were writing a configurable editor and you wished to change the accelerator definitions of the surounding window dynamically. The call-back function cannot be a string representing a standard call-back.
See also | %ac, REMOVE_ACCELERATOR@


ADD_CURSOR_MONITOR@

Platform

Win32, x64

Purpose

To name a call-back function that monitors which window or control has the cursor.

Syntax

SUBROUTINE ADD_CURSOR_MONITOR@( CB_FUNC )
EXTERNAL CB_FUNC

Description

A general mechanism is available to enable programmers to monitor the window/control that has the cursor (or the focus, see ADD_FOCUS_MONITOR@).

CB_FUNC is the name of a routine that is either a function returning an integer, or a SUBROUTINE. The return value (if any) is not used. Cursor call-back functions can use the CLEARWIN_INFO@ parameter 'CURSOR_WINDOW' to determine the (integer kind=7) window handle of the control or window that has the cursor.

Notes

a) Window handles can be obtained using %hw or %lc.

b) Although window handles are unique at any given time, handles can (and often do) get re-used after a window has been destroyed.

See also

REMOVE_CURSOR_MONITOR@, ADD_FOCUS_MONITOR@


ADD_FOCUS_MONITOR@

Platform | Win32, x64
Purpose | To name a call-back function that monitors which control has the focus.
Syntax | SUBROUTINE ADD_FOCUS_MONITOR@( CB_FUNC ) EXTERNAL CB_FUNC
Description | See ADD_CURSOR_MONITOR@. Focus call-back functions use the CLEARWIN_INFO@ parameter 'FOCUSSED_WINDOW'.
Notes | The CLEARWIN_INFO@ parameter used here is not the same as 'FOCUS_WINDOW' which returns the handle of the WINIO@ window which has focus rather than the control within the window that has the focus.
See also | REMOVE_FOCUS_MONITOR@, ADD_CURSOR_MONITOR@


ADD_GRAPHICS_ICON@

Platform

Win32, x64

Purpose

To place a movable icon or bitmap in a %gr graphics region.

Syntax

INTEGER(7) FUNCTION ADD_GRAPHICS_ICON@(NAME, X, Y,
+ WIDTH, DEPTH)
CHARACTER(*) NAME
INTEGER X, Y, WIDTH, DEPTH

Description

A %gr graphics region may have an icon resource 'attached' to it. The icon can be moved freely around the graphics window with the mouse. Control of the icon is maintained by the call-back function attached to the %gr window with the caret modifier (^).

The NAME argument is that used for the resource that is included in your program. If the image is directly imported from a file then set NAME to the file name enclosed in curly backets. The X and Y values, initially hold the location the image is draw to. They also hold the new position when the image is moved. The CLEARWIN_INFO@ parameter 'DRAGGED_ICON' is set to the value of the handle of the moved icon. The handle is initially obtained as the returned from the function. The call-back function may modify the X and Y values if required. The purpose of this may be to 'lock' the image onto the horizontal or vertical plane by continuously setting either the X or Y variables to a constant value.

When the icon is dropped CLEARWIN_INFO@ parameter 'DROPPED_ICON' is set to the handle of the icon. A graphics icon can be removed with a call to REMOVE_GRAPHICS_ICON@.

The width and height parameters should be set at zero except when the icon image occupies less than the possible 32x32 icon area e.g. 16x16. A small icon can be constructed by starting at the top-left corner and filling the remaining unused area with the 'transparent' colour. If you do not specify the correct size of the icon then the unused area will be detected by the mouse.

Return value

Returns a non-zero value for success or zero for failure.

See also

REMOVE_GRAPHICS_ICON@, %gr Graphics icons


ADD_HYPERTEXT@

Platform | Win32, x64
Purpose | To add text to the hypertext system.
Syntax | SUBROUTINE ADD_HYPERTEXT@( BUFFER, SIZE, HTEXTNAME ) CHARACTER(*) BUFFER, HTEXTNAME INTEGER SIZE
Description | ADD_HYPERTEXT@ adds, to the hypertext resource base, a hypertext document containing one or more hypertext topics. Note that this routine does not take a copy of the hypertext data so you must ensure that the memory is not changed or discarded before any hypertext processing is complete. The format code %ht is used to display the hypertext resource. Resources may be included in the resource section of your program/resource script.
See also | ADD_HYPERTEXT_RESOURCE@


ADD_HYPERTEXT_RESOURCE@

Platform | Win32, x64
Purpose | To open a hypertext resource that is included in a resource file.
Syntax | SUBROUTINE ADD_HYPERTEXT_RESOURCE@( NAME ) CHARACTER(*) NAME
Description | The resource file must be added to combine the hypertext document with the program using it. The resource filename should be placed on the WINAPP line after the stack and heap size declarations. See %ht format and the browse example code included with the ClearWin+ release.
See also | ADD_HYPERTEXT@
Example | WINAPP 50000, 50000, 'MYPROG.RC' Where myprog.rc is a list of resources. For example: HYPSOMEINFO HYPERTEXT "info1.htm"


ADD_KEYBOARD_MONITOR@

Platform | Win32, x64
Purpose | To name a call-back function that monitors the use of the keyboard.
Syntax | SUBROUTINE ADD_KEYBOARD_MONITOR@( CB_FUNC ) EXTERNAL CB_FUNC
Description | See ADD_CURSOR_MONITOR@. Keyboard call-back functions use the CLEARWIN_INFO@ parameter 'KEYBOARD_KEY'.
Notes | This routine replaces GET_WKEY@ and GET_WKEY1@ and should be used in preference to these routines. Calls to these routines will fail if ADD_KEYBOARD_MONITOR@ has been called.
See also | REMOVE_KEYBOARD_MONITOR@, ADD_CURSOR_MONITOR@


ADD_MENU_ITEM@

Platform

Win32, x64

Purpose

To create a dynamic menu using %mn.

Syntax

SUBROUTINE ADD_MENU_ITEM@( HANDLE, NAME, ENABLE,
+ CHECK, CALLBACK_FUNCTION)
INTEGER(7) HANDLE
INTEGER ENABLE, CHECK, CALLBACK_FUNCTION
CHARACTER(*) NAME

Description

By using %mn, menu items can be added at run time. This is of greatest use when you wish to show a file history or a list of open windows. Items are added one at a time to the end of the pop down menu that contains the handle.

In %mn (see Menu format) an asterisk (*) must be added where a text description would previously have been placed and a integer (kind=7) argument, instead of a call-back, must be provided to hold the handle.

For example:

i=winio@('%mn[&Window[*]]&',HANDLE)

HANDLE can then be passed to ADD_MENU_ITEM@.

NAME is the new string to put into the menu i.e. the new menu item. ENABLE controls the enabling of the item (1 for enabled, zero for disabled, i.e. greyed) and the CHECK will add or remove a tick character (1 for checked, zero for unchecked). A call-back function must be provided so that ClearWin+ can act upon a menu selection. A separator is obtained if name is input as char(0).

Example

See Dynamic menus.

See also

REMOVE_MENU_ITEM@, %mn, Menu format


ATTACH_BITMAP_PALETTE@

Platform | Win32, x64
Purpose | To attach a palette to a DC.
Syntax | INTEGER ATTACH_BITMAP_PALETTE@( HDC, P ) INTEGER(7) HDC, P
Description | To attach a colour palette to a device context. This should not normally be needed as SET_COLOURS@ provides sufficient flexibility.
Return value | On success 1 will be returned. -1 indicates that the screen type cannot provide the palette requested due to too few palette entries available. A zero indicates that the display is in full colour mode and therefore does not use a palette.
See also | ACTIVATE_BITMAP_PALETTE@


AUTO_SCALE_FONT@

Platform | Win32, x64
Purpose | To scale fonts to a sensible size ready for printing.
Syntax | SUBROUTINE AUTO_SCALE_FONT@()
Description | When drawing to a printer via PRINT_GRAPHICS@ a call to AUTO_SCALE_FONT@ will automatically scale the font to a reasonable size for the printer resolution. Otherwise CLEARWIN_INFO@ (with "GRAPHICS_WIDTH" and "GRAPHICS_DEPTH") can be called in order to get the pixel width and height and to assign a suitable scaling factor in a call to SCALE_FONT@.
Notes | Introduced with FTN95 8.30.
See also | PRINT_GRAPHICS@


BOLD_FONT@

Platform | Win32, x64
Purpose | To change the current drawing surface text to/from bold.
Syntax | SUBROUTINE BOLD_FONT@( ACTIVE ) INTEGER ACTIVE
Description | When using the function DRAW_CHARACTERS@ on a drawing surface with any font selected (other than a Hershey font), a call to this routine with a value of one will make any further text output bold. A further call with a value of zero will reverse the effect.
See also | ROTATE_FONT@, SCALE_FONT@, SELECT_FONT@, ITALIC_FONT@, UNDERLINE_FONT@


BREAK_MODEM_CONNECTION@

Platform | Win32, x64
Purpose | To close a modem connection if one exists.
Syntax | SUBROUTINE BREAK_MODEM_CONNECTION@()
Description | See Linking to the web .


BROWSE_FOR_FOLDER@

Platform

Win32, x64

Purpose

To display a dialog box from which the user can select a folder.

Syntax

LOGICAL FUNCTION BROWSE_FOR_FOLDER@(INSTR,PATH)
CHARACTER(*) INSTR, PATH

Description

INSTR is an input string that appears in the dialog box as instructions to the user. PATH is an output string that gives the full path of the folder selected by the user. If a valid folder is not selected or the user clicks on the CANCEL button, PATH is returned as an empty string and the function returns .FALSE..

You can provide an initial PATH, that is automatically selected when the dialog is opened, by making a prior call to the subroutine SET_BROWSE_FOR_FOLDER_INITIAL@(PATH).

Return value

The function returns .FALSE. if a valid folder is not selected or if the user clicks on the CANCEL button.

See Also

BROWSE_FOR_FOLDER1@


BROWSE_FOR_FOLDER1@

Platform

Win32, x64

Purpose

To display a dialog box from which the user can select a folder.

Syntax

LOGICAL FUNCTION BROWSE_FOR_FOLDER1@(HWND,INSTR,PATH,FLAGS)
INTEGER(7) HWND
CHARACTER(*) INSTR, PATH
INTEGER FLAGS

Description

An extended version of BROWSE_FOR_FOLDER@. INSTR is an input string that appears in the dialog box as instructions to the user. PATH is an output string that gives the full path of the folder selected by the user. If a valid folder is not selected or the user clicks on the CANCEL button, PATH is returned as an empty string and the function returns .FALSE..

You can provide an initial PATH, that is automatically selected when the dialog is opened, by making a prior call to the subroutine SET_BROWSE_FOR_FOLDER_INITIAL@(PATH).

HWND can be set to zero or to the Windows handle of the parent window.

FLAGS can be used to customise the appearance of the dialog box. Passing z'40' allows for features like folder creation. A full list of the flags is available in the documentation for the ulFlags member of the BROWSEINFO structure.

Return value

The function returns .FALSE. if a valid folder is not selected or if the user clicks on the CANCEL button.

Notes

Added to FTN95 at version 7.10


CHANGE_BUTTON_TEXT@

Platform

Win32, x64

Purpose

To change the text on a %bt or %tt button.

Syntax

SUBROUTINE CHANGE_BUTTON_TEXT@( HWND, BUTTONTEXT )
INTEGER(7) HWND
CHARACTER(*) BUTTONTEXT

Description

HWND is the handle of a button control obtained using %lc.

The size of the button depends on the initial text supplied using %bt or %tt. If BUTTONTEXT is longer than this then it may not fit on to the button.

This facility should be used sparingly because a window with several buttons that change their meaning on the fly may confuse the user. One potential use is to create toggle buttons with text such as Start and Stop. In this case you would typically place the call to CHANGE_BUTTON_TEXT@ inside the callback routine for the button and use a variable to keep track of state of the toggle.

See also

%bt, %tt


CHANGE_HELP_TEXT@

Platform | Win32, x64
Purpose | To change the help text associated with a contol.
Syntax | SUBROUTINE CHANGE_HELP_TEXT@( HWND, TEXT ) INTEGER(7) HWND CHARACTER(*) TEXT
Description | This is for help strings that are not ms_style tooltips. These occur when %th is used without [ms_style] or an option that implies [ms_style]. They also occur when a control is defined using the ? modifier (e.g. %?bt[OK]) and when neither %th nor %bh is present. HWND is the Windows handle of the controls obtained using %lc.


CHANGE_HYPERTEXT@

Platform | Win32, x64
Purpose | To change the topic in a hypertext control.
Syntax | SUBROUTINE CHANGE_HYPERTEXT@( HWND, TOPICNAME ) INTEGER(7) HWND CHARACTER(*) TOPICNAME
Description | TOPICNAME is the name of the topic to select (as in <DOC name = "doc_name">) and HWND is the handle of the main window returned by %hw.


CHANGE_PEN@

Platform | Win32, x64
Purpose | To change the pen in a device context acquired through GET_BITMAP_DC@.
Syntax | INTEGER FUNCTION CHANGE_PEN@(HDC,PEN_STYLE,WIDTH,COLOUR) INTEGER(7) HDC INTEGER PEN_STYLE,WIDTH,COLOUR
Description | The pen associated with a device context acquired through GET_BITMAP_DC@ can be changed using the Windows API function SelectObject. However, when using the CHANGE_PEN@ function, ClearWin+ keeps track of which pens have been created, re-uses them where possible and finally deletes them automatically. The style, width, and colour arguments are as supplied to the Windows API function CreatePen.
Return value | Always returns 1.


CHOOSE_COLOUR@

Platform | Win32, x64
Purpose | To display a standard Windows dialog box so that the user can select a colour.
Syntax | INTEGER CHOOSE_COLOUR@( )
Return value | This function returns the RGB value of the colour selected by the user or -1 if the operation is cancelled. The user can use the dialog to define custom colours that are available if the dialog is opened again before the program terminates (default values are restored when the program restarts).
See also | CHOOSE_FONT@, CHOOSE_COLOUR_EX@


CHOOSE_COLOUR_EX@

Platform

Win32, x64

Purpose

To display a standard Windows dialog box so that the user can select a colour.

Syntax

SUBROUTINE CHOOSE_COLOUR_EX@( COLOUR, CUSTOM, FLAGS )
INTEGER COLOUR, CUSTOM(16), FLAGS

Return value

This is a more flexible alternative to the simpler CHOOSE_COLOUR@.

COLOUR is both the initial value and the value returned by the dialog. A returned value of -1 means that the dialog has been canceled.

CUSTOM is both the initial set of values for the "Custom colors" in the dialog and the values for this set returned by the dialog.

FLAGS is an input value that is normally set to zero. When non-zero, the value is used in the resulting call to the Microsoft API function called ChooseColor.

The user can use the dialog to define custom colours that are available if the dialog is opened again before the program terminates (default values are restored when the program restarts).

Example

  INTEGER colour,custom(16)
  colour = RGB@(0,0,0)
  custom = RGB@(255,255,255)
  CALL CHOOSE_COLOUR_EX@(colour, custom, 0)
  IF(colour /= -1) THEN ...

See also

CHOOSE_COLOUR@, CHOOSE_FONT@


CHOOSE_FONT@

Platform

Win32, x64

Purpose

To display a standard Windows dialog box so that the user can select a font, its attributes and its colour.

Syntax

SUBROUTINE CHOOSE_FONT@( RBGCOLOUR )
INTEGER RGBCOLOUR

Description

This function displays a dialog box that allows the user to select a font, its attributes (bold, italic, underline, strikeout) and its colour. This becomes the font for the current drawing surface. RBGCOLOUR is used for both input and output. On input it is the colour that is initially selected in the dialog box. On output it is the RGB value selected by the user.

If this font is to be restored after a change of font then you should call GET_FONT_ID@ before the change and then SELECT_FONT_ID@ to restore the font.

See also

GET_FONT_ID@, SELECT_FONT_ID@ CHOOSE_COLOUR@


CLEARWIN_FLOAT@

Platform | Win32, x64
Purpose | To access ClearWin+ parameters.
Syntax | DOUBLE PRECISION FUNCTION CLEARWIN_FLOAT@( PARAM ) CHARACTER(*) PARAM
Description | Parameters are specified as case insensitive character strings. They may be system or user-defined values.
Return value | Returns the value of the specified floating point parameter.
See also | SET_CLEARWIN_FLOAT@


CLEARWIN_INFO@

Platform

Win32, x64

Purpose

To access ClearWin+ parameters.

Syntax

INTEGER(7) FUNCTION CLEARWIN_INFO@( PARAM )
CHARACTER(*) PARAM

Description

Parameters are specified as case insensitive character strings. They may be system or user-defined values.

The following parameters are defined:

ACTION_X
Provides the X value of the control that has generated the call-back.

ACTION_Y
Provides the Y value of the control that has generated the call-back.

ACTIVE_EDIT_BOX
Returns the address of the EDIT_INFO array of the currently active %eb box. Notice that this edit box might not have focus if, for example, the user had just moved to a menu item.

BUTTON_NUMBER
Returns the button pressed.

CALL_BACK_WINDOW
Returns the Windows HANDLE of the main window that has generated the call-back.

COLUMN_NUMBER
The column clicked in a %lv when the reason is COLUMN_CLICK.

CURRENT_CONTROL
Returns the Windows HANDLE of the control that has generated the call-back.

CURSOR_WINDOW
Used with ADD_CURSOR_MONITOR@. Gives the HANDLE of the control which currently has the cursor.

DRAGGED_ICON
Is set to the value of the HANDLE for the dragged icon, indicating that a icon is currently being dragged (see ADD_GRAPHICS_ICON@).

DROPPED_COUNT
Used with the %dr call-back function to return the number of files dropped.

DROPPED_CURRENT
Used with the %dr call-back function to return the number of the current file being processed (in the range from 1 to the value supplied by DROPPED_COUNT).

DROPPED_ICON
Is set to the value of the HANDLE for the recently dropped icon (see ADD_GRAPHICS_ICON@).

EDITABLE_LISTBOX_INDEX
Holds the index of the listbox item selected by the user from an editable list box (see %el).

EDIT_KEY
Used with %eb to get the ASCII value of the last key pressed. This information can be obtained in response to a return of 'DATA_ALTERATION' from CLEARWIN_STRING@('CALLBACK_REASON'). In order to activate this feature you must use the %eb[extended]. The call-back is called after the change has been made so you will need to use one of the above editing functions if you want to undo the key press.

EXTENDED_ERROR
Provides the result of a call to the Windows API function CommDlgExtendedError().

FILTER_ITEM_SELECTED
Holds the index of the file filter that was selected by the user when presented with a GET_FILTERED_FILE@ dialog. This can be used, for example, to detect that the user required to save a file with a different filename extension.

FOCUS_WINDOW
This parameter will return the Window HANDLE of the window with focus, or zero if no window of the application has the focus ( see %hw).

FOCUSSED_WINDOW
Used with ADD_FOCUS_MONITOR@. Gives the HANDLE of the control which currently has the keyboard focus.

GAINING_FOCUS
Returns 1 when an (%eb) edit box gains the focus.

GIF_MOUSE_X
Returns the pixel co-ordinate of a mouse click in a %gi image relative to the top left corner of the image.

GIF_MOUSE_Y
Returns the pixel co-ordinate of a mouse click in a %gi image relative to the top left corner of the image.

GRAPHICS_DC
Set during the call-back when a %dw[user_resize] graphics area is re-sized (or when it is first created). The call-back can use this to re-draw the image.

GRAPHICS_DEPTH
Provides the 'Y axis' value for the graphics window, vital if the window is resized at any point.

GRAPHICS_HDC
This provides the device context of the drawing surface. It will return zero if there is no current drawing surface. Using this HANDLE you can write additional information to a drawing surface using API functions. The handle points to a bitmap so it is also possible to extract information form this area. Do not use this HANDLE with %gr if metafile_resize has been specified. If you use YIELD_PROGRAM_CONTROL@, or if you return from a call-back there is a possibility that the drawing surface will be re-sized (replacing its HANDLE) or closed. It is therefore important to obtain the HANDLE again in such circumstances. In general, obtain the HANDLE, perform the actions you require, and discard the HANDLE.

GRAPHICS_MOUSE_FLAGS
Provides the flags associated with a mouse event in a graphics (%gr) or owner-draw (%dw) control.

The flags should be considered as a set of bits thus:

MK_LBUTTON | 1 | Left mouse button depressed
MK_LBUTTON | 2 | Right mouse button depressed
MK_SHIFT | 4 | Keyboard shift key depressed
MK_CONTROL | 8 | Keyboard control key depressed
MK_MBUTTON | 16 | Middle mouse button depressed

GRAPHICS_MOUSEWHEEL_ROTATION
Provide the movement on the mouse wheel in a graphics (%gr) or owner-draw (%dw) control.

GRAPHICS_MOUSE_X
Provide the X co-ordinate of a mouse event in a graphics (%gr) or owner-draw (%dw) control.

GRAPHICS_MOUSE_Y
Provides the Y co-ordinate of a mouse event in a graphics (%gr) or owner-draw (%dw) control.

GRAPHICS_RESIZING
This returns the value one if the window has been resized making it necessary to interrogate GRAPHICS_DEPTH and GRAPHICS_WIDTH.

GRAPHICS_WIDTH
Provides the 'X axis' value for the graphics window, vital if the window is resized at any point.

The flags should be considered as a set of bits thus:

INTERMEDIATE_SCROLL
Used with %hx and %vx to determine if the callback was called whilst the thumb is moving or after its release. Returns the value 1 if the thumb is moving, otherwise zero.

KEYBOARD_KEY
Key press in a %bv or %lv. This is in response to the reason KEY_DOWN.

LATEST_FORMATTED_WINDOW
This is set to the Windows HANDLE of the most recently created formatted window. This HANDLE should be used with care. In particular, if you make explicit Windows API calls using this HANDLE, these may interfere with the action of winio@.

LATEST_VARIABLE
Holds the address of a variable in a call-back attached to %rd, %rf or %rs.

LATEST_WINDOW
Same as LATEST_FORMATTED_WINDOW.

LISTBOX_ITEM_SELECTED
Used in a call-back function for a list box. Returns 1 if the item was "selected" by double clicking on an item in the extended list; returns zero if the item was "moved to" by using a single click.

LOSING_FOCUS
Returns 1 when an edit box (%eb) loses its focus.

MAX_GRAPHS_PER_PLOT
Maximum graphs per %pl.

MESSAGE_HWND
This is set to the HWND parameter in a call-back from the %mg format.

MESSAGE_LPARAM
This is set to the LPARAM parameter in a call-back from the %mg format.

MESSAGE_MSG
This is set to the message parameter in a call-back from the %mg format.

MESSAGE_WPARAM
This is set to the WPARAM parameter in a call-back from the %mg format.

OPENGL_ALIVE
Returns 1 if OpenGL is active and zero otherwise. If OpenGL is not active then calling OpenGL routines in ClearWin+ causes a hard error. This information function can be used to guard against such calls.

OPENGL_DEPTH
Returns the HANDLE of the device context for the current %og region.

OPENGL_DEVICE_CONTEXT
Returns the pixel depth of a resized OpenGL (%og) region.

OPENGL_WIDTH
Returns the pixel width of a resized OpenGL (%og) region.

PIXELS_PER_H_UNIT
Translates from device dependant units used by %aw etc. to absolute pixel values

PIXELS_PER_V_UNIT
Translates from device dependant units used by %aw etc. to absolute pixel values

POPUP_X
X Location of last popup menu to be displayed.

POPUP_Y
Y Location of last popup menu to be displayed.

PRINTER_COLLATE etc.
For printer parameters see Customising the printer dialog box.

ROW_NUMBER
Current item in a %bv or %lv.

SCREEN_DEPTH
Returns the vertical screen resolution. Note that the available area of the largest possible window (the client area) will be normally be a little smaller than this because of the caption, border, etc..

SCREEN_NUM_COLOURS
Number of colour available on screen.

SCREEN_WIDTH
Returns the horizontal screen resolution.

SHEET_NO
Holds the value of the current top-most property sheet (%ps). Initially it is 1.

SPIN_CONTROL_USED
This is set whilst in a call-back for a variable modified using a spin control.

SYSTEM_FONT_HEIGHT
Returns the height of the standard system font in logical units. This can be used to detect whether the user has set the Control Panel, Display Properties to Small Fonts (=16) or Large Fonts (=20) or Other....

TEXT_ARRAY_CHAR etc.
Parameters used with %tx are detailed in Text array.

TOOLTIP_HWND
Window HANDLE of current tooltip.

TREEVIEW_ITEM_SELECTED
Returns the value one when an item has been selected from a treeview control (%tv) by means of a double mouse click.

USER_DATA
Returns the address of data associated with the control by either %ud or SET_USER_DATA@. This is equivalent to calling GET_USER_DATA@ with the control's handle.

USER_WINDOW_DATA
Returns the address of data associated with the window by either %ud or SET_USER_DATA@ (rather than the control that the callback is for -- USER_DATA above returns that). This is equivalent to calling GET_USER_DATA@ with the window's handle.

Return value

Returns the value of the specified integer parameter.

See also

SET_CLEARWIN_INFO@


CLEARWIN_STRING@

Platform

Win32, x64

Purpose

To obtain an information string from ClearWin+.

Syntax

CHARACTER(*) FUNCTION CLEARWIN_STRING@( STR )
CHARACTER(*) STR

Description

When in a ClearWin+ call-back this function is used to determine extra information about the nature of the call-back. For example passing STR = 'CALLBACK_REASON' will reveal more about why the call-back was called.

The following values for STR are valid:

CHECKING_DIRECTORY, FILE_FOUND and FIND_FILE_CALLBACK_REASON
Set in the callback provided to FIND_FILE@.

CURRENT_TEXT_ITEM, CURRENT_TEXT_DOCUMENT and CURRENT_TEXT_TITLE
Information about a document being browsed to within a %ht. 'CURRENT_TEXT_ITEM' is the new URL, 'CURRENT_TEXT_DOCUMENT' is the source document and 'CURRENT_TEXT_TITLE' is the title of the current page. See Hypertext windows.

CURRENT_MENU_ITEM
This option will return a string containing the current menu item selected. It is employed when using dynamic menus that have a shared call-back (see Dynamic menus).

CURRENT_URL
Is the URL being navigated to when the callback reason is HYPERTEXT_LINK

DROPPED_FILE
Is a string containing the full path and filename of the object dropped into a format window using %dr.

ERROR_REPORT< br/> Contains the current error message if a native graph plotting routine returns an error code. See Native graph plotting.

EDITED_TEXT
When a %lv, %tv or %bv item is edited, this contains the new item text.

MESSAGE_TEXT
Contains the text sent via SEND_TEXT_MESSAGE@.

PRINTER_DOCUMENT
Contains the title of the printed document. This can be set via SET_CLEARWIN_STRING@ prior to calling routines such as PRINT_GRAPHICS_PAGE@, OPEN_PRINTER@ etc.

CALLBACK_REASON
Whenever a call-back function is invoked, this string can be used to determine the reason for the call. The following list of reasons (upper case letters only) may be extended in the future, so programs should be designed to ignore reasons which they do not recognise.

Reason | Comments
'ACCELERATOR' | Call associated with %ac.
'BEGIN_DRAG' | An item in a %lv or %bv is being dragged.
'BEGIN_EDIT' | A label is about to be edited in a %lv or %bv.
'BUTTON_PRESS' | A button has been pressed.
'CHECKBOX_CHANGE' | A checkbox in a %lv has changed state.
'CLOSEUP' | The droplist in a %el has been closed.
'COLOURING' | User_colour event for edit box (%eb).
'DATA_ALTERATION' | The contents of %eb, %rd (etc.) box have been altered.
'DIRTY' | Indicates an OpenGL window is in need of re-painting.
'DO_COMMAND' | The callback was called because of calling DO_COMMAND@. See also %rc.
'DRAG_AND_DROP' | Call in response to dropping a file onto the window.
'DROP_TARGET' | During a drag and drop this reason is used to identify when the target of the drag changes. This will change as the mouse moves. Applies to %bv and %lv.
'DROPDOWN' | The droplist in a %el has been opened.
'DROPPED_FILE' | A file has been dropped - see %dr.
'EDIT_KEY_DOWN' | The user has pressed a keyboard key during a label edit. Applies to %bv and %lv.
'END_DRAG' | An item in a %lv or %bv has completed a drag.
'END_EDIT' | A label is about to be edited in a %lv or %bv
'ENUMERATED_PARAMETER' | An enumerated parameter (%ep) has been selected from within a parameter box.
'FILE_OPEN' | Call from standard call-backs 'FILE_OPENR' or 'FILE_OPENW'.
'GAINING_FOCUS' | Edit box gets input focus.
'HSCROLL' | Horizontal scrollbar moved
'HYPERTEXT_CHANGE' | Called when hypertext is being changed.
'HYPERTEXT_LINK' | Call-back from activating a hypertext link in %ht or %wb.
'ITEM_DOUBLE_CLICKED' | Listbox item double clicked.
'ITEM_EXPANDED' | A node in a %bv has been expanded or collapsed.
'ITEM_SELECTED' | Listbox item selected.
'KEY_DOWN' | A keyboard key has been pressed.
'LEFT_MOUSE_PRESS' | This indicates that a graphics icon has been dragged within a %gr. See also: ADD_GRAPHICS_ICON@.
'LOSING_FOCUS' | Edit box loses input focus.
'MB_COMMAND' | Button press in a %mb.
'MB_CUSTOMISE?' | User has double clicked the customise dialog in a %mb.
'MB_DELETE?' | User has started moving a button in a %mb.
'MB_DROPDOWN?' | User has requested a dropdown menu in a %mb.
'MB_HELP' | User has clicked the help button in the customised dialog in a %mb.
'MB_INSERT?' | User has completed moving a button in a %mb.
'MDI_PAGE_TURN' | The active child window has changed in a %fr.
'MENU_SELECTION' | A menu item has been invoked.
'MESSAGE_HOOK' | Call of %mg related function.
'MOUSE_CLICK' | Node clicked in a %bv.
'MOUSE_ENTER', 'MOUSE_LEAVE' | Indicates that the mouse has entered or left the area of a %ib. The %ib must have the [mouse_hover] option for this callback reason to be used.
'MOUSE_LEFT_CLICK' | Left button down.
'MOUSE_LEFT_RELEASE' | Left button up.
'MOUSE_DOUBLE_CLICK' | Left double click.
'MOUSE_MIDDLE_CLICK' | Middle button down.
'MOUSE_MIDDLE_RELEASE' | Middle button up.
'MOUSE_MOVE' | Mouse movement.
'MOUSE_RIGHT_CLICK' | Right button down.
'MOUSE_RIGHT_RELEASE' | Right button up.
'PLOT_ADJUST' | When a %pl is changed -- resize for example.
'QUERY_SHUTDOWN' | Windows is asking to shutdown. See %ew.
'RESIZE' | Called when a control is being re-sized.
'SCROLL' | Scroll complete.
'SET_SELECTION' | An item has been selected in a %lv or %bv.
'SETUP' | OpenGL window resized, see %og.
'SIZE_ADJUST' | A %ib is about to be displayed.
'STRING_CHANGE' | Text has changed in a %el.
'TIMER' | Timer has fired in a %dl.
'USER_MESSAGE' | Message recieved via %rm.
'USER_PARAMETER' | A user parameter (%up) has been selected from within a parameter box.
'TIMER' | Call associated with %dl.
'VSCROLL' | Vertical scrollbar moved
'WINDOW_CLOSE' | Call in response to %cc.
'WINDOW_CLOSED' | Call in response to %`cc.
'WINDOW_STARTUP' | Call in response to %sc.
'+' | Called as part of a compound call-back.
'?' | Not currently in a call-back.

Return value | Returns the value of the specified string parameter.
See also | SET_CLEARWIN_STRING@


CLEARWIN_VERSION@

Platform | Win32, x64
Purpose | Gets the current ClearWin+ version information.
Syntax | INTEGER FUNCTION CLEARWIN_VERSION@()
Return value | The minor version number is stored in the lower byte of the returned value and the major version number is stored in the second byte.
Example | WINAPP INCLUDE <windows.ins> INTEGER version, i version=clearwin_version@() i=winio@('%ca[Version information]&') i=winio@('%nlMajor %wd minor%wd%nl', + version/256,AND(version,255)) END


CLEAR_BITMAP@

Platform | Win32, x64
Purpose | To clear a bitmap device context acquired by GET_BITMAP_DC@.
Syntax | SUBROUTINE CLEAR_BITMAP@( HDC ) INTEGER(7) HDC
Description | The bitmap associated with the given device context is cleared to the current Windows background
See also | GET_BITMAP_DC@, RELEASE_BITMAP_DC@, %dw


CLEAR_SCREEN@

Platform | Win32, x64
Purpose | To clear the drawing surface.
Syntax | SUBROUTINE CLEAR_SCREEN@
Description | CLEAR_SCREEN@ clears the current drawing surface to the default background.
See also | DRAW_FILLED_RECTANGLE@.


CLEAR_WINDOW@

Platform | Win32, x64
Purpose | To clear a given ClearWin window to its given background colour.
Syntax | SUBROUTINE CLEAR_WINDOW@(HWND) INTEGER(7) HWND
Description | All text written to the window will be cleared and all call-back requests deleted. This is effectively 'clear screen' and leaves the window in a state as if it had just been created. HWND is the window handle returned by CREATE_WINDOW@.


CLIPBOARD_TO_SCREEN_BLOCK@

Platform | Win32, x64
Purpose | To copy a bitmap on the clipboard to a device independent bitmap (DIB).
Syntax | INTEGER FUNCTION CLIPBOARD_TO_SCREEN_BLOCK@( HDIB ) INTEGER(7) HDIB
Description | This function copies a bitmap from the clipboard and returns a handle HDIB to the device independent bitmap that it creates. This handle can then be used, for example, with DIB_PAINT@, DIB_PRINT@ and EXPORT_BMP@.
Return value | A function return value of zero indicates a failure (e.g. the current clipboard data is of the wrong type).
See also | GET_SCREEN_DIB@, RELEASE_SCREEN_DIB@, IMPORT_BMP@


CLOSE_CD_TRAY@

Platform | Win32, x64
Purpose | To close an open CD-drive tray.
Syntax | SUBROUTINE CLOSE_CD_TRAY@()
Description | Simply by calling this routine any open CD drive with a mechanical drawer will close.
See also | OPEN_CD_TRAY@, PLAY_AUDIO_CD@, SET_CD_POSITION@, STOP_AUDIO_CD@
Example | WINAPP INTEGER i,ctrl,winio@ EXTERNAL cb_open,cb_close ctrl=1 i=winio@('%ca[CD Tray Control]%nl&') i=winio@('%^bt[OPEN] ^bt[CLOSE]%lw',cb_open,cb_close,ctrl) END INTEGER FUNCTION cb_open() include <windows.ins> CALL open_cd_tray@() cb_open=2 END INTEGER FUNCTION cb_close() INCLUDE <windows.ins> CALL close_cd_tray@() cb_close=2 END


CLOSE_METAFILE@

Platform | Win32, x64
Purpose | To close a previously opened metafile.
Syntax | INTEGER CLOSE_METAFILE@( UID ) INTEGER UID
Description | If UID is zero then the current drawing surface is used otherwise an identifier to an existing drawing surface should be supplied.
See also | OPEN_METAFILE@, METAFILE_TO_CLIPBOARD@, PLAY_CLIPBOARD_METAFILE@


CLOSE_PRINTER@

Platform | Win32, x64
Purpose | To close output to a graphics printer or plotter.
Syntax | INTEGER FUNCTION CLOSE_PRINTER@( UID ) INTEGER UID
Description | See OPEN_PRINTER@. If UID is zero, the current printer is closed.
Return value | Returns 1 for success or zero for failure.
See also | DO_COPIES@, OPEN_PRINTER@, SELECT_PRINTER@, CLOSE_PRINTER_ONLY@


CLOSE_PRINTER_ONLY@

Platform | Win32, x64
Purpose | To close a graphics printer or plotter without output.
Syntax | INTEGER FUNCTION CLOSE_PRINTER_ONLY@( UID ) INTEGER UID
Description | Use this function instead of CLOSE_PRINTER@ if you want to abort a printing process without output. See OPEN_PRINTER@.
Return value | Returns 1 for success or zero for failure.
See also | CLOSE_PRINTER@, OPEN_PRINTER@, SELECT_PRINTER@


CLOSE_SVG@

Platform | Win32, x64
Purpose | To end and close graphics output to an SVG file opened with OPEN_SVG@ or OPEN_SVG1@.
Syntax | INTEGER FUNCTION CLOSE_SVG@(UID) INTEGER UID
Description | Calling CLOSE_SVG@ stops graphics output to the SVG file whose user identifier is UID. The file can then be copied or displayed.
Notes | Added to FTN95 at version 8.05
Return value | Returns 1 on success or zero on failure.
See also | OPEN_SVG@


CLOSE_WAV_FILE@

Platform | Win32, x64
Purpose | To close a WAV file opened by OPEN_WAV_FILE_READ@ or OPEN_WAV_FILE_WRITE@
Syntax | SUBROUTINE CLOSE_WAV_FILE@(HANDLE) INTEGER(7) HANDLE
Description | This routine closes a WAV file opened for reading or writing. It is particularly important to call this routine to close a file open for writing before the program terminates.


COPY_FROM_CLIPBOARD@

Platform

Win32, x64

Purpose

To copy data from the clipboard.

Syntax

INTEGER FUNCTION COPY_FROM_CLIPBOARD@( BUFFER, NUM, TYPE )
CHARACTER(*) BUFFER
INTEGER NUM, TYPE

Description

Use this routine to copy anything from the clipboard. The following data types can exist in the clipboard, though not all are directly supported by ClearWin+:

CF_BITMAP | Bitmap data
CF_DIB | A BITMAPINFO structure followed by a bitmap
CF_DIF | Data interchange format
CF_DSPBITMAP | Private data stored in a bitmap format
CF_DSPMETAFILEPICT | Private data stored in metafile format
CF_DSPTEXT | Private data stored in text format
CF_METAFILEPICT | The data is in metafile format
CF_OEMTEXT | The data is in OEM text format
CF_OWNERDISPLAY | The data is a private format
CF_PALETTE | A palette
CF_RIFF | Resource interchange format
CF_SYLK | Microsoft symbolic link format
CF_TEXT | Text format
CF_TIFF | Tag image file format
CF_WAVE | Wave format

The BUFFER will contain NUM bytes copied from the clipboard. To determine the length of CF_TEXT or CF_OEMTEXT the routine SIZEOF_CLIPBOARD_TEXT@ can be called. On 64-bit systems more than 2GB of data canvas can be copied from the clipboard using COPY_FROM_CLIPBOARD64@.

Return value

Returns 1 for success or zero for failure.

See also

 COPY_TO_CLIPBOARD@,
COPY_TO_CLIPBOARD64@,
COPY_FROM_CLIPBOARD64@,
CLIPBOARD_TO_SCREEN_BLOCK@,
GRAPHICS_TO_CLIPBOARD@,
SIZEOF_CLIPBOARD_TEXT@,
SIZEOF_CLIPBOARD_TEXT64@

Example

INTEGER addr,len,i
CHARACTER buffer*1024
len=sizeof_clipboard_text@()
IF(len.GT.0)THEN
CALL get_storage@(addr,len)
IF(addr.GT.0)THEN
i=copy_from_clipboard@(addr,len, CF_TEXT)
CALL move@(buffer,CCORE1(addr),len)
ENDIF
ENDIF


COPY_FROM_CLIPBOARD64@

Platform

x64

Purpose

To copy large data from the clipboard.

Syntax

INTEGER FUNCTION COPY_FROM_CLIPBOARD64@( BUFFER, NUM, TYPE )
CHARACTER(*) BUFFER
INTEGER*8 NUM
INTEGER TYPE

Description

Use this routine to copy anything from the clipboard. The following data types can exist in the clipboard, though not all are directly supported by ClearWin+:

CF_BITMAP | Bitmap data
CF_DIB | A BITMAPINFO structure followed by a bitmap
CF_DIF | Data interchange format
CF_DSPBITMAP | Private data stored in a bitmap format
CF_DSPMETAFILEPICT | Private data stored in metafile format
CF_DSPTEXT | Private data stored in text format
CF_METAFILEPICT | The data is in metafile format
CF_OEMTEXT | The data is in OEM text format
CF_OWNERDISPLAY | The data is a private format
CF_PALETTE | A palette
CF_RIFF | Resource interchange format
CF_SYLK | Microsoft symbolic link format
CF_TEXT | Text format
CF_TIFF | Tag image file format
CF_WAVE | Wave format

The BUFFER will contain NUM bytes copied from the clipboard. To determine the length of CF_TEXT or CF_OEMTEXT the routine SIZEOF_CLIPBOARD_TEXT64@ can be called.

Return value

Returns 1 for success or zero for failure.

Notes

Added to FTN95 at version 8.10

See also

 COPY_TO_CLIPBOARD@,
COPY_TO_CLIPBOARD64@,
COPY_FROM_CLIPBOARD@,
CLIPBOARD_TO_SCREEN_BLOCK@,
GRAPHICS_TO_CLIPBOARD@,
SIZEOF_CLIPBOARD_TEXT@,
SIZEOF_CLIPBOARD_TEXT64@

Example

INTEGER*8 addr,len,i
CHARACTER buffer*1024
len=sizeof_clipboard_text64@()
IF(len.GT.0)THEN
CALL get_storage64@(addr,len)
IF(addr.GT.0)THEN
i=copy_from_clipboard64@(addr,len, CF_TEXT)
CALL move64@(buffer,CCORE1(addr),len)
ENDIF
ENDIF


COPY_GRAPHICS_REGION@

Platform

Win32, x64

Purpose

To copy screen blocks in drawing surfaces defined by %gr etc..

Syntax

INTEGER FUNCTION COPY_GRAPHICS_REGION@(
+ DEST_GR, DX, DY, DWIDTH, DHEIGHT,
+ SRC_GR, SX, SY, SWIDTH, SHEIGHT, COPY_MODE )
INTEGER DEST_GR, DX, DY, DWIDTH, DHEIGHT,
+ SRC_GR, SX, SY, SWIDTH, SHEIGHT, COPY_MODE

Description

You must have at least one drawing surface open (see for example %`gr in Graphics format). DEST_GR is the user identifier of the destination drawing surface and SRC_GR is the source drawing surface, however, the identifiers specified can be the same. If you set either or both to zero then the current drawing surface is assumed for the source and/or destination.

DX, DY, DWIDTH and DHEIGHT specify the destination rectangular region.

SX, SY, SWIDTH and SHEIGHT specify the source rectangular region.

If DWIDTH = SWIDTH and DHEIGHT = SHEIGHT then a normal copy will occur. If there are any differences then the image will be 'stretched' accordingly.

COPY_MODE defines the method of copying. Windows defines 255 different copy methods (ROPS). The most useful are described below:

Hex Value | Name | Logical Description
CC0020 | SRCCOPY | source (most common - a direct copy)
8800C6 | SRCAND | source and destination
660046 | SRCINVERT | source xor destination
440328 | SRCERASE | source and not destination
EE0086 | SRCPAINT | source or destination
330008 | NOTSRCCOPY | not source
1100A6 | NOTSRCERASE | not (source or destination)
BB0226 | MERGEPAINT | not source or destination
550009 | DSTINVERT | not destination
000042 | BLACK | 0
FF0062 | WHITE | 1

Return value

Returns 1 for success or zero for failure.

Notes

Under Win32 it is possible to stretch a drawing surface when copying from the screen to a printer but not every printer supports this mode.

See also

SCROLL_GRAPHICS@, SELECT_GRAPHICS_OBJECT@, CREATE_GRAPHICS_REGION@, NEW_GRAPHICS_REGION@, DELETE_GRAPHICS_REGION@


COPY_TO_CLIPBOARD@

Platform | Win32, x64
Purpose | To copy data to the clipboard.
Syntax | INTEGER FUNCTION COPY_TO_CLIPBOARD@( BUFFER, NUM, TYPE ) CHARACTER(*) BUFFER INTEGER NUM, TYPE
Description | NUM contents of BUFFER will be placed into the Windows clipboard and will be of the TYPE specified. For a list of the available data types see the COPY_FROM_CLIPBOARD@ function. On 64-bit systems more than 2GB of data canvas can be copied to the clipboard using COPY_TO_CLIPBOARD64@.
Return value | Returns 1 on success or zero on failure.
See also | COPY_TO_CLIPBOARD64@, COPY_FROM_CLIPBOARD@, COPY_FROM_CLIPBOARD64@, CLIPBOARD_TO_SCREEN_BLOCK@, GRAPHICS_TO_CLIPBOARD@, SIZEOF_CLIPBOARD_TEXT@, SIZEOF_CLIPBOARD_TEXT64@


COPY_TO_CLIPBOARD64@

Platform | x64
Purpose | To copy large data to the clipboard.
Syntax | INTEGER FUNCTION COPY_TO_CLIPBOARD64@( BUFFER, NUM, TYPE ) CHARACTER(*) BUFFER INTEGER*8 NUM INTEGER TYPE
Description | NUM contents of BUFFER will be placed into the Windows clipboard and will be of the TYPE specified. For a list of the available data types see the COPY_FROM_CLIPBOARD64@ function.
Return value | Returns 1 on success or zero on failure.
Notes | Added to FTN95 at version 8.10
See also | COPY_TO_CLIPBOARD@, COPY_FROM_CLIPBOARD@, COPY_FROM_CLIPBOARD64@, CLIPBOARD_TO_SCREEN_BLOCK@, GRAPHICS_TO_CLIPBOARD@, SIZEOF_CLIPBOARD_TEXT@ SIZEOF_CLIPBOARD_TEXT64@


CREATE_BITMAP@

Platform

Win32, x64

Purpose

To create a bitmap from bitmap data.

Syntax

INTEGER(7) FUNCTION CREATE_BITMAP@( PTR )
INTEGER(7) PTR

Description

Creates a bitmap from a pointer to data that is in the same format as a .BMP file. When the program is terminated the bitmap will be deleted. The function returns a handle that can be used with %`bm or in Windows API functions that require a HBITMAP handle.

Return value

Returns a handle to the new bitmap. A zero return indicates failure.

See also

MAKE_BITMAP@


CREATE_CURSOR@

Platform

Win32, x64

Purpose

To create a cursor from data in a .CUR file.

Syntax

INTEGER(7) FUNCTION CREATE_CURSOR@( PTR )
INTEGER(7) PTR

Description

Creates a cursor from a pointer to data that is in the same format as a .CUR file. When the program is terminated the cursor will be deleted. The function returns a handle that can be used, for example, with %`cu or in Windows API functions that require a HCURSOR handle.

Return value

Returns a handle to the new cursor. A zero return indicates failure.


CREATE_GRAPHICS_REGION@

Platform

Win32, x64

Purpose

To create an internal (off-screen) drawing surface.

Syntax

INTEGER FUNCTION CREATE_GRAPHICS_REGION@( UID,
+ WIDTH, HEIGHT )
INTEGER UID, WIDTH, HEIGHT

Description

This routine is used to create internal drawing surfaces. For example, it can be used to display part of a large bitmap. Areas of the buffer can be copied into a %gr region (for example) using COPY_GRAPHICS_REGION@. If you make extensive use of this function it is recommended that you delete unwanted surfaces with a call to DELETE_GRAPHICS_REGION@.

UID is an input value, chosen by the programmer, that must be unique. It is used to identify the surface in calls to related functions. WIDTH, HEIGHT specify the size in pixels of the region.

The colour mode for the surface will be determined by the default colour mode or by the colour mode of the current %gr drawing surface.

The function NEW_GRAPHICS_REGION@ can be used instead if you want to specify the initial colour

Return value

Returns 1 for success, otherwise zero.

See also

DELETE_GRAPHICS_REGION@, COPY_GRAPHICS_REGION@, SCROLL_GRAPHICS@, NEW_GRAPHICS_REGION@


CREATE_WINDOW@

Platform | Win32, x64
Purpose | To create and display a ClearWin window.
Syntax | INTEGER(7) FUNCTION CREATE_WINDOW@(TITLE,X,Y,XW,YW) INTEGER X,Y,XW,YW CHARACTER(*) TITLE
Description | Creates a window of width XW, height YW and title TITLE at position (X,Y). Do not confuse this function with the similarly named routine in the Windows API called CreateWindow.
Return value | Returns a standard Windows handle.


DEFINE_FILE_EXTENSION@

Platform

Win32, x64

Purpose

Allows application file extension registration.

Syntax

SUBROUTINE DEFINE_FILE_EXTENSION@(EXTNAME, PATH,
+ DESCR, ICON_IDX, NEW_OPTION )
CHARACTER*129 NAME, PATH, DESCRIPTION
INTEGER ICON_INDEX, NEW_OPTION

Description

It is possible to register an application with the system so that if a data file is opened via Explorer your application will be called to process it.

The EXTNAME variable is a string that contains the extension, the PATH must contain the full path and program name. A text description should be supplied in DESCRIPTION. The ICON_INDEX selects the icon to be used by Windows. If you specify -1 no icon is used otherwise the relevant icon is used. i.e. if you have four icons in your resource, by placing a value of 2 in ICON_INDEX the second icon resource will be used. NEW_OPTION option should be set to a non zero value to activate the file type addition.

For example:

CHARACTER*129 pname
CALL get_program_name@(pname)
k=define_file_extension@('.ICO',pname,
+ 'Icon file editor',0,1)

You can obtain the file name passed to your program as if you were examining the arguments on the command line.

For example:

...
CHARACTER*129 cmnam@,filetoopen
filetoopen=cmnam@()
...

GET_PROGRAM_NAME@ and CMNAM@ are Silverfrost library functions.


DELETE_GRAPHICS_REGION@

Platform | Win32, x64
Purpose | To remove an internal drawing surface.
Syntax | INTEGER FUNCTION DELETE_GRAPHICS_REGION@( UID ) INTEGER UID
Description | This routine will remove from memory a drawing surface that has previously been defined by CREATE_GRAPHICS_REGION@ or NEW_GRAPHICS_REGION@. UID is the value input in an earlier call to the functions.
Return value | Returns 1 for success, otherwise zero.
See also | CREATE_GRAPHICS_REGION@, COPY_GRAPHICS_REGION@, SCROLL_GRAPHICS@


DESTROY_WINDOW@

Platform | Win32, x64
Purpose | To close and destroy a displayed ClearWin window.
Syntax | SUBROUTINE DESTROY_WINDOW@(HWND) INTEGER(7) HWND
Description | Destroys a window specified by HWND and any child windows that may be owned by it. Fonts owned by the window are not destroyed. HWND is the window handle returned by CREATE_WINDOW@.


DIB_PAINT@

Platform

Win32, x64

Purpose

To display a device independent bitmap (DIB).

Syntax

INTEGER FUNCTION DIB_PAINT@( HORIZ, VERT, HDIB,
+ FUNCTION, MODE )
INTEGER HORIZ, VERT, FUNCTION, MODE
INTEGER(7) HDIB

Description

Displays the DIB with handle HDIB on the current device with HORIZ and VERT relative displacement (they may be negative). FUNCTION selects the type of logical restore operation with respect to the previous screen :

0 | REPLACE former pixel
1 | AND with former pixel
2 | OR with former pixel
3 | XOR with former pixel

MODE specifies if

0 | the dib palette should be used,
1 | the current palette should be used and the image not dithered,
2 | dithering should be used.

Before you can call this function the DIB must first be loaded using GET_SCREEN_BLOCK@, IMPORT_BMP@, IMPORT_PCX@, or CLIPBOARD_TO_SCREEN_BLOCK@.

Return value

Returns 1 the function is successful otherwise zero.


DIB_PRINT@

Platform

Win32, x64

Purpose

To print a device independent bitmap.

Syntax

INTEGER FUNCTION DIB_PRINT@(HDIB, PR_X, PR_Y, PR_WIDTH,
+ PR_HEIGHT)
INTEGER(7) HDIB
INTEGER PR_X, PR_Y, PR_WIDTH, PR_HEIGHT

Description

This function replaces PRINT_DIB@.

HDIB is the handle of a DIB created using GET_SCREEN_DIB@. Calling this routine allows you to set the bitmap source dimensions. PR_X, PR_Y, PR_WIDTH, and PR_HEIGHT are dimensions for the printer page.

You must call GET_SCREEN_DIB@ before opening the printer (with OPEN_PRINTER@). Then call DIB_PRINT@ after opening the printer.

Setting PR_X=-1, causes the output to be centred horizontally on the page.
Setting PR_Y=-1, causes the output to be centred vertically on the page.
Setting PR_WIDTH=-1, causes the output to be scaled horizontally in proportion to the screen and printer page width.
Setting PR_HEIGHT=-1, causes the output to be scaled vertically in proportion to the screen and printer page height.

Return value

Returns 1 for success or zero for failure.

See also

PRINT_DIB@, DIB_PAINT@, RELEASE_SCREEN_DIB@, EXPORT_BMP@


DISPLAY_DIB_BLOCK@

Platform | Win32, x64
Purpose | To display a device independent bitmap.
Syntax | SUBROUTINE DISPLAY_DIB_BLOCK@( X,Y,PARRAY,AW,AH,AX,AY,W,H, + FUNCTION,MODE,ERCODE ) CHARACTER PARRAY(3,AW,AH) INTEGER X,Y,AW,AH,AX,AY,W,H,FUNCTION,MODE,ERCODE
Description | All of the arguments are input values except for ERCODE which returns the error status. This routine transfers a rectangular block of size W ❌ H from the array PARRAY at position (AX, AY) to the position (X, Y) on the current graphics device (e.g. a %gr window or a printer). FUNCTION and MODE are the same as in DIB_PAINT@ and will normally be set to zero. The variable ERCODE is returned as zero if the process is successful.
See also | GET_IM_INFO@, GET_DIB_SIZE@, GET_DIB_BLOCK@, PUT_DIB_BLOCK@, DIB_PRINT@, PROGRESS_BAR@
Example | See Drawing device independent bitmaps.


DISPLAY_POPUP_MENU@

Platform | Win32, x64
Purpose | To activate a popup menu defined using %pm.
Syntax | SUBROUTINE DISPLAY_POPUP_MENU@( )
Description | This subroutine will activate a pre-defined popup menu. It can be used when the right mouse button is pressed over a %gr drawing surface that has FULL_MOUSE_INPUT activated (see Graphics format).


DO_COMMAND@

Platform | Win32, x64
Purpose | To execute the callback previously associated by %rc.
Syntax | SUBROUTINE DO_COMMAND@(CMD_ID) INTEGER CMD_ID
Description | Runs the callback associated with the identifier 'CMD_ID'. The identifiers are defined using the %rc format code. Callbacks run using DO_COMMAND will have the callback reason 'DO_COMMAND'.
Notes | Introduced with FTN95 8.40.
See also | Callback reasons


DO_COPIES@

Platform

Win32, x64

Purpose

To produce multiple printer copies of a graphics image using metafiles.

Syntax

INTEGER DO_COPIES@( UID, NUM )
INTEGER UID, NUM

Description

Sends NUM copies to the printer. A metafile must have been created with a call to OPEN_METAFILE@ and also closed by CLOSE_METAFILE@ before DO_COPIES@ can be used.

The call to CLOSE_PRINTER@ will automatically send the number of copies the user has selected to the printer. The CLEARWIN_INFO@ parameter PRINTER_COPIES will return this number.

See also

OPEN_PRINTER@, CLOSE_PRINTER@

Example

See Using a metafile to print multiple copies.


DOWNLOAD@

Platform

Win32, x64

Purpose

To to read the contents of a URL into memory.

Syntax

INTEGER(7) FUNCTION DOWNLOAD@(URL, FILESIZE, ERROR)
CHARACTER(*) URL
INTEGER FILESIZE, ERROR

Description

The function returns the INTEGER address of the downloaded file stored in memory. The memory can be released by a call to RETURN_STORAGE@.

FILESIZE is the size of the file that is to be downloaded. If this value is zero then the function returns zero and the size of the file is the returned as the new value of FILESIZE. The returned error code ERROR is zero for success. An error code value of 1 (one) indicates that FILESIZE was too small so that only part of the file was stored. Error code values greater than 1 (one) indicate total failure with the function returning a zero address.

The returned address can be used to access the file by using FTN95 intrinsics such as CCORE1(addr).

See also

READ_URL@ and download options, Linking to the web

Example

INCLUDE <clearwin.ins>
INTEGER err,fileSize
INTEGER(7)handle
CHARACTER(80) url
url = "http://..."
err = 0
fileSize = 0
handle = DOWNLOAD@(url, fileSize, err)
IF(err > 0) STOP 'Download failed'
fileSize = fileSize + 4
handle = DOWNLOAD@(url, fileSize, err)
!Display the first 20 characters in the download...
DO i=0,20
PRINT*, CCORE1(handle+i)
ENDDO
CALL RETURN_STORAGE@(handle)
. . .


DRAW_BEZIER@

Platform

Win32, x64

Purpose

To draw a Bézier spline on the current drawing surface

Syntax

SUBROUTINE DRAW_BEZIER@( X, Y, N, COLOUR )
INTEGER X(N),Y(N),N,COLOUR

Description

X and Y are arrays giving the co-ordinates of the N points and COLOUR is the colour value using the current colour mode.

N must be a multiple of 4 because Bézier curves are formed from segments defined by 4 points where the first and last points are the points to be joined and the second and third points are control points.

There is also a DRAW_BEZIERSD@ routine which is identical to DRAW_BEZIER@ except that the X and Y arrays are DOUBLE PRECISION:

SUBROUTINE DRAW_BEZIERSD@(X,Y,N,ICOL)
DOUBLE PRECISION X(N),Y(N)
INTEGER N,ICOL

See also:

DRAW_FILLED_BEZIERSD@


DRAW_CHARACTERS@

Platform

Win32, x64

Purpose

To draw text on the current drawing surface.

Syntax

SUBROUTINE DRAW_CHARACTERS@(STR,IH,IV,ICOL)
CHARACTER(*) STR
INTEGER IH,IV,ICOL

Description

DRAW_CHARACTERS@ draws text, using the current font and attributes, at the point (IH, IV). These co-ordinates represent the bottom left-hand corner of the first character. STR contains the character string to be drawn. The text is positioned to the nearest pixel. ICOL provides the colour for the text that appears on the existing background using the current colour mode.

It is recommended that a call be made to SELECT_FONT@ be made before calling DRAW_CHARACTERS@.

DRAW_CHARACTERS@ can be used in GDI+ mode but the display may not match that produced by the GDI. When porting from GDI to GDI+ and a match is important, users might consider mixed GDI/GDI+ drawing (GDI for characters, GDI+ for lines) provided no use is made of metafiles.

When using the GDI, the height and width of characters can be set independently (using SIZE_IN_PIXELS@ etc.). In contrast, when using the GDI+, only the height can be transmitted and a specified width is ignored. The result is that the GDI/GDI+ heights will match but the string widths may not (the design decision within ClearWin+ is that to match the heights is paramount). When it is expedient to use GDI+ for drawing characters and the when it is important to match the string width rather than the character height, ClearWin+ provides a function called GET_TEXT_HEIGHT@ that provides the adjusted height of a given string such that its GDI+ width matches its GDI width.

See also

Using GDI+, SELECT_FONT@, SCALE_FONT@, UNDERLINE_FONT@, ITALIC_FONT@,
BOLD_FONT@, SIZE_IN_PIXELS@, SIZE_IN_POINTS@, ROTATE_FONT@,
GET_FONT_NAME@, CHOOSE_FONT@.


DRAW_ELLIPSE@

Platform | Win32, x64
Purpose | To draw an ellipse on the current drawing surface.
Syntax | SUBROUTINE DRAW_ELLIPSE@(IXC,IYC,IA,IB,ICOL) INTEGER IXC,IYC,IA,IB,ICOL
Description | DRAW_ELLIPSE@ draws an ellipse with centre at (IXC, IYC), with horizontal semi-axis IA, vertical semi-axis IB and colour ICOL using the current colour mode. This routine can be used to produce a circle on the drawing surface if the axes are scaled appropriately.
See also | Using GDI+, DRAW_FILLED_ELLIPSE@


DRAW_FILLED_BEZIERSD@

Platform | Win32, x64
Purpose | To draw a filled Bézier spline on the current drawing surface
Syntax | SUBROUTINE DRAW_FILLED_BEZIERSD@( X, Y, N, COLOUR ) DOUBLE PRECISION X(N),Y(N) INTEGER N,COLOUR
Description | X and Y are arrays giving the co-ordinates of the N points and COLOUR is the colour value using the current colour mode. N must be a multiple of 4 because Bézier curves are formed from segments defined by 4 points where the first and last points are the points to be joined and the second and third points are control points.
See also: | DRAW_BEZIER@


DRAW_FILLED_ELLIPSE@

Platform | Win32, x64
Purpose | To fill an ellipse on the current drawing surface.
Syntax | SUBROUTINE DRAW_FILLED_ELLIPSE@(IXC,IYC,IA,IB,ICOL) INTEGER IXC,IYC,IA,IB,ICOL
Description | DRAW_FILLED_ELLIPSE@ fills an ellipse with centre at (IXC, IYC), with horizontal semi-axis IA, vertical semi-axis IB and colour ICOL using the current colour mode. This routine can be used to fill a circle if the axes are scaled appropriately.
See also | Using GDI+, DRAW_ELLIPSE@


DRAW_FILLED_POLYGON@

Platform | Win32, x64
Purpose | To fill a polygon on the current drawing surface.
Syntax | SUBROUTINE DRAW_FILLED_POLYGON@(IX,IY,N,ICOL) INTEGER IX(N),IY(N) INTEGER N,ICOL
Description | DRAW_FILLED_POLYGON@ draws a straight line from (IX(1), IY(1)) to (IX(2), IY(2)), and continues until (IX(N), IY(N)) and fills the enclosed region. ICOL specifies the fill colour value using the current colour mode.
See also | Using GDI+, DRAW_POLYLINE@


DRAW_FILLED_RECTANGLE@

Platform | Win32, x64
Purpose | To fill a rectangle on the current drawing surface.
Syntax | SUBROUTINE DRAW_FILLED_RECTANGLE@(IX1,IY1,IX2,IY2,ICOL) INTEGER IX1,IY1,IX2,IY2,ICOL
Description | DRAW_FILLED_RECTANGLE@ fills a rectangle in colour ICOL using the current colour mode. (IX1, IY1) and (IX2,IY2) are opposite corners.
See also | Using GDI+, DRAW_RECTANGLE@


DRAW_LINE_BETWEEN@

Platform

Win32, x64

Purpose

To draw a straight line on the current drawing surface.

Syntax

SUBROUTINE DRAW_LINE_BETWEEN@(IX1,IY1,IX2,IY2,ICOL)
INTEGER IX1,IY1,IX2,IY2,ICOL

Description

DRAW_LINE_BETWEEN@ draws a line with colour value ICOL (using the current colour mode) from (IX1, IY1) to (IX2, IY2). The coordinates are pixel numbers relative to the top left of the drawing surface. When not in GDI+ mode and the line width is one, a pixel is is drawn at the end point of the line. This is not the case in GDI+ mode

The library also contains a REAL*8 version of this routine which is especially useful when drawing SVG files.

SUBROUTINE DRAW_LINE_BETWEEND@(RX1,RY1,RX2,RY2,ICOL)
REAL*8 RX1,RY1,RX2,RY2
INTEGER ICOL

See also

Using GDI+, DRAW_POLYLINE@, DRAW_POINT@


DRAW_POINT@

Platform | Win32, x64
Purpose | To set a single pixel colour on the current drawing surface.
Syntax | SUBROUTINE DRAW_POINT@(IH,IV,ICOL) INTEGER IH,IV,ICOL
Description | DRAW_POINT@ sets the pixel at (IH,IV) on the current drawing surface to colour value ICOL using the current colour mode.
See also | GET_POINT@, GET_RGB_VALUE@


DRAW_POLYLINE@

Platform | Win32, x64
Purpose | To draw a number of connected straight lines on the current drawing surface.
Syntax | SUBROUTINE DRAW_POLYLINE@(IX,IY,N,ICOL) INTEGER IX(N),IY(N) INTEGER N,ICOL
Description | DRAW_POLYLINE@ draws a straight line from (IX(1), IY(1)) to (IX(2), IY(2)), and continues until (IX(N), IY(N)). That is, it joins N points with straight lines. ICOL specifies the colour value using the current colour mode. For a closed polygon, simply set the last pair of coordinates equal to the first pair.
See also | Using GDI+, DRAW_LINE_BETWEEN@, DRAW_FILLED_POLYGON@


DRAW_RECTANGLE@

Platform | Win32, x64
Purpose | To draw a rectangle on the current drawing surface.
Syntax | SUBROUTINE DRAW_RECTANGLE@(IX1,IY1,IX2,IY2,ICOL) INTEGER IX1,IY1,IX2,IY2,ICOL
Description | DRAW_RECTANGLE@ draws a rectangle in colour ICOL using the current colour mode. (IX1, IY1) and (IX2, IY2) are opposite corners.
See also | Using GDI+, DRAW_FILLED_RECTANGLE@


EXPORT_BMP@

Platform | Win32, x64
Purpose | To exports a device independent bitmap to a .BMP file.
Syntax | SUBROUTINE EXPORT_BMP@( HDIB, FILENAME, ERROR ) INTEGER(7) HDIB CHARACTER(*) FILENAME INTEGER ERROR
Description | Writes a DIB to a bitmap file specified by FILENAME. HDIB is a handle returned for example by GET_SCREEN_DIB@, CLIPBOARD_TO_SCREEN_BLOCK@ or IMPORT_BMP@. ERROR returns one of the following:
0 | success
1 | unable to open file
3 | unable to write to file

See also

IMPORT_BMP@, WRITE_GRAPHICS_TO_BMP@, DIB_PAINT@, DRAW_FILLED_POLYGON@, EXPORT_GIF@, EXPORT_PCX@


EXPORT_IMAGE@

Platform

Win32, x64

Purpose

To export a (%gr) drawing surface to an image file.

Syntax

INTEGER FUNCTION EXPORT_IMAGE@( FILENAME )
CHARACTER(*) FILENAME

Description

FILENAME is the name of a file. The file name extension determines the type of image file to be created and must be one of: .png, .jpg, .jpeg, .bmp, .gif, .emf, and .pcx.

Return value

The function returns a non-zero value when successful.

Notes

An active metafile is needed in order to export an EMF image. Other formats do not require a metafile. Metafiles are created by using %gr[metafile_resize] or by calling OPEN_METAFILE@.

The quality of a JPEG image exported by EXPORT_IMAGE@ can be changed by calling the function SET_JPEG_QUALITY@ as follows:

REAL(KIND=2) FUNCTION SET_JPEG_QUALITY@( Q )
REAL(KIND=2) Q

Q is an input value in the range from 0.01D0 to 1.0D0 (use steps of 0.01). The function returns the old value should you wish to restore it afterwards. The default value of Q is 0.75D0.

See also

IMPORT_IMAGE@


EXPORT_GIF@

Platform | Win32, x64
Purpose | To exports a device independent bitmap (DIB) to a .GIF file.
Syntax | SUBROUTINE EXPORT_GIF@( HDIB, FILENAME, ERROR ) INTEGER(7) HDIB CHARACTER(*) FILENAME INTEGER ERROR
Description | Writes a DIB to a gif file specified by FILENAME. HDIB is a handle returned for example by GET_SCREEN_DIB@, CLIPBOARD_TO_SCREEN_BLOCK@ or IMPORT_GIF@. ERROR returns one of the following:

0 | success
1 | unable to open file
3 | unable to write to file

See also

IMPORT_GIF@, DIB_PAINT@, EXPORT_BMP@, EXPORT_PCX@


EXPORT_PCX@

Platform | Win32, x64
Purpose | To export a device independent bitmap to a .PCX file.
Syntax | SUBROUTINE EXPORT_PCX@( HDIB, FILENAME, ERROR ) INTEGER(7) HDIB CHARACTER(*) FILENAME INTEGER ERROR
Description | Writes a DIB to a PCX file specified by FILENAME. HDIB is a handle returned for example by GET_SCREEN_DIB@, CLIPBOARD_TO_SCREEN_BLOCK@ or IMPORT_PCX@. ERROR returns one of the following:
0 | success
1 | unable to open file
3 | unable to write to file

See also

IMPORT_PCX@, WRITE_GRAPHICS_TO_PCX@, DIB_PAINT@, DIB_PRINT@, EXPORT_GIF@, EXPORT_BMP@


FEED_WKEYBOARD@

Platform | Win32, x64
Purpose | To insert a key into a ClearWin window keyboard buffer.
Syntax | SUBROUTINE FEED_WKEYBOARD@(KEY,ERROR) INTEGER KEY,ERROR
Description | This routine is only for use in a ClearWin window (e.g. with %cw). KEY is the ASCII code for the key to be inserted. Currently ERROR always returns zero for success.
See also | FLUSH_WKEYBOARD@, GET_WKEY@, GET_WKEY1@, WKEY_WAITING@


FILL_SURFACE@

Platform | Win32, x64
Purpose | To fill an area of the current drawing surface with a given colour.
Syntax | SUBROUTINE FILL_SURFACE@( XSTART, YSTART, SURF_COL + FILL_COL ) INTEGER XSTART, YSTART, SURF_COL, FILL_COL
Description | XSTART, YSTART are the co-ordinates of the focus, FILL_COL is the colour to fill with and SURF_COL is the current colour of the region to fill. The colour values relate to the current colour mode.
See also | FILL_TO_BORDER@


FILL_TO_BORDER@

Platform | Win32, x64
Purpose | To fill an area of the current drawing surface with a given colour.
Syntax | SUBROUTINE FILL_TO_BORDER@( XSTART, YSTART, FILL_COL + STOP_COL ) INTEGER XSTART, YSTART, FILL_COL, STOP_COL
Description | XSTART, YSTART are the co-ordinates of the focus, FILL_COL is the colour to fill with and STOP_COL is the colour of the closed boundary of the area to fill. The colour values relate to the current colour mode
See also | FILL_SURFACE@


FIND_FILE@

Platform

Win32, x64

Purpose

To search for a specified file.

Syntax

INTEGER FUNCTION FIND_FILE@ (DIRECTORY, FILENAME, CALLBACK)
CHARACTER(*) DIRECTORY, FILENAME
EXTERNAL CALLBACK

Description

This function searches within the given DIRECTORY and its subdirectories for the specified FILENAME, calling the function CALLBACK for each occurrence found. CALLBACK is a function that you provide. It takes no arguments and returns an integer value.

The callback function is called when the search enters a new subdirectory, and when a matching file has been found. CLEARWIN_STRING@('FIND_FILE_CALLBACK_REASON') is used to distinguish between these cases returning either 'FILE_FOUND' or 'CHECKING_DIRECTORY'.

Subsequently CLEARWIN_STRING@('FILE_FOUND') returns the file name if a file has been found whilst CLEARWIN_STRING@('CHECKING_DIRECTORY') returns the full name of a directory if the search enters a new subdirectory.

The callback function should return 1 to stop the search or 0 to continue. If the search is stopped, FIND_FILE@ returns 1 whilst if it completed successfully it returns zero.

The directory and filename strings must not exceed 260 characters.

Follow the link to find some sample code.


FLUSH_WKEYBOARD@

Platform | Win32, x64
Purpose | To empty a ClearWin window keyboard buffer.
Syntax | SUBROUTINE FLUSH_WKEYBOARD@( )
Description | This routine is only for use in a ClearWin window (e.g. with %cw).
See also | FEED_WKEYBOARD@, GET_WKEY@, GET_WKEY1@, WKEY_WAITING@


FONT_METRICS@

Platform | Win32, x64
Purpose | To get the font system metrics for the default font and the current drawing surface.
Syntax | SUBROUTINE FONT_METRICS@( METRICS ) INTEGER METRICS(20)
Description | The array is returned with values for the following 20 font system metrics: Height, Ascent, Descent, InternalLeading, ExternalLeading, AveCharWidth, MaxCharWidth, Weight, Overhang, DigitizedAspectX, DigitizedAspectY, FirstChar, LastChar, DefaultChar, BreakChar, Italic, Underlined, StruckOut, PitchAndFamily, CharSet.


FREEZE_WINDOW_CONTENTS@

Platform

Win32, x64

Purpose

To temporarily freeze the display of a window whilst multiple changes are made to its appearance.

Syntax

SUBROUTINE FREEZE_WINDOW_CONTENTS@( HWND )
INTEGER(7) HWND

Description

HWND is the handle of the window obtained using %hw.

Sometimes it is useful to freeze the visible contents of a window whilst a number of changes are made. This is particularly true when the window contains a frame with child sub-windows. By freezing a window, performing a sequence of changes, and unfreezing the window, the contents of the window will appear to change only once.

This routine covers the window in question with another window containing a copy of the contents of initial window. Therefore it is important that the window is not moved whilst frozen and it should only be frozen for a very short period of time.

See also

UNFREEZE_WINDOW_CONTENTS@


GET_BITMAP_DC@

Platform

Win32, x64

Purpose

To obtain the device context of a bitmap which may be written to using the Windows API graphics functions and used in a %dw format.

Syntax

INTEGER(7) FUNCTION GET_BITMAP_DC@( H_BITS, V_BITS )
INTEGER H_BITS,V_BITS

Description

The bitmap is created of size H_BITS × V_BITS pixels. The device context can be destroyed by RELEASE_BITMAP_DC@, but will be returned to the system at normal program termination.

RELEASE_BITMAP_DC@ should be used when multiple bitmaps are created and when they need not be saved.

Return value

The function returns a handle to the device context.

See also

CLEAR_BITMAP@, RELEASE_BITMAP_DC@, %dw


GET_CLEARWIN_TEXT@

Platform | Win32, x64
Purpose | To get text from a ClearWin window.
Syntax | INTEGER FUNCTION GET_CLEARWIN_TEXT@(HWD,BUFFER,COPY) INTEGER(7) HWD INTEGER COPY CHARACTER(*) BUFFER
Description | HWD is the handle of ClearWin window in question. To obtain the handle of the default window use: HWD=GET_DEFAULT_WINDOW@( )
Return value | If COPY is zero, the function returns the length of the required buffer but no data is copied. If COPY is 1, the data is also copied to the buffer.


GET_CURRENT_DC@

Platform | Win32, x64
Purpose | To get the device context of the current drawing surface.
Syntax | SUBROUTINE GET_CURRENT_DC@( DC ) INTEGER(7) DC
See also | SELECT_GRAPHICS_OBJECT@, SET_UPDATE_RECTANGLE@


GET_CURRENT_GRAPHICS_REGION@

Platform | Win32, x64
Purpose | To obtain a HANDLE to the current drawing surface.
Syntax | INTEGER(7) FUNCTION GET_CURRENT_GRAPHICS_REGION@()
Description | Returns the Windows handle of the current drawing surface. When usig multiple surfaces this handle can be used with SELECT_GRAPHICS_REGION@ to switch drawing to a different surface.
Return value | The function returns a handle to the drawing surface.


GET_DEFAULT_WINDOW@

Platform | Win32, x64
Purpose | To return the handle of the current default ClearWin window for standard Fortran I/O.
Syntax | INTEGER(7) FUNCTION GET_DEFAULT_WINDOW@()


GET_DIB_BLOCK@

Platform

Win32, x64

Purpose

To read a BMP or JPEG format file into a character array.

Syntax

SUBROUTINE GET_DIB_BLOCK@( FILENAME, PARRAY, AW, AH, ADX,
+ ADY, W, H, DX, DY, ERCODE )
CHARACTER(*) FILENAME
CHARACTER PARRAY(3,AW,AH)
INTEGER AW,AH,ADX,ADY,W,H,DX,DY,ERCODE

Description

All of the arguments are input values except for PARRAY which contains the returned data and ERCODE which returns the error status.

FILENAME is the name of the BMP file.

AW and AH are dimensions of PARRAY.

ADX and ADY are offsets used when writing the data to PARRAY.

W and H are the width and height of the image data to be copied.

DX and DY are offsets used when reading the data from the file.

The first dimension of PARRAY is used to store the red, green and blue values for each pixel. ERCODE will return:

0 | SUCCESS
2 | READ ERROR
4 | MEMORY ERROR
5 | NOT A BMP FILE
10 | BAD FILE
13 | BAD NUMBER
16 | OTHER ERROR

 | For JPEG data the file name must have a .jpg or .jpeg extension. A wider range of files can be loaded after a call to USE_GDIPLUS_IMAGE_FILES@.
See also | GET_DIB_SIZE@, PUT_DIB_BLOCK@, DIB_PAINT@
Example | See Drawing device independent bitmaps.


GET_DIB_SIZE@

Platform | Win32, x64
Purpose | To get information from a BMP or JPEG data file.
Syntax | SUBROUTINE GET_DIB_SIZE@( FILENAME, WIDTH, HEIGHT, NBBP, + ERCODE ) CHARACTER(*) FILENAME INTEGER WIDTH, HEIGHT, NBBP, ERCODE
Description | This routine is similar to GET_IM_INFO@ but returns the number of bits per pixel NBBP as follows:

NBBP | Number of colours
1 | 2
4 | 16
8 | 256
24 | 16MB

 | For JPEG data the file name must have a .jpg or .jpeg extension.
See also | GET_DIB_BLOCK@, PUT_DIB_BLOCK@, DIB_PAINT@, USE_GDIPLUS_IMAGE_FILES@
Example | See Drawing device independent bitmaps.


GET_DISPLAY_BITS@

Platform

Win32, x64

Purpose

To get the number of screen colours.

Syntax

INTEGER FUNCTION GET_DISPLAY_BITS@()

Return value

GET_DISPLAY_BITS@ returns one of the following values:

4 | 16 colours
8 | 256 colours
16 | High colour 16-bit
24 | True colour 24-bit
32 | True colour 32-bit

Notes

The number of colours for 32-bit True colour is too large for a signed 32-bit integer INTEGER(3).


GET_FILTERED_FILE@

Platform

Win32, x64

Purpose

To access the standard 'open' dialog box.

Syntax

SUBROUTINE GET_FILTERED_FILE@(TITLE, FILE, PATH,
+ FILTERNAMES, FILTERSPECS, NFILTERS, MUSTEXIST )
CHARACTER(*) TITLE, FILE, PATH, FILTERNAMES, FILTERSPECS
INTEGER NFILTERS, MUSTEXIST

Description

This function can be used instead of %fs and %ft in cases where the filters need to be set dynamically. The arguments are as follows:

TITLE: | The caption for the dialog box.
FILE: | The full path returned by the dialog box.
PATH: | The input path.
FILTERNAMES: | An array of strings for the description of file filters.
FILTERSPECS: | An array of strings for the corresponding filters.
NFILTERS | The number of file filters.
MUSTEXIST: | An input value that is set to 1 if the file to be selected must already exist.

Notes

After this routine has been called, CLEARWIN_INFO@('FILTER_ITEM_SELECTED') provides the index of the file filter that was selected by the user. This can be called, for example, to detect if the file was saved using a different file extension.

Previously 64 bit ClearWin+ used an indirect call to the Windows API whilst 32 bit ClearWin+ used a direct call. Now both 64 bit and 32 bit ClearWin+ use a direct call by default whilst the indirect method is available as an option. The alternative is a little slower but might generally prove to be safer. Make a prior call:

CALL CLEARWIN_OPTION@("alt_open_save")

in order to activate the indirect alternative. The opposite is:

CALL CLEARWIN_OPTION@("-alt_open_save")

See also

GET_MULTIPLE_FILENAMES@

Example

WINAPP
INTEGER i,winio@,open_func
EXTERNAL open_func
i=winio@('%ca[Image info]&')
i=winio@('%mn[&File[&Open,E&xit]]',open_func,'EXIT')
END
c------------------------------------------------------------
INTEGER FUNCTION open_func()
INCLUDE <windows.ins>
CHARACTER file*129,format*12,title*20,path*129
INTEGER NFILTERS
PARAMETER(NFILTERS=2)
CHARACTER*20 filtname(NFILTERS),filtspec(NFILTERS)
title='Open Bitmap File'
file=' '
path='c:\windows'
filtname(1)='Bitmap files'
filtspec(1)='*.bmp'
filtname(2)='All files'
filtspec(2)='*.*'
CALL get_filtered_file@(title,file,path,filtname,filtspec,
+ NFILTERS,1)
. . . .
open_func=1
END


GET_FONT_ID@

Platform | Win32, x64
Purpose | To get the current font identifier.
Syntax | SUBROUTINE GET_FONT_ID@( ID ) INTEGER(7) ID
Description | ID is returned as the identifier of the font for the current drawing surface.
See also | CHOOSE_FONT@, SELECT_FONT_ID@


GET_FONT_NAME@

Platform | Win32, x64
Purpose | To return the name of the loaded font.
Syntax | SUBROUTINE GET_FONT_NAME@( NAME, NUM ) CHARACTER(*) NAME INTEGER NUM
Description | The name of an installed font is returned in the NAME parameter. NUM references the installed fonts and should start at 1. If a call is made and there is no associated font to the number supplied an empty string will be returned.
Example | INCLUDE <windows.ins> CHARACTER*20 name DO k=1,3000 CALL get_font_name@(name,k) IF(name.EQ.' ')STOP PRINT *,name ENDDO END


GET_GRAPHICAL_RESOLUTION@

Platform | Win32, x64
Purpose | To determine the width and height of the current drawing surface.
Syntax | SUBROUTINE GET_GRAPHICAL_RESOLUTION@( WIDTH, HEIGHT ) INTEGER WIDTH, HEIGHT
Description | WIDTH and HEIGHT are set to the values for the current drawing surface.


GET_GRAPHICS_SELECTED_AREA@

Platform | Win32, x64
Purpose | To get the current %gr 'rubber-band' selection.
Syntax | SUBROUTINE GET_GRAPHICS_SELECTED_AREA@(X1,Y1,X2,Y2) INTEGER X1, Y1, X2, Y2
Description | The four parameters are set to the values of the current graphics selection which is defined by the 'rubber-band' line activated with a call to SET_GRAPHICS_SELECTION@. The selection mode must be set to either 1, 2 or 4 before this routine can be used.
See also | SET_GRAPHICS_SELECTION@, %gr
Example | See Graphics selections.


GET_IM_INFO@

Platform | Win32, x64
Purpose | To obtain information from a graphics file.
Syntax | SUBROUTINE GET_IM_INFO@( FILENAME, WIDTH, HEIGHT + NB_COLOURS, NB_IMAGES, FORMAT, ERROR ) CHARACTER(*) FILENAME,FORMAT INTEGER WIDTH(n), HEIGHT(n), NB_COLOURS(n) INTEGER NB_IMAGES, ERROR
Description | This subroutine accesses the information that is contained within a .BMP or .PCX file supplied in FILENAME. The relevant data is returned in the supplied parameters. The WIDTH and HEIGHT will contain the dimension of the image. WIDTH, HEIGHT and NB_COLOURS are arrays. NB_IMAGES is returned as the number of images and n should set at a value which is always greater than or equal to NB_IMAGES. FORMAT will be returned as a single character string, either 'BMP' or 'PCX'. ERROR will return:
0 | SUCCESS
2 | READ ERROR
5 | NOT A BMP FILE
10 | BAD FILE
15 | UNKNOWN FORMAT

See also

GET_DIB_SIZE@


GET_MATCHED_COLOUR@

Platform | Win32, x64
Purpose | To find the closest RGB colour match for the current drawing surface.
Syntax | INTEGER FUNCTION GET_MATCHED_COLOUR@(COLOUR) INTEGER COLOUR
Description | GET_MATCHED_COLOUR@ selects the RGB palette colour that is the best match to the supplied RGB COLOUR on the current drawing surface. An error condition arises if RGB colour mode is not selected on the current drawing surface. If there is no current drawing surface then the function returns its input value. Likewise, the function returns its input value if the region is a printer or if the graphics device is a high colour device (i.e. more than 8 bits per pixel).
Return value | Returns the closest match for the current drawing surface.
See also | GET_NEAREST_SCREEN_COLOUR@, USE_RGB_COLOURS@
Example | See Windows graphic modes.


GET_MOUSE_INFO@

Platform | Win32, x64
Purpose | To obtain the position of the mouse, the mouse buttons, and the keyboard shift keys at the time when the last owner-draw (%^dw) or graphics region (%^gr) call-back function was called.
Syntax | SUBROUTINE GET_MOUSE_INFO@( X, Y, FLAGS ) INTEGER X,Y,FLAGS
Description | This routine should be called immediately on entry to the call-back function. It does not make sense to call this function in other contexts. The X and Y values are pixel positions relating to the bitmap associated with the format code (%gr or %dw). Pixel co-ordinates are measures from (0,0) at the top left corner of the area. FLAGS contains the following flags (the parameters will be found in windows.ins):

MK_LBUTTON | 1 | Left mouse button depressed
MK_RBUTTON | 2 | Right mouse button depressed
MK_SHIFT | 4 | Keyboard shift key depressed
MK_CONTROL | 8 | Keyboard control key depressed
MK_MBUTTON | 16 | Middle mouse button depressed

Notes

CLEARWIN_INFO@ can be used instead. These values are returned using GRAPHICS_MOUSE_FLAGS, GRAPHICS_MOUSE_X and GRAPHICS_MOUSE_Y.


GET_MULTIPLE_FILENAMES@

Platform

Win32, x64

Purpose

To access the standard 'open' dialog box.

Syntax

LOGICAL FUNCTION GET_MULTIPLE_FILENAMES@(HWND,
+ TITLE, FILE, NCHARS, FILTER, PATH, NEXT)
CHARACTER(*) TITLE, FILE, FILTER, PATH
INTEGER(7) HWND
INTEGER NCHARS
LOGICAL NEXT

Description

This function is an alternative to GET_FILTERED_FILE@ and allows more than one file to be selected. The arguments are as follows.

Description

HWND: | The Windows handle of the parent window. Use zero for the desktop.
TITLE: | The caption for the dialog box.
FILE: | The full path returned by the dialog box.
NCHARS: | The number of characters in the variable FILE.
FILTER: | The description of the file filters (see example below).
PATH: | The default path (see example).
NEXT: | Set FALSE for the first call then TRUE.

Notes

After this routine has been called, CLEARWIN_INFO@('FILTER_ITEM_SELECTED') provides the index of the file filter that was selected by the user. This can be called, for example, to detect if the file was saved using a different file extension.

Previously 64 bit ClearWin+ used an indirect call to the Windows API whilst 32 bit ClearWin+ used a direct call. Now both 64 bit and 32 bit ClearWin+ use a direct call by default whilst the indirect method is available as an option. The alternative is a little slower but might generally prove to be safer. Make a prior call:

CALL CLEARWIN_OPTION@("alt_open_save")

in order to activate the indirect alternative. The opposite is:

CALL CLEARWIN_OPTION@("-alt_open_save")

Return value

Returns TRUE if another file has been found in the list.

See also

GET_FILTERED_FILE@

Example

WINAPP
INCLUDE <windows.ins>
LOGICAL L,next
CHARACTER*256 filename,filter,defpath
filter = "Free Fortran files (*.f90)"//char(0)//"*.f90"//char(0) &
//"All files (*.*)"//char(0)//"*.*"//char(0)//char(0)
defpath = char(0) !Gives the current working directory
L = .TRUE.
next = .FALSE.
DO WHILE(L)
filename = char(0)
L=GET_MULTIPLE_FILENAMES@(0,"Dialog Title",filename,256,filter,defpath,next)
next = .TRUE.
IF(L) PRINT*, trim(filename)
END DO
END


GET_NEAREST_SCREEN_COLOUR@

Platform | Win32, x64
Purpose | To find the closest colour match for the screen from the system palette.
Syntax | INTEGER FUNCTION GET_NEAREST_SCREEN_COLOUR@(COLOUR) INTEGER COLOUR
Return value | Returns the RGB colour from the Windows system palette that will be displayed when the specified colour value is used on the screen (the value returned by the Windows API function GetNearestColor).
Notes | You can use this function to provide a colour for a drawing surface if you want to over-ride the colour matching carried out automatically by ClearWin+. See Windows graphic modes for further details.
See also | GET_MATCHED_COLOUR@


GET_OS_VER@

Platform

Win32, x64

Purpose

To get version information for the operating system.

Syntax

SUBROUTINE GET_OS_VER@( PLATFORMID, MAJOR, MINOR )
INTEGER PLATFORMID, MAJOR, MINOR

Description

This routine returns values for the platform id and major and minor version numbers according to the following table.

OS | Major | Minor | Platform ID
Windows 3.1 |  |  | 0
Windows 95 | 4 | 0 | 1
Windows 98 | 4 | 10 | 1
Windows Me | 4 | 90 | 1
Windows NT 3.51 | 3 | 51 | 2
Windows NT 4.0 | 4 | 0 | 2
Windows 2000 | 5 | 0 | 2
Windows XP | 5 | 1 | 2
Windows Vista | 6 | 0 | 2
Windows 7 | 6 | 1 | 2
Windows 8 | 6 | 2 | 2
Windows 8.1* | 6 | 3 | 2
Windows 10* | 10 | 0 | 2

Notes

If the executable is running in "compatibility mode" then this routine provides information about the compatible operating system rather than the machine operating system. To get information about the machine operating system use GET_WOW_VER@.

* Windows 8.1 and Windows .10 give the same results as Windows 8 unless a "target" manifest is provided (see below).

Targeting your application for Windows

An application can be targeted for a particular operating system by including a manifest file in a resource script. A line in the resource script takes the form:

   1 24 my.manifest

where the file my.manifest could contain:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
    <application>
      <!-- Windows 10 -->
      <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
      <!-- Windows 8.1 -->
      <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
      <!-- Windows Vista -->
      <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
      <!-- Windows 7 -->
      <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
      <!-- Windows 8 -->
      <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
    </application>
  </compatibility>
</assembly>

Here is a sample program:

   USE clrwin
  INTEGER maj, min, b
  CHARACTER*80 ch
  CALL get_os_ver@(b,maj,min)
  PRINT*,maj,min,b
  CALL get_wow_ver@(ch,maj,min)
  PRINT*,maj,min
  PRINT*,ch
  END
  RESOURCES
    1 24 my.manifest


GET_POINT@

Platform | Win32, x64
Purpose | To get a pixel colour on the current drawing surface.
Syntax | SUBROUTINE GET_POINT@(IH,IV,ICOL) INTEGER IH,IV,ICOL
Description | GET_POINT@ gets the colour value ICOL using the current colour mode of the pixel at (IH, IV) on the current drawing surface. The colour value is given in terms of the current colour mode of the surface.
See also | GET_RGB_VALUE@, DRAW_POINT@


GET_PRINTER_ORIENTATION@

Platform | Win32, x64
Purpose | To get the printer orientation as portrait or landscape.
Syntax | INTEGER GET_PRINTER_ORIENTATION@( )
Return value | Returns 0 for portrait and 1 for landscape.


GET_RGB_VALUE@

Platform

Win32, x64

Purpose

To get the RGB value of the colour of a pixel on the current drawing surface.

Syntax

SUBROUTINE GET_RGB_VALUE@( HOR, VER, VALUE )
INTEGER(KIND=2) HOR,VER
INTEGER(KIND=3) VALUE

Description

The horizontal and vertical co-ordinates locate the pixel on the current drawing surface. An RGB value is always returned irrespective of the current colour mode for the surface.

Note

HOR and VER are KIND=2 input values.

See also

GET_NEAREST_SCREEN_COLOUR@, USE_RGB_COLOURS@


GET_SCREEN_DIB@

Platform | Win32, x64
Purpose | To copy part of a graphics area.
Syntax | SUBROUTINE GET_SCREEN_DIB@( HDIB, X1, Y1, X2, Y2) INTEGER(7) HDIB INTEGER X1, Y1, X2, Y2
Description | HDIB is returned as the handle of a new device context that contains a copy of part of the current graphics area. X1, Y1 are input as the pixel co-ordinates of the top left hand corner of the area to copy whilst X2, Y2 are the corresponding co-ordinates of the bottom right hand corner.
See also | DIB_PAINT@, DIB_PRINT@, EXPORT_BMP@, RELEASE_SCREEN_DIB@


GET_SYSTEM_FONT@

Platform | Win32, x64
Purpose | To get the attributes of the system font.
Syntax | SUBROUTINE GET_SYSTEM_FONT@(LFHEIGHT,LFWIDTH, + LFESCAPEMENT,LFORIENTATION,LFWEIGHT, + LFITALIC,LFUNDERLINE,LFSTRIKEOUT,LFCHARSET, + LFOUTPRECISION,LFCLIPPRECISION,LFQUALITY, + LFPITCHANDFAMILY,LPFACENAME) INTEGER LFHEIGHT,LFWIDTH, LFESCAPEMENT, + LFORIENTATION,LFWEIGHT,LFITALIC, + LFUNDERLINE,LFSTRIKEOUT,LFCHARSET, + LFOUTPRECISION,LFCLIPPRECISION,LFQUALITY, + LFPITCHANDFAMILY CHARACTER(*) LPFACENAME
Description | These attributes may be used to build new fonts by modification. i.e. scaling, italicisation etc.. Modified parameters can then be supplied to the Windows API function CreateFont. See the Windows API documentation of CreateFont for further details.


GET_TEXT_HEIGHT@

Platform | Win32, x64
Purpose | To get the GDI+ height of a character string that will produce the same width characters as GDI.
Syntax | INTEGER FUNCTION GET_TEXT_HEIGHT@(string) CHARACTER(LEN=*)::string
Description | When using the GDI, the height and width of characters can be set independently (using SIZE_IN_PIXELS@ etc.). In contrast, when using the GDI+, only the height can be transmitted and a specified width is ignored. The result is that the GDI/GDI+ heights will match but the string widths may not (the design decision within ClearWin+ is that to match the heights is paramount). When it is expedient to use GDI+ for drawing characters and the when it is important to match the string width rather than the character height, ClearWin+ provides this function (GET_TEXT_HEIGHT@) to provide the adjusted height of a given string such that its GDI+ width matches its GDI width.
Notes | Introduced with FTN95 7.00.
See also | Using GDI+, DRAW_CHARACTERS@.


GET_TEXT_SIZE@

Platform | Win32, x64
Purpose | To get the dimensions of a graphics character string.
Syntax | SUBROUTINE GET_TEXT_SIZE@( STR, WIDTH, DEPTH ) CHARACTER(*) STR INTEGER WIDTH,DEPTH
Description | This routine returns the pixel WIDTH and DEPTH of a given character string STR when drawn on the current drawing surface. Trailing spaces will be included so either use a substring notation or terminate the significant characters by CHAR(0).
See also | Using GDI+, SELECT_FONT@, SCALE_FONT@, UNDERLINE_FONT@, ITALIC_FONT@, BOLD_FONT@, SIZE_IN_PIXELS@, SIZE_IN_POINTS@, ROTATE_FONT@, GET_FONT_NAME@, CHOOSE_FONT@.


GET_TRACK_LENGTH@

Platform | Win32, x64
Purpose | To get the length of a CD track.
Syntax | INTEGER FUNCTION GET_TRACK_LENGTH@( TRACK ) INTEGER TRACK
Description | Call this routine to obtain the length of an audio CD's track in milliseconds. If the track length returned is zero then this track does not exist. This result can be used to determine the number of audio tracks available. The first track number is 1 rather than zero.
Return value | Returns the required track length or zero on failure.
See also | CLOSE_CD_TRAY@, SET_CD_POSITION@, PLAY_AUDIO_CD@, STOP_AUDIO_CD@


GET_USER_DATA@

Platform

Win32, x64

Purpose

To get the location of user data associated with the control.

Syntax

INTEGER(7) FUNCTION GET_USER_DATA@(HWND)
INTEGER(7) HWND

Description

HWND is the window handle of the control obtained by using %lc. The function returns the last value assoicated with the control either by using the format code %ud or the routine SET_USER_DATA@. The same value can also be retrieved by using CLEARWIN_INFO@("USER_DATA") in the controls callback.

See also

%ud, SET_USER_DATA@


GET_WINDOW_LOCATION@

Platform

Win32, x64

Purpose

To get the location and size of a given window.

Syntax

SUBROUTINE GET_WINDOW_LOCATION@( HWND, X, Y, WIDTH,
+ HEIGHT)
INTEGER(7) HWND
INTEGER X, Y, WIDTH, HEIGHT

Description

HWND is a window handle obtained, for example, by using %hw or %lc. Other arguments are returned with the pixel coordinates and dimensions of the window.

Notes

For main windows the X,Y location is in absolute screen coordinates. For child windows attached by %aw to a frame, the coordinates are relative to the top left corner of the frame. For controls and other child (%ch) windows X and Y are relative to the parent window.

This routine (together with the associated move and resize routines) can be used on windows created using WINIO@ or on other windows if the window handle is available. They are particularly useful to control the placement of MDI child windows.

Moving individual controls and un-framed child windows may be unwise as it can cause controls to overlap on the screen.

Windows will be partially or totally concealed if they are moved outside the area of the screen or the enclosing window or frame (in the case of child windows). This is normal and can be used if desired.

Some interesting effects can be obtained by using these functions. For example, suppose that a child window (which might contain a large graphics region) were attached to a frame that was too small to contain it. By calling MOVE_WINDOW@ (e.g. in response to a scroll call-back function) with negative values of X and/or Y, the contents of the window could be scrolled within the frame.

The API function BringWindowToTop may also be useful when re-arranging windows.

See also

MOVE_WINDOW@, RESIZE_WINDOW@


GET_WKEY1@

Platform | Win32, x64
Purpose | To get a key from a ClearWin window keyboard buffer.
Syntax | INTEGER FUNCTION GET_WKEY1@( )
Description | This routine is only for use in a ClearWin window (e.g. with %cw). It is like GET_WKEY@ but immediately returns zero if the buffer is empty.
Notes | ADD_KEYBOARD_MONITOR@ provides a better mechanism for handling keyboard input.
Return value | Returns the ASCII code for the first key and removes it from the buffer. If the buffer is empty it returns zero.
See also | FEED_WKEYBOARD@, FLUSH_WKEYBOARD@, GET_WKEY@, WKEY_WAITING@


GET_WKEY@

Platform | Win32, x64
Purpose | To get a key from a ClearWin window keyboard buffer.
Syntax | INTEGER FUNCTION GET_WKEY@( )
Description | This routine is only for use in a ClearWin window (e.g. with %cw). If necessary, it waits for the user to press a key on the keyboard. However, the routine will yield to other processes.
Notes | ADD_KEYBOARD_MONITOR@ provides a better mechanism for handling keyboard input.
Return value | Returns the ASCII code for the first key and removes it from the buffer.
See also | FEED_WKEYBOARD@, FLUSH_WKEYBOARD@, GET_WKEY1@, WKEY_WAITING@


GET_WOW_VER@

Platform | Win32, x64
Purpose | To get version information for the operating system.
Syntax | SUBROUTINE GET_WOW_VER@( PRODUCT, MAJOR, MINOR ) CHARACTER(*) PRODUCT INTEGER MAJOR, MINOR
Description | This routine is similar to GET_OS_VER@ and provides version data for the operating system together with its product description, for example "Microsoft Windows XP". It differs from GET_OS_VER@ when the executable is running in "compatibility mode" where GET_OS_VER@ provides the compatible OS and GET_WOW_VER@ provides the machine OS.


GRAPHICS_TO_CLIPBOARD@

Platform | Win32, x64
Purpose | To allow the interchange of graphics between drawing surfaces and other Windows applications.
Syntax | INTEGER FUNCTION GRAPHICS_TO_CLIPBOARD@(X1,Y1,X2,Y2) INTEGER X1, Y1, X2, Y2
Description | Places a rectangular area of a drawing surface on to the clipboard so that other Windows programs can use the image. X1, Y1 is the top left corner of the area. X2, Y2 is the lower right corner of the area.
Return value | Returns 1 for success and zero on failure.
See also | COPY_FROM_CLIPBOARD@, COPY_TO_CLIPBOARD@, CLIPBOARD_TO_SCREEN_BLOCK@


GRAPHICS_WRITE_MODE@

Platform | Win32, x64
Purpose | To select replace/XOR mode before writing to the current drawing surface.
Syntax | SUBROUTINE GRAPHICS_WRITE_MODE@(MODE) INTEGER MODE
Description | This routine sets the graphics write mode for the current drawing surface depending on the value of MODE. Any value other than 3 will force all subsequent graphics output to replace existing pixels. A value of 3 will cause the output to be XORed with existing pixels.


HIBYTE@

Platform | Win32, x64
Purpose | To get the top 8 bits of a 16 bit integer.
Syntax | INTEGER*1 FUNCTION HIBYTE@(WORD) INTEGER*2 WORD
Notes | This is the ClearWin+ Fortran equivalent of the Microsoft C macro with the same name. See also: LOBYTE@, LOWORD@, HIWORD@


HIGH_COLOUR_MODE@

Platform | Win32, x64
Purpose | To test if the screen is a high colour device.
Syntax | LOGICAL FUNCTION HIGH_COLOUR_MODE@( )
Description | A high colour device is one that has more than 8 bits per pixel (i.e. more than 256 colours). A high colour device does not make use of colour palettes. If you want to use a wide range of colours whilst avoiding the complexities of managing a palette, one solution is to restrict the usage to desktops operating in high colour mode. Thus you can use this function to test if the desktop is set to operate with more than 256 colours per pixel and to send a error message and close down on failure. All modern screens are high colour.
Return value | Returns .TRUE. for success.


HIWORD@

Platform | Win32, x64
Purpose | To get the top 16 bits of a 32 bit integer.
Syntax | INTEGER*2 FUNCTION HIWORD@(DWORD) INTEGER DWORD
Description | Windows API functions sometimes return two values in a long integer with one value in the top 16 bits and one value in the bottom 16 bits. GetTextExtent does this for example, returning the height of the text in the top 16 bits and the width in the bottom 16 bits.
Notes | This is the Fortran ClearWin+ equivalent of the Microsoft C macro with the same name. See also LOWORD@, HIBYTE@, LOBYTE@


IMPORT_BMP@

Platform | Win32, x64
Purpose | To read in a BMP file.
Syntax | INTEGER(7) FUNCTION IMPORT_BMP@( FILENAME, ERROR ) CHARACTER(*) FILENAME INTEGER ERROR
Description | Reads in a BMP file and returns a DIB handle to the image. The handle can then be used with DIB_PAINT@, DIB_PRINT@ and EXPORT_BMP@. ERROR returns one of the following:

0 | success
2 | unable to read file
4 | insufficient memory
5 | not a BMP file
10 | unable to open file

Return value | Returns a handle to the image or zero on failure.
See also | GET_SCREEN_DIB@, RELEASE_SCREEN_DIB@, IMPORT_PCX@, CLIPBOARD_TO_SCREEN_BLOCK@, IMPORT_GIF@, IMPORT_IMAGE@, IMPORT_FILE_IMAGE@


IMPORT_FILE_IMAGE@

Platform | Win32, x64
Purpose | To paste an image on to a (%gr) drawing surface using an external file.
Syntax | INTEGER FUNCTION IMPORT_FILE_IMAGE@( FILENAME, X, Y ) CHARACTER(*) FILENAME INTEGER X, Y
Description | FILENAME is the filename to use. The file data (rather than the file name extension) determines the type of the image (.png, .jpeg, .bmp, .gif or .pcx). X and Y are pixel offsets into the %gr region.
Return value | The function returns a non-zero value when successful.
See also | EXPORT_IMAGE@, USE_GDIPLUS_IMAGE_FILES, IMPORT_BMP@, IMPORT_GIF@, IMPORT_PCX@, IMPORT_IMAGE@


IMPORT_GIF@

Platform | Win32, x64
Purpose | To read in a GIF file.
Syntax | INTEGER(7) FUNCTION IMPORT_GIF@( FILENAME, IMAGEN, NIMAGES, ERROR ) CHARACTER(*) FILENAME INTEGER IMAGEN,NIMAGES,ERROR
Description | Reads in a GIF file and returns a DIB handle to the image. The handle can then be used with DIB_PAINT@ and DIB_PRINT@. IMAGEN is an input value being the number of the image in the file to display. NIMAGES is returned as the number of images in the file. ERROR returns one of the following:

0 | success
2 | unable to read file
4 | insufficient memory
5 | not a GIF file
10 | unable to open file

Return value | Returns a handle to the image or zero on failure.
See also | GET_SCREEN_DIB@, RELEASE_SCREEN_DIB@, IMPORT_PCX@, CLIPBOARD_TO_SCREEN_BLOCK@, IMPORT_BMP@, IMPORT_IMAGE@, IMPORT_FILE_IMAGE@


IMPORT_IMAGE@

Platform | Win32, x64
Purpose | To paste an image on to a (%gr) drawing surface using an internal resource or an external file.
Syntax | INTEGER FUNCTION IMPORT_IMAGE@( RSCNAME, X, Y ) CHARACTER(*) RSCNAME INTEGER X, Y
Description | RSCNAME is linked to a file via a resource script or is a file name enclosed in curly brackets. The file data (rather than the file name extension) determines the type of the image (.png, .jpeg, .bmp, .gif or .pcx). X and Y are pixel offsets into the %gr region.
Example | i=IMPORT_IMAGE@(rsc_name,0,0) !The resource script contains one of the following lines. rsc_name IMAGE png_file.png rsc_name IMAGE jpg_file.jpg rsc_name IMAGE bmp_file.bmp rsc_name GIF gif_file.gif rsc_name IMAGE pcx_file.pcx
Return value | The function returns a non-zero value when successful.
See also | EXPORT_IMAGE@, USE_GDIPLUS_IMAGE_FILES, IMPORT_BMP@, IMPORT_GIF@, IMPORT_PCX@, IMPORT_FILE_IMAGE@


IMPORT_PCX@

Platform | Win32, x64
Purpose | To read in a .PCX file.
Syntax | INTEGER(7) FUNCTION IMPORT_PCX@( FILENAME, ERROR ) CHARACTER(*) FILENAME INTEGER ERROR
Description | Reads in a PCX file and returns a DIB handle to the image that is compatible with windows bitmaps allowing it be used with DIB_PAINT@, DIB_PRINT@ and EXPORT_BMP@. ERROR returns one of the following:

0 | success
2 | unable to read file
4 | insufficient memory
6 | not a PCX file
10 | unable to open file

Return value | Returns a handle to the image or zero on failure.
See also | GET_SCREEN_DIB@, RELEASE_SCREEN_DIB@, IMPORT_BMP@, IMPORT_GIF@, IMPORT_IMAGE@, CLIPBOARD_TO_SCREEN_BLOCK@, IMPORT_FILE_IMAGE@


INVALID_FLOAT@

Platform | Win32, x64
Purpose | To detect if a value is a NaN.
Syntax | LOGICAL FUNCTION INVALID_FLOAT@(VALUE) REAL VALUE
Description | This tests to see if the value represent a NaN. There is a similar function INVALID_DOUBLE@ that does the same function for double precision values: LOGICAL FUNCTION INVALID_DOUBLE@(VALUE) DOUBLE PRECISION VALUE


LOADRESOURCE@

Platform | Win32, x64
Purpose | To get the Microsoft HANDLE of a bitmap, icon or cursor.
Syntax | INTEGER(KIND=7) FUNCTION LOADRESOURCE@(NAME, ResType) CHARACTER(LEN=*) name, resType
Notes | ResType is one of "BITMAP", "ICON" and "CURSOR". NAME can correspond to one of a number of predefined Microsoft resources or can be a name provided in a user resource script or RESOURCES directive. Predefined BITMAPs are "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce", "zoom" and "restore". Predefined ICONs are "app", "logo", "info", "error", "warn", "question" and "shield". Predefined CURSORs are "arrow", "cross", "hand", "help", "ibeam", "no", "size" and "wait". LOADRESOURCE@ can be used, for example, with %`bm, %`ic and with the Windows API function SetCursor.


LOBYTE@

Platform | Win32, x64
Purpose | To get the bottom 8 bits of a 16 bit integer.
Syntax | INTEGER*1 FUNCTION LOBYTE@(WORD) INTEGER*2 WORD
Notes | This is the ClearWin+ Fortran equivalent of the Microsoft C macro with the same name. See also HIBYTE@, LOWORD@, HIWORD@.


LOWORD@

Platform | Win32, x64
Purpose | To get the bottom 16 bits of a 32 bit integer.
Syntax | INTEGER*2 FUNCTION LOWORD@(DWORD) INTEGER DWORD
Notes | This is the Fortran ClearWin+ equivalent of the Microsoft C macro with the same name. See also: HIWORD@, LOBYTE@, HIBYTE@


MAKE_BITMAP@

Platform | Win32, x64
Purpose | To embed a bitmap in program code.
Syntax | INTEGER(7) FUNCTION MAKE_BITMAP@(BMP_DATA, XRES, YRES) CHARACTER*YRES BMP_DATA( XRES ) INTEGER XRES, YRES PARAMETER XRES,YRES
Description | Bitmaps are usually included in a program statically via resources or dynamically with Windows API calls. This routine is provided so that bitmaps may be included in the source code as text data and then translated into bitmap format. A (HBITMAP) handle to a bitmap is returned that can be used for example with %`bm. This provides a speedy method of designing simple graphics that would otherwise require image editing software. The character arrays may include the following characters:

- (minus) | Black
b | Dark blue
r | Dark red
g | Dark green
y | Dark yellow (brown)
m | Dark magenta
c | Dark cyan
w | Grey
l | Light grey
B | Blue
R | Red
G | Green
Y | Yellow
M | Magenta
C | Cyan
W | White

Return value | Returns a bitmap handle to the new bitmap.
See also | MAKE_ICON@


MAKE_ICON@

Platform

Win32, x64

Purpose

To embed an icon in program code.

Syntax

INTEGER(7) FUNCTION MAKE_ICON@( ICON_DATA )
CHARACTER*32 ICON_DATA(32)

Description

This routine allows an icon to be embedded in the program code. A 32x32 character array must be defined to accommodate the icon data. The characters can be defined as any of the following:

- (minus) | Black
b | Dark blue
r | Dark red
g | Dark green
y | Dark yellow (brown)
m | Dark magenta
c | Dark cyan
w | Grey
B | Blue
R | Red
G | Green
Y | Yellow
M | Magenta
C | Cyan
W | White

 | If any other character is used then a transparent colour is assumed which will allow the background to show through. A (HICON) handle to the icon is returned which may be used for example with %`ic. The icon is automatically discarded at program termination.
Return value | Returns a handle to the new icon.
See also | MAKE_BITMAP@
Example | INCLUDE <windows.ins> CHARACTER*32 icon(32) INTEGER hicon hicon=make_icon@(ICON) DATA icon(1)/'RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR'/ DATA icon(2)/'RYYBBYYBBYYBBYYBBYYBBYYBBYYBBYYR'/ ... ... DATA icon(30)/'RYYBBYYBBYYBBYYBBYYBBYYBBYYBBYYR'/ DATA icon(31)/'RYYBBYYBBYYBBYYBBYYBBYYBBYYBBYYR'/ DATA icon(32)/'RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR'/ k=winio@('%ca[Make icon]%nl%`ic',HICON) END


MAP_FILE_FOR_READING@

Platform

Win32, x64

Purpose

To map a file to memory.

Syntax

INTEGER(7) FUNCTION MAP_FILE_FOR_READING@( FILENAME, SIZE )
CHARACTER(*) FILENAME
INTEGER SIZE

Description

When a file is memory mapped, a region of memory is defined so that accesses to that memory effectively access the disk file. A file may be opened for reading using MAP_FILE_FOR_READING@.

FILENAME is the name of the file to be opened and SIZE is returned as the size of the file.

Use the various Silverfrost CORE intrinsic functions to access the contents of the file. Any attempt to alter the contents of the file will cause an error. The memory can be unmapped by calling UNMAP_FILE@.

Return value

Returns the starting address of the mapped view or zero on failure

Notes

To call a routine with a mapped file as an argument use the form MYSUB(CCORE1(PTR)) where PTR is the value returned by MAP_FILE_FOR_READING@.

See also

MAP_FILE_FOR_READ_WRITE@, UNMAP_FILE@


MAP_FILE_FOR_READ_WRITE@

Platform | Win32, x64
Purpose | To map a file to memory.
Syntax | INTEGER(7) FUNCTION MAP_FILE_FOR_READ_WRITE@( FILENAME, SIZE ) CHARACTER(*) FILENAME INTEGER SIZE
Description | See MAP_FILE_FOR_READING@. In MAP_FILE_FOR_READ_WRITE@ the variable SIZE can be input as zero, in which case it will be returned as the original size of the file. Otherwise, the mapped memory region will be set to SIZE bytes and the file will be extended if necessary. If the file does not exist it will be created. In this routine the contents of the file can be changed.
Return value | Returns the starting address of the mapped view or zero on failure.
See also | MAP_FILE_FOR_READING@, UNMAP_FILE@


METAFILE_TO_CLIPBOARD@

Platform | Win32, x64
Purpose | To send a metafile to the clipboard.
Syntax | INTEGER FUNCTION METAFILE_TO_CLIPBOARD@( )
Description | This function can be used after a call to OPEN_METAFILE@ followed by calls to graphics drawing routines. It causes the image to be stored on the clipboard in metafile format. Alternatively, if the %gr option metafile_resize is used, this function can be used to send the resulting metafile to the clipboard.
Return value | Returns 1 for success or zero for failure.
Notes | If a background colour is specified for %gr (e.g. %gr[black]), this information is not recorded in the metafile.
See also | OPEN_METAFILE@, CLOSE_METAFILE@, PLAY_CLIPBOARD_METAFILE@


MOVE_WINDOW@

Platform | Win32, x64
Purpose | To move a window.
Syntax | SUBROUTINE MOVE_WINDOW@( HWND, X, Y) INTEGER(7) HWND INTEGER X, Y
Description | HWND is typically a value obtained by using %hw or %lc. X and Y are input as the new location of the window in pixel coordinates. See GET_WINDOW_LOCATION@ and its associated notes.
See also | RESIZE_WINDOW@


MOVIE_PLAYING@

Platform | Win32, x64
Purpose | To test if a video is still playing.
Syntax | INTEGER(7) FUNCTION MOVIE_PLAYING@()
Return value | MOVIE_PLAYING@ returns an integer that is the Window handle of the movie window created by a call to SHOW_MOVIE@ (or zero if no movie is playing). This handle can be passed to the standard API function DestroyWindow to force the movie to end.


nARGB@

Platform | Win32, x64
Purpose | To pack 8-bit colour values plus opacity into a 32-bit integer.
Syntax | INTEGER FUNCTION nARGB@(ALPHA,RED,GREEN,BLUE) INTEGER ALPHA, RED, GREEN, BLUE
Description | 'ALPHA' is the opacity and RED, GREEN and BLUE are the colour intensities. All values are assumed to be in the range 0-255 inclusive. This function returns the RGB@ value and has the side effect of storing the opacity for the next call to a drawing routine. This temporary value is reset to the default opacity after its first use and this value over-rides the default opacity for the current drawing surface. When nARGB@ is called as an argument of a graphics routine then the stored opacity will relate to the current call.
Return value | Returns the packed RGB values.
Notes | Introduced with FTN95 7.00.
See also | Using GDI+, SET_OPACITY, USE_GDIPLUS


NEW_GRAPHICS_REGION@

Platform

Win32, x64

Purpose

To create an internal (off-screen) drawing surface.

Syntax

INTEGER FUNCTION NEW_GRAPHICS_REGION@( UID,
+ WIDTH, HEIGHT, COL)
INTEGER UID, WIDTH, HEIGHT, COL

Description

This routine is used to create internal drawing surfaces. For example, it can be used to display part of a large bitmap. Areas of the buffer can be copied into a %gr region (for example) using COPY_GRAPHICS_REGION@. If you make extensive use of this function it is recommended that you delete unwanted surfaces with a call to DELETE_GRAPHICS_REGION@.

UID is an input value, chosen by the programmer, that must be unique. It is used to identify the surface in calls to related functions. WIDTH, HEIGHT specify the size in pixels of the region. The surface will be initialised to the RGB colour COL.

The colour mode for the surface will be determined by the default colour mode or by the colour mode of the current %gr drawing surface.

Return value

Returns 1 for success, otherwise zero.

See also

DELETE_GRAPHICS_REGION@, COPY_GRAPHICS_REGION@, SCROLL_GRAPHICS@, CREATE_GRAPHICS_REGION@.


NEW_PAGE@

Platform

Win32, x64

Purpose

To provide a new page on the current drawing surface.

Syntax

SUBROUTINE NEW_PAGE@

Description

The effect of this routine depends on the type of the current drawing surface:

Device | Effect
screen | clears the screen area (identical to CLEAR_SCREEN@)
printer | prints the image and then blanks the bitmap (an alternative to CLOSE_PRINTER@)


OPEN_CD_TRAY@

Platform | Win32, x64
Purpose | To open a CD-drive tray.
Syntax | SUBROUTINE OPEN_CD_TRAY@()
Description | Simply by calling this routine any closed CD drive with a mechanical drawer will open.
See also | CLOSE_CD_TRAY@, SET_CD_POSITION@, PLAY_AUDIO_CD@, STOP_AUDIO_CD@


OPEN_GL_PRINTER1@

Platform

Win32, x64

Purpose

To attach a printer to OpenGL.

Syntax

INTEGER FUNCTION OPEN_GL_PRINTER1@(ID,ATTRIB,WIDTH,HEIGHT)
INTEGER ID,ATTRIB,WIDTH,HEIGHT

Description

This function is similar to OPEN_GL_PRINTER@ but it does not display the Open Printer dialog box. Instead it uses either the default printer or the printer selected in an earlier call to OPEN_GL_PRINTER@.

ID is the user assigned printer identification number.

ATTRIB is a variable that describes the buffering that is required and is a combination of the following flags.

GL_DOUBLE_BIT

GL_STENCIL_BIT

GL_ACCUM_BIT

GL_DEPTH16_BIT

GL_DEPTH32_BIT

These flags may be added together.

When the function returns, WIDTH and HEIGHT provide the width and height of the printer page in pixels.

Note that ID and ATTRIB are input values whilst WIDTH and HEIGHT are output values.

Return value

This function returns 1 for success, otherwise zero.

See also

OPEN_GL_PRINTER@, PRINT_OPENGL_IMAGE@


OPEN_GL_PRINTER@

Platform

Win32, x64

Purpose

To display the Open Printer dialog box and attach it to OpenGL.

Syntax

INTEGER FUNCTION OPEN_GL_PRINTER@(ID,ATTRIB,WIDTH,HEIGHT)
INTEGER ID,ATTRIB,WIDTH,HEIGHT

Description

ID is the user assigned printer identification number.

ATTRIB is a variable that describes the buffering that is required and is a combination of the following flags.

GL_DOUBLE_BIT

GL_STENCIL_BIT

GL_ACCUM_BIT

GL_DEPTH16_BIT

GL_DEPTH32_BIT

These flags may be added together.

When the function returns, WIDTH and HEIGHT provide the width and height of the printer page in pixels.

Note that ID and ATTRIB are input values whilst WIDTH and HEIGHT are output values.

Return value

This function returns 1 if the user selected a device or zero if the "CANCEL" button was selected.

See also

OPEN_GL_PRINTER1@, PRINT_OPENGL_IMAGE@


OPEN_METAFILE@

Platform | Win32, x64
Purpose | To record graphics sequences.
Syntax | INTEGER FUNCTION OPEN_METAFILE@( H ) INTEGER H
Description | Opens a metafile for the current graphics area. A metafile is used to store graphics information using a device independent format that can be printed, replayed or copied to the clipboard.
Return value | Returns 1 for success or zero on failure.
See also | CLOSE_METAFILE@, METAFILE_TO_CLIPBOARD@, PLAY_CLIPBOARD_METAFILE@, DO_COPIES@, PRINT_GRAPHICS_PAGE@


OPEN_PRINTER1@

Platform

Win32, x64

Purpose

To begin output to a graphics printer or plotter.

Syntax

INTEGER FUNCTION OPEN_PRINTER1@( UID )
INTEGER UID

Description

OPEN_PRINTER1@ does not generate a standard "Open Printer" dialog box which means that printing can resume to the current printer after calls to OPEN_PRINTER@ and CLOSE_PRINTER@. This avoids the need to repeatedly select the same printer. Subsequent calls to Silverfrost graphics routines are written to this device. The printer or plotter is activated when CLOSE_PRINTER@ (see ) or the routine NEW_PAGE@ is called (after calling this routine, it may be necessary to reset the text attributes).

UID is a unique identifier supplied by the programmer and its value is used in conjunction with SELECT_GRAPHICS_OBJECT@.

Return value

This function returns 1 for success, otherwise zero.

Notes

This routine can be used in conjunction with the %gr format code that is used to draw to the screen using Silverfrost graphics routines (see Graphics format). It can also be used independently of WINIO@.

The standard call-back function GPRINTER_OPEN can also be used to produce graphics output.

See also

CLOSE_PRINTER@, DO_COPIES@, SELECT_PRINTER@


OPEN_PRINTER1_TO_FILE@

Platform | Win32, x64
Purpose | To cause the Windows printer device driver to begin graphics output to a file instead of a physical printer.
Syntax | INTEGER FUNCTION OPEN_PRINTER1_TO_FILE@(UID, FILENAME) CHARACTER(*) FILENAME INTEGER UID
Description | This function is similar to OPEN_PRINTER1@ but the output is sent to the specified file.
Return value | Returns 1 for success, otherwise zero.
See also | OPEN_PRINTER_TO_FILE@


OPEN_PRINTER@

Platform

Win32, x64

Purpose

To begin output to a graphics printer or plotter.

Syntax

INTEGER FUNCTION OPEN_PRINTER@( UID )
INTEGER UID

Description

OPEN_PRINTER@ generates a standard "Open Printer" dialog box from which the user can select a graphics printer or plotter device for subsequent output. If a device is successfully selected then subsequent calls to Silverfrost graphics routines are be written to this device. The printer or plotter is activated when CLOSE_PRINTER@ or the Silverfrost graphics routine NEW_PAGE@ is called (after calling this routine, it may be necessary to reset the text attributes).

UID is a unique user identifier supplied by the programmer and is used in conjunction with SELECT_GRAPHICS_OBJECT@.

OPEN_PRINTER@ and CLOSE_PRINTER@ will use the GDI+ library provided the smoothing and/or opacity is set. Call USE_GDIPLUS@ before opening the printer or set the opacity and/or the smoothing after opening. Alternatively OPEN_PRINTER@ will inherit the opacity and smoothing of the current drawing surface before opening.

Return value

This function returns 1 if the user selected a device or zero if the "CANCEL" button was selected.

Notes

This routine can be used in conjunction with the %gr format code that is used to draw to the screen using Silverfrost graphics routines (see Graphics format). It can also be used independently of WINIO@.

The standard call-back function GPRINTER_OPEN can also be used to produce graphics output.

See also

CLOSE_PRINTER@, DO_COPIES@, SELECT_PRINTER@, OPEN_PRINTER1@, Selecting a printer


OPEN_PRINTER_TO_FILE@

Platform | Win32, x64
Purpose | To cause the Windows printer device driver to begin graphics output to a file instead of a physical printer.
Syntax | INTEGER FUNCTION OPEN_PRINTER_TO_FILE@(UID, FILENAME) CHARACTER(*) FILENAME INTEGER UID
Description | This function is similar to OPEN_PRINTER@ but the output is sent to the specified file.
Return value | Returns 1 if the user selected a device or zero if the "CANCEL" button was selected.
See also | OPEN_PRINTER1_TO_FILE@


OPEN_SVG@

Platform | Win32, x64
Purpose | To begin output to a Scalable Vector Graphics (SVG) file. Scalable Vector Graphics files allow you to produce graphics file that are resolution independent.
Syntax | INTEGER FUNCTION OPEN_SVG@(FILE, NX, NY) CHARACTER(*) FILE INTEGER NX,NY
Description | Calling OPEN_SVG@ will direct graphics to a new SVG graphics file. SVG has the advantage of being a vector format that will scale with the resolution required. NX and NY specify the bounding box into which the graphics are to be drawn. FILE is the path of the file. This is analogous to generating printer output. This function sets the identifier of the associated graphics object to zero. Call CLOSE_SVG@(0) to terminate output to the file.
Return value | Returns 1 on success or zero on failure.
Notes | OPEN_SVG1@ is similar but allows the programmer to set the user identifier for the associated graphics object. Added to FTN95 at version 8.05.
See also | OPEN_SVG1@


OPEN_SVG1@

Platform | Win32, x64
Purpose | To begin output to a Scalable Vector Graphics (SVG) file. Scalable Vector Graphics files allow you to produce graphics file that are resolution independent.
Syntax | INTEGER FUNCTION OPEN_SVG1@(FILE, NX, NY, UID) CHARACTER(*) FILE INTEGER NX,NY,UID
Description | Calling OPEN_SVG1@ will direct graphics to a new SVG graphics file. SVG has the advantage of being a vector format that will scale with the resolution required. NX and NY specify the bounding box into which the graphics are to be drawn. FILE is the path of the file. This is analogous to generating printer output. UID is the programmer's identifier of the associated graphics object (used in SELECT_GRAPHICS_OBJECT@). Call CLOSE_SVG@(UID) to terminate output to the file.
Return value | Returns 1 on success or zero on failure.
Notes | Added to FTN95 at version 8.05
See also | OPEN_SVG@


OPEN_TO_WINDOW@

Platform | Win32, x64
Purpose | To attach a ClearWin window to a Fortran unit.
Syntax | SUBROUTINE OPEN_TO_WINDOW@(UNIT,HWND) INTEGER UNIT INTEGER(7) HWND
Description | Attaches a previously created ClearWin window with handle HWND to Fortran unit UNIT. This routine enables Fortran I/O requests (for example READ, WRITE and PRINT) to be directed to the specified window.


OPEN_WAV_FILE_READ@

Platform | Win32, x64
Purpose | To open a WAV file for reading in sections.
Syntax | INTEGER(7) FUNCTION OPEN_WAV_FILE_READ@(FILE,N_CHANNELS,N_SAMPLES,SAMPLE_RATE) CHARACTER(*) FILE INTEGER N_CHANNELS,N_SAMPLES,SAMPLE_RATE
Description | This routine opens a simple (uncompressed) .WAV file so that its contents can be read with a series of calls to WAV_FILE_READ@. The number of samples and the sample rate are returned by the function. WAV files should be closed using CLOSE_WAV_FILE@
Return value | The return value is the handle to be passed to subsequent sound function calls. A zero value indicates a corrupt WAV file or an unsupported WAV format.
See also | OPEN_WAV_FILE_WRITE@


OPEN_WAV_FILE_WRITE@

Platform

Win32, x64

Purpose

To open a WAV file for writing in sections.

Syntax

INTEGER(7) FUNCTION OPEN_WAV_FILE_WRITE@(FILE,N_CHANNELS,
+ SAMPLE_RATE)
CHARACTER(*) FILE
INTEGER N_CHANNELS,SAMPLE_RATE

Description

This routine clears and opens a .WAV file to receive sound output as a series of calls to WAV_FILE_WRITE@. The number of channels and the sample rate must be supplied to this function. The file will contain sound stored at 16 bits per sample.

Unlike WRITE_WAV_FILE@, files written in this way can be written in sections, and may therefore be of effectively unlimitted size.

The file should be closed using CLOSE_WAV_FILE@

Return value

The return value is the handle to be passed to subsequent sound function calls.

See also

OPEN_WAV_FILE_READ@


PERFORM_GRAPHICS_UPDATE@

Platform | Win32, x64
Purpose | To refresh the current drawing surface display.
Syntax | SUBROUTINE PERFORM_GRAPHICS_UPDATE@( )
Description | The current drawing surface, defined by %gr, will be refreshed with every call to this routine. Under normal operations a call to a graphics function will not produce an immediate update, rather ClearWin+ will wait until you have finished your current sequence of graphics calls from within your call-back. This is not usually a problem as it ensures that only the final results are displayed.
See also | SELECT_GRAPHICS_OBJECT@


PERMIT_ANOTHER_CALLBACK@

Platform

Win32, x64

Purpose

To allow another call-back function to be called.

Syntax

SUBROUTINE PERMIT_ANOTHER_CALLBACK@( )

Description

Usually if a window invokes a call-back function (in response to a menu, say) most of the standard controls are inhibited from raising further call-backs. This action is normally desirable as it prevents unfortunate complications if the user's mouse 'bounces' on a button.

The subroutine PERMIT_ANOTHER_CALLBACK@ allows a call-back function to permit an additional call-back. This routine will only permit one additional call-back, but it can be called as many times as desired, each time enabling a further call-back. When using this routine it is assumed that a call will also be made to a routine such as TEMPORARY_YIELD@ to permit the processing of further messages.

Notes

Many programs that seem to require this facility may be presenting the user with a non-standard interface and should be re-structured. For example, suppose a window offers a menu item which will start a lengthy calculation which the user may wish to abort. The usual way to handle this is to display a small additional window with a Cancel button and possibly a progress bar. Since this additional window is distinct from the window which contained the original menu item, there is no need to call the above routine.

See also

PERMIT_CALLBACK_IN_WINDOW@


PERMIT_CALLBACK_IN_WINDOW@

Platform | Win32, x64
Purpose | To allow another call-back function to be called.
Syntax | SUBROUTINE PERMIT_CALLBACK_IN_WINDOW@( HWND ) INTEGER(7) HWND
Description | HWND is a window handle obtained using %hw. This routine is like PERMIT_ANOTHER_CALLBACK@ but is only effective for callback functions that are called from the window with handle W.


PLAY_AUDIO_CD@

Platform | Win32, x64
Purpose | To play the audio CD from the current position.
Syntax | INTEGER FUNCTION PLAY_AUDIO_CD( DURATION ) INTEGER DURATION
Description | Plays an audio CD starting at the current location which can be set with a call to SET_CD_POSITION@. If duration is any valid number greater than 0 it will play for that amount of time in milliseconds. If the duration is less than 0 it will play that number of tracks i.e. a value of -4 will play the next four tracks.
Return value | Always returns 1.
See also | CLOSE_CD_TRAY@, OPEN_CD_TRAY@, SET_CD_POSITION@, STOP_AUDIO_CD@, GET_TRACK_LENGTH@
Example | call set_cd_position@( 1, 0 ) call play_audio_cd@( -1 )


PLAY_CLIPBOARD_METAFILE@

Platform | Win32, x64
Purpose | To play a clipboard metafile on the current drawing surface.
Syntax | INTEGER PLAY_CLIPBOARD_METAFILE@( COL ) INTEGER COL
Description | This can be used after a call to METAFILE_TO_CLIPBOARD@. COL is used to set the background colour using the current colour mode.
Return value | The value 1 is returned for success and zero for failure.
See also | OPEN_METAFILE@, CLOSE_METAFILE@


PLAY_SOUND@

Platform | Win32, x64
Purpose | To send a sample to the audio output device.
Syntax | INTEGER FUNCTION PLAY_SOUND@( LEFT, RIGHT, SAMPLES ) INTEGER*2 LEFT(SAMPLES), RIGHT(SAMPLES) INTEGER SAMPLES PARAMETER SAMPLES
Description | LEFT and RIGHT are arrays that contain the 16 bit sample data. The number of samples is SAMPLES. You should check the values returned by SOUND_PLAYING@ and SOUND_RECORDING@ so that a call is not made to this routine until the sound device is idle.
Return value | Returns 1 for success and a zero on failure
See also | WRITE_WAV_FILE@, PLAY_SOUND_RESOURCE@, RECORD_SOUND@, SOUND_PLAYING@, SOUND_RECORDING@


PLAY_SOUND_RESOURCE@

Platform

Win32, x64

Purpose

To send a resource SOUND to the current audio device.

Syntax

INTEGER FUNCTION PLAY_SOUND_RESOURCE@( NAME )
CHARACTER*80 NAME

Description

This routine plays any resource that is of type SOUND. Care should be taken not to include samples (.WAV files) that are more than a few seconds for two reasons. 1) the sample occupies memory and 2) the routine is synchronous and will halt all other output until the sample has completed playback. It is necessary to supply a valid resource name to this routine.

For example:

Include in the resource section of your program:

MYWAVE SOUND "dogbark.wav"

In the code section:

res=PLAY_SOUND_RESOURCE@( 'MYWAVE' )

Return value

Returns 0 for success, otherwise -1.

See also

WRITE_WAV_FILE@, PLAY_SOUND@, RECORD_SOUND@, SOUND_PLAYING@,
SOUND_RECORDING@


PRINTER_DIALOG_OPTIONS@

Platform

Win32, x64

Purpose

To configure the standard printer dialog box.

Syntax

SUBROUTINE PRINTER_DIALOG_OPTIONS@(
+ NO_PRINT_TO_FILE, NO_PAGE_NUMBERS, NO_SELECTION,
+ NO_DEFAULT_WARNING, SET_SOME_PAGES, SET_SELECTION,
+ SET_COLLATE, SET_ALL_PAGES, SET_PRINT_TO_FILE )
INTEGER
+ NO_PRINT_TO_FILE, NO_PAGE_NUMBERS, NO_SELECTION,
+ NO_DEFAULT_WARNING, SET_SOME_PAGES, SET_SELECTION,
+ SET_COLLATE, SET_ALL_PAGES, SET_PRINT_TO_FILE

Description

The following table describes the effect of setting an argument value to 1 rather than zero.

NO_PRINT_TO_FILE | Hides the 'Print to file' check box.
NO_PAGE_NUMBERS | Disables the 'Page numbers' radio button.
NO_SELECTION | Disables the 'Print selection' radio button.
NO_DEFAULT_WARNING | Disables 'No default printer' warning.
SET_SOME_PAGES | 'Page rage' radio button is set.
SET_SELECTION | 'Selection' radio button is set.
SET_COLLATE | 'Collate copies' check box is checked.
SET_ALL_PAGES | 'Print all pages' radio button is set.
SET_PRINT_TO_FILE | 'Print to file' check box is checked.

The following CLEARWIN_INFO@ strings hold some of the selected options after the printer dialog box has closed.

'PRINTER_SELECTION' | 'Print selection' was set.
'PRINTER_COLLATE' | 'Print collate copies' was checked.
'PRINTER_PAGENUMBERS' | 'Print page numbers' was set.

These values will be either 1 or zero.

Note

You can deduce the 'print all pages' radio button selection by 'PRINTER_SELECTION' and 'PRINTER_PAGENUMBERS' both being equal to zero.

See also

Selecting a printer.


PLOT_REDRAW@, SIMPLEPLOT_REDRAW@

Platform | Win32, x64
Purpose | To force a redraw of a %pl.a href="/clearwin+/simplepl/native.htm">native %pl.
Syntax | SUBROUTINE PLOT_REDRAW@() SUBROUTINE SIMPLEPLOT_REDRAW@()
Description | These force a redraw of Simpleplot graphs. PLOT_REDRAW@ must be used when using logarithmic scales with the native %pl and where the plot data has changed.
See also | native %pl, %pl


PRINT_DIB@

Platform | Win32, x64
Purpose | To print a device independent bitmap (dib).
Syntax | INTEGER FUNCTION PRINT_DIB@( UID, PR_X, PR_Y, + PR_WIDTH, PR_HEIGHT, HDIB, X, Y, WIDTH, HEIGHT ) INTEGER UID, PR_X, PR_Y, + PR_WIDTH, PR_HEIGHT, X, Y, WIDTH, HEIGHT INTEGER(7) HDIB
Description | This function is obsolete. New code should use DIB_PRINT@. UID is the user identifier of the printer as supplied to OPEN_PRINTER@. PR_X, PR_Y is the printer offset position to start printing (using the printer resolution). PR_WIDTH, PR_HEIGHT represent the size of the area to print (using the printer resolution). HDIB is the handle of the DIB returned by IMPORT_BMP@, IMPORT_PCX@, GET_SCREEN_DIB@ or CLIPBOARD_TO_SCREEN_BLOCK@. X, Y is the offset position from which to start reading the bitmap WIDTH, HEIGHT represent the size of the bitmap area to print.
Return value | Returns 1 for success or zero for failure.
See also | DIB_PRINT@, DIB_PAINT@, RELEASE_SCREEN_DIB@, EXPORT_BMP@


PRINT_GRAPHICS@

Platform

Win32, x64

Purpose

To simplify the process of printing graphics.

Syntax

INTEGER FUNCTION PRINT_GRAPHICS@(CB)
INTEGER FUNCTION CB()

Description

PRINT_GRAPHICS@ takes one argument which is a user-defined callback function. It calls OPEN_PRINTER@ in order to display the standard open printer dialog, then it calls the callback function and then CLOSE_PRINTER@. For example, PRINT_GRAPHICS@ can be used together with a callback function that uses %pl[external] in order to print a graph. When the callback draws directly to the graphics object (using routines such as DRAW_LINE_BETWEEN@), a call to AUTO_SCALE_FONT@() will automatically scale the font to a reasonable size for the printer resolution. Otherwise CLEARWIN_INFO@ (with "GRAPHICS_WIDTH" and "GRAPHICS_DEPTH") can be called in order to get the pixel width and height and to assign a suitable scaling factor in a call to SCALE_FONT@.

PRINT_GRAPHICS@ automatically sets the default line width (see SET_LINE_WIDTH@) to a value that is reasonable for the printer resolution. It returns zero if CANCEL is selected from the open printer dialog. Otherwise it returns the value returned by the callback function.

Notes

Introduced with FTN95 8.30.

See also AUTO_SCALE_FONT@


PRINT_GRAPHICS_PAGE@

Platform | Win32, x64
Purpose | To print a metafile graphics page.
Syntax | SUBROUTINE PRINT_GRAPHICS_PAGE@
Description | The current metafile image is printed to the graphics printer destination. The page is not cleared and can still be drawn to.
See also | OPEN_METAFILE@, DO_COPIES@


PRINT_OPENGL_IMAGE@

Platform

Win32, x64

Purpose

To print an OpenGL image.

Syntax

INTEGER PRINT_OPENGL_IMAGE@(ID,LEAVE_OPEN)
INTEGER ID
LOGICAL LEAVE_OPEN

Description

ID is the user-defined identification number previously used with OPEN_GL_PRINTER@ or OPEN_GL_PRINTER1@.

LEAVE_OPEN = .TRUE. specifies that the current print job is to be left open as there are more drawings to be sent. LEAVE_OPEN = .FALSE. specifies that the printer connection with this ID is to be closed.

See also

OPEN_GL_PRINTER@, OPEN_GL_PRINTER1@


PROGRESS_BAR@

Platform

Win32, x64

Purpose

To update a %br during a call to DISPLAY_DIB_BLOCK@.

Syntax

SUBROUTINE PROGRESS_BAR@(X)
REAL(2) X

Description

PROGRESS_BAR@ provides a link to a %br progress bar that is to be filled during the call to DISPLAY_DIB_BLOCK@.

For example:

C_EXTERNAL PROGRESS_BAR@ "__progress_bar"(REF)
REAL(2) fill
....
iw = WINIO@('%10br&',fill,255)
....
CALL PROGRESS_BAR@(fill)
CALL DISPLAY_DIB_BLOCK@(...

At the moment PROGRESS_BAR@ is only linked to DISPLAY_DIB_BLOCK@.

Notes

Added to FTN95 at version 8.10


PUT_DIB_BLOCK@

Platform | Win32, x64
Purpose | To save a DIB block in a BMP file (24 bits per pixel) or a JPEG file.
Syntax | SUBROUTINE PUT_DIB_BLOCK@( FILENAME, PARRAY, AW, AH, ADX, + ADY, W, H, NBPP, ERCODE ) CHARACTER(*) FILENAME CHARACTER PARRAY(3,AW,AH) INTEGER AW,AH,ADX,ADY,W,H,NBBP,ERCODE
Description | All of the arguments are input values except for ERCODE which returns the error status. FILENAME is the name of the BMP file. AW and AH are dimensions of PARRAY. ADX and ADY are offsets used when reading the data from PARRAY. W and H are the width and height of the image data to be copied. PARRAY is the same as in GET_DIB_BLOCK@. NBPP is currently not used but should be set to 24 because currently this routine always writes out BMP files with 24 bits per pixel. ERROR will return:

0 | SUCCESS
1 | ERROR ON FILE OPEN
3 | ERROR ON WRITE
13 | BAD NUMBER

 | For JPEG data the file name must have a .jpg or .jpeg extension.
See also | GET_DIB_SIZE@, GET_DIB_BLOCK@, DIB_PAINT@
Example | See Drawing device independent bitmaps.


READ_URL@

Platform

Win32, x64

Purpose

To to read the contents of a URL.

Syntax

SUBROUTINE READ_URL@(URL, FILE, MODE, ERROR)
CHARACTER(*) URL, FILE
INTEGER MODE, ERROR

Description

If this routine succeeds (i.e. an internet connection is available and the URL can be accessed), ERROR is set to zero and the data from the URL is transferred to the specified file (which can be a full path name). If MODE=0, the data is assumed to be text and new lines are converted to DOS style. If MODE=1, binary data is assumed.

The URL can be quite general. In particular, you can use an FTP address assuming anonymous access is possible, or an HTTP address with extra information attached. For example, you could query a search engine directly using this routine.

If you want more control over how the download is controlled you can set a callback for this routine. The callback will be called at a point in the download process at which you can configure the connection. The callback is set via:

SUBROUTINE SET_INTERNET_CB@(cb)
INTEGER,EXTERNAL::cb

When your callback is called you can use SET_INTERNET_PARAM@ to configure the connection. If the callback function returns zero then the primary internet call is aborted.

INTEGER FUNCTION SET_INTERNET_PARAM@(PARAM, VALUE)
INTEGER PARAM,VALUE

PARAM is one of the option flags listed here: https://docs.microsoft.com/en-us/windows/win32/wininet/option-flags. SET_INTERNET_PARAM@ returns the previous value for the given parameter. If VALUE is set to zero then the existing value is returned without setting a new value.

See also

DOWNLOAD@, Linking to the web


RECORD_SOUND@

Platform | Win32, x64
Purpose | To record sound from the sound input device.
Syntax | INTEGER RECORD_SOUND@( LEFT, RIGHT, SAMPLES, FLAG ) INTEGER*2 LEFT(SAMPLES), RIGHT(SAMPLES) INTEGER SAMPLES, FLAG PARAMETER SAMPLES
Description | LEFT and RIGHT are arrays of INTEGER*2 16 bit data . They will be filled with sound data so enough memory should be allocated to them which should be the same value as SAMPLES. FLAG is a return value that is currently unused. You should check the SOUND_PLAYING@ and SOUND_RECORDING@ results so that a call is not made to this routine until the sound device is idle.
Return value | Returns 1 for success or zero on failure.
See also | WRITE_WAV_FILE@, PLAY_SOUND@, SOUND_PLAYING@, SOUND_RECORDING@, PLAY_SOUND_RESOURCE@


RECOVER_DIB_BLOCK@

Platform | Win32, x64
Purpose | To recover a device independent bitmap.
Syntax | SUBROUTINE RECOVER_DIB_BLOCK@( X,Y,PARRAY,AW,AH,AX,AY,W,H, + FUNCTION,MODE,ERCODE ) CHARACTER PARRAY(3,AW,AH) INTEGER X,Y,AW,AH,AX,AY,W,H,FUNCTION,MODE,ERCODE
Description | This routine takes the same arguments as DISPLAY_DIB_BLOCK@, but transfers the image from the current drawing surface to the array.
See also | GET_IM_INFO@, GET_DIB_SIZE@, GET_DIB_BLOCK@, PUT_DIB_BLOCK@, DIB_PRINT@


RELEASE_BITMAP_DC@

Platform | Win32, x64
Purpose | To release a bitmap device context acquired by GET_BITMAP_DC@.
Syntax | SUBROUTINE RELEASE_BITMAP_DC@(HDC) INTEGER(7) HDC
Description | The device context and its associated bitmap are released. This function must not be called whilst a window that uses the device context is still active. HDC is the value returned by a previous call to GET_BITMAP_DC@.
See also | GET_BITMAP_DC@, CLEAR_BITMAP@, %dw


RELEASE_SCREEN_DIB@

Platform | Win32, x64
Purpose | To release the memory for a DIB.
Syntax | SUBROUTINE RELEASE_SCREEN_DIB@( HDIB ) INTEGER(7) HDIB
Description | HDIB is input as the handle of a device independent bitmap created for example by GET_SCREEN_DIB@, IMPORT_BMP@, or CLIPBOARD_TO_SCREEN_BLOCK@.


REMOVE_ACCELERATOR@

Platform | Win32, x64
Purpose | To remove an accelerator key created using %ac or ADD_ACCELERATOR@.
Syntax | SUBROUTINE REMOVE_ACCELERATOR@( HWND, KEY_NAME ) INTEGER(7) HWND CHARACTER(*) KEY_NAME
Description | Removes the key with name KEY_NAME from the window with handle HWND. See ADD_ACCELERATOR@ for further details.
See also | %ac, ADD_ACCELERATOR@


REMOVE_CURSOR_MONITOR@

Platform | Win32, x64
Purpose | To release a call-back function that monitors which window or control has the cursor.
Syntax | SUBROUTINE REMOVE_CURSOR_MONITOR@( CB_FUNC ) EXTERNAL CB_FUNC
Description | See ADD_CURSOR_MONITOR@.


REMOVE_FOCUS_MONITOR@

Platform | Win32, x64
Purpose | To release a call-back function that monitors which window or control has the focus.
Syntax | SUBROUTINE REMOVE_FOCUS_MONITOR@( CB_FUNC ) EXTERNAL CB_FUNC
Description | See ADD_FOCUS_MONITOR@.


REMOVE_GRAPHICS_ICON@

Platform | Win32, x64
Purpose | To remove an icon from a %gr drawing surface.
Syntax | SUBROUTINE REMOVE_GRAPHICS_ICON( HANDLE ) INTEGER(7) HANDLE
Description | HANDLE is the value returned by an earlier call to ADD_GRAPHICS_ICON@.
See also | ADD_GRAPHICS_ICON@


REMOVE_KEYBOARD_MONITOR@

Platform | Win32, x64
Purpose | To release a call-back function that monitors the use of the keyboard.
Syntax | SUBROUTINE REMOVE_KEYBOARD_MONITOR@( CB_FUNC ) EXTERNAL CB_FUNC
Description | See ADD_KEYBOARD_MONITOR@.


REMOVE_MENU_ITEM@

Platform | Win32, x64
Purpose | Removes a dynamically attached %mn menu item.
Syntax | SUBROUTINE REMOVE_MENU_ITEM@( HANDLE ) INTEGER(7) HANDLE
Description | Use this routine to remove the last menu item that was previously been attached with a call to ADD_MENU_ITEM@ (see ).
See also | ADD_MENU_ITEM@


REPLACE_ENHANCED_MENU@

Platform | Win32, x64
Purpose | To replace an enhanced menu.
Syntax | SUBROUTINE REPLACE_ENHANCED_MENU@(HANDLE, MENU) INTEGER(7) HANDLE CHARACTER(*) MENU
Description | See Enhanced menus .


REPLACE_ENHANCED_POPUP_MENU@

Platform | Win32, x64
Purpose | To replace an enhanced popup menu.
Syntax | SUBROUTINE REPLACE_ENHANCED_POPUP_MENU@(HANDLE, MENU) INTEGER(7) HANDLE CHARACTER(*) MENU
Description | See Enhanced menus .


REPLY_TO_TEXT_MESSAGE@

Platform | Win32, x64
Purpose | To reply to a message from an application that uses SEND_TEXT_MESSAGE@.
Syntax | SUBROUTINE REPLY_TO_TEXT_MESSAGE@( REPLY ) CHARACTER(*) REPLY
Description | This routine can be used within a call-back function associated with %rm. The message and reply can be up to 255 characters long.
See also | %nc, %rm, SEND_TEXT_MESSAGE@


RESIZE_WINDOW@

Platform | Win32, x64
Purpose | To resize a window given its window handle.
Syntax | SUBROUTINE RESIZE_WINDOW@( HWND, WIDTH, HEIGHT ) INTEGER(7) HWND INTEGER WIDTH, HEIGHT
Description | HWND is typically a value obtained by using %hw or %lc. WIDTH and HEIGHT are input as the new size of the window in pixels. See GET_WINDOW_LOCATION@ and its associated notes.
See also | MOVE_WINDOW@


RGB@

Platform | Win32, x64
Purpose | To pack 8-bit colour values into a 32-bit integer.
Syntax | INTEGER FUNCTION RGB@(RED,GREEN,BLUE) INTEGER RED,GREEN,BLUE
Description | This function is equivalent to the Windows API macro called RGB. It takes colour values in the range 0 to 255 and packs them into the 24 least significant bits of a 32 bit integer. GREEN is shifted left 8 bits and BLUE is shifted left 16 bits. RGB values are used in drawing routines when RGB colour mode is adopted.
Return value | Returns the packed RGB values.


ROTATE_FONT@

Platform | Win32, x64
Purpose | To rotate the font being used on the current drawing surface.
Syntax | SUBROUTINE ROTATE_FONT@( ROT ) DOUBLE PRECISION ROT
Description | This routine will rotate the selected font about the bottom left-hand corner of the text. The rotation is anti-clockwise and ROT is specified in degrees.
See also | ITALIC_FONT@, SCALE_FONT@, SELECT_FONT@, UNDERLINE_FONT@, BOLD_FONT@


SCALE_FONT@

Platform

Win32, x64

Purpose

To scale the font being used on the current drawing surface.

Syntax

SUBROUTINE SCALE_FONT@( SIZE )
DOUBLE PRECISION SIZE

Description

Rescales the font being used on the current drawing surface.

The scaling involves integer truncation and so is only approximate. A more accurate result may be given by SCALE_FONT1@. This routine uses rounding rather than truncation but is otherwise the same as SCALE_FONT@.

Because of their approximate nature, these functions should not be used in succession and it is recommended that a routine such as SIZE_IN_PIXELS@ be used from time to time in order to set a base size.

Alternatively the subroutine UNSCALE_FONT@(), which takes no arguments, may be called in order to undo the immediately previous call to SCALE_FONT@ or SCALE_FONT1@.

See also

ROTATE_FONT@, SELECT_FONT@, UNDERLINE_FONT@, ITALIC_FONT@, BOLD_FONT@


SCC_LIB_VERSION@

Platform

Win32, x64

Purpose

To get a sequence number for the user's ClearWin+ library.

Syntax

INTEGER FUNCTION SCC_LIB_VERSION@( )

Description

This function returns an integer that is derived from the DATE/TIME at which the library was built (by Silverfrost). This number is guaranteed to increase monotonically with every new release of the library.

The function can be used to avoid problems that can occur when the version of ClearWin+ on a user's machine is older than that on the developer's machine (for example the code might use a function that is not present in an older library).

You can store the value returned by this function on your machine (as a known integer constant) and include a call to this function in the program code to get the corresponding value on a user's machine. An error condition can be triggered if the user's value is less than your constant value.


SCROLL_GRAPHICS@

Platform

Win32, x64

Purpose

To scroll an area of the current drawing surface.

Syntax

SUBROUTINE SCROLL_GRAPHICS@( DX, DY, LEFT, TOP,
+ RIGHT, BOTTOM, SWITCH, COLOUR )
INTEGER DX, DY, LEFT, TOP, RIGHT, BOTTOM, SWITCH,
+ COLOUR

Description

This routine allows you to scroll an area the drawing surface. The direction of scrolling is set by the two variables DX and DY. They represent the displacement the image will be copied to. For DX, values less than 0 will move the image left and values greater than 0 will move the image right by the relevant number of pixels. For DY, values less than 0 will move the image up and values greater then 0 will move the image down by the relevant number of pixels.

The LEFT, TOP, RIGHT, BOTTOM arguments define the area to be moved. This can be the whole surface or a sub region within the whole.

SWITCH can either be set to 0 or 1. If it is set to 1 then the area that becomes invalid is set to the COLOUR specified by the final argument (using the current colour mode). If it is 0 then the invalid region is left unchanged. You should note that this is a copy routine not a move and the region of the screen that is not copied will not be automatically modified.

See also

SELECT_GRAPHICS_OBJECT@, COPY_GRAPHICS_REGION@,
CREATE_GRAPHICS_REGION@, NEW_GRAPHICS_REGION@, DELETE_GRAPHICS_REGION@


SEE_PROPERTYSHEET_PAGE@

Platform | Win32, x64
Purpose | To set the sheet number for %ps.
Syntax | SUBROUTINE SEE_PROPERTYSHEET_PAGE@( SHEET_N ) INTEGER SHEET_N
Description | See %ps.


SEE_TREEVIEW_SELECTION@

Platform

Win32, x64

Purpose

To ensure that the current %tv item is visible.

Syntax

SUBROUTINE SEE_TREEVIW_SELECTION@( POINT )
INTEGER POINT

Description

This routine ensures that the treeview (defined by %tv in Tree-view) is opened showing the current selection. The argument is the current selection integer (not the array of descriptions). This function may be of most use if called via a call-back attached to %sc, thus providing a once only update.

Note that you should ensure that all the appropriate nodes in the hierarchy are marked as expanded ('E') in order to make the selected item visible.


SELECT_FONT@

Platform

Win32, x64

Purpose

To select a new font for a drawing surface.

Syntax

SUBROUTINE SELECT_FONT@( FONTNAME )
CHARACTER(*) FONTNAME

Description

FONTNAME becomes the font for the current drawing surface. The default size is not changed. The font can be set to any currently enabled Windows fonts (see the relevant Windows font manager). Care should be taken when selecting fonts since fonts that are available on one machine may not be available on another.

FONTNAME could be a user-added Windows font or 'SYSTEM FIXED FONT' (this font is used for output to a ClearWin window) or 'SYSTEM FONT' (this is the Windows SYSTEM_FONT parameter or, under Windows 95, the DEFAULT_GUI_FONT parameter and is used in some ClearWin+ controls).

Notes

The default Charset value (see FONT_METRICS@) for Courier New is ANSI_CHARSET. By using /OEM after the name of the font ('Courier New/OEM') it is possible to choose OEM_CHARSET.

See also

ROTATE_FONT@, SCALE_FONT@, ITALIC_FONT@, UNDERLINE_FONT@, BOLD_FONT@


SELECT_FONT_ID@

Platform | Win32, x64
Purpose | To set the font for the current drawing surface.
Syntax | INTEGER FUNCTION SELECT_FONT_ID@( ID ) INTEGER(7) ID
Description | ID is a value returned by an earlier call to GET_FONT_ID@.
Return value | Returns 1 for success or zero on failure.
See also | CHOOSE_FONT@, GET_FONT_ID@


SELECT_GRAPHICS_OBJECT@

Platform | Win32, x64
Purpose | To select the current drawing surface.
Syntax | INTEGER FUNCTION SELECT_GRAPHICS_OBJECT@( UID ) INTEGER UID
Description | Drawing surfaces are created by %gr, OPEN_PRINTER@ etc. and CREATE_GRAPHICS_REGION@. UID is a value that is supplied to %`gr, or OPEN_PRINTER@ etc.. ClearWin+ drawing routines are applied to the current drawing surface. Call this function if there is more than one drawing surface in order to draw on a surface that is not the current one. This is an alternate function to SELECT_GRAPHICS_REGION@.
Return value | The value 1 is returned for success or zero for failure (invalid identifier).


SELECT_GRAPHICS_REGION@

Platform | Win32, x64
Purpose | To select the current drawing surface.
Syntax | INTEGER FUNCTION SELECT_GRAPHICS_REGION@( HANDLE ) INTEGER(7) HANDLE
Description | Drawing surfaces are created by %gr, OPEN_PRINTER@ etc. and CREATE_GRAPHICS_REGION@. HANDLE is a value that is supplied to %gr or %pl via the [handle] option. HANDLE can also be obtaind by calling GET_CURRENT_GRAPHICS_REGION@ immediately after calling CREATE_GRAPHICS_REGION@ or immediately after a winio("%gr&"...) OPEN_PRINTER@ etc.. ClearWin+ drawing routines are applied to the current drawing surface. Call this function if there is more than one drawing surface in order to draw on a surface that is not the current one. This is an alternate function to SELECT_GRAPHICS_OBJECT@.
Return value | The value 1 is returned for success or zero for failure (invalid identifier).


SELECT_PRINTER@

Platform

Win32, x64

Purpose

To configure and select the active printer.

Syntax

INTEGER FUNCTION SELECT_PRINTER@( DEV, PORT )
CHARACTER(*) DEV, PORT

Description

A call to SELECT_PRINTER@ will provide a standard Windows dialog box from which the user is able to select and configure any of the attached printer devices.

On return DEV will contain the name of the printer device that has been selected and PORT will contain the name of the port it is connected to.

A character array of size 256, in each case, should be sufficient to hold the returned data.

Return value

Returns 1 for success or zero if the user clicked on the CANCEL button.

See also

OPEN_PRINTER@, CLOSE_PRINTER@

Example

PORT LPT1: , COM3: , FAX: ...


SEND_TEXT_MESSAGE@

Platform

Win32, x64

Purpose

To send a message to an application that uses %rm.

Syntax

INTEGER FUNCTION SEND_TEXT_MESSAGE@( CLASS_NAME,
+ MESSAGE, REPLY)
CHARACTER(*) CLASS_NAME,MESSAGE,REPLY

Description

This function sends a text string of up to 255 characters to a window with the given class name. The recipient window will normally use the %nc format to give its class a specific name. The recipient will also use the %rm format (which takes one call-back argument) to supply a call-back function to handle the message. The call-back function can call CLEARWIN_STRING@('MESSAGE_TEXT') to obtain the message. To send a reply, the call-back function should call REPLY_TO_TEXT_MESSAGE@. Since the message and reply can be up to 255 characters long, they can hold considerable amounts of information.

Notes

a) Every message requires by its very nature a context switch from the transmitter application to the receiver. Under Win32 this is quite slow therefore large amounts of information are best transmitted in a file, sending just a short message to transmit the file name. Bearing in mind that file accesses are normally cached, this method can be quite efficient.

b) One use for inter-process communication is particularly common under Win32. It is possible to start several copies of a Win32 application. Often the user does not really want several independent copies of your application running simultaneously. Suppose, for example that a MDI editor MYEDIT is already running and the user issues the command:

MYEDIT filename

What is probably required is to open the file in the editor that is already running. To achieve this it is first necessary to uniquely identify the main window of your application. This is done using the %nc format to give the window a distinctive class name. The window should also use the %rm format to supply a routine to handle messages. Before the main window is created the program should call SEND_TEXT_MESSAGE@ to send the name of the file to another copy of the editor if one is running. If this function returns 1 for success the current program can be terminated in the knowledge that the file has been transmitted to another active version of the application.

Return value

Returns 1 for success, otherwise zero if no window with the given class name was found.


SET_ALL_MAX_LINES@

Platform | Win32, x64
Purpose | To set the maximum number of lines to be stored for all ClearWin windows.
Syntax | SUBROUTINE SET_ALL_MAX_LINES@(N) INTEGER N
Description | This routine is the same as SET_MAX_LINES@ but applies to all ClearWin windows.


SET_CD_POSITION@

Platform | Win32, x64
Purpose | To set the position of the CD read head to TRACK + MILLISECONDS (offset).
Syntax | INTEGER SET_CD_POSITION@( TRACK, MILLISECONDS ) INTEGER TRACK, MILLISECONDS
Description | The CD read head will be moved to the track plus the number of specified milliseconds into that track. The first track number is 1 rather than 0.
Return value | Returns 1 for success or zero on failure.
See also | CLOSE_CD_TRAY@, OPEN_CD_TRAY@, PLAY_AUDIO_CD@, STOP_AUDIO_CD@, GET_TRACK_LENGTH@


SET_CLEARWIN_FLOAT@

Platform | Win32, x64
Purpose | To set or change a floating point value associated with a named string.
Syntax | SUBROUTINE SET_CLEARWIN_FLOAT@( STRING, VALUE ) CHARACTER(*) STRING DOUBLE PRECISION VALUE
Description | This routine will create and assign a value to a private named parameter that can be retrieved using CLEARWIN_FLOAT@. User defined parameters can be very useful to communicate information between modules in a program (especially between DLLs under Win32). This function cannot be used to set system CLEARWIN_FLOAT@ values.
See also | CLEARWIN_FLOAT@


SET_CLEARWIN_INFO@

Platform | Win32, x64
Purpose | To set or change an integer value associated with a named string.
Syntax | SUBROUTINE SET_CLEARWIN_INFO@( STRING, VALUE ) CHARACTER(*) STRING INTEGER VALUE
Description | This function will create and assign a value to a private named parameter that can be retrieved using CLEARWIN_INFO@. User defined parameters can be very useful to communicate information between modules in a program (especially between DLLs under Win32). This function cannot be used to set system CLEARWIN_INFO@ values except for the printer dialog parameters described in Customising the printer dialog box.
See also | CLEARWIN_INFO@


SET_CLEARWIN_STRING@

Platform

Win32, x64

Purpose

To set or change a string value associated with a named string.

Syntax

SUBROUTINE SET_CLEARWIN_STRING( STRING, VALUE )
CHARACTER(*) STRING, VALUE

Description

This function will create and assign a value to a private named parameter that can be retrieved using CLEARWIN_STRING@. User defined parameters can be very useful to communicate information between modules in a program (especially between DLLs under Win32). This function should not be used to set system CLEARWIN_STRING@ values except for:

PRINTER_DOCUMENT

This is the name of the document that is about to be printed. Its default value is "ClearWin+ Output".

See also

CLEARWIN_STRING@


SET_CLEARWIN_STYLE@

Platform | Win32, x64
Purpose | Modifies the default styling controls for ClearWin (%cw) windows.
Syntax | INTEGER FUNCTION SET_CLEARWIN_STYLE@( NEWSTYLE ) INTEGER NEWSTYLE
Description | The default style for a format window is (WS_OVERLAPPEDWINDOW + WS_HSCROLL + WS_VSCROLL). This can be changed to any valid combination of Windows styles contained in the windows.ins file so that any subsequent widows have a new style.

WS_OVERLAPPED | WS_POPUP
WS_CHILD | WS_CLIPSIBLINGS
WS_CLIPCHILDREN | WS_VISIBLE
WS_DISABLED | WS_MINIMIZE
WS_MAXIMIZE | WS_CAPTION
WS_BORDER | WS_DLGFRAME
WS_VSCROLL | WS_HSCROLL
WS_SYSMENU | WS_THICKFRAME
WS_MINIMIZEBOX | WS_MAXIMIZEBOX
WS_GROUP | WS_TABSTOP
WS_OVERLAPPEDWINDOW | WS_POPUPWINDOW
WS_CHILDWINDOW | WS_EX_DLGMODALFRAME
 | WS_EX_NOPARENTNOTIFY

Return value

The previous settings are returned and should be stored if the effect you wish to generate is only temporary.


SET_CONTROL_BACK_COLOUR@

Platform

Win32, x64

Purpose

To change the background colour of a control after a window/dialog has been created.

Syntax

SUBROUTINE SET_CONTROL_BACK_COLOUR@(HWND,COLOUR)
INTEGER(7) HWND
INTEGER COLOUR

Description

HWND is the window handle of the control obtained by using %lc. COLOUR is the RGB colour value (see RGB@).

See also

SET_CONTROL_TEXT_COLOUR@

Notes

Unless the colour is to be varied you can set the background colour of a control using %`bg before the control when the window is created.

A call to SET_CONTROL_BACK_COLOUR@ can be made in the callback function for the control in question.


SET_CONTROL_TEXT_COLOUR@

Platform

Win32, x64

Purpose

To change the text colour of a control after a window/dialog has been created.

Syntax

SUBROUTINE SET_CONTROL_TEXT_COLOUR@(HWND,COLOUR)
INTEGER(7) HWND
INTEGER COLOUR

Description

HWND is the window handle of the control obtained by using %lc. COLOUR is the RGB colour value (see RGB@).

See also

SET_CONTROL_BACK_COLOUR@

Notes

Unless the colour is to be varied you can set the text colour of a control using %tc before the control when the window is created, possibly followed by another %tc to reset it after the control has been specified.

A call to SET_CONTROL_TEXT_COLOUR@ can be made in the callback function for the control in question. This means, for example, that it is possible to construct a control that displays text in red for negative values and black for positive values.


SET_CONTROL_VISIBILITY@

Platform | Win32, x64
Purpose | To show or hide a control or window.
Syntax | SUBROUTINE SET_CONTROL_VISIBILITY@(HWND,SHOW) INTEGER(7) HWND INTEGER SHOW
Description | HWND is the window handle obtained by using %lc or %hw. SHOW is set to 1 to show the window or 0 to hide it. This routine provides the same functionality as the API function ShowWindow but also performs certain necessary housekeeping internal to ClearWin+. It is therefore preferred to ShowWindow.


SET_CURSOR_WAITING@

Platform | Win32, x64
Purpose | To produce a temporary hour-glass cursor.
Syntax | SUBROUTINE SET_CURSOR_WAITING@( WAIT ) INTEGER WAIT
Description | If WAIT is set to a non-zero value, the routine changes the cursor to an hour-glass with immediate effect. A zero value then causes the previous cursor to be restored, again with immediate effect.


SET_DASH_ARRAY@

Platform | Win32, x64
Purpose | To define the line pattern for a line on the current drawing surface.
Syntax | SUBROUTINE SET_DASH_ARRAY@( ARR, SIZE ) DOUBLE_PRECISION ARR(*) INTEGER SIZE
Description | ARR is an array of lengths and 'SIZE' is the number of elements in this array. The first element of ARR is the length of the first dash as a multiple of the current line width. The second is the length of the following space and so on. 'SIZE' indicates when the pattern repeats. When using this routine, only the end cap styles in SET_LINE_STYLE@ have any effect and then only when the line width is greater than 1. If SET_LINE_STYLE@ is called after this routine then PS_USERSTYLE must be included with the end cap style. A call to SET_LINE_STYLE@(PS_SOLID) restores the default line style.
Notes | Introduced with FTN95 7.00.
See also | SET_LINE_WIDTH@


SET_DEFAULT_FONT@

Platform | Win32, x64
Purpose | To set the default standard I/O font for ClearWin windows.
Syntax | SUBROUTINE SET_DEFAULT_FONT@(HFONT) INTEGER(7) HFONT
Description | This routine is not suitable for format windows. It sets the default standard I/O font for ClearWin windows to HFONT. HFONT must be the handle to an existing font which can for example be obtained by calling the CreateFont Windows API function.
Note | Any font changes will affect only those ClearWin windows subsequently created. If you wish to change the default font for all ClearWin windows then this can only be achieved by calling one of the ClearWin+ set-font functions before any windows are created or any standard I/O is performed.


SET_DEFAULT_PROPORTIONAL_FONT@

Platform | Win32, x64
Purpose | To set the default standard I/O font for ClearWin windows to "System".
Syntax | SUBROUTINE SET_DEFAULT_PROPORTIONAL_FONT@()
Description | This routine is not suitable for format windows. The font is proportionally spaced. You can revert to a mono spaced font by using SET_DEFAULT_TO_FIXED_FONT@.


SET_DEFAULT_TO_FIXED_FONT@

Platform | Win32, x64
Purpose | To reset the default standard I/O font for ClearWin windows to "System Fixed".
Syntax | SUBROUTINE SET_DEFAULT_TO_FIXED_FONT@()
Description | This routine is not suitable for format windows. The font is mono-spaced. You can set the font to a proportional font using SET_DEFAULT_PROPORTIONAL_FONT@.


SET_DEFAULT_WINDOW@

Platform

Win32, x64

Purpose

To set the default ClearWin window for standard I/O.

Syntax

INTEGER(7) FUNCTION SET_DEFAULT_WINDOW@(HWND)
INTEGER(7) HWND

Description

All future standard I/O requests will be directed to this window. HWND is a handle created by CREATE_WINDOW@.

Return value

Returns the handle of the previous default window.


SETDPIAWARENESS@

Platform

Win32, x64

Purpose

To instruct ClearWin+ to modify the settings for DPI awareness available in Windows 8.1 and above.

Syntax

INTEGER SETDPIAWARENESS@(VALUE)
INTEGER VALUE

Description

ClearWin+ now makes use of the "DPI awareness" features first available with Windows 8.1. This means that, where possible, ClearWin+ will take advantage of the Windows API features designed to handle high DPI display settings which otherwise can lead to clipped text and blurry images.

This means that, where possible, ClearWin+ now makes the call "SetProcessDpiAwareness(Process_System_DPI_Aware)" in its initialisation process. Programmers who need to use values other than Process_System_DPI_Aware (which has the value 1) can do so via this function.

VALUE should take one of the following:

  • 0 - DPI unaware - the default for before Windows 8.1. This app does not scale for DPI changes and is always assumed to have a scale factor of 100% (96 DPI). It will be automatically scaled by the system on any other DPI setting.
  • 1 - System DPI aware - the ClearWin+ default for Windows 8.1 and above. This app does not scale for DPI changes. It will query for the DPI once and use that value for the lifetime of the app. If the DPI changes, the app will not adjust to the new DPI value. It will be automatically scaled up or down by the system when the DPI changes from the system value.
  • 2 - Per monitor DPI aware. This app checks for the DPI when it is created and adjusts the scale factor whenever the DPI changes. These applications are not automatically scaled by the system.

The Windows API function SETDPIAWARENESS@ is only effective on its first call so a call to SETDPIAWARENESS@ must be placed before any other calls to the ClearWin+ library.

Return value

0 - success
z'80004001' (E_NOTIMPL), OS does not support function
z'80070057' (E_INVALIDARG), Invalid value
z'80070005' (E_ACCESSDENIED), if the awareness value has already been set

Notes

Added to FTN95 at version 7.10


SET_FLOAT_LIMITS@

Platform | Win32, x64
Purpose | To change the limits of a %fl control.
Syntax | SUBROUTINE SET_FLOAT_LIMITS@(HWND, MIN, MAX) INTEGER(7) HWND DOUBLE PRECISION MIN,MAX
Description | Calling SET_FLOAT_LIMITS@ will change the current limits on the %fl control which has the handle HWND. The handle can be found by using the %lc format. The new limits will be MAX and MIN. If the current data is outside of the new limits then a "refresh" should be generated. For example, the callback function that calls this routine should return the value 1 rather than 2.
Notes | Added to FTN95 at version 7.10


SET_OPACITY@

Platform | Win32, x64
Purpose | To set the opacity for future drawing operations.
Syntax | SUBROUTINE SET_OPACITY( OPACITY ) INTEGER OPACITY
Description | SET_OPACITY@ enables programmers to set the alpha value for colours. A value for Opacity in the range 0-255 inclusive, sets this as the default value for the current drawing surface and activates the GDI+ library. 255 is fully opaque - colours without an opacity value can be considered having an opacity of 255. A value of 256 (the initial default) indicates that the GDI+ library is not to be used. This function returns the previous opacity value. With the function and SET_SMOOTHING_MODE@, standard ClearWin+ drawing routines like DRAW_LINE_BETWEEN@ and DRAW_CHARACTERS@ can be used without change.
Notes | Introduced with FTN95 7.00.
See also | Using GDI+, USE_GDIPLUS@, nARGB@


SET_GRAPHICS_SELECTION@

Platform | Win32, x64
Purpose | To select a 'rubber-band' mode for a %gr region.
Syntax | SUBROUTINE SET_GRAPHICS_SELECTION@( MODE ) INTEGER MODE
Description | MODE can be any of the following:

0 | No selection
1 | A rectangular box is drawn whilst the left mouse button is mouse is held down.
2 | A straight line is drawn whilst the left mouse button is mouse is held down.
3 | Extended cross hairs are drawn whenever the cursor is in the graphics region.
4 | Like MODE = 1 but the box is invisible.

This routine is used when mouse input is processed within a %gr drawing surface. It remains local to the current drawing surface selected with SELECT_GRAPHICS_OBJECT@.

Mode 1 makes a box appear whenever the left mouse button is pressed. The corner of the box will stay anchored to that point until the mouse button is released. The other corner will follow the mouse cursor around the drawing surface until the mouse button is released. By processing the mouse state and the released information it is possible to determine the co-ordinates of the selected region.

Mode 2 is similar to mode 1 but a straight line joins the first point to the second whilst the left mouse button is held down.

Mode 0 deactivates the box and line high-lighting mechanism. All the lines are drawn on to and removed from the display with an XOR write which prevents the destruction of any underlying graphics.

It is important to note that you should only call this routine once for each line mode change required.

See also

GET_GRAPHICS_SELECTED_AREA@

Example

See Graphics selections.


SET_HIGHLIGHTED@

Platform | Win32, x64
Purpose | To select all of the text in a %rd, %rf or %rs edit box.
Syntax | SUBROUTINE SET_HIGHLIGHTED@(HWND) INTEGER(7) HWND
Description | HWND is the window handle of the edit box obtained by using %lc.
See also | %rd, %rf, %rs


SET_INTEGER_LIMITS@

Platform | Win32, x64
Purpose | To change the limits of a %il control.
Syntax | SUBROUTINE SET_INTEGER_LIMITS@(HWND, MIN, MAX) INTEGER(7) HWND INTEGER MIN,MAX
Description | Calling SET_INTEGER_LIMITS@ will change the current limits on the %il control which has the handle HWND. The handle can be found by using the %lc format. The new limits will be MAX and MIN. If MAX is equal to MIN then the control becomes read-only. If the current data is outside of the new limits then a "refresh" should be generated. For example, the callback function that calls this routine should return the value 1 rather than 2.
Notes | Added to FTN95 at version 7.10


SET_LINE_STYLE@

Platform

Win32, x64

Purpose

To set the style for a line on the current drawing surface.

Syntax

SUBROUTINE SET_LINE_STYLE@( VALUE )
INTEGER VALUE

Description

This routine changes the line style on the current drawing surface. VALUE is one of the following predefined Windows constants (available from the file windows.ins):

PS_SOLID | solid line
PS_DASH | dashed line
PS_DOT | dotted line
PS_DASHDOT | alternating dashes and dots
PS_DASHDOTDOT | alternating dashes and double dots
PS_NULL | pen is invisible
PS_INSIDEFRAME | the dimensions of a figure are reduced so that it fits entirely in the bounding rectangle, taking into account the width of the pen.

The following "endcap" styles must be combined with the PS_GEOMETRIC style.

PS_ENDCAP_ROUND | lines have a rounded end
PS_ENDCAP_SQUARE | lines have a square end
PS_ENDCAP_FLAT | lines have a flat end

Notes

PS_INSIDEFRAME can be ORed with one of the other values.

PS_SOLID, PS_NULL and PS_INSIDEFRAME are only available with a line width greater than 1.

PS_NULL can be used to remove the black border when printing a 'filled polygon', for example, on a black and white printer.

See also

SET_LINE_WIDTH@, SET_DASH_ARRAY@, SET_MITER_LIMIT@


SET_LINE_WIDTH@

Platform | Win32, x64
Purpose | To set the line width on the current drawing surface.
Syntax | SUBROUTINE SET_LINE_WIDTH@( VALUE ) INTEGER VALUE
Description | Changes the pixel thickness of a line when drawing on a drawing surface. The default value is 1.
See also | SET_LINE_STYLE@, SET_DASH_ARRAY@


SET_MAX_LINES@

Platform | Win32, x64
Purpose | To set the maximum number of lines to be stored for a given ClearWin window.
Syntax | SUBROUTINE SET_MAX_LINES@(HWND,N) INTEGER(7) HWND INTEGER N
Description | Sets a maximum to the number of lines of output (N > 50) that is to be stored by the ClearWin window with handle HWND. Before storing line N +1, line 1 is deleted etc..


SET_MAX_DIALOG_SIZE@

Platform | Win32, x64
Purpose | To increase the maximum dimensions for fixed sized winio@ windows.
Syntax | SUBROUTINE SET_MAX_DIALOG_SIZE@( WIDTH, HEIGHT ) INTEGER WIDTH, HEIGHT
Description | The default maximum of 1280x1280 pixels can be increased by a call to this routine. WIDTH and HEIGHT are input as pixel values and must be large enough for the largest window that will subsequently be created using winio@.


SET_MITER_LIMIT@

Platform | Win32, x64
Purpose | change the miter limit for the PS_JOIN_MITER style..
Syntax | INTEGER FUNCTION SET_MITER_LIMIT@(LIMIT) INTEGER LIMIT
Description | The default ClearWin+ limit is 4. This function sets a new limit and returns the previous limit.
Notes | Introduced with FTN95 7.00.
See also | SET_LINE_STYLE@, SET_DASH_ARRAY@, SetMiterLimit Windows API


SET_MOUSE_CURSOR_POSITION@

Platform | Win32, x64
Purpose | To set the position of the mouse with respect to a given window.
Syntax | SUBROUTINE SET_MOUSE_CURSOR_POSITION@( HWND, X, Y ) INTEGER(7) HWND INTEGER X, Y
Description | HWND is the handle of window, X is the x position relative to the window, and Y is the y position relative to the window. If HWND is zero, the positioning is relative to the top left-hand corner of the screen itself.


SET_OLD_RESIZE_MECHANISM@

Platform

Win32, x64

Purpose

To revert to the old ClearWin+ resizing strategy.

Syntax

SUBROUTINE SET_OLD_RESIZING_MECHANISM@( )

Description

In the original ClearWin+ specification you could create windows which would re-size without any control changing its dimensions. This happened if you used %ww but either did not use a pivot (%pv), or applied a pivot to a control which could not use it.

To obtain the old specification you should call SET_OLD_RESIZE_MECHANISM@. The new scheme is described in Pivot.


SET_OPEN_DIALOG_PATH@

Platform | Win32, x64
Purpose | To set the initial directory before displaying the standard file open dialog box.
Syntax | SUBROUTINE SET_OPEN_DIALOG_PATH@( PATH )
See also | %fs, %ft, GET_FILTERED_FILE@


SET_PRINTER_ORIENTATION@

Platform | Win32, x64
Purpose | To set the printer orientation to portrait or landscape.
Syntax | SUBROUTINE SET_PRINTER_ORIENTATION@( V ) INTEGER V
Description | This routine can be called before OPEN_PRINTER@ and OPEN_PRINTER1@ or before using one of the standard call-back functions 'PRINTER_SELECT', 'PRINTER_OPEN', or 'PRINTER_OPEN1'. Set V = 0 for portrait and V = 1 for landscape.


SET_RGB_COLOURS_DEFAULT@

Platform | Win32, x64
Purpose | To set the global default to either RGB or VGA colour mode.
Syntax | SUBROUTINE SET_RGB_COLOURS_DEFAULT@( BOOL ) INTEGER BOOL
Description | By default ClearWin+ operates in RGB colour mode. The alternative is VGA colour mode in which colours are represented by palette index values. RGB colour mode is recommended for new programs but this routine can be used to change to VGA colours when preferred. USE_RGB_COLOURS@ is similar but relates to a given drawing surface. See Graphics format for further details. Use an input value of zero to change the default to VGA colour mode.
See also | USE_RGB_COLOURS@, %gr[rgb_colours]


SET_SMOOTHING_MODE@

Platform

Win32, x64

Purpose

To set the GDI+ smoothing mode for the current drawing surface.

Syntax

INTEGER FUNCTION SET_SMOOTHING_MODE@(MODE)
INTEGER MODE

Description

This function returns the previous mode and sets the new mode for the current drawing surface in the range 0-5 inclusive with the following outline:

           SmoothingModeDefault      = 0 (no smoothing)
           SmoothingModeHighSpeed    = 1 (no smoothing)
           SmoothingModeHighQuality  = 2 (8x4 box filter)
           SmoothingModeNone         = 3 (no smoothing)
           SmoothingModeAntiAlias8x4 = 4 (8x4 box filter)
           SmoothingModeAntiAlias8x8 = 5 (8x8 box filter)

Smoothing performed by an 8 X 4 box filter gives better results for nearly vertical lines than it does for nearly horizontal lines. Smoothing performed by an 8 X 8 box filter gives equally good results for nearly vertical and nearly horizontal lines. The 8x8 algorithm produces higher quality smoothing but is slower than the 8 X 4 algorithm.

Note that, if the current opacity is 256 then calling SET_SMOOTHING_MODE@ will set the opacity to 255 to activate the GDI+ library.

%gr[smooth4] sets the opacity to 255 and the smoothing mode to 4.
%gr[smooth8] sets the opacity to 255 and the smoothing mode to 5.

Notes

Introduced with FTN95 7.00.

See also

Using GDI+, SET_OPACITY, USE_GDIPLUS, nARGB@


SET_SOUND_SAMPLE_RATE@

Platform

Win32, x64

Purpose

To set the sampling speed.

Syntax

SUBROUTINE SET_SOUND_SAMPLE_RATE@( RATE )
INTEGER RATE

Description

The sampling rate is the frequency at which the sound sample will be played back or recorded. Do not change this value whilst SOUND_PLAYING@ or SOUND_RECORDING@ return a value of 1. The maximum value that is permissible is dependant of the sound device being used and you should consult the relevant technical notes supplied with it. Common Windows values are maximum 44100 (44.1KHz), midrange 22050 (22.05khz) and minimum 11025 (11.025khz) - also the default. It should also be noted that there will be an absolute minimum. There is no sense in recording at anything less than 8000 (Hz), which is approximately the same sample rate as a telephone connection, as the recording quality would be too low for practical use.

When selecting a suitable value it should also be noted that the sample rate must be set to twice that of the maximum frequency you wish to record, this is to preserve quality and reduce alias distortion.

For example:

If the maximum frequency to be recorded is 10khz (10000) then the sample rate must be set to 20Khz (20000).

Note that this will require a large of amount storage.

See also

WRITE_WAV_FILE@, PLAY_SOUND@, SOUND_PLAYING@,
PLAY_SOUND_RESOURCE@, SOUND_RECORDING@,
SOUND_SAMPLE_RATE@


SET_UPDATE_RECTANGLE@

Platform | Win32, x64
Purpose | To inform ClearWin+ when a rectangle has been updated by a direct call to an API graphics function.
Syntax | SUBROUTINE SET_UPDATE_RECTANGLE@( X1, Y1, X2, Y2 ) INTEGER X1, Y1, X2, Y2
Description | See updating the screen.
See also | GET_CURRENT_DC@


SET_USER_DATA@

Platform

Win32, x64

Purpose

To set the location of user data associated with the control.

Syntax

SUBROUTINE SET_USER_DATA@(HWND, LOCDATA)
INTEGER(7) HWND
INTEGER(7) LOCDATA

Description

HWND is the window handle of the control obtained by using %lc. LOCDATA is an INTEGER(7) that is associated with the control. This can be the address of a memory location or just an integer. The data stored is up to the programmer. The data is retrieved either by using GET_USER_DATA@ or by using CLEARWIN_INFO@('USER_DATA') inside a callback for the control. The data can also be stored via the %ud format code.

See also

%ud, GET_USER_DATA@

Notes

 To pass the location of of a variable or or array use the LOC intrinsic.


SHOW_MOVIE@

Platform

Win32, x64

Purpose

To show a video.

Syntax

SUBROUTINE SHOW_MOVIE@(FILE,OPT)
INTEGER OPT
CHARACTER(*) FILE

Description

SHOW_MOVIE@ opens the given .AVI file and shows it in a window. If OPT is zero, the user must click the play button to start the movie. If OPT is 1, the movie starts immediately. Do not call this routine with a file which does not exist - if necessary check in advance.

When SHOW_MOVIE@ returns, the movie window will be displayed and will be under the user's control. The MOVIE_PLAYING@ function can be used to determine when the user finally closes the window. If a second call to SHOW_MOVIE@ is made before a previous movie has finished playing, Clearwin+ will wait until the first movie completes.

Movie files can include a sound track, which will be played if a sound card us installed in your PC.


SIZEOF_CLIPBOARD_BITMAP@

Platform | Win32, x64
Purpose | To get the size of the bitmap held on the clipboard.
Syntax | INTEGER FUNCTION SIZEOF_CLIPBOARD_BITMAP@( WIDTH, HEIGHT ) INTEGER WIDTH, HEIGHT
Description | WIDTH and HEIGHT receive the dimensions of the bitmap.
Return value | Returns the value 1 if successful otherwise zero.
See also | SIZEOF_CLIPBOARD_TEXT@


SIZEOF_CLIPBOARD_TEXT@

Platform | Win32, x64
Purpose | To get the size of the text held in the clipboard.
Syntax | INTEGER FUNCTION SIZEOF_CLIPBOARD_TEXT@()
Description | This routine returns the length of the Windows clipboard text array (CF_TEXT or CF_OEMTEXT format). The returned length includes a null (CHAR(0)) character that terminates the string.
Return value | Returns the length of the string or zero on failure. On 64-bit systems clipboard sizes of more than 2GB can be determined with SIZEOF_CLIPBOARD_TEXT64@.
See also | COPY_TO_CLIPBOARD@, COPY_TO_CLIPBOARD64@, COPY_FROM_CLIPBOARD@, COPY_FROM_CLIPBOARD64@, CLIPBOARD_TO_SCREEN_BLOCK@, GRAPHICS_TO_CLIPBOARD@, SIZEOF_CLIPBOARD_TEXT64@


SIZEOF_CLIPBOARD_TEXT64@

Platform | x64
Purpose | To get the large size of the text held in the clipboard.
Syntax | INTEGER*8 FUNCTION SIZEOF_CLIPBOARD_TEXT64@()
Description | This routine returns the length of the Windows clipboard text array (CF_TEXT or CF_OEMTEXT format). The returned length includes a null (CHAR(0)) character that terminates the string.
Return value | Returns the length of the string or zero on failure.
Notes | Added to FTN95 at version 8.10
See also | COPY_TO_CLIPBOARD@, COPY_TO_CLIPBOARD64@, COPY_FROM_CLIPBOARD@, COPY_FROM_CLIPBOARD64@, CLIPBOARD_TO_SCREEN_BLOCK@, GRAPHICS_TO_CLIPBOARD@, SIZEOF_CLIPBOARD_TEXT@


SIZE_IN_PIXELS@

Platform | Win32, x64
Purpose | To set the font size in pixels.
Syntax | SUBROUTINE SIZE_IN_PIXELS@( HEIGHT, WIDTH ) INTEGER HEIGHT, WIDTH
Description | This routine allows you to specify the height and width of a font in pixels.
See also | SIZE_IN_POINTS@


SIZE_IN_POINTS@

Platform | Win32, x64
Purpose | To set the font size in points.
Syntax | SUBROUTINE SIZE_IN_POINTS@( HEIGHT, WIDTH ) INTEGER HEIGHT, WIDTH
Description | Sets the HEIGHT and WIDTH of a font that is being used on a drawing surface.
See also | SIZE_IN_PIXELS@, SELECT_FONT@


SOUND_PLAYING@

Platform | Win32, x64
Purpose | To test for ongoing sound output.
Syntax | INTEGER FUNCTION SOUND_PLAYING@()
Description | This function returns 1 while there is sound output and zero when there is none. It is most useful when used to 'join' several sound samples together by detecting when one has finished so that the next may be started.
Return value | Returns 1 if sound is playing otherwise zero.
See also | WRITE_WAV_FILE@, RECORD_SOUND@, PLAY_SOUND@, PLAY_SOUND_RESOURCE@, SOUND_RECORDING@


SOUND_RECORDING@

Platform | Win32, x64
Purpose | To test if a recording is being made.
Syntax | INTEGER FUNCTION SOUND_RECORDING@()
Return value | Returns 1 while the sound system is recording and 0 when it is idle.
See also | WRITE_WAV_FILE@, RECORD_SOUND@, SOUND_PLAYING@, SOUND_SAMPLE_RATE@, PLAY_SOUND@, PLAY_SOUND_RESOURCE@


SOUND_SAMPLE_RATE@

Platform | Win32, x64
Purpose | To return the current sound sampling rate.
Syntax | INTEGER FUNCTION SOUND_SAMPLE_RATE@( )
Return value | Returns the value supplied to SET_SOUND_SAMPLE_RATE@ or the default sample rate.
See also | WRITE_WAV_FILE@, RECORD_SOUND@, PLAY_SOUND@, PLAY_SOUND_RESOURCE@, SOUND_RECORDING@


START_PROCESS@

Platform

Win32, x64

Purpose

To create a new process and wait for it to terminate.

Syntax

INTEGER FUNCTION START_PROCESS@( COMMAND, PARAMS )
CHARACTER(*) COMMAND,PARAMS

Description

COMMAND is the command line that is to be executed. PARAMS is a string of parameters that is appended to the command line.

Return value

Returns 0 or a positive value if successful. A return value of -1 indicates an error condition.

Notes

The new process is given the same 'show' state as that used when creating the calling process. This will usually be 'show normal' or 'show maximised'.

The alternative function START_PPROCESS@ takes the same form but returns immediately (i.e. it does not wait for the created process to terminate).

In order to issue a DOS command you will need to invoke the command shell by using the prefix 'cmd /c ' followed by the DOS command. The alternative is to call CISSUE@

Example

INTEGER START_PROCESS@,i
i=START_PROCESS@('run.exe',' ')
END


STOP_AUDIO_CD@

Platform | Win32, x64
Purpose | To stop audio playback from the CD.
Syntax | SUBROUTINE STOP_AUDIO_CD@()
See also | CLOSE_CD_TRAY@, OPEN_CD_TRAY@,PLAY_AUDIO_CD@, SET_CD_POSITION@


STOP_WHEN_WINDOWS_CLOSE@

Platform | Win32, x64
Purpose | To wait until all ClearWin+ windows are closed.
Syntax | SUBROUTINE STOP_WHEN_WINDOWS_CLOSE@()
Description | %lw can be used to leave one or more windows open but for 64 bit executables care should be taken to avoid arriving at the runtime "END PROGRAM" point in the code with windows still open. This can result in your working memory being released to the system and being used elsewhere causing your data to be corrupted whilst still in use by ClearWin+. If necessary, a call can be made to the routine STOP_WHEN_WINDOWS_CLOSE@, before "END PROGRAM" in order to avoid a premature exit.


SUPPRESS_CMD_BOX@

Platform | Win32, x64
Purpose | To hide the command prompt window for the next started process.
Syntax | SUBROUTINE SUPPRESS_CMD_BOX@()
Description | This routine can be called before a call to CISSUE@, or START_PROCESS@ or START_PPROCESS@ with the result that, if the process is a "Console" application then the associated "Command Prompt" window will be hidden. The suppress state is automatically cancelled after the call so a new call to SUPPRESS_CMD_BOX@ is required for each call to START_PROCESS@ etc


TEMPORARY_YIELD@

Platform | Win32, x64
Purpose | Provides an alternative to YIELD_PROGRAM_CONTROL@(Y_TEMPORARILY).
Syntax | SUBROUTINE TEMPORARY_YIELD@()


UNDERLINE_FONT@

Platform | Win32, x64
Purpose | To add an underline to text on the current drawing surface.
Syntax | SUBROUTINE UNDERLINE_FONT@( ACTIVE ) INTEGER ACTIVE
Description | When using the function DRAW_CHARACTERS@ on a drawing surface with any font selected, a call to this routine with a value of 1 will make subsequent text underlined. A further call with a value of 0 will switch off the effect.
See also | ROTATE_FONT@, SCALE_FONT@, SELECT_FONT@, ITALIC_FONT@, BOLD_FONT@


UNFREEZE_WINDOW_CONTENTS@

Platform | Win32, x64
Purpose | To restore a window after using FREEZE_WINDOW_CONTENTS@.
Syntax | SUBROUTINE UNFREEZE_WINDOW_CONTENTS@( HWND ) INTEGER(7) HWND
Description | HWND is the handle of the window used with FREEZE_WINDOW_CONTENTS@.
See also | FREEZE_WINDOW_CONTENTS@


UNMAP_FILE@

Platform | Win32, x64
Purpose | To close a file map.
Syntax | SUBROUTINE UNMAP_FILE@( PTR ) CHARACTER(*) PTR
Description | File maps are closed automatically when the program terminates but can be closed sooner by calling this routine. PTR is a value returned by MAP_FILE_FOR_READING@ or MAP_FILE_FOR_READ_WRITE@.
See also | MAP_FILE_FOR_READING@, MAP_FILE_FOR_READ_WRITE@


UPDATE_WINDOW@

Platform | Win32, x64
Purpose | To redraw a ClearWin window.
Syntax | SUBROUTINE UPDATE_WINDOW@(W) INTEGER(7) W
Description | Causes the entire client area to be 'invalidated' and therefore re-drawn. This should not be confused with the ClearWin+ function WINDOW_UPDATE@ that is used for format windows.


USE_APPROXIMATE_COLOURS@

Platform

Win32, x64

Purpose

To switch off colour matching for all drawing surfaces.

Syntax

SUBROUTINE USE_APPROXIMATE_COLOURS@( BOOL )
INTEGER BOOL

Description

By default, routines that draw to a drawing surface use a colour matching algorithm that selects an optimum colour match corresponding to the supplied colour value. Colour matching can be switched off (for all drawing surfaces) by calling this routine with the argument set to zero. A non-zero value switches on again.

If automatic colour matching is switched off, a matched colour can still be obtained from GET_MATCHED_COLOUR@. The result is used as an RGB value in any of the drawing surface routines.

Using this routine may lead to a significant improvement in the performance of your program since colour matching is often unnecessary. When colour matching is desirable, it is only necessary to apply the matching algorithm once for each colour that is used.

This function is not needed on modern 24-bit displays.


USE_GDIPLUS_IMAGE_FILES@

Platform | Win32, x64
Purpose | To turn on the use of GDI+ when loading image files.
Syntax | INTEGER USE_GDIPLUS_IMAGE_FILES@(STATE) INTEGER STATE
Description | When GDI+ image loading is turned on a wider range of file types can be loaded with the subroutines GET_DIB_SIZE@, GET_DIB_BLOCK@ and IMPORT_IMAGE@. Passing 1 for STATE will turn on the use of GDI+, passing 0 will turn it off. Off is the default state.
Return value | Returns the previous STATE.
Notes | Added to FTN95 at version 7.10


USE_GDIPLUS@

Platform | Win32, x64
Purpose | Turn on use of GDI+.
Syntax | INTEGER FUNCTION USE_GDIPLUS@(STATE) INTEGER STATE
Description | A non-zero value for 'STATE' enables the GDI+ by setting the default opacity to 255 when drawing surfaces are created. This function returns the previous state. The default state is zero (OFF)..
Notes | Introduced with FTN95 7.00.
See also | Using GDI+, SET_OPACITY@, SET_SMOOTHING_MODE@


USE_RESOURCE_LIBRARY@

Platform

Win32, x64

Purpose

To specify the name of a DLL that contains resources.

Syntax

SUBROUTINE USE_RESOURCE_LIBRARY@( LIBNAME )
CHARACTER(*) LIBNAME

Description

By default any resources required by a program are obtained from the main .EXE file. This routine causes ClearWin+ to also search for resources in the specified DLL. It can be called more than once if the resources are distributed between various DLLs. The library name is the local name of the DLL without its .DLL extension. For example:
CALL USE_RESOURCE_LIBRARY@('MYLIB').

Since FTN95 version 8.62 this library call is redundant. ClearWin+ will automatically look for resources in the executable and in any associated DLLs that were created using FTN95 or SCC.


USE_RGB_COLOURS@

Platform | Win32, x64
Purpose | To switch between colour modes on a drawing surface.
Syntax | INTEGER FUNCTION USE_RGB_COLOURS@( UID, BOOL ) INTEGER UID, BOOL
Description | UID is the programmer's identifier for the drawing surface as used for example in SELECT_GRAPHICS_OBJECT@ and %'gr. If UID is zero then the current drawing surface is used. BOOL can be either 1 or 0. If it is 1 then the RGB colour mode will be used otherwise VGA colour mode (see Graphics format).
Return value | Returns 1 for success or zero if the identifier is not valid.
See also | SET_RGB_COLOURS_DEFAULT@, %gr[rgb_colours]


USE_URL@

Platform | Win32, x64
Purpose | To open a file that has a registered extension.
Syntax | SUBROUTINE USE_URL@( URL ) CHARACTER(*) URL
Description | This routine uses the Windows shell and primarily is designed to open a URL by starting up the default web browser. However, in general it can start any object that has a file name with a registered extension (e.g. .DOC files). You can use this routine in a ClearWin+ window call-back function in order to open a Web document.
See also | INTERNET_HYPERLINK standard call-back.


USE_WINDOWS95_FONT@

Platform | Win32, x64
Purpose | To set the default WINIO@ font to Windows 95 font (Windows 95 only).
Syntax | SUBROUTINE USE_WINDOWS95_FONT@()
Description | If this routine is called, by default all WINIO@ dialogs will use the Windows 95 font where available. This is equivalent to placing %`sf at the front of each WINIO@ string and adding a grave accent to every existing %sf format.
See also | %sf


WAV_FILE_READ@

Platform | Win32, x64
Purpose | To read a WAV file as a samples wave-form.
Syntax | SUBROUTINE WAV_FILE_READ@( HANDLE, LEFT, + RIGHT,SAMPLES ) INTEGER(7) HANDLE INTEGER SAMPLES INTEGER*2 LEFT(SAMPLES), RIGHT(SAMPLES)
Description | Samples sound data is read from the WAV file, returning at most SAMPLES values. HANDLE is returned by a call to OPEN_WAV_FILE_READ@.
See also | OPEN_WAV_FILE_READ@,


WAV_FILE_WRITE@

Platform | Win32, x64
Purpose | To store any recorded data.
Syntax | SUBROUTINE WAV_FILE_WRITE@( HANDLE, LEFT, RIGHT,SAMPLES ) INTEGER(7) HANDLE INTEGER SAMPLES INTEGER*2 LEFT(SAMPLES), RIGHT(SAMPLES)
Description | The data contained in LEFTand RIGHT is written to disk in WAV file format. HANDLE is returned by a call to OPEN_WAV_FILE_WRITE@.
See also | OPEN_WAV_FILE_WRITE@


WBCOMMAND@

Platform | Win32, x64
Purpose | To navigate a %wb format code to a different URL.
Syntax | INTEGER FUNCTION WBCOMMAND@( URL ) CHARACTER(*) URL
Description | Cause the %wb control with focus to navigate to a new URL.
Return value | Returns 0 on success or an Internet Explorer error code.
See also | %wb


WINDOWS_95_FUNCTIONALITY@

Platform | Win32, x64
Purpose | To test if Windows 95 is in use.
Syntax | INTEGER FUNCTION WINDOWS_95_FUNCTIONALITY@()
Return value | Returns the value 1 if Windows 95, otherwise zero.


WIN_COUA@

Platform | Win32, x64
Purpose | To output n characters from a string to a ClearWin window.
Syntax | SUBROUTINE WIN_COUA@(HWND,STR,N) INTEGER(7) HWND INTEGER N CHARACTER(*) STR
Description | Outputs N characters from the string STR to the ClearWin window with handle HWND.This function provides an alternative to the standard Fortran routines WRITE and PRINT that are normally used for text output to a ClearWin window.


WIN_GETCHAR@

Platform | Win32, x64
Purpose | To read a character from the keyboard.
Syntax | INTEGER WIN_GETCHAR@(HWND) INTEGER(7) HWND
Description | Changes the input focus to the ClearWin window with handle HWND and reads a character from the keyboard. This function provides an alternative to the standard READ routine.


WIN_GETLINE@

Platform | Win32, x64
Purpose | To read a line of text from the keyboard.
Syntax | SUBROUTINE WIN_GETLINE@(HWND,LINE) INTEGER(7) HWND CHARACTER(*) LINE
Description | Changes the input focus to the ClearWin window with handle HWND and reads a line of text from the keyboard. This function provides an alternative to the standard READ routine.


WINIO@

Platform | Win32, x64
Purpose | Build ClearWin+ windows with format codes.
Syntax | SUBROUTINE WINIO@(FORMAT, ...) CHARACTER(*) FORMAT
Description | See Window formats


WINSTYLE@

Platform

Win32, x64

Purpose

Provide a default style for all subsequent WINIO@ windows.

Syntax

SUBROUTINE WINSTYLE@(FORMAT)
CHARACTER(*) FORMAT

Description

Provides a default style for all subsequent WINIO@ windows. FORMAT is the same as the first argument of winio@ but has no other arguments. Its use is restricted to the following format codes:

  • %fn Font name
  • %bf Bold font
  • %it Italic font
  • %ul Underlined font
  • %ts Text size (in the new form %ts[value] where value is a floating point number)
  • %tc Text colour
  • %fb Button font
  • %ww Window style
  • %sy Dialog style
  • %es Escape key closes the window

A terminating ampersand (&) for continuation may be used but is not required.

Example

call winstyle@("%ww[not_fixed_size]")
call winstyle@("%es")
call winstyle@("%fn[Tahoma]")
call winstyle@("%fb")
call winstyle@("%ts[1.5]%it")
call winstyle@("%tc[blue]%bg[#f0f0f0]")
i = winio@("Hello");
i = winio@("Hello again!&");
i = winio@("%2nl%cn%tt[OK]");

Notes

Added to FTN95 at version 8.20

See also

winio@


WKEY_WAITING@

Platform | Win32, x64
Purpose | To test if there are any keys in a ClearWin window keyboard buffer.
Syntax | INTEGER FUNCTION WKEY_WAITING@( )
Description | This routine is only for use in a ClearWin window (e.g. with %cw).
Return value | Returns the number of keys in the keyboard buffer.
See also | FEED_WKEYBOARD@, FLUSH_WKEYBOARD@, GET_WKEY@, GET_WKEY1@


WRITE_GRAPHICS_TO_BMP@

Platform | Win32, x64
Purpose | To write the current drawing surface to a BMP file.
Syntax | SUBROUTINE WRITE_GRAPHICS_TO_BMP@( FILENAME, ERROR ) CHARACTER(*) FILENAME INTEGER ERROR
Description | Writes the current drawing surface to the file with name FILENAME. ERROR returns one of the following:

0 | success
1 | no current drawing surface or unable to open file
3 | unable to write to file

See also

IMPORT_BMP@, EXPORT_BMP@


WRITE_GRAPHICS_TO_PCX@

Platform | Win32, x64
Purpose | To write the current drawing surface to a PCX file.
Syntax | SUBROUTINE WRITE_GRAPHICS_TO_PCX@( FILENAME, ERROR ) CHARACTER(*) FILENAME INTEGER ERROR
Description | Writes the current drawing surface to the file with name FILENAME. ERROR returns one of the following:

0 | success
1 | no current drawing surface or unable to open file
3 | unable to write to file

See also

IMPORT_PCX@, EXPORT_PCX@


WRITE_WAV_FILE@

Platform

Win32, x64

Purpose

To store any recorded data.

Syntax

SUBROUTINE WRITE_WAV_FILE@( FILENAME, CHAN, SAMPLES,
+ LEFT, RIGHT )
CHARACTER(*) FILENAME
INTEGER CHAN, SAMPLES
INTEGER*2 LEFT(SAMPLES), RIGHT(SAMPLES)
PARAMETER SAMPLES

Description

The data contained in LEFTand RIGHT is written to disk in wave file format. FILENAME should be set to the desired file name. CHAN can be either 1 (mono) or 2 (stereo). SAMPLES is the length of both the LEFTand RIGHT data arrays (they should be identical).

This routine writes a whole WAV file in one go, so it must be of a size that can fit into memory.

See also

SOUND_RECORDING@, RECORD_SOUND@, SOUND_PLAYING@,
PLAY_SOUND_RESOURCE@, PLAY_SOUND@, SET_SOUND_SAMPLE_RATE@


Y

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


YIELD_PROGRAM_CONTROL@

Platform

Win32, x64

Purpose

To process Windows messages.

Syntax

SUBROUTINE YIELD_PROGRAM_CONTROL@(OPTION)
INTEGER OPTION

Description

This routine contains a Windows message loop. It is called automatically by ClearWin+ so that the programmer does not need to include a message loop in a program. It can be used within a program to ensure that a process does not totally take over the CPU. OPTION may be either Y_PERMANENTLY or Y_TEMPORARILY.

You may need to call this routine using Y_TEMPORARILY, if the program makes protracted use of the CPU and you want to allow it to respond to events (such as mouse events) whilst the processing continues. Call this routine at suitable points during the process to enable the message queue for the current application to be processed. Message queues for other applications that are running will automatically be processed. TEMPORARY_YIELD@ is the same as YIELD_PROGRAM_CONTROL@(Y_TEMPORARILY).

Calling this routine using Y_PERMANENTLY is equivalent to reaching the END statement of a ClearWin+ program.


Glossary

Accelerator keys

Bitmap

Button

Call-back function

Caption

Child window

ClearWin window

Clipboard

Colour modes

DLL

Drawing surfaces

Edit box

Focus

Font

Format

GIF file

Greyed out

GUI

Handle

High colour device

htmL

Icon

Maximise

MDI

Menu

Minimise

Resources

RGB colours

Screen resolution

Screen saver

Scroll bar

Shortcut keys

Standard character string

Status bar

Thumb

Toolbar

Win16

Win32

Windows application

Windows control

Windows API

Windows message

WM_PAINT message


Accelerator keys

An accelerator key is a key sequence, such as Alt-C that can directly activate some process in a window (i.e. without popping up a menu). Accelerators can be defined using %ac. A special case of an accelerator key is defined using %es, which causes a window to respond to the ESC key by closing.


Bitmap

A rectangular image stored as binary data (see %bm). Bitmaps are stored in files with the .BMP suffix.


Button

A button is a control that is designed to respond to a mouse click. Several types of buttons are available. Simple 3-dimensional press and release buttons containing text (and sometimes an icon as well) can be created using %bt. Radio buttons are created with %rb. These are point like structures (with the name along side) that toggle when pressed. Buttons containing a picture can be created with %tb.


Call-back function

A ClearWin+ call back function is a function passed to WINIO@ (and certain other functions) that is called when certain events occur. In ClearWin+, all such functions take no arguments and return an integer result.


Caption

The distinctively coloured strip across the top of most windows that contains the title together with some controls for manipulating the window. A window can be dragged by its caption. See %ca.


Child window

A child window is a window that is contained within a larger window (which could be a child of yet another window). The sub-windows of an MDI application (see %fr and %aw) are children, as are the separate sheets of a property sheet (see %ps and %sh). However, most controls, such as buttons, are considered by Windows to be children of the window that contains them. This is why controls can be referred to by their window handle (see %lc).


ClearWin window

A ClearWin window (no '+') refers to a window created to contain output that would have gone to the screen if the program were not a Windows application. The name refers to the fact that the original ClearWin only created such relatively primitive windows. A ClearWin window is still useful for debugging purposes, and may be properly embedded in a format window using %cw. Keyboard input can also be taken from a ClearWin window, but this is not recommended in finished programs.


Clipboard

The clipboard is a structure maintained by Windows that can contain information which is to be copied within or between applications. The clipboard 'knows' the format of the data that it contains, so a text editor will not accidentally paste data of another format (e.g. an image) into its contents. By convention, the clipboard is accessed as a direct response to controls with names such as 'paste', 'cut', 'copy'. It is extremely anti-social to use the clipboard in any other way, as users learn to rely on the contents of the clipboard remaining unchanged unless they explicitly alter them.


Colour modes

When drawing to drawing surfaces, ClearWin+ operates in one of two colour modes; RGB mode or VGA mode. In VGA mode, colour values are represented as indexes into a colour palette by which ClearWin+ emulates a DOS environment. This mode is useful for porting DOS programs to Windows. Currently the default colour mode is VGA mode. In RGB mode ClearWin+ uses RGB colours (the native Windows colour representation). RGB mode is recommended for new programs.


DLL

This stands for Dynamic Link Library - a library of code that can be linked to a program at run time. DBOS provides such a mechanism, as does Win32. The Win32 file salflibc.dll is an example of a DLL.


Drawing surfaces

ClearWin+ includes a library of drawing routines for drawing lines and text, for filling areas, for copying from one place to another, etc.. These drawing routines are applied to the current drawing surface. This surface could be one of a number of rectangular areas of the screen generated by %gr, it could be one of a number of printer bitmaps (created for example by OPEN_PRINTER@) or it might be an internal bitmap created by CREATE_GRAPHICS_REGION@ (that is, a bitmap that is created for copying to another drawing surface). SELECT_GRAPHICS_OBJECT@ is used to switch from one drawing surface to another.


Edit box

This term is used to refer to boxes created with %eb to perform text editing. The term may also include other boxes containing editable text, such as numeric input boxes created with %rd, %rf, etc..


Focus

A control is said to have focus if it is the one that will respond to keyboard input. Even buttons can have focus - a button with focus can be activated by pressing the space bar. Usually the appearance of a control changes slightly when it acquires focus.


Font

Information describing the graphical layout of a set of characters. Windows fonts can be variable pitch (e.g. Times New Roman) or fixed pitch (e.g. Courier New). Variable pitch fonts fit characters into different amounts of horizontal space depending on their shape and the shapes of their neighbours (see %fn). Each font type comes in several sizes (see %ts) and variants - italic (%it), bold (%bf) and underline (%ul).


Format

format window | a window that has been created using WINIO@.
format string | the first argument of WINIO@.
format code | a format substring beginning with %.
format modifier | one of the characters ^ ` ~ ? appearing in a format code.


GIF file

An image file format popular in World Wide Web documents. GIF files can be partially transparent and/or animated. They can be incorporated into ClearWin+ programs as resources and accessed using the %gi format.


Greyed out

This expression refers to the process by which certain menu items, buttons, etc. can be given a washed out appearance which is an indication to the user that they are not available in current circumstances. Many controls and menus can be controllably greyed using the '~' format modifier together with an integer control variable that specifies the current state.


GUI

This stands for Graphical User Interface, and refers to a program with a Windows interface (or the equivalent on other platforms).


Handle

A handle is an integer (kind=7) supplied by Windows (in the context of Windows programming) used to refer to an object. Thus a window handle is an integer used to refer to a whole window or an individual control (most of which are treated as small child windows). A bitmap handle is an integer used to refer to a bitmap, etc..


High colour device

A high colour graphics device is one that uses more than 8 bits (256 colours) per pixel. Colour palettes become redundant when using such a device. The function HIGH_COLOUR_MODE@ can be used to test for a high colour device.


htmL

Hypertext Mark-up Language is the language used to create Internet Web pages. A simplified form can be used to create hypertext pages in a format window (see %ht).


Icon

An icon is a special sort of image, stored in a binary file with the .ICO suffix. It is partially transparent. Thus an icon can appear to have any shape (see %ic and %mi). ClearWin+ uses icons of size 32x32. However, larger transparent images can be manipulated as GIF files.


Maximise

The process by which a window is expanded until it exactly fits the screen (or containing window in the case of MDI children). Menu options in the system menu (and buttons on the top right of the window) enable the user to select and de-select this state for a window. %ww[maximise] can be used to create a window in this state.


MDI

This stands for Multiple Document Interface. This is a style of program in which one large window contains one or more smaller windows within it. These windows can be opened, closed, moved, etc. independently. Most Windows editors adopt this style with one window per opened file. The %fr and %aw formats can be used to create such programs under ClearWin+.


Menu

Menus are text structures that respond to mouse clicks (and usually certain Alt-key sequences) to enable users to give commands to the program. There are three types of menus in Windows. 1) Ordinary window menus that start just below a window's caption and drop down to reveal sub options when they are clicked (see %mn). 2) The so called system menu, that can be activated by clicking in the top left corner of a window (see %sm), and 3) popup menus that appear when the right mouse button is clicked (see %pm). See also shortcut keys.


Minimise

The process by which a window is shrunk to an icon (also known as iconification). Menu options in the system menu (and buttons on the top right of the window) enable the user to select this state. The user can access the system menu in order to return the window to normal by clicking on the icon. Use %mi to define the icon that will be used in the minimised state.


Resources

Microsoft jargon for non-program information (e.g. images or sounds) built into a program. Resources are specified in resource scripts, and are compiled with the resource compiler (SRC). ClearWin+ programs use resources to incorporate images, sounds, and hypertext into the program.


RGB colours

The Windows API represents a colour in terms of the intensity (in the range 0 to 255) of its red, green and blue components. Each component is thus an 8-bit value and the three components are packed into a 32-bit integer with the least significant 8 bits being red, the next 8 bits green and then blue. The most significant 8 bits are not used. The packing process is done for you by the function RGB@. For example RGB@(255,0,0) represents pure red.


Screen resolution

The number of pixels horizontally and vertically on the entire screen. Typical values are 640 x 480, 800 x 600, and 1024 x 768. The screen will also have a colour resolution, typically 16, 256, 16k, or higher.


Screen saver

A program designed to run while the computer is idle. Usually such programs are designed to stop as soon as mouse or keyboard input is received (see %ns and %sv).


Scroll bar

A scroll bar is a structure to the right of a window or control that can be used to shift the contents vertically, or at the bottom of a window to shift the contents horizontally. A scroll bar has an arrow structure at either end that will scroll the contents by one unit (e.g. one line if the contents is text) and a moveable control (known as a thumb) that can be dragged to make larger movements. Movements of one page (the exact meaning of which depends on the window contents) can be made by clicking above or below the thumb (see %hx and %vx).


Shortcut keys

A shortcut key represents a way of accessing a menu using the keyboard. Each item of a menu can have a letter underlined, indicating that it can be selected by holding down the Alt key and pressing the letter (or certain other keys). The components of subsequent sub-menus can then be selected by pressing further keys corresponding to underlined letters in the menus. The whole process of underlining the letters and responding to the keyboard is controlled by merely prefixing the letter in the menu item by an '&' (see %mn and %sm).


Standard character string

This is the name given to text in a format string that is either placed in square brackets or is replaced by an @ symbol and represented by an argument.


Status bar

This is a strip at the bottom of a window with a distinct colour (usually grey) in which special information is placed. See the %ob format for details of how to create one.


Thumb

The name given to a blank box that appears on a scroll bar. One of the mechanisms for scrolling involves dragging this box with the mouse.


Toolbar

A toolbar is a rectangular array of bitmap buttons, usually but not always located under the window menu bar. Toolbars can be created as arrays of bitmap buttons using %tb.


Win16

This refers to programs that interact with the 16-bit API of Windows 3.1. This is also available under Windows 95. Silverfrost compilers generate 32-bit code for Win16 that operates using a 16/32 interface. Although the Win16 API is available under Windows NT, there are certain restrictions that prevent the above 16/32 interface from working - Win32 must be used for this operating system.


Win32

This refers to programs that exploit the 32-bit mode of operation available in Windows NT and subsequent 32 bit versions of Windows.


Windows API

This is the set of routines supplied by Microsoft to access the features of Windows. All Windows programs ultimately call these routines. For example, requests to ClearWin+ are executed internally by making calls to the Windows API.


Windows application

A Windows program - that is any program that opens at least one window. Non Windows applications read and write to a DOS box.


Windows control

A windows control is any part of a window that operates as a distinctive entity. For example, buttons, %rd integer input boxes, and toolbars are all controls.


Windows message

Windows communicates information about events (such as key presses, mouse movements, etc.) to the program by means of 'messages'. These are small structures that are stored in a queue and accessed by means of a call to the Windows API. This process is handled automatically by ClearWin+. Specific Windows messages are referred to by names such as WM_PAINT, WM_CREATE, etc.


WM_PAINT message

This is a message sent by Windows to an application to tell it to 're-paint' one of its windows (for example because another window has obscured it). ClearWin+ programmers do not need to be aware of the fact that a window's contents may have to be regenerated in this way. However some call-backs, such as the re-colour call back from %eb edit boxes, may be activated in response to this message.


Functions ported from DBOS

In this section:

  • Introduction
  • Graphics
  • Graphics plotter/screen
  • Graphics printer
  • Mouse
  • Table of alternative routines

This section contains information about functions that feature in the Silverfrost DOS (DBOS) graphics library. It describes the extent to which this library has been ported to ClearWin+. The following classification of DBOS graphics functions can be made in relation to ClearWin+.

1. Functions that are useful in new programs (marked ü). Some of these will have identical usage under ClearWin+ to that under DBOS. For some the functionality is slightly different. Details are given in the Library reference.

2. Functions that can be used in new programs (marked þ) but for which there is a suitable alternative. Details for these functions are given in the ClearWin+ User's Supplement. A table of the alternative routines is given at the end of this appendix. The alternatives are documented in this guide.

3. Functions that could be ported from existing DBOS programs but which should not be written into new programs because there is a better alternative under ClearWin+ (marked ð). A table of alternative routines is given at the end of this section.

4. Functions which have no operation or are not useful under ClearWin+ but can be left in old programs that have been ported from DBOS (marked €).

5. Functions which have not been implemented under ClearWin+ (marked û).


DBOS Graphics

In this section:

  • Introduction
  • Graphics
  • Graphics plotter/screen
  • Graphics printer
  • Mouse
  • Table of alternative routines

CLEAR_SCREEN@ | Clears the drawing surface. | ü
CLEAR_SCREEN_AREA@ | Clears a rectangular area of the drawing surface. | þ
COMBINE_POLYGONS@ | Gets the handle for a combination of polygons. | ð
CREATE_POLYGON@ | Gets a handle for a specified polygon. | ð
DELETE_POLYGON_DEFINITION@ | Deletes a polygon definition. | ð
DRAW_HERSHEY@ | Draws an Hershey character. | ð
DRAW_LINE@ | Draws a straight line on the drawing surface. | ð
DRAW_TEXT@ | Draws text on the drawing surface. | ð
EGA@ | Switches to EGA graphics mode. | €
ELLIPSE@ | Draws an ellipse. | ð
FILL_ELLIPSE@ | Fills an ellipse. | ð
FILL_POLYGON@ | Fills a polygon. | ð
FILL_RECTANGLE@ | Fills a rectangle. | ð
GET_ALL_PALETTE_REGS@ | Gets all palette registers for colour graphics. | ð
GET_DEVICE_PIXEL@ | Gets a pixel colour from a graphics region. | û
GET_GRAPHICS_MODES@ | Gets details of all the graphics modes. | €
GET_GRAPHICS_RESOLUTION@ | Gets details of the high resolution graphics mode. | €
GET_PIXEL@ | Gets a pixel colour from the drawing surface. | ð
GET_TEXT_MODES@ | Gets information about the available text modes. | û
GET_TEXT_SCREEN_SIZE@ | Gets the resolution of the current text mode. | û
GET_VIDEO_DAC_BLOCK@ | Gets a block of VGA DAC registers. | ð
GRAPHICS_MODE_SET@ | Sets the graphics mode to a given resolution. | ð
GRAPHICS_WRITE_MODE@ | Selects replace/XOR mode before writing to the screen, virtual screen or printer. | ü
HERSHEY_PRESENT@ | Tests if a character number has a Hershey representation. | ð
HIGH_RESOLUTION_GRAPHICS_MODE@ | Switches to high resolution graphics mode. | €
IS_TEXT_MODE@ | Tests if the screen is in text or graphics mode. | û
LOAD_STANDARD_COLOURS@ | Loads the standard colours for 256 colour mode. | ü
MOVE_POLYGON@ | Moves the position of a polygon. | ð
POLYLINE@ | Draws a number of connected straight lines. | ð
RECTANGLE@ | Draws a rectangle. | ð
RESTORE_GRAPHICS_BANK@ | Restores the graphics bank after a BIOS call. | €
RESTORE_TEXT_SCREEN@ | Restores a text screen saved with SAVE_TEXT_SCREEN@. | û
SAVE_TEXT_SCREEN@ | Saves the whole of the text screen. | û
SCREEN_TYPE@ | Gets the graphics screen type. | €
SET_ALL_PALETTE_REGS@ | Sets all palette registers for colour graphics. | ð
SET_DEVICE_PIXEL@ | Sets a pixel colour on the drawing surface. | þ
SET_PALETTE@ | Sets a palette register for colour graphics. | ð
SET_PIXEL@ | Sets a pixel colour on the drawing surface. | ð
SET_TEXT_ATTRIBUTE@ | Sets the current graphics text attributes. | þ
SET_VIDEO_DAC@ | Sets a VGA DAC register. | ð
SET_VIDEO_DAC_BLOCK@ | Sets a block of VGA DAC registers. | ð
TEXT_MODE@ | Returns to text mode. | €
TEXT_MODE_SET@ | Selects the current text mode. | €
USE_VESA_INTERFACE@ | Forces the VESA interface to be used. | €
VGA@ | Switches to VGA graphics mode. | €


Graphics plotter/screen

In this section:

  • Introduction
  • Graphics
  • Graphics plotter/screen
  • Graphics printer
  • Mouse
  • Table of alternative routines

CLOSE_PLOTTER@ | Closes the plotter device or file. | ð
CLOSE_VSCREEN@ | Closes the virtual screen. | þ
CREATE_SCREEN_BLOCK@ | Creates a screen block in memory. | þ
GET_DACS_FROM_SCREEN_BLOCK@ | Uses palette information from a PCX file. | þ
GET_SCREEN_BLOCK@ | Saves a rectangular area of the screen. | þ
NEW_PAGE@ | Provides a new page on the drawing surface. | ü
OPEN_PLOT_DEVICE@ | Opens the plotter. | ð
OPEN_PLOT_FILE@ | Directs plotter output to a file. | ð
OPEN_VSCREEN@ | Opens a screen block as the virtual screen. | þ
PCX_TO_SCREEN_BLOCK@ | Loads a file a screen block. | þ
PLOTTER_SET_PEN_TYPE@ | Selects a pen type for the plotter. | €
RESTORE_SCREEN_BLOCK@ | Displays a previously saved area of the screen. | þ
SCREEN_BLOCK_TO_PCX@ | Saves a screen block a file. | þ
SCREEN_BLOCK_TO_VSCREEN@ | Loads a screen block to the virtual screen. | þ
SCREEN_TO_VSCREEN@ | Loads the graphics screen to the virtual screen. | þ
VSCREEN_TO_PCX@ | Saves the virtual screen to a file. | þ
VSCREEN_TO_SCREEN@ | Loads the virtual screen to the graphics screen. | þ
WRITE_TO_PLOTTER@ | Writes a string to the plotter. | €


Graphics printer

In this section:

  • Introduction
  • Graphics
  • Graphics plotter/screen
  • Graphics printer
  • Mouse
  • Table of alternative routines

CLOSE_GRAPHICS_PRINTER@ | Closes the graphics printer device or file. | ð
GET_PCL_PALETTE@ | Gets the colour definitions for a given number of colours. | ü
LOAD_PCL_COLOURS@ | Loads the standard colour definitions. | ü
OPEN_GPRINT_DEVICE@ | Opens a graphics printer. | ð
OPEN_GPRINT_FILE@ | Directs graphics printer output to a file. | ð
PRINT_GRAPHICS_PAGE@ | Prints a graphics page. | ü
SELECT_DOT_MATRIX@ | Selects an Epson compatible dot matrix printer | û
SELECT_PCL_PRINTER@ | Specifies attributes of a PCL printer. | ð
SET_PCL_BITPLANES@ | Sets the number of colours in the image. | €
SET_PCL_GAMMA_CORRECTION@ | Alters the "gamma correction" for colours. | €
SET_PCL_GRAPHICS_DEPLETION@ | Improves the image quality. | €
SET_PCL_GRAPHICS_SHINGLING@ | Makes a number of print passes. | €
SET_PCL_LANDSCAPE@ | Sets LANDSCAPE or PORTRAIT orientation. | þ
SET_PCL_PALETTE@ | Loads the colour definitions. | €
SET_PCL_RENDER@ | Sets the "rendering algorithm". | €


Mouse

In this section:

  • Introduction
  • Graphics
  • Graphics plotter/screen
  • Graphics printer
  • Mouse
  • Table of alternative routines

DISPLAY_MOUSE_CURSOR@ | Shows the mouse cursor on the screen. | €
GET_MOUSE_BUTTON_PRESS_COUNT@ | Gets the number of times a button has been pressed. | €
GET_MOUSE_EVENT_MASK@ | Gets the mask for the most recent mouse interrupt. | €
GET_MOUSE_PHYSICAL_MOVEMENT@ | Gets the mouse pad distance from the last call. | €
GET_MOUSE_POSITION@ | Gets the present state of the mouse cursor. | ð
GET_MOUSE_SENSITIVITY@ | Gets the values of the physical movement ratios and the double speed threshold. | €
HIDE_MOUSE_CURSOR@ | Hides the mouse cursor on the screen. | €
INITIALISE_MOUSE@ | Initialises the mouse driver. | €
MOUSE@ | Performs a mouse interrupt. | €
MOUSE_CONDITIONAL_OFF@ | Switches off the cursor when it enters a specified rectangle. | €
MOUSE_LIGHT_PEN_EMULATION@ | Uses the mouse as a light-pen. | €
MOUSE_SOFT_RESET@ | Initialises the mouse. | ð
QUERY_MOUSE_SAVE_SIZE@ | Gets the buffer size for the mouse state. | €
RESTORE_MOUSE_DRIVER_STATE@ | Restores a former state of the mouse driver. | €
SAVE_MOUSE_DRIVER_STATE@ | Saves the current state of the mouse driver. | €
SET_MOUSE_BOUNDS@ | Restricts mouse movements to a specified rectangle. | €
SET_MOUSE_GRAPHICS_CURSOR@ | Specifies the shape of the mouse cursor for graphics mode. | €
SET_MOUSE_INTERRUPT_MASK@ | Enables mouse actions to produce interrupts. | €
SET_MOUSE_MOVEMENT_RATIO@ | Sets the mouse cursor sensitivity. | €
SET_MOUSE_POSITION@ | Moves the mouse cursor to a particular position. | ð
SET_MOUSE_SENSITIVITY@ | Sets the mouse cursor sensitivity and the threshold for the double speed. | €
SET_MOUSE_SPEED_THRESHOLD@ | Sets the threshold for double speed. | €
SET_MOUSE_TEXT_CURSOR@ | Specifies details of the mouse cursor for text mode. | €


Table of alternative routines

In this section:

  • Introduction
  • Graphics
  • Graphics plotter/screen
  • Graphics printer
  • Mouse
  • Table of alternative routines

DBOS routine | ClearWin+ alternative
CLEAR_SCREEN_AREA@ | DRAW_FILLED_RECTANGLE@
CLOSE_GRAPHICS_PRINTER@ | CLOSE_PRINTER@
CLOSE_PLOTTER@ | CLOSE_PRINTER@
CLOSE_VSCREEN@ | CREATE_GRAPHICS_REGION@ etc.
COMBINE_POLYGONS@ | DRAW_FILLED_POLYGON@
CREATE_POLYGON@ | DRAW_FILLED_POLYGON@
CREATE_SCREEN_BLOCK@ | CREATE_GRAPHICS_REGION@ etc.
DELETE_POLYGON_DEFINITION@ | DRAW_FILLED_POLYGON@
DRAW_HERSHEY@ | DRAW_CHARACTERS@
DRAW_LINE@ | DRAW_LINE_BETWEEN@
DRAW_TEXT@ | DRAW_CHARACTERS@
ELLIPSE@ | DRAW_ELLIPSE@
FILL_ELLIPSE@ | DRAW_FILLED_ELLIPSE@
FILL_POLYGON@ | DRAW_FILLED_POLYGON@
FILL_RECTANGLE@ | DRAW_FILLED_RECTANGLE@
GET_ALL_PALETTE_REGS@ | GET_COLOURS@
GET_MOUSE_POSITION@ | CLEARWIN_INFO@
GET_PIXEL@ | GET_POINT@
GET_SCREEN_BLOCK@ | CREATE_GRAPHICS_REGION@ etc.
GET_VIDEO_DAC_BLOCK@ | GET_COLOURS@
GRAPHICS_MODE_SET@ | LOAD_STANDARD_COLOURS@
HERSHEY_PRESENT@ | DRAW_CHARACTERS@
MOUSE_SOFT_RESET@ | SET_MOUSE_CURSOR_POSITION@
MOVE_POLYGON@ | DRAW_FILLED_POLYGON@
OPEN_GPRINT_DEVICE@ | OPEN_PRINTER@
OPEN_GPRINT_FILE@ | OPEN_PRINTER_TO_FILE@
OPEN_PLOT_DEVICE@ | OPEN_PRINTER@
OPEN_PLOT_FILE@ | OPEN_PRINTER_TO_FILE@
OPEN_VSCREEN@ | CREATE_GRAPHICS_REGION@ etc.
PCX_TO_SCREEN_BLOCK@ | CREATE_GRAPHICS_REGION@ etc.
POLYLINE@ | DRAW_POLYLINE@
RECTANGLE@ | DRAW_RECTANGLE@
RESTORE_SCREEN_BLOCK@ | CREATE_GRAPHICS_REGION@ etc.
SCREEN_BLOCK_TO_PCX@ | CREATE_GRAPHICS_REGION@ etc.
SCREEN_BLOCK_TO_VSCREEN@ | CREATE_GRAPHICS_REGION@ etc.
SCREEN_TO_VSCREEN@ | CREATE_GRAPHICS_REGION@ etc.
SELECT_PCL_PRINTER@ | OPEN_PRINTER@
SET_ALL_PALETTE_REGS@ | SET_COLOURS@
SET_DEVICE_PIXEL@ | DRAW_POINT@
SET_MOUSE_POSITION@ | SET_MOUSE_CURSOR_POSITION@
SET_PALETTE@ | SET_COLOURS@
SET_PCL_LANDSCAPE@ | SET_PRINTER_ORIENTATION@
SET_PIXEL@ | DRAW_POINT@
SET_TEXT_ATTRIBUTE@ | BOLD_FONT@ etc.
SET_VIDEO_DAC@ | SET_COLOURS@
SET_VIDEO_DAC_BLOCK@ | SET_COLOURS@
VSCREEN_TO_PCX@ | CREATE_GRAPHICS_REGION@ etc.
VSCREEN_TO_SCREEN@ | CREATE_GRAPHICS_REGION@ etc.


Introduction to Simfit and Simdem

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

Simfit

Simfit is an Open Source package for

  • Simulation;
  • Curve Fitting;
  • Statistics; and
  • Graph plotting.

It can be downloaded from the Simfit website at

https://www.simfit.silverfrost.com

Simfit can be used in such areas as biology (growth curves), psychology (factor analysis), physiology (transport), pharamacology (dose response curves), pharmacy (pharmacokinetics), immunology (ligand binding), biochemistry (calibration), biophysics (kinetics), epidemiology (survival analysis), medical statistics (meta analysis), chemistry (chemical kinetics), physics (dynamical systems), and mathematics (numerical analysis).

Clipboard data can be analyzed, there is a fully featured pdf user manual with hyper-links, and macros to interface with MS Excel are provided.

Simdem

The Simdem package is an Open Source implementation of the front-end to the Windows API that was created using Clearwin+ to enable Simfit to run in Windows. It is now included in the standard Silverfrost release.

Simdem consists of documentation, and 70 demonstration programs in standard Fortran to illustrate how to create controls for input/ouput, and graphics files in .eps, .emf, .bmp, .pcx, .jpg, .png, tif, and .svg formats, using only standard conforming Fortran code, with no direct references to winio@, or any other FTN95 library routines. The 32-bit Simdem library implementation uses three DLLs as follows:

  1. w_menus.dll (standard Fortran);
  2. w_graphics.dll (standard Fortran); and
  3. w_clearwin.dll (FTN95 specific code and auxiliaries).

In versions of Simdem from 7.40 on these three dlls are replaced by the single file simdem32.dll. This run-time dll will be automatically linked when compiling from Plato.

The 64-bit Simdem library implementation uses three DLLs as follows:

  1. x64_menus.dll (standard Fortran);
  2. x64_graphics.dll (standard Fortran); and
  3. x64_clearwin.dll (FTN95 specific code and auxiliaries).

In versions of Simdem from 7.4.0 on these three dlls are replaced by the single file simdem64.dll. This run-time dll will be automatically linked when compiling from Plato.

Users of FTN95 with versions of Simdem before 7.4.0 have only to supply references to these DLLs in Plato, or on the command line to SLINK, to be able to build fully featured executables with menus, dialogues, graphics, extensive file handling procedures, and a mini spreadsheet type numerical editor, without any need to use calls to winio@. This is because all the code required to transform standard Fortran calls into calls to the Windows API via winio@ are taken care of by w_clearwin.dll, or x64_clearwin.dll when the compiler option /64 is used. Of course, the Simdem DLLs can also be used by executables that call winio@ directly, or link to any other DLLs, or static libraries.

For more detailed information see simdem.chm supplied as part of the Simdem package.


Simfit plotting styles

Plotting styles

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following examples illustrate some of the plotting styles you can use from the Simdem package.


Plotting a pie chart

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code is extracted from program simdem47.f95 in the Simdem package, and it illustrates how easy it is to plot a vector, declared as double precision x(n), as a pie chart. The segment angles are proportional to x(i), so these must all be positive.

!
! initialise essential arguments for default pie chart
!
      do i = 1, n
         x(i) = dble(i)
         write (labels(i),'(a,i2)') 'Segment', i
      enddo
      title = 'Demonstrating a Simfit pie chart'
!
! isend = 1: call pcplot in default mode
!
      isend = 1
      call pcplot (isend, ifill, ihue, n, d, x, labels, title)

The following plot is then displayed, and can then be edited to add further features, printed, or archived as a graphics file. It is possible to edit the segment labels, panel key labels, and title, and to perform additional operations like 3D perspective, and segment displacements, or adding descriptive text, or further graphical objects.


Plotting a bar chart

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code is extracted from program simdem48.f95 in the Simdem package, and it illustrates how easy it is to plot a matrix, declared as double precision x(nmax,ncol), as a bar chart.

!
! initialise essential arguments for default bar chart
!
      do j = 1, ncol
         do i = 1, nrow
            x(i,j) = dble(i + j)
         enddo
      enddo
      titles(1) = 'Demonstrating a Simfit bar chart'
      titles(2) = 'Rows'
      titles(3) = 'Columns'
      titles(4) = blank
!
! isend = 1: call bcplot in default mode
!
      isend = 1
      call bcplot (isend, ncol, nrmax, nrow, x, labels, titles)

The following plot is then displayed and can be edited to add further features, printed, or archived as a graphics file. It is possible to edit the bar labels, keys, and titles, and to perform additional operations like 3D perspective, and side panel re-positioning.


Plotting y = f(x)

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code is extracted from program simdem09.f95 in the Simdem package, and it illustrates how easy it is to plot a curve in the form y = f(x), where x and y are double precision arrays.

!
! Define line and symbol types then number of points and data
!
      l = 1  !solid line type
      m = 5  !circle symbol type
      n = 10 !plot 10 points
      do i = 1, n
         x(i) = i
         y(i) = i
      enddo
!
! Define title and legends
!
      ptitle = 'y = f(x)'
      xtitle = 'x'
      ytitle = 'y'
c
c Plot the graph
c
      call gks001 (l, m, n, x, y, ptitle, xtitle, ytitle)

The following plot is then displayed and can be edited to add further features, printed, or archived as a graphics file.


Plotting r = r(θ)

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code is extracted from program simdem64.f95 in the Simdem package, and it illustrates how easy it is to plot a curve in the parametric form r = r(θ), where r and theta are double precision arrays.

!
! calculate r = sin(4*theta)
!
      delta = two*pi/dble(n - 1)
      theta(1) = zero
      do i = 2, n - 1
         theta(i) = theta(i - 1) + delta
      enddo
      theta(n) = two*pi
      do i = 1, n
         r(i) = sin(four*theta(i))
      enddo
!
! plot the 8 leaved rose
!
      call rtplot (n, r, theta)

The following plot is then displayed and can be edited to add further features, printed, or archived as a graphics file.


Plotting x = x(t), y = y(t)

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code is extracted from program simdem10.f95 in the Simdem package, and it illustrates how easy it is to plot a curve in the parametric form x = x(t), y = y(t), where x and y are double precision arrays. Of course, the arrays x, and y do not need to be in parameteric form, and any number of up to 4 x,y pairs in the form y = f(x) can be plotted. Setting l(i) = m(i) = 0 suppresses the plotting of y(i).

!
! Define line and symbol types and number of points
!
      l1 = 1     !solid line type
      l2 = 2     !dashed line type
      l3 = 3     !dotted line type
      l4 = 4     !dashed-dotted line type
      m1 = 5     !circle symbol type
      m2 = 8     !triangle symbol type
      m3 = 11    !square symbol type
      m4 = 14    !diamond symbol type
      n = nmax/2 !number of points for plotting
      n1 = n
      n2 = n
      n3 = n
      n4 = n
!
! Define the data
!
      delta = pi2/(dble(n) - one)
      t(1) = zero
      do i = 2, n - 1
         t(i) = t(i - 1) + delta
      enddo
      t(n) = pi2
      do i = 1, n
         cosi = cos(t(i))
         sini = sin(t(i))
         x1(i) = a*cosi
         x2(i) = b*cosi
         x3(i) = c*cosi
         x4(i) = d*cosi
         y1(i) = a*sini
         y2(i) = b*sini
         y3(i) = c*sini
         y4(i) = d*sini
      enddo
!
! Define the title and legends
!
      ptitle = 'y = f(x)'
      xtitle = 'x'
      ytitle = 'y'
!
! Plot the graphs
!
      call gks004 (l1, l2, l3, l4, &
                   m1, m2, m3, m4, &
                   n1, n2, n3, n4, &
                   x1, x2, x3, x4, &
                   y1, y2, y3, y4, &
                   ptitle, xtitle, ytitle, &
                   axes, gsave)

The following plot is then displayed and can be edited to add further features, printed, or archived as a graphics file.


Plotting x = x(t), y = y(t), z = z(t)

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code was extracted from simdem23.f95 in the Simdem package, in order to demonstrate how easy it is to plot parametric curves in space, where x, y and z are double precision arrays. Of course, x, y, and z do not have to be defined parametrically and any sets of x,y,z triples can be plotted.

!
! Define t
!
      n = nmax/2
      t(1) = zero
      t(n) = two*pi
      delta = (t(n) - t(1))/(dble(n) - one)
      do i = 2, n - 1
         t(i) = t(i - 1) + delta
      enddo
!
! Define x, y, z as a helix
!
      x(1) = one
      y(1) = zero
      z(1) = one
      do i = 2, n - 1
         delta = two*t(i)
         x(i) = cos(delta)
         y(i) = sin(delta)
         z(i) = dble(i)
      enddo
      x(n) = x(1)
      y(n) = y(1)
      z(n) = dble(n)
!
! Display the space curve
!
      call space0 (n, nmax, x, xtemp, y, ytemp, z)

The following plot is then displayed and can be edited to add further features, printed, or archived as a graphics file.


Plotting z = f(x,y)

In this section:

  • Introduction
  • Simfit plotting styles
  • Plotting a pie chart
  • Plotting a bar chart
  • Plotting y = f(x)
  • Plotting r = r(θ)
  • Plotting x = x(t), y = y(t)
  • Plotting x = x(t), y = y(t), z = z(t)
  • Plotting z = f(x,y)

The following code is extracted from program simdem22.f95 in the Simdem package, and it illustrates how easy it is to plot a surface defined as z = f(x,y), where x, y, and z are double precision arrays. The x and y values must be in the form of a rectangular grid.

!
! Define x and y
!
      nx = 20
      ny = 20
      x(1) = - one
      x(nx) = one
      delta = (x(nx) - x(1))/(dble(nx) - one)
      do i = 2, nx - 1
         x(i) = x(i - 1) + delta
      enddo
      y(1) = - one
      y(ny) = one
      delta = (y(ny) - y(1))/(dble(ny) - one)
      do j = 2, ny - 1
         y(j) = y(j - 1) + delta
      enddo
!
! Define z = f(x,y) and the ranges (xmin,xmax), (ymin,ymax)
!
      do j = 1, ny
         do i = 1, nx
            z(i,j) = x(i)**2 - y(j)**2
         enddo
      enddo
      xmax = x(nx)
      xmin = x(1)
      ymax = y(ny)
      ymin = y(1)
!
! Display the surface, contours, projection, skyscraper blocks, etc.
!
      call surd2s (isend, nmax, nx, ny, vector, xmax, xmin, ymax, ymin, z, unused)

The following plot is then displayed, and can be edited to add further features, printed, or archived as a graphics file. The contours can be suppressed, or plotted separately, and there are options to rotate, add labels, arrows, text, graphical objects, etc. In addition, the points defined by z = f(x,y) can be plotted as bars, or cylinders, when error bars can also be added.


Optimisation and efficient use of Fortran

Introduction

Optimisation

The /OPTIMISE compiler option

Using a coprocessor

Optimisation processes

Helping the optimiser

Efficient use of Fortran

Labels

Intrinsic functions

Statement functions

Common subexpressions

Constants

Dummy array dimensions

Character variables

Format statements

Efficient use of Fortran 95


Optimisation and Efficient use of FTN95

This section describes the FTN95 local and global optimisation features and indicates some of the ways in which a programmer can write Fortran programs that will make the best use of these features.


The /OPTIMISE compiler option

/OPTIMISE (or /OPTIMIZE) selects the optimisation facility described in the following topics.

The /OPTIMISE option causes the compiler to make a second pass through the source code image in order to perform improvements to the object code that will result in faster execution times for typical programs.


Using a coprocessor

On a Win32 platform the compiler will automatically generate correct code for an Intel compatible numeric coprocessor.


Optimisation processes

The improvements in execution speed that are obtained depend upon the style and content of the source program, for example, whether one- or multi-dimensioned arrays are used, whether nested loops appear, and so on.

As optimisation can involve source code re arrangement and a change in the way that registers and store locations are used, it is possible that numerical results produced by an optimised program may differ in some way from those produced by the unoptimised version of the same program. This effect may be more noticeable with iterative algorithms and is due to the fact that a more accurate value can be held in a coprocessor floating point register than can be held in the corresponding store location.

Some programs may actually execute more slowly when optimised due to non-executed loops that cannot be detected by the compiler, for example:

DO 10 I=1,N

where N is zero or negative at run time. In this case code that is moved out of the loop will be executed once, rather than not at all as would happen if this optimisation had not been made.

When the compiler option /OPTIMISE is used, the compiler performs code optimisation based on rearranging the order of execution of statements which constitute a program unit (see below). If /OPTIMISE is not used, the following optimisations are typical of those performed by default.

  • Constant 'folding' and conversion of Fortran type at compile time. Constant folding is the process of taking a statement such as:

A = I + 3 + 7

and producing code which is the same as for the statement:

A = I + 10

This might not appear to be of much use at first glance, since you might not think that you would write expressions with multiple constants in this way. However, consider the expression 2*PI*R where PI is a parameter - the 2*PI part would be evaluated at compile time. In addition to this however, a number of situations arise for the implicit arithmetic which the compiler plants code for (chiefly array subscript calculation) where this technique results in considerable reduction in the amount of arithmetic done at run time.

Related to this is the conversion of the type of constants where appropriate. For example, the statement:

X = 4

is compiled as:

X = 4.0

thus the need for a type conversion at run time is obviated.

  • Elimination of common subexpressions within a statement. Again, this applies equally to expressions which form subscript calculations. Consider the following assignment:

A(I,J+K) = A(I,J+K) + 3

The code necessary to calculate the offset represented by (I,J+K) is only performed once.

  • The contents of registers are "remembered" between statements so that redundant load and store operations are avoided. For example, consider the following sequence of statements:

K = I + J
L = K * I

For the second statement, the compiler recognises that it has the value of K in a register, so it does not need to load K from store.

Note, however, that it will probably need to reference the value of I from memory, since the calculation of I + J will have resulted in the loss of the value of I from a register.

Even if there were some statements interspersed between the statements above, this optimisation could still take place, so long as:

  • the register in question was not used for another purpose in the interim, and

  • none of the interim statements were GOTOs, and

  • none of the executable statements were labelled (a good reason to dispense with unused labels in your code).

The compiler tries to avoid using registers which might contain something useful in a subsequent calculation.

A related technique is used for the coprocessor floating point registers, although due to the limited size of the hardware register stack, it is not possible to leave a value in a register just in case it might be useful. Instead, if a recently calculated floating point value proves to be useful for a subsequent calculation, the instruction which places the result in the corresponding memory location is converted from "store and pop" to "store and don't pop". The value is then available somewhere in the register stack for the subsequent calculation.

Note that this floating point register tracking is not performed when the /DEBUG compiler option is used or implied.

  • Full use is made of the instruction set. For example, an integer addition or subtraction of 1 is performed by the appropriate increment or decrement instruction. Also, some optimisations can be used to perform certain arithmetic operations a little quicker. For example, evaluation of I*5, where I is of integer type, can be performed with the instruction sequence:

MOV EAX%,I
LEA EAX%,[EAX%+EAX%*4]

which is faster than the corresponding integer multiply. Note however, that this optimisation is not done in CHECK mode, since any overflow would go undetected.

When the /OPTIMISE option is used, optimisations performed include the following:

  1. Loop invariant motion. This means that any calculations which are constant with respect to the loop variable may be moved, so that they are performed once and for all on entry to the loop. This leads to the actual degradation in performance mentioned earlier, for the case where the loop is not executed at all. However, in most cases, particularly when the loop is executed a large number of times, considerable savings can result.

  2. Loop induction weakening. This means that, instead of using multiples of the loop index, a constant is added to a pseudo variable each time round the loop. For example, consider the following loop:

DO I = 1, N
A(1,I) = 0
END DO

The offset into the array A will be a constant multiple of the loop variable I. The constant is related to the size of the first dimension of the array A. Induction weakening will replace multiplication by this constant to produce the array offset at each iteration of the loop by a faster addition of the constant at each iteration.

  3. Elimination of common subexpressions across statements. This is often a consequence of the optimisations in (1) and (2) : expressions which are taken out of the loop as either loop invariant, or as candidates for induction weakening, can themselves be sub-parts of larger expressions.

  4. In some loops, particularly useful quantities can be "locked" into registers. "Locking" means that, for the duration of a loop, the value of a program variable, or perhaps a derived quantity such as an offset into an array, is kept in a register, and is not stored into its associated store location (if indeed it has one) until exit from the loop.

Obviously, this requires that exit from the loop cannot be by means of a GOTO from within itself, and that no subroutine or function is called from within the loop, as these statements could destroy any value held in the register.

Also, there is some trade-off involved in tying up a register in this way, so generally locking will only occur for relatively short loops.

Optimisation of the loop in the example given in 2) above involves induction weakening and locking the array offset in a register.

  5. Some additional optimisations based on the 80486 and Pentium instruction set. In some cases integer instructions are used instead of floating point instructions. This often results in different behaviour where the operands are invalid (for example where they should cause an overflow), but it is assumed that, if optimisation is being employed, problems such as this have been eliminated.

  6. Many cases of a "dot-product" construction are spotted and replaced with faster code, for example:

DO I = 1, N
SUM = SUM + A(I)*B(I)
END DO

  7. Many cases of redundant combinations of instructions are eliminated, for example, jumps to the next line, loads from a register to itself which sometimes are generated as a result of register locking (see 4 above).

The above list is not exhaustive, and new optimisations will be added during the course of compiler development.


Helping the optimiser

The success which the optimiser has with your code depends to a large extent on the code itself. In order to ensure that the object code is correct in all cases, the optimiser takes a conservative approach which can sometimes mean that potential optimisations are ignored. As a rule of thumb, the more structured the code appears to the optimiser, the more optimisations it can apply. It is difficult to give hard and fast rules as to how best to maximise the optimisation which can take place, but a number of general points should be noted:

  • GOTOs can often inhibit optimisation. This is particularly the case in tight loops. You may be able to achieve the effect you want by using a logical variable.

  • Function and subroutine calls within loops prevent many optimisations from occurring. Apart from the fact that no register tracking can take place across CALL statements and function references (the called routine does not save the register set), many of the loop optimisations cannot take place.

Even if the CALL statement or function reference appears to be "loop invariant" in some sense (for example, all of its arguments are themselves loop invariant), the CALL statement or function reference cannot be moved because of side effects which the routine may have, or common variables which it uses which are not loop invariant.

Thus, it is up to you to remove CALLs and function references which are genuinely loop invariant from out of your loops.

  • It is a good idea to remove all redundant labels (these are automatically indicated by FTN95's compilation diagnostics).


Efficient use of Fortran

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Labels

The compiler outputs a warning message if a label has been set but never used. Redundant labels should be removed as their presence inhibits optimisation in many cases. Labels can also often be removed by making small changes to the structure of the program, for example:

IF(I/=0)
                GOTO 10
A = B
C = D
10 J = I

If label 10 had not been referenced from elsewhere in the program unit, this could be rewritten more efficiently (and legibly) using a block-IF statement as follows:

IF(I==0)THEN
  A = B
  C = D
ENDIF
J = I

The extra efficiency would derive from the fact that the compiler 'remembers' that it has I in a register when it compiles the statement J=I.


Intrinsic functions

The following intrinsic functions are compiled as in-line code:

  • Type conversion functions such as INT, REAL, DBLE, CMPLX, CHAR, ICHAR, CONJG and DIMAG.

  • AND, OR, XOR, NOT, LS, RS, LR, RR, SHFT, LOC, CCORE1, CORE1, CORE2, CORE4, FCORE4 and DCORE8.
    Note: these functions are FTN95 extensions to standard Fortran 95.

  • The MAX and MIN functions.

  • ABS and its non-generic variants, except CABS and CDABS.

  • LEN and LENG.

  • LGE, LGT, LLE and LLT.

  • The long to short conversion functions INTB, INTS, INTL, LGCB, LGCS and LGCL.

  • INDEX, if the second argument is of length 1, for example:

K=INDEX(MESSAGE,' ')


Statement functions

Statement functions are always expanded as in-line code. Efficient execution is therefore guaranteed and is to be preferred to the supplying of a one line external function.


Common sub-expressions

In most cases, common sub-expressions are evaluated only once. Thus the following code could not be improved by the prior assignment TEMP=X*Y:

Z = (X*Y)/(1.0+X*Y)

Common sub-expressions may sometimes be evaluated more than once in character expressions and in arithmetic expressions contained in logical IF statements.


Constants

The constant parts of expressions are evaluated at compile-time so that PARAMETER statements can be used in many cases to make programs more readable without increasing execution time. For example, consider the following:

PARAMETER (PI=3.14159)
. . .
CALL FRED(PI/2.0)

The expression PI/2.0 is constant and is therefore evaluated at compile-time and nothing would be gained by replacing the expression with its calculated value.


Dummy array dimensions

It is more efficient to dimension a dummy array A(*) rather than A(N) if the value of N implies the whole of array A.


Character variables

The manipulation of long character data has hidden overheads. In particular, consider the following:

CHARACTER(LEN=100)::A
. . .
A = 'FRED'

The execution of the assignment statement involves the insertion of 96 blanks to pad out the variable A to its declared length of 100. Note, however, that

A = ' '

is far more efficient than for example:

. . .
DO I=1,100
A(I:I) = ' '
END DO
. . .


Format statements

Unlike many Fortran implementations, FTN95 preprocesses 'constant' formats at compile-time. These 'constant' formats are as follows:

  • A FORMAT statement.

  • A format expression that is a character constant or a character constant expression.

  • A format expression that is a parameter name.

All formats which include character arrays, array elements or variables are decoded at run-time. Such non-constant formats require more extensive decoding which leads to longer execution times.

For example, the following should be avoided wherever possible:

CHARACTER(LEN=10)::F
F = '(3F10.4)'
. . .
WRITE (2,F)X,Y,Z

It could be rewritten as follows:

CHARACTER(LEN=10)::F
PARAMETER (F='(3F10.4)')
. . .
WRITE (2,F)X,Y,Z

so that the format specifier would be decoded at compile-time.

Note also that the colon (:) edit descriptor and tab facilities can often be used instead of a run-time format.


Efficient use of Fortran 95

The following notes relate to features introduced into the Fortran 95 standard.

  • FTN95 produces faster code with ALLOCATABLE arrays as against POINTER arrays because the ALLOCATABLE attribute guarantees contiguous storage and no aliasing.

  • Temporary arrays (required only during the life time of a function call) are better implemented using automatic arrays in preference to ALLOCATABLE arrays because these can be allocated more efficiently.

  • Fixed-size arrays are more efficient than variable-sized arrays so, when the logic of the program and memory constraints allow, fixed-size arrays are preferred.

  • Specifying the INTENT attribute of a dummy argument improves diagnostics and helps the optimiser and code generator.

  • The use of ENTRY and EQUIVALENCE prevents certain optimisations from taking place.


Fortran input/output

The FTN95 input/output statements allow ISO standard-conforming programs to be written that can:

  • Open and close files

  • Make inquiries about the type and mode of access of a file

  • Access data using any combination of formatted or unformatted and sequential or direct access data transfer statements.

There are nine input/output statements:

OPEN
CLOSE
INQUIRE
BACKSPACE
ENDFILE
REWIND
READ
WRITE
PRINT

There is also one format descriptor statement :

FORMAT

Each of these statements has an associated list of specifiers, for example:

BACKSPACE | (UNIT=7)
WRITE | (10,REC=9) B,C
OPEN | (UNIT=3,FILE='FRED')
READ | (UNIT=2,END=20) A

The general form of these specifiers will be obvious from these examples. Full details of Fortran 95 the input/output statements are given in the Fortran 95 Standard. This section contains a quick reference guide to the input/output and device control statements. In this section the name <variable> refers to a numeric or string variable as appropriate.

Note: The standard Fortran I/O system is not compatible with the FTN95 library file-manipulation routines. These functions provide low-level file access.


OPEN

It is possible to open a file dynamically (that is, at run time) by means of the Fortran OPEN statement.

The OPEN statement will cause a file to become connected. It is used to describe the properties of a connection in addition to performing the connection itself. For example, in order to open a text file for input, the following statement might appear in a program:

OPEN(UNIT=8,FILE='FRED')

It will be apparent that the name of the file and a unit number are used together with some defaults provided by the system in order to open the file.

The general form of the OPEN statement is:

OPEN(<olist>)

<olist> is a list of specifiers. It must contain exactly one external unit specifier <unit> and may contain, at most, one of each of the other specifiers listed below:

UNIT=<value>
<value> is the unit number. The keyword and equals sign are optional if this is the first item in the list. UNIT values should be greater than 6 to avoid the possibility of re-assigning standard input/output streams.

FILE=<filename>
<filename> is the name of the file to which the unit will be connected when it is opened. This is only optional if the specifier STATUS=SCRATCH is present.

IOSTAT=<variable>
<variable> is an integer numeric variable into which the input/output status will be written. The variable will be positive if an error occurred, otherwise it will be zero.

ERR=<label>
<label> is a label to jump to in the event of an error.

ACCESS=<string>
This specifies the type of access for which the file is to be opened. <string> is either DIRECT, SEQUENTIAL or STREAM. As an extension to the Fortran standard <string> can also be TRANSPARENT (see the FORM specifier below). By default the ACCESS is SEQUENTIAL.
STREAM is part of the Fortran 2003 Standard and is similar to FTN95 TRANSPARENT access. When compared with DIRECT, STREAM uses POS in place of REC and has a fixed RECL value which for FTN95 is one. The Fortran 2003 intrinsic NEW_ LINE can be used within an WRITE statement. It returns a CHARACTER result which for FTN95 is CHAR(10) and is translated to CHAR(13) then CHAR(10) in the output file.

FORM=<string>
<string>is a character expression (typically a constant), whose value is FORMATTED, UNFORMATTED or PRINTER when any trailing blanks are removed.
FORM specifies whether the data transfer to and from the program will be formatted, unformatted or in line printer format.
If the specifier is omitted, FORMATTED is assumed if the file is being connected for sequential access and UNFORMATTED is assumed if the file is being connected for direct or transparent access (see the ACCESS specifier above).
FORM=PRINTER is an extension to the ANSI Standard, and specifies that the first column of any output record is taken as a Fortran carriage control character.
The Fortran carriage control characters are as follows:

Character | Vertical Spacing before printing
Blank | One line
0 | Two lines
1 | To first line of next page
+ | No advance

Carriage return, linefeed, and form feed control characters are output as necessary to give the effects above.
Note that FORM=PRINTER is only appropriate for files on which output only is performed.
For ACCESS = TRANSPARENT and FORM= FORMATTED, no carriage returns are output at the end of record on output (the user can output carriage returns with the "/" editing descriptor), and on input precisely the field widths specified in the input format are read, with no attempt to align to record boundaries (i.e. after carriage returns).
For ACCESS = TRANSPARENT and FORM = UNFORMATTED, on output the values in the I/O list are output to file in their internal format, with no surrounding record structure (unlike sequential unformatted). Similarly, on input, the values in the input list are read in direct from file, without any record structure. This gives a Fortran binding for applications which would previously have called the I/O primitive subroutines OPENR@, OPENW@, READF@, WRITEF@ etc. directly.

ACTION=<string>
<string> specifies that READ, WRITE or READWRITE operations will be allowed on the file. The default is READWRITE.

BLANK=<string>
This option may only appear for files being connected for formatted input/output. <string> is a string which when the trailing spaces are removed is either NULL or ZERO. The default is NULL. If NULL, then all spaces in formatted numeric fields are ignored, if ZERO then spaces in formatted numeric fields are treated as zeros.

DELIM=<string>
<string> specifies the delimiter to be used in character constants. It is always one of APOSTROPHE , QUOTE or NONE. The default is NONE.

PAD=<string>
<string> specifies whether input records are space padded. The value is either YES or NO. The default is YES.

POSITION=<string>
<string> is a character expression that, when trailing spaces have been removed, is ASIS , REWIND or APPEND.

RECL=<value>
<value> is an integer expression, which gives record length in bytes. For direct access files, this specifier is obligatory.
As an extension to the standard, RECL may also be specified for a file opened for sequential access. This causes fixed length records to be read from or written to file and allows a BACKSPACE to be followed by a WRITE.

STATUS=<string>
<string> is a character expression which, when trailing spaces are removed, gives the value OLD, NEW, REPLACE, SCRATCH or UNKNOWN.

The following options for <string> are not in the ANSI Standard:

'APPEND'
A FILE= specifier must also be used. 'APPEND' is allowed for both formatted and unformatted files opened for sequential access. Output is appended to <filename> if it exists - if <filename> does not exist, it will be created.

'MODIFY'
A FILE= specifier must also be used - <filename> need not exist. If <filename> does not exist, 'MODIFY' is equivalent to 'NEW'. If <filename> exists, 'MODIFY' causes the existing file to be truncated and overwritten.

'READONLY'
A FILE= specifier must also be used and <filename> must exist. READONLY status ensures that any attempt to write a record to <filename> causes a run-time error. It also enables a file to be opened for reading more than once.

SHARE=<access mode>
The operating system provides a means whereby a program, when opening a file, can define the access that other programs are allowed to a file for the period that the first program has the file open.

This file sharing mechanism applies for multiple instances of the same file opened by a particular program, for two or more programs running on the same machine, or by two or more programs running on different machines (e.g. access via a shared disk on a network).

When a program opens a file, it can specify that it requires read access, write access, or read and write access. In addition to this, it can specify the <access mode> that other programs are permitted while it still has the file open.

<access mode> is a character expression whose value is one of the following:

'COMPAT' | Compatibility mode - equivalent to opening the file with no sharing attributes. No other program will be able to access the file while this program has it open.
'DENYRW' | Exclusive - no other program can access the file while it is open.
'DENYWR' | Other programs cannot access the file for write or read/write access, but can open the file for read only access.
'DENYRD' | Other programs cannot access the file for read or read/write access, but can open the file for write only access.
'DENYNONE' | Other programs can access the file for read, write or read/write access.

Note that a second or subsequent program attempting to open the file will be denied access in all cases if it attempts to open the file in compatibility mode. All attempts to open a file that may be in use by another program must use one of the other modes, and thereby must specify the access to be granted to other programs trying to access the file subsequently.

DRIVER=<string>
DRIVER is an extension to the ANSI Standard. <string> is the name of a subroutine which has been previously declared in an EXTERNAL statement. If DRIVER= appears, then FILE=, FILETYPE= and STATUS= must not appear. For further information see the FTN77 User's Guide available in PDF form on the Silverfrost website.

FILETYPE=<string>
FILETYPE is an extension to the ANSI Standard. If FILETYPE='TTY', input and output is read from the keyboard and written to the screen via the appropriate unit number.
By default trailing spaces are removed when writing a string to a file. To avoid this effect use FILETYPE='FSU'.
Note that other devices such as LPT1 may be available by simply opening 'files' of the corresponding name. For example, to write directly to the printer from unit 6 it is often possible to execute: OPEN(UNIT=6,FILE='LPT1').

Reading tab characters
In an FTN95 READ statement, by default, tab characters read from a file are converted to spaces. To avoid this conversion you should make a call to the subroutine READ_TABS@(unitno) immediately after the OPEN statement (unitno is the unit number of the stream).


CLOSE

The CLOSE statement is used to disconnect a file which has been connected with OPEN. It has the following specifiers associated with it:

UNIT=<value>
<value> is the unit number. The keyword and equals sign are optional if this is the first specifier in the list.

IOSTAT=<variable>
<variable> specifies an integer variable into which the input/output status will be written. A positive value will be written on error, zero otherwise.

ERR=<label>
<label> specifies a label to jump to in the event of an error.

STATUS=<string>
<string> is either 'KEEP' or 'DELETE'. The default for named files is 'KEEP', for scratch files is 'DELETE'.


INQUIRE - file or unit

The INQUIRE statement is used to find out the properties of a particular named file or of the connection or availability of a particular unit. The INQUIRE statement may be executed before, while or after a file is connected to a unit. All values assigned by the INQUIRE statement are those that are current at the time of the statement. It has the following specifiers associated with it:

UNIT=<value>
<value> specifies the unit number for INQUIRE by unit. The keyword and equals sign are optional if this is the first specifier in the list.

FILE=<string>
<string> specifies the filename for INQUIRE by name. UNIT must not be used if is used and vice-versa.

IOSTAT=<variable>
<variable> specifies an integer variable into which the input/output status may be written.

ERR=<label>
<label> is a label to jump to in the event of an error.

EXIST=<variable>
<variable> specifies a logical variable that will be set true if the file or unit exists, otherwise false.

OPENED=<variable>
<variable> specifes a logical variable which will be set true if a connection exists to the file or logical unit number, otherwise false.

NUMBER=<variable>
<variable> is the variable into which the unit number attached to the file is written, or -1 if the file is not attached to a unit.

NAMED=<variable>
<variable> is set to true if the specified file is named, otherwise false.

NAME=<variable>
<variable> will contain the name of the file (if named) or undefined.

ACCESS=<variable>
<variable> will contain the access type for which the unit or file is opened. This will be SEQUENTIAL, DIRECT or UNDEFINED.

SEQUENTIAL=<variable>
<variable> will contain YES, NO or UNKNOWN depending on whether the file or unit is opened for sequential access.

DIRECT=<variable>
<variable> will contain YES, NO or UNKNOWN depending on whether the file or unit is opened for direct access.

FORM=<variable>
<variable> will contain FORMATTED or UNFORMATTED depending on the connection to the file or unit.

FORMATTED=<variable>
<variable> will contain YES, NO or UNKNOWN depending on whether the file or unit is opened for formatted file operations.

UNFORMATTED=<variable>
<variable> will contain YES, NO or UNKNOWN depending on whether the file or unit is opened for unformatted file operations.

RECL=<variable>
<variable> will contain the maximum record length for a formatted or unformatted file, or undefined if there is no connection.

NEXTREC=<variable>
In direct access files, <variable> will contain one more than the last record number read (records start at 1) or undefined if the position is not known.

BLANK=<variable>
<variable> will contain 'NULL', 'ZERO' or 'UNDEFINED', depending on the connection to the unit number or file.

POSITION=<variable>
<variable> will contain 'REWIND', 'APPEND', 'ASIS' or 'UNDEFINED' depending on the connection to the unit or file.

ACTION=<variable>
<variable> will contain 'READ', 'WRITE', 'READWRITE' or 'UNDEFINED' depending on the connection to the unit or file.

READ=<variable>
<variable> will contain 'YES', 'NO' or 'UNKNOWN' depending on the connection to the unit or file.

WRITE=<variable>
<variable> will contain 'YES', 'NO' or 'UNKNOWN' depending on the connection to the unit or file.

READWRITE=<variable>
<variable> will contain 'YES', 'NO' or 'UNKNOWN' depending on the connection to the unit or file.

DELIM=<variable>
<variable> will contain 'APOSTROPHE', 'QUOTE', 'NONE' or 'UNDEFINED' depending on the connection to the unit or file.

PAD=<variable>
<variable> will contain 'YES' or 'NO' depending on the connection to the unit or file.


INQUIRE - input/output list

The second use of INQUIRE is to find the length of an unformatted input/output list. When used for this purpose, INQUIRE has the following single specifier:

IOLENGTH= <variable>
<variable> will contain the length of an unformatted input/output list.


BACKSPACE

Execution of a BACKSPACE statement causes the disc file connected to the specified unit to be positioned before the preceding record. If there is no preceding record, the position of the file is unchanged. If the preceding record is an endfile record, the file is positioned before the endfile record.

You cannot backspace over a record that has been written using list-directed formatting.

The following specifiers are associated with the BACKSPACE statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if this is the first item in the list. If unit number is the only argument, the brackets around the argument list are optional.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error.

ERR=<label>
<label> specifies a label to go to in the event of an error.


REWIND

Execution of a REWIND statement causes the specified disc file to be positioned at its initial point.

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if this is the first item in the list. If unit number is the only argument, the brackets around the argument list are also optional.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error.

ERR=<label>
<label> specifies a label to go to in the event of an error.


ENDFILE

Execution of an ENDFILE statement causes an end-of-file (EOF) record to be written to the specified disc file.

UNIT= <value>
<value> specifies the unit number. The keyword is optional if it is the first item in the list. If the unit number is the only argument, the brackets around the argument list are optional.

IOSTAT= <variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error.

ERR= <label>
<label> specifies a label to go to in the event of an error.


READ - internal

The READ statement can be used to input data from internal files. When used for this purpose, the specifiers associated with it are as follows:

UNIT= <string>
<string> is a character variable. The keyword and equals sign are optional if it is the first item in the list.

FMT= <string, label or *>
Specifies the format in which the data will be read. The keyword and equals sign are optional if this is the second item in the list of specifiers.

IOSTAT= <variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR= <label>
<label> specifies a label to go to in the event of an error.

END= <label>
<label> specifies a label to go to on end of file.


READ - namelist

Read a file using a namelist.

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the specifier list.

NML=<namelist-group-name>
The keyword and equals sign are optional if it is the second item in the specifier list.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.

END=<label>
<label> specifies a label to go to on end of file.


READ - sequential formatted

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional, if this is the first item in the list of specifiers.

FMT=<string, label or *>
Specifies the format in which the data will be read. The keyword is optional if this is the second item in the list of specifiers.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.

END=<label>
<label> specifies a label to go to on end of file.

ADVANCE=<string>
<string> should be set to 'NO' for non-advancing input, 'YES' or absent for advancing input.

SIZE=<variable>
<variable> will contain the number of characters actually read (non-advancing only).

EOR=<label>
<label> specifies a label to go to on end of record (non-advancing).

Reading tab characters
 In an FTN95 READ statement, by default, tab characters read from a file are converted to spaces. To avoid this conversion of tabs you should make a call to the subroutine READ_TABS@(unitno) immediately after the OPEN statement (unitno is the unit number of the stream).


READ - sequential unformatted

When READ is used to read data from sequential unformatted files, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the specifier list.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.

END=<label>
<label> specifies a label to go to on end of file.


READ - direct formatted

When READ is used to read data from direct formatted files, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the specifier list.

FMT=<string or label>
Specifies the format for the data to be read in. The keyword and equals sign are optional if this is the second item in the list.

REC=<value>
<value> specifies the record number to read from.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


READ - direct unformatted

When READ is used to read data from direct unformatted files, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if this is the first item in the list.

REC=<value>
<value> specifies the record number to read from.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


WRITE - internal

When WRITE is used to write data to an internal file, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the list.

FMT=<string, label or *>
Specifies the format for the data to be written. The keyword and equals sign are optional if it is the second item in the list.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


WRITE - namelist

Write a file using a namelist.

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the list.

NML=<namelist-group-name>
The keyword and equals sign are optional if this is the second item in the list.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


WRITE - sequential formatted

When WRITE is used to write data to a sequential formatted file, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if this is the first item in the list.

FMT=<string, label or *>
Specifies the format for the data to be written. The keyword and equals sign are optional if this is the second item in the list.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.

ADVANCE=<string>
<strings> equals 'NO' for non-advancing output, 'YES' or absent for advancing output.


WRITE - sequential unformatted

When WRITE is used to write data to a sequential unformatted file, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the list.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


WRITE - direct formatted

When WRITE is used to write data to a direct formatted file, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the list.

FMT=<string or label>
Specifes the format for the data to be written. The keyword and equals sign are optional if it is the second item in the list.

REC=<value>
<value> specifies the record number to start writing to.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


WRITE - direct unformatted

When WRITE is used to write data to a direct unformatted file, the following specifiers are associated with the statement:

UNIT=<value>
<value> specifies the unit number. The keyword and equals sign are optional if it is the first item in the list.

FMT=<string or label>
Specifies the format for the data to be written. The keyword and equals sign are optional if it is the second item in the list.

REC=<value>
<value> specifies the record number to start writing to.

IOSTAT=<variable>
<variable> will contain zero if the operation was successful, otherwise a positive value to indicate an error, -1 to indicate EOF or -2 to indicate EOR.

ERR=<label>
<label> specifies a label to go to in the event of an error.


Reading tabs characters

READ_TABS@

Reading tab characters
 In an FTN95 READ statement, by default, tab characters read from a file are converted to spaces. To avoid this conversion you should make a call to the subroutine READ_TABS@(unitno) immediately after the OPEN statement (unitno is the unit number of the stream).


FORMAT edit descriptors

The following specifiers are edit descriptors that can be used with the FORMAT statement. Generally, w represents an integer specifying the field width and m represents an integer specifying the number of digits to be displayed. Under Fortran 95, if w is set to zero, then the field width is automatically set to the minimum value that can be used.

I <w.m>
Integer

B <w.m>
Integer as binary

O <w.m>
Integer as octal

Z <w.m>
Integer as hexadecimal

F <w.d>
Real, fixed form

E <w.dEe>
Real, exponent form

EN <w.dEe>
Engineering notation (exponent is 0 or divisible by 3)

ES <w.dEe>
Scientific notation, non-zero significands are greater than or equal to 1.0 and less than 10.0 (see note below)

G <w.dEe>
General, for any intrinsic data type

L <w>
Logical

A <w>
Character

D <w.d>
Real (D used as exponent letter)

<w>H
Hollerith (obsolescent feature, should be avoided)

Note
ESw.d edit descriptors are explicitly restricted by the standard to numbers where the absolute value of the decimal exponent is less than 1000. If the decimal exponent of the number is outside of this range, then the decimal exponent is divided by 10 and preceded by a dollar sign "$" if positive and an equals sign "=" if negative. For example, if 1e2000 were written using ES12.3, the result would be "xxx1.000$200" where x is a space. If 1e-2000 were written using ES12.3, the result would be "xxx1.000=200" where x is a space. To avoid this situation use the ESw.dEe edit descriptor.


FORMAT control descriptors

The following specifiers are control descriptors that can be used with the FORMAT statement:

T<n>
Tab to position n, positions start at 1

TL<n>
Tab left n

TR<n>
Tab right n

<n>X
n spaces

<n>/
n new records. n can be omitted. The default value for n is 1.

S
Use default of SS and SP

SS
Suppress leading + signs

SP
Print leading + signs

<k> P
Set scale factor for E, F and G processing

BN
Interpret spaces as nulls

BZ
Interpret spaces as zeros


Re-entrant Output

FTN95 does not permit you to perform inline output as for example in....

INTEGER F
EXTERNAL F
PRINT*, F()
END

INTEGER FUNCTION F()
F = 1
PRINT*,"Result = ",F
END

However, a call to the FTN95 routine ENABLE_REENTRANT_IO@ enables you to perform inline output provided that it is to a different UNIT number...

INTEGER F
EXTERNAL F
CALL ENABLE_REENTRANT_IO@(.TRUE.)
PRINT*, F()
END

INTEGER FUNCTION F()
F = 1
OPEN(8,FILE="tmp")
WRITE(8,*) "Result = ",F
END


Business editing

FTN95 business editing is an extension to the standard that is intended for accounting programs in which the following features are desirable:

  • Filling of number fields, thus preventing subsequent modification, for example when printing cheques.

  • Suppression of leading zeros and plus signs.

  • Printing of trailing minus signs (an accounting convention).

  • Conversion of trailing minus signs to CR to indicate credit entries.

Business editing is controlled by the B edit descriptor which has the form:

B <string>

where <string> can contain the following characters:

+ - $ , * Z # . CR

For example:

WRITE(*,"(B'####')") 147

The field width is indicated by the number of characters in <string>. If the field width is too small for the number in question, then the output field will be filled with asterisks.

The characters have the following significance:

PLUS (+)
'FIXED SIGN': if the first character of <string> is a single plus (+), then the actual sign of the number (+ or -) is printed as the first character on the left in the output field.

'FLOATING SIGN': if there are multiple plus (+) signs at the beginning of <string>, then these will be replaced in the output field by printing characters and the actual sign of the number (+ or -) will be printed on the extreme left in the output field.

'TRAILING SIGN': this is the plus (+) sign on the extreme right of <string>. The actual sign (+ or -) of the number will be printed in that output field position.

MINUS (-)
This works in the same way as the PLUS sign. However, for a positive number a blank is printed instead of '+'. This is PLUS sign suppression.

DOLLAR SIGN ($)
A DOLLAR SIGN sign may not be preceded by anything except a fixed sign. 'FIXED DOLLAR' is a single dollar sign which will be printed in the corresponding position in the output number.

'FLOATING DOLLAR': these are multiple dollar signs which are replaced by printing digits in the output number. A single dollar sign will be printed as the first character on the left.

ASTERISK (*)
If the output number has a digit where there is an asterisk, this digit will be printed. Otherwise, an asterisk (*) will be printed - this is field filling. An asterisk may be preceded only by a fixed sign and/or a fixed dollar.

ZED (Z)
This indicates leading zero suppression. In other words, if the digit in the output number is a leading zero, it will not be printed and a blank space will appear instead.

NUMBER SIGN (#)
Digit positions indicated by #'s are not subject to leading zero suppression.

COMMA (,)
If a comma occurs in the asterisk field, then a "*" will be printed. If a comma is preceded by a significant character (which is not a sign or a dollar sign) then a "," will be printed in the output field. Otherwise, a blank space will be printed. Commas must follow any leading characters and preceed decimal points.

CREDIT (CR)
The characters CR may only appear as the last two characters of <string>. In the output "CR" will be printed following the number if it is negative, otherwise, two blanks will be printed.

DECIMAL POINT (.)
decimal point in the output number. The only characters allowed to follow the decimal point are #, CR or trailing signs.

The examples in the table below illustrate the use of the B edit descriptor.

Number | B-Format | Output
147 | B'####' | 0147
14789 | B'####' | ****
0 | B'####' | 0000
147 | B'ZZZZ' | 147
1478 | B'ZZZZ' | 1478
0 | B'ZZZZ' |
0 | B'ZZZ#' | 0
6.089 | B'#.##' | 6.09
0 | B'#.##' | 0.00
9876.34 | B'ZZZ,ZZZ,ZZ#.##' | 9,876.34
987654.34 | B'ZZZ,ZZZ,ZZ#.##' | 987,654.34
0 | B'ZZZ,ZZZ,ZZ#.##' | 0.00
8 | B'+###' | +008
-8 | B'+###' | -008
8 | B'-ZZ#' | 8
-8 | B'-ZZ#' | - 8
126 | B'ZZZZZ+' | 126+
-126 | B'ZZZZZ+' | 126-
126 | B'ZZZZZ-' | 126
-126 | B'ZZZZZ-' | 126-
45678 | B'ZZZ,ZZ#CR' | 45,678
-45678 | B'ZZZ,ZZ#CR' | 45,678CR
308 | B'+++,++#.##' | +308.00
-308 | B'+++,++#.##' | -308.00
99 | B'$ZZZZZZ#' | $ 99
99 | B'$$$$$$$#' | $99
308126 | B'$***,***,**#.##' | $****308,126.00


Other Extensions

Line-printer carriage control characters

The Fortran standard defines the following:

+ | remain on the same line (overprint)
0 | double line space
1 | advance to the beginning of the next page

In addition, FTN95 uses:

- (minus)

double line space

Printing to a device

FTN95 permits you to write directly to a given device. For example,

OPEN(UNIT=8, FILE='LPT1:')
WRITE(8, '(A)') 'Output to printer'
CLOSE(8)


Kind parameters for intrinsic types

This section lists the KINDs associated with each of the intrinsic types, and some information about each KIND.

Logical KINDs

Integer KINDs

Real KINDs

Complex KINDs


Logical KINDs

 | Default | 8 bit | 16 bit | 32 bit
Kind Number | 3 | 1 | 2 | 3


Integer KINDs

 | Default | int8 | int16 | int32 | int64
Kind Number | 3 | 1 | 2 | 3 | 4
Digits | 31 | 7 | 15 | 31 | 63
Radix | 2 | 2 | 2 | 2 | 2
Range | 9 | 2 | 4 | 9 | 18
Huge | 2147483647 | 127 | 32767 | 2147483647 | 9223372036854775807
Bit Size | 32 | 8 | 16 | 32 | 64


Real KINDs

 | Default | Single | Double | Extended (Win32 only)
Kind Number | 1 | 1 | 2 | 3
Digits | 24 | 24 | 53 | 64
Max Exponent | 128 | 128 | 1024 | 16384
Min Exponent | -125 | -125 | -1021 | -16381
Precision | 6 | 6 | 15 | 18
Radix | 2 | 2 | 2 | 2
Range | 37 | 37 | 307 | 4931
Epsilon | 1.1920929E-07 | 1.1920929E-07 | 2.2204460E-16 | 1.0842022E-19
Tiny | 1.1754944E-38 | 1.1754944E-38 | 2.2250739E-308 | 3.3621031E-4932
Huge | 3.4028235E+38 | 3.4028235E+38 | 1.7976931E+308 | 1.1897315E+4932


Complex KINDs

 | Default | Single | Double | Extended (Win32 only)
Kind Number | 1 | 1 | 2 | 3
Precision | 6 | 6 | 15 | 18
Range | 37 | 37 | 307 | 4931


Language extensions

The list of extensions below is only available the /ISO compiler option has not been specified. This is a subset of the FTN77 Fortran extensions as some FTN77 extensions are now part of the Fortran 95 standard (e.g. B, O and Z format descriptors) or are due to be incorporated into a future Fortran standard (e.g. conditional compilation).

Hollerith data anywhere in source (not just in FORMAT strings)

Use of @ and $ characters in names and common block names

Octal, hexadecimal and binary constants outside of DATA statements

FTN77 compatible WHILE statement

Internal procedures

Conditional compilation

Business editing

In-line 32-bit assembler

Miscellaneous Input/Output Extensions


Hollerith data

Hollerith data is not part of the Fortran standard although it was included in Fortran 66. In FTN95 they have been implemented as extensions to the Standard for compatibility with FTN77. Occurrences of Hollerith data are flagged as a warning by the compiler. New programs should not use these two extensions.

Note: Hollerith editing in formats is still part of the Standard.

For example:

10 FORMAT(4HFRED)

is equivalent to:

10 FORMAT('FRED')

Hollerith data is stored as two 8-bit characters per word, any unused character positions being blank-filled.

The number of characters contained by each type of variable is as follows:

Type

Number of
Hollerith
Characters

INTEGER(KIND=1)
LOGICAL(KIND=1)

1

INTEGER(KIND=2)
LOGICAL(KIND=2)

2

INTEGER(KIND=3)
LOGICAL(KIND=3)
REAL(KIND=1)

4

REAL(KIND=2)

8

REAL(KIND=3)

10

Hollerith data is allowed in FTN95 as follows:

  1. In DATA statements for variables and arrays of type INTEGER and REAL. For example:

      REAL(2)
                :: A(3)
INTEGER(3) :: IB(2)
DATA A/24HABCDEFGHIJKLMNOPQRSTUVWX/
DATA IB/8H01234567/

Note that apostrophes can be used as an alternative to the nH form.

  2. As data read by READ and WRITE statements; for example:

      READ(1,10)I
 10   FORMAT(A2)

An Aw edit descriptor is used to specify that ASCII characters are to be read into or written from the specified variables which may be of type INTEGER, REAL, DOUBLE PRECISION or LOGICAL. FTN95 allows the form A (alone) where w is assumed to be the number of ASCII characters that will fit into the variable in the input/output list. For example:

      INTEGER(2)
                :: I
REAL(1) :: R
LOGICAL(3) :: L
READ(1,10)I,R,L
10   FORMAT(3A)

would read, from a single record, 2 characters into I, 4 characters into R and 4 characters into L.

  3. In assignment statements where the left hand side is an arithmetic variable or array element, for example:

      I = 'AB'
      R = '1234'

Note the use of apostrophes in these examples.

  4. In subroutine calls or function references, for example:

      CALL PIANO(5HFORTE)
      I = RS(1HA,8)

A run-time error will be generated when using the compile-time option /CHECK, if a Hollerith string is passed as an actual routine argument and the corresponding dummy argument is not of type CHARACTER.


Use of @ and $ characters in names

It is often useful to be able to name a subroutine or common block in such a way that it will not clash with names chosen by everyday use of the compiler. FTN95 allows the @ and $ characters as any non-initial character of a Fortran name.

Example:

      SUBROUTINE PRINT$(I)
      COMMON/COM@/A,B,C(100)
      EXTERNAL F1@,F2@
      INTEGER F1@
      . . .
      CALL MY_SUB(F1@)
      . . .

No guarantee can be given that use of a name containing an @ character will not cause unpredictable results as a result of a clash with an FTN95 library name or other reserved name. However, no system name contains a $ character.


Octal, hexadecimal and binary constants

FTN95 permits the use of B, O and Z constants anywhere in a program (the standard specifies these should only appear in DATA statements.) To specify the size of the constant, a kind specifier should appear after the constant, e.g. "Z'7F'_1" is an INTEGER(KIND=1) constant.


WHILE statement

For compatibility with FTN77, FTN95 offers an alternative WHILE statement. Its general form is

WHILE (logical expression) DO
. . . .
ENDWHILE

The WHILE-block may contain any executable Fortran statements. WHILE-blocks may be nested within each other or within IF-, ELSE-, and ELSEIF-blocks and/or DO statements. The rules of nesting are the same as those for the IF construct.

An ENDWHILE statement can be labelled but may only be referenced from within the WHILE block.

Example:

J = 0
WHILE(I.NE.0)DO
 I = LIST(I)
  J = J+1
ENDWHILE


Internal procedures

FTN95 provides internal procedures to allow even a few lines of coding to be used as a "subroutine" without the run-time overhead that a CALL statement produces. These are mainly provided for compatibility with FTN77, since Fortran 95 allows internal sub-programs via the CONTAINS statement, although internal procedures are still useful in run-time sensitive code.

As its name suggests, an internal procedure is local to the program unit in which it appears. FTN95 provides three statements to deal with internal procedures, and extends the use of the EXIT statement:

INTERNAL PROCEDURE <list of int-proc-names>

INVOKE <int-proc-name>

PROCEDURE <int-proc-name>

EXIT <int-proc-name>

The INTERNAL PROCEDURE statement

INTERNAL PROCEDURE is a specification statement and must appear before any executable statement in a program unit. The general form is:

INTERNAL PROCEDURE <list of int-proc-names>

where <list of int-proc-names> is a list of internal procedure names separated by commas. Every internal procedure name used in a program unit must first appear in an INTERNAL PROCEDURE statement.

The PROCEDURE statement

The PROCEDURE statement is used to define the start of an internal procedure. It has the form:

PROCEDURE <int-proc-name>

An internal procedure has no argument list; any local or external name available to the program unit in which the internal procedure appears is available for use within the procedure.

Note:
When defining an internal procedure, it is up to the programmer to ensure that there is no possibility of control "flowing into" the procedure. It is suggested that internal procedure definitions are grouped together following a RETURN or GOTO statement at the end of a program unit, for example:

. . .
RETURN
PROCEDURE P1
. . .
PROCEDURE P2
. . .
END

The EXIT statement

The EXIT statement is used to exit from an internal procedure. It may appear anywhere in an internal procedure definition and takes the form:

EXIT <int-proc-name>

An EXIT statement can appear wherever an executable statement is allowed (for example, at the end of an IF statement).

Care should be taken to ensure that the name of the internal procedure is not the same as any construct-label in the routine otherwise the EXIT statement could be ambiguous.

The only effect of an EXIT statement is to transfer control to the statement following the INVOKE statement used to invoke the internal procedure.

More than one EXIT statement can appear in an internal procedure definition. The EXIT statement need not necessarily be the last statement in a definition so that remarks made at the end of the previous section again apply here.

A program may also exit an internal procedure by executing a RETURN statement, which also leaves the parent routine.

The INVOKE statement

The INVOKE statement is used to "call" an internal procedure. It has the general form:

INVOKE <int-proc-name>

and can appear anywhere that an executable statement is allowed. The only effect of an INVOKE statement is to transfer control to the specified internal procedure.

Example of the use of an internal procedure

INTERNAL PROCEDURE ERROR
. . .
N = 7
INVOKE ERROR
. . .
N = 80
INVOKE ERROR
. . .
PROCEDURE ERROR
IF (N.LT.50) THEN
CALL ERROR1(N)
ELSE
 CALL ERROR2(N)
ENDIF
EXIT ERROR
. . .
END


Conditional compilation

Silverfrost Conditional compilation

FTN95 provides conditional compilation by means of the SPECIAL PARAMETER statement together with the /SPARAM and /VPARAM compile-time options and the CIF, CELSE and CENDIF statements.

SPECIAL PARAMETER statement

The specification statement

SPECIAL PARAMETER <name>

defines <name> to be of type integer. <name> must not appear in a type statement and is local to the program unit in which the SPECIAL PARAMETER statement appears. The value represented by <name> is set by means of the /SPARAM or /VPARAM compile-time option as follows:

/SPARAM <integer>

where <integer> is the required value.

Any number of SPECIAL PARAMETER names are allowed per program unit but they are all assigned the same value when used with /SPARAM. The alternative is:

/VPARAM <name> <integer>

which allows individual values to be assigned by name rather than assigning one value to all. A value assigned by /VPARAM over-rides a value assigned by /SPARAM.

CIF, CELSE and CENDIF

CIF, CELSE and CENDIF are used to select the statements in a program unit that are to be used during a particular compilation. Their general forms are:

CIF (<name> <op> <constant>) THEN
. . .
CELSE
. . .
CENDIF

where <name> is a SPECIAL PARAMETER, <op> is one of the arithmetic relational operators (.EQ.,.LT., etc. or their equivalents ==, < etc.) and <constant> is an integer constant. In fixed format, CIF etc. begin in column 7 or after.

CIF and CENDIF must appear in pairs: their appearance constitutes a CIF-block.

The actual value assigned to the special parameter <name> is compared with the integer constant <constant>. If the two agree, the statements following CIF are compiled until a CELSE or CENDIF statement is found.

If the two disagree, statements are ignored until a CELSE or CENDIF statement is encountered. Such statements are denoted by a back-slash character in the listing file.

Once CENDIF is encountered, the CIF-block is complete. CELSE causes the reverse effect to that specified by the preceding CIF statement.

CIF..CENDIF blocks can be nested and CELSEIF may be used to replace the sequence CELSE, CIF,.....CENDIF as in the Fortran IF construct.

SPECIAL PARAMETERS can be assigned using /SPARAM, /VPARAM or by using a standard Fortran PARAMETER statement. Values that are not set, default to zero. If /SPARAM and /VPARAM are not used, then /FPP must be included in the compiler command line in order to invoke the preprocessor (note that /FPP is included in /CLR).

As a special case, the form

CIF (<name>) THEN
. . .

can be used where <name> is assigned to 1 (unity, representing TRUE) or to zero (representing FALSE).

The additional features described in Conditonal compilation and detecting .NET at runtime can also be used on a Win32 platform.

Compiler defined values

FTN95 recognises the following parameters: _WIN32, _WIN64, _CLR, _DEBUG, and _FTN95_VER.

For example,

   CIF(_WIN64)
   PRINT*, "64 bit compilation"
  CENDIF

  CIF(_FTN95_VER == 870)
   PRINT*, "Version 8.70"
  CENDIF

_CLR corresponds to /CLR (i.e. .NET compilation) and _DEBUG to /DEBUG.


Conditional compilation

C-Style Conditional Compilation

Alongside Silverfrost Conditional Compilation, FTN95 also offers a C-Style pre-processor. This processor makes use of the standard #if..#endif style of pre-processor directives. This pre-processing operates alongside the Silverfrost pre-processor and is not affected by its use. It is invoked by the use of

/CFPP

on the command line. The command line switches:

/VPARAM <name> <integer>
/DEFINE <name> <integer>

Can be used in conjunction with /CFPP to define values that can be used subsequently within conditional statements. Only integer values are accepted and used as part of the two statements above. Values set as part of these statements can be used interchangeably, that is a value defined by /DEFINE can be compared against one defined with /VPARAM.

The pre-processor can only be used for conditional compilation. Macro substitution is not supported.

#if..#ifdef..#ifndef..#elif..#else..#endif blocks are used to determine which portions of source code should be compiled depending on the logical result of expressions contained within the pre-processor statements

Pre-processor Statements

The following pre-processor statements are supported by FTN95:

#if (constant-expression)
#ifdef (param-name)
#ifndef (param-name)
#elif (constant-expression)
#else
#endif
#define (param-name) [(param-value)]
#undef (param-name)
#error (string)
#warning (string)
#include (quoted file name)

Nested single line statements may be constructed such as:

#if MACRO1 && (defined (MACRO2) || MACRO3 > 10)

Statements can be nested over multiple lines also.

Line continuations are not permitted


Business Editing

FTN95 business editing is an extension to the standard that is intended for accounting programs in which the following features are desirable:

  • Filling of number fields, thus preventing subsequent modification, for example when printing cheques.

  • Suppression of leading zeros and plus signs.

  • Printing of trailing minus signs (accounting convention).

  • Conversion of trailing minus signs to CR to indicate credit entries.

Business editing is controlled by the B edit descriptor which has the form:

B'<string>'

where <string> can contain the following characters:

+ - $ , * Z # . CR

For example:

WRITE(*,"(B'####')") 147

The field width is indicated by the number of characters in <string>. If the field width is too small for the number in question, then the output field will be filled with asterisks.

The characters have the following significance:

PLUS (+)
'FIXED SIGN': if the first character of <string> is a single plus (+), then the actual sign of the number (+ or -) is printed as the first character on the left in the output field.

'FLOATING SIGN': if there are multiple plus (+) signs at the beginning of <string>, then these will be replaced in the output field by printing characters and the actual sign of the number (+ or -) will be printed on the extreme left in the output field.

'TRAILING SIGN': this is the plus (+) sign on the extreme right of <string>. The actual sign (+ or -) of the number will be printed in that output field position.

MINUS (-)
This works in the same way as the PLUS sign. However, for a positive number a blank is printed instead of '+'. This is PLUS sign suppression.

DOLLAR SIGN ($)
A DOLLAR SIGN sign may not be preceded by anything except a fixed sign. 'FIXED DOLLAR' is a single dollar sign which will be printed in the corresponding position in the output number.

'FLOATING DOLLAR': these are multiple dollar signs which are replaced by printing digits in the output number. A single dollar sign will be printed as the first character on the left.

ASTERISK (*)
If the output number has a digit where there is an asterisk, this digit will be printed. Otherwise, an asterisk (*) will be printed - this is field filling. An asterisk may be pre ceded only by a fixed sign and/or a fixed dollar.

ZED (Z)
This indicates leading zero suppression. In other words, if the digit in the output number is a leading zero, it will not be printed and a blank space will appear instead.

NUMBER SIGN (#)
Digit positions indicated by #'s are not subject to leading zero suppression.

COMMA (,)
If a comma occurs in the asterisk field, then a "*" will be printed. If a comma is preceded by a significant character (which is not a sign or a dollar sign) then a "," will be printed in the output field. Otherwise, a blank space will be printed. Commas must follow any leading characters and preceed decimal points.

CREDIT (CR)
The characters CR may only appear as the last two characters of <string>. In the output "CR" will be printed following the number if it is negative, otherwise, two blanks will be printed.

DECIMAL POINT (.)
decimal point in the output number. The only characters allowed to follow the decimal point are #, CR or trailing signs.

The examples in the following table illustrate the use of the B edit descriptor.

Number | B-Format | Output
147 | B'####' | 0147
14789 | B'####' | ****
0 | B'####' | 0000
147 | B'ZZZZ' | 147
1478 | B'ZZZZ' | 1478
0 | B'ZZZZ' |
0 | B'ZZZ#' | 0
6.089 | B'#.##' | 6.09
0 | B'#.##' | 0.00
9876.34 | B'ZZZ,ZZZ,ZZ#.##' | 9,876.34
987654.34 | B'ZZZ,ZZZ,ZZ#.##' | 987,654.34
0 | B'ZZZ,ZZZ,ZZ#.##' | 0.00
8 | B'+###' | +008
-8 | B'+###' | -008
8 | B'-ZZ#' | 8
-8 | B'-ZZ#' | - 8
126 | B'ZZZZZ+' | 126+
-126 | B'ZZZZZ+' | 126-
126 | B'ZZZZZ-' | 126
-126 | B'ZZZZZ-' | 126-
45678 | B'ZZZ,ZZ#CR' | 45,678
-45678 | B'ZZZ,ZZ#CR' | 45,678CR
308 | B'+++,++#.##' | +308.00
-308 | B'+++,++#.##' | -308.00
99 | B'$ZZZZZZ#' | $ 99
99 | B'$$$$$$$#' | $99
308126 | B'$***,***,**#.##' | $****308,126.00


IEEE Standard 754 Special Floating Point Numbers

The following sample code illustrates how special floating point values can be managed in FTN95:

SUBROUTINE SpecialNumber(in, out)
CHARACTER(LEN=*) in
DOUBLE PRECISION out
out = 0.0D0
CALL UPCASE@(in)
SELECT CASE(in)
 CASE("MINUS_ZERO")
  DCORE8(LOC(out)) = Z'8000000000000000'D
 CASE("MINUS_INFINITY")
  DCORE8(LOC(out)) = Z'FFF0000000000000'D
 CASE("PLUS_INFINITY")
  DCORE8(LOC(out)) = Z'7FF0000000000000'D
 CASE("NOT_A_NUMBER")
  DCORE8(LOC(out)) = Z'FFFFFFFFFFFFFFFF'D
 CASE("UNDEFINED")
  DCORE8(LOC(out)) = Z'8080808080808080'D
END SELECT
END

LOGICAL FUNCTION IsSpecialNumber(in, val)
CHARACTER(LEN=*) in
DOUBLE PRECISION val
LOGICAL res
res = .FALSE.
CALL UPCASE@(in)
SELECT CASE(in)
 CASE("MINUS_ZERO")
  res = CORE4(LOC(val)+4)==Z'80000000'.AND.CORE4(LOC(val))==0
 CASE("MINUS_INFINITY")
  res = CORE4(LOC(val)+4)==Z'FFF00000'.AND.CORE4(LOC(val))==0
 CASE("PLUS_INFINITY")
  res = CORE4(LOC(val)+4)==Z'7FF00000'.AND.CORE4(LOC(val))==0
 CASE("NOT_A_NUMBER")
  res = CORE4(LOC(val)+4)==Z'FFFFFFFF'.AND.CORE4(LOC(val))==Z'FFFFFFFF'
 CASE("UNDEFINED")
  res = CORE4(LOC(val)+4)==Z'80808080'.AND.CORE4(LOC(val))==Z'80808080'
END SELECT
IsSpecialNumber = res
END

PROGRAM test
 DOUBLE PRECISION val
 LOGICAL IsSpecialNumber
 CALL SpecialNumber("MINUS_INFINITY",val)
 IF(IsSpecialNumber("MINUS_INFINITY",val)) PRINT*,"OK"
END


Extended ALLOCATE statement

FTN95 allows you to access memory that was created in another process. The keyword SHARENAME is provided as an FTN95 extension to the standard ALLOCATE command in order to create memory in one process that can be accessed from another. The same keyword can also be used to create a file mapping.

FTN95 also allows you to access memory that was created elsewhere in the same process via the keyword ABSOLUTE_ADDRESS as descibed below.

Sharing memory between different processes

In the following illustration we create two programs that share common memory. The two programs (called shareA and shareB) are listed below. After compiling the programs using FTN95, the operation is as follows...

1. Start up program shareA.
2. Start up program shareB in a separate Command Prompt window.
3. Type a message as input into the instance of shareA.
4. View the same message as it appears as output in instance of shareB

The two programs use a common semaphore in order to synchronise the events.

Here is the code for shareA.f90...

include <windows.ins>
integer(2) c
character,pointer::msg*80
  allocate(msg, SHARENAME="MyMemory")
  print*, "Type a message to send. Do not use spaces..."
  read*, msg
  call SIGNAL_SEMAPHORE@("MySemaphore")
  print*, "Read the message then press any key to terminate"
  call get_key@(c)
end

Here is the code for shareB.f90...

include <windows.ins>
integer(2) c
character,pointer::msg*80
  allocate(msg, SHARENAME="MyMemory")
  print*, "Waiting for message..."
  call WAIT_ON_SEMAPHORE@("MySemaphore")
  print*, msg(1:len_trim(msg))
  print*, "Press any key to terminate"
  call get_key@(c)
end

File mapping

FTN95 also provides for the file-mapping of memory using the same keyword SHARENAME.

Here is some sample code to illustrate how it works. When you run the following program, the relevant file is created on the first run and there is no output. On the second run, the file now exists and its content is output.

character,pointer::msg*80
character(*),parameter:: myData = "C:\TechSupport\test.dat"
logical file_exists@, exists
exists = file_exists@(myData)
allocate(msg, SHARENAME=myData)
if(.NOT. exists) then
  msg = "Data created!"
else
  print*, msg
endif
end

If the drive letter for the path is lower case then the file is mapped for reading only. A file mapping occurs when the second character of the SHARENAME is a colon, otherwise you get inter-process shared memory without file mapping.

De-allocating SHARENAME memory

By default the system releases shared memory when all processes accessing that memory have terminated. In exceptional circumstances you may wish to call DEALLOCATE for this memory allocation, in which case you must first call the subroutine ENABLE_DEALLOCATE@ (giving the name of the allocated variable) before calling DEALLOCATE.

ABSOLUTE_ADDRESS

For Win32 and x64 platforms, an FTN95 ALLOCATE statement can take the keyword argument ABSOLUTE_ADDRESS=addr where addr is the INTEGER KIND(7) address obtained from the LOC of some object. Here is an illustrative example.

INTEGER(7) addr
REAL x
REAL,ALLOCATABLE::this
addr = LOC(x)
ALLOCATE(this,ABSOLUTE_ADDRESS=addr)
x = 3.14159
PRINT*, this
END


Miscellaneous Input/Output Extensions

A $ or \ edit descriptor is provided to facilitate the output of requests to the screen, without generating a new line. The descriptor must terminate the format specification. The comma preceeding \ is optional (like it is with the / descriptor). For example:

     WRITE(*,100) K
100  FORMAT("Old K=",I5,"Enter new value",$)
     END


What's new in Fortran 95

The following topics describe the main differences between the Fortran 90 and the Fortran 95 standard. This information has been extracted from an article by Craig Dedo and is used with his permission.

FORALL

Nested WHERE Construct

PURE procedures

Elemental procedures

Improved initialisations

Automatic deallocation

New initialisation features

Remove conflicts with IEC 559

Minimum width editing

Namelist

CPU-TIME intrinsic subroutine

MAXLOC and MINLOC intrinsics

Deleted features

New obsolescent features

Language Tidy-ups


FORALL

The FORALL statement and construct and PURE procedures have been added to Fortran 95 to allow Fortran 95 programs to execute efficiently in parallel on multi-processor systems. These features allow the majority of programs coded in High Performance Fortran (HPF) to run on a standard conforming Fortran 95 processor with little change. Adding these features to Fortran 95 does not imply that a particular Fortran 95 processor is multi-processor.

The purpose of the FORALL statement and construct is to provide a convenient syntax for simultaneous assignments to large groups of array elements. The multiple assignment functionality it provides is very similar to that provided by the array assignment statement and the WHERE construct in Fortran 90. FORALL differs from these constructs in its syntax, which is intended to be more suggestive of local operations on each element of an array, and in its generality, which allows a larger class of array sections to be specified. In addition, a FORALL may invoke user-defined functions on the elements of an array, simulating Fortran 90 elemental function invocation (albeit with a different syntax).

FORALL is not intended to be a completely general parallel construct; for example, it does not express pipelined computations or multiple-instruction multiple-data (MIMD) computation well. This was an explicit design decision made in order to simplify the construct and promote agreement on the statement's semantics.


Nested WHERE Construct

The WHERE construct has been extended in order to provide for syntactic regularity with the FORALL construct. The FORALL construct allows for nested FORALL constructs.

Early implementation of some High Performance Fortran (HPF) processors included the nested WHERE construct. Use of these processors showed that the feature provided real value to customers.


PURE procedures

The purpose of PURE procedures is to allow a processor to know when it is safe to implement a section of code as a parallel operation. The freedom from side effects of a pure function assists the efficient implementation of concurrent execution and allows the function to be invoked concurrently in a FORALL without such undesirable consequences as nondeterminism. It also forces some error checking on functions used in a FORALL construct.


Elemental procedures

ELEMENTAL procedures provide the programmer with more powerful expressive capabilities and the processor with additional opportunities for efficient parallelisation.

Extending the concept of elemental procedures from intrinsic to user-defined procedures is very much analogous to, but simpler than, extending the concept of generic procedures from intrinsic to user-defined procedures. Generic procedures were introduced for intrinsic procedures in Fortran 77 and extended to user-defined procedures in Fortran 90. Elemental procedures were introduced for intrinsic procedures in Fortran 90 and, because of their usefulness in parallel processing, it is quite natural that they be extended to user-defined procedures in Fortran 95. ELEMENTAL procedures are PURE.


Improved initialisations

A significant number of useful applications will be facilitated by the ability to perform more complicated calculations when specifying data objects. Allowing a restricted class of non-intrinsic functions in certain specification expressions achieves this goal.


Automatic deallocation

Automatic deallocation of allocatable arrays provides a more convenient and less error prone method of avoiding memory leaks by removing the burden of manual storage deallocation for allocatable arrays.

The 'undefined' allocation status of Fortran 90 meant that an allocatable array could easily get into a state where it could not be further used in any way whatsoever. It could not be allocated, deallocated, referenced, or defined. The result was undefined if the array was used as the argument to the ALLOCATED function. Removal of this status provides the user with a safe way of handling unSAVEd allocatable arrays and permits use of the ALLOCATED intrinsic function to discover the current allocation status of the array at any time.


New initialisation features

The prime motivation for adding a means to specify default initialisation for objects of derived type is a desire to eliminate memory leakage, i.e., situations in which allocated memory becomes inaccessible. This can occur in applications that manipulate objects of derived type with pointer components.

Most memory leakage can be avoided if it is possible to specify that pointers be created with an initial status of disassociated.

This standard provides a new intrinsic function, NULL, with a single optional argument. NULL allows the initial status of a pointer to be specified as disassociated in declarations, structure constructors, or type definitions.

Several alternatives were considered and rejected for a variety of reasons. Most of these reasons involve the problem of disambiguating references to generic procedures; i.e., when a program invokes a generic procedure, which specific procedure is supposed to be invoked? Completely defining a pointer object before using it does not help with the disambiguation problem. Creating a NULL constant does not provide any way to specify the type and type parameters of the pointer that is returned. A NULL function with a MOLD argument provides these needed capabilities.

This language extension does not completely solve the memory leakage problem; for that, an automatic destructor is needed which would be invoked for local pointers and structures with pointer components when the procedure in which they are created terminates. Such a facility is not included in this standard; it could be provided automatically by a processor that strove to conserve allocatable memory.

Automatic pointer destructors were not included in this standard because the consequences of inaccessible pointers are not as serious as they are with allocatable arrays which become inaccessible. If a local, unSAVEd pointer is not deallocated and the program exits the procedure in which it is defined, the storage is not recoverable but the pointer is reusable.

For reasons of determinacy and portability, an object for which default initialisation is specified is not allowed to appear in a DATA statement. In traditional implementations, a compiler passes initialisation information for non-dynamic variables to a loader, which is frequently designed to handle object code from several Different languages. It would be difficult to guarantee that initialisation in a DATA statement would override the default initialisation specified in a type definition.


Remove conflicts with IEC 559

Edits to sections 4.3.1 and 7.1.7 removed conflicts in Fortran 90 with the IEC 559 (IEEE 754/854) standard. Previous Fortran standards appeared to prohibit certain numeric values and numeric operations which were valid when using IEC 559 arithmetic. Fortran 90 requires that the value of a positive zero be the same as that of a negative zero, whereas IEC 559 requires that they be different. Fortran 90 prohibits any mathematically invalid operation, whereas IEC 559 requires such operations to produce +Inf , -Inf or NaNs.

These conflicts were removed to allow processors the ability to implement more of the IEC 559 arithmetic model without violating the Fortran standard.


Minimum width editing

Certain edit descriptors have been extended to allow formatted output of numeric values, while minimising the amount of "white space" produced. This extension permits more information to be presented on a limited width display device (e.g. terminal), without concern about overflowing a user specified field width. Allowing a zero field width to be specified for the I, B, 0, Z and F edit descriptors provides this functionality. A field width specification of zero always specifies a minimum field width; it never specifies suppression of data output or an actual field width of zero.


Namelist

Although not described here, namelist input has been extended to allow comments to follow one or more object name / value pairs on a line. This allows users to document how a namelist input file is structured, which values are valid, and the meaning of certain values. Each line in the namelist input may contain information about name / value pairs. This additional information may improve the documentation of the input file.


CPU_TIME intrinsic subroutine

A new intrinsic subroutine CPU_TIME has been added. This feature is provided to allow the assessment of which processor resources a piece of code consumes during execution. This could be the execution of the whole program or only a small part of it. Additional purposes could be comparing different algorithms on the same computer or trying to discover which parts of a calculation on a computer are most expensive.


MAXLOC and MINLOC intrinsics

Fortran 90 specified the MAXLOC and MINLOC intrinsics with only ARRAY and MASK arguments. The High Performance Fortran (HPF) group added the DIM argument between the original two arguments for consistency with the MAXVAL and MINVAL intrinsics. An incompatibility between Fortran 90 and HPF results unless MAXLOC and MINLOC are specified as generic interfaces, each with two specific interfaces: the first matching Fortran 90 and the second adding a non-optional DIM argument as the second argument. The Fortran Standards Committee decided that Fortran 95 should allow the DIM and MASK arguments to be specified in either order. For consistency, this provision for DIM and MASK to be specified in either order was extended to the other intrinsics that have the same arguments. These intrinsics are MAXVAL, MINVAL, PRODUCT, and SUM.


Deleted features

Note that, with the exception of "branching to ENDIF", features deleted from the Fortran standard are still available in FTN95.

The list of deleted features is:

  • real and double precision DO control variables,

  • branching to an END IF from outside its block,

  • PAUSE statement,

  • ASSIGN, assigned GOTO, assigned FORMAT specifiers,

  • cH edit descriptor,


New obsolescent features

There are some new obsolescent features to be added to those brought over from Fortran 90. Although obsolete, these features are still supported by FTN95. They are:

  • real and double precision DO control variables,computed GOTO,

  • statement functions,

  • DATA statements amongst executables,

  • assumed-length character functions,

  • fixed form source,

  • assumed-size arrays (i.e. with '*' in the last dimension),

  • CHARACTER*< len > style declarations.


Language tidy-ups

Language tidy-ups are mainly concerned with ironing out ambiguities in the Fortran 90 standard and adding extra text to make matters clearer.


Introduction

An Overview of Fortran 95

Introduction | The form of a simple program | Structures | Character strings
 | Formula translation |  | Arrays
 | Formatted output |  | User-defined types
Flow control | IF construct |  | Pointers
 | IF statement |  | Dynamic storage allocation
 | CASE construct | Procedures | Functions
 | DO construct |  | Subroutines
 | Iterated DO construct |  | Arguments
 | GOTO |  | Interface statements
 | STOP | Modules | Introduction


Introduction

Fortran 95 Language Overview

This overview describes a recommended subset of free format Fortran 95. Obsolete and redundant features of earlier Fortran standards are omitted. Although these are omitted from this overview, FTN95 provides a full implementation of the standard and includes features from earlier standards that are deleted in the Fortran 95 standard.

The overview is not fully comprehensive. It does not include topics such as file input/output, KIND type attributes, DATA and PARAMETER statements.


Program Form

The form of a simple program

A simple program takes the form:

[PROGRAM name ]

statements

END [PROGRAM name]

Optional items are shown in square brackets.

Comments may be included as required, for example:

PROGRAM Prog1

PRINT *, "Welcome to FTN95" ! Output a simple message.

END PROGRAM Prog1


Formula translation

Fortran is designed for formula translation. Many elementary Fortran programs will include three components:

  1. The input of data which is stored as variables

  2. The evaluation of formulae using the input data

  3. The output of the results

Here is a simple example:

PROGRAM Prog2

INTEGER i,j

READ *,i

j=2*i+3

PRINT *,j

END PROGRAM Prog2

The next example is similar but uses REAL numbers:

PROGRAM Prog3

REAL x

WRITE(*,"(a)",ADVANCE="NO") "Enter a real number:"

READ *,x

PRINT *, "The result is:", x/3.0-0.9E6

END PROGRAM Prog3

In Fortran it is possible to use a variable without explicitly declaring its type. Variables that are not declared are assumed to be either INTEGER or REAL depending on the first letter in the name. However, the use of this implicit typing is not recommended. Moreover, if a variable name is spelled incorrectly, the implicit typing rule will cause the rogue variable to be declared leading to erroneous results. In order to avoid this happening, it is recommended that the implicit typing facility be switched off. To do this, include the statement IMPLICIT NONE before any type declarations.

Note: FTN95 can be configured so that IMPLICIT NONE is the default for all program units (see the compiler options /CONFIG and /IMPLICIT_NONE).


Formatted output

List directed input (using READ *) is adequate for most purposes. In contrast, list directed output (using say PRINT *) has its limitations. For example, when outputting REAL numbers, the programmer usually wants to control the number of significant figures that are presented. The next example shows how to do this.

PROGRAM Prog4

PRINT "( a , i2 , 4x ,a, f6.2 ,4x,a, e10.3 )", &

"Integer:",77,"Float",77.0,"Exponent",77.0

END PROGRAM Prog4

The output is:

Integer:77 Float: 77.00 Exponent: 0.770E+02


Flow control

The statements within a Fortran program are implemented in their natural order. Elementary programs of the kind discussed so far (containing input, formula translation and output) do not have the ability to apply conditions to the process or to repeat sections of the code. For this we need mechanisms for controlling the order and the conditions under which the statements are executed. This section describes such flow control constructs together with the IF statement, the first of which is the IF construct.


Assignment_statement

IF construct

A simple form for the IF construct is:

IF(logical_expression) THEN

statement_block 1

[ELSE

statement_block 2 ]

ENDIF

The ELSE section is optional. If the logical expression is true, the first block is executed, otherwise the second.

For example:

IF(x>0.0)THEN

 y=x

ELSE

 y=0.0

ENDIF

Logical expressions are formed using relational operators and logical operators knowing their order of precedence.

Logical expressions can be stored as mLOGICAL variables.

If the ELSE section consists of one IF construct, then ELSE and IF can be reduced to ELSEIF provided that one of the associated ENDIFs is deleted. Sometimes it is simpler to use a CASE construct.

IF constructs can be named. Optionally, the same name may be used after ELSE and after ELSEIF (expr) THEN.


Logical IF statement

IF statement

The general form for the IF statement is:

IF(logical_expression) simple_statement

For example the statement:

IF(x<0.0) x=-x

makes x positive.

Logical expressions are formed using relational operators and logical operators knowing their order of precedence .

Logical expressions can be stored as LOGICAL variables.

IF statements can be nested within one of the flow control constructs but not vice-versa.

Unlike flow control constructs, an IF statement can not be named.

For most purposes, an IF construct is preferred to an IF statement, even in simple cases. For example,

IF(x<0.0)THEN
x=-x
ENDIF

though less concise, scans more easily. The IF statement may, however, be preferred for use with the statements STOP, RETURN, EXIT and CYCLE.


CASE construct

The CASE construct provides an alternative to an IF construct containing multiple ELSEIFs. It takes the general form:

SELECT CASE(expression)
CASE(case_selector 1)
statement_block 1
CASE(case_selector 2)
statement_block 2
. . .
CASE DEFAULT
statement_block
END SELECT

CASE constructs can be named.

The expression provides a value upon which the selection is based and must be a scalar of type INTEGER, LOGICAL or CHARACTER.

CASE DEFAULT is optional and is not necessarily placed last. It provides for the situation where none of the given CASEs applies.

The case_selector values must be of the same type as expression. They contain a single constant value or a list of constant values. Ranges may also be used. For example:

!Month and Days are of type INTEGER
!Month has been assigned a value.
SELECT CASE(Month)
  CASE(4,6,9,11)
    Days=30
  CASE(1,3,5,7:8,10,12)
    Days=31
  CASE(2)
    Days=28
    !Code to test for a leap year
  CASE DEFAULT
    !Code to flag an error
END SELECT

A range takes the form CASE(low: high) where low or high (but not both) may be omitted. For example, if high is omitted then the condition becomes expression>low. For example:

SELECT CASE(n)
  CASE(:-1)
    Sign=-1 !if n<0
  CASE(0)
    Sign=0 !if n=0
  CASE(1:)
    Sign=1 !if n>0
END SELECT

Each case must be unique with no possible overlap.

In the case of a CHARACTER expression, it may represent a single character or a character string.


DO construct

There are two forms for the DO construct. The simple DO construct described here and the iterated DO construct described in the next topic.

A simple DO construct takes the form:

DO
statement_block
END DO

This causes the block of statements to be repeated. Typically, within the block of statements, there will be an IF statement of the form:

IF(logical_expression) EXIT

The EXIT statement causes control to pass to the statement following END DO.

The CYCLE statement is an alternative to EXIT. It causes control to pass to a point immediately after the last statement of the block, allowing repetition to continue.

DO constructs can be named. If a DO construct is named then the same name must be appended to the corresponding END DO and may optionally be appended to an enclosing EXIT or CYCLE. If DO constructs are nested, one within another, then a name attached to EXIT or CYCLE provides an extra degree of control.

A DO WHILE construct provides an alternative construction in the form:

DO WHILE(logical_expression)
statement_block
END DO

This is equivalent to:

DO
IF(.NOT.logical_expression) EXIT
statement_block
END DO


Iterated DO construct

The iterated DO construct takes the form:

DO variable=start_value, end_value [, increment]
statement_block
END DO

This is equivalent to:

variable=start_value
DO WHILE(variable <= end_value)
statement_block
variable=variable+increment
END DO

DO constructs can be named.

variable is an INTEGER variable, whilst start_value, end_value, and increment are INTEGER expressions. increment is optional and when omitted defaults to 1 (unity). increment may be negative in which case start_value>end_value. For example:

DO i=10,0,-2
  !Do something for i=10,8,6,4,2 and 0
END DO

EXIT and CYCLE can be used with all forms of the DO construct.


GOTO statement

GOTO

Any statement can be given a label in the form of an integer constant in the range 1 to 99999. A label must appear at the beginning of a line. It can have spaces before it and must have at least one space after it and before the statement. A line that is a continuation must not be labeled.

The form for the GOTO statement is:

GOTO label

GOTO statements should only be used in exceptional circumstances. For example:

  1. To exit from deeply nested flow constructs.

  2. To jump to one of a number of terminating error conditions at the end of a program or procedure.

Wherever possible, use an IF construct in preference to GOTO statements.


STOP statement

STOP

The form for the STOP statement is:

STOP [message]

message is optional and is a character string.

STOP causes a normal (successful) termination of the program. If present, the message is output to the standard output device. STOP does not flag an error condition to the operating system.

The terminating END of a PROGRAM implies STOP.


Structures

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Character strings

Introduction

The statements:

CHARACTER c
c="A"

declare c to be a single character and assigns the letter A to it.

The statements:

CHARACTER(LEN=20)::str
str="A test string"

declare str to be a character string consisting of 20 characters and assigns the given string to it.

A double colon (::) can be used to separate any of the intrinsic types INTEGER, REAL, LOGICAL, COMPLEX and CHARACTER from the list that flows. It is mandatory when the type is given additional attributes.

Assignment

Suppose that str1 is assigned to str2:

str2=str1

If str1 is shorter than str2 then str2 is padded out with trailing spaces. If str1 is longer than str2 then str1 is truncated to fit.

Concatenation

A double oblique (//) is used with character strings to denote the operation of concatenation thus:

str=str1//str2

The use of a variable on both sides of an assignment statement is not permitted. For example:

str=str//"."

causes an error condition.

Sub strings

A sub string of the variable str is obtained using the notation str(pos1:pos2) where pos1 and pos2 represent INTEGER expressions. pos1 and pos2 denote the positions in the string counting from 1 (unity) at the first character. For example:

str="A test string"
str1=str(3:6) !str1="test"
str2=str(:6) !str2="A test"
str3=str(3:) !str3="test string"

The resulting strings will be truncated or padded with trailing spaces depending on their lengths.

If pos1 is greater than pos2 then a string of zero length is obtained.

Intrinsic functions

LEN(str) returns the number of characters in str.

LEN_TRIM(str) returns the number of characters in str excluding trailing spaces

TRIM(str) removes trailing spaces from str.

INDEX(str1,str2) returns the position of the first occurrence of str2 in str1.

SCAN(str1,str2) returns the position of the first occurrence in str1 of any of the characters of str2.

VERIFY(str1,str2) returns the position of the first occurrence in str1 of any of character not in str2.

INDEX, SCAN and VERIFY have optional third arguments that provide for scanning from the end.

More…


Arrays

An array consists of a number of elements of the same type. An element is identified by the name of the array together with one or more indexes, one for each dimension of the array.

Declaration

INTEGER ar(0:9)
REAL beta(1:9,1:10)

ar is a one dimensional array of INTEGERs with index in the range from 0 to 9.

beta is a two dimensional array of REALs with first index in the range from 1 to 9 and second index in the range from 1 to 10.

A particular element of ar is represented by ar(expr) where expr is an integer expression. Similarly an element of the two dimensional array beta is represented by beta(expr1,expr2).

If the lower bound for an index is 1 (unity) then it may be omitted. For example:

REAL beta(9,10)

The rank of an array or scalar is the number of dimensions. A scalar has rank zero.

The shape of an array or scalar is a list of integers, one for each dimension, giving the number of elements along each dimension in turn. ar has shape (10). beta has shape (9,10). A scalar has shape ( ).

Assignment

Individual elements can be assigned values just like simple variables:

beta(3,4)=1.0

In addition, every element of an array can be assigned a particular value:

beta=0.0

One array can be copied, element by element, into another provided that the two have the same shape.

beta=gamma

Assignment is permissible if the array on the left is conformable to the object on the right. Two objects are conformable if they have the same shape or if one is a scalar.

Any intrinsic function that is classed as elemental can be used in an array expression to carry out assignment on an element by element basis:

REAL a(10),b(10),c(10)
 ! Values are assigned to the elements of a, b, and c
a=2.0*a+b*ABS(c)

Constructor

An array constructor is used to build an array from a list of values between "(/" and "/)". For example, given a REAL array x with shape (4):

x = (/ 1.4, 0.5, 1.0, 1.5 /)

All the components must have the same type and type attributes.

The rank of an array constructor is one. An intrinsic function called RESHAPE can be used to convert to rank greater than one.

WHERE statement and construct

Element by element array assignments (A = B) can be made conditional by using a WHERE statement or WHERE construct. The two forms are analogous to the IF statement and the IF construct.

The form of the WHERE statement is:

WHERE(mask_expression) array_assignment

For example:

WHERE (a>0.0) a=1.0/a ! a is a known REAL array

The form of the WHERE construct is:

WHERE(mask_expression)

array_assignments

[ ELSEWHERE

array_assignments ]

END WHERE

For example:

WHERE (b/=0)
  a=a/b ! a and b are known INTEGER arrays
ELSEWHERE
  a=0
END WHERE

The ELSEWHERE section is optional.

If the ELSEWHERE section consists of one WHERE construct, then ELSE and WHERE can be reduced to ELSEWHERE provided that one of the associated ENDWHEREs is deleted.

Like other constructs, WHERE constructs can be named. Optionally, the same name may be used after ELSEWHERE and after ELSEWHERE (mask_expression).

Intrinsic functions

SUM(a) sums the elements an array.
DOT_PRODUCT(a,b) forms an inner product.
MATMUL(a,b) forms a matrix product.
MAXLOC(a) returns the location of the largest value (also MINLOC).
MAXVAL(a) returns the largest value (also MINVAL).

More…

The following more advanced topics are not described here:

Triplet notation

Vector subscripts

The FORALL construct


User-defined types

Defining a new type

The definition of a user-defined type consists of a list of names together with their type. It describes the fields of a record. The form is:

TYPE type_name

type_of_field1 name_of_field1

type_of_field2 name_of_field2

. . .

END TYPE type_name

For example:

TYPE ADDRESS
  CHARACTER(LEN=40)::Name
  INTEGER ::Number
  CHARACTER(LEN=40)::Street
  CHARACTER(LEN=40)::Town
  CHARACTER(LEN=10)::PostCode
END TYPE ADDRESS

Unlike an array, the components of a user-defined type need not have the same type.

A field type can be a user-defined type.

A field can be an array.

Declaring a type does not allocate storage for a variable of that type.

Declaring variables

Once a type has been defined, a declaration takes the form:

TYPE(type_name) list_of_variables

For example:

TYPE(ADDRESS) MyAddress,AddressBook(200)

AddressBook is an array with index from 1 to 200.

A double colon (::) is required if type attributes are included.

Referencing a field

In contrast to an array where a component is identified by its index, a component of a record is identified by its name. The percent sign (%) is used in this context. For example:

MyAddress%Number

AddressBook(10)%Street

Constructor

The fields of record can be given a value by simple assignment:

MyAddress%Number=12

or by using a constructor that takes the form of a function whose name is that of the type and whose arguments are the initial values for the fields.

MyAddress=ADDRESS("John Smith",12,"Main St","Salford","M6 4NZ")


Pointers

In Fortran, a pointer is an alias for another item of data (or a block in the form of an array, a section of an array, or a structure). It is not the address of the item but rather it is an alternative name for the item. This association between a pointer and what it is an alias for, can be changed under program control. As a result, pointers can be used to create structures such as linked lists and trees.

Declaring a pointer

A pointer is declared by giving it a type with the POINTER attribute. The data item for which it is an alias must also be given the TARGET attribute. For example:

REAL,TARGET::x
REAL,POINTER::AltX

Associating a pointer with a target

The combination "=>" is used to associate a pointer with a given item of data. For example:

AltX=>x
AltX=1.0

makes AltX an alias for x and then assigns the value 1.0 to x.

The states of a pointer

A pointer is in one of three states:

  1. It may be undefined. It has been declared but not associated with an item of data.

  2. It may be null. This is a zero state obtained using NULLIFY or the intrinsic function NULL. It is used to explicitly state that the pointer is currently not an alias for any data item (e.g. a terminator for a linked list).

  3. It may be associated. It is currently an alias for some target.

The intrinsic function ASSOCIATED may be used to determine the current state of a pointer.


Dynamic storage allocation

Allocating storage for arrays

If the required size of an array is not known at compile time, it can be declared with the ALLOCATABLE attribute. For example:

REAL,ALLOCATABLE::ar(:,:)

declares ar to be a REAL, two-dimensional array of undefined shape.

At run time when the required shape becomes known, storage can be allocated dynamically using ALLOCATE. For example:

INTEGER n,ErrorState
! Code to determine the value of n
ALLOCATE(ar(n,n),STAT=ErrorState)
IF(ErrorState>0) STOP "Failed dynamic allocation"

The STAT argument is optional.

Allocated memory is obtained from an area of memory called the heap. It is automatically returned when the program terminates or (if the array is local to a procedure) when a RETURN is executed. Otherwise, memory can be explicitly returned by using DEALLOCATE. For example:

DEALLOCATE(ar)

The ALLOCATED intrinsic function can be used to determine if an array is currently allocated.

Allocating storage for structures

By using the ALLOCATE statement, it is also possible to allocate memory for a structure referenced only by a pointer. The following example, though trivial, illustrates the idea.

REAL,POINTER::x
ALLOCATE(x)
x=1.0
DEALLOCATE(x)

DEALLOCATE returns the storage and nullifies the pointer.

In the case of arrays, the attributes ALLOCATABLE and POINTER are synonymous.

The NULLIFY statement

Given a pointer ptr, the statement

NULLIFY(ptr)

sets ptr to the null state. After ptr has been nullified, ASSOCIATED(ptr) will return FALSE.


Procedures

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Procedures

A procedure is a sub program that is written as a separate, named block of code. Procedures can have arguments that are used to input information into the procedure and to return information to the program or procedure making the call. Within the procedure the arguments are called dummy arguments. The corresponding arguments at the point of call are called actual arguments. Procedures are used to represent identifiable sub tasks within a program.

A procedure is either a FUNCTION or a SUBROUTINE.

Typically, FUNCTIONs have arguments that are used to input information and a single output value that is returned via the function name. A FUNCTION is called from within an expression.

A SUBROUTINE has arguments that can be used for input or output (or both) and is called using a CALL statement.

A procedure is external if it is not presented within a PROGRAM, MODULE or another procedure. It is either presented in a separate file or after the END of a PROGRAM, MODULE or another procedure.

A procedure is internal if it is presented between a CONTAINS statement and the END of a PROGRAM, MODULE or an external procedure.

An internal procedure is a module procedure if it is presented between a CONTAINS statement and the END of a MODULE.

Here is an example of an internal FUNCTION in a main PROGRAM:

PROGRAM Prog3
REAL a
READ *, a
PRINT *, func(a)

CONTAINS

REAL FUNCTION func(x)
REAL x
func=x*x+1.0
END
END Prog3

Internal procedures can also use variables that are declared in the host (i.e. before the CONTAINS statement).


Functions

A simple FUNCTION takes the form:

type FUNCTION name(list of arguments)
argument types
declaration of local variables
body of function
END [FUNCTION [name] ]

For example:

REAL FUNCTION mod(x,y)
REAL x,y
mod=SQRT(x*x+y*y) !SQRT is a standard intrinsic function
END FUNCTION mod

The body of the function contains one or more assignment statements in which the name of the function is assigned a value. If flow control statements and/or constructs are used within the body of the function then a RETURN statement can be used to exit from the function. The END statement implies RETURN.

As an alternative to using the function name in assignment statements, a different name may be used if this name is added to the specification as illustrated here:

REAL FUNCTION mod(x,y) RESULT(f)
REAL x,y
f=SQRT(x*x+y*y)
END FUNCTION mod

A function that either directly or indirectly calls itself must use RESULT and must be given the RECURSIVE attribute. For example:

RECURSIVE INTEGER FUNCTION factorial(n) RESULT(f)
INTEGER n
IF(n==0)THEN
 f=1
ELSE
 f=factorial(n-1)
ENDIF
END FUNCTION factorial


Subroutines

A simple SUBROUTINE takes the form:

SUBROUTINE name(list of arguments)
argument types
declaration of local variables
body of subroutine
END [SUBROUTINE [name] ]

A subroutine is called by using a CALL statement. For example:

PROGRAM Prog4
 INTEGER a
 CALL sub(2,a)
CONTAINS
 SUBROUTINE sub(m,n)
 INTEGER m,n
 n=m+1
 END SUBROUTINE sub
END PROGRAM Prog4

If flow control statements and/or constructs are used within the body of the subroutine then a RETURN statement can be used to exit from the subroutine. The END statement implies RETURN.


Arguments

Unless optional arguments are used (see below) the number of actual arguments must be the same as the number of dummy arguments. Unless keywords are used (see below) the order of the arguments must be the same. In addition, the arguments will usually have the same type (and type attributes), the same shape and (with character strings) the same length.

The INTENT attribute

In Fortran all arguments are passed by reference. This means that the information passed is the address of the data concerned. Potentially any argument can be used either for input or for output. There is therefore the likelihood of side effects at the point of call when a dummy argument is inadvertently changed within a procedure.

The INTENT attribute limits the way in which an argument may be used within a procedure as follows:

INTENT(IN) The procedure must not change the argument.

INTENT(OUT) The argument is undefined on entry and may be given a value in the procedure.

INTENT(INOUT) The argument may be given a value in the procedure.

For example:

REAL FUNCTION mod(x,y)
REAL,INTENT(IN)::x,y
mod=SQRT(x*x+y*y)
END FUNCTION mod

It is recommended that INTENT be used with all arguments. If the PURE attribute is attached to a procedure then a compilation error occurs unless all of the arguments are marked as INTENT(IN).

Keyword arguments

The name of a dummy argument can be used as a keyword in the call of a procedure. For example:

PROGRAM Prog5
 REAL a
 READ *, a
 PRINT *, func(x=a)
CONTAINS
 REAL FUNCTION func(x)
 REAL x
 func=x*x+1.0
 END
END Prog5

By using keywords, the order of the arguments can be changed. Also arguments that are optional (see below) may be omitted. If a keyword is used or an optional argument omitted, all arguments that follow must use keywords.

External procedures that have keyword or optional arguments must also have an explicit interface (see the next topic).

Optional arguments

The attribute OPTIONAL can be attached to a dummy argument. OPTIONAL arguments may be omitted from the actual argument list. The intrinsic function PRESENT may be used within a procedure to test if an optional argument was present in the actual argument list. For example:

REAL FUNCTION func(x,y)
REAL x,z
REAL,OPTIONAL::y
IF(PRESENT(y))THEN
 z=y
ELSE
 z=1.0
ENDIF
func=x*x+z
END FUNCTION func

External procedures that have optional arguments must have an explicit interface.

Assumed shape arrays

A dummy argument that is an array may be declared without its shape. In this case the dummy argument will inherit the shape of the actual array argument. For example:

SUBROUTINE ProcessArray(arr)
REAL arr(:,:)
INTEGER m,n
m=SIZE(arr,DIM=1)
n=SIZE(arr,DIM=2)
. . .
END SUBROUTINE ProcessArray

Automatic arrays

An array that is local to a procedure can be declared to have a shape that depends on the current arguments. For example:

SUBROUTINE ProcessArray(arr)
REAL,INTENT(IN)::arr(:)
REAL a(SIZE(arr)) !Lower bound is one
a=arr !Take a copy of arr
. . .
END SUBROUTINE ProcessArray

The alternative is to make an explicit call to ALLOCATE.


Interface blocks

Interface statements

  1. If a procedure is internal to a program unit (i.e. a program, module or external procedure) then it can be assumed that the compiler will have all the information that is needed to compile that unit. In other words the compiler has the ability to look ahead to the CONTAINS section of the unit and to extract any information that is needed concerning the interface.

  2. If a procedure is defined in a MODULE (see the next topic) then it can be used within a program unit provided that a corresponding USE statement is supplied before the call. A USE statement provides the required interface information.

  3. If a call is made from a program unit to an external procedure, then an INTERFACE statement may be used to supply all the external information that is needed in order to handle the procedure.

Procedures of types 1,2 and 3 are said to have an explicit interface otherwise the interface is implicit.

For implicit procedures, the EXTERNAL statement in the form:

EXTERNAL list_of_procedures

may be used to specify that a procedure is external. The list is simply a list of names without details about the arguments etc. It is necessary to use an external statement if the name is (or might be) the same as that of an intrinsic function. In addition, the return type of an external function must be declared unless the implicit typing rule is used. For implicit procedures, the number, order and type of the dummy arguments are implied from the actual arguments and the compiler simply checks that the various calls to a procedure are consistent.

An INTERFACE statement may be provided in order to make an interface explicit. It is required when a procedure has keyword and/or optional arguments.

An INTERFACE statement takes the form:

INTERFACE
interface_body
END INTERFACE

The interface body is normally a copy of the procedure header (or a number of them) leaving out variables that are local to the procedure and leaving out the code for the body of the procedure.

An INTERFACE statement can also be used within a MODULE in order to introduce user-defined operators and generic procedures.


Modules

Programs are made up of program units consisting of one main PROGRAM together with optional external procedures and MODULEs.

A MODULE can contain data that is to be shared by a number of program units. Variables can be declared within a MODULE and accessed and changed by any program unit that includes a corresponding USE statement. A MODULE supercedes the COMMON block of Fortran 77 and earlier standards.

A MODULE can also contain the definition of user-defined types together with the definition of procedures that are common to a number of program units. Some of these procedures may be used to create user-defined operators. In this respect, a MODULE can be designed to be "object oriented".

A MODULE has the form:

MODULE module_name
[specification_statements]
[CONTAINS
module_procedures]
END [MODULE [module_name]]

The specification statements can include the definition of user-defined types and the declaration of variables of any known type. USE statements relating to other MODULEs can also be included.

The module procedures are presented in exactly the same way as in other program units.

The USE statement

A USE statement has the form:

USE module_name

A USE statement may appear in a main program, another module or a procedure (of any kind). Variables declared in a module are shared amongst all the program units using the module.

USE ONLY and renaming

ONLY may be included in a USE statement in the form:

USE module_name, ONLY: list_of_variables

For example:

USE MyModule, ONLY : nValues

The effect is to make all the variables in the given module unavailable except for those in the list of variables. This will avoid possible name clashes.

A local alias can be substituted for the name of a module variable as illustrated here:

USE MyModule, n=>nValues
USE MyModule, ONLY: n=>nValues

n is a local alias for the variable nValues in MyModule.

The PRIVATE and PUBLIC statements

The PRIVATE statement is used within a MODULE in order to specify that certain variables may only be used within the module (in internal procedures) and are not available when the module is USEd.

The form is:

PRIVATE list_of_variables

A PRIVATE statement without a list makes all variables PRIVATE by default. A PUBLIC statement is then used to specify those variables that may be USEd.

The form of the PUBLIC statement is:

PUBLIC list_of_variables

Compiling modules

Modules can be placed in a file together with other program units. However, it is recommended that modules be placed in their own files so that they can be separately compiled. If a module is changed in a way that does not affect the interface then program units that use that module do not need to be recompiled.

The following more advanced topics are not described here:

Generic procedures (i.e. overloading procedure names)

User-defined operators (including assignment)

Extending intrinsic generic functions


FTN95 Library

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

The run-time system that is installed with FTN95 contains many useful subroutines and functions. They can be accessed alphabetically from the links above and are categorized below:

Standard intrinsics (index)

Standard intrinsics (classified)

Bit-handling routines

Character-handling routines

Command line parsing routines

Data sorting routines

Error and exception handling routines

File-manipulation routines

In-line routines

Process control routines

Random number routines

Screen/Keyboard routines

Serial Communications routines

Storage management routines

System routines

Time and date routines


Standard Fortran intrinsics

ABS
ACHAR
ACOS
ACOSH
ADJUSTL
ADJUSTR
AIMAG
AINT
ALL
ALLOCATED
ANINT
ANY
ASIN
ASINH
ASSOCIATED
ATAN
ATAN2
ATANH
BESSEL_J0
BESSEL_J1
BESSEL_JN
BESSEL_Y0
BESSEL_Y1
BESSEL_YN
BIT_SIZE
BTEST
CEILING
CHAR
CMPLX
COMPILER_OPTIONS
COMPILER_VERSION
CONJG
COS
COSH
COUNT
CPU_TIME
CSHIFT
C_SIZEOF
DATE_AND_TIME
DBLE
DIGITS
DIM
DOT_PRODUCT
DPROD
EOSHIFT
EPSILON
ERF
ERFC
ERFC_SCALED
EXP
EXPONENT
FINDLOC
FLOOR
FRACTION
GAMMA
GET_ENVIRONMENT_VARIABLE
HUGE
IACHAR
IAND
IBCLR
IBITS
IBSET
ICHAR
IEOR
INDEX
INT
IOR
ISHFT
ISHFTC
 KIND
LBOUND
LEN
LEN_TRIM
LGE
LGT
LLE
LLT
LOG
LOG10
LOG_GAMMA
LOGICAL
MATMUL
MAX
MAXEXPONENT
MAXLOC
MAXVAL
MERGE
MIN
MINEXPONENT
MINLOC
MINVAL
MOD
MODULO
MOVE_ALLOC
MVBITS
NEAREST
NINT
NOT
NULL
PACK
PRECISION
PRESENT
PRODUCT
RADIX
RANDOM_NUMBER
RANDOM_SEED
RANGE
REAL
REPEAT
RESHAPE
RRSPACING
SCALE
SCAN
SELECTED_INT_KIND
SELECTED_REAL_KIND
SET_EXPONENT
SHAPE
SIGN
SIN
SINH
SIZE
SPACING
SPREAD
SQRT
STORAGE_SIZE
SUM
SYSTEM_CLOCK
TAN
TANH
TINY
TRANSFER
TRANSPOSE
TRIM
UBOUND
UNPACK
VERIFY


ABS

Platform

x64, Win32, .NET

Purpose

To get the absolute value of the argument.

Class

Elemental function.

Syntax

INTEGER FUNCTION ABS(A); INTEGER A
REAL FUNCTION ABS(A); REAL A
REAL FUNCTION ABS(A); COMPLEX A

Return value

If A is INTEGER or REAL then the return value is A (if A > 0) and -A (if A < 0).

If A is COMPLEX and A = (x, y) then the return value is [image].


ACHAR

Platform | x64, Win32, .NET
Purpose | To get a character in the ASCII collating sequence.
Class | Elemental function.
Syntax | CHARACTER FUNCTION ACHAR(I) INTEGER I
Return value | If I is in the range 0 to 255, ACHAR returns the single character of type KIND('A') that is given by the ASCII collating sequence.
Notes | IACHAR is the inverse function.


ACOS

Platform | x64, Win32, .NET
Purpose | To get the Arccosine (inverse cosine) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ACOS(X) REAL X COMPLEX FUNCTION ACOS(X) COMPLEX X
Description | If X is REAL then it must be in the range -1. < X < 1.
Return value | The real part of the result is given in radians in the range 0 < result < p .


ACOSH

Platform | x64, Win32
Purpose | To get the Arccosine (inverse hyperbolic cosine) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ACOSH(X) REAL X COMPLEX FUNCTION ACOSH(X) COMPLEX X
Description | The REAL value X must be in the range X ≥ 1.


ADJUSTL

Platform | x64, Win32, .NET
Purpose | To remove leading spaces from a character string and insert them at the end.
Class | Elemental function.
Syntax | CHARACTER (LEN=*) FUNCTION ADJUSTL(STRING) CHARACTER (LEN=*) STRING
Return value | The result has then same type and length as STRING.


ADJUSTR

Platform | x64, Win32, .NET
Purpose | To remove trailing spaces from a character string and insert them at the beginning.
Class | Elemental function.
Syntax | CHARACTER (LEN=*) FUNCTION ADJUSTR(STRING) CHARACTER (LEN=*) STRING
Return value | The result has then same type and length as STRING.


AIMAG

Platform | x64, Win32, .NET
Purpose | To get the imaginary part of a complex number.
Class | Elemental function.
Syntax | REAL FUNCTION AIMAG(Z) COMPLEX Z
Return value | If Z = (x, y) then the result is y.


AINT

Platform | x64, Win32, .NET
Purpose | To truncate a REAL number to its integer part.
Class | Elemental function.
Syntax | REAL FUNCTION AINT(A [,KIND]) REAL A INTEGER KIND
Description | KIND is optional. If it is omitted the return type is the same as A. If KIND is present it specifies the kind type of the return value.
Return value | The argument is truncated towards zero.
Example | AINT(1.6) gives 1.0. AINT(-2.6) gives -2.0.


ALL

Platform

x64, Win32, .NET

Purpose

To test if all the elements in a logical array are true.

Class

Transformational function.

Syntax

LOGICAL FUNCTION ALL(MASK [,DIM])
LOGICAL MASK
INTEGER DIM

Description

MASK is a logical array. DIM is optional and is a value in the range 1 < DIM < n where n is the rank (i.e. the number of dimensions) of MASK. ALL returns a logical array or scalar whose kind type is the same as an element of MASK. If MASK has rank 1 or if DIM is not present then ALL returns a scalar otherwise ALL returns an array whose rank is one less than that of MASK. If MASK has rank 1 then a supplied value of DIM is ignored.

Return value

ALL(MASK) returns the scalar value true if all the elements of MASK are true. It returns false if any element of MASK is false.

If MASK has rank n greater than 1 then ALL(MASK, DIM) returns a logical array of rank n - 1 whose elements are given by ALL(MASK) applied along dimension DIM.

Example

If MASK =
then ALL(MASK, 1) returns [true, true, false]

whilst ALL(MASK, 2) returns [false, true]


ALLOCATED

Platform | x64, Win32, .NET
Purpose | To determine whether or not an allocatable array is currently allocated.
Class | Inquiry function.
Syntax | LOGICAL FUNCTION ALLOCATED(ARRAY)
Description | ARRAY is any allocatable array.
Return value | Using the default LOGICAL type, the result is true if the array is currently allocated, otherwise false.


ANINT

Platform | x64, Win32, .NET
Purpose | To round off a REAL number to its nearest integer value
Class | Elemental function.
Syntax | REAL FUNCTION ANINT(A [,KIND]) REAL A INTEGER KIND
Description | KIND is optional. If it is omitted the return type is the same as A. If KIND is present it specifies the kind type of the return value.
Return value | The argument is rounded to its nearest integer value.
Example | ANINT(1.6) gives 2.0. ANINT(-2.6) gives -3.0.


ANY

Platform

x64, Win32, .NET

Purpose

To test if any of the elements in a logical array are true.

Class

Transformational function.

Syntax

LOGICAL FUNCTION ANY(MASK [,DIM])
LOGICAL MASK; INTEGER DIM

Description

MASK is a logical array. DIM is optional and is a value in the range 1 < DIM < n where n is the rank (i.e. the number of dimensions) of MASK. ANY returns a logical array or scalar whose kind type is the same as an element of MASK. If MASK has rank 1 or if DIM is not present then ANY returns a scalar otherwise ANY returns an array whose rank is one less than that of MASK. If MASK has rank 1 then a supplied value of DIM is ignored.

Return value

ANY(MASK) returns the scalar value true if any of the elements of MASK are true. It returns false if all of the elements of MASK is false.

If MASK has rank n greater than 1 then ANY(MASK, DIM) returns a logical array of rank n - 1 whose elements are given by ANY(MASK) applied along dimension DIM.

Example

If MASK =

then ANY(MASK, 1) returns [true, true, false]

whilst ANY(MASK, 2) returns [true, true]


ASIN

Platform | x64, Win32, .NET
Purpose | To get the Arcsine (inverse sine) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ASIN(X) REAL X COMPLEX FUNCTION ASIN(X) COMPLEX X
Description | For REAL X, X must be in the range -1 < X < 1.
Return value | The real part of the result is given in radians in the range - p/2 < result < p /2.


ASINH

Platform | x64, Win32
Purpose | To get the Arcsine (inverse hyperbolic sine) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ASINH(X) REAL X COMPLEX FUNCTION ASINH(X) COMPLEX X
Description | The REAL value X can take any real value.


ASSOCIATED

Platform

x64, Win32, .NET

Purpose

To determine whether or not a pointer is associated or is associated with a given target.

Class

Inquiry function.

Syntax

LOGICAL FUNCTION ASSOCIATED(POINTER [,TARGET])

Description

POINTER is a pointer of any type whose status has been set as associated or disassociated (not undefined). TARGET is optional and is a pointer or a target. TARGET has the same type, type parameters, and rank as POINTER. If it is a pointer then its status must not be undefined .

Return value

The ISO standard defines the result as:

  1. If TARGET is absent, the result is true if POINTER is currently associated with a target and false if it is not.

  2. If TARGET is present and is a scalar target, the result is true if TARGET is not a zero-sized storage sequence and the target associated with POINTER occupies the same storage units as TARGET. Otherwise, the result is false. If POINTER is disassociated, the result is false.

  3. If TARGET is present and is an array target, the result is true if the target associated with POINTER and TARGET have the same shape, are neither of size zero nor arrays whose elements are zero-sized storage sequences, and occupy the same storage units in array element order. Otherwise, the result is false. If POINTER is disassociated, the result is false.

  4. If TARGET is present and is a scalar pointer, the result is true if the target associated with POINTER and the target associated with TARGET are not zero-sized storage sequences and they occupy the same storage units. Otherwise, the result is false. If either POINTER or TARGET is disassociated, the result is false.

  5. If TARGET is present and is an array pointer, the result is true if the target associated with POINTER and the target associated with TARGET have the same shape, are neither of size zero nor arrays whose elements are zero-sized storage sequences, and occupy the same storage units in array element order. Otherwise, the result is false. If either POINTER or TARGET is disassociated, the result is false.


ATAN

Platform | x64, Win32, .NET
Purpose | To get the Arctangent (inverse tangent) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ATAN(X) REAL X COMPLEX FUNCTION ATAN(X) COMPLEX X
Description | For REAL X, X can be any real value.
Return value | The real part of the result is given in radians in the range - p/2 < result < p /2.


ATANH

Platform | x64, Win32
Purpose | To get the Arctangent (inverse hyperbolic tangent) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ATANH(X) REAL X COMPLEX FUNCTION ATANH(X) COMPLEX X
Description | The REAL value X must be in the range -1 < X < 1.


ATAN2

Platform | x64, Win32, .NET
Purpose | To get the Arctangent (inverse tangent) from the arguments.
Class | Elemental function.
Syntax | REAL FUNCTION ATAN2(Y,X) REAL X, Y
Description | (X, Y) are cartesian coordinates and the result is the value of Arctangent(Y/X). If Y>0, the result is positive. If Y=0, the result is zero if X>0 and p if X<0. If Y<0, the result is negative. If X=0, the absolute value of the result is p/2. The arguments must not both have the value zero.
Return value | The result is given in radians in the range - p < result < p .


BESSEL_J0

Platform | Win32 and x64
Purpose | To compute the Bessel function of the first kind of order 0.
Class | Elemental function
Syntax | REAL FUNCTION BESSEL_J0(X) REAL X
Description | The return value is of type REAL, of the same kind as X, and lies in the range -0.4027... <= Bessel_j0(X) <= 1.


BESSEL_J1

Platform | Win32 and x64
Purpose | To compute the Bessel function of the first kind of order 1.
Class | Elemental function
Syntax | REAL FUNCTION BESSEL_J1(X) REAL X
Description | The return value is of type REAL, of the same kind as X, and lies in the range -0.5818... <= Bessel_j1(x) <= 0.5818.


BESSEL_JN

Platform | Win32 and x64
Purpose | To compute the Bessel function of the first kind of order N.
Class | Elemental function
Syntax | REAL FUNCTION BESSEL_JN(N,X) INTEGER N REAL X
Description | The return value is a scalar of type REAL and of the same kind as X. Note that this function does not fully implement the Fortran 2008 standard in that it can only take two arguments and N must be a scalar value.


BESSEL_Y0

Platform | Win32 and x64
Purpose | To cumpute the Bessel function of the second kind of order 0.
Class | Elemental function
Syntax | REAL FUNCTION BESSEL_Y0(X) REAL X
Description | The return value is of type REAL and of the same kind as X.


BESSEL_Y1

Platform | Win32 and x64
Purpose | To compute the Bessel function of the second kind of order 1.
Class | Elemental function
Syntax | REAL FUNCTION BESSEL_Y1(X) REAL X
Description | The return value is of type REAL and has the same kind as X.


BESSEL_YN

Platform | Win32 and x64
Purpose | To compute the Bessel function of the second kind of order N.
Class | Elemental function
Syntax | REAL FUNCTION BESSEL_YN(N,X) INTEGER N REAL X
Description | The return value is a scalar of type REAL and has the same kind as X. Note that this function does not fully implement the Fortran 2008 standard in that it can only take two arguments and N must be a scalar value.


BIT_SIZE

Platform | x64, Win32, .NET
Purpose | To get the number of bits in an integer.
Class | Inquiry function.
Syntax | INTEGER FUNCTION BIT_SIZE(I) INTEGER I
Description | I can be a scalar or an array.
Return value | The result is a scalar of the same type as the argument.


BTEST

Platform | x64, Win32, .NET
Purpose | To test if a particular bit in an integer is set.
Class | Elemental function.
Syntax | LOGICAL FUNCTION BTEST(I, POS) INTEGER I, POS
Description | POS must be in the range 0 < POS < BIT_SIZE(I). Bit zero is the least significant bit. At least one of I and POS must be a scalar.
Return value | The result has the default logical type.


CEILING

Platform | x64, Win32, .NET
Purpose | To get the least integer greater than or equal to its argument.
Class | Elemental function.
Syntax | INTEGER FUNCTION CEILING (A [,KIND]) REAL A; INTEGER KIND
Description | KIND is optional. If it is omitted the return type is the default integer type. If KIND is present it specifies the kind type of the return value.
Example | CEILING(-2.6) has the integer value -2.
See also | FLOOR


CHAR

Platform | x64, Win32, .NET
Purpose | To get the character in a given position of the collating sequence associated with the specified kind type parameter.
Class | Elemental function.
Syntax | CHARACTER FUNCTION CHAR(I [,KIND]) INTEGER I, KIND
Description | I represents the position in the collating sequence numbering from zero. KIND is optional and can be used to specify the (scalar) kind type parameter of the character set. If KIND is not present the default character set is used. CHAR is the inverse of the intrinsic function ICHAR .
Return value | The result is a character of length one.
Example | CHAR(97) gives 'a' when used with the ASCII collating sequence.


CMPLX

Platform

x64, Win32, .NET

Purpose

To convert a number or a pair of numbers to complex type.

Class

Elemental function.

Syntax

COMPLEX FUNCTION CMPLX(X [,Y,KIND]);REAL X; INTEGER KIND
COMPLEX FUNCTION CMPLX(X [,Y,KIND]);INTEGER X;INTEGER KIND
COMPLEX FUNCTION CMPLX(X [,KIND]); COMPLEX X;INTEGER KIND

Description

KIND an optional scalar value. If it is omitted the return type is the default complex type. If KIND is present it specifies the kind type of the return value.

If X is real or integer it represents the real part of the complex result. In this case if Y is absent its default value is zero. Y is optional. It is either real or integer (not complex) and represents the imaginary part of the complex result.

Example

CMPLX(-4) gives the value (-4.0, 0.0).


COMMAND_ARGUMENT_COUNT

Platform | x64, Win32, .NET
Purpose | To get the number of command line arguments.
Syntax | INTEGER FUNCTION COMMAND_ARGUMENT_COUNT( )
Return value | Returns the number of arguments on the command line. The command name is not included in the count.
Notes | This is an F2003 standard intrinsic.


COMPILER_OPTIONS

Platform | Win32 and x64
Purpose | To return a string with the options used for compiling.
Syntax | CHARACTER(LEN=*) FUNCTION COMPILER_OPTIONS()
Description | This function requires the statement: USE ISO_FORTRAN_ENV


COMPILER_VERSION

Platform | Win32 and x64
Purpose | To return a string with the name and version of the compiler.
Syntax | CHARACTER(LEN=*) FUNCTION COMPILER_VERSION()
Description | This function requires the statement: USE ISO_FORTRAN_ENV


CONJG

Platform | x64, Win32, .NET
Purpose | To get the conjugate of a complex number.
Class | Elemental function.
Syntax | COMPLEX FUNCTION CONJG(Z) COMPLEX Z
Return value | The result has the same type as Z.
Example | CONJG ((1.0, 2.0)) has the value (1.0, -2.0).


COS

Platform

x64, Win32, .NET

Purpose

To get the Cosine of the argument.

Class

Elemental function.

Syntax

REAL FUNCTION COS(X); REAL X
COMPLEX FUNCTION COS(X); COMPLEX X

Description

If X is real it is an angle measured in radians. If X is complex its real part is in radians.


COSH

Platform | x64, Win32, .NET
Purpose | To get the Hyperbolic cosine of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION COSH(X) REAL X COMPLEX FUNCTION COSH(X) COMPLEX X
Description | The result has the same type as X. If X is complex then the imaginary part of the result is in radians.


COUNT

Platform | x64, Win32, .NET
Purpose | Count the number of true elements of MASK along dimension DIM.
Class | Transformational function.
Syntax | INTEGER FUNCTION COUNT(MASK [,DIM]) LOGICAL MASK; INTEGER DIM
Description | MASK is a logical array. DIM is optional and is a value in the range 1 < DIM < n where n is the rank (i.e. the number of dimensions) of MASK. COUNT returns an integer array of the default kind type. If MASK has rank 1 or if DIM is not present then COUNT returns a scalar otherwise COUNT returns an array whose rank is one less than that of MASK. If MASK has rank 1 then a supplied value of DIM is ignored.
Return value | COUNT(MASK) returns the number of elements of MASK that are true. If MASK has rank n greater than 1 then COUNT(MASK, DIM) returns a integer array of rank n - 1 whose elements are given by COUNT(MASK) applied along dimension DIM.
Example | If MASK = then COUNT(MASK, 1) returns [2, 1, 0] whilst COUNT(MASK, 2) returns [1, 2].


CPU_TIME

Platform | x64, Win32, .NET
Purpose | To get the processor time.
Class | Subroutine.
Syntax | SUBROUTINE CPU_TIME(TIME) REAL,INTENT(OUT)::TIME
Return value | TIME is a scalar value giving the processor time in seconds. A negative value denotes an error condition.
Example | REAL TIME1, TIME2 CALL CPU_TIME(TIME1) ! Processing... CALL CPU_TIME(TIME2) PRINT *, 'Processing time was ', TIME2-TIME1, ' seconds'


CSHIFT

Platform

x64, Win32, .NET

Purpose

Perform a circular shift on an array expression.

Class

Transformational function.

Syntax

FUNCTION CSHIFT(ARRAY, SHIFT [, DIM])
INTEGER SHIFT
INTEGER DIM

Description

Perform a circular shift on an array expression of rank one or perform circular shifts on all the complete rank one sections along a given dimension of an array expression of rank two or greater. Elements shifted out at one end of a section are shifted in at the other end. Different sections may be shifted by different amounts and in different directions.

DIM is optional and is a value in the range 1 < DIM < n where n is the rank (i.e. the number of dimensions) of ARRAY. The default value of DIM is 1.

Return value

The result has the same type, type parameters and shape as ARRAY.

Example

If A = [1, 2, 3, 4, 5] then CSHIFT(A, 2) (i.e. shifted to the left) gives [3, 4, 5, 1, 2], and CSHIFT(A, -2) gives [4, 5, 1, 2, 3].

If B = [image] then CSHIFT(B, 1, 2) gives

If SHIFT = [1, 0, 2] then CSHIFT(B, SHIFT, 2) gives [image].


C_SIZEOF

Platform | x64, Win32
Purpose | To get the size of an expression in bytes.
Syntax | INTEGER FUNCTION C_SIZEOF(X)
Description | The argument X can be any expression. The returned value has the KIND value C_SIZE_T from the ISO_C_BINDING module. This function requires the statement: USE ISO_C_BINDING
Notes | The standard intrinsic STORAGE_SIZE is similar but returns the size in bits.


DATE_AND_TIME

Platform

x64, Win32, .NET

Purpose

To get the real-time date and clock time.

Class

Subroutine

Syntax

SUBROUTINE DATE_AND_TIME([DATE, TIME, ZONE, VALUES])
CHARACTER (LEN=*), INTENT(OUT)::DATE, TIME, ZONE
INTEGER, INTENT(OUT)::VALUES(8)

Description

All the arguments are optional.

The leftmost 8 characters of DATE are assigned a value of the form CCYYMMDD, where CC is the century, YY the year , MM the month, and DD the day.

The leftmost 10 characters of TIME are assigned a value of the form hhmmss.sss, where hh is the hour, mm is the minutes, and ss.sss is the seconds and milliseconds.

The leftmost 5 characters of ZONE are assigned a value of the form ±hhmm, where hh and mm are the time difference in hours and minutes with respect to Coordinated Universal Time (UTC i.e. GMT).

VALUES(1) is the year (e.g. 1997).

VALUES(2) is the number of the month (1 denotes January).

VALUES(3) is the day of the month in the range 1 to 31.

VALUES(4) is the time difference in minutes with respect to UTC.

VALUES(5) is the hour in the range 0 to 23.

VALUES(6) is the minutes in the range 0 to 59.

VALUES(7) is the seconds in the range 0 to 59.

VALUES(8) is the milliseconds in the range 0 to 999.

Return value

On error character variables are returns as blanks and integer values are returned as -HUGE(0).


DBLE

Platform | x64, Win32, .NET
Purpose | To convert to double precision.
Class | Elemental function.
Syntax | DOUBLE PRECISION FUNCTION DBLE(A)
Description | A is of type INTEGER, REAL or COMPLEX. If A is COMPLEX the result is the real part of A. The kind type of the result is KIND(0.0D0).


DIGITS

Platform | x64, Win32, .NET
Purpose | To get the number of significant digits for a given type of number.
Class | Inquiry function.
Syntax | INTEGER FUNCTION DIGITS(X)
Description | X is integer or real, scalar or array. The result is dependent on the type and kind type of the variable. It is the number of significant digits in the model for an integer and the number of significant figures in the mantissa of the model for a real. The result depends on the base that is used in the model (e.g. base 2 or base 10).


DIM

Platform

x64, Win32, .NET

Purpose

To get the difference if positive, otherwise zero.

Class

Elemental function.

Syntax

INTEGER FUNCTION DIM(X,Y); INTEGER X,Y
REAL FUNCTION DIM(X,Y); REAL X,Y

Description

Both the result an Y have the same type and kind type as X.

Return value

X-Y if X>Y, otherwise zero.


DOT_PRODUCT

Platform

x64, Win32, .NET

Purpose

To get the dot-product of two numeric or logical vectors.

Class

Transformational function.

Syntax

FUNCTION DOT_PRODUCT(VECTOR_A, VECTOR_B)

Description

The type of the result is a scalar numeric (integer, real, or complex) or logical type and is the same type as each element of the one-dimensional array VECTOR_A.

VECTOR_A and VECTOR_B are one-dimensional arrays with the same length. VECTOR_A is of numeric type or logical type. If VECTOR_A is numeric then VECTOR_B must be numeric (though perhaps not the same type) and if VECTOR_A is logical then VECTOR_B must be logical.

Return value

If VECTOR_A is integer or real then the result is the inner product of the two arrays (i.e. the sum of the products of corresponding elements).

If VECTOR_A is complex then its conjugate is used in the inner product and the result is the complex value that is the sum of the terms. If VECTOR_B = VECTOR_A then the imaginary part of the result will be approximately zero.

If VECTOR_A is logical then the result is the same as ANY(VECTOR_A .AND. VECTOR_B).

If the vectors have size zero then the result is zero or false.


DPROD

Platform | x64, Win32, .NET
Purpose | To get the double precision value of multiplying two reals.
Class | Elemental function.
Syntax | DOUBLE PRECISION FUNCTION DPROD(X, Y) REAL X, Y


EOSHIFT

Platform | x64, Win32, .NET
Purpose | Perform an end-off shift on an array expression.
Class | Transformational function.
Syntax | FUNCTION EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM]) INTEGER SHIFT INTEGER DIM
Description | Perform an end-off shift on an array expression of rank one or perform end-off shifts on all the complete rank one sections along a given dimension of an array expression of rank two or greater. Elements are shifted off at one end of a section and copies of a boundary value are shifted in at the other end. Different sections may have different boundary values and may be shifted by different amounts and in different directions. BOUNDARY is optional and takes the following default values depending in its type:

Integer
Real
Complex
Logical
Character

0
0.0
(0.0, 0.0)
false
filled with blanks

DIM is optional and is a value in the range 1 < DIM < n where n is the rank (i.e. the number of dimensions) of ARRAY. The default value of DIM is 1.

Return value

The result has the same type, type parameters and shape as ARRAY.

Example

If A = [1, 2, 3, 4, 5] then EOSHIFT(A, 2) (i.e. shifted to the left) gives [3, 4, 5, 0, 0], and EOSHIFT(A, -2, 6) gives [6, 6, 1, 2, 3].

If A = [image] then EOSHIFT(A, 1, DIM=2) gives [image].

If S = [1, 0, 2] and B = [10, 0, 0] then
EOSHIFT(A, S, BOUNDARY=B, DIM=2) gives [image].


EPSILON

Platform | x64, Win32, .NET
Purpose | To get the smallest positive value for the given kind type of a real variable.
Class | Inquiry function.
Syntax | REAL FUNCTION EPSILON(X) REAL X;
Description | If p is the number of significant digits (i.e. p= DIGITS(X)) and b is the base that is used in the model (e.g. base 2 or base 10) then EPSILON(X) = [image] .
Return value | X may be a scalar or an array but the result is a scalar.


ERF

Platform | Win32 and x64
Purpose | To compute the error function.
Class | Elemental function
Syntax | REAL FUNCTION ERF(X) REAL X
Description | The return value is of type REAL, of the same kind as X and lies in the range -1 <= erf (x) <= 1.


ERFC

Platform | Win32 and x64
Purpose | To compute the complementary error function.
Class | Elemental function
Syntax | REAL FUNCTION ERFC(X) REAL X
Description | The return value is of type REAL and of the same kind as X. It lies in the range 0 <= erfc(x) <= 2.


ERFC_SCALED

Platform | Win32 and x64
Purpose | To compute the exponentially-scaled complementary error function.
Class | Elemental function
Syntax | REAL FUNCTION ERFC_SCALED(X) REAL X
Description | The return value is of type REAL and of the same kind as X.


EXECUTE_COMMAND_LINE

Platform

x64, Win32

Purpose

To run a shell command, synchronously or asynchronously.

Syntax

SUBROUTINE EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ] )
CHARACTER(LEN=*) COMMAND,CMDMSG
LOGICAL WAIT
INTEGER EXITSTAT,CMDSTAT

Description

The COMMAND argument is passed to the shell and executed. Other arguments are optional,

If WAIT is present and has the value false, the execution of the command is asynchronous otherwise the command is executed synchronously.

The three last arguments allow the user to get status information. After synchronous execution, EXITSTAT contains the integer exit code of the command. CMDSTAT is set to zero if the command line was executed. CMDMSG is assigned an error message if an error has occurred.

Notes

This is an F2008 standard intrinsic.


EXP

Platform

x64, Win32, .NET

Purpose

To get the exponential of the argument.

Class

Elemental function.

Syntax

REAL FUNCTION EXP(X); REAL X;
COMPLEX FUNCTION EXP(X); COMPLEX X;

Description

The result is ex and has the same type as X.


EXPONENT

Platform | x64, Win32, .NET
Purpose | To get the exponent part of a real number.
Class | Elemental function.
Syntax | INTEGER FUNCTION EXPONENT(X) REAL X
Return value | The result is zero if X is zero otherwise the result is the exponent part of the model used for real numbers (i.e. the power to which the base for the model is raised).


FINDLOC

Platform

x64, Win32

Purpose

To get the first position in an array where the element has a given value.

Class

Transformational function.

Syntax

INTEGER FUNCTION FINDLOC(ARRAY, VALUE, DIM [, MASK])
INTEGER FUNCTION FINDLOC(ARRAY, VALUE [, MASK])
INTEGER DIM
LOGICAL MASK

Description

ARRAY is an integer or real array. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is a logical array that is conformable with ARRAY.

Return value

This function determines the location in the ARRAY along dimension DIM with the value VALUE, for which the elements of MASK are TRUE.

If DIM is not present, the result is an array of rank one and size n, otherwise the result is of rank n - 1 and has a shape that is the same as that of ARRAY but omitting dimension DIM.

Example

The value of FINDLOC ([2, 6, 4, 6], VALUE = 6) is [2].

If A has the value
[ 0 -5 7 7 ]
[ 3 4 -1 2 ]
[ 1 5 6 7 ]
and M has the value
[ T T F T ]
[ T T F T ]
[ T T F T ]
then FINDLOC (A, 7, MASK = M) is [1, 4].

The value of FINDLOC ([2, 6, 4], VALUE = 6, DIM = 1) is 2.

If A has the value

[ 1 2 -9 ]
[ 2 3 6 ]
then FINDLOC (A, VALUE = 2, DIM = 1) is [2, 1, 0] and FINDLOC (A, VALUE = 2, DIM = 2) is [2, 1].

Notes

This function was introduced in the Fortran 2008 standard and is similar to MINLOC. When fully implemented it will include additional arguments: KIND and BACK.


FLOOR

Platform | x64, Win32, .NET
Purpose | To get the greatest integer less than or equal to its argument.
Class | Elemental function.
Syntax | INTEGER FUNCTION FLOOR(A [, KIND]) REAL A INTEGER KIND
Description | KIND is optional. If it is omitted the return type is the default integer type. If KIND is present it specifies the kind type of the return value.
Return value | FLOOR(2.6) gives 2. FLOOR(-3.4) gives -4.
See also | CEILING


FRACTION

Platform | x64, Win32, .NET
Purpose | To get the factional part (mantissa) of a real number.
Class | Elemental function.
Syntax | REAL FUNCTION FRACTION(X) REAL X
Return value | The result is zero if X is zero otherwise the result is the fractional part of the model used for real numbers. It has the same kind type as the argument.


GAMMA

Platform | Win32 and x64
Purpose | To compute the Gamma function.
Class | Elemental function
Syntax | REAL FUNCTION GAMMAF(X) REAL X
Description | The return value is of type REAL and has the same kind as X.


GET_COMMAND

Platform

x64, Win32, .NET

Purpose

To get the whole command line.

Syntax

SUBROUTINE GET_COMMAND([COMMAND, LENGTH, STATUS])
CHARACTER (LEN=*) COMMAND
INTEGER LENGTH, STATUS

Description

COMMAND is an optional INTENT(OUT) argument. When present it receives the entire command line.

LENGTH is an optional INTENT(OUT) argument. When present it receives the length of the command by which the program was invoked.

STATUS is an optional INTENT(OUT) argument that receives the error state. It is set to zero on success. A value of -1 indicates that the length of COMMAND is insufficient for the command line. A positive value indicates an error condition.

Notes

This is an F2003 standard intrisic.


GET_COMMAND_ARGUMENT

Platform

x64, Win32, .NET

Purpose

To get the command line argument at a given position.

Syntax

SUBROUTINE GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS] )
INTEGER NUMBER
CHARACTER(LEN=*) VALUE
INTEGER LENGTH, STATUS

Description

NUMBER is an INTENT(IN) argument giving the position (in the range from zero to the number of arguments) of the argument for which information is required. A value of zero indicates the command name.

VALUE is an optional INTENT(OUT) argument that receives the argument at position NUMBER.

LENGTH in an optional INTENT(OUT) argument that receives the length of VALUE.

STATUS is an optional INTENT(OUT) argument that recieves the error state. A zero value indicates success. A value of -1 indicates that the length of VALUE is insufficient for the argument. A positive value indicates an error condition such as NUMBER being greater than the number of arguments.

Notes

This is an F2003 standard intrisic.


GET_ENVIRONMENT_VARIABLE

Platform

Win32 and x64

Purpose

To get the value of an environmental variable.

Syntax

SUBROUTINE GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME])
CHARACTER(LEN=*) NAME, VALUE
INTEGER LENGTH, STATUS
LOGICAL TRIM_NAME

Description

Stores the value of environment variable NAME in VALUE. If NAME is not available then VALUE is filled with spaces. If VALUE is not large enough then it is truncated.
LENGTH is returned as the length needed to store the value or zero if NAME is not available.

STATUS is returned with the result -1 (present but truncated) or 1 (not available) or 2 (not supported) or zero (success).

If TRIM_NAME is present and .FALSE. then trailing spaces in VALUE reflect trailling spaces in the name.

All aguments other than NAME are optional.


HUGE

Platform

x64, Win32, .NET

Purpose

To get the largest positive value for the current model and the given kind type of a real or an integer variable.

Class

Elemental function.

Syntax

REAL FUNCTION HUGE(X); REAL X
INTEGER FUNCTION HUGE(X); INTEGER X

Return value

X may be a scalar or an array but the result is a scalar.


IACHAR

Platform | x64, Win32, .NET
Purpose | To get the position of a character in the ASCII collating sequence.
Class | Elemental function.
Syntax | INTEGER FUNCTION IACHAR(C) CHARACTER C
Description | C is a character of length one.
Return value | The result is an integer in the range 0 <result< 127. Its type is the default integer type.
Example | IACHAR('a') gives 97.


IAND

Platform | x64, Win32, .NET
Purpose | To perform a bitwise AND operation.
Class | Elemental function.
Syntax | INTEGER FUNCTION IAND(I, J) INTEGER I, J
Description | J and the result have the same kind type as I.
Return value | Each bit of I is ANDed with the bit of J in the same position according to the table:

I J IAND
1 1 1
1 0 0
0 1 0
0 0 0


IBCLR

Platform | x64, Win32, .NET
Purpose | To clear a single bit.
Class | Elemental function.
Syntax | INTEGER FUNCTION IBCLR(I, POS) INTEGER I, POS
Description | The position POS is non-negative with zero as the least significant bit. The result has the same kind type as I.
Return value | The result is the same as I except that bit POS is zero.


IBITS

Platform | x64, Win32, .NET
Purpose | To extract a sequence of bits.
Class | Elemental function.
Syntax | INTEGER FUCNTION IBITS(I, POS, LEN) INTEGER I, POS, LEN
Description | The position POS is non-negative with zero as the least significant bit. The length of the sequence LEN is non-negative. The result has the same kind type as I.
Return value | The result has the value of the sequence of LEN bits in I beginning at bit POS, right-adjusted with all other bits zero.


IBSET

Platform | x64, Win32, .NET
Purpose | To set a single bit.
Class | Elemental function.
Syntax | INTEGER FUNCTION IBSET(I, POS) INTEGER I, POS
Description | The position POS is non-negative with zero as the least significant bit. The result has the same kind type as I.
Return value | The result is the same as I except that bit POS is one.


ICHAR

Platform | x64, Win32, .NET
Purpose | To get the position of a character in the collating sequence of a given kind type.
Class | Elemental function.
Syntax | INTEGER FUNCTION ICHAR(C) CHARACTER C
Description | C is a character of length one.
Return value | The result is an integer in the range 0 < result < n - 1 where n is the number of characters in the collating sequence. Its type is the default integer type.


IEOR

Platform | x64, Win32, .NET
Purpose | To perform a bitwise exclusive OR operation.
Class | Elemental function.
Syntax | INTEGER FUNCTION IEOR(I, J) INTEGER I, J
Description | J and the result have the same kind type as I.
Return value | Each bit of I is XORed with the bit of J in the same position according to the table:

I J IEOR
1 1 0
1 0 1
0 1 1
0 0 0


INDEX

Platform

x64, Win32, .NET

Purpose

To get the starting position of a substring within a string.

Class

Elemental function.

Syntax

INTEGER FUNCTION INDEX(STRING, SUBSTRING [, BACK])
CHARACTER (LEN=*) STRING, SUBSTRING
LOGICAL BACK

Description

If BACK is omitted or has the value false then STRING is scanned from the beginning for the first occurrence of SUBSTRING. Zero is returned if all of SUBSTRING is not found or if LEN(SUBSTRING) = 0.

If BACK is true then scanning is from the end to find the last occurrence. Zero is returned if all of SUBSTRING is not found. LEN (STRING) + 1 is returned if LEN (SUBSTRING) = 0.

Return value

If SUBSTRING is found the result is a positive integer giving its position.

Example

INDEX('SALFORD', 'FORD') gives 4.
INDEX('FORTRAN', 'R', BACK=.TRUE.) gives 5.


INT

Platform | x64, Win32, .NET
Purpose | To convert to integer type.
Class | Elemental function.
Syntax | INTEGER FUNCTION INT(A [,KIND]) INTEGER KIND
Description | A is of type INTEGER, REAL or COMPLEX. The kind type of the result is KIND if it is present otherwise it is the default integer kind.
Return value | If A is integer the result is A (if it is in range). If A is real the result is the integer part of A truncated towards zero. If A is complex, INT(A) is obtained by applying the above rule to the real part of A.


IOR

Platform | x64, Win32, .NET
Purpose | To perform a bitwise OR operation.
Class | Elemental function.
Syntax | INTEGER FUNCTION IOR(I, J) INTEGER I, J
Description | J and the result have the same kind type as I.
Return value | Each bit of I is ORed with the bit of J in the same position according to the table:

I J IEOR
1 1 1
1 0 1
0 1 1
0 0 0


ISHFT

Platform | x64, Win32, .NET
Purpose | To perform a bitwise shift operation.
Class | Elemental function.
Syntax | INTEGER FUNCTION ISHFT(I, SHIFT) INTEGER I, SHIFT
Description | SHIFT is a positive or negative integer whose absolute value is less than or equal to BIT_SIZE(I). A positive value denotes a shift to the left. Bits that are shifted out are lost and zeros are shifted in from the opposite end. The result has the same kind type as I.
Notes | The use of negative, short integer (KIND =1 or KIND = 2) values of I gives undefined results.


ISHFTC

Platform

x64, Win32, .NET

Purpose

To perform a bitwise circular shift operation.

Class

Elemental function.

Syntax

INTEGER FUNCTION ISHFTC(I, SHIFT [, SIZE])
INTEGER I, SHIFT, SIZE

Description

SHIFT is a positive or negative integer whose absolute value is less than or equal to SIZE.

SIZE is an optional positive integer less than or equal to BIT_SIZE (I). The default value of SIZE is BIT_SIZE(I).

A positive value of SHIFT denotes a shift to the left. The leftmost SIZE bits are processed and SHIFT bits are shifted out from one end and shifted in from the opposite end. The result has the same kind type as I.


KIND

Platform | x64, Win32, .NET
Purpose | To get the value of the kind type of the argument.
Class | Inquiry function.
Syntax | INTEGER FUNCTION KIND(X)
Description | X is any intrinsic type (scalar or array).
Return value | The result is the kind type parameter of X represented as a scalar of the default integer type.


LBOUND

Platform

x64, Win32, .NET

Purpose

To return all the lower bounds or a specified lower bound of an array.

Class

Inquiry function.

Syntax

INTEGER FUNCTION LBOUND(ARRAY [, DIM [, KIND]])
INTEGER DIM, KIND

Description

ARRAY is an array of any type, not a scalar. If it is a pointer it must be associated. If it is an allocatable array it must be allocated. DIM (optional) is a scalar integer with a value in the range 1 < DIM < n, where n is the rank of ARRAY.

The result is of default integer type. It is scalar if DIM is present; otherwise, the result is an array of rank one and size n, where n is the rank of ARRAY. If KIND is present it provides the INTEGER kind value of the result.

Return value

  1. For an array section or for an array expression other than a whole array or array structure component, LBOUND(ARRAY, DIM) has the value 1. For a whole array or array structure component, LBOUND(ARRAY, DIM) has the value:

    1. equal to the lower bound for subscript DIM of ARRAY if dimension DIM of ARRAY does not have extent zero or if ARRAY is an assumed-size array of rank DIM, or

    2. 1 otherwise.

  2. LBOUND(ARRAY) has a value whose ith component is equal to LBOUND(ARRAY, i), for i = 1, 2, ..., n, where n is the rank of ARRAY.

Notes

LBOUND returns a value of default integer type on all platforms. For x64 this will be 32 bits by default.

Example

If A is declared by the statement

REAL A(2:3,7:10)

then LBOUND(A) is [2, 7] and LBOUND(A, DIM=2) is 7.


LEN

Platform | x64, Win32, .NET
Purpose | To get the length of a character string.
Class | Inquiry function.
Syntax | INTEGER FUNCTION LEN(STRING) CHARACTER (LEN=*) STRING
Return value | The result is the number of characters in STRING if it is scalar or in an element of STRING if it is array of character strings.
Example | If STRING is declared as CHARACTER (LEN=20)::STRING(10) LEN(STRING) has the value 20.


LEN_TRIM

Platform | x64, Win32, .NET
Purpose | To get the length of a character string excluding trailing blanks.
Class | Elemental function.
Syntax | INTEGER FUNCTION LEN_TRIM(STRING) CHARACTER (LEN=*) STRING
Example | LEN_TRIM('A B ') has the value 3 and LEN_TRIM(' ') has the value 0.


LGE

Platform | x64, Win32, .NET
Purpose | To test if a string is lexically greater than or equal to another string, using the ASCII collating sequence.
Class | Elemental function.
Syntax | LOGICAL FUNCTION LGE(STRING_A, STRING_B) CHARACTER (LEN=*) STRING_A, STRING_B
Description | If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.
Return value | The result is true if the strings are equal or if STRING_A follows STRING_B in the ASCII collating sequence; otherwise, the result is false. The result is true if both strings are of zero length.


LGT

Platform | x64, Win32, .NET
Purpose | To test if a string is lexically greater than another string, using the ASCII collating sequence.
Class | Elemental function.
Syntax | LOGICAL FUNCTION LGT(STRING_A, STRING_B) CHARACTER (LEN=*) STRING_A, STRING_B
Description | If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.
Return value | The result is true if STRING_A follows STRING_B in the ASCII collating sequence; otherwise, the result is false. The result is false if both strings are of zero length.


LLE

Platform | x64, Win32, .NET
Purpose | To test if a string is lexically less than or equal to another string, using the ASCII collating sequence.
Class | Elemental function.
Syntax | LOGICAL FUNCTION LLE(STRING_A, STRING_B) CHARACTER (LEN=*) STRING_A, STRING_B
Description | If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.
Return value | The result is true if the strings are equal or if STRING_A precedes STRING_B in the ASCII collating sequence; otherwise, the result is false. The result is true if both strings are of zero length.


LLT

Platform | x64, Win32, .NET
Purpose | To test if a string is lexically less than another string, using the ASCII collating sequence.
Class | Elemental function.
Syntax | LOGICAL FUNCTION LLT(STRING_A, STRING_B) CHARACTER (LEN=*) STRING_A, STRING_B
Description | If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.
Return value | The result is true if STRING_A precedes STRING_B in the ASCII collating sequence; otherwise, the result is false. The result is false if both strings are of zero length.


LOG

Platform

x64, Win32, .NET

Purpose

To get the natural logarithm of the argument.

Class

Elemental function.

Syntax

REAL FUNCTION LOG(X); REAL X
COMPLEX FUNCTION LOG(X); COMPLEX X

Description

If X is real, its value must be greater than zero. If X is complex, its value must not be zero.

Return value

The result has the value log e X. A complex result is the principal value with imaginary part w in the range -p < w < p. The imaginary part of the result is p only when the real part of the argument is less than zero and the imaginary part of the argument is zero.


LOG10

Platform | x64, Win32, .NET
Purpose | To get the common logarithm of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION LOG(X) REAL X
Description | X must be greater than zero.
Return value | The result has the value log10 X.


LOG_GAMMA

Platform | Win32 and x64
Purpose | Compute the natural logarithm of the absolute value of the Gamma function.
Class | Elemental function
Syntax | REAL FUNCTION LOG_GAMMA(X) REAL X
Description | The return value is of type REAL of the same kind as X. X must be greater than zero.


LOGICAL

Platform | x64, Win32, .NET
Purpose | To convert to another logical kind type.
Class | Elemental function.
Syntax | LOGICAL FUNCTION LOGICAL(L [, KIND]) LOGICAL L INTEGER KIND
Description | The kind type of the result is KIND if it is present otherwise it is the default logical kind.


MATMUL

Platform

x64, Win32, .NET

Purpose

To multiply two numeric or logical matrices

Class

Transformational function.

Syntax

FUNCTION MATMUL(MATRIX_A, MATRIX_B)
MATRIX_A, MATRIX_B

Description

MATRIX_A shall be of numeric type (integer, real, or complex) or of logical type. MATRIX_A and MATRIX_B must be array valued and of rank one or two.

MATRIX_B must be of numeric type if MATRIX_A is of numeric type and of logical type if MATRIX_A is of logical type. If MATRIX_A has rank one, MATRIX_B must have rank two. If MATRIX_B has rank one, MATRIX_A must have rank two. The size of the first (or only) dimension of MATRIX_B must equal the size of the last (or only) dimension of MATRIX_A.

Return value

If the arguments are of numeric type, the type and kind type parameter of the result are determined by the types of the arguments. If the arguments are of type logical, the result is of type logical. The result is the standard matrix product of the two matrices. In the case where the numeric result for element ( i , j ) takes the form
SUM (MATRIX_A (i, :) * MATRIX_B (:, j )),
the corresponding logical result takes the form
ANY (MATRIX_A ( i, : ) .AND. MATRIX_B ( :, j )).

The shape of the result depends on the shapes of the arguments as follows:

Case (i): If MATRIX_A has shape (n, m) and MATRIX_B has shape (m, k), the result has shape (n, k).

Case (ii): If MATRIX_A has shape (m) and MATRIX_B has shape (m, k), the result has shape (k).

Case (iii): If MATRIX_A has shape (n, m) and MATRIX_B has shape (m), the result has shape (n ).


MAX

Platform

x64, Win32, .NET

Purpose

To get the maximum value of a list of numbers.

Class

Elemental function.

Syntax

INTEGER FUNCTION MAX(A1, A2 [, A3, ...]); INTEGER A1,...
REAL FUNCTION MAX(A1, A2 [, A3, ...]); REAL A1,...

Description

The arguments must all be of same type and kind type which will be the type and kind type of the result.

Return value

The result is the largest item in the list.


MAXEXPONENT

Platform | x64, Win32, .NET
Purpose | To get the maximum exponent for the kind type of the argument.
Class | Inquiry function.
Syntax | INTEGER FUNCTION MAXEXPONENT(X) REAL X
Description | X can be a real scalar or real array of any kind type.
Return value | The result is the largest exponent that is permissible for the given kind type.


MAXLOC

Platform

x64, Win32, .NET

Purpose

To get the first position in an array where the element has the maximum value for the array.

Class

Transformational function.

Syntax

INTEGER FUNCTION MAXLOC(ARRAY, DIM [, MASK])
INTEGER FUNCTION MAXLOC(ARRAY [, MASK])
INTEGER DIM
LOGICAL MASK

Description

ARRAY is an integer or real array. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is a logical array that is conformable with ARRAY.

Return value

This function determines the location of the first element of ARRAY along dimension DIM having the maximum value of the elements identified by MASK.

If DIM is not present, the result is an array of rank one and size n, otherwise the result is of rank n - 1 and has a shape that is the same as that of ARRAY but omitting dimension DIM.

Example

If A = [3, 2, 9, 9] then MAXLOC(A) is 3.

If A = [image] then MAXLOC(A, MASK = A .LT. 5) is [1, 4] which is the location of the largest value for this mask.

If A = [image] then MAXLOC(A, DIM = 1) is [2, 2, 2, 1] and MAXLOC(A, DIM = 2) is [4, 3].


MAXVAL

Platform

x64, Win32, .NET

Purpose

To get the maximum value of the elements of an array.

Class

Transformational function.

Syntax

FUNCTION MAXVAL(ARRAY, DIM [, MASK])
FUNCTION MAXVAL(ARRAY [, MASK])
INTEGER DIM
LOGICAL MASK

Description

ARRAY is an integer or real array. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is a logical array that is conformable with ARRAY.

Return value

This function determines the maximum value of the elements of ARRAY along dimension DIM corresponding to the true elements of MASK. The result is a scalar or array having the same type.

If DIM is not present, the result is scalar, otherwise the result is of rank n - 1 and has a shape that is the same as that of ARRAY but omitting dimension DIM.

If ARRAY has size zero, MAXVAL(ARRAY) gives the negative number of largest magnitude for the given type and kind type.

If MASK is false for all elements then MAXVAL(ARRAY, MASK=MASK) gives the negative number of largest magnitude for the given type and kind type.

Example

If A = [3, 2, 9, 9] then MAXVAL(A) is 9.

If A = [image] then MAXVAL(A, MASK = A .LT. 5) is 4.

If A = [image] then MAXVAL(A, DIM = 1) is [5, 6, 7, 8] and MAXVAL(A, DIM = 2) is [8, 7]


MERGE

Platform | x64, Win32, .NET
Purpose | To merge two arrays according to a given mask.
Class | Elemental function.
Syntax | FUNCTION MERGE(TSOURCE, FSOURCE, MASK) LOGICAL MASK
Description | TSOURCE is an array of any type and kind type. FSOURCE and the result have the same type and kind type as TSOURCE. MASK is a logical array that is conformable to TSOURCE, FSOURCE and the result.
Return value | For each element, the result is TSOURCE if MASK is true and FSOURCE otherwise.
Example | If A = [1, 4, 5], B = [4, 3, 6] then MERGE(A, B, MASK= A < B) gives [1, 3, 5].


MIN

Platform

x64, Win32, .NET

Purpose

To get the minimum value of a list of numbers.

Class

Elemental function.

Syntax

INTEGER FUNCTION MIN(A1, A2 [, A3, ...]); INTEGER A1,...
REAL FUNCTION MIN(A1, A2 [, A3, ...]); REAL A1,...

Description

The arguments must all be of same type and kind type which will be the type and kind type of the result.

Return value

The result is the smallest item in the list.

Example

MIN(-1.0, 0.0, 2.0) gives -1.0.


MINEXPONENT

Platform | x64, Win32, .NET
Purpose | To get the minimum exponent for the kind type of the argument.
Class | Inquiry function.
Syntax | INTEGER FUNCTION MAXEXPONENT(X) REAL X
Description | X can be a real scalar or real array of any kind type.
Return value | The result is the smallest exponent (i.e. the negative value with largest magnitude) that is permissible for the given kind type.


MINLOC

Platform

x64, Win32, .NET

Purpose

To get the first position in an array where the element has the minimum value for the array.

Class

Transformational function.

Syntax

INTEGER FUNCTION MINLOC(ARRAY, DIM [, MASK])
INTEGER FUNCTION MINLOC(ARRAY [, MASK])
INTEGER DIM
LOGICAL MASK

Description

ARRAY is an integer or real array. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is a logical array that is conformable with ARRAY.

Return value

This function determines the location of the first element of ARRAY along dimension DIM having the minimum value of the elements identified by MASK.

If DIM is not present, the result is an array of rank one and size n, otherwise the result is of rank n - 1 and has a shape that is the same as that of ARRAY but omitting dimension DIM.

Example

If A = [3, 2, 2, 9] then MINLOC(A) is 2.

If A = [image] then MINLOC(A, MASK = A > 3) is [1, 4] which is the location of the smallest value for this mask.

If A = [image] then MINLOC(A, DIM = 1) is [1, 1, 1, 2] and MINLOC(A, DIM = 2) is [1, 4].


MINVAL

Platform

x64, Win32, .NET

Purpose

To get the minimum value of the elements of an array.

Class

Transformational function.

Syntax

FUNCTION MINVAL(ARRAY, DIM [, MASK])
FUNCTION MINVAL(ARRAY [, MASK])
INTEGER DIM
LOGICAL MASK

Description

ARRAY is an integer or real array. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is a logical array that is conformable with ARRAY.

Return value

This function determines the minimum value of the elements of ARRAY along dimension DIM corresponding to the true elements of MASK. The result is a scalar or array having the same type.

If DIM is not present, the result is scalar, otherwise the result is of rank n - 1 and has a shape that is the same as that of ARRAY but omitting dimension DIM.

If ARRAY has size zero, MINVAL(ARRAY) gives the positive number of largest magnitude for the given type and kind type.

If MASK is false for all elements then MINVAL(ARRAY, MASK=MASK) gives the positive number of largest magnitude for the given type and kind type.

Example

If A = [3, 2, 2, 9] then MINVAL(A) is 2.

If A = [image] then MINVAL(A, MASK = A > 5) is 7.

If A = [image] then MINVAL(A, DIM = 1) is [1, 2, 3, 4] and MINVAL(A, DIM = 2) is [1, 4].


MOD

Platform

x64, Win32, .NET

Purpose

To get the remainder after division.

Class

Elemental function.

Syntax

INTEGER FUNCTION MOD(A, P); INTEGER A, P
REAL FUNCTION MOD(A, P); REAL A, P

Description

P and the result have the same type and kind type as A.

Return value

If P ¹ 0, the result is the remainder of A after division by P given by A - INT(A/P) * P.

Example

MOD(4.0, 3.0) gives approximately 1.0. MOD(8, -6) gives 2.


MODULO

Platform

x64, Win32, .NET

Purpose

To get the modulo.

Class

Elemental function.

Syntax

INTEGER FUNCTION MODULO(A, P); INTEGER A, P
REAL FUNCTION MODULO(A, P); REAL A, P

Description

P and the result have the same type and kind type as A. P must be non-zero.

Return value

If A is of type integer, MODULO(A, P) has the value R such that A = Q * P + R, where Q is an integer. If P > 0 then 0 < R < P. If P > 0 then P < R < 0.

If A is of type real then the result is A – FLOOR (A / P) * P.

Example

MODULO(8, 6) gives 2. MODULO(8, -6) gives -4.


MVBITS

Platform

x64, Win32, .NET

Purpose

To copy a sequence of bits.

Class

Elemental subroutine.

Syntax

SUBROUTINE MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)
INTEGER,INTENT(IN) ::FROM, FROMPOS, LEN, TOPOS
INTEGER,INTENT(INOUT)::TO

Description

FROMPOS > 0 and FROMPOS + LEN < BIT_SIZE(FROM).

LEN > 0.

TO has the same kind type as FROM.

TOPOS > 0 and TOPOS + LEN < BIT_SIZE(TO).

Return value

After calling the subroutine the value of TO is modified by copying bits from FROM. LEN bits are copied from FROM starting at FROMPOS. The bits are copied to TO starting at TOPOS. FROM and TO are zero-based, counting from the least significant bit.

Example

If T = 4 then after a call to MVBITS(12, 2, 2, TO, 0), TO takes the value 7.


NEAREST

Platform | x64, Win32, .NET
Purpose | To get the nearest available value to the right or to the left.
Class | Elemental function.
Syntax | REAL FUNCTION NEAREST(X, S) REAL X, S
Description | The sign of S provides the direction. A positive value means to the right (towards positive infinity); a negative value means to the left (towards negative infinity). S must not be zero.
Return value | The result is the nearest machine representable value to X (that is not equal to X) in the given direction.


NINT

Platform | x64, Win32, .NET
Purpose | To get the nearest integer to a given real value.
Class | Elemental function.
Syntax | INTEGER FUNCTION NINT(A [, KIND]) REAL A INTEGER KIND
Description | If KIND is present it gives the kind type of the integer result, otherwise the result is of default integer type.
Return value | The result is obtained by rounding off the given real value to the nearest integer. If A > 0, NINT(A) has the value INT(A + 0.5); if A < 0, NINT(A) has the value INT(A – 0.5).


NOT

Platform | x64, Win32, .NET
Purpose | To perform a bitwise NOT operation.
Class | Elemental function.
Syntax | INTEGER FUNCTION NOT(I) INTEGER I
Description | The result has the same kind type as I.
Return value | Each bit of I is transposed according to the table:

I NOT
1 0
0 1


NULL

Platform | x64, Win32, .NET
Purpose | To disassociate a pointer.
Class | Transformational function.
Syntax | FUNCTION NULL([MOLD])
Description | If MOLD is present it is a pointer of any type and gives the type of the result. If MOLD is absent then the type of the result matches the target of the assignment.
Return value | This function provides an alternative to using the standard intrinsic NULLIFY. This functional form can be included with a declaration.
Example | REAL, POINTER :: X => NULL( )


PACK

Platform

x64, Win32, .NET

Purpose

To pack a given array into an array of rank one.

Class

Transformational function.

Syntax

FUNCTION PACK(ARRAY, MASK [, VECTOR])
LOGICAL MASK

Description

ARRAY is an array of any type. MASK is a logical array that is conformable with ARRAY. VECTOR is optional. VECTOR and the result of the function are arrays of rank one with the same type and type parameters as ARRAY.

If VECTOR is absent the size of the result is equal to the number of elements of MASK that are true. If VECTOR is present then the size of the result is equal to the size of VECTOR which must not be less than the number of elements of MASK that are true.

Return value

The result is a one-dimensional array obtained by selecting those values of ARRAY for which the corresponding element in MASK is true. VECTOR can be used to provide default values for the result after the point at which packing ceases.

Example

If M = [image] then PACK(M, MASK=M>2) gives [4, 5, 3, 6].

If also V=[0, 0, 0, 0, 0] then PACK(M, MASK=M>2, VECTOR=V) gives [4, 5, 3, 6, 0].


PRECISION

Platform

x64, Win32, .NET

Purpose

To get the decimal precision for real numbers with the kind type of the argument.

Class

Inquiry function.

Syntax

INTEGER FUNCTION PRECISION(X); REAL X
INTEGER FUNCTION PRECISION(X); COMPLEX X

Description

X may be real or complex, scalar or array valued. The result is a scalar integer of the default kind type.

Return value

The result is the number of significant decimal figures that can be stored for the given real kind type.


PRESENT

Platform | x64, Win32, .NET
Purpose | To determine whether an optional argument is present.
Class | Inquiry function.
Syntax | LOGICAL FUNCTION PRESENT(A)
Description | The argument A is the name of an optional dummy argument in the current subprogram. It may be of any type, a scalar or an array, and it may be a pointer. It may also be the (dummy) name of a procedure. There is no assumed INTENT attribute for A.
Return value | The result has the value true if the optional argument A is present in the current call to the subprogram and otherwise has the value false.


PRODUCT

Platform

x64, Win32, .NET

Purpose

To get the product of all the elements of an array.

Class

Transformational function.

Syntax

FUNCTION PRODUCT(ARRAY, DIM [, MASK])
FUNCTION PRODUCT(ARRAY [, MASK])
LOGICAL MASK
INTEGER DIM

Description

ARRAY is an array of type integer, real or complex. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is a logical array that is conformable to ARRAY. The result will have the same attributes as ARRAY except that the rank will be different. It is scalar if DIM is absent or ARRAY has rank one; otherwise, the result is an array of rank n - 1. If ARRAY has rank one and DIM is present then the given value of DIM is ignored and defaults to one.

Return value

Case (i): The result of PRODUCT(ARRAY) has a value equal to the product of all the elements of ARRAY. It has the value one if ARRAY has size zero.

Case (ii): The result of PRODUCT (ARRAY, MASK = MASK) has a value equal to the product of the elements of ARRAY corresponding to the elements of MASK that are true. It has the value one if there are no true elements.

Case (iii): The result of PRODUCT(ARRAY, DIM = DIM [, MASK = MASK]) has a value equal to the product (using the mask if present) of the elements of ARRAY along the given dimension.

Example

If A = [image] then PRODUCT(A, DIM = 1) gives [4, 10, 18] and PRODUCT(A, DIM = 2) gives [6, 120].


RADIX

Platform | x64, Win32, .NET
Purpose | To get the base used internally for a given type and kind type.
Class | Inquiry function.
Syntax | INTEGER FUNCTION RADIX(X)
Description | X is of type integer or real, a scalar or an array.
Return value | The result is the scalar integer value of the model used by the compiler to represent values of the given type and kind type.


RANDOM_NUMBER

Platform | x64, Win32, .NET
Purpose | To get a pseudo-random number or an array of pseudo-random numbers in a uniform distribution over the range 0 < x < 1.
Class | Subroutine.
Syntax | SUBROUTINE RANDOM_NUMBER(HARVEST) REAL,INTENT(OUT)::HARVEST
Description | HARVEST may be a scalar which receives a single pseudo-random number or it may be an array to receive a sequence of pseudo-random numbers. The seed used by the random number generator can be set and interrogated using the subroutine RANDOM_SEED .


RANDOM_SEED

Platform

x64, Win32, .NET

Purpose

To restart or interrogate the pseudo-random number generator used by RANDOM_NUMBER .

Class

Subroutine.

Syntax

SUBROUTINE RANDOM_SEED([SIZE, PUT, GET])
INTEGER, INTENT(OUT)::SIZE
INTEGER, INTENT(IN)::PUT
INTEGER, INTENT(OUT)::GET

Description

RANDOM_SEED must have either no arguments or exactly one argument. SIZE is a scalar integer giving the number of integers N that are used by the random number generator to represent the seed. PUT is a one-dimensional array of size > N that can be used to initialise the seed parameters. GET is a one-dimensional array of size > N that can be used to get the current values of the seed parameters.

If RANDOM_SEED is called with no arguments then a default initial value is assigned to the seed.


RANGE

Platform | x64, Win32, .NET
Purpose | To get the range of the decimal exponent for integer or real numbers with a given kind type.
Class | Inquiry function.
Syntax | INTEGER FUNCTION RANGE(X)
Description | X is of type integer, real or complex. It may be a scalar or an array.
Return value | The result is a scalar integer giving the smaller of the largest positive exponent and the absolute value of the largest negative exponent that is used by the compiler for numbers of the given type and kind type. For real values of kinds 1, 2 and 3 the results are respectively 37, 307 and 4931.


REAL

Platform | x64, Win32, .NET
Purpose | To convert to real type.
Class | Elemental function.
Syntax | REAL FUNCTION REAL(A [,KIND]) INTEGER KIND
Description | A is of type INTEGER, REAL or COMPLEX. If A is of type INTEGER or REAL, the result is REAL and kind type of the result is KIND if it is present otherwise it is the default real kind. If A is of type COMPLEX, the result is REAL and the kind type of the result is KIND otherwise it is the kind type of A (i.e. A is COMPLEX and the result is REAL with the same kind type value).
Return value | If A is integer or real, the result is A. If A is complex, the result is the real part A.


REPEAT

Platform | x64, Win32, .NET
Purpose | To concatenate several copies of a string.
Class | Transformational function.
Syntax | CHARACTER (LEN=*) FUNCTION REPEAT(STRING, NCOPIES) CHARACTER (LEN=*) STRING INTEGER NCOPIES
Description | NCOPIES is a non-negative value giving the number of times STRING is to appear in the result.
Return value | The return is the resultant string.


RESHAPE

Platform

x64, Win32, .NET

Purpose

To construct an array of a specified shape from the elements of a given array.

Class

Transformational function.

Syntax

FUNCTION RESHAPE(SOURCE, SHAPE [, PAD, ORDER])
INTEGER SHAPE, ORDER

Description

SOURCE is an array of any type. If PAD is present it is also an array of the same type and type parameters as SOURCE which is used to fill in any values that are missing from the end of SOURCE. PAD is used repeatedly if necessary.

SHAPE is an one-dimensional integer array with n values where 0 < n < 8. It gives the shape of the result (the number of elements along each dimension). If ORDER is present, it has the same shape as SHAPE and contains a permutation of the integers (1, 2, 3, . . ., n). The default is the natural order. ORDER is used to provide a permutation on the subscript order of the result.

Return value

The result is an array constructed from the elements of SOURCE and PAD using the shape given by SHAPE and ORDER.

Example

RESHAPE((/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) as the value [image] .

RESHAPE((/ 1, 2, 3, 4, 5, 6 /), (/ 2, 4 /), (/ 0, 0 /), (/ 2, 1 /)) has the value [image].


RRSPACING

Platform | x64, Win32, .NET
Purpose | To get the reciprocal of the relative spacing of model numbers near the argument value.
Class | Elemental function.
Syntax | REAL FUNCTION RRSPACING(X) REAL X
Description | See the ISO standard.


SCALE

Platform | x64, Win32, .NET
Purpose | To provide a model-based scaling of a real value.
Class | Elemental function.
Syntax | REAL FUNCTION SCALE (X, I) REAL X INTEGER I
Return value | The result is X * bI where b is the base that is used by the compiler to model real numbers.


SCAN

Platform | x64, Win32, .NET
Purpose | To scan a string for any one of the characters in a set of characters.
Class | Elemental function.
Syntax | INTEGER FUNCTION SCAN(STRING, SET [, BACK]) CHARACTER (LEN=*) STRING, SET LOGICAL BACK
Description | If BACK is omitted, this function scans STRING for the first occurrence of any of the characters in SET. If BACK is set to true, scanning starts at the end of STRING.
Return value | If a match is found, the result is an integer marking the position of the character in STRING starting at 1. If a match is not found or the length of STRING or SET is zero, the result is zero.
Example | SCAN ('FORTRAN', 'TR') has the value 3. SCAN ('FORTRAN', 'TR', BACK = .TRUE.) has the value 5.


SELECTED_INT_KIND

Platform | x64, Win32, .NET
Purpose | To get the kind type parameter for integers with a given range.
Class | Transformational function.
Syntax | INTEGER FUNCTION SELECTED_INT_KIND(R) INTEGER R
Description | The result is the kind type for integers n such that -10R < n < 10R .
Example | SELECTED_INT_KIND(6) gives the kind type that may be used to represent values in the range -999999 < n < 999999.


SELECTED_REAL_KIND

Platform | x64, Win32, .NET
Purpose | To get the kind type parameter for real values with a given precision and range.
Class | Transformational function.
Syntax | INTEGER FUNCTION SELECTED_REAL_KIND([P, R]) INTEGER P, R
Description | SELECTED_REAL_KIND must have at least one argument. P is the required number of significant decimal digits (as returned by the intrinsic function PRECISION) and R is the required decimal exponent range (as returned by the intrinsic function RANGE).
Return value | The result is the kind type parameter for real values with the given precision and/or range. A value of -1 is returned if P is out of range. A value of -2 is returned if R is out of range. A value of -3 is returned if both P and R are out of range.


SET_EXPONENT

Platform | x64, Win32, .NET
Purpose | To set the exponent of a real value relative to that used by model numbers.
Class | Elemental function.
Syntax | REAL FUNCTION SET_EXPONENT(X, I) REAL X INTEGER I
Description | See the ISO standard.


SHAPE

Platform | x64, Win32, .NET
Purpose | To get the shape of an array or a scalar.
Class | Inquiry function.
Syntax | INTEGER FUNCTION SHAPE(SOURCE)
Description | SOURCE is an array or scalar of any type.
Return value | The result is a one-dimensional integer array whose size is equal to the rank of SOURCE and whose values represent the shape of SOURCE (the extent of each dimension in turn).
Example | If A has dimension (2:5, -2:5) then SHAPE(A) gives (/ 4, 8 /). If B is a scalar then SHAPE(B) has rank one and zero size.


SIGN

Platform | x64, Win32, .NET
Purpose | To form a number from the absolute value of one number and the sign of another.
Class | Elemental function.
Syntax | FUNCTION SIGN(A, B)
Description | A can be integer or real. B and the result of the function have the same type as A.
Return value | The result is formed by taking the absolute value of A and multiplying by -1 if B is negative. If B is zero the result may be unsafe.


SIN

Platform

x64, Win32, .NET

Purpose

To get the Sine of the argument.

Class

Elemental function.

Syntax

REAL FUNCTION SIN(X); REAL X
COMPLEX FUNCTION SIN(X); COMPLEX X

Description

If X is real it is an angle measured in radians. If X is complex its real part is in radians.


SINH

Platform | x64, Win32, .NET
Purpose | To get the Hyperbolic sine of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION SINH(X) REAL X COMPLEX FUNCTION SINH(X) COMPLEX X
Description | The result has the same type as X.


SIZE

Platform

x64, Win32, .NET

Purpose

To get the extent of an array along a specified dimension or the total number of elements in the array.

Class

Inquiry function.

Syntax

INTEGER FUNCTION SIZE(ARRAY [, DIM [, KIND]])
INTEGER DIM, KIND

Description

ARRAY is an array of any type. If it is allocatable it must be allocated. If it is a pointer it must be associated. If it is an assumed size array then DIM must be present and have a value which is less than the rank of ARRAY.

If DIM is present it is a scalar in the range 1 < DIM < n where n is the rank of ARRAY.
If KIND is present it provides the INTEGER kind value of the result.

Return value

The result has a value equal to the extent of dimension DIM of ARRAY or, if DIM is absent, the total number of elements of ARRAY.

Notes

The Fortran Standard stipulates that the SIZE intrinsic function (without a KIND argument) should return an value of default integer type. For FTN95 this is a 32 bit integer unless the default is changed via a command line switch. FTN95 is not standard conforming in this respect for the x64 platform unless /SIZE_ISO or /ISO is used on the command line. In other words, SIZE usually provides a 64 bit value for x64. An exception to this rule is that a call to a routine of the the form FUNC(SIZE(...)) is standard conforming. This is because the type of an argument will be critical when used with generic functions.


SPACING

Platform | x64, Win32, .NET
Purpose | To get the absolute spacing of model numbers near the argument value.
Class | Elemental function.
Syntax | REAL FUNCTION SPACING(X) REAL X
Description | See the ISO standard. If X is zero the result is the same as TINY(X).


SPREAD

Platform

x64, Win32, .NET

Purpose

To replicate an array by adding a dimension.

Class

Transformational function.

Syntax

FUNCTION SPREAD(SOURCE, DIM, NCOPIES)
INTEGER DIM, NCOPIES

Description

SOURCE is of any type, either an array or a scalar. The result has the same type as SOURCE and has rank n + 1 where n is the rank of SOURCE.

DIM is a scalar integer with an value in the range 1 < DIM < n. NCOPIES is a scalar integer giving the number of times the original array is to be replicated.

Example

If A = [6, 2, 3] then SPREAD(A, DIM = 2, NCOPIES = 4) gives [image].


SQRT

Platform

x64, Win32, .NET

Purpose

To get the square root of the argument.

Class

Elemental function.

Syntax

REAL FUNCTION SQRT(X); REAL X
COMPLEX FUNCTION SQRT(X); COMPLEX X

Description

If X is real, it must not be negative.

If X is complex, the result is the principal value which has a real part that is non-negative. If the real part is zero, the imaginary part is non-negative.


STORAGE_SIZE

Platform | x64, Win32
Purpose | To get the size of an object in bits.
Syntax | INTEGER FUNCTION STORAGE_SIZE(A, [,KIND]) INTEGER KIND
Description | The argument A is a scalar or array of any type. If KIND is present then the returned value has this kind value.
Notes | The standard ISO_C_BINDING module has a similar function C_SIZEOF that returns the size in bytes


SUM

Platform

x64, Win32, .NET

Purpose

To sum the elements of an array.

Class

Transformational function.

Syntax

FUNCTION SUM(ARRAY, DIM [,MASK])
FUNCTION SUM(ARRAY [,MASK])
INTEGER DIM

Description

ARRAY is an array of any type. The result is a scalar or array with the same type as elements of ARRAY. DIM is a scalar integer in the range 1 < DIM < n where n is the rank of ARRAY. MASK is an array of type logical which is conformable with ARRAY. Elements of MASK are set to true when corresponding elements of ARRAY are to be included in the sum.

If DIM is present, summation is along the dimension specified by DIM resulting in an array of rank n - 1. If DIM is absent, the result is a scalar giving the sum of all the elements (for which MASK is true).

Example

If A is [image] then SUM(A, DIM = 1) is [5, 7, 9] and SUM(A, DIM = 2) is [6, 15].


SYSTEM_CLOCK

Platform

x64, Win32, .NET

Purpose

To get integer data from a real-time clock.

Class

Subroutine

Syntax

SUBROUTINE SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])
INTEGER,INTENT(OUT)::COUNT, COUNT_RATE, COUNT_MAX

Description

COUNT is incremented by one for each clock count until the value COUNT_MAX is reached and is reset to zero at the next count.

COUNT_RATE is the number of processor clock counts per second.

COUNT_MAX the maximum value that COUNT can have.

Note

INTEGER values can be KIND 2,3 or 4 but KIND 2 will soon overflow.


TAN

Platform | x64, Win32, .NET
Purpose | To get the Tangent of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION TAN(X) REAL X COMPLEX FUNCTION TAN(X) COMPLEX X
Description | The return value is in radians.


TANH

Platform | x64, Win32, .NET
Purpose | To get the Hyperbolic tangent of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION TANH(X) REAL X COMPLEX FUNCTION TANH(X) COMPLEX X
Description | The result has the same type as X. If X is COMPLEX then the imaginary part of the result is in radians. If X is REAL then the return value lies in the range -1 < result < 1.


TINY

Platform | x64, Win32, .NET
Purpose | To get the smallest positive number of the model representing numbers of the same type and kind type parameter as the argument.
Class | Inquiry function
Syntax | REAL FUNCTION TINY(X) REAL X
Description | X is a scalar or an array. The result is a scalar of the same type and kind type.


TRANSFER

Platform

x64, Win32, .NET

Purpose

To change the type and/or kind type of a scalar or array.

Class

Transformational function.

Syntax

FUNCTION TRANSFER (SOURCE, MOLD [, SIZE])
INTEGER SIZE

Description

This function returns a result with a physical representation identical to that of SOURCE but interpreted with the type and type parameters of MOLD.

SOURCE and MOLD may be of any type and may be scalar or array valued. SIZE is a scalar giving the size of the result. The result is of the same type and type parameters as MOLD.

Case (i): If MOLD is a scalar and SIZE is absent, the result is a scalar.

Case (ii): If MOLD is array valued and SIZE is absent, the result is array valued and of rank one. Its size is as small as possible such that its physical representation is not shorter than that of SOURCE.

Case (iii): If SIZE is present, the result is array valued of rank one and size SIZE.

Return value

If the physical representation of the result has the same length as that of SOURCE, the physical representation of the result is that of SOURCE. If the physical representation of the result is longer than that of SOURCE, the physical representation of the leading part is that of SOURCE and the remainder is undefined. If the physical representation of the result is shorter than that of SOURCE, the physical representation of the result is the leading part of SOURCE. If D and E are scalar variables such that the physical representation of D is as long as or longer than that of E, the value of TRANSFER(TRANSFER(E, D), E) shall be the value of E.


TRANSPOSE

Platform | x64, Win32, .NET
Purpose | To transpose an array of rank two.
Class | Transformational function.
Syntax | FUNCTION TRANSPOSE(MATRIX)
Description | MATRIX is an array of any type and has rank two.
Return value | The result is an array of the same type and type parameters as MATRIX and with rank two and shape (n, m) where (m, n) is the shape of MATRIX. Element (i, j) of the result has the value MATRIX(j, i ).


TRIM

Platform | x64, Win32, .NET
Purpose | To remove trailing spaces from a string.
Class | Transformational function.
Syntax | CHARACTER (LEN=*) FUNCTION TRIM(STRING) CHARACTER (LEN=*) STRING
Description | The result has the same kind type as STRING and a length that is the length of STRING less the number of trailing spaces in STRING.


UBOUND

Platform

x64, Win32, .NET

Purpose

To get the upper bound or upper bounds for the indexes of an array.

Class

Inquiry function.

Syntax

INTEGER FUNCTION UBOUND (ARRAY [, DIM [, KIND]])
INTEGER DIM, KIND

Description

ARRAY is an array of any type. If it is a pointer it must be associated. If it is an allocatable array, it must be allocated. If it is an assumed-size array, DIM must be present with a value less than the rank of ARRAY.

DIM is a scalar with a value in the range 1 < DIM < n, where n is the rank of ARRAY.

The result is a scalar integer or a one-dimensional integer array (of default type). It is scalar if DIM is present, otherwise, the result is an array of size n. If KIND is present it provides the INTEGER kind value of the result.

Return value

Case (i): For an array section or for an array expression, other than a whole array or array structure component, UBOUND(ARRAY, DIM) has a value equal to the number of elements in the given dimension; otherwise, it has a value equal to the upper bound for subscript DIM of ARRAY. If dimension DIM has zero size the result is zero.

Case (ii): UBOUND(ARRAY) has a value whose ith component is equal to UBOUND(ARRAY, i), for i = 1, 2, ..., n .

Notes

UBOUND returns a value of default integer type on all platforms. For x64 this will be 32 bits by default.

Example

If A is declared by the statement REAL A(2:3, 7:10) then UBOUND(A) is [3, 10] and UBOUND(A, DIM = 2) is 10.


UNPACK

Platform

x64, Win32, .NET

Purpose

Unpack a one-dimensional array under the control of a mask.

Class

Transformational function.

Syntax

FUNCTION UNPACK(VECTOR, MASK, FIELD)
LOGICAL MASK

Description

VECTOR is a one-dimensional array of any type. Its size is at least t where t is the number of true elements in MASK. MASK is a logical array. FIELD has the same type and type parameters as VECTOR and is conformable with MASK.

The result is an array with the same type and type parameters as VECTOR and the same shape as MASK.

Return value

Elements of VECTOR are unpacked into the result at positions where MASK is true. Unpacking starts along the first dimension (index) of MASK. When an element of MASK is false, FIELD is used if it is a scalar otherwise the corresponding element of FIELD is used.

Example

If VECTOR = [2, 3, 4, 5, 6], MASK = [image] and FIELD = [image], then the result is [image].


VERIFY

Platform

x64, Win32, .NET

Purpose

To get the position of the first character in a string that does not appear in a given set of characters.

Class

Elemental function.

Syntax

INTEGER FUNCTION VERIFY(STRING, SET [, BACK])
CHARACTER (LEN=*) STRING,SET
LOGICAL BACK

Description

SET is of type character with the same kind type parameter as STRING. BACK is a scalar of type logical. The result is a scalar of default integer type.

Return value

Case (i): If BACK is absent or has the value false and if STRING contains at least one character that is not in SET, the value of the result is the position of the first character of STRING that is not in SET.

Case (ii): If BACK is present with the value true and if STRING contains at least one character that is not in SET, the value of the result is the position of the rightmost character of STRING that is not in SET.

Case (iii): The value of the result is zero if each character in STRING is in SET or if STRING has zero length.

Example

VERIFY ('ABBA', 'A') has the value 2.

VERIFY ('ABBA', 'A', BACK = .TRUE.) has the value 3.

VERIFY ('ABBA', 'AB') has the value 0.


Intrinsic functions classified

Standard Fortran 95 intrinsics

Array processes

Bitwise operations

Mathematical functions

Model inquiry functions

Number and type operations

Storage allocation

String operations

Subroutine arguments

Time and date functions


Arrays processes

Array processes

ALL | MAXLOC | SHAPE
ANY | MAXVAL | SIZE
COUNT | MERGE | SPREAD
CSHIFT | MINLOC | SUM
DOT_PRODUCT | MINVAL | TRANSPOSE
EOSHIFT | PACK | UBOUND
LBOUND | PRODUCT | UNPACK
MATMUL | RESHAPE |


Bitwise operations

BIT_SIZE | IBITS | ISHFT
BTEST | IBSET | ISHFTC
IAND | IEOR | MVBITS
IBCLR | IOR | NOT


Command line operations

COMMAND_ARGUMENT_COUNT

GET_COMMAND

GET_COMMAND_ARGUMENT


Mathematical functions

ACOS
ACOSH
ASIN
ASINH
ATAN
ATAN2
ATANH
BESSEL_J0
BESSEL_J1
BESSEL_JN
BESSEL_Y0
BESSEL_Y1
BESSEL_YN
COS
COSH

DIM


Model inquiry

Model inquiry functions

EPSILON | PRECISION | SET_EXPONENT
HUGE | RADIX | SPACING
MAXEXPONENT | RANGE | TINY
MINEXPONENT | RRSPACING |
NEAREST | SCALE |


Number/type operations

ABS | EXPONENT | MODULO
AIMAG | FLOOR | NINT
AINT | FRACTION | RANDOM_NUMBER
ANINT | INT | RANDOM_SEED
CEILING | KIND | REAL
CMPLX | LOGICAL | SELECTED_INT_KIND
CONJG | MAX | SELECTED_REAL_KIND
DBLE | MIN | TRANSFER
DIGITS | MOD |


Storage allocation

ALLOCATED

ASSOCIATED

NULL


String operations

ACHAR | INDEX | LLT
ADJUSTL | LEN_TRIM | REPEAT
ADJUSTR | LEN | SCAN
CHAR | LGE | TRIM
IACHAR | LGT | VERIFY
ICHAR | LLE |


Subroutine arguments

PRESENT


Time and date

Time and date functions

CPU_TIME

DATE_AND_TIME

SYSTEM_CLOCK


Bit-handling routines

The routines in this section provide for bit packed logical arrays. The routines are compiled in-line using the Intel bit manipulation instructions. The result executes about as fast as a reference to a logical array, but the data is stored 8 or 16 or 32 times more efficiently. The bit array may be held in an array (or even a simple variable) of any type (usually INTEGER (KIND= 2)). These routines do not check that their arguments are in range, even in CHECK mode. Bits are numbered from 0. Bit 0 is the least significant bit of the first word of the array.

CLEAR_BIT@ | Clears the N'th bit of an array.
SET_BIT@ | Sets the N'th bit of an array.
TEST_BIT@ | Sets the N'th bit of an array.

See also: Standard Fortran 95 bitwise operations


CLEAR_BIT@

Platform | x64, Win32
Purpose | To clear the N'th bit of an array.
Syntax | SUBROUTINE CLEAR_BIT@(IA,N) INTEGER IA(*),N
Description | Clears the N'th bit of the array IA. IA and N can be any INTEGER type.
Notes | CLEAR_BIT@ is not like the standard intrinsic IBCLR. CLEAR_BIT@ is not elemental and N extends from the lowest bit of IA(1) to highest bit of the last element of IA.


SET_BIT@

Platform | x64, Win32
Purpose | To set the N'th bit of an array.
Syntax | SUBROUTINE SET_BIT@(IA,N) INTEGER IA(*),N
Description | Sets the N'th bit of the array IA. IA and N can be any INTEGER type.
Notes | SET_BIT@ is not like the standard intrinsic IBSET. SET_BIT@ is not elemental and N extends from the lowest bit of IA(1) to highest bit of the last element of IA.


TEST_BIT@

Platform | x64, Win32
Purpose | To test if the N'th bit of an array is set.
Syntax | INTEGER FUNCTION TEST_BIT@(IA,N) INTEGER IA(*),N
Description | TEST_BIT@ may be declared as LOGICAL or INTEGER. IA and N can be any INTEGER type.
Return value | TEST_BIT@ returns 1 or 0 (.TRUE. or .FALSE.) according to whether the N'th bit of IA is set or not.
Notes | TEST_BIT@ is not like the standard intrinsic BTEST. TEST_BIT@ is not elemental and N extends from the lowest bit of IA(1) to highest bit of the last element of IA.


Character-handling routines

The routines in this section provide various facilities for manipulating objects of Fortran CHARACTER type.

ALLOCSTR@ | Allocates dynamic storage and copies a string.
APPEND_STRING@ | Adds a string to the end of a line.
CENTRE@ | Positions a string in the centre of a field.
CHAR_FILL@ | Fills a string with a particular character.
CHSEEK@ | Looks for a given string in an ordered array.
CNUM | Converts an integer to character form.
COMPRESS@ | Compresses a string by using tabs.
GETSTR@ | Gets a string that was stored using ALLOCSTR@.
LCASE@ | Alters a character argument so that all letters become lower case.
NONBLK | Obtains the position of the first character that is not a space.
SAYINT | Returns an integer argument as text.
TRIM@ | Removes leading spaces.
TRIMR@ | Rotates a character string right until there are no trailing spaces.
UPCASE@ | Alters a character argument so that all letters become upper case.

See also: Standard Fortran 95 string operations


ALLOCSTR@

Platform | x64, Win32
Purpose | To allocate dynamic storage and copy a string.
Syntax | INTEGER (KIND=7) FUNCTION ALLOCSTR@(STRING) CHARACTER (LEN=*) STRING
Description | ALLOCSTR@ copies STRING with trailing spaces removed and terminated by a null (i.e. a C-format string), into a dynamic storage space which it allocates. The string can be retrieved using the routine GETSTR@.
Return value | The return value of the function is the address of the storage used.
Example | See GETSTR@ .


APPEND_STRING@

Platform | x64, Win32
Purpose | To add a string to the end of a line.
Syntax | SUBROUTINE APPEND_STRING@(LINE,ADDITION) CHARACTER (LEN=*) LINE,ADDITION
Description | This routine adds the string ADDITION to the end of string LINE after removing trailing spaces from LINE. This can be used to build up complex strings without the need to do many substring calculations.
Example | PROGRAM SONG CHARACTER (LEN=80)::LINE CHARACTER (LEN=20)::SAYINT INTEGER::NO_GREEN_BOTTLES LINE='THERE ARE' READ *,NO_GREEN_BOTTLES IF(NO_GREEN_BOTTLES == 0)THEN CALL APPEND_STRING@(LINE,' NO') ELSE CALL APPEND_STRING@(LINE,' '//SAYINT(NO_GREEN_BOTTLES)) ENDIF CALL APPEND_STRING@(LINE,' STANDING ON A WALL') CALL SOU@(LINE) END PROGRAM SONG


CENTRE@

Platform | x64, Win32
Purpose | To position a string in the centre of a field.
Syntax | CHARACTER (LEN=*) FUNCTION CENTRE@(STRING,IW) CHARACTER (LEN=*) STRING INTEGER (KIND=2) IW
Return value | CENTRE@ returns STRING after padding with blanks on the left so that the non-blank part is centred in a field of IW characters. This is very useful for titles.
Example | CHARACTER (LEN=80) CENTRE@ PRINT *,CENTRE@('FINAL RESULTS',80)


CHAR_FILL@

Platform | x64, Win32
Purpose | To fill a string with a particular character.
Syntax | SUBROUTINE CHAR_FILL@(STRING,FILL) CHARACTER (LEN=*) STRING CHARACTER (LEN=1) FILL
Description | This routine fills the string in STRING with the character FILL up to the full length of STRING.
Notes | The standard intrinsic function REPEAT can be used instead.


CHSEEK@

Platform | x64, Win32
Purpose | To look for a given string in an ordered array.
Syntax | SUBROUTINE CHSEEK@(ITEM,LIST,N,IRES) CHARACTER (LEN=*) ITEM,LIST(N) INTEGER (KIND=3) N,IRES
Description | Seeks the string ITEM in the sorted array LIST using a binary chop. Returns the position in IRES or 0 if not found. Note that the LIST array must be sorted in ascending dictionary order.
Example | PROGRAM FOOD CHARACTER(LEN=10)::FOODS(5) CHARACTER(LEN=12)::MEAL INTEGER::K DATA FOODS/'BUTTER','EGGS','FISH','MUTTON','SUGAR'/ DO READ (*,'(A)') MEAL CALL CHSEEK@(MEAL,FOODS,5,K) SELECT CASE(K) CASE(0) PRINT *,'this is not a food I know about' CASE(1) PRINT *,'spread it' CASE(2) PRINT *,'boil it' CASE(3) PRINT *,'fry it' CASE(4) PRINT *,'stew it' CASE(5) PRINT *,'put it in coffee' END SELECT END DO END PROGRAM FOOD


CNUM

Platform | x64, Win32
Purpose | To convert an integer to character form.
Syntax | CHARACTER (LEN=*) FUNCTION CNUM(J) INTEGER (KIND=3) J
Description | Converts the INTEGER (KIND=3) number J to characters, left-justified with sign if negative.
Notes | This is a Silverfrost library function.


COMPRESS@

Platform | x64, Win32
Purpose | To compress a string by using tabs.
Syntax | SUBROUTINE COMPRESS@(LINE,L) CHARACTER (LEN=*) LINE INTEGER (KIND=2) L
Description | COMPRESS@ replaces multiple blanks where possible in a line with tabs to column positions which are multiples of eight. The new length of the line is returned in L. The tabbing scheme is that used by DOS, so the resulting line can be written to a DOS file.


GETSTR@

Platform | x64, Win32
Purpose | To get a string which was stored using ALLOCSTR@.
Syntax | CHARACTER (LEN=*) FUNCTION GETSTR@(PTR) INTEGER (KIND=7) PTR
Description | This function can be used for strings allocated with the ALLOCSTR@ routine. ALLOCSTR@ and GETSTR@ provide a simple way of storing and retrieving large amounts of character information for which a maximum possible length of each element is known, but where if all trailing spaces were stored the amount of memory required would be excessive. For example, lines of text destined for screen display could be stored in this way (usually a maximum of 80 characters, but often with much trailing space). Another application of this routine is for C string entities passed to Fortran routines.
Return value | GETSTR@ returns the null-terminated string at address PTR as a Fortran CHARACTER entity, truncating or blank-padding as necessary.
Example | INTEGER (KIND=7)::ALLOCSTR@,PTR CHARACTER (LEN=80):: GETSTR@ . . . PTR=ALLOCSTR@(LINE) . . . OUTLIN=GETSTR@(PTR) PRINT '(A)', OUTLIN


LCASE@

Platform | x64, Win32
Purpose | To alter a character argument so that all letters become lower case.
Syntax | SUBROUTINE LCASE@(A) CHARACTER (LEN=*) A
Example | PROGRAM TEST_CASE CHARACTER (LEN=10)::FRED FRED = 'ABC123' CALL LCASE@(FRED) IF(FRED /= 'abc123') PRINT *,'LCASE@ routine has failed' END PROGRAM TEST_CASE


NONBLK

Platform | x64, Win32
Purpose | To obtain the position of the first non-blank character.
Syntax | INTEGER (KIND=2) FUNCTION NONBLK(A) CHARACTER (LEN=*) A
Return value | NONBLK returns the position of the first non-blank character in the character argument A. If the argument is wholly blank, 0 is returned.
Notes | This is a Silverfrost library function. The standard intrinsic function VERIFY can be used instead.


SAYINT

Platform | x64, Win32
Purpose | To return an integer argument as text.
Syntax | CHARACTER (LEN=*) FUNCTION SAYINT(I) INTEGER (KIND=3) I
Description | As an example, the value I=-270 would return the character value 'MINUS TWO HUNDRED AND SEVENTY'.
Notes | This is a Silverfrost library function.


TRIM@

Platform | x64, Win32
Purpose | To remove leading blanks.
Syntax | SUBROUTINE TRIM@(X) CHARACTER (LEN=*) X
Description | TRIM@ is used to remove leading blank characters from the character argument X.
Notes | The standard intrinsic function ADJUSTL can be used instead.


TRIMR@

Platform | x64, Win32
Purpose | To rotate a character string right until there are no trailing blanks.
Syntax | SUBROUTINE TRIMR@(X) CHARACTER (LEN=*) X
Notes | If the string is blank, it is left unchanged. The standard intrinsic function ADJUSTR can be used instead.
Example | PROGRAM READ_NAMES ! Read names from a file and print them right justified. CHARACTER (LEN=10)::NAME OPEN(FILE='NAMES',UNIT=10) DO READ (10,'(A)',END=999) NAME CALL TRIMR@(NAME) PRINT *,NAME END DO 999 END PROGRAM READ_NAMES


UPCASE@

Platform | x64, Win32
Purpose | To alter a character argument so that all letters become upper case.
Syntax | SUBROUTINE UPCASE@(A) CHARACTER (LEN=*) A
Example | PROGRAM UCASE CHARACTER (LEN=10)::FRED FRED = 'ABcd' CALL UPCASE@(FRED) IF(FRED /= 'ABCD') PRINT *,'UPCASE@ routine has failed' END


Command line parsing routines

The routines in this section allow the programmer to access the program name and command line arguments with which the program was invoked. If the program was run with /LGO, the command line arguments which are returned are those which follow the /PARAMS option (if one appears on the command line).

CMNAM | Reads a token from the command line.
CMNAM@ | Reads a token from the command line.
CMNAMR | Resets the command line.
CMNARGS@ | Gets the number of command line arguments.
CMNUM@ | Gets the next command line argument as an integer.
CMPROGNM@ | Gets the program name.
COMMAND_ARGUMENT_COUNT | Gets the number of arguments on the command line.
COMMAND_LINE | Reads the whole command line.
GET_COMMAND | Reads the whole command line.
GET_COMMAND_ARGUMENT | Gets the command line argument at a given position.
GET_PROGRAM_NAME@ | Returns the name of the current program.


CMNAM

Platform | x64, Win32
Purpose | To read a token from the command line.
Syntax | CHARACTER (LEN=*) FUNCTION CMNAM()
Description | This function is useful for programs which are to be used as commands with arguments on the command line. Arguments (or "tokens") are separated by spaces (not slashes).
Return value | CMNAM reads a token and returns it as the character result. Spaces are returned when tokens are exhausted.
Notes | This is a Silverfrost library function.
Example | !This program operates like the MS-DOS COPY command. !Eg. store the program in COPY.FOR and type: !FTN95 COPY /LGO /PARAMS <FIRST file> <SECOND file> PROGRAM COPY_FILE CHARACTER (LEN=20)::CMNAM,FILE2 CHARACTER (LEN=128)::DATA INTEGER (KIND=2)::KEY LOGICAL::L OPEN(UNIT=3,FILE=CMNAM(),STATUS='READONLY',ERR=200) FILE2=CMNAM() INQUIRE(FILE=FILE2,EXIST=L) IF (L) THEN PRINT *,'File to be written already exists & & OK to overwrite? (y/n)' CALL GET_KEY@(KEY) IF((KEY /= 89).AND.(KEY /= 121)) STOP PRINT*,'y' ENDIF OPEN(UNIT=4,FILE=FILE2,STATUS='MODIFY',ERR=210) !Copy file one line at a time DO READ(3,'(A)',END=220) DATA WRITE(4,'(A)') DATA END DO 200 PRINT*,'File to be read does not exist' STOP 210 PRINT*,'File to be written can not be created' 220 END PROGRAM COPY_FILE


CMNAM@

Platform | x64, Win32
Purpose | To read a token from the command line.
Syntax | CHARACTER (LEN=*) FUNCTION CMNAM@()
Description | This routine performs like CMNAM except that a token terminates at a slash. Slashes are converted into minus (-) characters and start the next token. For example, /ALPHA/BETA would generate two tokens: "-ALPHA" and "-BETA".


CMNAMR

Platform | x64, Win32
Purpose | To reset the command line.
Syntax> | SUBROUTINE CMNAMR
Description | CMNAMR resets the command line so that it can be read again with CMNAM etc.. CMNAMR has no arguments.
Notes | This is a Silverfrost library function.


CMNARGS@

Platform | x64, Win32
Purpose | To get the number of command line arguments.
Syntax | INTEGER (KIND=2) FUNCTION CMNARGS@()
Return value | CMNARGS@ returns the number of arguments on the command line (excluding the invocation name of the program).
Note | When calling CMNARGS@ you must declare it as INTEGER(KIND=2).


CMNUM@

Platform | x64, Win32
Purpose | To get the next command line argument as an integer.
Syntax | SUBROUTINE CMNUM@(N,*) INTEGER (KIND=3) N
Description | This routine interprets the next command line argument as an integer if possible. The alternate return is taken if the next token is not a valid integer, and the next call of CMNAM@ will return the token which caused the error.


CMPROGNM@

Platform | x64, Win32
Purpose | To get the program name.
Syntax | CHARACTER (LEN=*) FUNCTION CMPROGNM@()
Return value | CMPROGNM@ returns the name by which the program was invoked from the command line.


COMMAND_LINE

Platform | x64, Win32, .NET
Purpose | To read the whole command line.
Syntax | SUBROUTINE COMMAND_LINE(C) CHARACTER (LEN=*) C
Description | This routine returns the whole command line in C (excluding the program name).
Notes | This is a Silverfrost library function. The standard Fortran intrinsic GET_COMMAND provides a similar standard conforming alternative.


GET_PROGRAM_NAME@

Platform | x64, Win32
Purpose | To return the name of the current program.
Syntax | SUBROUTINE GET_PROGRAM_NAME@(NAME) CHARACTER (LEN=*) NAME


Console input and output

COU@ | Outputs text to the screen with a new line.
COUA@ | Outputs text to the screen without a new line.
ERRCOU@ | Outputs text to the standard error device.
ERRCOUA@ | Outputs text to the standard error device.
ERRNEWLINE@ | Writes an newline to the standard error device.
ERRSOU@ | Outputs text to the standard error device.
ERRSOUA@ | Outputs text to the standard error device.
GET_KEY@ | Gets the next keycode.
NEWLINE@ | Writes a carriage return/linefeed to the screen (standard output).
PRINT_HEX1@ | Prints a 1 byte hexadecimal number (2 digits) without a new line.
PRINT_HEX2@ | Prints a 2 byte hexadecimal number (4 digits) without a new line.
PRINT_HEX4@ | Prints a 4 byte hexadecimal number (8 digits) without a new line.
PRINT_I1@ | Prints an INTEGER(1) decimal number without a new line.
PRINT_I2@ | Prints an INTEGER(2) decimal number without a new line.
PRINT_I4@ | Prints an INTEGER(3) decimal number without a new line.
SOU@ | Outputs text with a new line, omitting any trailing blanks.
SOUA@ | Outputs text without a new line, omitting any trailing blanks.


COU@

Platform | x64, Win32
Purpose | To output text to the screen with a new line.
Syntax | SUBROUTINE COU@(A) CHARACTER (LEN=*) A
See also | COUA@, SOU@, SOUA@.
Example | CALL COU@('message to screen')


COUA@

Platform | x64, Win32
Purpose | To output text to the screen without a new line.
Syntax | SUBROUTINE COUA@(A) CHARACTER (LEN=*) A
Description | COUA@ takes the message length (which must be less than 1024 characters) from its character argument A. This is useful as a prompt or as part of a sequence of calls which build up a line on the screen.
See also | COU@, SOU@, SOUA@ .


ERRCOU@

Platform | x64, Win32
Purpose | To output text to the standard error device.
Syntax | SUBROUTINE ERRCOU@(STRING) CHARACTER (LEN=*) STRING
Description | ERRCOU@ outputs text followed by a new line taking the message length from its character argument STRING.


ERRCOUA@

Platform | x64, Win32
Purpose | To output text to the standard error device.
Syntax | SUBROUTINE ERRCOUA@(STRING) CHARACTER (LEN=*) STRING
Description | ERRCOUA@ outputs text (without a new line) taking the message length from its character argument STRING. This is useful as a prompt or as part of a sequence of calls which build up a line on the screen.


ERRNEWLINE@

Platform | x64, Win32
Purpose | To write a newline to the standard error device.
Syntax | SUBROUTINE ERRNEWLINE@


ERRSOU@

Platform | x64, Win32
Purpose | To output text to the standard error device.
Syntax | SUBROUTINE ERRSOU@(STRING) CHARACTER (LEN=*) STRING
Description | ERRSOU@ outputs text from the character argument STRING to standard error omitting any trailing blanks, and outputting a new line.


ERRSOUA@

Platform | x64, Win32
Purpose | To output text to the standard error device.
Syntax | SUBROUTINE ERRSOUA@(STRING) CHARACTER (LEN=*) STRING
Description | ERRSOUA@ outputs text from the character argument STRING to standard error omitting any trailing blanks. It does not output a new line.


GET_KEY@

Platform | x64, Win32
Purpose | To get the next keycode.
Syntax | SUBROUTINE GET_KEY@(K) INTEGER (KIND=2) K
Description | This subroutine gets a keycode from the keyboard. If the buffer is not empty then a value is read and removed from the buffer. If the buffer is empty then the function waits for a keyboard input. The value of K assigned such that if the high byte is equal to 0 then the low byte is the ASCII value for the key pressed. If the high byte is equal to 1 then the low byte is the scan code for a Function key or an ALT key combination (the scan code is then K-256).
Example | CALL GET_KEY@(K) IF(K == Z'13B')THEN PRINT *,'F1 Key pressed' ELSEIF(K == Z'13C')THEN : : ENDIF


NEWLINE@

Platform | x64, Win32
Purpose | To write a carriage return/linefeed to the screen (standard output).
Syntax | SUBROUTINE NEWLINE@


PRINT_BYTES@

Platform | x64, Win32
Purpose | To write a sequence of hexadecimal values.
Syntax | SUBROUTINE PRINT_BYTES@(IARR,N) INTEGER (KIND=2) IARR(*),N
Description | PRINT_BYTES@ writes N bytes of datum IARR in hexadecimal to standard output, separating each byte value by a space, with no terminating new line.


PRINT_BYTES_R@

Platform | x64, Win32
Purpose | To write a hexadecimal sequence in reverse order.
Syntax | SUBROUTINE PRINT_BYTES_R@(IARR,N) INTEGER (KIND=2) IARR(*),N
Description | This routine is similar to PRINT_BYTES@, but the bytes are written in reverse order.


PRINT_I1@

Platform | x64, Win32
Purpose | To print an INTEGER (KIND=1) decimal number without a new line.
Syntax | SUBROUTINE PRINT_I1@(I) INTEGER (KIND=1) I


PRINT_I2@

Platform | x64, Win32
Purpose | To print an INTEGER (KIND=2) decimal number without a new line.
Syntax | SUBROUTINE PRINT_I2@(I) INTEGER (KIND=2) I


PRINT_I4@

Platform | x64, Win32
Purpose | To print an INTEGER (KIND=3) decimal number without a new line.
Syntax | SUBROUTINE PRINT_I4@(L) INTEGER (KIND=3) L


PRINT_HEX1@

Platform | x64, Win32
Purpose | To print a 1 byte hexadecimal number (2 digits) without a new line.
Syntax | SUBROUTINE PRINT_HEX1@(L) INTEGER (KIND=1) L


PRINT_HEX2@

Platform | x64, Win32
Purpose | To print a 2 byte hexadecimal number (4 digits) without a new line.
Syntax | SUBROUTINE PRINT_HEX2@(L) INTEGER (KIND=2) L


PRINT_HEX4@

Platform | x64, Win32
Purpose | To print a 4 byte hexadecimal number (8 digits) without a new line.
Syntax | SUBROUTINE PRINT_HEX4@(L) INTEGER (KIND=3) L


PRINT_R4@

Platform | x64, Win32
Purpose | To print a REAL (KIND=1) value as a number without a new line.
Syntax | SUBROUTINE PRINT_R4@(R) REAL (KIND=1) R


PRINT_R8@

Platform | x64, Win32
Purpose | To print a REAL (KIND=2) value as a number without a new line.
Syntax | SUBROUTINE PRINT_R8@(R) REAL (KIND=2) R


SOU@

Platform | x64, Win32
Purpose | To output text with a new line, omitting any trailing blanks.
Syntax | SUBROUTINE SOU@(A) CHARACTER (LEN=*) A
Description | SOU@ writes to the screen from the character argument A. It is identical to COU@ except that the cursor will not scan over any trailing blanks.
See also | COU@, COUA@, SOUA@ .


SOUA@

Platform | x64, Win32
Purpose | To output text without a new line, omitting any trailing blanks.
Syntax | SUBROUTINE SOUA@(A) CHARACTER (LEN=*) A
Description | SOUA@ writes to the screen from the character argument A omitting any trailing blanks. It is like SOU@ but does not output a new line.
See also | COU@, COUA@, SOU@ .


Data sorting routines

The routines in this section provide facilities for sorting arrays of various types. The routines described use a quicksort algorithm, and perform well for data that is originally randomly ordered. Note, however, that these routines are not stable in the strict sense. That is, equal keys do not necessarily maintain their order relative to each other.

CHSORT@ | Sorts an array of characters.
DSORT@ | Sorts a REAL(KIND=2) array.
ISORT@ | Sorts an integer array.
RSORT@ | Sorts a REAL(KIND=1) array.


CHSORT@

Platform

x64, Win32

Purpose

To sort an array of characters.

Syntax

SUBROUTINE CHSORT@(A,CHS,N)
CHARACTER (LEN=*) CHS(N)
INTEGER (KIND=3) A(N),N

Description

CHSORT@ sorts the character array CHS by setting pointers from 1 to N in the array A. After sorting, A(1) contains a pointer to the "first" element of CHS, A(2) to the "second", and so on.

Example

PROGRAM SORT
CHARACTER (LEN=20)::PUPILS(100)
INTEGER (KIND=3)::I,IP(100)
DO I=1,100
READ(5,'(A)') PUPILS(I)
END DO
CALL CHSORT@(IP,PUPILS,100)
PRINT *,'Sorted list of pupils:-'
DO I=1,100
PRINT *,PUPILS(IP(I))
END DO
END PROGRAM SORT


DSORT@

Platform

x64, Win32

Purpose

To sort a REAL (KIND=2) array.

Syntax

SUBROUTINE DSORT@(A,D,N)
REAL (KIND=2) D(N)
INTEGER (KIND=3) A(N),N

Description

DSORT@ sorts the REAL array D by setting pointers from 1 to N in the array A in the same manner as CHSORT@ .


ISORT@

Platform

x64, Win32

Purpose

To sort an integer array.

Syntax

SUBROUTINE ISORT@(A,IA,N)
INTEGER (KIND=3) IA(N)
INTEGER (KIND=3) A(N),N

Description

ISORT@ sorts the integer array IA by setting pointers from 1 to N in the array A in the same manner as CHSORT@ .


RSORT@

Platform

x64, Win32

Purpose

To sort a REAL (KIND=1) array.

Syntax

SUBROUTINE RSORT@(A,R,N)
REAL (KIND=1) R(N)
INTEGER (KIND=3) A(N),N

Description

RSORT@ sorts the REAL array R by setting pointers from 1 to N in the array A in the same manner as CHSORT@ .


Error handling routines

Error and exception handling routines

The routines described in this section fall into two main categories:

  • Those that allow interpretation of error codes returned by other routines. Routines which fall into this category include ERR77 and DOS_ERROR_MESSAGE@. Where a routine returns an error code it is of course always good practice to check it for an acceptable value (usually zero).

  • Those that allow control over the action taken in the event of a software-generated exception. Exception handling routines in this section are currently for Win32 only. For information on handling .NET exceptions see Handling exceptions.

More...

ACCESS_DETAILS@ | Gets details of the access violation.
CLEAR_FLT_UNDERFLOW@ | Clears a floating point underflow exception.
DOS_ERROR_MESSAGE@ | Gets a DOS error message.
DOSERR@ | Prints a DOS error message when an error occurs.
ERR77 | Prints a DOS error message and terminate a program when an error occurs.
ERROR@ | Prints a user defined error message and terminate a program.
EXCEPTION_ADDRESS@ | Finds the address of the instruction that generated the exception.
FORTRAN_ERROR_MESSAGE@ | Gets a Fortran error message.
GET_VIRTUAL_COMMON_INFO@ | Gets virtual common block details.
JUMP@ | Executes a non-local jump.
LABEL@ | Sets a label for a non-local jump.
PERMIT_UNDERFLOW@ | Switches off floating point underflow checking.
PRERR@ | Prints the error message associated with a given error code.
QUIT_CLEANUP@ | Prints a message and exit from a program with Control-break.
RESTORE_DEFAULT_HANDLER@ | Removes a user defined exception handler.
RUNERR@ | Prints the run-time error corresponding to a given IOSTAT value.
SET_DISK_ERRORS@ | Controls the critical event handler.
SET_TRAP@ | Traps a given event.
TRAP_EXCEPTION@ | Installs a user defined exception handler.
UNDERFLOW_COUNT@ | Gets the number of floating point underflows.


ACCESS_DETAILS@

Platform | Win32
Purpose | Get the details of the access violation.
Syntax | SUBROUTINE ACCESS_DETAILS@(ADDRESS, MODE, IC) INTEGER (KIND=3) ADDRESS LOGICAL (KIND=3) MODE INTEGER (KIND=2) IC
Description | This subroutine is used after an access violation has occurred to ascertain the address that was being accessed when the exception occurred. If this function is successful, ADDRESS contains the address that was being accessed. MODE is set to TRUE if the instruction was attempting to read from the address, FALSE if the instruction was attempting to write to the address. IC is set to 0 on success, 1 on failure.


CLEAR_FLT_UNDERFLOW@

Platform | Win32
Purpose | Clear a floating point underflow exception (Win32 only).
Syntax | SUBROUTINE CLEAR_FLT_UNDERFLOW@
Description | Decode the instruction that caused the floating point underflow and clear the floating point underflow from the machine state.


DOS_ERROR_MESSAGE@

Platform | Win32
Purpose | To get a DOS error message.
Syntax | SUBROUTINE DOS_ERROR_MESSAGE@(ERROR_CODE,MESSAGE) INTEGER (KIND=2) ERROR_CODE CHARACTER (LEN=*) MESSAGE
Description | Returns the DOS error string corresponding to the error number ERROR_CODE. The error numbers are augmented in the same way as for DOSERR@.
Example | CHARACTER (LEN=80)::MESSAGE CALL OPENR@('DATA',IH,ERROR_CODE) CALL DOS_ERROR_MESSAGE@(ERROR_CODE,MESSAGE) PRINT *,MESSAGE


DOSERR@

Platform | Win32
Purpose | To print a DOS error message and exit when an error occurs.
Syntax | SUBROUTINE DOSERR@(ERROR_CODE) INTEGER (KIND=2) ERROR_CODE
Description | This routine does nothing if ERROR_CODE is zero, otherwise it prints the DOS error message corresponding to ERROR_CODE and exits from the program. It is typically used after system calls that use DOS and are normally expected to succeed.
Example | CALL OPENR@('DATA',IH,ERROR_CODE) CALL DOSERR@(ERROR_CODE)


ERR77

Platform | Win32
Purpose | To print a DOS error message and terminate a program when an error occurs.
Syntax | SUBROUTINE ERR77(MESSAGE,ERROR_CODE) CHARACTER (LEN=*) MESSAGE INTEGER (KIND=2) ERROR_CODE
Description | This routine has a null effect if ERROR_CODE is zero. Otherwise the string MESSAGE is printed, followed by the text of the DOS error indicated by ERROR_CODE. The program then terminates abnormally. This routine is normally used to test for DOS error following another system call, as in the example.
Notes | This is a Silverfrost library routine.


ERROR@

Platform | Win32
Purpose | To print a user defined error message and terminate a program.
Syntax | SUBROUTINE ERROR@(ERROR_MESSAGE) CHARACTER (LEN=*) ERROR_MESSAGE
Description | This routine generates a user defined error condition. If the program is running under the debugger, then the message will be displayed in the error window. Otherwise, the error is printed out and the EXIT routine is called with a code of 1 (exit to DOS).
Example | CALL ERROR@('Too many data points for PLOT program')


EXCEPTION_ADDRESS@

Platform | Win32
Purpose | To find the address of the instruction which generated the exception (Win32 only).
Syntax | INTEGER (KIND=3) EXCEPTION_ADDRESS@
Description | EXCEPTION_ADDRESS@ returns the address of the instruction that generated the exception event.
Return value | Address of the instruction that generated the exception.


EXPORTCALLSTACK@

Platform

x64, Win32

Purpose

To export the current call stack to a file.

Syntax

SUBROUTINE EXPORTCALLSTACK@(FILENAME)
CHARACTER(LEN=*) FILENAME

Description

When an exception is raised, FTN95 responds with a dialog box showing the current call stack. A similar call stack is presented when running the debuggers. FTN95 does not have a facility to generate this call stack under program control but EXPORTCALLSTACK@ provides an alternative list that is similar to the corresponding call stack.

EXPORTCALLSTACK@ has no effect unless the option /RUNTRACE is used on the FTN95 command line (for every file in the project) and users should be aware that this option can significantly increase the size of the resulting executable and may impact the speed of execution.

EXPORTCALLSTACK@ also requires a prior call to CREATECALLSTACK@ and this routine takes the form:

SUBROUTINE CREATECALLSTACK@(MAXSIZE)
INTEGER MAXSIZE

where MAXSIZE is input as the maximum number of levels in the call stack that will be automatically generated as the program is executed. CREATECALLSTACK@ must be called in the main program before all other executable statements.

EXPORTCALLSTACK@ is called at the start of the subroutine where the call stack is needed and FILENAME is the name of the file for the results (this file must have write access). EXPORTCALLSTACK@ can be called from more than one subroutine but the file name on the first call is also used for subsequent calls so, for simplicity, the argument should not vary.

EXPORTCALLSTACK@ does not terminate the program execution. The processing that continuously generates the call stack can be terminated by the calling CREATECALLSTACK@(0) and, for some diagnostic purposes, this call could be made after a call to EXPORTCALLSTACK@.


FORTRAN_ERROR_MESSAGE@

Platform | Win32
Purpose | To get a Fortran error message.
Syntax | SUBROUTINE FORTRAN_ERROR_MESSAGE@(ERROR_CODE,MESSAGE) INTEGER (KIND=2) ERROR_CODE CHARACTER (LEN=*) MESSAGE
Description | Returns the error message corresponding to the Fortran run time error number ERROR_CODE. Some error messages are rather vague (e.g. Inconsistent call to routine) but when these errors occur the system produces a more informative error message.
Example | CHARACTER (LEN=80)::MESSAGE INTEGER (KIND=2)::ERROR_CODE< BR>OPEN(FILE='FRED',UNIT=6,IOSTAT=ERROR_CODE) CALL FORTRAN_ERROR_MESSAGE@(ERROR_CODE,MESSAGE) PRINT *,MESSAGE


GET_VIRTUAL_COMMON_INFO@

Platform

Win32

Purpose

Get virtual common block details.

Syntax

SUBROUTINE GET_VIRTUAL_COMMON_INFO@(NAME,BASE, &
& SIZE,COMMIT,AMOUT_COMMITTED)
CHARACTER (LEN=*) NAME
INTEGER (KIND=3) BASE,SIZE,COMMIT,AMOUT_COMMITTED

Description

When a program is linked using the virtual common (VC) option, all uninitialised data (i.e. the BSS section) is removed from the executable and placed into virtual paged memory with default base address 0x20000000. Pages of memory are committed when necessary. GET_VIRTUAL_COMMON_INFO@ allows a user to determine how much memory is used and also provides other information.

The subroutine returns BASE,SIZE,COMMIT(amount of memory the system automatically commits) andAMOUNT_COMITTED (amount of memory already committed) for the allocated virtual common block.

Example

PROGRAM TVC1
INTEGER (KIND=3)::BASE,SIZE,COMMIT,AMT_COMMIT
CALL GET_VIRTUAL_COMMON_INFO@('TVC1.EXE',BASE, SIZE,COMMIT,AMT_COMMIT)
PRINT*,' BASE = ', BASE
PRINT*,' SIZE = ', SIZE
PRINT*,' COMMIT = ', COMMIT
PRINT*,' AMT_COMMIT = ', AMT_COMMIT
END PROGRAM TVC1


JUMP@

Platform | Win32
Purpose | To execute a non-local jump (Win32 only).
Syntax | SUBROUTINE JUMP@(LABEL) COMPLEX (KIND=2) LABEL
Description | This routine is described here since its most frequent use is in conjuction with SET_TRAP@. It takes a label generated by LABEL@ and jumps to the label. The label must exist in a still active routine, but this can be any distance down the call stack.
Example | Consider a program designed to process several sets of data and to carry on even after errors had been diagnosed in earlier data sets:
 | PROGRAM INPUT COMPLEX (KIND=2) RECOVER CALL LABEL@(RECOVER,*10) 10 DO CALL READ_DATA CALL PROCESS END DO CONTAINS SUBROUTINE ERROR(MESSAGE) CHARACTER(*) MESSAGE CALL COU@(MESSAGE) CALL JUMP@(RECOVER) END SUBROUTINE ERROR END PROGRAM INPUT
 | Subroutine ERROR could be called from anywhere inside PROCESS (even many layers down inside subroutine calls) to return to label 10 ready to process the next data set. The use of JUMP@ obviates the need to provide an explicit error exit path back to the main program. It is the user's responsibility to ensure that the LABEL is still accessible when JUMP@ is called, i.e. that the routine which is called LABEL@ has not yet exited.


LABEL@

Platform | Win32
Purpose | To set a label for a non-local jump (Win32 only).
Syntax | SUBROUTINE LABEL@(LABEL,*) COMPLEX (KIND=2) LABEL
Description | This routine makes a label for use with JUMP@.
Example | See JUMP@ .


PERMIT_UNDERFLOW@

Platform | Win32
Purpose | To switch off floating point underflow checking (Win32 only).
Syntax | SUBROUTINE PERMIT_UNDERFLOW@(PERMISSION) LOGICAL (KIND=2) PERMISSION
Description | If PERMISSION is .TRUE. then this routine forces subsequent floating point underflows to return zero. If PERMISSION is .FALSE. then subsequent underflows will force a program fault.


PRERR@

Platform | Win32
Purpose | To print the error message associated with a given error code.
Syntax | SUBROUTINE PRERR@(ERROR_CODE,STRING) INTEGER (KIND=2) ERROR_CODE CHARACTER (LEN=*) STRING
Description | This routine does nothing if ERROR_CODE is zero, otherwise it prints the user-supplied string STRING followed by the system error message corresponding to ERROR_CODE. The routine returns normally and program execution continues. ERROR_CODE will normally be a value returned by an earlier call to a routine that could generate a system error condition.


QUIT_CLEANUP@

Platform | Win32
Purpose | To print a message and exit from a program with Control-break (Win32 only).
Syntax | SUBROUTINE QUIT_CLEANUP@(MESSAGE) CHARACTER (LEN=*) MESSAGE
Description | This routine uses SET_TRAP@ to trap Control-break. The system responds to Control-break by printing the given message and returning to DOS. This routine provides a simple way to enable programs to be terminated early in a graceful fashion.
Example | CALL QUIT_CLEANUP@('Quit pressed - program abandoned')


RESTORE_DEFAULT_HANDLER@

Platform | Win32
Purpose | Remove a user defined exception handler (Win32 only).
Syntax | SUBROUTINE RESTORE_DEFAULT_HANDLER@(EXCEPTION) INTEGER (KIND=3) EXCEPTION
Description | Remove the default exception handler for the exception event given by EXCEPTION and re-install the default handler.


RUNERR@

Platform | x64, Win32
Purpose | Terminates the executable by raising an exception.
Syntax | SUBROUTINE RUNERR@(IEXCEPT) INTEGER (KIND=2) IEXCEPT
Description | IEXCEPT is a system value for the resulting message.


SET_DISK_ERRORS@

Platform | Win32
Purpose | To control the critical event handler.
Syntax | SUBROUTINE SET_DISK_ERRORS@(L) LOGICAL (KIND=2) L
Description | If L is .TRUE. critical errors will return an error code and not put up the "Abort, Retry, Ignore" message. If L is .FALSE. the message will appear.


SET_TRAP@

Platform

Win32

Purpose

Install a user defined exception handler for Ctrl+C (Win32 only).

Syntax

INTEGER(KIND=3) SET_TRAP@(ROUTINE, EXCEPTION)
INTEGER(KIND=3) EXCEPTION, ROUTINE
EXTERNAL ROUTINE

Description

EXCEPTION is set to zero to handle CTRL+C. The function ROUTINE is installed as the handler for this event. The location of the previous handler is returned. If the application is to terminate then ROUTINE should return a zero value. Otherwise a value of 1 is returned.

Example

PROGRAM TrapException
INTEGER SET_TRAP@, OldHandler
EXTERNAL SET_TRAP@, CtrlcHandler
OldHandler=SET_TRAP@(CtrlcHandler, 0)
DO WHILE(.TRUE.)
PRINT *, 'Continuing. . .'
ENDWHILE
PRINT *, 'Normal termination'
END
INTEGER FUNCTION CtrlcHandler()
STOP 'Ctrl+C trapped'
CtrlcHandler=0
END


TRAP_EXCEPTION@

Platform | Win32
Purpose | Install a user defined exception handler (Win32 only).
Syntax | INTEGER (KIND=3) FUNCTION TRAP_EXCEPTION@(EXCEPTION, ROUTINE) INTEGER (KIND=3) EXCEPTION, ROUTINE EXTERNAL ROUTINE
Description | The subroutine ROUTINE is installed as the default method of handling the event specified by EXCEPTION.
Return value | If EXCEPTION is a valid exception event, the location of the previous handler is returned. 0 is returned if EXCEPTION is an invalid exception code.

The values of EXCEPTION are as follows:

Event | Parameter name | Value
Access violation | ACCESS_VIOLATION | 0
Invalid floating point operation | FLT_INVALID_OPERATION | 1
Denormal floating point operand | FLT_DENORMAL | 2
Floating point divide by zero | FLT_DIV_ZERO | 3
Floating point overflow | FLT_OVERFLOW | 4
Floating point underflow | FLT_UNDERFLOW | 5
Inexact floating point result | FLT_INEXACT_RESULT | 6
Floating point stack overflow | FLT_STACK_FAULT | 7
Breakpoint | BREAK_POINT | 9
Single step | SINGLE_STEP | 10
Execution of a privileged instruction | PRIV_INSTRUCTION | 11
All exceptions | ALL_EXCEPTIONS | 12
All floating point exceptions | ALL_FLOATING_POINT | 13
Integer divide by zero | INT_DIVIDEBY_ZERO | 14
Down to page reserve | DOWNTO_PAGE_RESERVE | 16

Values returned by ROUTINE:

Instruction to event handler | Parameter name | Value
Exception has been handled so continue execution. | CONTINUE_EXECUTION | 0
The problem has not been fixed so the system should try to handle this event. | EXCEPTION_UNHANDLED | 1
Unable to continue after handling this exception so exit from the program. | NONCONTINUABLE_EXCEPTION | -2

Notes

Unless assembler coding is used, ROUTINE should normally return the value NONCONTINUABLE_EXCEPTION. One exception to this rule is floating point underflow for which one can return EXCEPTION_UNHANDLED and then continue.

Integer overflow does not generate an exception unless in /DEBUG mode. In /DEBUG mode the exception cannot be trapped.

The above parameter names and values are listed in the file exceptn.ins.

Example

PROGRAM TrapException
INCLUDE <EXCEPTN.INS>
INTEGER TRAP_EXCEPTION@, DivZeroHandler, OldHandler
EXTERNAL TRAP_EXCEPTION@, DivZeroHandler
REAL r, zero
OldHandler=TRAP_EXCEPTION@(FLT_DIV_ZERO, DivZeroHandler)
zero=0.0
r=1.234/zero
PRINT *, 'Normal termination'
END
INTEGER FUNCTION DivZeroHandler()
INCLUDE <EXCEPTN.INS>
PRINT *, 'Float divide by zero trapped'
DivZeroHandler= NONCONTINUABLE_EXCEPTION
END

This example illustrates a case where it is not possible to continue executing the program after the event has been trapped. The best that one can do is to save program data and exit cleanly.


UNDERFLOW_COUNT@

Platform | Win32
Purpose | To get the number of floating point underflows (Win32 only).
Syntax | SUBROUTINE UNDERFLOW_COUNT@(COUNT) INTEGER (KIND=3) COUNT
Description | COUNT is returned as the number of underflows that have occurred since the start of the program.


File-manipulation routines

FTN95 offers a wide variety of file manipulation routines. Routines which take operating system file handles as arguments must only be used with file handles obtained with one of the file opening routines detailed in this section. The reading and writing routines use a buffer to improve the performance. These buffers are cleared when a file is closed or when a program terminates and returns to the operating system. As a result of this, a file which has been open for writing may give an error (e.g. full disk) as it is closed with CLOSEF@. In all cases where a routine returns an error code, this may be interpreted by calling a routine such as DOSERR@.

ATTACH@ | Sets the current directory.
CLOSEF@ | Closes a file.
CLOSEFD@ | Closes and delete a file.
CURDIR@ | Gets the current directory.
CURRENT_DIR@ | Obsolete routine. Use CURDIR@.
EMPTY@ | Clears a file for writing.
ERASE@ | Deletes a file.
FEXISTS@ | Searches for a file with a given path name or wildcard.
FILE_EXISTS@ | Obsolete routine. Use FEXIST@ instead.
FILE_SIZE@ | Gets the size of a file in bytes.
FILE_TRUNCATE@ | Truncates an open file at its current position.
FILEINFO@ | Gets information about a specified file.
FILES@ | Obtains directory information.
FPOS@ | Repositions a file.
FPOS_EOF@ | Moves the file pointer to end-of-file.
GET_FILES@ | Gets a list of files in the current working directory.
GET_PATH@ | Gets the fully qualified pathname.
MKDIR@ | Creates a new DOS directory.
OPENR@ | Opens a file for reading.
OPENRW@ | Opens a file for reading or writing.
OPENW@ | Opens a file for writing.
READF@ | Reads binary data from a file.
READFA@ | Reads ASCII text from a file.
RENAME@ | Renames a file.
RFPOS@ | Gets the position of a file.
SET_FILE_ATTRIBUTE@ | Sets a file attribute.
SET_SUFFIX@ | Changes the extension of a given file name.
SET_SUFFIX1@ | Adds an extension to a given file name.
TEMP_FILE@ | Provides a unique name for a file.
TEMP_PATH@ | Gets a suitable name for a temporary file.
WILDCHECK@ | Checks for the matching of a file name with a wild card.
WRITEF@ | Writes binary data to a file.
WRITEFA@ | Writes a line of data to an ASCII file.


ATTACH@

Platform | x64, Win32
Purpose | To set the current directory.
Syntax | SUBROUTINE ATTACH@(PATH,ERROR_CODE) CHARACTER (LEN=*) PATH INTEGER (KIND=2) ERROR_CODE
Description | PATH should be the path name of a directory (e.g. C:\PROJECT). ATTACH@ makes this the current directory, switching disks if necessary. ERROR_CODE is returned with a non-zero system error code if it fails.
Example | CHARACTER (LEN=50)::PATH CALL COUA@('Where do you want to be? ') READ(*,'(A)')PATH CALL ATTACH@(PATH,ERROR_CODE) CALL DOSERR@(ERROR_CODE) CALL COU@('OK - that is where you are! '). . .


CLOSEF@

Platform | x64, Win32
Purpose | To close a file.
Syntax | SUBROUTINE CLOSEF@(SID, ERROR_CODE) INTEGER (KIND=2) SID, ERROR_CODE
Description | CLOSEF@ closes a file opened by OPENR@, OPENW@ or OPENRW@ . ERROR_CODE is returned with a non-zero system error code if it fails.
See also | OPENR@, OPENRW@, OPENW@, READF@, READFA@, WRITEF@, WRITEFA@, FPOS@, FPOS_EOF@


CLOSEFD@

Platform | x64, Win32
Purpose | To close and delete a file.
Syntax | SUBROUTINE CLOSEFD@(SID,ERROR_CODE) INTEGER (KIND=2) SID,ERROR_CODE
Description | CLOSEFD@ is the same as CLOSEF@ but CLOSEFD@ also deletes the file from the disc. This is useful for temporary files.


CURDIR@

Platform | x64, Win32
Purpose | To get the current directory.
Syntax | CHARACTER (LEN=*) FUNCTION CURDIR@()
Return value | CURDIR@ returns the fully qualified path name of the current directory. Its maximum length is 256 characters. If an error occurs the path name is filled with spaces.
Example | CHARACTER (LEN=256)::CURDIR@ PRINT *,'You are currently in ',CURDIR@()


COUNT_FILES@

Platform | x64, Win32
Purpose | To obtain the number of files in a directory.
Syntax | INTEGER FUNCTION COUNT_FILES@(PATH) CHARACTER (LEN=*) PATH
Description | Returns the number of files in the directory given by PATH. For example, this could be the full path or the path relative to the "current working directory".
See also | GET_FILES@.


CURRENT_DIR@

Platform | x64, Win32
Purpose | To get the current directory.
Syntax | SUBROUTINE CURRENT_DIR@(DIR,ERROR_CODE) CHARACTER (LEN=*) DIR INTEGER (KIND=2) ERROR_CODE
Description | This routine is obsolete. Use CURDIR@ instead.
Return value | Returns the name of the current working directory in DIR, or a non-zero error code ERROR_CODE if failed. ERROR_CODE is returned as ERANGE if the variable DIR is not of sufficient length. (ERANGE is defined in the include file errno.ins.)


EMPTY@

Platform | x64, Win32
Purpose | To clear a file for writing.
Syntax | SUBROUTINE EMPTY@(SID,ERROR_CODE) INTEGER (KIND=2) SID,ERROR_CODE
Description | EMPTY@ clears the file open with file handle SID (which must not be open for reading only). ERROR_CODE is returned as zero for success or with a system error code if it fails.


ERASE@

Platform | x64, Win32
Purpose | To delete a file.
Syntax | SUBROUTINE ERASE@(FILE,ERROR_CODE) CHARACTER (LEN=*) FILE INTEGER (KIND=2) ERROR_CODE
Description | ERASE@ deletes a file. The file name may be a local name, for example: FOO.TXT, or a fully qualified pathname, for example, C:\PROJECT\JUNK.TXT. ERROR_CODE is returned as zero for success or with the system error code.
Example | CALL ERASE@('USELESS.DAT',ERROR_CODE) CALL DOSERR@(ERROR_CODE)


FEXISTS@

Platform | x64, Win32
Purpose | To search for a file with a given path name or wildcard.
Syntax | LOGICAL (KIND=3) FUNCTION FEXISTS@(PATH, ERROR_CODE) CHARACTER (LEN=*) PATH INTEGER (KIND=3) ERROR_CODE
Return value | FEXISTS@ returns a logical value which is .TRUE. if the name supplied in PATH is that of a file which does exist, or is a wildcard which matches one file only. It returns .FALSE. if such a file does not exist. ERROR_CODE returns zero if the function returns .TRUE. otherwise ERROR_CODE returns a non-zero system error code.


FILE_EXISTS@

Platform | x64, Win32
Purpose | To search for a file with a given path name or wildcard.
Syntax | LOGICAL (KIND=3) FUNCTION FILE_EXISTS@(PATH) CHARACTER (LEN=*) PATH
Description | This function is obsolete. Use FEXISTS@ instead. FILE_EXISTS@ returns a logical value which is .TRUE. if the name supplied in PATH is that of a file which does exist, or is a wildcard which matches one file only. It returns .FALSE. if such a file does not exist, or if any kind of error occurs.


FILE_SIZE@

Platform

x64, Win32

Purpose

To get the size of FILE in bytes.

Syntax

SUBROUTINE FILE_SIZE@(FILE,SIZE,ERROR_CODE)
CHARACTER (LEN=*) FILE
INTEGER (KIND=3) SIZE
INTEGER (KIND=2) ERROR_CODE

Description

Returns the size of the file specified by FILE in SIZE. ERROR_CODE is returned as zero if the process is carried out successfully, otherwise ERROR_CODE returns a system error code.

File sizes that are greater than or equal to 2147483647 are returned as 2147483647.
The routine FILE_SIZE8@ has the same arguments except that SIZE is declared as REAL*8.


FILE_TRUNCATE@

Platform | x64, Win32
Purpose | To truncate an open file at its current position.
Syntax | SUBROUTINE FILE_TRUNCATE@(SID,ERROR_CODE) INTEGER (KIND=2) SID,ERROR_CODE
Description | This routine uses the system identifier SID of a file that has already been opened by OPENW@ or OPENRW@ and truncates the file at the current writing position. ERROR_CODE is returned as zero if the process is carried out successfully, otherwise ERROR_CODE returns a system error code.


FILEINFO@

Platform

x64, Win32

Purpose

To get information about a specified file.

Syntax

SUBROUTINE FILEINFO@(PATH, MODE, DEV, RDEV, NLINK, SIZE, ATIME, MTIME, CTIME, ERROR_CODE)
CHARACTER (LEN=*) PATH
INTEGER (KIND=2) MODE, DEV, RDEV, NLINK, ERROR_CODE
INTEGER (KIND=3) SIZE, ATIME, MTIME, CTIME

Description

Returns information about the file specified by PATH. This routine can be used to return the size of a file in SIZE and the date and time that the file was last accessed in ATIME. The returned value of ATIME can then be supplied to TOTIME@, TOEDATE@ etc.. Similarly MTIME is the last write time and CTIME is the time of creation. ERROR_CODE is returned as zero if the process is carried out successfully, otherwise ERROR_CODE returns a system error code.

File sizes that are greater than or equal to 2147483647 are returned as 2147483647.
The routine FILEINFO8@ has the same arguments except that SIZE is declared as REAL*8.


FILES@

Platform

x64, Win32

Purpose

To obtain directory information.

Syntax

SUBROUTINE FILES@(PAT, N, NMAX, FILES, ATTR, DATE, TIME, FILE_SIZE)
CHARACTER (LEN=*) PAT,FILES(NMAX)
INTEGER (KIND=2) N,NMAX
INTEGER (KIND=2) ATTR(NMAX), DATE(NMAX), TIME(NMAX)
INTEGER (KIND=3) FILE_SIZE(NMAX)

Description

Returns directory information for files selected by PAT (e.g. A:\*.FOR). N is returned as the number of file names returned. If N is equal to NMAX there may be more matches which could not be returned. The remainder of the arrays return information about the files. Hidden files and directories are returned by this routine together with ordinary files. Such files may be distinguished by using the DOS file attribute returned in the ATTR array. The date and time are returned in the DOS compressed format.

The information returned within the ATTR array is equivalent to the dwFileAttributes element of the WIN32_FIND_DATA structure as described in the Microsoft documentation.

File sizes that are greater than or equal to 2147483647 are returned as 2147483647.
The routine FILES8@ has the same arguments except that FILE_SIZE is declared as REAL*8.

Example

See SET_FILE_ATTRIBUTE@ .


FLUSH_FORTRAN_HANDLE@

Platform | x64, Win32
Purpose | To flush the Fortran low level buffer.
Syntax | SUBROUTINE FLUSH_FORTRAN_HANDLE@(SID) INTEGER (KIND=2) SID
Description | SID is a system identifier returned by OPENRW@ or OPENF@. This routine flushes the output buffer to disk but keeps the file open.


FPOS@

Platform

x64, Win32

Purpose

To reposition a file.

Syntax

SUBROUTINE FPOS@(SID,POSITION, NEW_POSITION, ERROR_CODE)
INTEGER (KIND=2) SID, ERROR_CODE
INTEGER (KIND=3) POSITION, NEW_POSITION

Description

FPOS@ attempts to reposition an open file with the given SID to the given POSITION. NEW_POSITION is returned as either the requested POSITION or as the position of end-of-file, whichever is less. ERROR_CODE is returned as zero or with a system error code if it fails.

Notes

If the input value of POSITION is supplied as a constant and the compiler option /INTS is used, it will be necessary to force the length of the constant to 4 bytes.

You can use FPOSLONG@ to reposition a file to a 64-bit offset

SUBROUTINE FPOSLONG@(SID,POSITION, NEW_POSITION, ERROR_CODE)
INTEGER (KIND=2) SID, ERROR_CODE
INTEGER (KIND=4) POSITION, NEW_POSITION

See also

OPENR@, OPENRW@, OPENW@, READF@, READFA@, WRITEF@, WRITEFA@, CLOSEF@, FPOS_EOF@


FPOS_EOF@

Platform | x64, Win32
Purpose | To move the file pointer to end-of-file
Syntax | SUBROUTINE FPOS_EOF@(SID, NEW_POSITION, ERROR_CODE) INTEGER (KIND=2) SID, ERROR_CODE INTEGER (KIND=3) NEW_POSITION
Description | Move the file pointer associated with the file open with the given SID to end-of-file. NEW_POSITION is the new value of the file pointer.
Notes | You can use FPOS_EOFLONG@ to move to end-of-file and get the position a file as a 64-bit offset. SUBROUTINE FPOS_EOFLONG@(SID, NEW_POSITION, ERROR_CODE) INTEGER (KIND=2) SID, ERROR_CODE INTEGER (KIND=4) NEW_POSITION
See also | OPENR@, OPENRW@, OPENW@, READF@, READFA@, WRITEF@, WRITEFA@, CLOSEF@, FPOS@


GET_FILES@

Platform

x64, Win32

Purpose

To get a list of files in the current working directory.

Syntax

SUBROUTINE GET_FILES@(WILDCARD, FILES, MAXFILES, NFILES, ERROR_CODE)
CHARACTER (LEN=*) WILDCARD, FILES(MAXFILES)
INTEGER (KIND=2) MAXFILES, NFILES, ERROR_CODE

Description

Returns a list of all the files in the current working directory which can be matched by WILDCARD.

Returns error code ERROR_CODE as ERANGE if FILES is not big enough, but the entries which are stored in FILES will be valid.

See also

COUNT_FILES@.


GET_PATH@

Platform | x64, Win32
Purpose | To get the fully qualified pathname.
Syntax | SUBROUTINE GET_PATH@(SID,RESULT,ERROR_CODE) CHARACTER (LEN=*) RESULT INTEGER (KIND=2) SID,ERROR_CODE
Description | GET_PATH@ returns the pathname of the file with system identifier SID. This works regardless of whether a local or global name was used when the file was originally opened. ERROR_CODE is returned as zero for success or it is returned as a system error code.
Example | CHARACTER (LEN=100)::FULL_PATH CALL OPENR@('MYDATA',SID,ERROR_CODE) CALL DOSERR@(ERROR_CODE) CALL GET_PATH@(SID,FULL_PATH,ERROR_CODE) CALL DOSERR@(ERROR_CODE) PRINT *,FULL_PATH. . .


MKDIR@

Platform | x64, Win32
Purpose | To create a new system directory.
Syntax | SUBROUTINE MKDIR@(DIR,ERROR_CODE) CHARACTER (LEN=*) DIR INTEGER (KIND=2) ERROR_CODE
Description | The argument DIR can be either the local name of a directory, or the full path name. In either case, if the directory cannot be created for any reason, a non-zero system error code will be returned.


OPENF@

Platform

x64, Win32

Purpose

To open a file for reading or writing with sharing attributes.

Syntax

SUBROUTINE OPENF@(FILE,ATTR,SID,ERROR_CODE)
CHARACTER (LEN=*) FILE
INTEGER (KIND=2) ATTR,SID,ERROR_CODE

Description

This routine opens the given file FILE for reading or writing without deleting existing data. If the file does not exist then it is created. The subroutine returns the identifier SID for use with other file handling routines in this chapter. ERROR_CODE is returned as zero if the operation has succeeded, otherwise it is returned with the relevant system error code.

ATTR is an input to the subroutine that is used to specify the attributes of the open file. The first four bits (the least significant or rightmost) specify the access mode. The next four bits specify the share mode as follows.

Access mode | read only | Z'00' | Current application can only read the file.
 | write only | Z'01' | Current application can only write to the file.
 | read/write | Z'02' |
Share mode | compatibility mode | Z'00' | Compatible with systems that do not allow sharing, equivalent to 'deny none'.
 | deny all | Z'10' | Other applications can not read or write to the file whilst it is open in the current application.
 | deny write | Z'20' | Other applications can not write to the file whilst it is open in the current application.
 | deny read | Z'30' | Other applications can not read the file whilst it is open in the current application.
 | deny none | Z'40' | Other applications are allowed to read or write to the file.

 | Thus for read/write access with shared 'deny all' access use Z'12'.
Notes | The sharing attributes of an open file are determined by the first application to open it. So if it is already open the current sharing mode will have no effect.


OPENR@

Platform | x64, Win32
Purpose | To open a file for reading.
Syntax | SUBROUTINE OPENR@(FILE, SID, ERROR_CODE) CHARACTER (LEN=*) FILE INTEGER (KIND=2) SID, ERROR_CODE
Description | This routine opens the given file FILE for reading and returns the identifier SID for use with other file handling routines. ERROR_CODE is returned as zero if the operation has succeeded, otherwise it is returned with the relevant system error code.
See also | OPENRW@, OPENW@, READF@, READFA@, WRITEF@, WRITEFA@, CLOSEF@, FPOS@, FPOS_EOF@


OPENRW@

Platform | x64, Win32
Purpose | To open a file for reading or writing.
Syntax | SUBROUTINE OPENRW@(FILE, SID, ERROR_CODE) CHARACTER (LEN=*) FILE INTEGER (KIND=2) SID, ERROR_CODE
Description | This routine opens a file FILE for reading or writing and returns the identifier SID for use with other file handling routines. If the file does not exist it is created, however an existing file is not emptied and may be over-written at the current position. If the intended action depends on whether or not a given file exists, then a prior call to OPENR@ can be used to test if it does exist. ERROR_CODE is returned as zero if the operation has succeeded, otherwise it is returned with the relevant system error code.
See also | OPENR@, OPENW@, READF@, READFA@, WRITEF@, WRITEFA@, CLOSEF@, FPOS@, FPOS_EOF@


OPENW@

Platform | x64, Win32
Purpose | To open a file for writing.
Syntax | SUBROUTINE OPENW@(FILE, SID, ERROR_CODE) CHARACTER (LEN=*) FILE INTEGER (KIND=2) SID, ERROR_CODE
Description | This routine opens a file FILE for writing, by creating a file or emptying the file if it already exists. It returns the identifier SID for use with other file handling routines. ERROR_CODE is returned as zero if the operation has succeeded, otherwise it is returned with the relevant system error code.
Example | See OPENRW@ .


RENAME@

Platform | x64, Win32
Purpose | To rename a file.
Syntax | SUBROUTINE RENAME@(FILE1, FILE2, ERROR_CODE) CHARACTER (LEN=*) FILE1, FILE2 INTEGER (KIND=2) ERROR_CODE
Description | RENAME@ renames FILE1 as FILE2 in exactly the same way as the DOS RENAME command.


READF@

Platform

x64, Win32

Purpose

To read binary data from a file.

Syntax

SUBROUTINE READF@(DATA, SID, NBYTES, NBYTES_READ, ERROR_CODE)
CHARACTER (LEN=*) DATA
INTEGER (KIND=2) SID, ERROR_CODE
INTEGER (KIND=3) NBYTES, NBYTES_READ

Description

This routine reads NBYTES of data from an open file with a given system identier SID. ERROR_CODE is returned as zero for success or a system error code. If end of file is reached, NBYTES_READ is returned as -1, with an ERROR_CODE of zero. Also NBYTES_READ may be returned as less than NBYTES. This routine should be used on binary data.

Notes

If the input value of NBYTES is supplied as a constant and the compiler option /INTS is used, it will be necessary to force the length of the constant to 4 bytes.

If compiling for 64-bits (only) there is an extra long version of this routine that can read data chunks in excess of 2GB:

SUBROUTINE READFLONG@(DATA, SID, NBYTES, NBYTES_READ, ERROR_CODE)
CHARACTER (LEN=*) DATA
INTEGER (KIND=2) SID, ERROR_CODE
INTEGER (KIND=4) NBYTES, NBYTES_READ

See also

OPENR@, OPENRW@, OPENW@, READFA@, WRITEF@, WRITEFA@, CLOSEF@, FPOS@, FPOS_EOF@


READFA@

Platform | x64, Win32
Purpose | To read ASCII text from a file.
Syntax | SUBROUTINE READFA@(DATA, SID, NBYTES_READ, ERROR_CODE) CHARACTER (LEN=*) DATA INTEGER (KIND=2) SID, ERROR_CODE INTEGER (KIND=3) NBYTES_READ
Description | READFA@ reads a line of text from an open file with a given system identifier SID. Tabs are expanded as necessary. ERROR_CODE is returned as zero for success or with a system error code. If end of file is reached, NBYTES_READ is returned as -1, with an ERROR_CODE of zero.
See also | OPENR@, OPENRW@, OPENW@, READF@, WRITEF@, WRITEFA@, CLOSEF@, FPOS@, FPOS_EOF@


RFPOS@

Platform | x64, Win32
Purpose | To get the position of a file.
Syntax | SUBROUTINE RFPOS@(SID, POSITION, ERROR_CODE) INTEGER (KIND=2) SID, ERROR_CODE INTEGER (KIND=3) POSITION
Description | This routine returns the POSITION of the file with the given system identifier SID. ERROR_CODE is returned as zero or with a system error code if it fails.
Notes | You can use RFPOSLONG@ to get the position a file at a 64-bit offset. SUBROUTINE FPOSLONG@(SID,POSITION, NEW_POSITION, ERROR_CODE) INTEGER (KIND=2) SID, ERROR_CODE INTEGER (KIND=4) POSITION, NEW_POSITION


SET_FILE_ATTRIBUTE@

Platform | x64, Win32
Purpose | To set a file attribute.
Syntax | SUBROUTINE SET_FILE_ATTRIBUTE@(FILE, IAT, ERROR_CODE) CHARACTER (LEN=*) FILE INTEGER (KIND=2) IAT, ERROR_CODE
Description | This routine sets the attributes of the file FILE to IAT. ERROR_CODE is returned as zero for success or it is the system error code. This routine is useful for performing such tasks as changing the read-only status of a file, hiding or revealing a file, resetting the backup bit etc.. The following program will read a file name (possibly including wild cards) from the terminal and make the files read-only.
Example | CHARACTER (LEN=20)::FILE,FILES(1000),CMNAM INTEGER (KIND=2)::ATTR(1000),DATE(1000),TIME(1000)INTEGER (KIND=3)::FILE_SIZE(1000) CALL FILES@(CMNAM(), N, 1000, FILES, ATTR, DATE, TIME, FILE_SIZE) DO I=1,N CALL SET_FILE_ATTRIBUTE@(FILES(I),OR(ATTR(I),1),IC) CALL DOSERR@(IC) END DO


SET_SUFFIX@

Platform | x64, Win32
Purpose | To change the extension of a given file name.
Syntax | SUBROUTINE SET_SUFFIX@(FILENAME, SUFFIX, L) CHARACTER (LEN=*) FILENAME CHARACTER (LEN=3) SUFFIX LOGICAL (KIND=2) L
Description | SET_SUFFIX@ changes the file extension of a given file with name FILENAME. SUFFIX is the new extension required, given without the period ("."). The value L will be set to .TRUE. if the file had an extension that was not SUFFIX. L will be given the value .FALSE. if the file had the same or no extension.
Example | A='c:\ftn95.dir\file.dat' CALL SET_SUFFIX@(A,'ASC',L) ! At this point A contains 'c:\ftn95.dir\file.ASC' ! and L contains .TRUE.


SET_SUFFIX1@

Platform | x64, Win32
Purpose | To add an extension to a given file name.
Syntax | SUBROUTINE SET_SUFFIX1@(FILENAME,SUFFIX,L) CHARACTER (LEN=*) FILENAME CHARACTER (LEN=3) SUFFIX LOGICAL (KIND=2) L
Description | SET_SUFFIX1@ will add a file-extension SUFFIX to the string FILENAME containing a filename if none is present. The filename will be left as it is if the filename already contains an extension. The extension should be given without the period ("."). The value L will be set to .TRUE. if the file had an extension that was not SUFFIX. L will be given the value .FALSE. if the filename had the same or no extension.
Example | A='c:\ftn95.dir\file.dat' CALL SET_SUFFIX1@(A,'ASC',L) ! At this point A contains 'c:\ftn95.dir\file.dat' ! and L contains .TRUE.


TEMP_FILE@

Platform | x64, Win32
Purpose | To provide a unique name for a file.
Syntax | SUBROUTINE TEMP_FILE@(FILEX, ERROR_CODE) CHARACTER (LEN=*) FILEX INTEGER (KIND=2) ERROR_CODE
Description | TEMP_FILE@ provides a name which may be used for the creation of a temporary file. This name (of the form F$dddddd.TMP where d is a digit) is different from all the file names within the current directory. It is important to note that this routine does not create or open a file.


TEMP_PATH@

Platform | x64, Win32
Purpose | To get a suitable name for a temporary file.
Syntax | SUBROUTINE TEMP_PATH@(PATH, ERROR_CODE) CHARACTER (LEN=*) PATH INTEGER (KIND=2) ERROR_CODE
Description | This routine is obsolete. Use TEMP_FILE@ instead. TEMP_PATH@ makes up a path name for a temporary file. The file name component is created in the same way as for TEMP_FILE@. The directory is that given by the TMPDIR environment variable (or "\TMP" if this is not set). Note that this routine does not actually open the file.


TRANSLATE_FORTRAN_HANDLE@

Platform | x64, Win32
Purpose | To change from a Silverfrost file handle to a Win32 file handle.
Syntax | INTEGER (KIND=7) TRANSLATE_FORTRAN_HANDLE@(SID) INTEGER (KIND=2) SID
Return value | Returns the Win32 file handle corresponding to SID. SID is an identifier returned by OPENR@, OPENRW@, or OPENF@.


WILDCHECK@

Platform | x64, Win32
Purpose | To check for the matching of a file name with a wild card.
Syntax | LOGICAL (KIND=2) FUNCTION WILDCHECK@(WILDCARD, NAME) CHARACTER (LEN=*) WILDCARD, NAME
Description | Returns .TRUE. if NAME can be matched with WILDCARD, .FALSE. otherwise (including when the syntax of WILDCARD or NAME is invalid).


WRITEF@

Platform

x64, Win32

Purpose

To write binary data to a file.

Syntax

SUBROUTINE WRITEF@(DATA,SID, NBYTES, ERROR_CODE)
CHARACTER (LEN=*) DATA
INTEGER (KIND=2) SID, ERROR_CODE
INTEGER (KIND=3) NBYTES

Description

Writes NBYTES of binary data DATA to the file with the given identifier SID. ERROR_CODE is returned as zero for success or a system error code on failure. No data compression on insertion of control characters is performed.

Notes

If the input value of NBYTES is supplied as a constant, it is usually necessary to force its length to 4 bytes (append L to the decimal value).

If compiling for 64-bits (only) there is an extra long version of this routine that can write data chunks in excess of 2GB:

SUBROUTINE WRITEFLONG@(DATA,SID, NBYTES, ERROR_CODE)
CHARACTER (LEN=*) DATA
INTEGER (KIND=2) SID, ERROR_CODE
INTEGER (KIND=4) NBYTES

See also

OPENR@, OPENRW@, OPENW@, READF@, READFA@, WRITEFA@, CLOSEF@, FPOS@, FPOS_EOF@


WRITEFA@

Platform | x64, Win32
Purpose | To write a line of data to an ASCII file.
Syntax | SUBROUTINE WRITEFA@(DATA, SID, ERROR_CODE) CHARACTER (LEN=*) DATA INTEGER (KIND=2) SID, ERROR_CODE
Description | WRITEFA@ writes DATA to an open file with a given identifier SID. A carriage return/linefeed is added to the end of the data. ERROR_CODE is returned as zero for success, otherwise it returns the system error code.
See also | OPENR@, OPENRW@, OPENW@, READF@, READFA@, WRITEF@, CLOSEF@, FPOS@, FPOS_EOF@


In-line routines

The routines in this section are converted to in-line code, rather than procedure calls, and are therefore extremely efficient. They can often be used as a convenient alternative to resorting to assembler. Those routines described here which are functions should be explicitly declared to be of the right type.

FILL@ | Sets an array of N bytes to a particular value.
MATCH@ | Compares two arrays of N bytes.
MOVE@ | Copies an array of N bytes.
POP@ | Pops a value off the system stack.
PUSH@ | Pushes a value on the system stack.


FILL@

Platform | x64, Win32
Purpose | To set an array of N bytes to a particular value.
Syntax | SUBROUTINE FILL@(A, N, B) INTEGER (KIND=3) A, B, N
Description | This routine fills A (which may be of any type and is usually an array) with N bytes of value B. Thus if A is of type INTEGER*4 and N=4, each of the 4 bytes of A will be assigned to the value of B. B may be of any type but only the lowest byte is used.


MATCH@

Platform | x64, Win32
Purpose | To compare two arrays of N bytes.
Syntax | LOGICAL (KIND=2) FUNCTION MATCH@(A, B, N) INTEGER (KIND=2) A, B, N
Description | This function compares N bytes of data for equality. The first two arguments can be of any type and are usually arrays. N can be INTEGER (KIND=1), (KIND=2) or (KIND=3).
Return value | MATCH@ returns .TRUE. if the two arrays are identical, otherwise .FALSE..


MOVE@

Platform | x64, Win32
Purpose | To copy an array of N bytes.
Syntax | SUBROUTINE MOVE@(FROM, TO, N)
Description | This routine copies N bytes of data from FROM to TO. No data conversion is performed and no checks are made to ensure that the source and destination are large enough (even in /CHECK mode). Arguments FROM and TO may be of any type, N must be INTEGER (KIND=1), (KIND=2) or (KIND=3).


POP@

Platform | x64, Win32
Purpose | To pop a value off the system stack.
Syntax | SUBROUTINE POP@(A) INTEGER (KIND=3) A
Description | This routine is the opposite of PUSH@ .


PUSH@

Platform | x64, Win32
Purpose | To push a value on the system stack.
Syntax | SUBROUTINE PUSH@(A) INTEGER (KIND=3) A
Description | The argument A is pushed on to the system stack. Two bytes will be pushed for INTEGER (KIND=2), four for INTEGER (KIND=3) etc. Values saved in this way can be restored again with POP@ . The corresponding POP@ call must have an argument of the same type (otherwise the wrong number of bytes would be popped). A routine may return with data still pushed on the stack - such data is then lost.


Process control routines

CISSUE@ | Issues a DOS command.
EXIT@ | Terminates a program.
EXIT | Terminates a program.
GET_KEY_OR_YIELD@ | Gets the next keycode.
SLEEP@ | Suspends program execution for a specified time interval.
START_PROCESS@ | Creates a new process.
START_THREAD@ | Creates a new thread.
WAIT_FOR_THREAD@ | Waits for a given thread (or all threads) to end.
LOCK@ | Protects memory accessed on more than one thread.
UNLOCK@ | To release a lock on memory shared by different threads.


CISSUE@

Platform | x64, Win32
Purpose | To issue a system command.
Syntax | SUBROUTINE CISSUE@(A,IFAIL) CHARACTER (LEN=*) A INTEGER (KIND=2) IFAIL
Description | Issues the command stored as a character string in A. IFAIL is returned as one of the following:
IFAIL | Meaning
0 | Successful invocation of a command processor to execute the command
1 | A command processor could not be invoked
Notes | This is a Silverfrost library function. The value of IFAIL refers to the success or failure of invoking the command processor CMD.EXE. Unfortunately, CMD does not provide a mechanism whereby the success or failure of the invocation of the particular command can be reported back to the caller. So, for example, if you get a system error such as "Not found" for the command, IFAIL will be returned as zero. See also: START_PROCESS@, SUPPRESS_CMD_BOX@.


EXIT@

Platform | x64, Win32
Purpose | To terminate a program.
Syntax | SUBROUTINE EXIT@(ERROR_CODE) INTEGER (KIND=2) ERROR_CODE
Description | EXIT@ is a synonym for EXIT.


EXIT

Platform | x64, Win32
Purpose | To terminate a program.
Syntax | SUBROUTINE EXIT(ERROR_CODE) INTEGER (KIND=2) ERROR_CODE
Description | This routine terminates the program and returns to the operating system. If the error code is non zero the termination will be abnormal. Abnormal termination will interrupt the flow of a .BAT file (as if control break had been pressed).
Notes | This is a Silverfrost library function.
See also | ABORT@, EXIT callback


GET_KEY_OR_YIELD@

Platform | x64, Win32
Purpose | To get the next keycode.
Syntax | SUBROUTINE GET_KEY_OR_YIELD@(KEY) INTEGER (KIND=2) KEY
Description | This routine returns a key typed on the keyboard in exactly the same way as GET_KEY@ except that it will yield control to other tasks (if any) when no key press is pending.


LOCK@

Platform | x64, Win32
Purpose | To protect memory shared by different threads.
Syntax | SUBROUTINE LOCK@(LOCK_ID) INTEGER LOCK_ID
Description | Memory that is shared by different threads can be protected by calling LOCK@ (before) and UNLOCK@ (after) accessing the memory. LOCK@ and UNLOCK@ can also be used before and after calls to routines that access "static" variables in order to make them locally thread-safe. When LOCK@ is called and the same LOCK_ID is already active on another thread then LOCK@ waits for the corresponding UNLOCK@ on the other thread. Each LOCK_ID is assigned by the user and is to be uniquely associated with a particular grouping of variables.
See also | START_THREAD@, WAIT_FOR_THREAD@, UNLOCK@.


SLEEP@

Platform | x64, Win32
Purpose | To suspend program execution for a specified time interval.
Syntax | SUBROUTINE SLEEP@(TIME) REAL (KIND=1) TIME
Description | The time is given in seconds and is accurate to within one tick (18.2 ticks per second).
Note | SLEEP@ continues to use the CPU. To release the CPU, use SLEEP1@ instead. SLEEP1@ has the same argument as SLEEP@.


START_PROCESS@

Platform

x64, Win32

Purpose

To create a new process and wait for it to terminate.

Syntax

INTEGER FUNCTION START_PROCESS@(COMMAND,PARAMS)
CHARACTER(LEN=*) COMMAND,PARAMS

Description

COMMAND is the command line that is to be executed. PARAMS is a string of parameters that is appended to the command line.

Return value

Returns 0 or a positive value if successful. A return value of -1 indicates an error condition.
If the new process exits via a call of the form EXIT(errorcode) then START_PROCESS@ returns the value of errorcode.

Notes

The new process is given the same 'show' state as that used when creating the calling process. This will usually be 'show normal' or 'show maximised'.

The alternative function START_PPROCESS@ takes the same form but returns immediately (i.e. it does not wait for the created process to terminate).

If the process that is started is a console application you can prevent it from showing the console window by calling SUPPRESS_CMD_BOX@ first.


START_THREAD@

Platform

x64, Win32

Purpose

To start a new thread.

Syntax

INTEGER(7) START_THREAD@(SUB, PARAM)
INTEGER(7) PARAM
INTERFACE
SUBROUTINE SUB(ARG)
INTEGER(7) ARG
END SUBROUTINE
END INTERFACE

Description

START_THREAD@ starts SUB on a new thread and passes the argument PARAM to it as the value of ARG.

Notes

If PARAM is a variable that is used to return a value (INTENT(OUT)) then it must "exist" (remain in scope) whilst the thread is running.

PARAM and ARG are described here as having type INTEGER(7) but FTN95 will allow the argument to have any matching standard or user-defined type.

Return value

START_THREAD@ returns the Microsoft thread handle for the new thread.

See also

WAIT_FOR_THREAD@, LOCK@, UNLOCK@.


UNLOCK@

Platform | x64, Win32
Purpose | To release a lock on memory shared by different threads.
Syntax | SUBROUTINE UNLOCK@(LOCK_ID) INTEGER LOCK_ID
Description | See LOCK@.
See also | START_THREAD@, WAIT_FOR_THREAD@, LOCK@.


WAIT_FOR_THREAD@

Platform | x64, Win32
Purpose | To take a thread handle created via START_THREAD@ and wait for the given thread to end.
Syntax | SUBROUTINE WAIT_FOR_THREAD@(HANDLE) INTEGER(7) HANDLE
Description | If zero is passed instead of a handle then the routine waits for all threads (created using START_THREAD@) to end.
See also | START_THREAD@, LOCK@, UNLOCK@.


Random number routines

DATE_TIME_SEED@ | Selects a new "seed" for the pseudo-random number generator function RANDOM@.
RANDOM@ | Returns a pseudo-random double precision value.
SET_SEED@ | Enters a new "seed" for the pseudo-random number generator function RANDOM@.

See also: Standard Fortran 95 random number functions


DATE_TIME_SEED@

Platform | x64, Win32
Purpose | To select a new "seed" for the pseudo-random number generator function RANDOM@.
Syntax | SUBROUTINE DATE_TIME_SEED@
Description | This routine sets the seed for the random number generator to a value based on the current DATE/TIME. This routine is used to obtain a non repeatable sequence of pseudo-random numbers.
See also | RANDOM_SEED


RANDOM@

Platform | x64, Win32
Purpose | To return a pseudo-random double precision value.
Syntax | REAL (KIND=2) FUNCTION RANDOM@()
Description | This routine sets its seed automatically and produces the same sequence every time the program is run.
 | Alternatively, you may use DATE_TIME_SEED@ or SET_SEED@.
Return value | RANDOM@ returns a uniformly distributed random number x such that 0.0D0 < x < 1.0D0.
Notes | This is a Silverfrost library function. RANDOM_NUMBER is the standard intrinsic function.
Example | REAL(KIND=2)::RANDOM@,RANVEC(100) DO I=1,100 RANVEC(I)=RANDOM@() END DO . . .


SET_SEED@

Platform | x64, Win32
Purpose | To enter a new "seed" for the pseudo-random number generator function RANDOM.
Syntax | SUBROUTINE SET_SEED@(SEED) REAL (KIND=2) SEED
Description | This routine sets the seed for the random number generator to a value based on SEED. SEED may take any value. Each value produces a repeatable sequence of pseudo-random numbers.
See also | RANDOM_SEED


Serial communications routines

The following routines provide for Win32 serial communication between your computer and external devices. To access these routines you need to provide definitions by, for example, including the file clearwin.ins or by using the MSWIN module.

GETTERMINATECOMMCHAR@ | Gets the character that terminated the last call to READCOMMDEVICE@.
OPENCOMMDEVICE@ | Opens a serial port for I/O.
READCOMMDEVICE@ | Reads data from an open serial port.
SETCOMMTERMINATECHAR@ | Sets the characters that may be used to terminate a call to READCOMMDEVICE@.
SETCOMMWAITFORLINEFEED@ | Configures READCOMMDEVICE@ to wait for a linefeed character before returning.
SETECHOONREADCOMM@ | Sets the communication port to echo back to the sending device.
SETYIELDCOMM@ | Configures READCOMMDEVICE@ to yield to other applications when waiting for data.
WRITECOMMDEVICE@ | Writes a string to a serial port.


GETTERMINATECOMMCHAR@

Platform | Win32
Purpose | To get the character that terminated the last call to READCOMMDEVICE@.
Syntax | CHARACTER GETTERMINATECOMMCHAR@(PORTNUM) INTEGER (KIND=3) PORTNUM
Return value | GETTERMINATECOMMCHAR@returns the character that terminated the last READCOMMDEVICE@ call. This will be one of the characters set using SETCOMMTERMINATECHAR@. If the port is not open the function returns 1. If READCOMMDEVICE@ has not been called the default return is zero.
Notes | To access this routine you need to provide a definition by, for example, including the file clearwin.ins or by using the MSWIN module.


OPENCOMMDEVICE@

Platform

x64, Win32

Purpose

To open a serial port for I/O.

Syntax

INTEGER (KIND=7) OPENCOMMDEVICE@(PORTNUM,COMSPEC,RSIZE,TSIZE)
INTEGER (KIND=3) PORTNUM, RSIZE,TSIZE
CHARACTER (LEN=*) COMSPEC

Description

To initiate serial communications between the computer and external devices a communications port must be selected and opened.

PORTNUM must be in the range 0 to 256.

COMSPEC is a string that specifies the baud rate, parity, data and stop bit information (e.g. '9600, n, 8, 1'). Possible values are:

baud rate: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200

parity: n (none), o (odd), e (even)

data bits: 7 or 8

stop bits: 0 or 1

RSIZE and TSIZE were provided for Windows 3.1 and are now redundant.

Return value

OPENCOMMDEVICE@ returns a positive value when successful otherwise it returns -1.

Notes

To access this routine you need to provide a definition by, for example, including the file clearwin.ins or by using the MSWIN module.

OPENCOMMDEVICE@ returns a file HANDLE that can be used in a direct calls to Microsoft library functions such as WaitCommEvent. A suitable interface for WaitCommEvent is:
STDCALL WaitCommEvent 'WaitCommEvent' (VAL,REF,VAL):INTEGER*4
where the first argument is the HANDLE returned by OPENCOMMDEVICE@. The second argument receives the event mask and is an INTEGER*4 variable. The third argument must be set to zero and represents a NULL pointer passed as a value.


READCOMMDEVICE@

Platform | Win32
Purpose | To read data from an open serial port.
Syntax | INTEGER (KIND=3) READCOMMDEVICE@(PORTNUM,STRING,NREAD) INTEGER (KIND=3) PORTNUM,NREAD CHARACTER (LEN=*) STRING
Description | Use this function to read data from a serial port that has been opened by a call to OPENCOMMDEVICE@. PORTNUM must be a valid port number in the range 1 to 4 and NREAD is set as the maximum number of characters to be read. After the call STRING will contain the data held in the serial port up to NREAD characters. Fewer than NREAD characters will be read if one of the termination characters (set using SETCOMMTERMINATECHAR@) is encountered.
Return value | READCOMMDEVICE@ returns the number of characters read or -1 if an error occurred.
Notes | To access this routine you need to provide a definition by, for example, including the file clearwin.ins or by using the MSWIN module.


SETCOMMTERMINATECHAR@

Platform | Win32
Purpose | To set the characters that may be used to terminate a call to READCOMMDEVICE@ .
Syntax | INTEGER (KIND=3) SETCOMMTERMINATECHAR@(PORTNUM,STRING,LEN) INTEGER (KIND=3) PORTNUM,LEN CHARACTER (LEN=*) STRING
Description | PORTNUM must be a valid serial port number in the range 1 to 4. STRING contains a string of length LEN. This string is used to provide a list of characters that may be used to terminate a call to READCOMMDEVICE@. The termination character is discarded when READCOMMDEVICE@ is called. For example char(0)//char(12)//char(15) provides for the data to be terminated by a null character, a line feed or a carriage return.
Return value | SETCOMMTERMINATECHAR@ returns a positive value if successful or -1 if an error has occurred.
Notes | To access this routine you need to provide a definition by, for example, including the file clearwin.ins or by using the MSWIN module.


SETCOMMWAITFORLINEFEED@

Platform | Win32
Purpose | To set the "wait for line feed" state for READCOMMDEVICE@.
Syntax | INTEGER (KIND=3) SETCOMMWAITFORLINEFEED@(PORTNUM,STATE) INTEGER (KIND=3) PORTNUM,STATE
Description | Use this function to configure a serial port that has been opened by a call to OPENCOMMDEVICE@. PORTNUM must be a valid port number in the range 1 to 4. STATE is zero by default. Call this function with STATE=1 in order to cause READCOMMDEVICE@ to to wait for a linefeed character before returning.
Return value | SETCOMMWAITFORLINEFEED@ returns a positive value when successful otherwise it returns -1.


SETECHOONREADCOMM@

Platform | Win32
Purpose | To set the communication port to echo back to the sending device.
Syntax | INTEGER (KIND=3) SETECHOONREADCOMM@(PORTNUM,STATE) INTEGER (KIND=3) PORTNUM,STATE
Description | When communicating with a serial device such as a terminal, it is often necessary to return the data to the sender. In the case of a terminal the data will be transmitted from its keyboard to the host computer. SETECHOONREADCOMM@ is used to enable (STATE = 1) or disable (STATE = 0) the echoing of data. Data that is echoed back to a terminal will be displayed on its VDU. PORTNUM is a valid port number in the range 1 to 4.
Return value | SETECHOONREADCOMM@ returns a positive value if successful or -1 if an error has occurred.
Notes | To access this routine you need to provide a definition by, for example, including the file clearwin.ins or by using the MSWIN module.


SETYIELDCOMM@

Platform | Win32
Purpose | To set the yield state for READCOMMDEVICE@.
Syntax | INTEGER (KIND=3) SETYIELDCOMM@(PORTNUM,STATE) INTEGER (KIND=3) PORTNUM,STATE
Description | Use this function to configure a serial port that has been opened by a call to OPENCOMMDEVICE@. PORTNUM must be a valid port number in the range 1 to 4. STATE is zero by default. Call this function with STATE=1 in order to allow subsequent calls to READCOMMDEVICE@ to yield to other applications whilst waiting for data.
Return value | SETYIELDCOMM@ returns a positive value when successful otherwise it returns -1.


WRITECOMMDEVICE@

Platform | Win32
Purpose | To write a string to a serial port.
Syntax | INTEGER (KIND=3) WRITECOMMDEVICE@(PORTNUM,STRING) INTEGER (KIND=3) PORTNUM CHARACTER (LEN=*) STRING
Description | Use this function to write a string to a serial port that has been opened by a call to OPENCOMMDEVICE@. PORTNUM must be a valid port number in the range 1 to 4.
Return value | The function returns the number of characters written or -1 if an error has occurred.
Notes | To access this routine you need to provide a definition by, for example, including the file clearwin.ins or by using the MSWIN module.


Storage management routines

The routines described in this section provide a virtual storage heap. The virtual memory heap is located in memory above the stack, and has an initial size of 100 Megabytes. Since these routines work with addresses, the storage acquired by these routines must be manipulated by the 'core' intrinsics. As with any storage heap, it is important to avoid excessive fragmentation. This can be achieved by a variety of strategies, such as allocating blocks of fixed size, or de-allocating all allocated storage at once, so that no 'holes' are created. The first fit algorithm is used by the routines. Block sizes are rounded up to multiples of 4 bytes in size and carry a maximum of a 16-byte overhead. This overhead is reduced when many blocks are allocated and can be reduced to as little as 4 bytes. It is not necessary to return allocated storage before a program terminates - this is done automatically.

Under Win32 there are two 100MB heaps:

a) A Fortran heap used by GET_STORAGE@, RETURN_STORAGE@ and SHRINK_STORAGE@. This is fully virtual. Pages are provided by the run-time system in order to fill program page demands. The program may fail if it uses too much of the address space allocated or if the physical resources of the system are not sufficient to satisfy the program's demands.

b) A C/C++ heap used by malloc, new etc. in order to provide physical (committed) pages.

Memory allocated from this heap is guaranteed to be available. Memory allocated by GET_STORAGE@ should not be returned using free or delete. Similarly, memory allocated using malloc or new should not be returned using RETURN_STORAGE@.

GET_STORAGE@ | Gets a block of storage of size N bytes from the storage heap.
RETURN_STORAGE@ | Returns a block of storage.
SHRINK_STORAGE@ | Shrinks a block of storage.
GET_GSTORAGE@ | Gets a block of storage of size N bytes directly from the operating system.
RETURN_GSTORAGE@ | Returns a block of storage storage allocated by GET_GSTORAGE@.

See also: Standard Fortran 95 storage allocation


GET_GSTORAGE@

Platform

Win32

Purpose

To get a block of memory of size N bytes from the global memory heap.

Syntax

SUBROUTINE GET_GSTORAGE@(ADDR,N)
INTEGER (KIND=7) ADDR
INTEGER N

Description

ADDR is returned as the address of the first byte of the block. A returned value of -1 indicates that there is insufficient contiguous memory to create the block.

GET_GSTORAGE@ is provided for situations where a large block of memory is required in a Win32 application for a long period of time after which it is assumed that it will be released (using RETURN_GSTORAGE@) with no intention of using it again. In situations where the amount of memory required is small (<32K) GET_STORAGE@ provides better performance. GET_GSTORAGE@ requests memory directly from the operating system rather than using the heaps managed by salflibc

GET_GSTORAGE@ is not available for .NET where GET_STORAGE@ must be used.

Notes

Memory allocated using GET_GSTORAGE@ should be returned using RETURN_GSTORAGE@.

See also

RETURN_GSTORAGE@, GET_STORAGE@


GET_STORAGE@

Platform | Win32
Purpose | To get a block of storage of size N bytes from the storage heap.
Syntax | SUBROUTINE GET_STORAGE@(ADDR,N) INTEGER (KIND=7) ADDR INTEGER N
Description | ADDR is returned as the address of the first byte of the block. A returned value of -1 indicates that there is insufficient contiguous storage to create the block.
Notes | The heap used by GET_STORAGE@, RETURN_STORAGE@ and SHRINK_STORAGE@ is fully virtual. Pages are provided by the runtime system to satisfy the program's page demands. The program may fail if it uses too much of the address space allocated or if the physical resources on the system are not sufficient to satisfy the program's demands. Memory allocated using GET_STORAGE@ should be returned using RETURN_STORAGE@. The C function free and the C++ operator delete can not be used for this purpose.
See also | GET_GSTORAGE@


RETURN_GSTORAGE@

Platform | Win32
Purpose | To return a block of memory.
Syntax | SUBROUTINE RETURN_GSTORAGE@(ADDR) INTEGER (KIND=7) ADDR
Description | Returns a block of memory previously allocated by GET_GSTORAGE@. ADDR must be the value returned by an earlier call to GET_GSTORAGE@.


RETURN_STORAGE@

Platform | Win32
Purpose | To return a block of storage.
Syntax | SUBROUTINE RETURN_STORAGE@(ADDR) INTEGER (KIND=7) ADDR
Description | Returns a block of storage previously allocated by one of the storage management routines. ADDR must be the address of the start of the storage block to be returned.


SHRINK_STORAGE@

Platform | Win32
Purpose | To shrink a block of storage.
Syntax | SUBROUTINE SHRINK_STORAGE@(ADDR,N) INTEGER (KIND=7) ADDR INTEGER N
Description | Shrinks a block of storage previously allocated by one of the storage management routines. ADDR must be the address of the start of the storage block whose size is to be adjusted. N is the new size of the block. This routine cannot be used to enlarge a storage block.


System routines

DOSPARAM@ | Gets an environment variable.
GET_CURRENT_FORTRAN_IO@ | Accesses the state of the current Fortran I/O unit.
GET_CURRENT_FORTRAN_UNIT@ | Gets the unit number for the current I/O operation.
GETENV@ | Gets an environment variable.
GLOBALMEMORYSTATUS@ | Return information about system memory use.
PROCESSMEMORYINFO@ | Return information about memory use for the process.
SET_MAXIMUM_IO_BUFFER_SIZE@ | Increase the I/O buffer size from the default size of 32767.


DOSPARAM@

Platform

x64, Win32

Purpose

To get a DOS environment parameter value.

Syntax

SUBROUTINE DOSPARAM@(PARAM, VALUE)
CHARACTER (LEN=*) PARAM, VALUE

Description

This routine returns the value VALUE of a DOS parameter PARAM, which has been set using the DOS SET command. This can be very useful while creating environments in which programs are controlled by global information set up in batch files.

Example

After the DOS command
SET FILENAME=FRED
has been executed, the following code would open the file FRED:

CHARACTER (LEN=50)::FILE
CALL DOSPARAM@('FILENAME',FILE)
OPEN(FILE=FILE,UNIT=6)


GET_CURRENT_FORTRAN_UNIT@

Platform | x64, Win32
Purpose | To get the unit number for the current I/O operation.
Syntax | SUBROUTINE GET_CURRENT_FORTRAN_UNIT@(UNIT) INTEGER (KIND=2) UNIT
Description | This routine is useful in device drivers (using the DEVICE= I/O keyword) which are to be attached to more than one Fortran stream.


GLOBALMEMORYSTATUS@

Platform

Win32(ClearWin+)

Purpose

Provide easy access to the Windows API function GlobalMemoryStatusEx.

Syntax

INTEGER*8 GLOBALMEMORYSTATUS@(OPTION)
INTEGER OPTION

Description

OPTION is an input value in the range 1 to 7 that specifies the status value to be returned as follows:

1 | number between 0 and 100 that specifies the approximate percentage of physical memory that is in use (0 indicates no memory use and 100 indicates full memory use). | (dwMemoryLoad)
2 | Amount of physical memory currently available, in bytes. This is the amount of physical memory that can be immediately reused without having to write its contents to disk first. It is the sum of the size of the standby, free, and zero lists. | (ullTotalPhys)
3 | Amount of physical memory currently available, in bytes. | (ullAvailPhys)
4 | Current committed memory limit for the system or the current process, whichever is smaller, in bytes | (ullTotalPageFile)
5 | Maximum amount of memory the current process can commit, in bytes. | (ullAvailPageFile)
6 | The size of the user-mode portion of the virtual address space of the calling process, in bytes. This value depends on the type of process, the type of processor, and the configuration of the operating system. For example, this value is approximately 2 GB for most 32-bit processes on an x86 processor and approximately 3 GB for 32-bit processes that are large address aware running on a system with 4-gigabyte tuning enabled. | (ullTotalVirtual)
7 | Amount of unreserved and uncommitted memory currently in the user-mode portion of the virtual address space of the calling process, in bytes. | (ullAvailVirtual)

A negative returned value indicates an error condition. GlobalMemoryStatus@ can be called directly without the aid of a header file but must be declared as INTEGER*8.

Notes

Added to FTN95 at version 8.00

See Also

PROCESSMEMORYINFO@


ProcessMemoryInfo@

Platform

x64, Win32

Purpose

Return information about memory use for the process.

Syntax

INTEGER*8 FUNCTION ProcessMemoryInfo@(OPTION)
INTEGER OPTION

Description

This provides easy access to the Windows API function GetProcessMemoryInfo.

OPTION is an input value in the range 1 to 9 that specifies the information value to be returned as follows:

1: The number of page faults | (PageFaultCount)
2: The peak working set size, in bytes. | (PeakWorkingSetSize)
3: The current working set size, in bytes. | (WorkingSetSize)
4: The peak paged pool usage, in bytes. | (QuotaPeakPagedPoolUsage)
5: The current paged pool usage, in bytes. | (QuotaPagedPoolUsage)
6: The peak nonpaged pool usage, in bytes. | (QuotaPeakNonPagedPoolUsage)
7: The current nonpaged pool usage, in bytes. | (QuotaNonPagedPoolUsage)
8: The Commit Charge value in bytes for this process. | (PagefileUsage)
9: The peak value in bytes of the Commit Charge during the lifetime of this process. | (PeakPagefileUsage)

A negative returned value indicates an error condition. ProcessMemoryInfo@ can be called directly without the aid of a header file but it must be declared as INTEGER*8. For further information on these information values, see "PROCESS_MEMORY_COUNTERS structure".

Notes

Introduced with FTN95 8.10.

See Also

GLOBALMEMORYSTATUS@


SET_MAXIMUM_IO_BUFFER_SIZE@

Platform | x64, Win32
Purpose | Increase the I/O buffer size from the default size of 32767.
Syntax | SUBROUTINE SET_MAXIMUM_IO_BUFFER_SIZE@(size) INTEGER size
Description | Increase the I/O buffer size from the default size of 32767. This should only be used if the record length exceeds 32767.
Notes | Introduced with FTN95 8.20.


GETENV@

Platform | x64, Win32
Purpose | To get an environment variable.
Syntax | CHARACTER (LEN=*) FUNCTION GETENV@(VARIABLE) CHARACTER (LEN=*) VARIABLE
Return value | Returns the value of the specified environment variable.
See also | Intrinsic GET_ENVIRONMENT_VARIABLE


Time and date routines

CLOCK@ | Gets a time in seconds.
DATE@ | Gets the date in the form MM/DD/YY (American format).
DCLOCK@ | Gets a time in seconds.
EDATE@ | Gets the date in the form DD/MM/YY (European format).
FDATE@ | Gets the date in text form.
HIGH_RES_CLOCK@ | Obtains the CPU time accurate to 1 microsecond.
SECONDS_SINCE_1980@ | Gets the number of seconds from a fixed date.
TIME@ | Gets the time in the format HH:MM:SS.
TODATE@ | Converts a given time to a date in the form MM/DD/YY.
TOEDATE@ | Converts a given time to a date in the form DD/MM/YY.
TOFDATE@ | Returns the date in text form.
TOTIME@ | Returns the time in the form HH:MM:SS.

See also: Standard Fortran 95 time and date functions


CLOCK@

Platform | x64, Win32
Purpose | To get a time in seconds.
Syntax | SUBROUTINE CLOCK@(R) REAL (KIND=1) R
Description | This routine is usually used to time a process as shown in the example below.
See also | CPU_TIME, DCLOCK@, HIGH_RES_CLOCK@, SECONDS_SINCE_1980@.
Example | CALL CLOCK@(START) ! some calculation. . . CALL CLOCK@(FINISH) PRINT *,'elapsed time used = ',FINISH-START


CONVDATE@

Platform

x64, Win32

Purpose

To get the current date in numeric form.

Syntax

SUBROUTINE CONVDATE@(SECS,IDW,IDAY,IMONTH,IYEAR)
INTEGER (KIND=3) SECS
INTEGER (KIND=2) IDW,IDAY,IMONTH,IYEAR

Description

Converts SECS into a day of the week, IDW (0 = Sunday) and the day, month and year. SECS is the number of seconds since the beginning of 1970 obtained via a call to SECONDS_SINCE_1970@, converting the result from REAL(2) to INTEGER(3).

SUBROUTINE SECONDS_SINCE_1970@(DR)
REAL(KIND=2) DR

Notes

For x64 set SECS = 0.


CPU_CLOCK@

Platform | Win32
Purpose | To get the number of CPU clocks since start up.
Syntax | REAL (KIND=3) FUNCTION CPU_CLOCK@()
Description | This routine is usually used to time a process as shown in the example below. The routine is coded inline using the Pentium assembly instruction XRDTSC. It has its own time penalty of the order of 20 CPU clocks.
Notes | The function CPU_CLOCK@ is not available for 64 bit applications and has been replaced by the function RDTSC_VAL@ that takes no arguments and returns an INTEGER*8 result.
See also | CPU_TIME, DCLOCK@, HIGH_RES_CLOCK@, SECONDS_SINCE_1980@.
Example | REAL(3) START,FINISH START= CPU_CLOCK@() ! some calculation. . . FINISH= CPU_CLOCK@() PRINT *,FINISH-START,'clocks taken'


DATE@

Platform | x64, Win32
Purpose | To get the date in the form MM/DD/YY or MM/DD/YYYY (American format).
Syntax | CHARACTER*8 FUNCTION DATE@() CHARACTER*10 FUNCTION DATE@()
Description | Use CHARACTER (LEN=8) for MM/DD/YY and CHARACTER (LEN=10) for MM/DD/YYYY where the year appears as four digits.
See also | DATE_AND_TIME, EDATE@, FDATE@.
Example | CHARACTER (LEN=8)::DATE@ PRINT *,'program run on ',DATE@()


DCLOCK@

Platform | x64, Win32
Purpose | To get a time in seconds.
Syntax | SUBROUTINE DCLOCK@(R) REAL (KIND=2) R
Description | This routine is usually used to time a process as shown in the example for CLOCK@. This routine differs from CLOCK@ only in that its argument is REAL (KIND=2). Its main purpose is for use in conjunction with /DREAL, when all variables declared REAL (KIND=1) are actually compiled as REAL (KIND=2).
See also | CPU_TIME, HIGH_RES_CLOCK@ .


EDATE@

Platform | x64, Win32
Purpose | To get the date in the form DD/MM/YY or DD/MM//YYYY (European format).
Syntax | CHARACTER (LEN=8) FUNCTION EDATE@() CHARACTER (LEN=10) FUNCTION EDATE@()
Description | Use CHARACTER (LEN=8) for DD/MM/YY and CHARACTER (LEN=10) for DD/MM/YYYY where the year appears as four digits.
See also | DATE_AND_TIME, DATE@, FDATE@.
Example | CHARACTER (LEN=8)::EDATE@ PRINT *,'program run on ',EDATE@()


FDATE@

Platform | x64, Win32
Purpose | To get the date in text form.
Syntax | CHARACTER (LEN=*) FUNCTION FDATE@()
Return value | FDATE@ returns the date in the form: Thursday February 11, 1988
See also | DATE_AND_TIME, DATE@, EDATE@.
Example | CHARACTER (LEN=20)::FDATE@ PRINT *,'Program run on ',FDATE@()


HIGH_RES_CLOCK@

Platform | x64, Win32
Purpose | To obtain the CPU time accurate to 1 microsecond.
Syntax | REAL (KIND=2) FUNCTION HIGH_RES_CLOCK@(ALIGN) LOGICAL (KIND=2) ALIGN
Description | This function returns the CPU time as seconds since midnight accurate to about 1 microsecond (although the cost of the function call is approximately 100 microseconds because it must call DBOS). To achieve this precision the system clock is reprogrammed in mode 2. This could in principle affect other software, although we are not aware of any problems. The clock remains programmed in mode 2 until the system is rebooted. If the ALIGN argument is set .TRUE., this function will not return until after the next clock tick to help to obtain consistent timings. Obviously the second of a pair of calls to HIGH_RES_CLOCK@ should have ALIGN set to .FALSE.. Although the function is defined as REAL (KIND=2) it actually returns an 80-bit (KIND=3) precision result.
See also | CPU_TIME, DCLOCK@.
Example | REAL (KIND=2)::T1,T2,HIGH_RES_CLOCK@ T1=HIGH_RES_CLOCK@(.TRUE.) CALL SOME_PROCESS T2=HIGH_RES_CLOCK@(.FALSE.) PRINT *,'Time required = ',T2-T1


SECONDS_SINCE_1980@

Platform | x64, Win32
Purpose | To get the number of seconds from a fixed date.
Syntax | SUBROUTINE SECONDS_SINCE_1980@(DR) REAL (KIND=2) DR
Description | This routine returns the value of DR as the number of seconds that have elapsed since 12.00am on 1st January 1980. It can be used in a similar way to CLOCK@ (or DCLOCK@). SECONDS_SINCE_1980@ should be used when making timings which straddle midnight.


TIME@

Platform | x64, Win32
Purpose | To get the time in the format HH:MM:SS.
Syntax | CHARACTER*8 FUNCTION TIME@()
See also | DATE_AND_TIME


TODATE@

Platform | x64, Win32
Purpose | To convert the time given to a date for the form MM/DD/YY (American format). The time given should be the number seconds since the beginning of 1970.
Syntax | CHARACTER (LEN=*) FUNCTION TODATE@(SECS) INTEGER (KIND=3) SECS
See also | DATE_AND_TIME


TOEDATE@

Platform | x64, Win32
Purpose | To convert the time given to a date in the format DD/MM/YY (European format). The time given should be the number seconds since the beginning of 1970.
Syntax | CHARACTER (LEN=*) FUNCTION TOEDATE@(SECS) INTEGER (KIND=3) SECS
See also | DATE_AND_TIME


TOFDATE@

Platform | x64, Win32
Purpose | To get the date in text form. The time given should be the number seconds since the beginning of 1970.
Syntax | CHARACTER (LEN=*) FUNCTION TOFDATE@(SECS)
Return value | TOFDATE@ returns the date in textual format based on time given in the form: "Friday January 29, 1993".


TOTIME@

Platform | x64, Win32
Purpose | To return the time in the form "HH:MM:SS".
Syntax | CHARACTER (LEN=*) FUNCTION TOTIME@(SECS) INTEGER (KIND=3) SECS
Return value | Returns the time corresponding to SECS.
See also | DATE_AND_TIME


Using MK32

The Silverfrost MK32 utility is similar to the UNIX MAKE program. Users who are familiar with MAKE should be able to use this utility with little or no assistance.

A "make" utility is a project manager. Any given project is assumed to be based on a number of inter-related files. These might include a file for the main program, various files for the subroutines, various "include" files, object files, libraries, and maybe a final executable file. These are assumed to be inter-dependent, in that a change in one file will have repercussions on other files. For example a change in an "include" file will affect any source file which uses that include file, this in turn will affect the resulting object files and so on.

The purpose of a "make" utility is to read a file that describes all of the inter-dependencies in a given project and update only those files that need to be updated. The updating is based on the given dependency relationships and also on the current date/time stamp for the files. Thus if file A is given to be dependent on file B and file A predates file B, then file A is updated.

Note that a "make" utility uses the date/time stamp that the operating system places on a file when it is saved. If the computer date/time is not functioning correctly then the utility is unlikely to have the desired effect.


Tutorial

In order to illustrate how MK32 works, we shall consider the following simple situation.

Suppose we have a project based initially on two files. The first file, called prog.f90, contains only a main program; the second sub.f90 contains all of the user-defined subroutines that are called from the main program. In all other respects, these files are assumed to be independent of each other and independent of any other user files.

The simplest way of calling the Silverfrost make utility is to type just MK32 at the command prompt. If you do this then the utility processes a file called makefile which the user places in the current directory. makefile contains dependency relationships and dependency rules (either explicit or implicit) for the current project.

Examples: 1 2 3 4 5 6 7 8


Example 1

This first example illustrates the use of explicit dependency relations.

In the project described above, makefile could contain:

prog.exe: prog.obj sub.obj
          slink prog.lnk

prog.obj: prog.f90
          ftn95 prog /check

sub.obj:  sub.f90
          ftn95 sub /check

This means that prog.exe depends on both prog.obj and sub.obj and that prog.exe is created by calling SLINK using prog.lnk as the linker script. For .NET you would use DBK_LINK instead.

In turn prog.obj depends on prog.f90 and prog.obj is created by calling FTN95 using prog.f90 with the /CHECK option. A similar dependency relationship and rule is used for sub.obj.

If sub.f90 only were changed (for example) then calling the utility would result in sub.f90 being recompiled (but not prog.f90). Then because prog.exe depends on sub.obj, the linking process is also carried out.


Example 2

A second approach is to use an implicit dependency relationship as illustrated here:

.SUFFIXES: .f90 .obj

.f90.obj:
          ftn95 $< /check

prog.exe: prog.obj sub.obj
          slink prog.lnk

The explicit dependency relation for prog.exe has not changed. The first line gives a list of extensions (separated by at least one space) for which implicit relations will be supplied. In this case one relation is given showing how ".obj" files are derived from ".f90" files.

The next line is an example of an implicit relation. In this case the relationship states that (in the absence of an explicit relation) a ".obj" file is dependent on a corresponding ".f90" file and that the object file is formed by calling FTN95 with the /CHECK option. "$<" represents the source filename (the dependency file name with its extension). In other words, we have now used one implicit relation in place of two explicit relations in Example 1.


Example 3

Our next example of a makefile illustrates a use for the TOUCH utility and takes the form:

.SUFFIXES: .f90 .obj

.f90.obj:
          ftn95 $< /check

prog.exe: prog.lnk
          slink prog.lnk

prog.lnk: prog.obj sub.obj
          touch prog.lnk

The TOUCH utility simply updates the date/time stamp of the given file. So here we are saying that prog.lnk depends on prog.obj and sub.obj but the content of prog.lnk does not need to be changed. The order of the two explicit relations is significant; prog.exe is the primary target and must come first.


Example 4

Now we take Example 3 one stage further:

.SUFFIXES: .f90 .obj .lnk .exe

.f90.obj:
          ftn95 $< /check

.lnk.exe:
          slink $<

prog.exe:

prog.lnk: prog.obj sub.obj
          touch prog.lnk

This includes an implicit relation which connects the linker script to the executable. The result is neither shorter nor simpler than Example 3 and so has little merit unless you also use a default.mk file (see Example 6).


Example 5

We now return to the form given in example 2 and provide a modification which illustrates the use of macros and comments:

# Example 5

.SUFFIXES: .f90 .obj

OBJFILES=prog.obj \
         sub.obj
T=prog

.f90.obj:
         ftn95 $< /check

$T.exe:  $(OBJFILES)
         slink $T.lnk

Characters after a "#" symbol on a given line are ignored so the first line is a comment. OBJFILES and T are macros. They represent constant character strings which re place expressions of the form $(. . .) within dependency relations. If the macro name consists of only one character then the parenthesis is not required. The backslash (\) character is used for continuation (suppressing the following carriage return/linefeed). The following macros are implicitly defined:

$@ | evaluates to the file name of the current target
$* | evaluates to the file name of the current target without its extension
$< | evaluates to the source filename in an implicit rule

In a macro assignment, spaces can be used on either side of the equals sign. Macro names are case sensitive although it is common to use only upper case letters. Also, it is possible to append a string to an existing name as follows:

OBJFILES=prog.obj
OBJFILES+= sub.obj

but note that the space before sub.obj is essential in this context.


Example 6

Our next example is similar to example 4 but illustrates the use of a file called default.mk. Create a file in the project directory called default.mk containing the implicit relations:

.SUFFIXES: .f90 .obj .lnk .exe

.f90.obj:
          ftn95 $< /check

.lnk.exe:
          slink $<

makefile now contains:

prog.exe:

prog.lnk: prog.obj sub.obj
          touch prog.lnk

MK32 automatically calls default.mk and uses it as a header.

You will find a file called default.mk in the compiler directory. This file can be copied to your project directory and customised to suit your particular project.

If you wanted to include something other than (or as well as) default.mk in your makefile then insert a line of the form:

include filename

There must be no spaces at the beginning of this line.


Example 7

Taking this one stage further we now include macros in default.mk:

.SUFFIXES: .f90 .obj .exe

OPTIONS=

OBJFILES=

.f90.obj:
         ftn95 $< $(OPTIONS)

.obj.exe:
         slink $(OBJFILES) -FILE:$@

This uses the command line form of SLINK which is not available with LINK77. makefile now contains:

OPTIONS=/check

OBJFILES=prog.obj sub.obj

prog.exe: $(OBJFILES)


Example 8

Our final example uses the same default.mk as in Example 7 but moves OPTIONS and a new macro called TARGET to the command line. makefile now contains:

OBJFILES=$(TARGET).obj sub.obj

$(TARGET).exe: $(OBJFILES)

and the command line takes the form:

MK32 TARGET=prog OPTIONS=/check

Macros that are defined on the command line replace any definitions that appear in the makefiles. Alternatively you could define TARGET and/or OPTIONS as DOS environment variables. Other items that can be added to the command line are given in Command line options.


Reference

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Command line options

-f filename | Use filename instead of the default file called makefile. A minus sign in place of filename denotes the standard input.
-d | Display the reasons why MK32 chooses to rebuild a target. All dependencies which are newer are displayed
-dd | Display the dependency checks in more detail. Dependencies which are older are displayed, as well as newer.
-D | Display the text of the makefiles as they are read in.
-DD | Display the text of the makefiles and default.mk .
-e | Let environment variables override macro definitions from makefiles. Normally, makefile macros override environment variables. Command line macro definitions always override both environment variables and makefile macros definitions.
-i | Ignore error codes returned by commands. This is equivalent to the special target .IGNORE:.
-n | No execution mode. Print commands, but do not execute them. Even lines beginning with an @ (see Rules below) are printed. However, if a command line is an invocation of MK32, that line is always executed.
-r | Do not read in the default file default.mk .
-s | Silent mode. Do not print command lines before executing them. This is equivalent to the special target .SILENT:.
-t | Touch the target files, bringing them up to date, rather than performing the rules to reconstruct them.
macro=value | Macro definition. This definition remains fixed for the MK32 invocation. It overrides any regular definitions for the specified macro within the makefiles and from the environment. It is inherited by subordinate MK32's but acts as an environment variable for these. That is, depending on the -e setting, it may be overridden by a makefile definition.


Makefiles

The first makefile read is default.mk, which can be located anywhere along the PATH. It typically contains pre-defined macros and implicit rules.

The default name of the makefile is makefile in the current directory. An alternative makefile can be specified using one or more -f options on the command line. Multiple '-f's act as the concatenation of all the makefiles in a left-to-right order.

The makefile(s) may contain a mixture of comment lines, macro definitions, include lines, and target lines. Lines may be continued across input lines by using backslash (\) at the end of a line.

Anything after a "#" is considered to be a comment. Completely blank lines are ignored.

An include line is used to insert the text of another makefile. It consists of the word "include" left justified, followed by spaces, and followed by the name of the file that is to be included at this line. Include files may be nested.


Macros

Macros have the form WORD=text. WORD is case sensitive although commonly upper case. Later lines which contain $(WORD) or ${WORD} will have this replaced by 'text'. If the macro name is a single character, the parentheses are optional. The expansion is done recursively, so the body of a macro may contain other macro invocations. Spaces around the equal sign are not relevant when defining a macro. Macros may be extended to by using the "+=" notation.


Special macros

MAKEFLAGS | This macro is set to the options (not macros) provided on the command line for MK32. If this is set as an environment variable, the set of options is processed before any command line options. This macro may be explicitly passed to nested calls to MK32, but it is also available to these invocations as an environment variable.
SUFFIXES | This contains the default list of suffixes supplied to the special target .SUFFIXES:. It is not sufficient to simply change this macro in order to change the .SUFFIXES: list. That target must be specified in your makefile.
$* | The base name of the current target (used in implicit rules).
$< | The name of the current dependency file (used in implicit rules).
$@ | The name of the current target.


Targets

The form of an explicit dependency rule is:

target [target] [. . .]: [source] [. . .]
[rule]
[. . .]

Here we have one or more target files, each separated by a space, and followed by a colon (there must be no spaces before the first target). Then we have zero or more dependent files followed by zero or more rules (see below), each on its own line preceded by at least one space (again the space is essential). See Example 2. The targets can be macros that expand to targets.

The colon that appears in a dependency rule does not interfere with a colon that appears in the path of a file (after the drive letter).

If a target is named in more than one target line, the dependencies and rules are added to form the target's complete dependency list and rule list.

The dependants are ones from which a target is constructed. They in turn may be targets of other dependants. In general, for a particular target file, each of its dependent files is 'made', to make sure that each is up to date with respect to its dependants.

The modification time of the target is compared to the modification times of each dependent file. If the target is older, one or more of the dependants have changed, so the target must be constructed. This checking is done recursively, so that all dependants of dependants etc. . . are up to date.

To reconstruct a target, MK32 expands macros and either executes the rules directly, or passes each to a shell or COMMAND.COM for execution.

For target lines, macros are expanded on input. On other lines macros are expanded at the point of implementation.


Special targets

.DEFAULT: | The rule for this target is used to process a target when there is no other entry for it, and no implicit rule for building it. MK32 ignores all dependencies for this target.
.DONE: | This target and its dependencies are processed after all other targets are built.
.IGNORE: | Non-zero error codes returned from commands are ignored. Encountering this in a makefile is the same as specifying -i on the command line.
.INIT: | This target and its dependencies are processed before any other targets are processed.
.SILENT: | Commands are not echoed before executing them. Encountering this in a makefile is the same as specifying -s on the command line.
.SUFFIXES: | The suffixes list for selecting implicit rules. Specifying this target with dependants adds these to the end of the suffixes list. Specifying it with no dependants clears the list. In order to add dependants to the head of the list, use the form: .SUFFIXES: .abc $(SUFFIXES)


Rules

A line in a makefile that starts with a TAB or SPACE is a rule. This line is associated with the most recently preceding dependency line. A sequence of these may be associated with a single dependency line. When a target is out of date with respect to a dependent, the sequence of commands is executed. Rules may have any combination of the following characters to the left of the command:

  • @ will not echo the command line.

  • - MK32 will ignore the exit code of the command, i.e. the ERRORLEVEL of MSDOS. Without this, MK32 terminates when a non-zero exit code is returned.

  • + MK32 will use COMMAND.COM to execute the command. If the '+' is not attached to a shell line, but the command is a DOS command or if redirection is used (<, |, >), the shell line is passed to COMMAND.COM anyway.


Implicit rules

The form of an implicit rule is:

.source_extension.target_extension:
[rule]
[. . .]

Here we have a dot (no spaces before it) followed by the extension for the source file (one, two or three characters) then a dot followed by the extension for the target file and then a colon and then a new line and at least one space. Optional rules then follow on separate lines just as in an explicit dependency. See Example 3.

Implicit rules are linked to the .SUFFIXES: special target. Each entry in .SUFFIXES defines an extension to a filename which may be used to build another file. The implicit rules then define how to build one file from another. These files are related, in that they must share a common base name, but have different extensions.

If a file that is being made does not have an explicit target line, a search is made for an implicit rule. Each entry in the .SUFFIXES: list is combined with the extension of the target, to get the name of an implicit target. If this target exists, it gives the rules used to transform a file with the dependent extension to the target file. Any dependants of the implicit target are ignored.


Files

makefile | Current version(s) of make description file.
default.mk | Default file for user-defined targets, macros, and implicit rules.


Diagnostics

MK32 returns an exit status of 1 when it halts as a result of an error. Otherwise it returns an exit status of 0.

Here is a list of the error messages:

Badly formed macro

A macro definition has been encountered which has incorrect syntax. Most likely, the name is missing.

Cannot open file

The makefile indicated in an include directive was not found or was not accessible.

Don't know how to make target

There is no makefile entry for target, none of MK32's implicit rules apply, and there is no .DEFAULT: rule.

Improper macro

An error has occurred during macro expansion. The most likely error is a missing closing bracket.

Rules must be after target

A makefile syntax error, where a line beginning with a SPACE or TAB has been encountered before a target line.

Too many options

MK32 has run out of allocated space while processing command line options or a target list.


Samples

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Win32 only

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Clearwin+ Samples

For code examples of Clearwin+ please see the FTN95 Examples folder within your Documents folder.


Visual C Interoperability

Visual C Interoperability - Calling an FTN95 DLL from Visual C++

Topics Covered

Calling a Win32 DLL from unmanaged Visual C++
Exporting routines from a Win32 Fortran DLL
Debugging a FTN95 Win32 DLL within Visual Studio .NET

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\Win32\VisualCInteroperability

A set of shortcuts has also been provided in the start menu.

This example demonstrates the use of an FTN95 Win32 DLL called from unmanaged Visual C++. This examples requires the use of the Microsoft Visual C compiler, cl.exe. This is installed by Visual Studio .NET. To build this example the solution file can be loaded (VisualCInteroperability.sln) or the project can be built from the command line by using the supplied batch files present in the solution folder. To compile this application from the command line you should ensure that the Visual C++ compiler is available for use. This document refers to the creation of this project using Microsoft Visual Studio .NET, for command line usage much of this document applies, but please see the batch files for command syntax details. The Visual Studio .NET environment batch file vsvars32.bat should have been run for command line usage.

This sample assumes the __cdecl calling convention is used.

For an example of calling a Visual C++ Win32 DLL from Silverfrost Fortran see the VisualCInteroperability2 example.

Example Creation

This solution makes use of two language projects, an FTN95 Application Extension and a Visual C++ Win32 Console Application.

To create this solution two projects need to be created. First create the FTN95 Application Extension solution by selecting New Project from the File menu and choose a FTN95 Application Extension project. Name the project as desired or accept the default. When the project has loaded the configuration should be changed from .NET to Win32 if this is not already set. This can be done by selecting the project type combo box in the toolbar within Visual Studio .NET.

Enter the Fortran code as shown in the Code Features section below.

Select Properties from the Project menu. When creating a Fortran Application Extension project the default file type produced by a build is a DLL. As this project is to be used with Microsoft Visual C++ a .lib file has to be produced. In the project properties dialog, navigate to Compiler Options->Miscellaneous. In the Output Options section, select Output filetype and change the extension, using the dropdown available, to LIB as shown in the following image.

Select Linker Options in the same dialog and set Export all to Yes. This ensures that any routines that are included in the library produced by the project will be exported and callable from Visual C++. If only select routines need to be exported then a custom link script can be passed to the linker by creating a script and passing the script to the linker by specifying the script file in Extra linker options. A short description of how to do this for this project is shown below.

Using a Custom Link Script

If more options are required to be passed to the linker than are provided in the project configuration dialog then a custom link script can be provided. A blank text file should be created in the project directory and named as appropriate. For this example the file will be called extras.slink. To export specific routines from a DLL instead of all routines by use of Export all then specific Export commands can be passed to the linker. To export four specific routines from the code below the following linker script could be used:

export SUBSIMPLE
export SUBARGUMENTS
export SUBSTRING
export SUBARRAY

These exported routines can be accessed from the C program in the same way as with the use of Export all.

It is possible to provide alternate export names for the routines by the use of the following syntax within the script file:

export SUBSIMPLE=_SubSimple

This routine is then exported as _SubSimple and should be treated as such within the C program.

To specify the script file to the linker, the name of the script file should be prefixed with '$' and added to Linker Options->Extra linker options as shown in the following image. If specific exports are used as shown then Export all should also be set to No. Note that if the linker script is not resident within the project directory then a full path or a path relative to the project directory should be specified.

For more information about custom link scripts and the commands that can be used with them please see the following topics.

Script or command files
Interactive mode

Example Creation (continued)

When the Fortran project has been created, select Build from the Build menu. In the project output directory two files, a .lib and a .dll should have been created. The .lib file will be used by the Visual C++ project at build time, and the DLL will be used at runtime.

To create the Visual C++ project, select New Project from the File menu and select a Win32 Console Project from Visual C++ Projects. Name the project as appropriate and create the project. You should add the new project to the existing solution.

Enter the C code as shown in the Code Features section below.

Two changes need to be made to the Visual C++ project settings. Select Properties from the Project menu for the C++ project. Navigate to Linker->Input and select Additional Dependencies. The .lib file created by the Fortran project should be specified here. A path should be specified, using either a full or relative path. For this example the Fortran Application Extension and Visual C++ Project are in seperate parallel directories and therefore (in Debug/Win32 configuration) the path to the .lib file would be:

..\FortranApplicationExtension1\Debug\Win32\FortranApplicationExtension1.lib

Now we have ensured that the Visual C++ program has enough information to compile and link with the Fortran Application Extension, we need to ensure that the Fortran DLL is available for the Visual C++ program at runtime. This is accomplished by use of a Post-Build Event. When the Visual C++ program runs the Fortran Application Extension DLL needs to be available either in a local directory or on the system path. To make the DLL available locally a custom event can be used to copy the DLL from the Fortran output directory to the Visual C++ output directory. Still within the project properties navigate to Build Events->Post-Build Event and select Command Line. Enter the following command:

copy ..\FortranApplicationExtension1\Debug\Win32\FortranApplicationExtension1.dll $(OutDir)

Ensure that the solution build order is configured so that the Fortran Application Extension is built before the Visual C++ project. The entire solution can now be built. The solution should also be runnable from the Debug menu. Ensure that the Visual C++ project is set as the startup project.

Code Features

This example demonstrates calling an FTN95 from Visual C++. A variety of routines are called, with different arguments and return types, array passing and function pointers are demonstrated. Explanations are provided after each code snippet below.

Fortran Source

!---------------------------------------------------------------
! No arguments
!---------------------------------------------------------------
SUBROUTINE SubSimple
PRINT *,"Simple subroutine called"
END SUBROUTINE

!---------------------------------------------------------------
! Simple Integer and Real arguments
!---------------------------------------------------------------
SUBROUTINE SubArguments(i,x)
INTEGER(KIND=3) :: i
REAL(KIND=1) :: x
PRINT *,"SubArguments called with values:"
PRINT *,"i = ",i
PRINT *,"x = ",x
END SUBROUTINE

!---------------------------------------------------------------
! String arguments
!---------------------------------------------------------------
SUBROUTINE SubString(s1,s2)
CHARACTER(LEN=*) :: s1
CHARACTER(LEN=*) :: s2
PRINT *,"SubString called with two strings"
PRINT *,s1,s2
END SUBROUTINE

The above are three simple Fortran subroutines that accept different arguments. When passing the strings to the Fortran routines, as demonstrated by the last example, the lengths of the two strings are passed as extra arguments to the Fortran, see the C code for full details of this.

!---------------------------------------------------------------
! Array arguments
!---------------------------------------------------------------
SUBROUTINE SubArray(arr)
INTEGER(KIND=3) :: arr(:)
PRINT *,"SubArray called with array"
PRINT *,ARR
END SUBROUTINE

!---------------------------------------------------------------
! Call a routine with a function pointer from C
!---------------------------------------------------------------
SUBROUTINE SubFunc(func)
EXTERNAL :: func
CALL func(34)
END SUBROUTINE

The first of these two routines accepts an array from the C code. The size of the array is passed, by value from the C as an extra argument. The second subroutine illustrates the passing of a function pointer as an argument. func is a function pointer passed from C and then called from within the Fortran code.

!---------------------------------------------------------------
! An Integer returning Function
!---------------------------------------------------------------
INTEGER(KIND=3) FUNCTION FuncInteger()
FuncInteger = 347
END FUNCTION

!---------------------------------------------------------------
! A Real returning Function
!---------------------------------------------------------------
REAL(KIND=1) FUNCTION FuncReal()
FuncReal = 2.46677
END FUNCTION

The code above shows two Fortran functions returning different types.

For details of type differences between Fortran and C see the following topic:

Basic data types

Visual C++ Code

//----------------------------------------------------------------------
// Declare the external Fortran routines
//----------------------------------------------------------------------
extern "C" void SUBSIMPLE();
extern "C" void SUBARGUMENTS(int* i, float* x);
extern "C" void SUBSTRING(char* s1, char* s2, int i, int j);
extern "C" void SUBARRAY(int* arr, int size);
extern "C" void SUBFUNC(void* p);
extern "C" int FUNCINTEGER();
extern "C" float FUNCREAL();

These declarations should be provided to specify the Fortran routines that are to be called. Two cirumstances should be considered. If Export all was specified from the Fortran then the names should match those in the Fortran code but should be all upper-case, regardless of the case within the Fortran code. If explicit export statements have been provided by a link script then the names should match those provided in the link script. extern "C" should be specified to prevent Visual C++ from modifying the names of the routines in any way.

//----------------------------------------------------------------------
// Constants
//----------------------------------------------------------------------
#define ARRAY_SIZE 10

//----------------------------------------------------------------------
// Calls an FTN95 subroutine with no arguments
//----------------------------------------------------------------------
void CallSubroutineSimple()
{
  SUBSIMPLE();
}

//----------------------------------------------------------------------
// Calls an FTN95 subroutine with simple (int and float) arguments
//----------------------------------------------------------------------
void CallSubroutineArguments()
{
  int i = 3;
  float x = 4.6;
  SUBARGUMENTS(&i,&x);
}

//----------------------------------------------------------------------
// Calls an FTN95 subroutine with string arguments. The lengths of the
// two string arguments are passed by value as extra arguments.
//----------------------------------------------------------------------
void CallSubroutineString()
{
  char* chStr1 = "Hello ";
  char* chStr2 = "World...";
  SUBSTRING(chStr1,chStr2,strlen(chStr1),strlen(chStr2));
}

//----------------------------------------------------------------------
// Calls an FTN95 subroutine with an int array - note the size is passed
// as an extra argument in order to facilitate assumed size within the
// Fortran code. Extra arguments may be passed by value as shown, actual
// arguments must be passed by reference.
//----------------------------------------------------------------------
void CallSubroutineArray()
{
  int arr[ARRAY_SIZE] = {1,2,3,4,5,6,7,8,9,0};
  SUBARRAY(arr,ARRAY_SIZE);
}

The first routines above demonstrate calling FTN95 DLL subroutines with no arguments and with simple arguments. Note that arguments are always passed by reference.

The second two routines demonstrate calling subroutines that require extra arguments to be passed along with the actual arguments. These two subroutines accept assumed length character arguments and an assumed size array. The lengths/sizes of these arguments should be passed from the C as extra arguments on the end of the argument list, by value and in the order in which the arguments requiring extra arguments are passed.

//----------------------------------------------------------------------
// Calls an FTN95 function returning an int
//----------------------------------------------------------------------
void CallFuncInteger()
{
  int ret = FUNCINTEGER();
  printf("Return from FUNCINTEGER: %d\n",ret);
}

//----------------------------------------------------------------------
// Calls an FTN95 function returning a float
//----------------------------------------------------------------------
void CallFuncReal()
{
  float ret = FUNCREAL();
  printf("Return from FUNCREAL: %f\n",ret);
}

The above demonstrates calling functions in the Fortran DLL.

//----------------------------------------------------------------------
// Utility function used by CallSubroutineFunc
//----------------------------------------------------------------------
void FunctionPointer(int* i)
{
  printf("FunctionPointer called with i=%d\n",*i);
}

//----------------------------------------------------------------------
// Calls an FTN95 function with a function pointer argument
//----------------------------------------------------------------------
void CallSubroutineFunc()
{
  void (*pFunc) (int*);
  pFunc = FunctionPointer;
  SUBFUNC(pFunc);
}

The above routines are used to pass a function pointer to the Fortran. Within the Fortran the argument is specified as EXTERNAL.

Debugging an FTN95 DLL within Visual Studio .NET

Normally, to run this example the Visual C++ Project should be set as the startup project. To debug the Fortran DLL we need to go through extra steps as mixed language debugging with FTN95 and Visual C++ is only available in .NET configuration.

In order to debug the Fortran DLL the following steps need to be taken. Firstly, set the Fortran Application Extension as the startup project by right clicking the project in the Solution Explorer and selecting Set as StartUp Project. Enter the properties dialog for the Fortran Application Extension and select the Miscelleneoustab. Enter the full path to the Visual C++ Exe. Any time a debug target other than the main project output for a project is required then the full path should be entered. See the following image.

Click OK. Breakpoints can now be set inside the Fortran DLL and the debugger will break when execution hits these points. Alternatively Debug->Step Into can be used to break at the first executable statement that is reached in the Fortran DLL.


Visual C Interoperability

Visual C Interoperability - Calling a Visual C++ DLL from FTN95

Topics Covered

Calling a Visual C++ DLL from FTN95
Exporting routines from a Win32 Visual C++ DLL

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\Win32\VisualCInteroperability2

A set of shortcuts has also been provided in the start menu.

This example demonstrates the use of a Visual C++ DLL called from unmanaged FTN95 code. This examples requires the use of the Microsoft Visual C compiler, cl.exe. This is installed by Visual Studio .NET. To build this example the solution file can be loaded (VisualCInteroperability2.sln) or the project can be built from the command line by using the supplied batch files present in the solution folder. To compile this application from the command line you should ensure that the Visual C++ compiler is available for use. This document refers to the creation of this project using Microsoft Visual Studio .NET, for command line usage much of this document applies, but please see the batch files for command syntax details. The Visual Studio .NET environment batch file vsvars32.bat should have been run for command line usage.

This sample assumes the __cdecl calling convention is used.

For an example of calling a Win32 FTN95 DLL from Visual C++ see the VisualCInteroperability example.

Example Creation

This solution makes use of two language projects, an FTN95 Application and a Visual C++ Win32 DLL.

To create this solution two projects need to be created. First create the Visual C++ DLL project by selecting New Project from the File menu and selecting a Win32 Console Project from the Visual C++ Projects node of the project creation dialog.

Enter the C++ code as shown in the Code Features section below.

When the Visual C++ project has been created, select Build from the Build menu. In the project output directory two files, a .lib and a .dll should have been created. The .dll file can be used directly from the FTN95 application.

To create the FTN95 project, select New Project from the File menu and select a FTN95 Application from FTN95 Projects. Name the project as appropriate and create the project. You should add the new project to the existing solution.

Enter the Fortran code as shown in the Code Features section below.

You should add a reference to the Visual C++ Project from the Fortran project by selecting Add Reference when right clicking on the project node. Select the Projects tab and add a reference to the Visual C++ project. Adding the reference ensures that the DLL is passed to the Silverfrost linker, SLINK.

Now we have ensured that the FTN95 program has enough information to compile and link with the Visual C++ DLL, we need to ensure that the Visual C++ DLL is available for the FTN95 program at runtime. As we have added a reference to the DLL, this has the effect of ensuring that a copy of the DLL is made and placed with the Fortran application at build time. Ensure that the Fortran Application is set as the startup project.

Code Features

This example demonstrates calling a Visual C++ DLL from Fortran. A variety of routines are called, with different arguments and return types and array passing. Explanations are provided after each code snippet below.

Visual C++ Code

#include "stdafx.h"
#include <stdio.h>
//----------------------------------------------------------------------
// This is here for convienience, a .def file could also be used or
// /EXPORT on the linker command line
//----------------------------------------------------------------------
#define DllExport __declspec(dllexport)

//----------------------------------------------------------------------
// Defines the main entry point
//----------------------------------------------------------------------
BOOL APIENTRY DllMain( HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved )
{
return TRUE;
}

//----------------------------------------------------------------------
// Defines and exports a simple function, that accepts no arguments and
// returns void.
//----------------------------------------------------------------------
extern "C" DllExport void _FunctionSimple()
{
  printf("%s\n", "_FunctionSimple called");
}

//----------------------------------------------------------------------
// Defines and exports a function that accepts two arguments,
// both of these arguments are passed by value, Returns void.
//----------------------------------------------------------------------
extern "C" DllExport void _FunctionArgumentsValue(int i, double x)
{
  printf("%s%d%s%f\n",
         "_FunctionArgumentsValue called with arguments: ",
         i,", ",x);
}

//----------------------------------------------------------------------
// Defines and exports a function that accepts two arguments,
// both of these arguments are passed by reference. They are modified in
// the C routine and then printed out in the calling Fortran routine.
// Returns void.
//----------------------------------------------------------------------
extern "C" DllExport void _FunctionArgumentsReference(int* i, double* x)
{
  printf("%s%d%s%f\n",
         "_FunctionArgumentsReference called with arguments: ",
         *i,", ",*x);
  *i = 6;
  *x = 4.776;
}

//----------------------------------------------------------------------
// Defines and exports a function that accepts no arguments and
// returns an int. This function would be implemented in the just the
// same way for float/long etc,
//----------------------------------------------------------------------
extern "C" DllExport int _FunctionSimpleInt()
{
  printf("%s\n",
         "_FunctionSimpleInt called");
  return 9;
}

//----------------------------------------------------------------------
// Defines and exports a function that accepts an array and returns a
// float.
//----------------------------------------------------------------------
extern "C" DllExport float _FunctionArray(int arr[])
{
  printf("%s\n",
         "_FunctionArray called with array contents:");
  for (int i=0;i<10;++i)
  {
    printf("%d ",arr[i]);
  }
  printf("\n");
  return .7;
}

The code above is standard Visual C++ code. extern "C" has been used to prevent name mangling of the routines.

Fortran Source

PROGRAM MainProgram

!---------------------------------------------------------------
! Declare the C routines we wish to call
!---------------------------------------------------------------
C_EXTERNAL FunctionSimple "_FunctionSimple"
C_EXTERNAL FunctionArgumentsValue "_FunctionArgumentsValue" (VAL,VAL)
C_EXTERNAL FunctionArgumentsReference "_FunctionArgumentsReference" (REF,REF)
C_EXTERNAL FunctionSimpleInt "_FunctionSimpleInt" : INTEGER
C_EXTERNAL FunctionArray "_FunctionArray" (REF) : REAL

The routines above illustrate the syntax for declaring routines contained in external DLL's. For more information about the syntax of these declarations see the following topic.

Calling C/C++ from FTN95

INTEGER i
INTEGER arr(10)
REAL x
i = 1
x = 3.142

!
! Call a simple function
!
CALL FunctionSimple()

!
! Call a function with simple arguments by value
!
CALL FunctionArgumentsValue(1,4.66)

!
! Call a function with simple arguments by reference
!
CALL FunctionArgumentsReference(i,x)
PRINT *,"Value of i after call: ",i
PRINT *,"Value of x after call: ",x

!
! Call a function returning an integer
!
i = FunctionSimpleInt()
PRINT *,"Value of i after call: ",i

!
! Call a function returning a float and accepting an integer array
!
DO j=1,10
  arr(j) = j
END DO
x = FunctionArray(arr)
PRINT *,"Value of x after call: ",x

END PROGRAM

For details of type differences between Fortran and C see the following topic:

Basic data types


.NET only

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Mandelbrot Sample

Topics Covered

Calling Fortran from other .NET languages
Passing .NET objects to Fortran
Calling .NET methods from Fortran

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\NET\Mandelbrot

A set of shortcuts has also been provided in the start menu.

This example demonstrates many features of FTN95 for .NET and .NET language interoperabilty. A C# Windows Application makes use of a FTN95 for .NET assembly which makes calls to the .NET Framework to perform drawing operations.

This program requires the Microsoft .NET Framework to be installed in order to compile and run it. You can compile this example program either in Microsoft Visual Studio .NET or from the command line using the supplied batch files.

To compile from Microsoft Visual Studio .NET you just need to load the supplied solution file (Mandelbrot.sln), then choose Build Solution from the Build menu. You can now run the program under Debug mode by pressing F5.

To compile from the command line you can use either of the two batch files included in the Mandelbrot directory. Run builddbg.bat to create a debug build of the program in the Mandelbrot\bin\Debug directory, or run buildrel.bat to create a release build of the program in the Mandelbrot\bin\Release directory.

If compiling this application from the command line you should ensure that the .NET Framework directory is on the system PATH. Running the FTN95 for Microsoft .NET Command Prompt from the start menu will ensure that this is set up correctly.

Example Creation

This example makes use of two languages. A C# Windows Application and an FTN95 Fortran Application Extension project.

To create the Fortran Application Extension project, select New Project from the File menu. One file will be added to the project when it is created. This project uses functions that are available in Windows.System.Forms.dll, you should add this as a reference to the project using Add Reference from the References node. Enter the code below into the source file. This project can now be built using the Build command from the project menu.

To create the C# application, select New Project from the File menu, name the application if desired or accept the default. From the Toolbox add a PictureBox control and a Button control. Double-click the Button control to add an event handler for that button. Add the C# code as shown below. Because the C# application makes a call into the Fortran Application Extension you need to add a reference to the Fortran project. Do this by selecting Add Reference from the References node within the C# application and selecting the Fortran project.

Code Features

This example demonstrates calling a Fortran assembly from C# and passing .NET objects from the C# application. Methods of these objects are then called by the Fortran code to perform actions on the C# form.

The Fortran source is examined in more detail below.

Source Code

Fortran Source

!-----------------------------------------------------
! Module NetDeclarations contains declarations of .NET
! methods called by this example
!-----------------------------------------------------
MODULE NetDeclarations
  OBJECT("System.Drawing.Bitmap") :: bitmap
  OBJECT("System.Windows.Forms.PictureBox") :: picturebox
  ASSEMBLY_EXTERNAL(name="System.Drawing.Bitmap.SetPixel") :: bitmapSetPixel
  ASSEMBLY_EXTERNAL(name="System.Windows.Forms.PictureBox.Update") :: pictureboxUpdate
  ASSEMBLY_EXTERNAL(name="System.Windows.Forms.PictureBox.Invalidate") :: pictureboxInvalidate
  ASSEMBLY_EXTERNAL(name="System.Drawing.Color.FromArgb") :: colorFromArgb
  INTEGER :: r(256)
  INTEGER :: g(256)
  INTEGER :: b(256)
END MODULE

!-----------------------------------------------------
! Setup .NET objects
!-----------------------------------------------------
SUBROUTINE SetupMandelbrot_(bitmap_,picturebox_)
  USE NetDeclarations
  ASSEMBLY_INTERFACE(name="SetupMandelbrot")
  OBJECT("System.Drawing.Bitmap") :: bitmap_
  OBJECT("System.Windows.Forms.PictureBox") :: picturebox_
  INTEGER :: i
  bitmap = bitmap_
  picturebox = picturebox_
  DO i=1,192
    r(i) = MIN(255, (i*4/3) +192)
    g(i) = MIN(255, (i*4/3) +64)
    b(i) = MIN(255, (i*4/3))
  ENDDO
  DO i=1,64
    r(192+i) = MIN(255, (65-i)*4 + 192/3)
    g(192+i) = MIN(255, (65-i)*4 + 64/3)
    b(192+i) = MIN(255, (65-i)*4)
  ENDDO
END SUBROUTINE

This module defines a TYPE that will be used by main routine and also declares ASSEMBLY_EXTERNAL aliases for several .NET methods that are used by the main routine. More information about ASSEMBLY_EXTERNAL can be found here. Details of a routine to setup a color matrix for use later in the program are also provided.

!-----------------------------------------------------
! Draws the image on the Bitmap object we have been
! passed in
!-----------------------------------------------------
SUBROUTINE DrawMandelbrot_(zoom,offset_x,offset_y,size)
  USE NetDeclarations
  ASSEMBLY_INTERFACE(name="DrawMandelbrot")

.NET Objects are passed to the Fortran routine as bitmap and picturebox. Their full type can be seen in the OBJECT statements in the code above. An external alias is provided for the routine by use of an ASSEMBLY_INTERFACE statement. For more information see:

.NET Objects
Calling Fortran from other .NET languages

  INTEGER i,j,k,size,iter
  DOUBLE PRECISION :: zoom
  DOUBLE PRECISION :: offset_x,offset_y
  DOUBLE PRECISION :: zr,cr,zi,ci,zis,zrs
  i = 1
  j = 1
  iter = size
  size = size/2
  offset_x = offset_x-200.0+size
  offset_y = offset_y-120.0+size
  DO WHILE (i < iter+1)
    j = 1
    DO WHILE (j < iter+1)
      cr = ((i-size)/zoom + offset_x)/100.0
      ci = ((j-size)/zoom + offset_y)/100.0
      zr = 0.
      zi = 0.
      DO k=1,255
        zis = zi*zi
        zrs = zr*zr
        zi = 2*zr*zi+ci
        zr = zrs-zis+cr
        IF ((zrs+zis)>4.) EXIT
      ENDDO

The above code snippet is standard Fortran

      CALL bitmapSetPixel(bitmap,i-1,j-1,colorFromArgb(r(k),g(k),b(k)))
      j = j+1
    ENDDO
    i = i+1
  ENDDO
  CALL pictureboxInvalidate(picturebox)
  CALL pictureboxUpdate(picturebox)
END

The code above demonstrates the calling of .NET instance methods. The methods called do not return a value and so can be called as a SUBROUTINE. The aliases provided in the module are used and any arguments that are required are passed to the routine. Note that as these are instance methods the object that the method is being called on has to be passed as the first argument to the method.

This Fortran source should be compiled as a Fortran Application Extension and added to the following C# Application as a reference.

C# Source

//
// Automatically generated code removed
//

private void SetupBitmap()
{
  bitmap1 = new Bitmap(255,255);
  pictureBox1.Image = bitmap1;
}

private void DrawMandlebrot()
{
  MandelbrotBackend.DrawMandelbrot(zoom, x, y, pictureBox1.Height-1);
}

private void SetupMandelbrot()
{
  MandelbrotBackend.SetupMandelbrot(bitmap1, pictureBox1);
}

private void Form1_Load(object sender, System.EventArgs e)
{
  SetupBitmap();
  SetupMandelbrot();
  DrawMandlebrot();
}

private void Form1_KeyDown(object sender, System.Windows.Forms.KeyEventArgs e)
{
  if (e.KeyCode == Keys.Down)
    y += 20/zoom;
  else if (e.KeyCode == Keys.Up)
    y -= 20/zoom;
  else if (e.KeyCode == Keys.Left)
    x -= 20/zoom;
  else if (e.KeyCode == Keys.Right)
    x += 20/zoom;
  else if (e.KeyCode == Keys.PageUp)
    zoom *= 1.25;
  else if (e.KeyCode == Keys.PageDown)
    zoom /= 1.25;
  DrawMandlebrot();
}


Calculator Sample

Topics Covered

Calling Fortran from other .NET languages
.NET Exception handling within Fortran

Introduction

Default Location:

C# - <Documents Folder>\FTN95 Examples \NET\ FortranCalculator\CS
VB .NET - <Documents Folder>\FTN95 Examples \NET\ FortranCalculator\VB

Note: FortranCalculator has both a Visual Basic .NET (VB) and a C# implementation.

This example program is a basic calculator designed to demonstrate the multi language capabilities of FTN95 and Microsoft .NET. The user interface is completely designed with a Microsoft .NET language using Microsoft Visual Studio. The backend of the program that performs calculations is written in Fortran (and compiled with FTN95). While not very complex, this serves the purpose of showing how to create a multi language program.

To build this program for yourself you will require the Microsoft .NET Framework to be installed.

We recommend you use Microsoft Visual Studio .NET to examine and compile this example program, although we have provided a batch file for easy compiling from the command line.

To compile under Microsoft Visual Studio .NET you should load the solution file (VB_Calculator.sln or CS_Calculator.sln) in the project directory. To load the solution select File -> Open Solution, navigate to the solution file and open it. To build the solution, navigate to the Build menu and select Build Solution.

Once you have built the program you can run it in debug mode using 'F5' or the executable can be found in the Debug\NET subdirectory of the project folder and can be run directly.

To compile from the command line you can run the supplied builddbg.bat or buildrel.bat (Debug or Release) in the project directory. The executables will be placed in bin\Debug and bin\Release respectively. They can be run by simply double clicking the executable.

Example Creation

To create a multi language program such as this from scratch using Microsoft Visual Studio .NET you need to create two projects, one for each language. Since we are making a C#/VB windows application and calling functions from Fortran we should make the Fortran project output a DLL. To create this project, go to the File menu and select New Project. Select the FTN95 Projects branch, Choose FTN95 Application Extension from the available projects and type an appropriate name for the project then press OK.

One source file for the project is created automatically, if you needed more than one you could create them by selecting Add New Item from the Project menu. Enter the Fortran code as shown below, using the new ASSEMBLY_INTERFACE directive as shown in the example project to give a name to each subroutine/function. This becomes the externally (case sensitive) callable name of the routine containing the directive.

A new C#/VB project should now be added to the solution using Add -> New Project. Select Windows Application from the Visual C# Projects branch or the Visual Basic Projects branch and enter an appropriate name. After pressing OK the C# project is created and an empty dialog is shown. You can add new window controls to this dialog and add relevant C#/VB code for each. See the C#/VB documentation for more details on this.

Before you can call the Fortran code from your other project you must add a reference to the Fortran project to the C#/VB project.

The default namespace has been changed to FTN95Calculator to illustrate the use of the linker switch /CONTAINING_CLASS. Specification of this switch will change the default classname to that specified. Any routines contained within the assembly should then be qualified with the new classname. By default the classname is the project name. To change the default class name the following option should be set within Visual Studio .NET.

To call a subroutine or function from the Visual Basic .NET code you need to add the imported classname to the Project Imports list under Imports in the Visual Basic .NET project properties. Then make the call with that name as a class name, and the name you gave to the subroutine/function with the ASSEMBLY_INTERFACE directive as the method name, i.e. ClassName.methodName (arguments).

The arguments should be equivalent data types, e.g. real*8 is equivalent to double.

Note that in the code below, all function/subroutine names have different names than those provided by the ASSEMBLY_INTERFACE directive. This is to avoid any ambiguities when using the generated assembly from a case insensitive language such as Visual Basic .NET. Another approach to this problem is to use the /INTERFACE_ONLY switch on the linker command line. If using FTN95 within Visual Studio .NET then as of version 4.5 this option is on by default.

Code Features

This example uses a new keyword for FTN95 .NET - 'THROW'. When given a character string parameter this keyword will throw a UserException in the normal Microsoft .NET manner, which can then be caught by the calling code. Fortran is also capable of catching a thrown exception itself, using a similar syntax to C#.

Fortran Source

real*8 function add_ (x, y)
  assembly_interface(name="Add")
  real*8 x, y
  add_ = x + y
end

real*8 function subtract_ (x, y)
  assembly_interface(name="Subtract")
  real*8 x, y
  subtract_ = x - y
end

real*8 function multiply_ (x, y)
  assembly_interface(name="Multiply")
  real*8 x, y
  multiply_ = x * y
end

real*8 function divide_ (x, y)
  assembly_interface(name="Divide")
  real*8 x, y
  divide_ = x / y
end

real*8 function sqroot_ (x)
  assembly_interface(name="SqRoot")
  real*8 x
  object ("System.Exception") calculatorException
  calculatorException = new@ ("System.Exception")
  if (x < 0) throw calculatorException
  sqroot_ = sqrt(x)
end

real*8 function log_e_ (x)
  assembly_interface (name="Log")
  real*8 x
  object ("System.Exception") calculatorException
  calculatorException = new@ ("System.Exception")
  if (x < 0) throw calculatorException
  log_e_ = log(x)
end

real*8 function piValue_ ()
  assembly_interface (name="PiValue")
  piValue_ = 3.1415926535897932384626433832795
end

The code above illustrates the use of the ASSEMBLY_INTERFACE directive to provide case sensitive externally callable names for the functions/subroutines contained within the file.

Basic use of Fortran exception handling is also demonstrated in the above file. Within functions sqroot_ and log_e_ exception objects are created which are then conditionally thrown. The thrown exception should then be caught by any routine on the call stack. If no such catch exists then the exception will be presented as a program error. In this example the calling routine catches the thrown exception as can be seen in the following Visual Basic .NET code.

Visual Basic .NET source

Note that some of the non-interop code has been removed for brevity. Full source can be found in the actual example. C# source can also be found within the example directories.

Private Sub sqrtButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles sqrtButton.Click
  Try
    checkFlagState()
    DB1 = CDbl(textBox.Text)
    result = FTN95Calculator.SqRoot(DB1)
    res = (CStr(result))
    textBox.Text = res
  Catch
    ex As Exception When DB1 < 0
      Beep()
  End Try
End Sub

Private Sub piButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles piButton.Click
   checkFlagState()
  result = FTN95Calculator.PiVal()
  res = (CStr(result))
  textBox.Text = res
End Sub

Private Sub logButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles logButton.Click
  Try
    checkFlagState()
    DB1 = CDbl(textBox.Text)
    result = FTN95Calculator.Log(DB1)
    res = (CStr(result))
    textBox.Text = res
  Catch ex As Exception When DB1 < 0
    Beep()
  End Try
End Sub

Private Sub equalsButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles equalsButton.Click
  DB2 = CDbl(textBox.Text)
  Select Case opcode
    Case "add"
      result = FTN95Calculator.Add(DB1, DB2)
      eqpr = True
    Case "subtract"
      result = FTN95Calculator.Subtract(DB1, DB2)
      eqpr = True
    Case "multiply"
      result = FTN95Calculator.Multiply(DB1, DB2)
      eqpr = True
    Case "divide"
      result = FTN95Calculator.Divide(DB1, DB2)
      eqpr = True
    Case Else
      result = DB2
  End Select
  res = (CStr(result))
  textBox.Text = res
  needini = True
End Sub

Notable features in the code above is the calling technique, where the name specified to the Fortran linker through the /CONTAINING_CLASS switch is used to call the Fortran routines. Several of the calls are also surrounded by Try...Catch. The Fortran code can throw exceptions and this illustrates the catching of such exceptions. For more information related to this example please see the following topics.


Message Box Sample

Topics Covered

Calling static .NET methods from Fortran

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\NET\MessageBox

A set of shortcuts has also been provided in the start menu.

This simple example demonstrates using windows forms from FTN95 using the .NET framework. It shows a message box on screen saving the result of the call in a DialogResult object - another windows forms .NET class.

This program requires the Microsoft .NET Framework to be installed in order to compile and run it. You can compile this example program either in Microsoft Visual Studio .NET or from the command line using the supplied batch files.

To compile from Microsoft Visual Studio .NET you just need to load the supplied solution file (MessageBox.sln), then choose Build Solution from the Build menu. You can now run the program under Debug mode by pressing F5.

To compile from the command line you can use either of the two batch files included in the MessageBox directory. Run builddbg.bat to create a debug build of the program in the MessageBox\bin\Debug directory, or run buildrel.bat to create a release build of the program in the MessageBox\bin\Release directory.

If compiling this application from the command line you should ensure that the .NET Framework directory is on the system PATH. Running the FTN95 for Microsoft .NET Command Prompt from the start menu will ensure that this is set up correctly.

Example Creation

This is a simple one-file project. To create this project, navigate to the File menu and select New Project. Select the FTN95 Projects branch, Choose FTN95 Application from the available projects and type an appropriate name for the project and press OK. Since this project will be using the Microsoft .NET framework, we need to link with the relevant DLL's. This example uses the System.Windows.Forms namespace so needs to link with System.Windows.Forms.dll. You can add DLL's to be linked with in Visual Studio .NET by using Add Reference in the solution explorer, under the References node. From the command line the /r switch should be used as shown in the batch files. You can specify multiple DLL's by separating their filenames with a semicolon (;).

One source file for the project is created automatically, if you need more than one they can be added by selecting Add New Item from the Project menu.

Code Features

This example demonstrates calling a Microsoft .NET static method that returns a Microsoft .NET object. You can use this new functionality in your programs with the new ASSEMBLY_EXTERNAL and OBJECT keywords. The ASSEMBLY_EXTERNAL keyword creates an alias for a Microsoft .NET method which can then be called in the usual Fortran way, and the OBJECT keyword declares a variable as an instance of a Microsoft .NET class e.g:

ASSEMBLY_EXTERNAL (name="System.Windows.Forms.MessageBox.Show") showMessageBox
object ("System.Windows.Forms.DialogResult") dialogResult

Using these two Fortran identifiers you can now call a Microsoft .NET method, storing it's return value:

dialogResult = showMessageBox ("Hello from the Silverfrost FTN95 .NET team!", "Hello")

As this method is a static method it can be called without constructing an instance of the object containing the method. If this were a non-static object then an instance must be created using NEW@ and this instance passed as the first argument.

Source Code

Fortran Source

program MessageBox
 assembly_external (name="System.Windows.Forms.MessageBox.Show") showMessageBox
  object ("System.Windows.Forms.DialogResult") dialogResult
  dialogResult = showMessageBox ("Hello from the Silverfrost FTN95 .NET team!", "Hello")
end

See Also:


Online Image Viewer Sample

Topics Covered

Calling .NET library methods from Fortran
Using Clearwin+ with .NET Fortran
Using .NET exception handling

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\NET\OnLineImageViewer

This example program demonstrates creating objects of a class contained within the Microsoft .NET framework and subsequently calling a method on that object from within Fortran. The program asks the user for the URL of an image on the web, then downloads it using a call to a Microsoft .NET framework object, before finally displaying it on screen using ClearWin+.

ClearWin+ is a library of functions and subroutines provided by Silverfrost together with FTN95 for Microsoft .NET and Win32, it enables developers to produce Windows applications very quickly.

This program requires the Microsoft .NET Framework to be installed in order to compile and run it. You can compile this example program either in Microsoft Visual Studio .NET or from the command line using the supplied batch files.

To compile from Microsoft Visual Studio .NET you just need to load the supplied solution file (OnlineImageViewer.sln), then choose Build Solution from the Build menu. You can now run the program under Debug mode by pressing F5.

To compile from the command line you can use either of the two batch files included in the OnlineImageViewer directory. Run builddbg.bat to create a debug build of the program in the OnlineImageViewer\bin\Debug directory, or run buildrel.bat to create a release build of the program in the OnlineImageViewer\bin\Release directory.

Example Creation

This example makes use of just one project, an FTN95 Fortran Application project.

To create the Fortran Application project, select New Project from the File menu. One file will be added to the project when it is created. This project uses functions that are available in System.dll, this file is automatically added as a reference to a new project. Enter the code below into the source file. This project can now be built using the Build command from the project menu.

Code Features

This example demonstrates the use of Clearwin+ and the use of .NET library methods, .NET exception handling is also demonstrated. For more information regarding Clearwin+ and it's usage please see the following topic:

Clearwin+
Introduction to Clearwin+

Source Code

Fortran Source

winapp
program OnlineImageViewer
  implicit none
  include <clearwin.ins>
  include <globals.ins>
  integer width, height
  integer i
  integer downloadAndDisplayImage
  external downloadAndDisplayImage
  width = 416
  height = 226
  information = "Enter the URL and press the View button."
  url = "http://www.salfordsoftware.co.uk/images/salford_dl.jpg"
  file = "temp.jpg"
  buttonEnabled = 1
  call erase@ (file, i)
  i=winio@ ("%sy[3d_thin]%ca[Example Online Image Viewer]&")
  i=winio@ ("URL: %~35rs %`~^bt[View]%ff%nl&", url, buttonEnabled, buttonEnabled, downloadAndDisplayImage)
  i=winio@ ("%gr[black,rgb_colours]%ff%nl&", width, height)
  i=winio@ ("Status: %40st&", information)
  i=winio@ ("")
end

integer function downloadAndDisplayImage ()
  implicit none
  include <clearwin.ins>
  include <globals.ins>
  logical downloadImage
  integer showImage, imageDisplay
  buttonEnabled = 0
  information = "Downloading image..."
  call window_update@(information)
  imageDownloaded = downloadImage ()
  imageDisplay = showImage()
  downloadAndDisplayImage = 1
end

integer function showImage ()
  implicit none
  include <clearwin.ins>
  character*1024 filename
  if (imageDownloaded) then
    filename = "{"
    call append_string@(filename, file)
    call append_string@(filename, "}")
    call displayImage(filename)
  endif
  showImage = 1
end

logical function downloadImage ()
  implicit none
  include <globals.ins>
  assembly_external (name="System.Net.WebClient.DownloadFile") webClientDownloadFile
  object ("System.Net.WebClient") webClient
  object ("System.Net.WebException") webException
  webClient = new@("System.Net.WebClient")
  try
    call webClientDownloadFile (webClient, url, file)
  catch (webException)
    information = "Download failed."
    call window_update@ (information)
    downloadImage = .false.
    return
  endtry
  downloadImage = .true.
end

subroutine displayImage (filename)
  implicit none
  include <clearwin.ins>
  include <globals.ins>
  character*1024 filename
  integer didDisplay
  didDisplay = import_image@(filename, 0, 0)
  if (didDisplay == 0) then
    information = "Failed to display image."
    call window_update@(information)
  else
    information = "Image downloaded."
    call window_update@(information)
  endif
end

The above code largly contains Clearwin+ code to create the window for the application. Within downloadImage calls are made into the .NET runtime to perform the download. Exception handling can also be seen within the function. For more information on topics covered in this example please see the following topics:


Matrix Invert Sample

Topics Covered

Calling Fortran from other .NET languages

Introduction

Default location:

<Documents Folder>\FTN95 Examples\NET\MatrixInvert

This example demonstrates the ease in which existing library code can be integrated into an application without complex changes to the existing code. A matrix inversion function is called from a C# Windows Forms application. FTN95 for Microsoft .NET is designed to allow existing code to be integrated without modifying the existing Fortran legacy code that many people work with on a daily basis.

This program requires the Microsoft .NET Framework to be installed in order to compile and run it. You can compile this example program either in Microsoft Visual Studio .NET or from the command line using the supplied batch files.

To compile from Microsoft Visual Studio .NET you just need to load the supplied solution file (MatrixInvert.sln), then choose Build Solution from the Build menu. You can now run the program under Debug mode by pressing F5.

To compile from the command line you can use either of the two batch files included in the MatrixInvert directory. Run builddbg.bat to create a debug build of the program in the MatrixInvert\bin\Debug directory, or run buildrel.bat to create a release build of the program in the MatrixInvert\bin\Release directory.

If compiling this application from the command line you should ensure that the .NET Framework directory is on the system PATH. Running the FTN95 for Microsoft .NET Command Prompt from the start menu will ensure that this is set up correctly.

Code Features

The example illustrates the usage of ASSEMBLY_INTERFACE to provide the calling mechanism to the Fortran code. A small stub has been added to the program so that the way arrays are used in Microsoft .NET is satisfied. ASSEMBLY_INTERFACE assumes the array arguments are declared with assumed sizes (the Fortran 90 way). The assumed sizes are then filled in automatically by the interface from the dimensions of the C# array.

Source Code

Fortran Source

SUBROUTINE DINVERSTUB(A,D,L,M)
  ASSEMBLY_INTERFACE (NAME="DinverStub")
  REAL*8 A(:,:),D,L(:),M(:)
  CALL DINVER(A,4,4,D,L,M)
END SUBROUTINE

DINVER(A,N,NUS,D,L,M)
REAL*8 A(*),L(*),M(*)
REAL*8 BIGA,HOLD
REAL*8 A,D
IF(NUS.GT.1)GOTO 1
A(1)=1.0/A(1)
D=1.0D0
RETURN
1 D=1.0D0
NK=-N
DO 11 K=1,NUS
  NK=NK+N
  L(K)=K
  M(K)=K
  KK=NK+K
  BIGA=A(KK)
  DO 2 J=K,NUS
    IZ=N*(J-1)
    DO 2 I=K,NUS
    IJ=IZ+I
    IF(ABS(BIGA).GE.ABS(A(IJ)))GOTO 2
    BIGA=A(IJ)
    L(K)=I
    M(K)=J
  2 CONTINUE
  J=L(K)
  IF(J.LE.K)GOTO 4
   KI=K-N
  DO 3 I=1,NUS
    KI=KI+N
    HOLD=-A(KI)
    JI=KI-K+J
    A(KI)=A(JI)
  3 A(JI)=HOLD
  4 I=M(K)
  IF(I.LE.K)GOTO 6
  JP=N*(I-1)
  DO 5 J=1,NUS
    JK=NK+J
    JI=JP+J
    HOLD=-A(JK)
    A(JK)=A(JI)
  5 A(JI)=HOLD
  6 IF(BIGA.NE.0.0)GOTO 7
  D=0.0
  RETURN
  7 DO 8 I=1,NUS
    IF(I.EQ.K)GOTO 8
    IK=NK+I
    A(IK)=A(IK)/(-BIGA)
  8 CONTINUE
  DO 9 I=1,NUS
    IK=NK+I
    HOLD=A(IK)
    IJ=I-N
    DO 9 J=1,NUS
      IJ=IJ+N
      IF(I.EQ.K)GOTO 9
      IF(J.EQ.K)GOTO 9
      KJ=IJ-I+K
      A(IJ)=HOLD*A(KJ)+A(IJ)
  9 CONTINUE
  KJ=K-N
  DO 10 J=1,NUS
    KJ=KJ+N
    IF(J.EQ.K)GOTO 10
    A(KJ)=A(KJ)/BIGA
  10 CONTINUE
  D=D*BIGA
  A(KK)=1.0/BIGA
11 CONTINUE
K=NUS
12 K=K-1
IF(K.LE.0)RETURN
I=L(K)
IF(I.LE.K)GOTO 14
JQ=N*(K-1)
JR=N*(I-1)
DO 13 J=1,NUS
  JK=JQ+J
  HOLD=A(JK)
  JI=JR+J
  A(JK)=-A(JI)
13 A(JI)=HOLD
14 J=M(K)
IF(J.LE.K)GOTO 12
KI=K-N
DO 15 I=1,NUS
  KI=KI+N
  HOLD=A(KI)
  JI=KI-K+J
  A(KI)=-A(JI)
15 A(JI)=HOLD
GOTO 12
END

The large majority of this code is legacy Fortran 77 code, used to complete a Matrix Inversion. Note the routine at the top of the source, this provides a .NET stub to call the routine from. Arrays are declared as assumed size (as they need to be when passing arrays from other .NET languages). A call is then made to the original inversion routine.

C# Source

//
// Create the .NET arrays we are going to pass
// These should be populated using a suitable method. In the example we use
// a form and collect the data from user (or default) input. See the source
// file for more details
//
double[,] a = new double[4,4];
double d = 0;
double[] l = new double[100];
double[] m = new double[100];
//
// Make the call to the Fortran
//
FortranMatrixInvert.DinverStub(a,d,l,m);

For more information about topics relevant to this example see the following topics:


Threads Sample

Topics Covered

Using Clearwin+ to create a user interface
Using threads with FTN95 for Microsoft .NET

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\NET\Threads

This example demonstrates creating threads safely. It uses the ClearWin+ system to provide the user interface consisting of seven buttons: one to start each thread, one to stop each thread (there are three threads) and one to exit the program; along with a text box for the output. When the program is closed all threads are immediately halted.

You can compile this example program either in Visual Studio .NET or from the command line using the supplied batch files. To compile from Microsoft Visual Studio .NET you need to load the supplied solution file (Threads.sln), then choose 'Build Solution' from the 'Build' menu. You can now run the program under Debug mode by pressing F5. To compile from the command line you can use either of the two batch files included in the Threads directory. Run 'builddbg.bat' to create a debug build of the program in the Threads\bin\Debug directory, or run 'buildrel.bat' to create a release build of the program in the Threads\bin\Release directory.

Example Creation

This example makes use one language and one project, a Fortran Application.

To create the Fortran Application project, select New Project from the File menu. One file will be added to the project when it is created. Enter the code below into the source file. Within the project options you should navigate to Compiler Options->Miscellaneous and set Use multi-threading to yes. This ensures that threadsafe runtime routines are used. This project can now be built using the Build command from the project menu.

Code Features

This example demonstrates the use of the threads with FTN95 and the .NET Framework. New language extensions have been added to enable threading, these are discussed within the source code below. To create a new thread you can use either CREATE_THREAD@ or CREATE_THREAD1@. CREATE_THREAD@ takes two arguments: the first subroutine that will be called when the thread starts, and a unique integer value identifying the thread. This unique number will be passed as the only argument to the specified subroutine. CREATE_THREAD1@ is the same as CREATE_THREAD@ but with an extra argument which will be set to the Microsoft .NET framework Thread object that is created. You can then use this object with the other Microsoft .NET Thread functions. See the Microsoft .NET framework documentation for more details on the functionality encompassed by the Thread Class. An example call to CREATE_THREAD1@ is shown below.

call CREATE_THREAD1@ (thread_start_routine, identifier, new_thread_object)

If the code inside the thread start routine needs to write to a block of data that another thread may also need to access then this should be protected by adding locks to the code. Code inside a LOCK block can only be executed by one thread at a time. Any other thread that needs to run this code will be made to wait until the thread which locked the code reaches the END LOCK statement.

LOCK
! .. Execute Sensitive Code
END LOCK

During a computationally intensive thread routine (a long loop for example) you may wish to pause it for a small amount of time to allow the other threads in your program to continue processing. This can be done by using the Sleep function in the Thread class from the .NET framework. The example uses this function to allow the main user interface thread to process any interaction immediately, this can be seen in the source below.

Fortran Source

module thread_control
  type thread_type
    double precision threadbar
    logical running
    logical stopping
    integer start_button_enabled
    integer stop_button_enabled
  end type thread_type
  type (thread_type) thread(3)
end module thread_control

winapp
use thread_control
include <clearwin.ins>
external start_thread1, start_thread2, start_thread3
integer start_thread1, start_thread2, start_thread3
external stop_thread1, stop_thread2, stop_thread3
integer stop_thread1, stop_thread2, stop_thread3
external close_window
integer close_window
integer k
do k = 1, 3
  thread(k)%threadbar = 0
  thread(k)%running = .false.
  thread(k)%stopping = .false.
  thread(k)%start_button_enabled = 1
  thread(k)%stop_button_enabled = 0
end do
k = winio@ ("%ca[Creating threads]%sy[3d_thin]&")
k = winio@ ("%80.20cw%ff%nl&", 0)
k = winio@ ("%cn%^~bt[Start thread 1] %50br %^~bt[Stop thread 1]%nl&", &
  & thread(1)%start_button_enabled, start_thread1, thread(1)%threadbar, RGB@(255,0,0), &
  & thread(1)%stop_button_enabled, stop_thread1)
k = winio@ ("%cn%^~bt[Start thread 2] %50br %^~bt[Stop thread 2]%nl&", &
  & thread(2)%start_button_enabled, start_thread2, thread(2)%threadbar, RGB@(0,255,0), &
  & thread(2)%stop_button_enabled, stop_thread2)
k = winio@ ("%cn%^~bt[Start thread 3] %50br %^~bt[Stop thread 3]%nl&", &
  & thread(3)%start_button_enabled, start_thread3, thread(3)%threadbar, RGB@(0,0,255), &
  & thread(3)%stop_button_enabled, stop_thread3)
k = winio@ ("%cn%bt[OK]%cc", close_window)
end

subroutine thread_proc(k)
use thread_control
include <clearwin.ins>
assembly_external (name="System.Threading.Thread.Sleep") thread_sleep
data num_iterations/500/
thread(k)%running = .true.
thread(k)%stopping = .false.
thread(k)%start_button_enabled = 0
thread(k)%stop_button_enabled = 1
lock
  call window_update@(thread(k)%start_button_enabled)
  call window_update@(thread(k)%stop_button_enabled)
end lock
do m = 1, num_iterations
  thread(k)%threadbar = real(m) / real(num_iterations)
  ! Because the print will operate to the same IO unit in several
  ! threads we must execute only one of these at once
  lock
    print *, "Thread ", k, " :: line ", m, " / ", num_iterations
    call window_update@(thread(k)%threadbar)
  end lock
  if (thread(k)%stopping) exit
  call thread_sleep(50)
enddo
thread(k)%start_button_enabled = 1
thread(k)%stop_button_enabled = 0
lock
  call window_update@(thread(k)%start_button_enabled)
  call window_update@(thread(k)%stop_button_enabled)
endlock
thread(k)%running = .false.
end

! callback functions for starting the threads
integer function start_thread1()
use thread_control
external thread_proc
object ("System.Threading.Thread") threadObject
call create_thread1@ (thread_proc, 1, threadObject)
start_thread1 = 2
end

integer function start_thread2()
use thread_control
external thread_proc
object ("System.Threading.Thread") threadObject
call create_thread1@ (thread_proc, 2, threadObject)
start_thread2 = 2
end

integer function start_thread3()
use thread_control
external thread_proc
object ("System.Threading.Thread") threadObject
call create_thread1@ (thread_proc, 3, threadObject)
start_thread3 = 2
end

! callback functions for stopping the threads
integer function stop_thread1()
use thread_control
thread(1)%stopping = .true.
stop_thread1 = 2
end

integer function stop_thread2()
use thread_control
thread(2)%stopping = .true.
stop_thread2 = 2
end

integer function stop_thread3()
use thread_control
thread(3)%stopping = .true.
stop_thread3 = 2
end

integer function close_window()
use thread_control
assembly_external (name="System.Threading.Thread.Sleep") thread_sleep
integer k
if (thread(1)%running .or. thread(2)%running .or. thread(3)%running) then
  ! tell all threads to stop
  do k = 1, 3
    thread(k)%stopping = .true.
  end do
  ! wait for the threads to stop
  while (thread(1)%running .or. thread(2)%running .or. thread(3)%running) do
    call thread_sleep(50)
  end while
endif
close_window = 0
end

For more information about the topics discussed in this example see the following links:


Exception Generator

Exception Generator Sample

Topics Covered

Using CHECK to trap runtime exceptions.
Using THROW to throw .NET runtime exceptions.

Introduction

Default Location:

<Documents Folder>\FTN95 Examples\NET\ExceptionGenerator

This example demonstrates the use of the CHECK option within FTN95 programs. CHECK allows for a range of runtime errors to be trapped. This program demonstrates some of the errors that will be caught, but for full details on CHECK and CHECKMATE see the following topic:

Run-time diagnostics

The example uses ClearWin to display a choice of 7 Exceptions. Choosing one of these and pressing the 'Run Test' button will cause the program to break with the specified exception. If you are debugging in Visual Studio then a message box will appear when one of these exceptions is thrown showing you the line where the exception occured and the Exception's message. The example project consists of a single FTN95 fixed format source file.

To compile from Microsoft Visual Studio .NET you just need to load the supplied solution file (ExceptionGenerator.sln), then choose Build Solution from the Build menu. You can now run the program under Debug mode by pressing F5.

To compile from the command line you can use either of the two batch files included in the ExceptionGenerator directory. Run builddbg.bat to create a debug build of the program in the ExceptionGenerator\bin\Debug directory, or run buildrel.bat to create a release build of the program in the ExceptionGenerator\bin\Release directory.

If compiling this application from the command line you should ensure that the .NET Framework directory is on the system PATH. Running the FTN95 for Microsoft .NET Command Prompt from the start menu will ensure that this is set up correctly.

This example is configured for use as a .NET application. CHECK and CHECKMATE can be used within a Win32 application in much the same way. This example uses .NET specific features and therefore can only be used as a .NET project (that is with /CLR supplied on the command line). For Win32 examples see the demo\checkmate folder within your FTN95 installation.

Code Features

This example uses a new keyword for FTN95 .NET - THROW. When given a character string parameter this keyword will throw a UserException in the normal .NET way, which can then be caught by the calling code. .The THROW keyword can also accept a .NET object as a parameter. The example creates a 'System.Exception' object using the NEW@ keyword and passes it as an argument to THROW. For full details see the source code below.

Fortran Source

      options(check)
      winapp
      program ExceptionGenerator
        implicit none
        integer i
        integer runTest
        external runTest
        integer rb1, rb2, rb3, rb4, rb5, rb6, rb7
        common rb1, rb2, rb3, rb4, rb5, rb6, rb7
        rb1 = 1
        i=winio@ ('%sy[3d_thin]&')
        i=winio@ ('Select the exception test you would like to run.
     &%nl%nl&')
        i=winio@ ('%rb[Throw a System Exception]%nl&', rb1)
        i=winio@ ('%rb[Throw a custom Exception]%nl&', rb2)
        i=winio@ ('%rb[Call a missing routine]%nl&', rb3)
        i=winio@ ('%rb[Exceed the bounds of an array]%nl&', rb4)
        i=winio@ ('%rb[Attempt to read from an unopened file]%nl&',
      &rb5)
        i=winio@ ('%rb[Divide an integer by 0]%nl&', rb6)
        i=winio@ ('%rb[Call winio with too few arguments]%nl&', rb7)
        i=winio@ ('%`7ga&', rb1, rb2, rb3, rb4, rb5, rb6, rb7)
        i=winio@ ('%nl%`^bt[Run test]&', runTest)
        i=winio@ ('')
      end

      function runTest
        implicit none
        integer runTest
        integer rb1, rb2, rb3, rb4, rb5, rb6, rb7
        common rb1, rb2, rb3, rb4, rb5, rb6, rb7
        integer i, arraySize, array
        dimension array(10)
        character string(32)
        object ('System.Exception') systemException
        systemException = new@ ('System.Exception')
        if (rb1 .eq. 1) then
          throw systemException
        else if (rb2 .eq. 1) then
          throw 'A custom exception'
        else if (rb3 .eq. 1) then
          call nowt
        else if (rb4 .eq. 1) then
          arraySize = 100
          array(arraySize) = 0
        else if (rb5 .eq. 1) then
          read (10) i
        else if (rb6 .eq. 1) then
          i = i/0
        else if (rb7 .eq. 1) then
          i=winio@("%gr")
        end if
        runTest = 1
      end function

Note the first line of the code provides the OPTIONS(CHECK) directive. This is equivalent to passing the /CHECK switch to the compiler. For more information on the topics discussed with this example see the following topics:


Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


The FTN95 address space

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Edit box (%eb)

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


%ti

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Changing compiler options

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Extensions to FTN95 from the Fortran 2003 standard

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ALL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ANY

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


COUNT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


CSHIFT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


DOT_PRODUCT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


EOSHIFT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LBOUND

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MATMUL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MAXLOC

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MAXVAL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MERGE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MINLOC

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MINVAL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


PACK

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


PRODUCT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


RESHAPE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SHAPE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SIZE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SPREAD

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SUM

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


TRANSPOSE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


UBOUND

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


UNPACK

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


BIT_SIZE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


BTEST

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IAND

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IBCLR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IBITS

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IBSET

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IEOR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IOR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ISHFT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ISHFTC

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MVBITS

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


NOT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ACOS

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ASIN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ATAN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ATAN2

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


COS

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


COSH

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


DIM

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


DPROD

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


EXP

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LOG

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LOG10

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SIGN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SIN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SINH

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SQRT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


TAN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


TANH

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


EPSILON

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


HUGE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MAXEXPONENT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MINEXPONENT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


NEAREST

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


PRECISION

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


RADIX

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


RANGE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


RRSPACING

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SCALE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SET_EXPONENT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SPACING

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


TINY

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ABS

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


AIMAG

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


AINT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ANINT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


CEILING

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


CMPLX

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


CONJG

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


DBLE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


DIGITS

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


EXPONENT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


FLOOR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


FRACTION

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


INT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


KIND

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LOGICAL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MAX

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MIN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MOD

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


MODULO

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


NINT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


RANDOM_NUMBER

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


RANDOM_SEED

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


REAL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SELECTED_INT_KIND

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SELECTED_REAL_KIND

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


TRANSFER

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ALLOCATED

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ASSOCIATED

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


NULL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ACHAR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ADJUSTL

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ADJUSTR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


CHAR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


IACHAR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


ICHAR

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


INDEX

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LEN_TRIM

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LEN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LGE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LGT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LLE

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


LLT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


REPEAT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SCAN

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


TRIM

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


VERIFY

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


PRESENT

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


CPU_TIME

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


DATE_AND_TIME

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


SYSTEM_CLOCK

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Explicit ClearWin window creation

When ClearWin+ creates a ClearWin window for you it is created full screen by default. Also, the window uses the Windows system fixed font (referred to as SYSTEM_FIXED_FONT in the Windows documentation). In general, it is better to create a ClearWin window explicitly so that you have a handle to it and you can exert more control. For example, the following would create a half-size window in the centre of the screen:

WINAPP
INCLUDE <windows.ins>
INTEGER win,xsize,ysize,xpos,ypos
xsize=clearwin_info@('screen_width')/2
ysize=clearwin_info@('screen_depth')/2
xpos=xsize/4
ypos=ysize/4
win=create_window@('Moon landing',xpos,ypos,xsize,ysize)
...

The first ClearWin window that you create will be the parent window. When this window is closed the program will terminate.

Once you have created it, you can inform the system that your window is the default ClearWin window, thus:

CALL set_default_window@(win)

A ClearWin window can also be attached to a specified Fortran unit, for example:

CALL open_to_window@(7,win)
WRITE(7,'(a)') 'Testing'

Fortran units connected to ClearWin windows are opened for input and output. When you close such a unit, the corresponding window is closed and all the heap storage required to hold the output is returned to the system.

When your program terminates, the ClearWin windows that it has created will remain open for viewing, scrolling etc. until closed by the user (e.g. by pressing Alt-F4).


Standard call-back functions

ClearWin+ call-back functions

ABOUT

BEEP[sound option]

CASCADE

CONFIRM_EXIT

COPY, CUT, PASTE

COPY_TEXT

CONTINUE

EDIT_FILE_OPEN

EDIT_FILE

EDIT_FILE_SAVE, EDIT_FILE_SAVE_AS

EXIT

DEC

FATAL

FILE_OPENR[caption]

FILE_OPENW[caption]

GPRINTER_OPEN

HELP_CONTENTS

HELP_ON_HELP

HELP_LOOKUP

HTML_PRINTER_OPEN

INC

INTERNET_HYPERLINK

PRINT_ABORT

PRINTER_OPEN

PRINTER_OPEN1

PRINTER_SELECT

SELECT_ALL

SET

SETF

SOUND

STOP

SUPER_MAXIMISE

TEXT

TEXT_HISTORY

TOGGLE

+

A simple text editor


ClearWin windows

Introduction

Simple programs

Explicit ClearWin window creation

Text output to ClearWin windows

Getting text from a ClearWin window

Obsolete ClearWin window functions


List box format

List box format - %n.mls[options]

In this section:

  • Bar format - %Nbr[options]
  • Horizontal and vertical scroll bars %hx and %vx
  • List box format - %n.mls[options]
  • Multiple selection box - %n.mms
  • List-view - %lv[options]
  • Tree-view - %N.Mtv[options]
  • Branch-view - %bv[options]
  • Colour palette - %cl[options]

This format supplies a simple list-box facility. The corresponding arguments are an array of CHARACTER strings, an INTEGER argument giving the size of the array and an INTEGER argument that both sets the initial selection and returns the result.

For example:

INTEGER k
CHARACTER greek(4)*5
DATA (greek(i),i=1,4)/'alpha','beta','gamma','delta'/
k=1
i=winio@('Select a Greek letter: %7.3ls',greek,4L,k)
END

The characters "7.3" before "ls" specify the width of the list box (as the number of characters) and the depth of the list box (as the number of lines). Pre-setting k to 1 would cause "alpha" to be already highlighted when the window is displayed. If the user selects "beta", then k set to 2. If k were pre-set to zero, none of the items would be initially selected. If the user were to exit without making a selection, k would keep its pre-set value.

The grave accent (`) may be used with %ls to produce a drop-down combo box rather than a list box (for an editable combo box see %el ). The caret (^) character is used in association with a call-back function. This function will be called whenever an item is selected.

For example:

EXTERNAL ls_function
i=winio@('%^ls',array,6L,n,ls_function)

(See also the LISTBOX_ITEM_SELECTED parameter in CLEARWIN_INFO@).

For a list box (i.e. when a grave accent modifier is not used), the option hscrollbar provides a horizontal scroll bar whilst the option multicolumn provides a multiple column display. For example:

CHARACTER*8 fruit(7)
DATA fruit/'Apples','Bananas','Cherries','Grapes',
+ 'Oranges','Pears','Plums'/
i=winio@('%24.4LS[multicolumn]',fruit,7,k)

Combining hscrollbar with multicolumn gives a horizontal scroll bar that selects one column at a time.


Layout and positioning

Introduction

Centre - %cn

Right justify - %rj

Tab location - %Ntl

Box format - %n.mob[options][title]

Pivot - %pv

Get and set window position formats - %gp, %sp

Absolute position format - %ap

Programmer grid format - %gd


Edit box

Edit box - %eb

See Edit box (%eb).


Help

Introduction

Bubble and tooltip help - %bh and %th

Help format - %n.mhe


Leave window open

Leave window open - %lw[option]

In this section:

  • Caption - %ca[title]
  • Window handle - %hw
  • Control handle - %lc
  • Leave window open - %lw[option]
  • Start-up call-back - %sc
  • Child window - %ch
  • Control variable - %cv
  • Create MDI frame - %fr
  • Attach window - %aw
  • Drag and drop - %dr
  • Set window position - %sp
  • Set window size - %sz
  • Window style - %ww[options]
  • Background colour - %bg[colour]
  • ClearWin window - %N.Mcw[options]
  • Property sheet - %Nps
  • Property sheet child - %sh
  • Closure control format - %cc
  • Delayed auto recall - %dl
  • Wallpaper - %wp[bitmap]
  • User window - %uw[class_name]
  • Screen saver - %sv
  • Disable screen saver - %ns
  • Taskbar icon - %ti

By default, winio@ does not return until the window that it creates is closed. Occasionally it is useful to create a window that remains open while the program takes other actions. %lw causes winio@ to return as soon as it has created the window (the return value of winio@ is not used in this case). The format takes one INTEGER argument that can be used to close the window. This integer, known as the control variable, is set to -1 while the window is still active. It is very important that the control variable used to receive the result does not cease to exist before the window closes. Hence it is necessary to use a variable that is either global (appears in the main program, a COMMON block or MODULE) or static (appears in a SAVE or DATA statement).

Note: Although the control variable is initialised by the call to winio@, you may choose to give it a value before the call in order to avoid a compiler warning.

%lw is also used to create a child window that is to be inserted within another window that includes %ch. The grave accent is used in this context. In this case the window is not displayed until the control variable is passed to the window containing %ch. See %ch for an example of this procedure. A child window may be used only once. If it is not used it will be destroyed when the program terminates.

A window that has been left open by means of %lw can be closed by setting its control variable to a non-negative value and by passing the address of the control variable to WINDOW_UPDATE@.

For example:

INTEGER control
i=winio@('Processing - please wait%lw',control)
CALL do_something_complex()
control=0
CALL window_update@(control)

It is possible to use %lw in conjunction with graphics drawing using %gr, %og or %dw. This provides a means of drawing to a region after it has been created. However, it is recommended that code to draw to a graphics region be placed in a call-back function attached to %sc.

%lw can take the option owned ( %lw[owned] ). This option defines certain properties of the window in relation to its parent. The "owned" properties are those of a window that does not use %lw, namely that the parent cannot overlay the child and, if the parent is closed, the child automatically closes. For these properties to be meaningful the parent must be created using %ww. Also %lw[owned] must be used in the definition of a child window that appears in a call-back function of the parent.


Functions ported from DBOS

Introduction

Graphics

Graphics plotter/screen

Graphics printer

Mouse

Table of alternative routines


Format windows topics

Introduction

Call-back functions

Window formats

Closing a window

Updating windows

Advanced use of format windows

Format codes grouped by function

Alphabetical index of format codes


Introduction?

This chapter presents an overview of the ClearWin+ function winio@ that was introduced in Chapter 3 (ClearWin+ tutorial). Further details are given in the following sections up to (Format code reference) which provides a detailed reference.

winio@ is used to lay out and control a window in order to include a wide variety of controls, child windows, toolbars, etc.. Of course, this task could be carried out by making direct use of the Windows API. Although the direct method does provide maximum flexibility, it also requires large amounts of complex coding in order to control the interface. In contrast, the winio@ function requires a bare minimum of code to achieve elaborate window interfaces.

Windows applications typically have a great deal of "low level" functionality. For example, a window with several input controls will let the user move between fields using the tab key or the mouse. Likewise, buttons change their appearance slightly when they acquire focus. Fortunately you do not need to write code to program this functionality into your application, as it is already supplied by ClearWin+.

The following example illustrates the power and flexibility of winio@. In this example winio@ is used to produce a window that includes a menu bar with associated standard call-back functions. The window contains a so-called edit box that is used to display and edit a file. The menu and edit box is fully functional. Three buttons are also shown on the right hand side of the window. These are used to illustrate how buttons are added to the window. As the example stands, clicking on any of these buttons has no effect since code for the corresponding processes has been omitted.

WINAPP
INCLUDE <windows.ins>
CHARACTER*129 file,new_file,help_file
INTEGER compile,link,run,i
EXTERNAL compile,link,run
help_file='myhelp.hlp'
i=winio@('%ca[Example]&')
i=winio@('%mn[&File[&Open]]&','EDIT_FILE_OPEN','*.*',
+ file)
i=winio@('%mn[[&Save]]&','EDIT_FILE_SAVE','*.*',
+ new_file)
i=winio@('%mn[[Save &As]]&','EDIT_FILE_SAVE_AS','*.*',
+ new_file)
i=winio@('%mn[[E&xit]]&','EXIT')
i=winio@('%mn[&Edit[&Copy]]&','COPY')
i=winio@('%mn[[Cu&t]]&','CUT')
i=winio@('%mn[[&Paste]]&', 'PASTE')
i=winio@('%mn[&Help[&Contents]]&','HELP_CONTENTS',
+ help_file)
i=winio@('%mn[[&Help on help]]&','HELP_ON_HELP',
+ help_file)
c--- Define a 30x10 edit box %eb ---
i=winio@('%ww%pv&')
i=winio@('%30.10eb[vscrollbar,hscrollbar]&','*',0)
c--- Define buttons that are to be dispalyed ---
i=winio@('%2nl %^7bt[&Compile]&',compile)
i=winio@('%2nl %^7bt[&Link]&', link)
i=winio@('%2nl %^7bt[&Run]', run)
END
c--- Call-back functions that do nothing ---
INTEGER FUNCTION compile()
compile=1
END
INTEGER FUNCTION link()
link=1
END
INTEGER FUNCTION run()
run=1
END

This is what the window looks like on the screen:

The reminder of this section and the following sections up to and including (Format code reference) provide a detailed explanation of how to set out the parameters of winio@.


Format code reference

Introduction

%ac

%ap

%aw

%bc

%bd

%bf

%bg

%bi

%bk

%bm

%bn

%br

%bt

%bv

%bx

%ca

%cb

%cc

%ch

%cl

%cn

%co

%cu

%cv

%cw

%dc

%dd

%de

%df

%di

%dl

%dp

%dr

%dw

%dy

%eb

%el

%em

%ep

%eq

%es

%ew

%fb

%fd

%ff

%fh

%fl

%fn

%fp

%fr

%fs

%ft

%ga

%gb

%gd

%gf

%gi

%gp

%gr

%he

%ht

%hw

%hx

%ib

%ic

%id

%if

%il

%it

%lc

%ld

%ln

%ls

%lv

%lw

%mb

%mg

%mi

%mn

%ms

%mv

%nc

%nd

%nl

%nr

%ns

%nw

%ob

%og

%pb

%pd

%pl

%pm

%ps

%pv

%rb

%rc

%rd

%re

%rf

%rj

%rm

%rp

%rs

%sc

%sb

%sd

%sf

%sh

%si

%sl

%sm

%sp

%ss

%st

%su

%sv

%sy

%sz

%ta

%tb

%tc

%th

%ti

%tl

%tp

%ts

%tt

%tv

%tx

%ty

%ud

%ul

%up

%uw

%vx

%wb

%wc

%wd

%we

%wf

%wg

%wi

%wp

%ws

%ww

%wx


INTEGER(KIND=7)

For 32 bit applications, FTN95 translates INTEGER(KIND=7) to INTEGER(KIND=3), a 32 bit integer.
For 64 bit applications, FTN95 translates INTEGER(KIND=7) to INTEGER(KIND=4), a 64 bit integer.


Graphics Topics

Introduction

Graphics format %gr[options]

Basic graphics primitives

Drawing text

Re-sizing a graphics surface

The %gr call-back function

Graphics selections

Drawing device independent bitmaps

Direct manipulation of the graphics surface

Off-screen graphics

Graphics icons

Windows graphic modes

Owner draw box format - %dw[options]

Updating the screen

Using GDI+: anti-aliasing and opacity


Programming tips

Introduction

Tricks with boxes

Debugging with an auxiliary terminal

Recording mouse and keyboard events

Breaking into the debugger


FIND_FILE@ example

MODULE mainWindow
  CHARACTER *260 status
  CHARACTER *261 foundFiles(100)
  INTEGER numFoundFiles, selection(99), view
  INTEGER ctrl
  CHARACTER*128 rootDirectory, filename
END

WINAPP
PROGRAM find_file_test
  USE mainWindow
  INCLUDE <windows.ins>
  INTEGER i
  INTEGER start_search, clear_list
  EXTERNAL start_search, clear_list

  status = ""
foundFiles(1) = "|Filename_600"
numFoundFiles = 0
selection(1) = 1
view = 1
rootDirectory = "c:\program files\Silverfrost"
filename= "readme.txt"
i = winio@("%ww%sy[3d_thin]%ca[Example file finder]&")
i = winio@("%lv%ff&", 720, 480,
                foundFiles, 99, selection, view)
i = winio@("Directory:%ta%68rs%ff&",
                rootDirectory)
i = winio@("File:%ta%68rs%ff&", filename)
i = winio@("%`^bt[Search] %^bt[Clear list]%ff&",
                start_search, clear_list)
i = winio@("%96st&" , status)
i = winio@("%lw" , ctrl)
END

INTEGER FUNCTION start_search()
  USE mainWindow
  INCLUDE <windows.ins>
  INTEGER find_file_callback
  EXTERNAL find_file_callback
  INTEGER searchStopped
  CHARACTER*8 cnum, numFoundFilesString

  searchStopped = find_file@ (rootDirectory, filename,
                find_file_callback)
numFoundFilesString = cnum(numFoundFiles)
status = numFoundFilesString(:LEN_TRIM(numFoundFilesString))
                    //" items displayed"
CALL window_update@(status)
start_search = 1
END

INTEGER FUNCTION clear_list()
  USE mainWindow
  INCLUDE <windows.ins>
  INTEGER i

  DO i=2, 99
    foundFiles(i) = ""
  ENDDO

  numFoundFiles = 0
  status = ""
  CALL window_update@(status)
  clear_list = 1
END

INTEGER FUNCTION find_file_callback()
  USE mainWindow
  INCLUDE <windows.ins>
  CHARACTER*260 reason, path
  reason = clearwin_string@("FIND_FILE_CALLBACK_REASON" )
  IF (reason == "FILE_FOUND" ) THEN
    path = clearwin_string@("FILE_FOUND" )
    IF(numFoundFiles < 99) THEN
      numFoundFiles = numFoundFiles + 1
      foundFiles(numFoundFiles+1) = "|" //path
      CALL window_update@(foundFiles)
    ENDIF
  ELSEIF (reason == "CHECKING_DIRECTORY" ) THEN
    path = clearwin_string@("CHECKING_DIRECTORY" )
    status = path
    CALL window_update@(status)
 ENDIF

  find_file_callback = 0
END


GETFONTSIZE@

Platform | Win32, x64
Purpose | To get the dimensions of the LOGFONT character width and height.
Syntax | SUBROUTINE GETFONTSIZE@(hfont, width, height) INTEGER(7) hfont INTEGER width,height !(output values)
Description | This returns the LOGFONT character width and height for a given font handle. If the routine fails then the width and height are returned as zero.
Notes | Introduced with FTN95 8.20.


GETTEXTSIZE@

Platform | Win32, x64
Purpose | To get the dimensions of a graphics character string in the associated control.
Syntax | SUBROUTINE GETTEXTSIZE@( HWND, STR, WIDTH, DEPTH ) INTEGER(7) HWND CHARACTER(*) STR INTEGER WIDTH,DEPTH
Description | This routine returns the pixel WIDTH and DEPTH of a given character string STR when drawn on the control that has the handle HWND. Use this for example with the handle for %`cw or with %lc. Trailing spaces will be included so either use a substring notation or terminate the significant characters by CHAR(0). If the routine fails then the width and height are returned as zero.
Notes | Introduced with FTN95 8.20.


Library reference

ClearWin+ Library reference

  • ABORT@
  • ACTIVATE_BITMAP_PALETTE@
  • ADD_ACCELERATOR@
  • ADD_CURSOR_MONITOR@
  • ADD_FOCUS_MONITOR@
  • ADD_GRAPHICS_ICON@
  • ADD_HYPERTEXT@
  • ADD_HYPERTEXT_RESOURCE@
  • ADD_KEYBOARD_MONITOR@
  • ADD_MENU_ITEM@
  • ADJUST_IB_SIZES@
  • ADVANCE_EDIT_BUFFER@
  • ATTACH_BITMAP_PALETTE@
  • AUTO_SCALE_FONT@
  • BOLD_FONT@
  • BROWSE_FOR_FOLDER1@
  • CHANGE_HELP_TEXT@
  • CHANGE_HYPERTEXT@
  • CHANGE_TIMER_INTERVAL@
  • CHANGE_PEN@
  • CHOOSE_COLOUR@
  • CHOOSE_COLOUR_EX@
  • CHOOSE_FONT@
  • CLEAR_BITMAP@
  • CLEAR_SCREEN@
  • CLEAR_WINDOW@
  • CLEARWIN_FLOAT@
  • CLEARWIN_INFO@
  • CLEARWIN_STRING@
  • CLEARWIN_VERSION@
  • CLIPBOARD_TO_SCREEN_BLOCK@
  • CLOSE_CD_TRAY@
  • CLOSE_METAFILE@
  • CLOSE_PRINTER@
  • CLOSE_PRINTER_ONLY@
  • CLOSE_SVG@
  • CLOSE_WAV_FILE@
  • COPY_FROM_CLIPBOARD@
  • COPY_FROM_CLIPBOARD64@
  • COPY_GRAPHICS_REGION@
  • COPY_TO_CLIPBOARD@
  • COPY_TO_CLIPBOARD64@
  • CREATE_BITMAP@
  • CREATE_CURSOR@
  • CREATE_GRAPHICS_REGION@
  • CREATE_WINDOW@
  • CURRENT_TAB@
  • DEFINE_FILE_EXTENSION@
  • DELETE_GRAPHICS_REGION@
  • DELETE_TAB@
  • DESTROY_WINDOW@
  • DIB_PAINT@
  • DISPLAY_DIB_BLOCK@
  • DISPLAY_POPUP_MENU@
  • DO_COMMAND@
  • DO_COPIES@
  • DOWNLOAD@
  • DRAW_BEZIER@
  • DRAW_CHARACTERS@
  • DRAW_ELLIPSE@
  • DRAW_FILLED_BEZIERSD@
  • DRAW_FILLED_ELLIPSE@
  • DRAW_FILLED_POLYGON@
  • DRAW_FILLED_RECTANGLE@
  • DRAW_LINE_BETWEEN@
  • DRAW_POINT@
  • DRAW_POLYLINE@
  • DRAW_RECTANGLE@
  • EDIT_DELETE_LINES@
  • EDIT_CLIPBOARD_COPY@, EDIT_CLIPBOARD_CUT@, EDIT_CLIPBOARD_PASTE@
  • EDIT_OPEN_LINE_MARK@, EDIT_OPEN_BLOCK_MARK@, EDIT_CLOSE_MARK@
  • EDITFILECLOSEPROMPT@
  • EDITFILEMODIFIED@
  • EDITFILESAVE@
  • EDITFILESAVEAS@
  • EDIT_MOVE_END@, EDIT_MOVE_HOME@, EDIT_MOVE_BOF@, EDIT_MOVE_TOF@
  • EDIT_REFRESH@
  • EDIT_WINDOW_TOP_LEFT@
  • EXPORT_BMP@
  • EXPORT_GIF@
  • EXPORT_PCX@
  • FEED_WKEYBOARD@
  • FILL_SURFACE@
  • FILL_TO_BORDER@
  • FILL_TO_BORDER@
  • FIND_EDIT_STRING@
  • FIND_FILE@
  • FIND_REPLACE_EDIT_STRING@
  • FONT_METRICS@
  • GET_BITMAP_DC@
  • GET_CLEARWIN_TEXT@
  • GET_CURRENT_DC@
  • GET_CURRENT_GRAPHICS_REGION@
  • GET_DEFAULT_WINDOW@
  • GET_DIB_BLOCK@
  • GET_DIB_SIZE@
  • GETEDITTEXT@
  • GET_FILTERED_FILE@
  • GET_FONT_ID@
  • GET_FONT_NAME@
  • GETFONTSIZE@
  • GET_GRAPHICAL_RESOLUTION@
  • GET_GRAPHICS_SELECTED_AREA@
  • GET_IM_INFO@
  • GET_MATCHED_COLOUR@
  • GET_MOUSE_INFO@
  • GET_MULTIPLE_FILENAMES@
  • GET_NEAREST_SCREEN_COLOUR@
  • GET_POINT@
  • GET_PRINTER_ORIENTATION@
  • GET_RGB_VALUE@
  • GET_SCREEN_DIB@
  • GET_SYSTEM_FONT@
  • GET_TEXT_HEIGHT@
  • GET_TEXT_SIZE@
  • GETTEXTSIZE@
  • GET_TRACK_LENGTH@
  • GET_USER_DATA@
  • GET_WINDOW_LOCATION@
  • GET_WKEY@
  • GET_WKEY1@
  • GRAPHICS_TO_CLIPBOARD@
  • GRAPHICS_WRITE_MODE@
  • HIBYTE@
  • HIGH_COLOUR_MODE@
  • HIWORD@
  • IMPORT_BMP@
  • IMPORT_FILE_IMAGE@
  • IMPORT_GIF@
  • IMPORT_IMAGE@
  • IMPORT_TEX_OBJECT@
  • INSERT_EDIT_STRING@
  • ITALIC_FONT@
  • INVALID_FLOAT@ (and INVALID_DOUBLE@)
  • KILL_TIMER@
  • LOADRESOURCE@
  • LOBYTE@
  • LOWORD@
  • MAKE_BITMAP@
  • MAKE_ICON@
  • MAP_FILE_FOR_READ_WRITE@
  • MAP_FILE_FOR_READING@
  • METAFILE_TO_CLIPBOARD@
  • MOVE_WINDOW@
  • MOVIE_PLAYING@
  • nARGB@
  • NEW_GRAPHICS_REGION@
  • NEW_PAGE@
  • NEW_TAB@
  • NEXT_EDIT_OPERATION@
  • OPEN_CD_TRAY@
  • OPEN_EDIT_FILE@
  • OPEN_GL_PRINTER@
  • OPEN_GL_PRINTER1@
  • OPEN_METAFILE@
  • OPEN_PRINTER@
  • OPEN_PRINTER1@
  • OPEN_PRINTER1_TO_FILE@
  • OPEN_PRINTER_TO_FILE@
  • OPEN_SVG@
  • OPEN_SVG1@
  • OPEN_TO_WINDOW@
  • OPEN_WAV_FILE_READ@
  • OPEN_WAV_FILE_WRITE@
  • PERFORM_GRAPHICS_UPDATE@
  • PAUSE@
  • PERMIT_ANOTHER_CALLBACK@
  • PERMIT_CALLBACK_IN_WINDOW@
  • PLAY_AUDIO_CD@
  • PLAY_CLIPBOARD_METAFILE@
  • PLAY_SOUND@
  • PLAY_SOUND_RESOURCE@
  • PLOT_REDRAW@
  • PRINTER_DIALOG_OPTIONS@
  • PRINT_DIB@
  • PRINT_GRAPHICS@
  • PRINT_GRAPHICS_PAGE@
  • PRINT_OPENGL_IMAGE@
  • PROGRESS_BAR@
  • PUT_DIB_BLOCK@
  • READ_URL@
  • RECORD_SOUND@
  • RECOVER_DIB_BLOCK@
  • RELEASE_BITMAP_DC@
  • RELEASE_SCREEN_DIB@
  • REMOVE_ACCELERATOR@
  • REMOVE_CURSOR_MONITOR@
  • REMOVE_FOCUS_MONITOR@
  • REMOVE_GRAPHICS_ICON@
  • REMOVE_KEYBOARD_MONITOR@
  • REMOVE_MENU_ITEM@
  • REPLACE_ENHANCED_MENU@
  • REPLACE_ENHANCED_POPUP_MENU@
  • REPLY_TO_TEXT_MESSAGE@
  • RESIZE_WINDOW@
  • RGB@
  • ROTATE_FONT@
  • SCALE_FONT@
  • SCC_LIB_VERSION@
  • SCROLL_EDIT_BUFFER@
  • SCROLL_GRAPHICS@
  • SEE_PROPERTYSHEET_PAGE@
  • SEE_TREEVIEW_SELECTION@
  • SELECT_FONT@
  • SELECT_FONT_ID@
  • SELECT_GRAPHICS_OBJECT@
  • SELECT_GRAPHICS_REGION@
  • SELECT_PRINTER@
  • SEND_TEXT_MESSAGE@
  • SET_ALL_MAX_LINES@
  • SET_CD_POSITION@
  • SET_CLEARWIN_FLOAT@
  • SET_CLEARWIN_INFO@
  • SET_CLEARWIN_STRING@
  • SET_CLEARWIN_STYLE@
  • SET_CONTROL_BACK_COLOUR@
  • SET_CONTROL_TEXT_COLOUR@
  • SET_CONTROL_VISIBILITY@
  • SET_CURSOR_WAITING@
  • SET_DASH_ARRAY@
  • SET_DEFAULT_FONT@
  • SET_DEFAULT_PROPORTIONAL_FONT@
  • SET_DEFAULT_TO_FIXED_FONT@
  • SET_DEFAULT_WINDOW@
  • SETDPIAWARENESS@
  • SET_EDIT_FIRST_LINE@
  • SET_FLOAT_LIMITS@
  • SET_GRAPHICS_SELECTION@
  • SET_HIGHLIGHTED@
  • SET_INCREMENT@
  • SET_INTEGER_LIMITS@
  • SET_INTERNET_CB@
  • SET_INTERNET_PARAM@
  • SET_LINE_STYLE@
  • SET_LINE_WIDTH@
  • SET_MAX_LINES@
  • SET_MAX_DIALOG_SIZE@
  • SET_MITER_LIMIT@
  • SET_MOUSE_CURSOR_POSITION@
  • SET_OLD_RESIZE_MECHANISM@
  • SET_OPACITY@
  • SET_OPEN_DIALOG_PATH@
  • SET_PRINTER_ORIENTATION@
  • SET_RGB_COLOURS_DEFAULT@
  • SET_SMOOTHING_MODE@
  • SET_SOUND_SAMPLE_RATE@
  • SET_STATUS_TEXT@
  • SET_TAB_TOOLTIP@
  • SET_TIMER@
  • SET_TOOLTIP_TEXT@
  • SET_UPDATE_RECTANGLE@
  • SET_USER_DATA@
  • SHOW_MOVIE@
  • SIMPLEPLOT_REDRAW@
  • SIZEOF_CLIPBOARD_BITMAP@
  • SIZEOF_CLIPBOARD_TEXT@
  • SIZEOF_CLIPBOARD_TEXT64@
  • SIZE_IN_PIXELS@
  • SIZE_IN_POINTS@
  • SOUND_PLAYING@
  • SOUND_RECORDING@
  • SOUND_SAMPLE_RATE@
  • START_CLEARWIN_PLAYBACK@
  • START_CLEARWIN_RECORDER@
  • START_PROCESS@
  • STOP@
  • STOP_AUDIO_CD@
  • STOP_CLEARWIN_RECORDER@
  • STOP_WHEN_WINDOWS_CLOSE@
  • SUPPRESS_CMD_BOX@
  • TEMPORARY_YIELD@
  • UNDERLINE_FONT@
  • UNBLANK_CONTROL@
  • UNDO_EDIT_CHANGE@
  • UNFREEZE_WINDOW_CONTENTS@
  • UNMAP_FILE@
  • UPDATE_WINDOW@
  • USE_APPROXIMATE_COLOURS@
  • USE_GDIPLUS@
  • USE_GDIPLUS_IMAGE_FILES@
  • USE_RESOURCE_LIBRARY@
  • USE_RGB_COLOURS@
  • USE_URL@
  • USE_WINDOWS95_FONT@
  • WAV_FILE_READ@
  • WAV_FILE_WRITE@
  • WBCOMMAND@
  • WINDOWS_95_FUNCTIONALITY@
  • WINDOW_UPDATE@
  • WIN_COUA@
  • WIN_GETCHAR@
  • WIN_GETLINE@
  • WINIO@
  • WINSTYLE@
  • WKEY_WAITING@
  • WRITE_GRAPHICS_TO_BMP@
  • WRITE_GRAPHICS_TO_PCX@
  • WRITE_WAV_FILE@
  • YIELD_PROGRAM_CONTROL@


ITALIC_FONT@

Platform | Win32, x64
Purpose | To set/unset italic font style for text on the current drawing surface.
Syntax | SUBROUTINE ITALIC_FONT@( ITAL ) INTEGER ITAL
Description | This routine sets or resets the italic property of the current drawing surface. Any subsequent calls to the DRAW_CHARACTERS@ routine will reflect the change.
See also | ROTATE_FONT@, SCALE_FONT@, SELECT_FONT@, UNDERLINE_FONT@, BOLD_FONT@


ClearWin+ Library Reference


WINDOW_UPDATE@

Platform | Win32, x64
Purpose | To check if a window should be updated or closed.
Syntax | SUBROUTINE WINDOW_UPDATE@(W)
Description | Update a window associated with variable W. W must be a variable used in a previous winio@ call to create a window.
See Also | Updating Windows, UPDATE_WINDOW@


ClearWin+ Library Reference - Y


Animation and multiple windows

OpenGL achieves animation by using two buffers, the front and the back buffer. When this, so called, double buffering is enabled, drawing (or rendering in OpenGL terminology) is directed to the back buffer. When the image is complete, you transfer it to the front buffer, or display, by calling swap_opengl_buffers@. This ClearWin+ routine merely remembers the current OpenGL context and so saves the programmer effort. When the back buffer is transferred to the display, it is supposed to be no longer valid so two successive swap buffer calls should produce garbage on the display. Although this does not seem to happen under Win32, the retention of the buffer should not be relied upon, as it might not be retained on other platforms.

The program below is not a Red Book sample. It illustrates the use of multiple windows, independently animated. This is something not possible using GLAUX.

The use of multiple OpenGL windows requires that you know the device context and rendering context for each of the windows. Changing from one window to another requires that you swap both the device context and the rendering context. Therefore, you must "enquire" them and store them away. These enquiry and swapping functions (together with some functions) are known as the WGL set. They do not form part of OpenGL, but are essential to the Windows implementation of it. Documentation for these functions will be found in the Microsoft Developer Network help files. You can be sure that when opengl_proc is called, the expected device and rendering contexts are current.

The font is also set by means of a WGL call, wglUseFontOutlines. Note how, in the the program, a C type NULL pointer is simulated by CORE4(0). This function call will only be successful if the format code %fn is used in the definition of the parent window.

**********************************
* *
* Animation using OpenGL *
* *
**********************************

SUBROUTINE display()
INCLUDE <opengl.ins>,nolist
INCLUDE <clearwin.ins>,nolist
INCLUDE 'danimate.ins'

CALL glClear (OR(GL_COLOR_BUFFER_BIT,GL_DEPTH_BUFFER_BIT))
CALL glMatrixMode (GL_MODELVIEW)
CALL glLoadIdentity()
CALL glTranslated(0d0,0d0,-10d0)
CALL glRotated(spin,1d0,0d0,0d0)
CALL glCallList(101)
CALL swap_opengl_buffers()
CALL glFlush()
END

SUBROUTINE swapContexts(window)
INTEGER window
INCLUDE <opengl.ins>
INCLUDE 'danimate.ins'
CALL wglMakeCurrent(devicecontext(window),
& renderingcontext(window))
END

SUBROUTINE spinSlab(window)
INTEGER window
INCLUDE 'danimate.ins'
do_draw(window)=.TRUE.
END

SUBROUTINE stopSlab(window)
INTEGER window
INCLUDE 'danimate.ins'
do_draw(window)=.FALSE.
END

SUBROUTINE assemble_list
INCLUDE <clearwin.ins>,nolist
INCLUDE <opengl.ins>,nolist

REAL*4 white_colour(4),grey_colour(4),dark_grey_colour(4)
REAL*4 red_colour(4), yellow_colour(4), green_colour(4)
REAL*4 blue_colour(4), purple_colour(4), cyan_colour(4)
REAL*8 dimension,scale,d,fd,front,back
INTEGER flags,k
INTEGER hdc
LOGICAL ok
DATA white_colour/1.0,1.0,1.0,1.0/
DATA grey_colour/0.5,0.5,0.5,1.0/
DATA dark_grey_colour/0.3,0.3,0.3,1.0/
DATA red_colour/1.0,0.0,0.0,1.0/
DATA yellow_colour/1.0,1.0,0.0,1.0/
DATA green_colour/0.0,1.0,0.0,1.0/
DATA blue_colour/0.0,0.0,1.0,1.0/
DATA purple_colour/1.0,0.0,1.0,1.0/
DATA cyan_colour/0.0,1.0,1.0,1.0/
DATA front,back/-0.01d0,-0.5d0/

CALL glEnable(GL_DEPTH_TEST)
hDC=clearwin_info@('OPENGL_DEVICE_CONTEXT')
CALL glColor3f(1.0,1.0,1.0)

ok=wglUseFontOutlines(hDC, 0, 255, 1000, 0.0, 0.1,
& WGL_FONT_POLYGONS,core4(0))

CALL glMatrixMode (GL_MODELVIEW)
CALL glLoadIdentity()
CALL glTranslated(0d0,0d0,-10d0)

c----Clear the color and depth buffers.

CALL glClear (OR(GL_COLOR_BUFFER_BIT,GL_DEPTH_BUFFER_BIT))
dimension=2.2d0
scale=dimension*0.9d0
CALL glDisable(GL_LIGHTING)

CALL glNewList(101,GL_COMPILE)
c----Front face
CALL glBegin(GL_POLYGON)
CALL glColor3fv(blue_colour)
CALL glVertex3d(-dimension,-dimension,front)
CALL glVertex3d(-dimension, dimension,front)
CALL glVertex3d( dimension, dimension,front)
CALL glVertex3d( dimension,-dimension,front)
CALL glEnd()
c----Back face
CALL glBegin(GL_POLYGON)
CALL glColor3fv(yellow_colour)
CALL glVertex3d(-dimension,-dimension,back)
CALL glVertex3d( dimension,-dimension,back)
CALL glVertex3d( dimension, dimension,back)
CALL glVertex3d(-dimension, dimension,back)
CALL glEnd()
c----Top face
CALL glBegin(GL_POLYGON)
CALL glColor3fv(red_colour)
CALL glVertex3d(-dimension, dimension,front)
CALL glVertex3d(-dimension, dimension,back)
CALL glVertex3d( dimension, dimension,back)
CALL glVertex3d( dimension, dimension,front)
CALL glEnd()
c----Bottom face
CALL glBegin(GL_POLYGON)
CALL glColor3fv(green_colour)
CALL glVertex3d( dimension,-dimension,front)
CALL glVertex3d( dimension,-dimension,back)
CALL glVertex3d(-dimension,-dimension,back)
CALL glVertex3d(-dimension,-dimension,front)
CALL glEnd()

c----Draw graph

CALL glBegin(GL_LINES)
CALL glColor3fv(white_colour)
CALL glVertex2d(-scale,0d0)
CALL glVertex2d(scale,0d0)
CALL glVertex2d(0d0,-scale)
CALL glVertex2d(0d0,scale)
k=-10
WHILE(k .LE. 10) DO
CALL glVertex2d((scale/10)*k,0.0d0)
CALL glVertex2d((scale/10)*k,0.1d0)
CALL glVertex2d(0.0d0,(scale/10)*k)
CALL glVertex2d(0.1d0,(scale/10)*k)
k=k+1
ENDWHILE
CALL glEnd()
CALL glColor3fv(red_colour)
CALL glBegin(GL_LINE_STRIP)
d=-10d0
WHILE(d .LT. 10d0)DO
fd=5*(d/10)**3+3*(d/10)**2-d/10
CALL glVertex2d(d*scale/10,fd*scale/10)
d=d+0.05d0
ENDWHILE
CALL glEnd()
CALL glColor3fv(green_colour)
CALL glBegin(GL_LINE_STRIP)
d=-10d0
WHILE(d .LT. 10)DO
fd=5*(d/10)**3+6*(d/10)**2-d/10
CALL glVertex2d(d*scale/10,fd*scale/10)
d=d+0.05d0
ENDWHILE
CALL glEnd()
CALL glColor3fv(red_colour)
CALL glListBase(1000)
CALL glTranslated(0.15d0,scale*0.95,0d0)
CALL glScaled(0.2d0,0.2d0,0.2d0)
CALL glCallLists(5, GL_UNSIGNED_BYTE, '+10.0')
CALL glEndList()
END

SUBROUTINE myinit()
CALL assemble_list()
END

SUBROUTINE myreshape(w,h)
INCLUDE <opengl.ins>,nolist
INTEGER w
INTEGER h
DOUBLE PRECISION aspect_ratio

IF(h.NE.0)THEN
aspect_ratio=dble(w)/h
CALL glMatrixMode(GL_PROJECTION)
CALL glLoadIdentity()
CALL gluPerspective(30.0d0,aspect_ratio,1d0,15d0)
CALL glViewport(0,0,w,h)
ENDIF

END

INTEGER FUNCTION opengl_proc1()
INCLUDE <clearwin.ins>,nolist
INCLUDE <opengl.ins>,nolist
INCLUDE 'danimate.ins',nolist
INTEGER w,h
CHARACTER*256 reason
reason=clearwin_string@('CALLBACK_REASON')

IF(reason.EQ.'SETUP')THEN
CALL myinit()
ELSEIF(reason.EQ.'RESIZE')THEN
w=clearwin_info@('OPENGL_WIDTH')
h=clearwin_info@('OPENGL_DEPTH')
CALL myreshape(w,h)
ELSEIF(reason.EQ.'DIRTY')THEN
CALL display()
window1_active=.true.
ELSEIf(reason.EQ.'MOUSE_LEFT_CLICK')THEN
CALL spinSlab(1)
ELSEIF(reason.EQ.'MOUSE_RIGHT_CLICK')THEN
CALL stopSlab(1)
ENDIF

opengl_proc1=2
END

INTEGER FUNCTION opengl_proc2()
INCLUDE <clearwin.ins>,nolist
INCLUDE <opengl.ins>,nolist
INCLUDE 'danimate.ins'
INTEGER w,h
CHARACTER*256 reason
reason=clearwin_string@('CALLBACK_REASON')

IF(reason.EQ.'SETUP')THEN
CALL myinit()
ELSEIF(reason.EQ.'RESIZE')THEN
w=clearwin_info@('OPENGL_WIDTH')
h=clearwin_info@('OPENGL_DEPTH')
CALL myreshape(w,h)
ELSEIF(reason.EQ.'DIRTY')THEN
CALL display()
window2_active=.true.
ELSEIF(reason.EQ.'MOUSE_LEFT_CLICK')THEN
CALL spinSlab(2)
ELSEIF(reason.EQ.'MOUSE_RIGHT_CLICK')THEN
CALL stopSlab(2)
ENDIF
CALL temporary_yield@()
opengl_proc2=2
END

PROGRAM Animate
INCLUDE <opengl.ins>,nolist
INCLUDE <clearwin.ins>,nolist
DOUBLE PRECISION spin_array(2)
INTEGER i,window1,window2
INTEGER opengl_proc1, opengl_proc2
EXTERNAL opengl_proc1,opengl_proc2
INCLUDE 'danimate.ins'

do_draw(1)=.true.
do_draw(2)=.true.
devicecontext(1)=0
devicecontext(2)=0
renderingcontext(1)=0
renderingcontext(2)=0
spin=0d0
spin_array(1)=0d0
spin_array(2)=0d0
window1_active=.false.
window2_active=.false.

c----Create a couple of OpenGL Windows
c----Window 1
i=winio@('%es%ca[Rotating Slab]&')
i=winio@('%fn[Times New Roman]%ts&',3.0d0)
i=winio@('%sp%ww[no_border]%pv%^og[double,depth16]%lw'.
& 0,0,350,350,opengl_proc1,window1)

c----Get and save hDC and the Rendering Contexts

devicecontext(1)=wglGetCurrentDC()
renderingcontext(1)=wglGetCurrentContext()

c----Create a couple of OpenGL Windows
c----Window 2
i=winio@('%es%ca[Rotating Slab]&')
i=winio@('%fn[Times New Roman]%ts&',3.0d0)
i=winio@('%sp%ww[no_border]%pv%^og[double,depth16]%lw',
& 400,0,350,350,opengl_proc2,window2)

c----Get and save hDC and the Rendering Contexts

devicecontext(2)=wglGetCurrentDC()
renderingcontext(2)=wglGetCurrentContext()

do_draw(1)=.true.
do_draw(2)=.true.

WHILE(window1.LT.0 .OR. window2.LT.0)DO
IF(window1.LT.0)THEN
IF(do_draw(1))THEN
spin_array(1)=spin_array(1)+2d0
spin=spin_array(1)
CALL swapContexts(1)
CALL display()
ENDIF
ENDIF
IF(window2.LT.0)THEN
IF(do_draw(2))THEN
spin_array(2)=spin_array(2)+2d0
spin=spin_array(2)
CALL swapContexts(2)
CALL display()
ENDIF
ENDIF
CALL temporary_yield@()
ENDWHILE
END


Argument types

Some OpenGL functions take single precision arguments, others double precision. In many cases it is possible to determine the argument type from the variant of the name. For example, glColor3f requires single precision arguments whereas, glColor3d requires double precision arguments.

With other OpenGL functions, the name does not help. For example, glAccum and glClearColor require single precision arguments whereas, glOrtho takes double precision arguments.

Unlike OpenGL functions, all GLAUX functions that take floating-point arguments require the arguments to be double precision.

You should carefully check the types of the arguments to any function before using it.

You must specify a double precision constant by using a 'D' exponent. Any constants for which you use neither 'D' nor DBLE( ) will be regarded as single precision and will yield unexpected results.

When linking, you are recommended to link directly with the import libraries rather than the DLLs. Using the import library will cause mismatched arguments to result in a link failure and enable you to quickly correct any errors.


Call-backs and initialisation

This next sample program is considerably more advanced. It uses double.c and Listing 1.3 from the Red Book. It illustrates the use of the mouse and various call-back functions. We will convert it to ClearWin+.

1 #include "glos.h"
2
3 #include <GL/gl.h>
4 #include <GL/glu.h>
5 #include <GL/glaux.h>
6
7 void myinit(void);
8 void CALLBACK spinDisplay (void);
9 void CALLBACK startIdleFunc (AUX_EVENTREC *event);
10 void CALLBACK stopIdleFunc (AUX_EVENTREC *event);
11 void CALLBACK myReshape(GLsizei w, GLsizei h);
12 void CALLBACK display(void);
13
14 static GLfloat spin = 0.0;
15
16 void CALLBACK display(void)
17 {
18 glClear (GL_COLOR_BUFFER_BIT);
19
20 glPushMatrix ();
21 glRotatef (spin, 0.0, 0.0, 1.0);
22 glRectf (-25.0, -25.0, 25.0, 25.0);
23 glPopMatrix ();
24
25 glFlush();
26 auxSwapBuffers();
27 }
28
29 void CALLBACK spinDisplay (void)
30 {
31 spin = spin + 2.0;
32 if (spin > 360.0)
33 spin = spin - 360.0;
34 display();
35 }
36
37 void CALLBACK startIdleFunc (AUX_EVENTREC *event)
38 {
39 auxIdleFunc(spinDisplay);
40 }
41
42 void CALLBACK stopIdleFunc (AUX_EVENTREC *event)
43 {
44 auxIdleFunc(0);
45 }
46
47 void myinit (void)
48 {
49 glClearColor (0.0, 0.0, 0.0, 1.0);
50 glColor3f (1.0, 1.0, 1.0);
51 glShadeModel (GL_FLAT);
52 }
53
54 void CALLBACK myReshape(GLsizei w, GLsizei h)
55 {
56 if (!h) return;
57 glViewport(0, 0, w, h);
58 glMatrixMode(GL_PROJECTION);
59 glLoadIdentity();
50 if (w <= h)
61 glOrtho (-50.0, 50.0, -50.0*(GLfloat)h/(GLfloat)w,
62 50.0*(GLfloat)h/(GLfloat)w, -1.0, 1.0);
63 else
64 glOrtho (-50.0*(GLfloat)w/(GLfloat)h,
65 50.0*(GLfloat)w/(GLfloat)h, -50.0, 50.0, -1.0, 1.0);
66 glMatrixMode(GL_MODELVIEW);
67 glLoadIdentity ();
68 }
69
60 /* Main Loop
71 * Open window with initial window size, title bar,
72 * RGBA display mode, and handle input events.
73 */
74 int main(int argc, char** argv)
75 {
76 auxInitDisplayMode (AUX_DOUBLE | AUX_RGB);
77 auxInitPosition (0, 0, 500, 500);
78 auxInitWindow ("Double Buffering");
79 myinit ();
70 auxReshapeFunc (myReshape);
81 auxIdleFunc (spinDisplay);
82 auxMouseFunc (AUX_LEFTBUTTON, AUX_MOUSEDOWN, startIdleFunc);
83 auxMouseFunc (AUX_RIGHTBUTTON, AUX_MOUSEDOWN, stopIdleFunc);
84 auxMainLoop(display);
85 return(0);
86 }

The converted program double.for is presented below. Note the use of common blocks rather than C global variables.

Lines 76 to 78 in the Red Book sample have been replaced by a few ClearWin+ calls at lines 109 to 111. %og has been replaced by %^og indicating that a call-back function, opengl_proc, has been provided to handle messages. The use of %pv means that RESIZE messages are sent to the call-back.

Mouse messages are also sent to opengl_proc, as are the special SETUP and DIRTY messages. SETUP is sent only once, just after the window has been created and its arrival precedes that of RESIZE. DIRTY is sent when the window needs repainting, for example, after RESIZE or when the window is brought to the top after being partially obscured. If you take action on the DIRTY call-back, you will not need the static option on %og.

The Red Book variant of the program supplies several functions to handle events. These functions are still needed and perform the same task, but they are called directly in response to ClearWin+ messages sent to opengl_proc. The reshape function myReshape(x,y) is called in response to RESIZE. display is called in response to DIRTY. The mouse handling functions startIdleFunc and stopIdleFunc are called in response to MOUSE_LEFT_CLICK and MOUSE_RIGHT_CLICK. These are registered as call-backs with GLAUX at lines 70 and 82-83.

In the Red Book example, the initialising call to myinit at line 79 (just after the window has been created) is handled by ClearWin+ as a message sent to opengl_proc. This message is SETUP and is always sent before the first RESIZE message. The GLAUX idle function has no direct ClearWin+ equivalent. Instead, %lw is used in the winio@ call and program execution falls through into the following idle loop. The test for ctrl<0 at line 113 in the ClearWin+ example, allows the program to detect when the window has been closed so that program termination can proceed.

1 SUBROUTINE display()
2 INCLUDE <opengl.ins>,nolist
3 REAL spin
4 LOGICAL do_draw
5 COMMON /double_com/do_draw,spin
6
7 CALL glClear(GL_COLOR_BUFFER_BIT)
8
9 CALL glPushMatrix()
10 CALL glRotatef(spin, 0.0, 0.0, 1.0)
11 CALL glRectf(-25.0, -25.0, 25.0, 25.0)
12 CALL glPopMatrix()
13
14 CALL glFlush()
15 CALL swap_opengl_buffers()
16 END
17
18 SUBROUTINE spinDisplay()
19 INCLUDE <clearwin.ins>,nolist
20 REAL spin
21 LOGICAL do_draw
22 COMMON /DOUBLE_COM/do_draw,spin
23
24 IF(do_draw)THEN
25 spin = spin + 2.0
26 IF(spin.GT.360.0)THEN
27 spin = spin - 360.0
28 ENDIF
29 CALL display()
30 ENDIF
31 CALL temporary_yield@()
32 END
33
34 SUBROUTINE startIdleFunc ()
35 REAL spin
36 LOGICAL do_draw
37 COMMON /DOUBLE_COM/do_draw,spin
38 do_draw=.TRUE.
39 END
40
41 SUBROUTINE stopIdleFunc ()
42 REAL spin
43 LOGICAL do_draw
44 COMMON /double_com/do_draw,spin
45 do_draw=.FALSE.
46 END
47
48 SUBROUTINE myinit ()
49 INCLUDE <opengl.ins>,nolist
50 CALL glClearColor (0.0, 0.0, 0.0, 1.0)
51 CALL glColor3f (1.0, 1.0, 1.0)
52 CALL glShadeModel (GL_FLAT)
53 END
54
55 SUBROUTINE myReshape(w, h)
56 INCLUDE <opengl.ins>,nolist
57 INTEGER w,h
58 DOUBLE PRECISION aspect_ratio
59 IF(h.NE.0) THEN
60 aspect_ratio=REAL(w)/h
61
62 CALL glViewport(0, 0, w, h)
63 CALL glMatrixMode(GL_PROJECTION)
64 CALL glLoadIdentity()
65 IF (w.LE.h) THEN
66 CALL glOrtho(-50d0, 50d0, -50d0/aspect_ratio,
67 & 50d0/aspect_ratio, -1d0, 1d0)
68 ELSE
69 CALL glOrtho(-50d0*aspect_ratio,
70 & 50d0*aspect_ratio, -50d0, 50d0, -1d0, 1d0)
71 ENDIF
72 CALL glMatrixMode(GL_MODELVIEW)
73 CALL glLoadIdentity ()
74 CALL display()
75 ENDIF
76 END
77
78
79 INTEGER FUNCTION opengl_proc()
80 INCLUDE <clearwin.ins>,nolist
81 CHARACTER*256 reason
82 INTEGER w,h
83 REASON=clearwin_string@('CALLBACK_REASON')
84 IF(reason.EQ.'SETUP')THEN
85 CALL myinit()
86 ELSE IF(reason.EQ.'RESIZE')THEN
87 w=clearwin_info@('OPENGL_WIDTH')
88 h=clearwin_info@('OPENGL_DEPTH')
89 CALL myReshape(w,h)
90 ELSE IF(reason.EQ.'MOUSE_LEFT_CLICK')THEN
91 CALL startIdleFunc()
92 ELSE IF(reason.EQ.'MOUSE_RIGHT_CLICK')THEN
93 CALL stopIdleFunc()
94 END IF
95
96 opengl_proc=2
97 END
98
99 PROGRAM double
100 INCLUDE <clearwin.ins>,nolist
101 INTEGER i
102 INTEGER opengl_proc,ctrl
103 EXTERNAL opengl_proc
104 REAL spin
105 LOGICAL do_draw
106 COMMON /double_com/do_draw,spin
107 DATA spin,do_draw/0.0,.TRUE./
108
109 i=winio@('%es%ca[Double Buffering]&')
110 i=winio@('%sp%ww[no_border]%pv%^og[double]%lw',
111 & 0,0,500,500,opengl_proc,ctrl)
112
113 WHILE(ctrl.LT.0)DO
114 CALL spinDisplay()
115 ENDWHILE
116 END

This program follows the structure that will be used throughout this chapter, and your attention is drawn again to the use of opengl_proc to call the reshape, display, initialisation and mouse handling functions.


OpenGL

Introduction

OpenGL - %og[options]

The conversion of a Red Book example

Using a printer with OpenGL

References

Online information


Using the printer

Introduction

Selecting a printer

Customising the printer dialog box

Printer graphics

Using a metafile to print multiple copies


The Simfit and Simdem packages

Introduction

Simfit plotting styles

Plotting a pie chart

Plotting a bar chart

Plotting y = f(x)

Plotting r = r(θ)

Plotting x = x(t), y = y(t)

Plotting x = x(t), y = y(t), z = z(t)

Plotting z = f(x,y)


Direct calls to SIMPLEPLOT using %dw

Here is a sample program that makes direct calls into the SIMPLPLOT library and uses an owner draw graphics box to display the result.

MODULE spwin ! Contains definition of values to pass to DDDATA
INTEGER,PARAMETER::SIMPLE_WINDOWS_WINDOW=1
INTEGER,PARAMETER::SIMPLE_WINDOWS_PRINTER=2
INTEGER,PARAMETER::SIMPLE_WINDOWS_DIB=4
INTEGER,PARAMETER::SIMPLE_WINDOWS_METAFILE=8
INTEGER,PARAMETER::SIMPLE_PERCENT=0
INTEGER,PARAMETER::SIMPLE_PIXELS=1
INTEGER,PARAMETER::SIMPLE_MM=2
INTEGER,PARAMETER::SIMPLE_WINDOWS_END_LIST=0
INTEGER,PARAMETER::SIMPLE_WINDOWS_SET_WINDOWNAME=6
INTEGER,PARAMETER::SIMPLE_WINDOWS_SET_HDC_DIM=7

TYPE SIMPLE_WINDOWS_DATA_STRUCT_T
INTEGER :: iOpc ! Corresponds to C++ long int
INTEGER :: iPtr ! Address of OpCode specific data
END TYPE SIMPLE_WINDOWS_DATA_STRUCT_T

TYPE SIMPLE_WINDOWS_HDC_DATA_T
INTEGER :: hDC ! device context handle
INTEGER :: iWidth, iHeight ! plotting area
END TYPE SIMPLE_WINDOWS_HDC_DATA_T

TYPE SIMPLE_WINDOWS_SIZE_T
INTEGER :: iUnits ! SIMPLE_PERCENT, ..._PIXELS, ..._MM
INTEGER :: iWidth, iHeight, iDepth
END TYPE SIMPLE_WINDOWS_SIZE_T

TYPE SIMPLE_WINDOWS_ORIGIN_T
INTEGER :: iUnits ! SIMPLE_PERCENT, ..._PIXELS, ..._MM
INTEGER :: iX, iY
END TYPE SIMPLE_WINDOWS_ORIGIN_T

TYPE HDC_DIM_TYPE
INTEGER*4 iBitmapDC, iWidth, iHeight
END TYPE HDC_DIM_TYPE

TYPE(HDC_DIM_TYPE)::HDC_DIM

! Useful definition of data structure to hold BitmapDC to pass to SIMPLEPLOT

CONTAINS

SUBROUTINE SP_SupplyBitmap ! Pass Bitmap to SIMPLEPLOT
! Set up a Static (SAVEd) array of OpCodes. Each OpCode consists of an
! OpCode ID followed by an optional address of a data structure.
! The parameter block address is passed to SIMPLEPLOT by SUBROUTINE DDDATA.
!
! In this example:
! SIMPLE_WINDOWS_SET_HDC_DIM specifies that the next integer is the address
! of a data structure consisting of a Bitmap DC followed by its dimensions
! SIMPLE_WINDOWS_END_LIST is the mandatory end of list item which does not
! require the address of a structure
TYPE(SIMPLE_WINDOWS_DATA_STRUCT_T),DIMENSION(2)::OpCodes
SAVE OpCodes
OpCodes(1)%iOpc = SIMPLE_WINDOWS_SET_HDC_DIM ! hDC + dimensions
OpCodes(1)%iPtr = LOC(HDC_DIM) ! See definition of SPWIN above
OpCodes(2)%iOpc = SIMPLE_WINDOWS_END_LIST! End of list
CALL DDDATA(LOC(OpCodes))! Notify SIMPLEPLOT
CALL DEVNAM('WINDOW') ! Select Window
CALL OWNNEW(.TRUE.) ! Inhibit 'Continue' button
END SUBROUTINE SP_SupplyBitmap

!This subroutine is needed if the content of the graph window changes during the program run
SUBROUTINE UpdateWin
CALL OUTBUF ! Flush buffers
CALL WINDOW_UPDATE@(HDC_DIM%iBitmapDC) ! Copy Bitmap to window
END SUBROUTINE UpdateWin

END MODULE spwin

WINAPP
PROGRAM Simpleplot_plots
USE mswin
USE spwin
LIBRARY 'c:\program files (x86)\silverfrost\ftn95\simple.dll'
IMPLICIT NONE
REAL,DIMENSION(100) ::xarr,yarr
INTEGER :: narr,ltype,xscale,yscale,nstep=1,mtype=5
INTEGER :: ctype,i,ans
CHARACTER(8) :: xlabel="x",ylabel="y",ptype
REAL :: minx,maxx,miny,maxy

narr=0
DO i=1,100
xarr(i)=2*i
yarr(i)=i*i
narr=narr+1
END DO

HDC_DIM%iWidth = 600
HDC_DIM%iHeight = 800
HDC_DIM%iBitmapDC = GET_Bitmap_DC@(HDC_DIM%iWidth, HDC_DIM%iHeight)
CALL SP_SupplyBitmap ! Pass Bitmap to SIMPLEPLOT
CALL INITSP
CALL PGFULL(.true.)
!scale factor for text in graph
CALL TEXTMG(1.5)
!characters set
CALL CHSET(0)
!direction of ticks: in, out
CALL AXSBTK('XC','I')
CALL AXSBTK('YC','O')
!line thickness
CALL THCKMG('L',2.0)
!location of labels in the axes
CALL AXLBJS('**', 'Centre')
minx=minval(xarr)
maxx=maxval(xarr)
miny=minval(yarr)
maxy=maxval(yarr)
!define the graph scales: max and min values of x and y and the type of scales: 1-linear, 2-log
xscale=1;yscale=1
CALL SCALES(minx,maxx,xscale,miny,maxy,yscale)
!pen color 1...for axes
CALL PEN(4)
!cross point of x and y
CALL AXCRSS('YC',minx)
! labels of axes
CALL AXES7(xlabel, ylabel)
!pen color for data
CALL PEN(2)
!full line or dashed?
!ltype=0, full line,ltype=1, dashed
ltype=0
ptype="scatter"
ptype="curve"
IF(ptype=='curve') THEN
!cvtype=1 -> smooth
!cvtype=3 -> straight lines
ctype=3
CALL CVTYPE(ctype)
CALL BRKNCV(real(xarr,1),real(yarr,1),narr,ltype)
ELSE !scatter
CALL MKSET(1) !set of markers 1,2,3......
CALL MARKCV(real(xarr,1),real(yarr,1),narr,mtype,nstep)
ENDIF
ans=winio@('%ca[A Simple Plot with Simpleplot]%bg[grey]&')
ans=winio@('%dw&',HDC_DIM%iBitmapDC) ! Pass bitmapDC to ClearWin
ans=winio@('%ff%nl%cn%6bt[Close]')
END PROGRAM Simpleplot_plots


SIMPLEPLOT

Introduction

A simple example

%pl options

Direct calls to SIMPLEPLOT

Native %pl, SIMPLEPLOT without the DLL


ClearWin+ tutorial

Introduction

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6


Finding a routine to debug

Finding a particular routine that you want to debug is very simple, just press Ctrl+F. This will bring up the Find Routine window. Simply type in the routine you want to find and it will be displayed. The 'Find Routine' window actually performs a wildcard match for all routines which contain the text you typed, so you could just type the first few characters. For example if the routine required was called 'GET_SATURATED_RATIO' then typing in 'GET_SATUR' will probably find it. If there is more than one routine that matches your text then a list will be displayed.

In addition to pressing Ctrl+F you can also select Find Routine from the Tools menu or use the Find command from the debugger command line.


Finding the value of a variable

There are several ways to obtain the value of a variable and which is best depends on your particular situation. Here are three quick ways:

1. If you can see the variable in the source window, point the mouse at it - a tool-tip will appear with the value. A right mouse click will open a separate window that displays the value. The tool-tip feature can be turned off from the Options Window but the right mouse click will always work.

2. Look in the variables window (this can be configured to be alphabetic from the Options Window). Once the variable is highlighted you can open a separate window by pressing the left mouse button.

3. Using the debugger command line, simply type 'PRINT ' (or just 'P ') followed by the variable and it will be displayed in its own window. You can also display an expression. For example 'PRINT X/XRATIO' will display a window with the value of X/XRATIO. This will update as the program is stepped.


Debugging programs when the source files have moved

Having the full path of the source files that make up an application has the great advantage that it can be debugged in a directory that does not contain source files. It also means that source files can be located in more than one directory. It does, however, have the disadvantage that if the source files move (either because of a drive mapping change or even debugging the code on a different machine) then the source files cannot be found. The debugger allows you to specify a path (or list of paths) down which the debugger can look if it cannot find a source file in its expected location.

This path can be specified in two different ways:

1. You can use the /SOURCEPATH command line option when running the debugger. This should be followed by the path(s). e.g.

... /SOURCEPATH s:\src;s:\src\nt

Here two paths have been given and they will be searched in order. This option can be shortened to /SP.

2. You can use an MSDOS environment variable called SOURCEPATH that will be used in the absence of a /SOURCEPATH option. e.g.

SET SOURCEPATH=s;\src;s:\src;nt


64-bit Development

From version 8.00 onwards FTN95 includes a 64-bit compiler as well as the long established 32-bit version. 64-bit code is produced by using the /64 compiler switch. Plato also has appropriate configuration options for enabling 64-bit code production (which eventually boil down to it using the /64 compiler option).

It is not possible to mix 32 and 64-bit code. Compilation and linking is either all 32-bit or all 64. Linking is done by the new 64-bit linker: slink64.

FTN95 creates 64-bit executables and DLLs when:

  • the option /64 is used on the FTN95 command line,
  • SLINK64 is used in place of SLINK
  • salflibc64.dll and clearwin64.dll are used in place of salflibc.dll.

Differences between 32- and 64-bit Fortran

There are some differences between the 32 and 64-bit environments. These are summarised below:
  • 64-bit programs run in a much larger address space. 32-bit FTN95 programs could, with some configuration, use 3GB of RAM. 64-bit programs are effectively limited to the amount of RAM, with hard disk backing, that you can give them.
  • 64-bit programs cannot run on 32-bit versions of Windows.
  • 64-bit programs cannot use 32-bit DLLs (and vice-versa).
  • Extended precision (REAL*10 and COMPLEX*20) is not available in 64-bit mode
  • When distributing you programs you must also distribute the 64-bit run time DLLs. These are salflibc64.dll and clearwin64.dll
  • 64-bit Microsoft Windows HANDLEs are addresses (64-bit integers). So if a Windows handle is used explicitly in Fortran code, it will currently appear as a 32 (KIND=3) integer and must become a 64-bit (KIND=4) integer for 64-bit applications. FTN95 has a special KIND value (7) that is interpreted as KIND=3 for 32-bit applications and KIND=4 for 64-bit applications. Alternatively INTEGER(KIND=CW_HANDLE) can be used together with standard INCLUDE and MOD files because CW_HANDLE is defined as a parameter with value 7. Windows HANDLEs are mainly used with %lc, %hw and some direct calls to the Windows API.
  • Assembler in CODE/EDOC is not compatible between 32 and 64-bit modes
  • Extended precision (REAL*10) is not available when creating 64-bit applications.

SLINK64

SLINK64 can be used in:

a) command line mode
b) interactive mode or
c) script file mode

Here is an example of using command line mode...

   FTN95 prog.f95 /64
   FTN95 sub.f95  /64
   SLINK64 prog.obj sub.obj /file:prog.exe

Here is an example of using interactive mode...

   SLINK64
   $ lo prog.obj
   $ lo sub.obj
   $ file prog.exe

Here is an example of using a script file...

   SLINK64 @prog.inf

where prog.inf contains...

   lo prog.obj
   lo sub.obj
   file prog.exe

For further information see below or type...

SLINK64 /help

SLINK64 automatically scans commonly used Windows DLLs. If a Windows function located in (say) xxx.dll is reported as missing then the DLL should be loaded by using a script command of the form

   lo C:\Windows\Sysnative\xxx.dll
where C:\Windows illustrates the value of the %windir% environment variable.

Note that the initial release of SLINK64 can construct executables and DLLs but not static libraries.

SDBG64

The 64-bit debugger is provided. It operates in essentially the same way as the corresponding 32-bit debugger.

ClearWin+

64-bit ClearWin+ was previously available for use with third party compilers via clearwin64.dll. This DLL has now been extended for use with 64-bit FTN95. Users who have already adapted their code for use with third-party compilers can continue to use their modified code. Alternatively native FTN95/ClearWin+ code can be used without change apart from the following exceptions:

  • 64-bit Microsoft Windows HANDLEs are addresses (64-bit integers). So if a Windows handle is used explicitly in Fortran code, it will currently appear as a 32 (KIND=3) integer and must become a 64-bit (KIND=4) integer for 64-bit applications. FTN95 has a special KIND value (7) that is interpreted as KIND=3 for 32-bit applications and KIND=4 for 64-bit applications. Alternatively INTEGER(KIND=CW_HANDLE) can be used together with standard INCLUDE and MOD files because CW_HANDLE is defined as a parameter with value 7. Windows HANDLEs are mainly used with %lc, %hw and some direct calls to the Windows API.
  • The function CLEARWIN_INFO@ now returns an INTEGER(KIND=7) value.
  • A few very old graphics routines have not been ported to 64-bit ClearWin+.
  • The function CPU_CLOCK@ is not available for 64-bit applications and has been replaced by rdtsc_val@...INTEGER(KIND=4) FUNCTION RDTSC_VAL@()

SRC

Use the command line option /r for 64-bit applications and link the resulting .res file (together with the .obj files) via SLINK64.

Current experience suggests that using the "default.manifest" in a resource script causes the resulting 64-bit application to fail to load. However, a user supplied manifest file can improve the appearance. The text of a suitable manifest file is presented below.

RESOURCES

A RESOURCES directive can be used at the end of a 64-bit Fortran main program but it only has effect when used with FTN95 command line options /LINK or /LGO. Otherwise a separate call to SRC is required. (For Win32 main programs, FTN95 automatically adds the resources to the main object file).

Silverfrost INCLUDE and MOD files

Silverfrost INCLUDE files have been modified so that Microsoft HANDLEs have type INTEGER(KIND=7).

Silverfrost MOD files can be used without change provided they are updated to those in this release.

Note that user FTN95 MOD files for 64-bit applications may differ from those for 32-bit applications. So FTN95 uses the extension .mod64 for 64-bit MOD files whilst retaining teh extension .mod for 32-bit MOD files. The corresponding object files always differ and the respective linker (SLINK or SLINK64) will reject object files of the wrong kind.

By default FTN95 uses the extension .obj for both 64-bit and 32-bit object files. For projects, both Plato and Visual Studio retain the default extension and use a system of sub-folders in order to create executables for different platforms (such as Win32, x64 and .NET) and for differenct configurations (such as Debug, CheckMate and Release).

Users who prefer to build their applications using batch and/or makefiles can adopt a similar sub-folder approach to that used by Plato and Visual Studio. Alternatively, 64-bit object files can be given a different extension (e.g. .o64) by using /BINARY (together with the object file name) on the FTN95 command line. In that way, 64-bit and 32-bit object files could reside in the same folder.

Plato

The associated release of Plato is configured by default to use FTN95 when you select "Release x64" on the main toolbar. Previously this used gFortran.

Plato can be used as a debugger to step into 64 bit FTN95 code or to launch the 64-bit debugger SDBG64 as an external application. See the Settings dialog on the Tools menu..

Redistributing

Like salflibc.dll, salflibc64.dll and clearwin64.dll can be freely redistributed with your applications and DLLs.

Additional notes on porting from 32-bit to 64-bit applications

1) When using the standard Fortran SIZE intrinsic, FTN95 with /64 returns a 64-bit integer despite the fact that this is not strictly standard conforming. In certain very special circumstances, this change can cause existing code to fail. For example, failure will occur if SIZE(x) appears as the value of an argument to an overloaded subprogram (i.e. a subprogram that has various definitions depending on the types of its arguments). A new command line option /SIZE_ISO. is provided in order to resolve this conflict.

2) It is possible that there may a some slight loss of precision when porting from 32-bit to 64-bit calculations. This is mainly because some FTN95 32-bit mode floating point calculations actually use hidden extended precision on the way to producing double or single precision results. It is therefore possible that the process of porting to 64-bits may expose a numerically unstable calculation (i.e. one that depends critically on the level of round-off error). In the same way, in extreme cases it is possible that new exceptions may appear at runtime due to floating point overflow. Overflow can occur directly or as the result of dividing by a value that has underflowed to zero. In some cases it is possible to resolve these issues by using a scaling factor in the calculations.

Further information about SLINK64

The SINK64 command line

SLINK64 can be used in 3 ways...

1) It can use a series of commands from a file (recommended). The commands are placed in a file with the .inf or .link suffix, and is invoked thus:

SLINK64 file.inf

2) It can be used interactively, using the same commands as in (1).

3) It can be used from the command line. This can be derived from the command specifications. Thus the command lo <obj file> can be coded on the command line as /lo <obj file>

SLINK64 commands

  • load(lo) <file> - Loads the file, which must be FTN95/SCC 64-bit object code.
  • map <file> - Requests a link map, to be placed in the specified file. If the file argument is omitted, the map is placed in a file whose name is derived from the name of the DLL or EXE file being created.
  • file <exe or dll file> - Completes the linking operation and puts the result in the given file name. Note that the choice of suffix (DLL or EXE) determines the type of file created. Currently all entry points in the code are exported in the case of a DLL.
  • windows - This command forces the creation of a WINDOWS application, which does not use a console. This is normally used in conjunction with ClearWin+ code.
  • load(lo) <file.dll> - Uses the entry points in the specified DLL to satisfy calls in the code. The DLL must be avaiable at run-time.
  • load(lo) <file.res> - Loads a resource file created with SRC using the /r switch. This is the same SRC command used in 32-bit mode except that the /r switch must be used.
  • image_base <hex address> - Specifies the base address for the link (not normally required, and can be overwritten at run time by Windows).
  • stack_size <hex number> - Specifies the stack size. The default value is 0x1000000 (16 MB).
  • alias <name> <alias> - Sets up an alias to an external name when making a DLL. Note that the names are case sensitive. This was added to enable gFortran to call a DLL built with FTN95. It circumvents the problem that gFortran uses lower case names while FTN95 uses upper case names! It may have other specialised uses.
  • help - Prints out abbreviated help information to the console.
  • quit(q) - Quits SLINK64 without saving anything.

Typical use

SLINK64 is automatically called when /link or /lgo is used on the FTN95 command line. The name of the executable or DLL can be supplied after /link (this is optional for executables but mandatory for DLLs). Also /stack can be included followed by the stack size as a number of megabytes. /map can also be used in this context.

The WINAPP directive in the Fortran code creates a Windows application and this directive can optionally be followed by the name of a resource script. Alternatively a resource script can be included by placing the script after the main program by using the RESOURCES directive.

Here are the required SLINK64 commands for three slightly more complicated scenarios:

1) To link a simple program that uses a DLL:

The file (say) ExtraDLL.dll is scanned for entry points but it isn't incorporated in MyProgram.exe - so MyProgram.exe will require the DLL somewhere on the path at runtime.

     lo MyProgram.obj
     lo ExtraDLL.dll
     file MyProgram.exe

2) To link a number of files to create a DLL that exports all subroutine/function names:

     lo file1.obj
     lo file2.obj
     lo file3.obj
     file MyLibrary.dll

3) To create a windows program with some ClearWin+ code that uses resources:

The resources are prepared by:

     SRC MyResources.rc /r
Then the slink commands are:

     lo MyProgram.obj
     lo MyResources.res
     windows
     file MyProgram.exe

Further general information about 64-bit FTN95

Programs compiled with FTN95 using the /64 option, use the AMD64 instruction set (subsequently adopted by Intel, and referred to as x64 or x86_64) which is almost universally available on modern PC's. This code cannot be mixed with legacy 32-bit code, nor can it access legacy 32-bit DLL's. 64-bit object files must be linked using the new utility SLINK64. This object file format is incompatible with all third-party link utilities.

The default size of INTEGER variables remains unchanged (231-1), so INTEGER*8 (8-byte) variables must be used to index extremely large arrays. These variables are implemented in a more efficient and natural way in 64-bits. Note that some arrays that would not fit in the old 4GB limit may still be indexable using default sized integers, for example a REAL*8 array of 2,000,000,000 elements would occupy nearly 16GB of memory, but could be indexed using default integers.

The main value of 64-bit compilation is that the available address space has increased from 4GB to approximately 1.8 x 1019 bytes! This means that for the foreseeable future (possibly forever!), the size of programs will be limited only by the amount of physical memory available on a system.

Arrays that are ALLOCATEd, or which are in COMMON or in MODULEs can exceed the 4GB limit, except that initialised arrays must fit within the .EXE or .DLL file to which they belong, and the the size of these files cannot extend beyond the 4GB limit. This is a Microsoft limit, but is fairly reasonable, since the time needed to load a 4GB file would be excessive!

COMMON blocks and MODULE arrays are allocated dynamically as a program starts in order to enjoy no 4GB restrictions. This is applied to all such storage blocks, because a program may exceed the 4GB limit even though each individual array lies within this limit.

Local arrays (static or dynamic) are restricted as in 32-bits. This is because it is not feasible to extend the hardware stack to sizes > 4GB, and SAVE'd variables must fit within the EXE or DLL file to which they belong. Users who require a very large local array, should put it in a COMMON block or MODULE referenced by only the one routine.

Since the code can be distributed across multiple DLL's plus an EXE file, the code itself is also not limited to 4GB - although this is not usually a serious concern.

The various 64-bit Windows operating systems provide less than the full 1.8 x 1019 address space, and the size of this space varies somewhat with the available physical memory on the system. Nevertheless, these limits are very generous and will increase as physical memory becomes more plentiful. In part, these limits are due to the fact that the paging mechanism itself requires memory.

For further information see https://msdn.microsoft.com/en-us/library/aa366778.aspx.

The pair of DLL's SALFLIBC64.DLL and CLEARWIN64.DLL in 64-bits take the place of the 32-bits SALFLIBC.DLL. Currently CLEARWIN64.DLL (which contains much more than ClearWin+) is compiled with Microsoft C++. In the future this may be absorbed into SALFLIBC64.DLL but will remain independent for use with third-party compilers.

Perhaps surprisingly, FTN95.exe and SLINK64.exe are 32-bit executables, and so still require access to SALFLIBC.DLL at compile time.

Note that the extra executables and DLL's to support 64-bit mode can coexist with those that support 32-bit operations because they have different names.

Contents of a clrwin.manifest file...

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
    <security>
      <requestedPrivileges>
        <requestedExecutionLevel level="asInvoker" uiAccess="false"/>
      </requestedPrivileges>
    </security>
  </trustInfo>
  <dependency>
    <dependentAssembly>
      <assemblyIdentity type="Win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0"
                        processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
    </dependentAssembly>
  </dependency>
</assembly>

64-bit CODE/EDOC in FTN95

The AMD 64-bit architecture

This architecture was invented by AMD, and was later adopted by by Intel when their own Itanium 64-bit architecture was not received with enthusiasm. Intel use the term x86-64. It is the basis of most modern PCs, and is targeted by FTN95 when the /64 switch is used.

The AMD 64-bit architecture has 16 general purpose integer registers:

RAX, RCX, RDX, RBX, RSP, RBP, RSI, RDI, R8, R9, R10, R11, R12, R13, R14, R15.

The bottom eight registers correspond to the 32-bit register set, and retain some of the same functionality. Thus RSP is the stack pointer and descends as the stack expands, RCX, RSI and RDI are used for string operations just as they are in 32-bits, and RAX is used by convention to return integer function values. RBP does not correspond in function to EBP, however it is given a special function in Silverfrost code (explained later), and should not be modified in normal circumstances.

All these registers hold 64-bits (8 bytes) and can therefore hold a pointer to anywhere in the 64-bit address space.

64-bit programs can access two sets of different floating point registers - the old floating point stack of eight 80-bit registers, and a set of registers designated XMM0 - XMM15, and known as the SSE registers. These registers can hold multiple values simultaneously - foour REAL*4 floating point values, or two REAL*8 values. They can also hold integer values. Thus these registers are 16 bytes in width. These registers do not 'know' what data they contain - so it is up to the programmer to keep track. In particular, if you load a REAL*8 value into an XMM register and wish to store it as a REAL*4, you must first use the appropriate conversion instruction.

Strangely, the old coprocessor stack instructions, do offer some functionality that is not present in the newer SSE instruction set - for example SIN and COS can be evaluated in one instruction.

Silverfrost CODE/EDOC conventions

Let us start with a simple executable example of a 64-bit CODE/EDOC sequence that simply sums a vector of REAL*8 values. It is not meant to be optimal because it does not use the parallel execution facilities of the SSE registers.

      REAL*8 vec(3),ans
      DATA vec/3.0d0,4.0d0,5.0d0/
      CALL sum(vec,3,ans)
      PRINT*,ans
      END

      SUBROUTINE sum(vec,n,ans)
      INTEGER n
      REAL*8 vec,ans
      CODE
       MOV_Q     RDX,=VEC   ! The '=' denotes a (non-immediate) constant or, as in this case, the address of an argument
       MOV_Q     R14,=N     ! Remember all addresses are 64-bit - hence the use of MOV_Q
       MOVSX_Q   R14,[R14]  ! Instructions and register names are case insensitive
                            ! N is only a 32-bit integer, so it is sign extended to 64-bits
       XORPD     XMM0,XMM0  ! This is one way to zeroise an XMM register it does a bitwise exclusive OR
1      ADDSD     XMM0,[RDX]
       ADD_Q     RDX,8      ! This uses an immediate constant
       DEC_Q     R14
       JNE       $1         ! Labels are denoted by a '$'
       MOV_Q     RCX,=ans
       MOVDQU    [RCX],XMM0 ! Store away the accumulated answer in the argument ANS
      EDOC
      END

This illustrates a variety of points

1) The instructions that operate on the integer registers can operate on 1, 2, 4, or 8 byte operands. These are distinguished by a suffix, thus the MOV instruction takes the forms MOV_B, MOV_H, MOV, MOV_Q.

2) Unlike the 32-bit code/edoc, the register name does not change when the operation operates on a smaller number of bytes.

3) Operations that work on 4 bytes of a register (MOV, ADD, etc) also clear the upper 4 bytes of the register, whereas 2-byte and 1-byte instructions do not change the other bytes of the register. This is a feature of the hardware, not a Silverfrost convention.

4) Labels are prefixed by a '$' when used, just as is the case in 32-bit mode.

5) When accessing a Fortran argument, you need to first access its address (an 8-byte quantity). The notation =N is used to access the address of argument N. The '=' notation can also be used to address a constant in memory, for example:

                     MOVSD    XMM3,=2.0d0
6) The MOVSX_Q instruction sign extends a 32-bit integer to 64-bits. In situations where a number is known to be non-negative. This extension can be obtained for free using point 3 above.

In general a good way to learn to write instructions inside CODE/EDOC is to compile simple code samples with the /EXPLIST option, which will display the instructions generated by the compiler line by line in essentially the same format that you will use.

Referencing COMMON, MODULE, and ALLOCATE'd variables

Because most COMMON blocks are allocated as the program starts up (as are large arrays in MODULE's) the simplest way to access these objects, as well as explicitly ALLOCATE'd arrays, is to take their address before entering the CODE/EDOC. For example:

        COMMON/FRED/alpha,beta(100),gamma
        INTEGER*8 alpha,beta,gamma
        INTEGER*8 addressof_beta
        addressof_beta=loc(beta)
        CODE
         MOV_Q    R10,addressof_beta
         MOV_Q    [R10+8],42   !This sets beta(2) to the value 42

The 64-bit address space

The 32-bit address space provided a theoretical maximum 232 (4 x 109) addressable bytes. Correspondingly, the 64-bit address space offers a theoretical maximum 264 (1.8 x 1019) addressable bytes. This means that, rather like in the early days of the 32-bit architecture, when a typical computer might have vastly less than 232 bytes (4 GB) of memory, the virtual address space is only very sparsely populated.

Indeed, the 64-bit virtual address space is so large that it isn't possible to provide page tables to cover the address space. This means that the amount of virtual address space available to a program is determined in a way that depends on the version of Windows in use, and the total amount of main memory on the computer (say 16 GB). This number is still extremely large. However, it is relevant if you use calls to VirtualAlloc to access high memory addresses in an absolute way.

Using the SSE registers for parallel computation

Instructions like MOVDQA will load a pair of REAL*8 numbers into an XMM register. Since these numbers are just bits, the instruction can also be used to move four REAL*4 numbers into an XMM register. However this instruction will fault if the data is not 16-bit aligned. This is problematic because REAL*4 and REAL*8 numbers are aligned wherever possible (EQUIVALENCE can prevent alignment) to 4 and 8 bytes respectively. In practice it turns out that the MOVDQU (which is reputed to be slower than MOVDQA) seems to run at the same speed for aligned data, and only somewhat slower for non-aligned data, but generates no alignment faults.

It is also worth reading this discussion about alignment issues: http://lemire.me/blog/2012/05/31/data-alignment-for-speed-myth-or-reality/


Exception Handling

This section describes aspects of excpetion handling under Win32. The sections are:

Trapping Win32 exceptions

Underflows


INTERRUPT subroutines

The SET_TRAP@ routine enables a program to catch a number of program events. Certain events, such as the QUIT trap, can interrupt a program at an arbitrary point. The routine which is used to catch such an interrupt must be specially written to cater for this. You can also use assembly code for this purpose. While this technique offers the greatest flexibility, the INTERRUPT SUBROUTINE offers a simpler mechanism which is normally adequate.

An interrupt subroutine must have no arguments and is normally terminated by stopping (STOP or CALL EXIT) or by calling JUMP@ to re turn to a label in an earlier routine. The following program illustrates this technique:

     EXTERNAL QUITH
     COMPLEX(KIND=2) :: LABEL
     COMMON LABEL
     CALL LABEL@(LABEL,*1)
     CALL SET_TRAP@(QUITH,0)
 1   READ *,N
     DO 2 I=1,N
 2   PRINT *,N
     PRINT *,'END OF LOOP'
     GOTO 1
     END

     INTERRUPT SUBROUTINE QUITH
     COMPLEX(KIND=2) :: LABEL
     COMMON LABEL
     CALL COU('Quit trapped!')
     CALL JUMP@(LABEL)
     END

By pressing Ctrl Break you can force this program to abandon the loop in progress, print a message, and return to read more data. Clearly this technique is of great value in writing interactive programs.

It is possible on return from an INTERRUPT SUBROUTINE to continue from the point at which execution was interrupted, provided that the subroutine neither performs Fortran input/output calls nor any other system routine. For example, such a subroutine might simply set a flag in a common block and return to the calling program.

If the INTERRUPT SUBROUTINE either calls a system routine or performs input/output, and the interrupt takes place from within a system routine or the Fortran input/output system, then unpredictable effects can result after return from the routine. However, control can be passed back to the program using the LABEL@ and JUMP@ routines.


DIRENT@

Platform | x64, Win32
Purpose | To obtain directory information.
Syntax | SUBROUTINE DIRENT@(PAT, ATTRIBUTE, RESULT, RESULT_ATTRIBUTE, & & RESULT_DATE, RESULT_TIME, FILE_SIZE, ERROR_CODE) CHARACTER (LEN=*) PAT,RESULT INTEGER (KIND= 2) ATTRIBUTE, RESULT_ATTRIBUTE,RESULT_DATE, & & RESULT_TIME,ERROR_CODE INTEGER (KIND=3) FILE_SIZE
Description | DIRENT@ returns directory information for files selected by PAT (e.g. A:\*.FOR). That is, each call of the routine searches for a single file in the directory and with the extension implied by PAT. The attribute of the first file returned is selected by setting ATTRIBUTE to one of the following values:
0 | Return a normal file
2 | Return a hidden file
4 | Return a system file
6 | Return a volume name
16 | Return a sub directory
 | The name of the file that has been found is returned in RESULT. Other file information is returned in RESULT_ATTRIBUTE, RESULT_DATE, RESULT_TIME and FILE_SIZE. The file attributes are returned in DOS coded form using bits 0 to 5 of the result. The date and time are returned in DOS compressed format. After the first call of the routine, ATTRIBUTE should be set to -1 in order to continue the search for another file with the same attribute as before. When no more files can be found, ERROR_CODE is returned with the corresponding system error code.
Notes | A sequence of calls to DIRENT@ with a given PAT must not be interrupted by a call to DIRENT@ with a different PAT. The FILES@ routine has a simpler interface and is usually preferred to this routine.
Example | PROGRAM DIRENT CHARACTER (LEN=20)::PAT,FILE INTEGER (KIND=2)::ATTR,DATE,TIME,EC INTEGER (KIND=3)::SIZE CALL COUA@('Input directory pattern:') READ '(A)',PAT EC=0 DO WHILE(EC == 0) CALL DIRENT@(PAT,0,FILE,ATTR,DATE,TIME,SIZE,EC) IF (EC == 0) PRINT '(A,I6,I6,I6,I6)',FILE, ATTR, DATE, TIME, SIZE !Do not call DIRENT@(PAT2,...) from here END DO END PROGRAM DIRENT


A index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

ABS | ALLOCSTR@
ACCESS_DETAILS@ | ANINT
ACHAR | ANY
ACOS | APPEND_STRING@
ADJUSTL | ASIN
ADJUSTR | ASSOCIATED
AIMAG | ATAN2
AINT | ATAN
ALL | ATTACH@
ALLOCATED |


B index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

BIT_SIZE

BTEST


C index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

CEILING

CENTRE@

CHAR

CHAR_FILL@

CHSEEK@

CHSORT@

CISSUE

CLEAR_BIT@

CLEAR_FLT_UNDERFLOW@

CLOCK@

CLOSEF@

CLOSEFD@

CMNAM

CMNAM@

CMNAMR

CMNARGS@

CMNUM@

CMPLX

CMPROGNM@

COMMAND_ARGUMENT_COUNT

COMMAND_LINE

COMPRESS@

CONJG

COS

COSH

COU@

COUA@

COUNT

CPU_TIME

CSHIFT

CURDIR@

CURRENT_DIR@

GET_COMMAND

GET_COMMAND_ARGUMENT


D index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

DATE@

DATE_AND_TIME

DATE_TIME_SEED@

DBLE

DCLOCK@

DIGITS

DIM

DIRENT@

DOS_ERROR_MESSAGE@

DOSERR@

DOSPARAM@

DOT_PRODUCT

DSORT@


E index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

EDATE@

EMPTY@

EOSHIFT

EPSILON

ERASE@

ERR77

ERRCOU@

ERRCOUA@

ERRNEWLINE@

ERRSOU@

ERRSOUA@

ERROR@

EXCEPTION_ADDRESS@

EXIT@

EXIT

EXP

EXPONENT


F index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

FDATE@

FEXISTS@

FILE_EXISTS@

FILE_SIZE@

FILE_TRUNCATE@

FILEINFO@

FILES@

FILL@

FLOOR

FORTRAN_ERROR_MESSAGE@

FPOS@

FPOS_EOF@

FRACTION


G index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

GET_CURRENT_FORTRAN_IO@

GET_CURRENT_FORTRAN_UNIT@

GET_FILES@

GET_KEY@

GET_KEY_OR_YIELD@

GET_PATH@

GET_PROGRAM_NAME@

GET_STORAGE@

GET_VIRTUAL_COMMON_INFO@

GETENV@

GETSTR@


H index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

HIGH_RES_CLOCK@

HUGE


I index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

IACHAR | ICHAR | IOR
IAND | IEOR | ISHFT
IBCLR | INDEX | ISHFTC
IBITS | INT | ISORT@
IBSET |  |


J index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

JUMP@


K index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

KIND


L index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

LABEL@

LBOUND

LCASE@

LEN

LEN_TRIM

LGE

LGT

LLE

LLT

LOG

LOG10

LOGICAL


M index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

MATCH@

MATMUL

MAX

MAXEXPONENT

MAXLOC

MAXVAL

MERGE

MIN

MINEXPONENT

MINLOC

MINVAL

MKDIR@

MOD

MODULO

MOVE@

MVBITS


N index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

NEAREST

NEWLINE@

NINT

NONBLK

NOT

NULL


O index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

OPENR@

OPENRW@

OPENW@


P index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

PACK

PERMIT_UNDERFLOW@

POP@

PRECISION

PRERR@

PRESENT

PRINT_HEX1@

PRINT_HEX2@

PRINT_HEX4@

PRINT_I1@

PRINT_I2@

PRINT_I4@

PRODUCT

PUSH@


Q index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

QUIT_CLEANUP@


R index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

RADIX

RANDOM

RANDOM_NUMBER

RANDOM_SEED

RANGE

READF@

READFA@

REAL

RENAME@

REPEAT

RESHAPE

RESTORE_DEFAULT_HANDLER@

RETURN_STORAGE@

RFPOS@

RRSPACING

RSORT@

RUNERR@


S index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

SAYINT

SCALE

SCAN

SECONDS_SINCE_1980@

SELECTED_INT_KIND

SELECTED_REAL_KIND

SET_BIT@

SET_DISK_ERRORS@

SET_EXPONENT

SET_FILE_ATTRIBUTE@

SET_SEED@

SET_SUFFIX@

SET_SUFFIX1@

SET_TRAP@

SHAPE

SHRINK_STORAGE@

SIGN

SIN

SINH

SIZE

SLEEP@

SOU@

SOUA@

SPACING

SPREAD

SQRT

SUM

SYSTEM_CLOCK


T index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

TAN

TANH

TEMP_FILE@

TEMP_PATH@

TEST_BIT@

TIME@

TINY

TODATE@

TOEDATE@

TOFDATE@

TOTIME@

TRANSFER

TRANSPOSE

TRAP_EXCEPTION@

TRIM

TRIM@

TRIMR@


U index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

UBOUND

UNPACK


V index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

VERIFY


W index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

WILDCHECK@

WRITEF@

WRITEFA@


X index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Empty


Y index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Empty


Z index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Empty


Salford_libary_routines

Silverfrost library routines

With a small number of exceptions, the names of Silverfrost library functions all end with the @ symbol. The exceptions are coloured grey in this index and noted in the text. The names of standard Fortran 95 intrinsic functions do not end with the @ symbol.


ACOS

Platform | x64, Win32, .NET
Purpose | To get the Arccosine (inverse cosine) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ACOS(X) REAL X
Description | X must be in the range -1. < X < 1.
Return value | The result is given in radians in the range 0 < result < p .


ASIN

Platform | x64, Win32, .NET
Purpose | To get the Arcsine (inverse sine) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ASIN(X) REAL X
Description | X must be in the range -1 < X < 1.
Return value | The result is given in radians in the range - p/2 < result < p /2.


ATAN

Platform | x64, Win32, .NET
Purpose | To get the Arctangent (inverse tangent) of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION ATAN(X) REAL X
Description | X can be any real value.
Return value | The result is given in radians in the range - p/2 < result < p /2.


CEILING

Platform | x64, Win32, .NET
Purpose | To get the least integer greater than or equal to its argument.
Class | Elemental function.
Syntax | INTEGER FUNCTION CEILING (A [,KIND]) REAL A; INTEGER KIND
Description | KIND is optional. If it is omitted the return type is the default integer type. If KIND is present it specifies the kind type of the return value.
Example | CEILING(-2.6) has the integer value -2.


COSH

Platform | x64, Win32, .NET
Purpose | To get the Hyperbolic cosine of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION COSH(X) REAL X
Description | The result has the same type as X.


FLOOR

Platform | x64, Win32, .NET
Purpose | To get the greatest integer less than or equal to its argument.
Class | Elemental function.
Syntax | INTEGER FUNCTION FLOOR(A [, KIND]) REAL A INTEGER KIND
Description | KIND is optional. If it is omitted the return type is the default integer type. If KIND is present it specifies the kind type of the return value.
Return value | FLOOR(2.6) gives 2. FLOOR(-3.4) gives -4.


LBOUND

Platform

x64, Win32, .NET

Purpose

To return all the lower bounds or a specified lower bound of an array.

Class

Inquiry function.

Syntax

INTEGER FUNCTION LBOUND(ARRAY [, DIM])
INTEGER DIM

Description

ARRAY is an array of any type, not a scalar. If it is a pointer it must be associated. If it is an allocatable array it must be allocated. DIM (optional) is a scalar integer with a value in the range 1 < DIM < n, where n is the rank of ARRAY.

The result is of default integer type. It is scalar if DIM is present; otherwise, the result is an array of rank one and size n, where n is the rank of ARRAY.

Return value

  1. For an array section or for an array expression other than a whole array or array structure component, LBOUND(ARRAY, DIM) has the value 1. For a whole array or array structure component, LBOUND(ARRAY, DIM) has the value:

    1. equal to the lower bound for subscript DIM of ARRAY if dimension DIM of ARRAY does not have extent zero or if ARRAY is an assumed-size array of rank DIM, or

    2. 1 otherwise.

  2. LBOUND(ARRAY) has a value whose ith component is equal to LBOUND(ARRAY, i), for i = 1, 2, ..., n, where n is the rank of ARRAY.

Example

If A is declared by the statement

REAL A(2:3,7:10)

then LBOUND(A) is [2, 7] and LBOUND(A, DIM=2) is 7.


MOVE_ALLOC

Platform | x64, Win32
Purpose | Moves the allocation from one variable to another.
Syntax | SUBROUTINE MOVE_ALLOC(A, B)
Description | Allocation is moved from A to B. A and B must be the same type, kind and rank. After the call A will appear deallocated. Memory is not physically moved.


RANGE

Platform | x64, Win32, .NET
Purpose | To get the range of the decimal exponent for integer or real numbers with a given kind type.
Class | Inquiry function.
Syntax | INTEGER FUNCTION RANGE(X)
Description | X is of type integer, real or complex. It may be a scalar or an array.
Return value | The result is a scalar integer giving the difference between the largest (positive) exponent and the smallest (largest negative) exponent that is used by the compiler for numbers of the given type and kind type.


SINH

Platform | x64, Win32, .NET
Purpose | To get the Hyperbolic sine of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION SINH(X) REAL X
Description | The result has the same type as X.


SIZE

Platform | x64, Win32, .NET
Purpose | To get the extent of an array along a specified dimension or the total number of elements in the array.
Class | Inquiry function.
Syntax | INTEGER FUNCTION SIZE(ARRAY [, DIM]) INTEGER DIM
Description | ARRAY is an array of any type. If it is allocatable it must be allocated. If it is a pointer it must be associated. If it is an assumed size array then DIM must be present and have a value which is less than the rank of ARRAY. If DIM is present it is a scalar in the range 1 < DIM < n where n is the rank of ARRAY.
Return value | The result has a value equal to the extent of dimension DIM of ARRAY or, if DIM is absent, the total number of elements of ARRAY.


TAN

Platform | x64, Win32, .NET
Purpose | To get the Tangent of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION TAN(X) REAL X
Description | If X is real it is an angle measured in radians.


TANH

Platform | x64, Win32, .NET
Purpose | To get the Hyperbolic tangent of the argument.
Class | Elemental function.
Syntax | REAL FUNCTION TANH(X) REAL X
Description | The result has the same type as X.


UBOUND

Platform

x64, Win32, .NET

Purpose

To get the upper bound or upper bounds for the indexes of an array.

Class

Inquiry function.

Syntax

FUNCTION UBOUND (ARRAY [, DIM])
INTEGER DIM

Description

ARRAY is an array of any type. If it is a pointer it must be associated. If it is an allocatable array, it must be allocated. If it is an assumed-size array, DIM must be present with a value less than the rank of ARRAY.

DIM is a scalar with a value in the range 1 < DIM < n, where n is the rank of ARRAY.

The result is a scalar integer or a one-dimensional integer array (of default type). It is scalar if DIM is present, otherwise, the result is an array of size n .

Return value

Case (i): For an array section or for an array expression, other than a whole array or array structure component, UBOUND(ARRAY, DIM) has a value equal to the number of elements in the given dimension; otherwise, it has a value equal to the upper bound for subscript DIM of ARRAY. If dimension DIM has zero size the result is zero.

Case (ii): UBOUND(ARRAY) has a value whose ith component is equal to UBOUND(ARRAY, i), for i = 1, 2, ..., n .

Example

If A is declared by the statement REAL A(2:3, 7:10) then UBOUND(A) is [3, 10] and UBOUND(A, DIM = 2) is 10.


Assignment statement

This is a representation of the formula j=2i+3. Multiplication is represented by an asterisk (*) and addition by a plus sign (+). The value stored with the name i is used in the calculation. The result of the expression is then assigned (=) to the store with name j.

You can also use a minus sign (-), an oblique (/) for divide and a double asterisk for raising to a power but (for INTEGERs) division yields the whole number part of the result (truncated towards zero). The standard mathematical rules of precedence apply whilst brackets can be used to change this order.

Constants (like the 3 used here) can appear within an expression. INTEGER constants may be signed but only the digits 0 to 9 should be used (do not include a decimal point).


Construct names

Any of the flow control constructs (not an IF statement) can be assigned a construct name, followed by a colon on the first line of the construct. If a name is used, the corresponding END statement that ends the construct must be followed by the same construct name. Construct names are not labels associated with the GOTO statement (although they behave like labels when used with DO, EXIT and CYCLE statements). They are simply used as annotations in order to match an END with its beginning.


Data edit descriptors

This PRINT statement takes the form:

PRINT "(list_of_descriptors)", list_of_values

There is one descriptor for each value in the list.


Data edit descriptors - A

The A descriptor is used for strings. The number of characters in the output (the field width) is equal to the length of the string. The field width w can be prescribed by using the form Aw. For example A20 is used for a string in a field width of 20 characters. If the string has more than w characters it is truncated. If it has fewer that w characters, it is padded out with leading spaces.


Data edit descriptors - E

The E descriptor is used in the form Ew.d or Ew.d Ee in order to present REAL values with an exponent part. w is the width of the field and d is the number of digits to be presented after the decimal point in the mantissa. In the second form of the E descriptor, the positive integer e is the number of digits in the exponent part. The field is padded out with leading spaces if required. w will need to be at least d+7 in order to provide spaces for the other characters. If the field width is too small for the value to be output, then it is filled with asterisks in order to flag the error.

The EN (engineering) descriptor is identical to the E descriptor apart from the fact that the exponent is always presented as a multiple of 3.

The ES (scientific) descriptor is identical to the E descriptor apart from the fact that a non-zero mantissa is always presented as a value greater than or equal to 1 and less than 10.


Data edit descriptors - F

The F descriptor is used in the form Fw.d in order to present REAL values without giving an exponent part. w is the width of the field and d is the number of digits to be presented after the decimal point. The field is padded out with leading spaces if required. Remember to provide space for a sign if the value might be negative.

If the field width is too small for the value to be output, then the field is filled with asterisks in order to flag the error. As an alternative, the G descriptor can be used instead of F. This works like F if there is enough space, otherwise it uses the E descriptor.


Data edit descriptors - I

The I descriptor is used for integers in the form Iw or Iw.m. w is the field width and m is the minimum number of digits that are to be displayed. With Iw the field is padded out with leading spaces if required. With Iw.m the field is padded out with either leading spaces or leading zeros depending on the value of m. If the field width is too small for the value to be output, then the field is filled with asterisks in order to flag the error. Remember to provide space for a sign if the value might be negative.

In addition to the I descriptor, B, O, and Z are used for binary, octal and hexadecimal representations.


Data edit descriptors - X

The X descriptor is used in the form wX in order to insert w spaces in the output.


Data types

INTEGER is one of five intrinsic data types. The others are

REAL

COMPLEX

LOGICAL

CHARACTER

The programmer can define additional (derived) data types.

i and j are examples of variables. A variable is a name that is used to identify stored data. The data type for the variable (INTEGER in this case) specifies the kind of data that is stored. INTEGERs are used to represent whole numbers that may be signed but which do not have a fractional part. INTEGERs are often used for counting purposes. They have the advantage that they are stored exactly without round-off error.

This is an example of a declaration. Declarations belong to the set of statements called specification statements that must come before any executable statements in the program.


REAL Data types

REAL is another of the intrinsic data types and x is a REAL variable.

REAL variables are used to store single numbers that can not be represented as INTEGERs. They may have a decimal part or they may be outside of the permitted range for integers. REAL variables can be used to store a wide range of values with varying degrees of precision. They have the disadvantage that, more often than not, there is an element of round-off error (usually, if there are enough significant figures in the representation, only fractions that are whole number powers of 2 will be stored without error).

The details of how REAL variables are stored in memory are normally hidden to the programmer. However, it is important to note that the representation is different to that for INTEGERs and that the associated operators (+, -, *, etc.) represent internal processes that depend on the type of their operands.


Free format

In a free format program, the text can be spaced out without any restrictions. Spaces are sometimes required in order to mark the end of a keyword or name (and must not be used within keywords and names) but apart from this, spaces can be used at will to provide a convenient layout for the program. Indentation is particularly helpful as a means of providing a visual impression of the various levels within the program.


Comments

An exclamation mark (!) is used to mark the beginning of a comment. Any text from the exclamation mark to the end of the line is ignored by the compiler and can be used by the programmer to annotate the code. Good annotation is vitally important in order to ease the task of program maintenance.


Logical operators

The logical operators begin and end with a full stop. For example:

.OR.

.AND.

.NOT.

They operate on the logical values true and false as follows:

a .OR. b is true if either a or b (or both) are true otherwise it is false.

a .AND. b is true if both a and b are true otherwise it is false.

Do not assume that a is evaluated first.

.NOT. a is true if a is false and vice-versa.


LOGICAL variables

For example:

LOGICAL xIsNegative
!Code to declare x and give x a value.
xIsNegative=x<0

A logical variable can take one of two states representing true and false. These are represented in programs by:

.TRUE.

.FALSE.

with full stops at the beginning and the end.

For input and output, the edit descriptor Lw is used with logical variables. w is the field width. The output is the letter T (for true) or F (for false), padded with leading spaces. On input only the first character (after optional leading spaces and an optional full stop) is significant. This must be either the letter T or the letter F.


Names

Names start with a letter, can be made up of letters, digits, and underscores ( _ ) and are up to 31 characters long.

Lower and upper case letters can be used to present a program but all lower case letters are translated to upper case by the compiler. One convention, used here, is to show Fortran keywords as upper case and to use lower and mixed case letters for other names in the program.


Order of precedence

Relational operators take precedence over the logical operators.

For example:

IF(0.0<x .AND. x<1.0) y=1.0/x

.NOT. takes precedence over .AND.

.AND. takes precedence over .OR.

When in doubt insert extra brackets.


Print statement

This is an example of a PRINT statement. A PRINT statement is used to send information to the standard output device (normally the screen). The asterisk (*) represents list directed output. With this kind of output, the programmer does not specify how the data is to be presented but rather a default presentation (format) is used for each item in the list.

Here there is only one item in the list that follows the asterisk, namely a string. A string is a sequence of characters enclosed either by double quotation marks (as here) or by single quotation marks. Use double quotation marks when the string includes a single quotation mark and vice-versa. If the string contains both kinds, insert a single quote twice in order to obtain one single quote in the output.


Prompting for input

WRITE(*, has the same meaning as PRINT. WRITE is used for general purpose printing and the asterisk here denotes the standard output device. If we want to prompt the user for input, then we could use PRINT but the output automatically advances to the next line which is not ideal.

WRITE(*,*) is the same as PRINT * so the second asterisk in WRITE denotes list directed output. However, with list directed output, it is not possible to suppress the linefeed. In place of the second asterisk we use a format specifier to describe how the output is to appear. This takes the form of a string enclosed by round brackets. The letter a indicates that the output is a string.

The third argument of WRITE is used to suppress the linefeed.


Read statement

This is an example of a READ statement. This form of the READ statement is used to get information from the standard input device (normally the keyboard). The asterisk (*) represents list directed input. With this kind of input, the programmer does not specify exactly how the data is spaced out but only the order and the type of each component in the list of data.

Here there is only one item in the list that follows the asterisk, namely an INTEGER variable showing where the input data is to be stored.


Relational operators

The following operators can be used to compare INTEGER expressions or to compare REAL expressions.

> Greater than
< Less than

The following operators can be used to compare INTEGER expressions. Their use to compare REAL expressions is not recommended because of the likelihood of round-off error.

== Equal to
>= Greater than or equal to
<= Less than or equal to
/= Not equal to

The result of a comparison is one of the two logical values true and false.


Simple statement

A single statement, not a group of statements nor a flow control construct. Otherwise use an IF construct.


Statement block

A sequence of one or more statements in an IF, DO or CASE construct. IF statements and flow control constructs may be included provided that they are correctly nested one within another.


Statements

Statements are either specification statements or executable statements. All specification statements are placed before the first executable statement. Specification statements describe the environment in some way. Executable statements describe the actions to be carried out by the program.

Usually each statement is presented on a single line of the program and a linefeed marks the end of the statement. Up to 132 characters (including spaces) can appear on one line.

More than one statement can be written to a line if a semi-colon (;) is used to mark the end of each statement other than the last on the line.

A long statement can be continued on the next line if an ampersand (&) is added to the end of the line to be continued. If an ampersand is also placed at the beginning of the continuation line, then any white space between the two ampersands is ignored (can be used for example with long strings).

By repeated continuation, a single statement can occupy as many as 40 lines.


REAL expressions

The arithmetic expression x/3.0-0.9E6 is evaluated by taking a copy of the variable x, dividing by 3.0 and then a REAL constant value represented by 0.9E6 is subtracted. The resulting value is used in the PRINT statement. Expressions may be used as arguments in this way. It is not necessary to explicitly store the result before it is used.

The operators +, -, * (for multiply), / (for divide) and ** (for raising to a power) are used in REAL expressions to give the expected mathematical result (or rather the nearest approximation possible given the amount of memory used to store each variable). A REAL value can be raised to an INTEGER or a REAL power with the exception that a negative value can not be raised to a REAL power.

REAL constants contain a decimal point (represented by a full stop) or a letter E or both. 0.9E6 represents 0.9x106 and the letter E begins the exponent part of the constant which is an integer (possibly signed). Before the letter E is the mantissa that may be signed and is made up of digits and possibly a single decimal point. The mantissa is not optional and if the exponent part is absent, the mantissa must contain a decimal point.


Calling FTN95 from C/C++

Introduction

CHARACTER variables

Arrays

INTEGER, LOGICAL and REAL


Using MK32

Introduction

Tutorial

Reference

Command line options

Makefiles

Macros

Special macros

Targets

Special targets

Rules

Implicit rules

Files

Diagnostics


ABS

Example illustrating operations on integer sets

MODULE INTEGER_SETS
INTEGER, PARAMETER :: MAX_CARD = 100

TYPE SET
 PRIVATE
 INTEGER CARD
 INTEGER MEMBERS(MAX_CARD)
END TYPE SET

INTERFACE OPERATOR (.IN.)
 MODULE PROCEDURE MEMBER_OF
END INTERFACE

INTERFACE OPERATOR (*)
 MODULE PROCEDURE INTERSECT
END INTERFACE

CONTAINS

INTEGER FUNCTION CARD(S)
 TYPE (SET) S
 CARD = S%CARD
END FUNCTION CARD

LOGICAL FUNCTION MEMBER_OF(X, S)
 INTEGER X
 TYPE (SET) S
 MEMBER_OF = ANY(S % MEMBERS(1 : S%CARD) .EQ. X)
END FUNCTION MEMBER_OF

TYPE (SET) FUNCTION INTERSECT(S1, S2)
 TYPE (SET) S1, S2
 INTEGER I
 INTERSECT % CARD = 0
 DO I = 1, S1%CARD
  IF ( S1%MEMBERS(I) .IN. S2 ) THEN
   INTERSECT%CARD = INTERSECT%CARD + 1
   INTERSECT%MEMBERS(INTERSECT%CARD)=S1%MEMBERS(I)
  END IF
 END DO
END FUNCTION INTERSECT

TYPE (SET) FUNCTION BUILD_SET(V)
 INTEGER V(:)
 INTEGER J
 BUILD_SET%CARD = 0
 DO J = 1, SIZE(V)
  IF (.NOT.(V(J) .IN. BUILD_SET )) THEN
   IF (BUILD_SET%CARD < MAX_CARD) THEN
    BUILD_SET%CARD = BUILD_SET%CARD + 1
    BUILD_SET%MEMBERS(BUILD_SET%CARD) = V(J)
   ELSE
    PRINT *,'Maximum set size exceeded'
    STOP
   END IF
  END IF
 END DO
END FUNCTION BUILD_SET

FUNCTION VECTOR(S)
 INTEGER, POINTER :: VECTOR(:)
 TYPE (SET) S
 INTEGER I, J, K
 ALLOCATE( VECTOR(S%CARD) )
 VECTOR = S%MEMBERS(1:S%CARD)
 DO I = 1, S%CARD - 1
  DO J = I + 1, S%CARD
   IF (VECTOR(I) > VECTOR(J) ) THEN
    K = VECTOR(J)
    VECTOR(J) = VECTOR(I)
    VECTOR(I) = K
   END IF
  END DO
 END DO
END FUNCTION VECTOR

END MODULE INTEGER_SETS


.NET enumerated types

A .NET enumerated type (or enumerator) has a name and consists of a list of named constant integer values. When you define an enumerator you define a type and give it a name (this type can be considered to be a special kind of class). The definition of a .NET enumerator is usually located within a namespace in which case its name takes the form <namespace>.<type_name>.

For example there is system enumerator called CallingConvention that lies in the namespace called System.Runtime.InteropServices. The full type name for the enumerator is thus System.Runtime.InteropServices.CallingConvention.

In FTN95 you could give this type the name MY_CONVENTION and access it in your program by using the keyword ENUM as follows.

CHARACTER(LEN=60),PARAMETER::CONVENTION="System.Runtime.InteropServices.CallingConvention"
ENUM(CONVENTION)::MY_CONVENTION

This enumerated type has a component Winapi whose integer value is available in a FTN95 program by using the % operator:

INTEGER k
k=MY_CONVENTION%Winapi

These two fragments are equivalent to:

CHARACTER(LEN=60),PARAMETER::CONVENTION="System.Runtime.InteropServices.CallingConvention"
INTEGER k
k=CONVENTION%Winapi

This means that the standard % operator (for selecting a member of a Fortran derived type) has been extended so that it can also be used to select a component of a .NET enumerated type.

The component Winapi is unique with respect to case-insensitive matches so we do not need to surround it with quotation marks (see Manipulating .NET objects).


Installed Samples

Please see the sub-topics for information.


Calling Fortran from .NET - A Simple C# Form

This topic takes the form of a tutorial that describes how to create a C# form. The form is linked to a Fortran DLL that carries out an elementary processing task.

The approach described here has now been subsumed into Visual ClearWin (see Getting started for a set of Visual ClearWin samples).

First we create a new project by selecting New from the main File menu. From the Project types select "Visual C# Projects" and then from the Templates select "Windows Application". The default name will be WindowApplication1.

You will be presented with a blank form called Form1 in design view. Now use the Toolbox to add some components to this form. If the Toolbox is not visible on the left hand margin then select Toolbox from the main View menu.

The Toolbox appears when the mouse cursor hovers over the Toolbox bar and is automatically hidden when the mouse is moved away from the Toolbox. Click on the pin icon at the top of the Toolbox to switch off Auto Hide.

We will create a form that looks like this:

The form contains two Labels for the text "Input" and "Output", two Textboxes for the input and output fields and a Button that will be linked to a Fortran procedure that converts the input to the output.

Take care to create the Textbox for the input first because the first control automatically has the focus when the form is loaded. If you forget to do this then you should change the TabIndex property for this control to zero.

Click on TextBox in the Toolbox and drag a rectangle with a suitable size and position on the form. Keep the default name textBox1.

Do the same again to create textBox2 for the output. Use the Properties window to make this ReadOnly.

Click on Button in the Toolbox and drag a rectangle for the button. Keep the default name button1 but, in the Properties window, change the text to "Process".

Click on Label in the Toolbox and drag a rectangle first for the text "Input" and repeat for "Output".

When the form is loaded the user will enter a number as input and then click on the button in order to view the result of some calculation. The processing will take place in a Fortran DLL. First we enter code to respond to a button click. Later we will consider out how to prevent the user from typing invalid characters into the input box.

Using the design view of the form, double click on the button. This switches to the code view for the form and plants code for a function called button1_Click (as well as what you can see, code for button1_Click is also added in the "Windows Form Designer generated code" region).

Now add the following code as the body of the function button1_Click.

double v;
if(Double.TryParse(textBox1.Text, System.Globalization.NumberStyles.Any, null, out v))
     textBox2.Text = Project1.Process(v).ToString();
else textBox2.Text = "Error";

Project1.Process has not been written yet so the code will not compile.

Now we need to add a new project to the solution. This project is a Fortran DLL called Project1 containing a function called Process.

From the main File menu, select New . Now from the Project types select "FTN95 Projects" and the from the Templates select "FTN95 .NET project". Use the default name Project1.

Right click on Project1 in the Solution Explorer window and select Properties from the popup menu. In the dialog box for Project1 Property Pages, change the Output File Type to DLL. Close this dialog.

Right click again on Project1 in the Solution Explorer window and now select Add and then Add New Item. Select "FTN95 free format" source file in the resulting dialog box and use the default file name (freeformat1.f95).

Copy the following code into this file.

FUNCTION Process(x)
ASSEMBLY_INTERFACE (name="Process")
INTEGER,PARAMETER::d=selected_real_kind(10)
REAL(d)::Process
REAL(d),INTENT(IN)::x
Process=x*x
END

The use of the INTENT(IN) attribute for x is not essential.

The ASSEMBLY_INTERFACE serves two purposes. a) It means we can use "Process" rather than "PROCESS" as the C# name for the function and b) it means that the argument x is passed by value (the alternative is to use a pointer when calling Process from C# but to do this we would have to make the C# code "unsafe").

Build the DLL.

The final step is to add a reference to the DLL. Right click on the WindowsApplication1 project in the Solutions Explorer window and select Add Reference. In the Add References dialog, select the Projects tab and then select Project1.

Finally build the solution and run the application (press F5).

At the moment the user is allowed to type any character string into the input box and it would be better if the input were restricted to valid floating point numbers. In order to add code to filter the input, go back to the design view of the form and double click on the input Textbox. This switches to the code view and adds outline code for a function called textBox1_TextChanged. You can now add code to this function in order to filter the user input. For further information on C# forms see the Samples 2 and and Sample 6 in Installed Samples and also Windows Forms.

It is possible to create user controls that inherit attributes and methods from standard controls such as the TextBox control. These emulate features from ClearWin+ that are relevant to this context. For example, there are controls called Double_Box and Int32_Box that are derived from TextBox and that automatically filter the input for floating point values and integer values respectively.

To use a Double_Box instead of a TextBox for input, first use the design view of the form to select and delete textBox1. Now right click on the Toolbox and select Customise Toolbox. Select the .NET Framework Components tab and click on the NameSpace column header to find Salford.Windows.Forms. Click on the check box for Double_Box. When you close the customising dialog, you will see the new control in the toolbox. (Note that you will only need to customise the toolbox once and also that you can use the Toolbox right-click popup menu to create a new tab in the Toolbox for Silverfrost controls.) Select a DoubleBox from the Toolbox and drag a rectangle on to the form. By default this will have the name double_Box1.

Now view the properties of double_Box1 and note the additional properties that appear in the Data category. These are AutoCorrect, ExpFigs, Maximum, Minimum and Sigfigs. Select each in turn and note the description in the Descriptions pane.

Change the body of the function button1_Click to:

if(doubleBox1.ioStat==0) textBox2.Text =
                Project1.Process(double_Box1.Value).ToString();
else textBox2.Text = "";

Finally rebuild the solution and run the application (press F5). Note the behaviour using both valid and invalid data entries. Run the application again using range checking (setting values for Maximum and Minimum in the Properties Window) and a using different value for AutoCorrect.

When the program is run with AutoCorrect set to true, an invalid input (such as the unfinished entry "1.0e"), generates a warning when the button is clicked. The warning takes the form of a warning style icon that appears to the right of the input box. When the mouse hovers over the icon, a tooltip appears that displays the warning. A different warning message indicates an entry that was out of range.

A similar effect is obtained when AutoCorrect is set to false but when the button is clicked:

a) an invalid input value is not automatically corrected,

b) the code must use the ioStat attribute to test if the input is valid, and

c) when the input is invalid a flashing error style icon appears.

The possible values of ioStat are:

0 No error.
1 An invalid value.
2 The value is less than the prescribed minimum.
3 The value is greater than the prescribed maximum.

If AutoCorrect is set to true, once the focus is lost (i.e. a control other than the input box has the focus), ioStat will aways be zero because any invalid value will have been corrected.


/DREAL compiler option

/DREAL

specifies that FTN95 should treat all single precision (KIND=1) variables and constants as double precision (KIND=2). Correspondingly, all COMPLEX variables are treated as COMPLEX(KIND=2). It is not necessary to use the generic forms of the intrinsic functions when using /DREAL. If /DREAL is used, the compiler becomes aware of the allowable extensions. (Note that FTN95 does not act as a standard-conforming compiler when /DREAL is used.)

/DREAL can make it very easy to compile and execute a single precision program that has produced valid results on a machine with a more accurate single precision floating point representation, which would otherwise not work satisfactorily without a major conversion.


/HARDFAIL compiler option

/HARDFAIL

The use of the Win32 /HARDFAIL option causes run time errors to produce a machine level message and return to the operating system, rather than entering the symbolic debugger. This is sometimes useful if the program contains assembler code (within CODE/EDOC).


/INTL and/INTS compiler options

/INTL and /INTS

With /INTS, every variable of type INTEGER will become INTEGER(KIND=2) unless it
            is explicitly declared as INTEGER(KIND=3) or INTEGER(KIND=1). Similarly every
            constant of type INTEGER will become INTEGER(KIND=2) unless one or more of the
            following is true:

  • Its value lies outside the range -32768 to +32767.

  • It has an explicit kind specifier (e.g. 125_1 and 256_3).

  • It is followed by the letter L (for INTEGER(KIND=3)) or B (for INTEGER(KIND=1)). (These forms are not allowed when the /ISO option is used.)

If the /INTL option is used (this is the supplied default), every variable of
            type INTEGER will become INTEGER(KIND=3) unless it is explicitly declared as
            INTE GER(KIND=2) or INTEGER(KIND=1). Also every constant of type integer will
            become INTEGER(KIND=3) unless it is followed by an explicit kind specifier or
            the letter S (for INTEGER(KIND=2)) or B (for INTEGER(KIND=1)).

Unlike FTN77, FTN95 applies /INTS and /INTL to files that are INCLUDEd in the current file.

FTN95 only acts as a standard-conforming compiler when /INTL is used.


/LGO compiler option

/LGO

FTN95 provides a load-and-go facility via the /LGO compiler option so that programs can be quickly compiled, loaded and executed. /LGO can be used with large and complex programs, even those that require the use of libraries. No permanent object or executable file is produced (although there must be enough disk space to accommodate a temporary object file). These features make this facility invaluable for teaching, testing and development where repeated compi lations and test runs are the norm.

If you wish to keep a copy of the current executable file then the /LINK option should be used. /LINK has no effect when used with /LGO.

Most of the other compiler options are available together with a number of extra options which allow the following:

  • specification of relocatable binary library and input files,

  • underflow trapping,

  • interactive debugging.

The load-and-go facility is invoked by the /LGO option. For example:

FTN95 MYPROG /CHECK /LGO

would compile, load and execute the program held in the source file MYPROG.F90. The order of options on the command line is immaterial, except when an option requires a name, in which case the name must follow it.

The Win32 options /BREAK and /DBREAK both imply /LGO. These options also imply either /DEBUG or /CHECK.

These options are summarised in the following table for easy reference.

Option | Debug code planted | Check code planted | Immediate entry to debugger | /LGO implied
/DEBUG | yes |  |  |
/CHECK | yes | yes |  |
/BREAK (Win32) | yes | yes | yes | yes
/DBREAK (Win32) | yes |  | yes | yes


/LINK compiler option

/LINK

When the compiler is invoked with the /LINK option, for example

FTN95 MYPROG /LINK

the linker is automatically invoked after compilation is com plete (assuming, of course, that no compilation errors have occurred). The resultant object code is loaded and a corresponding .EXE file is produced (a .OBJ file is not saved). The example above would create a run file called MYPROG.EXE .

If you wish to load other relocatable binary files, in addition to that produced by compilation of the named source file, the /LIBRARY compiler option (or the corresponding directive) should be used.

Relocatable binary libraries and input files

The use of the /LGO and /LINK options is not restricted to programs that require only the FTN95 library. Other system or user relocatable binary (RLB) libraries and RLB input files can be specified by using one or both of the following methods:

  • By using the /LIBRARY option in the FTN95 command line. For example:

FTN95 MYPROG /LGO /LIBRARY GKSLIB

  • By using a LIBRARY directive (which, in fixed format, must commence at or beyond column 7) in the source file.

LIBRARY '<pathname>'

where <pathname> is the name of the file. For example:

LIBRARY 'C:\GRAPHICS\GKSLIB'

Use of a LIBRARY directive ensures that no RLB library or input file is forgotten when loading a program as the directives are always pre sent in the source file.

If a library filename does not include path information, the current directory is searched, followed by the directory containing the FTN95 compiler.

Notes:

  • The compiler will automatically search first for an RLB library or RLB input file with a name suffixed by .OBJ, and then for the un suffixed filename, even if the library or input filename specified in the FTN95 command does not contain the suffix.

  • Dynamic link libraries are not specified on the LIBRARY directive. Under Win32, DLLs are normally located either in the directory for the executable or on the PATH.


/LIST compiler option

/LIST <pathname> or /LIST

The /LIST compiler option generates a program listing on a given file. If <pathname> is omitted, then the default name for the listing file is <filename>.LIS.

When a compilation listing is produced, it always contains the following information:

  • Date and time of compilation

  • Source file pathname

  • Compiler version number

  • Compiler options in use

  • Source statement listing

  • Error, warning and comment messages.

The listing consists of all source statements and directives, numbered from line 1. If an INCLUDE file is listed, its numbering starts from 1 and numbering reverts to that of the previous file once the INCLUDE file has been processed. At the end of the listing of each program unit, three blank lines are output. Some error messages, warnings and comments are inter spersed with the listing of statements and directives; others ap pear at the end of the listing of a program unit. A number of other features of the listing should be noted:

  • INCLUDEDd files are not listed unless the /LIST_INSERT_FILES option is also used.

  • The line numbers of an INCLUDEd file are preceded by a slash character, which itself is preceded by two digits specifying the level of nesting of the INCLUDE directive.

  • Non-printing ASCII characters are represented by a query character (?) on the compilation listing. Note that the actual non-printing character is, however, treated as part of the source line to be processed.

  • The relative address of each statement is printed in hexadecimal at the right of the line (unless /NO_OFFSET is also used). Relative addresses allow the user to locate the source of run-time errors which occur in parts of the program where no checks have been specified. This is the byte address of the first machine instruction corresponding to the statement, relative to the start of the current program unit. The relative address is incremented for each statement for which the compiler generates code. Code generation ceases for the remainder of the source file when a compilation error is found (unless /PERSIST is also used).

  • For fixed format files the information in positions 73 to 80 is separated from the remainder of the line by several spaces. This makes the problem of lines overflowing past column 72 more noticeable from the compilation listing. Note, however, that in formation contained in positions 73 to 80 is overwritten in the source listing by the address offset information (unless /NO_OFFSET is also used ).


/LOGL and /LOGS compiler options

/LOGL and /LOGS

With /LOGS, every variable of type LOGICAL will become LOGICAL(KIND=2) unless it
            is declared as LOGICAL(KIND=1) or LOGI CAL(KIND=3) and every constant of type
            LOGICAL will become LOGICAL(KIND=2).

If the /LOGL option is used (this is the default), every variable of type
            LOGICAL will become LOGICAL(KIND=3) unless it is declared as LOGICAL(KIND=1) or
            LOGICAL(KIND=2). Also, every constant of type LOGICAL will become
            LOGICAL(KIND=3).

FTN95 only acts as a standard-conforming compiler when /LOGL is used.


/PARAMS compiler option

/PARAMS

The /PARAMS option is provided to specify command line informa tion for the program. This option is necessary in order to stop FTN95 from scanning the whole command line before the user's program is executed.

For example, suppose that NEWPROG.F90 obtains two filenames FILE1 and FILE2 by means of calls to the system routine CMNAM. These filenames could be specified as follows:

FTN95 NEWPROG /LGO /PARAMS FILE1 FILE2

An illustrative program appears with the description of the CMNAM routine.


/SAVE compiler option

/SAVE

By default, local variables are stored dynamically on the stack. Space for dynamic variables is reserved on entry to a program unit; the space is freed, and all data values are lost on RETURN. The alternative is to store variables statically. Static variables maintain their values until execution terminates. The following types of variables will automatically be static:

  • Any variable that appears in a SAVE statement.

  • Any variable in a program unit that contains a blank SAVE statement.

  • Any variable that appears in a DATA statement.

  • Any COMMON block variable.

  • Any variable that is initialised, e.g. INTEGER::I = 1

All other variables will be made static if the /SAVE option is used. However, it is better programming practise to use SAVE state ments in program units where static storage is required, rather than relying on the use of a /SAVE compiler option.


/TIMING compiler option

/TIMING

Overview

FTN95 now includes an in-built profiling tool called TimingAnalysis. TimingAnalysis accurately measures CPU time spent in each subroutine of a Fortran program. It allows program developers to discover the most CPU intensive areas of a program so that these can be improved. Frequently, it will be found that over 90% of the program CPU time is in less than 10% of the code.

TimingAnalysis produces a report giving statistics on CPU time, number of calls to and from routines, and the number of page faults per routine. CPU time statistics are collected on both an exclusive (only the single routine) basis and an inclusive basis (the routine and everything called below it). In addition to the reports, a file suitable for importing into a spread sheet is produced.

To use the TimingAnalysis all that is required is to compile with the /TIMING option. This can be done within Visual Studio .NET by selecting the Project Properties and navigating to Compiler Options->Debugging->Plant timing information and set this option to Yes. If compiling from the command line then the /TIMING option should be used.

TimingAnalysis creates output files containing summary information for the program executed. If using TimingAnalysis from Visual Studio .NET then these files will be placed in the project output directory and will have extensions of .TMR and .TMO. The .TMR file contains summary analysis of the executed program and the .TMO file contains a (by default) tab seperated file ready for importing into a spreadsheet program such as Microsoft Excel.

From the command line only .TMR files are produced by default. To specify a .TMO file from the command line an environment variable called TIMINGOPTS should be created and set as follows:

set TIMINGOPTS=/TMO /DLM tab

where /TMO indicates that a .TMO file should be produced and DLM specifes the delimeter character to be used in the .TMO file. The default is tab and can be any character other than '-' or '/'.

How Timing Analysis Works

TimingAnalysis uses the RDTSC instruction to access the Pentium cycle counter. This counter gives the number of cycles that have passed since the computer started up. This allows direct measurement of the time short segments of code take to execute. The times labeled as CPU time in TimingAnalysis reports are actually elapsed time spent in a routine, to a very high resolution. This time will include time waiting for I/O to the disk (including paging) or waiting at a prompt to the screen. With this in mind, the reports can be very useful.

The /TIMING compile option causes the compiler to produce code to plant code to do a call to the timing routine when a routine is called. TimingAnalysis stores the CPU timer and begins the work of collecting information. Any overhead introduced by using TimingAnalysis is removed when the reports are produced. The work of collecting and saving the timing information can take significant time and can double the run time of a program which does a lot of calls. This time spent is never counted in that of the timed program's subroutines and does not need to be compensated for.

After the subroutine entry information is stored, TimingAnalysis again stores the CPU timer and returns to the called subroutine. When TimingAnalysis is called at return time, it performs the subroutine exit measurements similar to the way it did at routine entry and then returns to the caller of the subroutine just timed. When the program reaches termination TimingAnlaysis produces reports and the program exits.

Understanding TimingAnalysis Reports

The timing analysis report is produced twice, once sorted on exclusive CPU secand again sorted on inclusive CPU sec. The second part of the report continues for one page or until the inclusive Cpu% drops below 4.0%. The report header indicates the sort key used for the report.There are two groups of information on the page, the exclusive information which applies only the routine itself and the inclusive information which applies to the routine and everything it calls and below. The following decribes the columns in the .TMR file produced by TimingAnalysis.

Exclusive Statistics

Called - This is the number of times this routine is called by other routines.
Calls - This is the number of calls made to other routines directly by this routine.
Page Flts - This is the number of times a page had to be brought in from disk during execution of this routine.
P/F% - The percentage of page faults encountered in this routine.
Cpu sec -This is the total CPU time in seconds spent in this routine.
Avg CPU -This is the total CPU time divided by the number of calls to this routine. This number is scaled to allow good significance to be displayed in a small space. It is followed by an indicator of its units which can be s for seconds, m for milliseconds, or u for microseconds.
Cpu% -This is the percent of the CPU time spent in this routine.
CumCpu% -This is a running sum of the column to its left and provides an easy way to determine how many routines comprise what percent of the total CPU time.

Inclusive Statistics

Called - This is the number of calls to this routine and all calls made by routines called by this routine. For the main program, this is the total of all calls made during the program execution.
Calls - This is the total of the calls made by this routine and the routines called by this routine. It is equal to inclusive Called minus exclusive Called and was included on the report mainly for symmetry.
Cpu sec - This is the total CPU time spent in this routine and all routines it calls. This is in effect viewing this routine as the start of a subsystem of the whole program.
Cpu% - This is the percentage of the CPU time that this routine and all called below it comprise.

Spreadsheet Output

When the /TMO option is given in the TIMINGOPTS environment variable or when the timing option is used within Visual Studio .NET, a file suitable for importing to a spread sheet or other utility is produced. This file has the same name as the timing report file, with the .TMO suffix. If the /DLM option is given a delimiter character can be given which can be: "comma", "tab", or any punctuation character. This character will then be used as a field separator. The .TMO file contains the basic data present in the timing report. The first line contains names of the quantities. The remainder of the file contains one line per called routine with that routine's data.

Using TimingAnalysis Reports

There are many ways to use TimingAnalysis reports to improve a program's performance. First of all, look at how many times each routine was called. Do these coincide with your understanding of the program? Could any be called in a loop they should not be in? When a routine is called many times but has a very short average execution time, there may be much time wasted in the call alone. It may be a good idea to find a way to perform the function in-line or compute a group of results in advance and simply access it where the call was.

The paging information can be very useful as well. In routines with high paging, look for multi-dimensional arrays which are accessed primarily with the right-most subscripts varying fastest.

The CPU time is the most useful statistic for improving program performance. The TimingAnalysis report is arranged so that you can easily determine a set of routines which comprise any particular percent of the whole run time. These are the routines which should be studied for possible improvement.

It is important to note what the time assigned to a routine includes. All routines which are compiled with the /TIMING option have their time assigned to them. Any routines not compiled with this option will have their time assigned to the routine which called them. All FORTRAN library routines such as SIN, ATAN, LOG, etc. have their CPU time included in the routines which call them. FORTRAN I/O statements can use a lot of CPU time and this is also assigned to the routines containing the I/O statements. The CPU time used to call another timed routine and transfer arguments is assigned to the calling program. The CPU time used in the return from the called program is assigned to the called program.

Restrictions

The maximum call depth within TimingAnalysis is 2048.

Recursion (a routine calling itself), a Fortran extension, will cause the inclusive statistics to be incorrect for the recursively called routines.

Alternate subroutine returns are not supported and will lead to incorrect timing results.


/UNDERFLOW compiler option

/UNDERFLOW

The use of the Win32 /UNDERFLOW option ensures that the first occurrence of underflow in an arithmetical computation is treated as a failure and is not ignored as would otherwise be the case. A large number of occurrences of underflow during execution can result in long execution times because of the way in which the underflow condition is treated. If an underflow is trapped, the message

ERROR: Floating point arithmetic underflow

is output and the interactive debugger is entered. If underflows occur during program execution and the /UNDERFLOW option is not used, a message is output at the end of the run specifying the number of underflows that have occurred.

See also Underflows.


/ZEROISE compiler option

/ZEROISE

In the following description, local variables and arrays that are given the SAVE attribute are called static variables.

FTN95 presets the value of all static variables to zero. This is the case even when /ZEROISE is not applied. A related option /SAVE applies the SAVE attribute to all local variables and arrays.

/ZEROISE is provided for use with /UNDEF (and options such as /CHECKMATE that imply /UNDEF). Otherwise /ZEROISE has no impact on the code generated by FTN95.

When used together, /ZEROISE over-rides /UNDEF for static variables and presets these values to zero rather than the "undefined" state. /ZEROISE is provided for use with Win32 and .NET but not for x64.


/CHECK_ALIAS compiler option

/CHECK_ALIAS

/CHECK_ALIAS can be used with /CHECK (or options such as /CHECKMATE that imply /CHECK) in order to provide runtime checking for aliased arguments. When used without /CHECK it has no effect.

Note 12.21 of the Fortran 95 Standard states:

"If there is a partial or complete overlap between the actual arguments associated with two different dummy arguments of the same procedure and the dummy arguments have neither the POINTER nor TARGET attribute, the overlapped portions shall not be defined, redefined, or become undefined during the execution of the procedure."

This restriction is rarely needed but may be required by compilers that produce highly optimised code.

Illustrations of code that fail this requirement are provided in the Polyhedron diagnostic test suite.

Here is the source code for alias1.for in the Polyhedron suite:

program alias1
 x = 1.0
 call sub(x,x)
 print *,x
end
subroutine sub(x,y)
 x=2.
 y=3.
end

This code fails first at "x=2." because x overlaps y for this call to sub.

Here is the source code for alias2.for in the Polyhedron suite:

program alias2
 real x(10)
 do i =1,10
   x(i) = i
 enddo
 call sub(x(1),x(5))
 print * ,x
end
subroutine sub(x,y)
 real x(*) , y(*)
 y(1) = 0
 x(10) = 0
end

This code fails at "y(1) = 0." because y overlaps x for this call to sub.

FTN95 detects these and similar errors at runtime when using /CHECK_ALIAS combined with /CHECK.

FTN95 can be configured (using /CONFIG) to make /CHECK_ALIAS the default. When configured, /CHECK_ALIAS will always be included when /CHECK is used.


Default compiler options

Many of the above options have a corresponding opposite. For example /-INTL is the opposite of /INTL. If the default setting is changed by using the /CONFIG option, then there are occasions when you may wish to use the opposite option in order to temporarily restore the original default. The configuration screen that appears when using /CONFIG indicates which options can be configured and hence have an opposite.


Topic

.

© 2004 Silverfrost Ltd.


AddControl@

Platform

.NET(including Win32)

Purpose

To add a control at run time.

Syntax

SUBROUTINE AddControl@(dialog, Class, controlName, x, y, w, h)
VCdialog dialog
STRING Class, controlName
INTEGER x, y, w, h

Description

This routine is not for normal use. It is recommended that controls be added in the design view.

Class is the class name of the control (e.g. "TextBox"). controlName is a unique name that you provide (e.g. "textBox1"). This corresponds to the design-view name of a control but must be different from the name of any existing control. (x, y) give the position of the top left corner whilst w and h are its dimensions.


Topic

Platform | .NET(including Win32)
Purpose | .
Syntax | .
Description | .
Return value | .


GetControl@

Platform | .NET(including Win32)
Purpose | To get a control object.
Syntax | System.Windows.Control FUNCTION GetControl@(dialog, controlName) VCdialog dialog STRING controlName
Description | This function is for advanced programming in the context of direct access to the .NET Framework library.
Return value | Returns a reference to the given object.


GetControlLocation@

Platform | .NET(including Win32)
Purpose | To get the location of a given control.
Syntax | SUBROUTINE GetControlLocation@(dialog, controlName, x, y) VCdialog dialog INTEGER x, y
Description | Returns the position of given control in (x, y).


GetForm@

Platform | .NET(including Win32)
Purpose | To get the Form object for a given dialog.
Syntax | System.Windows.Forms.Form FUNCTION GetForm@(dialog) VCdialog
Description | This function is for advanced programming in the context of direct access to the .NET Framework library.
Return value | Returns a reference to the given object.


OnScroll@

Platform

.NET(including Win32)

Purpose

To specify a callback for a scroll event.

Syntax

SUBROUTINE OnScroll@(dialog, controlName, callback)
VCdialog dialog
STRING controlName
EXTERNAL callback

Controls

TrackBar, Track_Bar

Description

OnScroll@ is called once for each relevant control when the dialog is configured (e.g. immediately after a call to vcCreateDialog@).

callback is the name of the Fortran function that contains the code to be executed when the user scrolls in the given control.

OnScroll@ is a special case of vcOnEvent@.

See also

vcOnClick@, vcOnEvent@

© 2004 Silverfrost Ltd.


OnTextChanged@

Platform

.NET(including Win32)

Purpose

To specify a callback for a TextChanged event.

Syntax

SUBROUTINE OnTextChanged@(dialog, controlName, callback)
VCdialog dialog
STRING controlName
EXTERNAL callback

Controls

Any control that has the TextChanged property.

Description

OnTextChanged@ is called once for each relevant control when the dialog is configured (e.g. immediately after a call to vcCreateDialog@).

callback is the name of the Fortran function that contains the code to be executed when the user changes the text in the given control.

vcOnClick@ is a special case of vcOnEvent@.

See also

vcOnEvent@

© 2004 Silverfrost Ltd.


OnTick@

Platform

.NET(including Win32)

Purpose

To specify a callback for a Timer event.

Syntax

SUBROUTINE OnTick@(dialog, controlName, callback)
VCdialog dialog
STRING controlName
EXTERNAL callback

Description

OnTick@ is called once for each relevant control when the dialog is configured (e.g. immediately after a call to vcCreateDialog@).

callback is the name of the Fortran function that contains the code to be executed when the timer is enabled and timer interval has elapsed.

OnTick@ is a special case of vcOnEvent@.

See also

vcOnEvent@, vcSetEnabled@, vcSetTimer@

© 2004 Silverfrost Ltd.


Visual ClearWin Library Reference


SetLineAlpha@

Platform | .NET(including Win32)
Purpose | To set the alpha value for subsequent line drawing.
Syntax | INTEGER FUNCTION SetLineAlpha@(drawing, alpha) VCdrawing drawing INTEGER alpha
Description | Sets the alpha value in the range 0 to 255.
Return value | Returns the previous value.
See also | SetLineARGB@, vcLineRGB@