Using the Console

Console Use for Fortran QuickWin and Fortran Standard Graphics Applications

For a Fortran QuickWin or Fortran Standard Graphics application, because the default program window handles both graphics and text, the use of a QuickWin window may not be very efficient:

• QuickWin windows use lots of memory and therefore have size limitations.

• They can be slow to scroll.

Although you can access the console window using WRITE and READ (or other) statements, applications that require display of substantial lines of text, consider creating a DLL that creates a separate console window for efficiency. The DLL application needs to call Windows* API routines to allocate the console, display text, accept keyed input, and free the console resources.

Basic use of a console is described in Code Samples of Console Use.

Console Use for Fortran Windows Applications and Fortran DLL Applications

With a Fortran Windows* or Fortran DLL application, attempting to write to the console using WRITE and READ (or other) statements before a console is created results in a run-time error (such as error performing WRITE).

A console created by a Fortran DLL is distinct from any application console window associated with the main application. A Fortran DLL application has neither a console nor an application window created for it, so it must create (allocate) its own console using Windows* API routines. When used with a Fortran QuickWin or Fortran Standard Graphics application main program, the Fortran DLL can provide its main application with a very efficient console window for text-only use.

Like a Fortran DLL application, a Fortran Windows application has neither a console nor an application window created for it, so it must create its own console using Windows* API routines. After allocating a console in a Fortran DLL, the handle identifier returned by the GetStdHandle Windows* API routine refers to the actual console the DLL creates.

When the Fortran Windows application does create a console window, it is very efficient for text-only use. The handle identifier returned by the GetStdHandle Calling Windows* API Routines refers to the actual console the Fortran Windows application creates.

For information about creating a console, see Allocating and Deallocating a Console below.

Code Samples for Console Use

The following sections shows sample code for using a console:

• Allocating and Deallocating a Console for Fortran Windows* and DLL Applications.

• Extending Size of the Console Window and Console Buffer for console use in any project type.

• Writing and Reading Characters at a Cursor Position for console use in any project type.

Allocating and Deallocating a Console

To create a console, you use the AllocConsole routine. When you are done with the console, free its resources with a FreeConsole routine. For example, the following code allocates the console, enlarges the buffer size, writes to the screen, waits for any key to be pressed, and deallocates the console:

! The following USE statement provides Fortran interfaces to Windows routines
    USE IFWIN
! Begin data declarations
    integer lines,length
    logical status
    integer fhandle
    Type(T_COORD) wpos
! Set buffer size variables
    length = 80
	 lines  = 90
! Begin executable code
!   Allocate a console
    status = AllocConsole() ! get a console window of the currently set size
    handle = GetStdHandle(STD_OUTPUT_HANDLE)
    wpos.x = length   ! must be >= currently set console window line length
    wpos.y = lines    ! must be >= currently set console window number of lines
    ! Set a console buffer bigger than the console window. This provides
    ! scroll bars on the console window to scroll through the console buffer
    status = SetConsoleScreenBufferSize(fhandle, wpos)
	 ! Write to the screen as needed. Add a READ to pause before deallocation
	 write (*,*) "This is the console output! It might display instructions or data "
	 write (*,*) " "
	 write (*,*) "Press any key when done viewing "
	 read (*,*)
!   Deallocate the console to free its resources.
    status = FreeConsole()    

Calling Windows* API routines is described in Calling Windows* API Routines.

If you are using a DLL, your DLL code will need to create subprograms and export their symbols to the main program.

Basic use of a console is described in Extending Size of the Console Window and Console Buffer and Writing and Reading Characters at a Cursor Position.

Extending the Size of the Console Window and Console Buffer

When you execute a Fortran Console application, the console is already allocated. You can specify the size of the console window, size of the console buffer, and the location of the cursor. If needed, you can extend the size of the console buffer and console window by using the following Windows* API routines:

1. You first need to obtain the handle of the console window using the GetStdHandle routine. For example:

   ! USE statements to include routine interfaces
   use ifqwin
   use ifport
   use ifcore
   use ifwin
   ! Data declarations
   integer fhandle
   logical lstat
   ! Executable code
   fhandle = GetStdHandle(STD_OUTPUT_HANDLE)
   ! ...

2. If needed, you can obtain the size of the:

   • Console window by using the GetConsoleWindowInfo routine.

   • Console buffer by using the GetConsoleScreenBufferInfo routine.

   For example:

   ! USE statements to include routine interfaces
   use ifqwin
   use ifport
   use ifcore
   use ifwin
   ! Data declarations
   integer fhandle
   logical lstat 
   Type(T_CONSOLE_SCREEN_BUFFER_INFO) conbuf
   type (T_COORD)        dwSize
   type (T_SMALL_RECT)   srWindow
   fhandle = GetStdHandle(STD_OUTPUT_HANDLE)
   ! Executable code to get console buffer size
   lstat = GetConsoleScreenBufferInfo(fhandle, conbuf)
   write (*,*) " "
   write (*,*) "Window coordinates= ", conbuf.srWindow
   write (*,*) "Buffer size= ", conbuf.dwSize
   ! ...

3. To set the size of the console window and buffer, use the SetConsoleWindowInfo and SetConsoleScreenBufferSize routines with the fhandle value returned previously:

!  USE statements to include routine interfaces
use ifqwin
use ifport
use ifcore
use ifwin
! Data declarations
integer nlines, ncols
logical lstat   
Type(T_COORD) wpos
Type(T_SMALL_RECT) sr
Type(T_CONSOLE_SCREEN_BUFFER_INFO) cinfo
! Executable code to set console window size
sr.top    =   0
sr.left   =   0
sr.bottom =   40 ! <= console buffer height 
 -1
sr.right  =   60 ! <= 
 console buffer width  -1
lstat = SetConsoleWindowInfo(fhandle, .TRUE., sr)
! Executable code to set console buffer size
nlines = 100
ncols  =  80
wpos.x = ncols  ! columns >= console window width
wpos.y = nlines ! lines   >= console window height
lstat = SetConsoleScreenBufferSize(fhandle, wpos)
! ...

Writing and Reading Characters at a Cursor Position

You can position the cursor as needed using the SetConsoleCursorPosition routine before you write characters to the screen:

 ! Use previous data declarations
 ! Position and write two lines
   wpos.x = 5 ! 6 characters from left
   wpos.y = 5 ! 6 lines down
   lstat = SetConsoleCursorPosition(fhandle, wpos)
   write(*,*) 'Six across Six down'
 ! ...

You read from the screen at an appropriate place, but usually you should set the cursor relative to the starting screen location:

  ! Use previous and the following data declaration
   CHARACTER(Len=50) charin
 ! Go back to beginning position of screen
   wpos.x = 0 ! 0 characters from left
   wpos.y = 0 ! 0 lines down
   lstat = SetConsoleCursorPosition(fhandle, wpos)
 ! Position character input at start of line 11
   wpos.x = 0 ! first character from left
   wpos.y = 10 ! 11 lines down
   lstat = SetConsoleCursorPosition(fhandle, wpos)
   read(*,*) charin
 ! ...

For console I/O, you can use Windows* OS routines WriteConsoleLine and ReadConsoleLine instead of Fortran WRITE and READ statements.