FORTRAN Interface

A short example program is the best introduction to Magics programming. The following code contains enough comments to describe what the program is doing, and is followed by the plot that it generates.

Example Fortran program

PROGRAM MAGICS_EXAMPLE_FORTRAN

C This program shows an example of a simple MAGICS plot.

C We start MAGICS, load some data, set some plotting

C attributes then generate the plot. MAGICS is closed at

C the end.


C Open MAGICS and set the output device

CALL POPEN

CALL PSETC ('OUTPUT_FORMAT', 'PS')

CALL PSETC ('OUTPUT_NAME', 'using_fortran1')

CALL PSETC ('PAGE_ID_LINE_USER_TEXT','Using FORTRAN Interface')

C Pass the data to MAGICS

CALL PSETC ('GRIB_INPUT_FILE_NAME', 'data/z500.grb')

CALL PGRIB

C Set up and plot the coastlines

CALL PSETC ('MAP_COASTLINE_COLOUR', 'GREY')

CALL PSETC ('MAP_GRID_COLOUR','GREY')

CALL PCOAST

C Define and plot the contour

CALL PSETC ('CONTOUR_LINE_STYLE', 'DASH')

CALL PCONT

C Set up and plot the title text. We just use the default setting

C which generates an automatic title from the data.

CALL PTEXT

C Close MAGICS. It is this command that actually initiates the

C plotting.

CALL PCLOSE

STOP

END

Magics Initialisation Routines in FORTRAN

The first Magics routine to be called must be POPEN and the last to be called must be PCLOSE. These two routines perform mandatory initialisation and termination functions. The formats of POPEN and PCLOSE, which have no arguments, are:

CALL POPEN

CALL PCLOSE

Magics Action Routines in FORTRAN

In order to plot something, an action routine must be called. In the example program, three plotting commands are called: PCOAST, PCONT and PTEXT. The following table shows all of the available action routines.

Table 2.1. Magics Action Routines

Syntax	Description
`CALL PCOAST`	Plots coastlines and grids
`CALL PCONT`	Plots contour fields
`CALL PWIND`	Plots wind fields
`CALL POBS`	Plots observations
`CALL PIMAGE`	Plots images, for example satellite
`CALL PTEXT`	Plots text
`CALL PGRAPH`	Plots graphs
`CALL PAXIS`	Plots axes
`CALL PSYMB`	Plots marker symbols
`CALL PLINE`	Plots lines and shapes over geographic areas
`CALL PBOXPLOT`	Plots boxplots

Each action routine has its own set of parameters which have a unique prefix to identify them. For instance, the parameter CONTOUR_LINE_STYLE affects the operation of PCONT. These parameters can be set by the user and, if not set, the default values will be used.

Even though parameters can be set anywhere in the user program, action routines will always use the last value assigned to a parameter before the action routine is called.

Magics Parameter Setting in FORTRAN

In Magics, plots generated using action routines will be drawn using information from the relevant Magics parameters. These parameter values can be changed dynamically by calling parameter-setting routines. There are only a few parameter-setting routines in Magics, one for each data type.

The names of the parameters are passed as parameters using FORTRAN character strings. This method allows easy-to-remember, English language keywords and the list of keywords can be easily extended. The set of routines for parameter setting is divided into four subsets: single parameter setting, single parameter resetting, array parameter setting and multiple parameter setting.

Values of Magics parameters can also be retrieved by using the function ENQR and passing it the parameter name as an input parameter.

Single Parameter Setting and Resetting

There are three subroutines to assign a single value to a parameter, each postfixed with a C , I or R , corresponding to a different argument type:

Table 2-2. Magics Single Parameter Setting Routines

Magics Parameter Setting in FORTRAN

In Magics, plots generated using action routines will be drawn using information from the relevant Magics parameters. These parameter values can be changed dynamically by calling parameter-setting routines. There are only a few parameter-setting routines in Magics, one for each data type.

The names of the parameters are passed as parameters using FORTRAN character strings. This method allows easy-to-remember, English language keywords and the list of keywords can be easily extended. The set of routines for parameter setting is divided into four subsets: single parameter setting, single parameter resetting, array parameter setting and multiple parameter setting.

Values of Magics parameters can also be retrieved by using the function ENQR and passing it the parameter name as an input parameter.

Single Parameter Setting and Resetting

There are three subroutines to assign a single value to a parameter, each postfixed with a C , I or R , corresponding to a different argument type:

Table 2.2. Magics Single Parameter Setting Routines

Function Call Syntax	Description
`CALL PSETC ( MAGICS_PARAMETER, CVALUE )`	For setting character arguments
`CALL PSETI ( MAGICS_PARAMETER, IVALUE )`	For setting integer arguments
`CALL PSETR ( MAGICS_PARAMETER, RVALUE )`	For setting real arguments

The first argument should be a character variable or constant specifying the Magics parameter to be set.The VALUE argument should be of the corresponding type for the chosen subroutine.

A parameter may be reset to its default value using the function PRESET:

There are three subroutines to assign a single value to a parameter, each postfixed with a C, I or R , corresponding to a different argument type:

Table 2.3. Magics Single Parameter Resetting Routine

Function Call Syntax	Description
`CALL PRESET( MAGICS_PARAMETER )`	For resetting a parameter of any data type

There are seven subroutines for passing information to Magics in the form of arrays:

Table 2.4. Magics Array Parameter Setting Routines

Syntax	Description
`CALL PSET1C ( MAGICS_PARAMETER, CARRAY, N1 )`	For 1-dimensional character array arguments
`CALL PSET1I ( MAGICS_PARAMETER, IARRAY, N1 )`	For 1-dimensional integer array arguments
`CALL PSET2I ( MAGICS_PARAMETER, IARRAY, N1, N2 )`	For 2-dimensional integer array arguments
`CALL PSET3I ( MAGICS_PARAMETER, IARRAY, N1, N2, N3 )`	For 3-dimensional integer array arguments
`CALL PSET1R ( MAGICS_PARAMETER, RARRAY, N1 )`	For 1-dimensional real array arguments
`CALL PSET2R ( MAGICS_PARAMETER, RARRAY, N1, N2 )`	For 2-dimensional real array arguments
`CALL PSET3R ( MAGICS_PARAMETER, RARRAY, N1, N2, N3 )`	For 3-dimensional real array arguments