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

 

SyntaxDescription
CALL PCOASTPlots coastlines and grids
CALL PCONTPlots contour fields
CALL PWINDPlots wind fields
CALL POBSPlots observations
CALL PIMAGEPlots images, for example satellite
CALL PTEXTPlots text
CALL PGRAPHPlots graphs
CALL PAXISPlots axes
CALL PSYMBPlots marker symbols
CALL PLINEPlots lines and shapes over geographic areas
CALL PBOXPLOTPlots 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

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.

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 SyntaxDescription
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 SyntaxDescription
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

 

SyntaxDescription
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

 

The fifth character of the subroutine name indicates that an array is being passed and also indicates its dimen-

sionality. The sixth character indicates the FORTRAN type of the array, i.e. Character, Integer or Real.

 

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.

 

The second argument should be an array of the appropriate data type containing the data to be assigned to the

Magics parameter.

 

Arguments N1, N2, N3 are integers which inform Magics of the size of the array being passed, i.e. number of

elements in each dimension of the array.

 

This type of subroutine can be used, for example, to pass lists of contour levels to Magics, e.g.

CALL PSET1R('CONTOUR_LEVEL_LIST', RLIST, 25)

 

where the real array RLIST contains a list of 25 contour levels.

 

Magics Pseudo-Action Routines in FORTRAN

 

As distinct from action routines, the pseudo action routines perform a type of action that does not result in

plotted output but signifies a change of state in Magics, such as moving to a new page.

 

Pseudo action routine PNEW will change from one plot area to another. The format of PNEW is:

 

Table 2-5. Magics Pseudo-Action Routines

 

Function Call

CALL PNEW ( 'SUPER_PAGE' )

CALL PNEW ( 'PAGE' )

CALL PNEW ( 'SUBPAGE' )

 

The change of plotting area does not take place when PNEW is called but when the next action routine is

called. Pseudo action routine PNEW is described in Chapter 4, Layout, Mapping and Coastlines.

 

Magics Data Loading Routines in FORTRAN

 

The following action routines are used to read data:

 

Table 2-6. Magics Data Reading Routines

 

Function Call

CALL PGRIB

 

CALL PNETCDF

CALL PBUFR

 

The magicsCompatibilityChecker

With its Fortran interface, Magics++ tries to be as backwards compatible as possible to MAGICS 6. Unfortunately this was not always possible and changes in the API have occurred. To help users to access if their Magics Fortran programs need changing a script is provided. This script is called magicsCompatibilityChecker and is called from the command line followed by the name of code file to be checked. An output will be printed to alert users of changes in the Fortran API.

magicsCompatibilityChecker mycode.f