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.
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.
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
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 |
A parameter may be reset to its default value using the function PRESET:
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 |
VALUE argument should be of the corresponding type for the chosen subroutine.
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
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
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