6 The FORTRAN interface

This section describes the subroutines that can be called from a FORTRAN program to interface with the Graphics Window Manager. All these routines use the inherited status strategy which means that if the STATUS argument is not set to the value SAI__OK on entry the routine will exit without performing any action. If an error occurs during the execution of a routine the STATUS will be set and an error will be reported using the error message service (EMS—SUN/104).

6.1 Summary of GWM calls

GWM_CLOSE( STATUS )
Close the X client-server connection.

GWM_CRWIN( WNAME, STATUS )
Create a GWM window.

GWM_DSWIN( WNAME, STATUS )
Destroy a GWM window.

GWM_EXIST( WNAME, EXISTS, STATUS )
Inquire if a GWM window of the given name exists.

GWM_GETCI( WNAME, IDIM, INDEXS, NCOLS, STATUS )
Inquire the number of colours and colour indices.

GWM_OPEN( DISPLY, USEDEF, STATUS )
Establish the X client server connection.

GWM_WSETC( OPTION, VALUE, STATUS )
Set a character string window option.

GWM_WSETI( OPTION, VALUE, STATUS )
Set an integer window option.

GWM_WSETL( OPTION, VALUE, STATUS )
Set a logical window option.

6.2 Making the X connection

The first thing to do when using the FORTRAN interface is to call the routine GWM_OPEN which establishes the connection between the client and the server. In this context the client is the cpu running the program and the server is the cpu displaying the image (X allows these cpu’s to be different). The first argument passed to GWM_OPEN defines this connection, however most applications need not worry about the details of the connection and can use the default (the option of specifying the connection path is included for completeness). The default connection is established with the following call

where the second argument is set to true to indicate that the default connection is to be used.

The connection is ended with a call to GWM_CLOSE. These two routines (GWM_OPEN and GWM_CLOSE) should bracket all other routines called from this interface.

As well as establishing the X connection GWM_OPEN also sets up an error handler to deal with any non-fatal X errors. Once this has been set up any such errors are reported using EMS. When GWM_CLOSE is called the previously active error handler is re-established.

6.3 Creating a GWM window

The routine GWM_CRWIN is used to create a GWM window on the server. The following example shows how a window with the name ’XWINDOWS’ is created (remember GWM window names are case sensitive).

On its own this call will create a window with the default characteristics of shape, colour etc. To select different characteristics calls to the routines GWM_WSETx are made before the call to GWM_CRWIN.

Each required window characteristic is selected with a separate call to one of the GWM_WSETx routines, where ’x’ represents the type of the characteristic, ’I’ for integer, ’L’ for logical and ’C’ for character string. The following table lists the characteristics and their types.

Most of these characteristics are directly comparable to the options of the xmake command. The only major difference is the -geometry option which here is split into its four components WIDTH, HEIGHT, XORIGIN and YORIGIN. The XSIGN and YSIGN characteristic is used to override the sign of XORIGIN and YORIGIN values; setting XSIGN or YSIGN to any value forces the corresponding origin value to have the same sign. This is only required when setting one of the origin characteristics to -0 in order to position the window at the bottom or right hand side of the screen.

The following example shows the use of most the options to create a window.

When defining a logical characteristic, such as the INTERACTIVE option, passing a true value in GWM_WSETL will activate the option, whereas passing a false value is equivalent to accepting the default.

Once the window has been created all the options are reset to their default values. If a second window is to be created all the necessary characteristics have to be re-defined before the next call to GWM_CRWIN.

A GWM window will remain on the server after the program which created it has terminated unless it is explicitly deleted using GWM_DSWIN.

6.4 Inquiries

The routine GWM_EXIST can be used to inquire if a GWM window of a given name exists on the server. A logical argument is returned with a value of true signifying that the window exists on the server, and a value of false indicating that it does not.

The routine GWM_GETCI returns the number of colours and the list of colour indices (pen numbers) allocated to a GWM window. The colour indices are returned in an array dimensioned by the application. If the array is not large enough to contain all the allocated colour indices then the array is filled up to its maximum size and the remaining indices are not returned. The argument specifying the number of colours does however return the actual number of colours allocated, and not the number of colours returned in the array. Consider making the inquiry for the window created in the previous example:

In this case the number of colours returned (NCOLS) will be 128, but only the first 64 colour indices will be returned in the INDEXS array.

6.5 Linking programs with GWM

Stand alone programs are linked with GWM by including ‘gwm_link‘ on the f77 command line.

Adam programs are linked with GMW by including ‘gwm_link_adam‘ on the alink command line.

6.6 Subroutine Specifications