man Autograph (3): To draw graphs, each with a labeled background and

SYNOPSIS

Each of the following routines draws a complete graph with a single call:

EZY - Draws, in a manner determined by the current values of the control parameters, a complete graph of a single curve through the points (I,YDRA(I)), for I from 1 to NPTS. The argument GLAB may be used to specify a "graph label", to be placed at the top of the graph.

EZXY - Draws, in a manner determined by the current values of the control parameters, a complete graph of a single curve through the points (XDRA(I),YDRA(I)), for I from 1 to NPTS. The argument GLAB may be used to specify a "graph label", to be placed at the top of the graph.

EZMY - Draws, in a manner determined by the current values of the control parameters, a complete graph of one or more curves, each defined by a set of points (I,YDRA(I,J)) (or (I,YDRA(J,I)), depending on the current value of 'ROW.'), for I from 1 to NPTS. The curve number J runs from 1 to MANY. The argument GLAB may be used to specify a "graph label", to be placed at the top of the graph.

EZMXY - Draws, in a manner determined by the current values of the control parameters, a complete graph of one or more curves, each defined by a set of points (XDRA(I),YDRA(I,J)) (or (XDRA(I),YDRA(J,I)) or (XDRA(I,J),YDRA(I,J)) or (XDRA(J,I),YDRA(J,I)), depending on the current value of 'ROW.'), for I from 1 to NPTS. The curve number J runs from 1 to MANY. The argument GLAB may be used to specify a "graph label", to be placed at the top of the graph.

The following routines provide access to control parameters:

ANOTAT - Changes the values of certain primary control parameters, purportedly having to do with "annotation" of a graph.

DISPLA - Changes the values of certain primary control parameters purportedly having to do with the "display" of a graph.

AGSETC - Allows a user program to (in effect) store a character string as the value of a specified single parameter.

AGSETF - Allows a user program to store a real number as the value of a single parameter.

AGSETI - Allows a user program to store the real equivalent of an integer as the value of a single parameter.

AGSETP - Allows a user program to reset the values of a group of parameters containing one or more elements.

AGSETR - Allows a user program to store a real number as the value of a single parameter.

AGGETC - Allows a user program to retrieve (in effect) the character-string values of certain single parameters.

AGGETF - Allows a user program to retrieve the real value of a single parameter.

AGGETI - Allows a user program to retrieve the integer equivalent of the real value of a single parameter.

AGGETP - Allows a user program to get the values of a group of parameters containing one or more elements.

AGGETR - Allows a user program to retrieve the real value of a single parameter.

The following are lower-level user-callable routines:

AGSTUP - Performs "set-up" tasks required before AGBACK and AGCURV may be called. Basically, AGSTUP examines the current values of the primary control parameters for errors and computes from them and from its arguments the values of secondary control parameters. The primary and secondary control parameters together determine how the routines AGBACK and AGCURV will behave.

AGBACK - Draws the background specified by the current values of the control parameters - the primary parameters with default values or with values supplied by the user, and the secondary parameters with values computed by AGSTUP.

AGCURV - Draws a curve in a manner specified by the current values of the control parameters - the primary parameters with default values or with values supplied by the user, and the secondary parameters with values computed by AGSTUP.

The following are other user-callable routines:

AGSAVE - Saves the current state of Autograph for later restoration by AGRSTR.

AGRSTR - Restores a saved state of Autograph.

The following are non-user-callable, CHARACTER*16 functions:

AGBNCH - Provides an easy way to convert binary dash patterns into character dash patterns.

AGDSHN - Provides an easy way to generate the names of parameters in the group 'DASH/PATTERN.', for use in calls to AGSETC and AGGETC.

C-BINDING SYNOPSIS

#include <ncarg/ncargC.h>

c_ezy
c_ezxy
c_ezmy
c_ezmxy
c_anotat
c_displa
c_agsetc
c_agsetf
c_agseti
c_agsetp
c_agsetr
c_aggetc
c_aggetf
c_aggeti
c_aggetp
c_aggetr
c_agstup
c_agback
c_agcurv
c_agsave
c_agrstr
c_agbnch
c_agdshn

USER-MODIFIABLE INTERNAL ROUTINES

AGCHAX - Provides a way for the user to change the color, intensity, line style, etc., of various portions of the axes.

AGCHCU - Provides a way for the user to change the color, intensity, line style, etc., of curves drawn by Autograph.

AGCHIL - Provides a way for the user to change the color, intensity, text style, etc., of the informational labels.

AGCHNL - Provides a way for the user to substitute arbitrary character strings for the numeric labels generated by Autograph.

AGPWRT - Provides a way for the user to change the style of all text strings drawn by Autograph.

AGUTOL - Provides a way for the user to change the user-system-to-label-system mapping for one or more of the four axes.

ACCESS

To use the Autograph Fortran or C routines, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.

To get smoother curves, drawn using spline interpolation, also load libdashsmth.o

Autograph contains a routine AGPWRT, which it calls to draw labels. This routine just passes its arguments on to the system-plot-package routine PWRIT. To use one of the fancier character-drawers, like Plotchar, just compile a routine AGPWRT to replace the default version; it has the same arguments as PWRIT and may either draw the character string itself, or just pass the arguments on to a desired character-drawer. You can also modify AGPWRT so that Autograph will access character fonts that are different from the default font. In its distributed form, AGPWRT calls PWRIT. Consult the documentation in the code. The file AGUPWRT on the distribution tape contains an implementation of AGPWRTX that allows Autograph to access the PWRITX character set. See the documentation in the code for AGUPWRTX. See your NCAR Graphics site representative to learn how to access the code.

MESSAGES

Autograph routines detect certain errors and, in response, call the routine SETER, which is an adapted version of a PORT error handler. Currently, all such errors are treated as being fatal and cause termination of the job. An error message is logged before the job is terminated. Each such message includes the name of the routine which detected the error and may be accompanied by supplementary information aimed at allowing the user to easily identify the call that caused the error. The possible error messages are as follows (in alphabetical order):

AGEXAX (CALLED BY AGSTUP) - USER-SYSTEM-TO-LABEL-SYSTEM MAPPING IS NOT MONOTONIC

This probably means that you have replaced the default routine AGUTOL with a version of your own, and you've blown it.

AGGETC - PARAMETER TO GET IS NOT INTRINSICALLY OF TYPE CHARACTER

The argument TPGN specifies a parameter which is not intrinsically of type character. See the description in the AGGETC man page.

AGGETP OR AGSETP - ATTEMPT TO ACCESS LABEL ATTRIBUTES BEFORE SETTING LABEL NAME

The parameter 'LABEL/NAME.' must be set prior to the call which gave the error message, specifying which label's attributes are being referenced.

AGGETP OR AGSETP - ATTEMPT TO ACCESS LINE ATTRIBUTES BEFORE SETTING LINE NUMBER

The parameter 'LINE/NUMBER.' must be set prior to the call which gave the error message, specifying which label line's attributes are being referenced.

AGGETP OR AGSETP - ILLEGAL KEYWORD USED IN PARAMETER IDENTIFIER

The argument TPGN contains an unrecognizable keyword.

AGKURV - NUMBER OF POINTS IS .LE. 0

The argument NEXY, in a call to AGCURV, is less than or equal to zero. The routine AGKURV is called by AGCURV to draw un-windowed curves.

AGNUMB - MANTISSA TOO LONG
AGNUMB - EXPONENT TOO LARGE
AGNUMB - ZERO-LENGTH MANTISSA

AGNUMB is called by AGAXIS to generate a character string expressing the value of a real number. You should not be able to generate any of AGNUMB's error messages. If you do, see the Autograph specialist.

AGQURV - NUMBER OF POINTS IS .LE. 0

The argument NEXY, in a call to AGCURV, is less than or equal to zero. The routine AGQURV is called by AGCURV to draw windowed curves.

AGRSTR - ERROR ON READ
AGRSTR - END-OF-FILE ON READ

Probably the unit specified by IFNO was not positioned properly.

AGSAVE - ERROR ON WRITE

A system error has occurred as a result of the attempted "WRITE".

AGSETC - PARAMETER TO SET IS NOT INTRINSICALLY OF TYPE CHARACTER

This means that the argument TPGN specifies some parameter other than one of the acceptable possibilities. See the description in the AGSETC man page.

AGSETP - ATTEMPT TO DEFINE LINE OF NON-EXISTENT LABEL

The user has attempted to define a line of a label without first specifying which label; 'LABEL/NAME.' must be set prior to the call which gave the error message.

AGSETP - LABEL LIST OVERFLOW - SEE AUTOGRAPH SPECIALIST

The user has attempted to define more labels than Autograph can handle; a modification of Autograph is required.

AGSETP - LINE LIST OVERFLOW - SEE AUTOGRAPH SPECIALIST

The user has attempted to define more label lines than Autograph can handle; a modification of Autograph is required.

AGSTCH - CHARACTER-STRING BUFFER OVERFLOW - SEE CONSULTANT

The routine AGSTCH is called by AGSETC to stash the character string in Autograph's character storage space. The available storage space has been exhausted. See the consultant.

AGSTCH - CHARACTER-STRING INDEX OVERFLOW - SEE CONSULTANT

The routine AGSTCH is called by AGSETC to stash the character string in Autograph's character storage space. Too many such strings have been stored. See the consultant.

AGSTUP - GRAPH WINDOW IMPROPERLY SPECIFIED

The parameters in the group named 'GRAPH.' have improper values.

AGSTUP - GRID WINDOW IMPROPERLY SPECIFIED

The parameters in the group named 'GRID.' have improper values. This is most likely to occur when 'SET.' has the value "2." or "4.", specifying that the edges of the grid window are to be as implied by the last call to the plot package routine SET. Check to make sure that the portion of the plotter frame specified by the last SET call is within the current graph window.

AGSTUP - s LABELS IMPROPERLY SPECIFIED

(where "s" = "LEFT", "RIGHT", "BOTTOM", "TOP", or "INTERIOR"). Re-read the paragraph "THE LABEL BOXES", in the section "OVERVIEW". You have defined a label with a basepoint on one edge of the grid window and an offset vector pointing outward, some part of which extends inside the grid window (or vice-versa). This is not allowed.

COPYRIGHT