Using the Console

On Windows systems, a console window typically allows input and output of characters (not graphics).

Certain console windows allow use of command-line interaction for programmers. For example, the Fortran Command Prompt available from the Compaq Visual Fortran program folder provides a command-line environment where Visual Fortran environment variables are already set. Similarly, the Command Prompt window provided by the operating system provides a general-purpose command-line console environment.

The primary purpose of an application's console window is to display and accept characters. For example, data written (explicitly or implicitly) by Fortran WRITE (or other) statements to Fortran logical unit 6 display characters on a console window. Similarly, data read by Fortran READ (or other) statements to unit 5 accept keyboard character input.

The console consists of two components:

The actual console window that shows the characters on the screen.
The console buffer that contains the characters to be displayed.

If the console screen buffer is bigger than the console window, scroll bars are provided automatically. The size of the console screen buffer must be larger (or equal to) the size of the console window (if not, an error occurs).

For applications that need to display more than a few hundred lines of text, the ability to scroll quickly through the text is important. Also, the maximum size of the console window buffer differs between Windows operating systems:

On a Windows 98, Windows Me, or Windows 95 system, the number of character lines is limited to about 40-50 pages of output with 132-character lines.
On a Windows NT or Windows 2000 system, the number of character lines is substantially larger than on Windows 98, Windows Me, and Windows 95 systems.

Fortran Console applications automatically provide a console. Fortran QuickWin (and Fortran Standard Graphics) applications do not provide a console, but display output and accept input from Fortran statements by using the program window.

Different Visual Fortran project types do or do not provide an application console window:

Project Type	Description of Console Provided
Fortran Console	Provides a console window since it is intended to be used for character-cell applications that use only text. When you run a Fortran Console application from a command prompt, the existing console environment is used. When you run the application from Windows or Developer Studio (by clicking on ! Execute program-name in the Build menu), a new console environment is created. The limits do not differ greatly whether the console is an existing command prompt or created by Windows or Developer Studio, but Windows NT and Windows 2000 systems have substantially greater capacity than Windows 98, Windows Me, and Windows 95 systems. Basic use of a console is described in Code Samples of Console Use.
Fortran QuickWin or Fortran Standard Graphics	Does not provide a console, but output to unit 6 and input to unit 5 are directed to the application program window, which can handle both text and graphics. However, because the program window must handle both text and graphics, it is not very efficient for just text-only use. A Fortran QuickWin or Fortran Standard Graphics program window (or child window) provides a console-like window. See Console Use for Fortran QuickWin and Fortran Standard Graphics Applications.
Fortran Windows	Does not provide a console window, but the user can create a console by using Win32 routines. See Console Use for Fortran Windows Applications and Fortran DLL Applications.
Fortran DLL	Does not provide a console window, but the user can create a console by using Win32 routines. See Console Use for Fortran Windows Applications and Fortran DLL Applications.
Fortran Static Library	Depends upon the project type of the main application that references the object code in the library (see above project types).

In addition to the Win32 routines mentioned below, there are other Win32 routines related to console use in the Platform SDK documentation, under Windows Base Services, File and I/O, Consoles and Character-Mode Support.

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 thus cannot be larger than a certain size.
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 Win32 routines to allocate the console, display text, accept keyed input, and free the console resources.

For a Fortran QuickWin project that uses a DLL to create and use a console, see the CONAPP Visual Fortran sample in ...\Df98\Samples\QuickWin.

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 Win32 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 Win32 routines. After allocating a console in a Fortran DLL, the handle identifier returned by the GetStdHandle Win32 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 Win32 routine 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 Win32 routines
     USE DFWIN
! Begin data declarations
     integer lines,length
     logical status
     integer handle
     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(handle, 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 Win32 routines is described in Calling Win32 Routines and the Visual Fortran Windows Module.

If you are using a DLL, your DLL code will need to create subprograms and export their symbols to the main program (see Creating Fortran DLLs).

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 Win32 routines:

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

 ! USE statements to include routine interfaces
    use dflib
    use dfwin

 ! Data declarations
    integer fhandle
    logical lstat
 ! Executable code
    fhandle = GetStdHandle(STD_OUTPUT_HANDLE)
 ! ...

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 dflib
    use dfwin
 ! 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

 ! ...

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 dflib
    use dfwin
 ! 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 Win32 routines WriteConsoleLine and ReadConsoleLine instead of Fortran WRITE and READ statements.