# Use the Console

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

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 larger than the console window, scroll bars are automatically provided. The size of the console screen buffer must be larger (or equal to) the size of the console window. If the buffer is smaller than the size of the console window, 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.

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.

The following Fortran Project Types provide an application console window:

Project Type | Description of Console Provided
--- | ---
Fortran Console | Provides a console window intended to be used for character-cell applications that use text only. When running a Fortran Console application from the command prompt, the existing console environment is used. When you run the application from Windows* or Developer Studio* (by selecting Start Without Debugging in the Debug menu), a new console environment is created. Basic console use 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. Because the program window must handle both text and graphics, it is not as efficient as the console 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 Windows* API 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 Windows* API routines mentioned below, there are other routines related to console use described in the Microsoft Platform SDK* documentation.

## 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.

## Allocate and Deallocate 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 Call 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 Extend the Size of the Console Window and Console Buffer and Write and Read Characters at a Cursor Position.

## Extend 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)
    ! ...

## Write and Read 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.

Parent topic: About Fortran Project Types

## See Also

Understand Project Types
Call Windows* API Routines
Use the Console
Code Samples of Console Use
Console Use for Fortran QuickWin and Fortran Standard Graphics Applications
Console Use for Fortran Windows* Applications and Fortran DLL Applications
Allocate and Deallocate a Console
Extend the Size of the Console Window and Console Buffer
Write and Read Characters at a Cursor Position