System Variables

This chapter discusses the PV-WAVE system variables. For more information on system variables, see Chapter 2, Constants and Variables, in the PV-WAVE Programmer's Guide.

The cursor system variable. Currently, its only function is to contain the subscript of the largest or smallest element found by the MAX and MIN functions.

The !Century_Divider system variable is intended to help ensure that two-digit-year format dates do not adversely affect existing PV-WAVE applications. This is intended as a temporary solution to the year 2000 problem. We recommend that all PV-WAVE code be updated with four-digit year dates.

If set to -1 (the default), PV-WAVE behaves as in versions before 6.21. That is, any date in a two-digit year format is interpreted as being between January 1, 1901 and December 31, 1999. Furthermore, when !Century_Divider is set to -1, a two-digit year of 00 is interpreted as Julian date zero (September 9, 1752). For more information on how dates are handled in PV-WAVE, refer to the chapter Working with Date/Time Data in the PV-WAVE User's Guide.

If set in the range {0..99}, the !Century_Divider value represents the maximum of the hundred year span encompassed by two-digit year dates. In other words, if !Century_Divider is set to 35, then all two-digit year dates encountered in PV-WAVE are interpreted to be in the range {1935..2034}. Therefore, the date 01-31-35 refers to January 31, 1935; 01-31-99 refers to January 31, 1999; and 01-31-34 refers to January 31, 2034.

If !Century_Divider is set to 0 or a value greater than 99, the two-digit year is added to 2000.

A structure containing information about the current graphics output device. Fields are described in the following sections.

The fields of the !D structure are read-only.

Stores the current display depth.

The line interval, in device coordinates, required to obtain a solid fill.

A longword of flags. Each bit is a flag encoded as shown in the following table:

!D.N_Colors

The number of simultaneously available colors. In the case of devices with windows, this field is set after the window is initialized. For monochrome systems, !D.N_Colors is 2, and for color systems it is normally 256.

A string containing the name of the device.

This field contains the number of color table indices available on the device. Devices without color tables have this field set to 0.

The logical number of the file open for output by the current graphics device. This field only has meaning if the file is accessible to the user from PV-WAVE, and is 0 if no file is open. For example, the PostScript driver maintains this field with the unit number of the file open for PostScript output. In the case of Tektronix output to a file, !D.Unit may be set to either + or -} the logical unit number.

The index of the currently open window. Set to -1 if no window is open. Used only with devices that support windows.

The normal width and height of a character in device units. These fields are set after the window is initialized.

The number of pixels per centimeter in the x and y directions.

Reports the width and height of the current graphics window in pixels. The values are updated when the window is resized.

Reports the height and width of the current graphics window in pixels. The values are updated when the window is resized.

A string containing, by default, a slash (/) character. This character is used to separate the parts of a date on output (for example, 5/15/1992). To use a different character, change the value of this variable. This variable is used by the DT_PRINT, DT_TO_STR, and DC_WRITE_* routines.

An array of strings containing the names of the days of the week. This system variable is used by the DAYNAME function to return the names of the days for a specified date/time variable.

Contains the name of the main PV-WAVE directory (that is, the directory containing the files PV-WAVE needs to run).

Contains the pixel dimensions of the display screen.

Contains the double-precision value of pi. This is a read-only system variable.

Contains the value of Julian Day 1 (September 14, 1752) as a !DT structure. Used in various Date/Time calculations. This value can be overridden using the Base keyword as a parameter to the SEC_TO_DT and DT_TO_SEC routines.

This variable can also be modified directly; however, if you do this, you must set the last field (the recalc flag) of the !DT structure to 1. For more information, see the section Recalc Flag in Chapter 8, Working with Date/Time Data, in the PV-WAVE User's Guide.

Contains the conversion factor to convert degrees to radians. The value is / 180, which is approximately 0.01745. This is a read-only system variable.

Enables or disables the keyboard line-editing feature.

Contains the code of the last I/O error message. The CURSOR function also uses !Err to store the return value of the function. This enables the user to determine which mouse button was pushed.

Contains the text of the last I/O error message. This is a read-only system variable.

This system variable is created by the CREATE_HOLIDAYS procedure. It is a Date/Time variable containing holidays as defined by CREATE_HOLIDAYS. This system variable does not have a default value. This variable can hold up to 50 holiday definitions.

Contains the logical unit number of journal output. If there is no journal output, !Journal = 0. This is a read-only system variable.

Identifies the language currently being used. The default is american.

An array of strings containing the names of the months. This system variable is used by the MONTH_NAME function to return the names of the months for a specified date/time variable.

Used by the CURSOR function to store the x and y position of the mouse, the mouse button status, and a date/time stamp. The fields for this variable are:

!Mouse.X!Mouse.Y!Mouse.Button!Mouse.Time

For additional information on this variable and its fields, see the CURSOR procedure.

Contains a prefix string for error messages issued by PV-WAVE. The default is a percent sign. This system variable provides a way to distinguish error messages from normal output.

Controls the direction of image transfers. If !Order is 0, images are transferred from bottom to top (i.e., the row with a 0 subscript is written on the bottom). Setting !Order to 1 transfers images from top to bottom.

The main system variable structure for plotting.

All fields, except !P.Multi, have a directly corresponding keyword parameter in the main plot procedures: AXIS, PLOT, OPLOT, CONTOUR, and SURFACE.

The !P structure fields are explained in the following sections.

Corresponding Plot Keyword: Background

The background color index. When erasing a window, all pixels are set to this color. The default value is 0.

Corresponding Plot Keyword: Charsize

The overall character size of all annotation. The normal size is 1. The main plot title size is 1.25 times this parameter.

Corresponding Plot Keyword: Charthick

The thickness of characters drawn with the vector fonts. Normal thickness is 1.0, double thickness is 2.0, and so on.

Corresponding Plot Keyword: None.

Contains a six-element vector. The first four elements specify in device coordinates a rectangle used to clip the graphics window. The rectangle is specified in the form [(x0, y0), (x1 , y1)]. The coordinates specify the lower-left and upper-right corners of the clipping rectangle, respectively. Normally the clipping rectangle is set to the Data Plot Area (the area bounded by the coordinate axes). The last two elements of this system variable are reserved for internal use by PV-WAVE.

Corresponding Plot Keyword: Color

Color index used to draw data, axes, and annotation.

Corresponding Plot Keyword: Font

The index of the graphics text font. !P.Font = -1 uses the software-drawn fonts (also called Hershey or vector-drawn fonts). !P.Font = 0 uses the hardware-drawn fonts. For information on hardware-drawn fonts available for a particular output device, see Appendix , Output Devices and Window Systems. See Software Fonts in Chapter 10 of the PV-WAVE User's Guide, for a complete description of the vector-drawn fonts.

Corresponding Plot Keyword: Gridstyle

Lets you change the default linestyle of x-, y-, and z-axis tick marks. The default is a solid line. Other linestyle choices and their index values are listed in the following table:

!P.Linestyle

Corresponding Plot Keyword: Linestyle

The style of the lines used to connect points.

The linestyle index is an integer, as described in the following table:

!P.Multi

Allows making multiple plots on a page or a screen. It is a five-element integer array defined as follows:

• !P.Multi(0) contains the number of plots remaining on the page. If !P.Multi(0) is less than or equal to 0, the page is cleared, the next plot is placed the upper-left-hand corner, and !P.Multi(0) is reset to the number of plots per page.

• !P.Multi(1) is the number of plot columns per page. If 0, one is assumed. If more than two plots are positioned in either the x or y direction, the character size is halved.

• !P.Multi(2) is the number of rows of plots per page. If 0, one is assumed.

• !P.Multi(3) is the number of plots stacked in the z dimension.

• !P.Multi(4) is 0 to make plots from left to right (column major), and top to bottom, and is 1 to make plots from top to bottom, left to right (row major).

To position two plots across the page:

!P.Multi = [0, 2, 0, 0, 0] 
PLOT, X0, Y0 ;Make left plot 
PLOT, X1, Y1 ;Right plot

To position two plots vertically:

!P.Multi = [0, 0, 2, 0, 0] 
PLOT, X0, Y0 ;Make top plot 
PLOT, X1, Y1 ;Bottom plot

To make four plots per page, two across and two up and down:

!P.Multi = [0, 2, 2, 0, 0]

and then call plot four times.

To reset !P.Multi back to the normal one plot per page:

!P.Multi = 0

For more information on !P.Multi, see the PV-WAVE User's Guide.

Corresponding Plot Keyword: NoClip

If set, this keyword disables the default clipping for the OPLOT procedure. By default, OPLOT uses the value of !P.Clip for its clipping rectangle. If you set !P.NoClip=1, then this default clipping is disabled for OPLOT. The Clip keyword takes precedence over the setting of !P.NoClip.

Corresponding Plot Keyword: Nsum

The number of adjacent points to sum to obtain a plotted point. If !P.Nsum is larger than 1, every group of !P.Nsum points is averaged to produce one plotted point. If there are m data points, then m / !P.Nsum points are displayed. On logarithmic axes a geometric average is performed.

It is convenient to use Nsum when there is an extremely large number of data points to plot because it plots fewer points, the graph is less cluttered, and it is quicker.

Corresponding Plot Keyword: Position

Specifies the position of the plot within the graphics window. It is called by specifying a four-element vector as follows:

!P.Position = [Xmin, Ymin, Xmax, Ymax]

The minimum and maximum position values are specified in normalized coordinates. For example, to position a plot in the center of the screen, type:

!P.Position = [0.2, 0.2, 0.8, 0.8]

Corresponding Plot Keyword: Psym

Specifies by reference number a symbol used to mark each data point. Each point drawn by PLOT and OPLOT is marked with a symbol if this field is non-zero. The available symbols and their corresponding reference numbers are shown in the following figure.

The USERSYM procedure is used to create a user-defined symbol (number 8).

For symbol number 10, Histogram, data points are plotted in the histogram mode. Horizontal and vertical lines are connect the plotted points, as opposed to the normal method of connecting points with straight lines.

Negative values of !P.Psym cause the symbol designated by |!P.Psym| to be plotted at each point with solid lines connecting the symbols. For example, a !P.Psym value of -5 plots triangles at each data point and connects the points with lines.

Specifies the positioning of the plot and its associated annotation (i.e., anything that can be specified with the PLOT command). The difference between !P.Region and !P.Position is that !P.Region provides a margin around the plot to accommodate plot annotation. It is called by specifying !P.Region's maximum and minimum values in normalized coordinates:

!P.Region = [Xmin, Ymin, Xmax, Ymax]

For example, to position a plot with its associated annotation in the center of the screen, type:

!P.Region = [0.2, 0.2, 0.8, 0.8]

Corresponding Plot Keyword: Subtitle

The plot subtitle, placed under the x-axis label.

Contains the homogeneous 4-by-4 transformation matrix.

Corresponding Plot Keyword: T3d

Enables the three-dimensional to two-dimensional transformation contained in the homogeneous 4-by-4 matrix !P.T.

Corresponding Plot Keyword: Thick

The thickness of the lines connecting points. A thickness of 1.0 is normal, 2 is double-wide, and so on.

Corresponding Plot Keyword: Tickformat

Changes the default format for x-, y-, and z-axis tick labels using FORTRAN-style format specifiers.

See ![XYZ].Tickformat for more information.

Corresponding Plot Keyword: Ticklen

The length of the tick marks, expressed as a fraction of the plot size. The default value is 0.02. A !P.Ticklen of 0.5 produces a grid, while a negative value for !P.Ticklen makes tick marks that extend outside the window, rather than inwards.

See also ![XYZ].Ticklen.

Corresponding Plot Keyword: Title

The main plot title. The text size of this main title is larger than the other text by a factor of 1.25.

Contains the colon-separated directory path to search for procedures, functions, and arguments of executive commands.

The main system variable structure for Date/Time plotting attributes. The fields of this structure are described below.

Corresponding Plot Keyword: Box

If zero, the background box for the Date/Time axis labels is off; if one, the background box is turned on. (Default: 0no box)

Corresponding Plot Keyword: Compress

If zero, compression is off; if one, compression is on. (Default: 0no compression)

If compression is set with the Compress keyword or !PDT.Compress, and this system variable is set to one, holidays are excluded from the results of Date/Time routines such as DT_ADD, DT_SUBTRACT, and DT_DURATION. (Default: 1)

If compression is set with the Compress keyword or !PDT.Compress, and this system variable is set to one, weekends are excluded from the results of Date/Time routines such as DT_ADD, DT_SUBTRACT, and DT_DURATION. (Default: 1)

Corresponding Plot Keyword: Max_Levels

Sets the maximum number of levels on a Date/Time axis. For more information, see the Max_Levels keyword in Chapter 3, Graphics and Plotting Keywords.

Corresponding Plot Keyword: Month_Abbr

If one, month names are abbreviated if there is not enough room to draw them on a plot axis; if zero, month names will not be abbreviated, and only the months which fit the space available on the axis will be displayed. (Default: 0months are not abbreviated)

Corresponding Plot Keyword: Start_Level

Allows you to override the starting level of the Date/Time axis labels that PV-WAVE derives. The default is -1, which causes starting levels to be selected automatically.

Contains axis ranges generated by the PLOT procedure.

Corresponding Plot Keyword: DT_Range

Can be used to specify an exact Date/Time axis range. You must pass in the desired start and end values from a Date/Time Julian value. The specified range may be adjusted slightly depending on the data. To force an exact axis range (exactly as specified), set the XStyle keyword to two. See the description of XStyle in Chapter 3, Graphics and Plotting Keywords.

This is a read-only system variable, which is mainly for internal use.

Corresponding Plot Keyword: Week_Boundary

Allows you to set a different day of the week as the boundary for numbering the start of the week on the axis levels. (0 = Sunday, 1= Monday, etc.)

The floating-point value of pi. This is a read-only system variable.

A string variable containing the prompt used by PV-WAVE.

Array of strings containing the names for fiscal quarters. The default names of these labels are Q1, Q2, Q3, and Q4.

This system variable is used to suppress error messages. It can have the following values:

!Radeg

A floating-point value for converting radians to degrees. The value is 180 / or approximately 57.2958. This is a read-only system variable.

Contains the value of the time at which you started PV-WAVE as a date/time structure.

A string containing, by default, a colon (:) character. This character is used to separate the parts of a time (for example, 07:54:58.000). To use a different character, change the value of this variable. This variable is used by the DT_PRINT, DT_TO_STR, and DC_WRITE_* routines.

A structure whose four string fields contain the current operating system, architecture and name (platform) of the machine running PV-WAVE, and the current PV-WAVE version number. This is a read-only system variable.

This system variable is created by the CREATE_WEEKENDS procedure. It contains an array of long integers, where ones represent weekends and zeros represent weekdays. The values are defined by the CREATE_WEEKENDS routine.

The system variables !X, !Y, and !Z, are structures that affect the appearance and scaling of the three axes. The fields for !X are described here. !Y and !Z have identical fields with identical meanings and usage.

In addition, almost all fields have corresponding keyword parameters, with identical function, but with temporary effect. For example, to suppress the minor tick marks on the x-axis using the !X system variable:

!X.Minor = -1

while to suppress them in the call to PLOT:

PLOT, X, Y, XMinor = -1

The name of the keyword parameter is simply the name of the system variable field, prefixed with the letter X, Y, or Z.

The fields for the !X system variable are explained in the following sections.

Corresponding Plot Keyword: [XYZ]Charsize

The size of the characters used to annotate the axis and its title. This field is a scale factor applied to the global scale factor. For example, setting !P.Charsize to 2.0 and !X.Charsize to 0.5 results in a character size of 1.0 for the x-axis.

The output axis range. Setting this variable has no effect; set !X.Range to change the range. !X.Crange(0) always contains the minimum axis value, and !X.Crange(1) contains the maximum axis value of the last plot.

Corresponding Plot Keyword: [XYZ]Gridstyle

Lets you change the default linestyle of tick marks along the x-, y-, and z-axes. The default is a solid line. Other linestyle choices and their index values are listed in the following table:

![XYZ].Margin

Corresponding Plot Keyword: [XYZ]Margin

A two-element array specifying the margin around the sides of the plot window, in units of character size. Default margins are 10 (left margin) and 3 (right margin) for the x-axis, 4 (bottom margin) and 2 (top margin) for the y-axis. For the z-axis the default margins are both 0.

When calculating the size and position of the plot window, PV-WAVE first determines the plot region, the area enclosing the window plus the axis annotation and titles. It then subtracts the appropriate margin from each side, obtaining the window.

Corresponding Plot Keyword: [XYZ]Minor

The number of minor tick intervals. If ![XYZ].Minor is 0, the default, the number of minor ticks is automatically determined. You can force a given number of minor tick intervals by setting this field to the desired number. To suppress minor tick marks, set ![XYZ].Minor to -1.

Corresponding Plot Keyword: [XYZ]Range

The input axis range, a two-element vector. The first element is the axis minimum, and the second is the maximum. Set this field, or use the corresponding keyword parameter, to specify the data range to plot. Because the endpoints of axes are rounded, the final axis range may not be equal to this input range. The field ![XYZ].Range contains the axis range used for the plot.

Set both elements equal to 0 for automatic axis ranges:

!X.Range = 0

To force the x-axis to run from 5.5 to 8.3:

!X.Range = [5.5, 8.3]
PLOT, X, Y

Alternatively, by using keywords:

PLOT, X, Y, XRange = [5.5, 8.3]

Note that even though the range was set to (5.5, 8.3), the resulting plot has a range of (5.5, 8.5), because of the axis rounding. To inhibit rounding, set !X.Style to 1.

Corresponding Plot Keyword: None.

Contains the normalized coordinates of the region. This field is similar to !X.Window in that it is set by the graphics procedures and is a two-element floating-point array.

The scaling factors for converting between data coordinates and normalized coordinates (a two-element array). The formula for conversion from data (X_d) to normalized (X_n) coordinates is:

Xn = Si Xd + S0

If logarithmic scaling is in effect, substitute log10 X_d for X_d.

Corresponding Plot Keyword: [XYZ]Style

The style of the axis encoded as bits in a longword. The axis style may be set to exact, extended, none, or no box using this field. See the following table for details.

Example

To set the x-axis style to exact, use:

!X.Style = 1

or by using a keyword parameter:

PLOT, X, Y, XStyle = 1

The thickness of the axis line and tick marks. 1.0 is normal.

Corresponding Plot Keyword: [XYZ]Tickformat

Changes the default format for axis tick labels using FORTRAN-style format specifiers. For example, the following statement changes the default tick label format to floating-point numbers carried to two decimal places.

!X.Tickformat = '(F5.2)'

The specified width of the format is at least five characters; however, this width expands automatically to accommodate larger values.

For more information on format specifiers, see Explicitly Formatted Input and Output in Chapter 8 of the PV-WAVE Programmer's Guide. See also Example 3: Specifying Tick Label Formats in Chapter 4 of the PV-WAVE User's Guide.

Note that only the I (integer), F (floating-point), and E (scientific notation) format specifiers can be used with !X.Tickformat. Also, you cannot place a quoted string inside a tick format. For example, ("", F5.2, "") is an invalid !X.Tickformat specification.

Corresponding Plot Keyword: [XYZ]Ticklen

The length of tick marks, expressed as a fraction of the plot size. The default value is 0.02. A negative value makes tick marks that extend outside the window, rather than inward.

Corresponding Plot Keyword: [XYZ]Tickname

The annotation for each tick. A string array of up to 30 elements. Setting elements of this array allows direct specification of the tick label. If this element contains a null string, the default value, PV-WAVE annotates the tick with its numeric value. Setting the element to a one-blank string suppresses the tick annotation.

To produce a plot with an abscissa labeled with the days of the week:

!X.Tickname = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT']

; Set up x-axis tick labels.

!X.Ticks = 6

; Use six tick intervals, requiring seven tick labels.

PLOT, Y

; Plot the data, this assumes that Y contains 7 elements.

The same plot can be produced, using keyword parameters, with:

PLOT, Y, XTickname = ['SUN', 'MON', 'TUE', $
    'WED', 'THU', 'FRI', 'SAT'], XTicks = 6

; Set fields, as above, only temporarily.

See Chapter 8, Working with Date/Time Data, in the PV-WAVE User's Guide for information on creating axes with date and time data.

Corresponding Plot Keyword: [XYZ]Ticks

The number of major tick intervals to draw for the axis. If ![XYZ].Ticks is set to 0, the default, PV-WAVE will select from three to six tick intervals. Setting this field to n, where n 0, produces exactly n tick intervals, and n + 1 tick marks.

Corresponding Plot Keyword: [XYZ]Tickv

The data values for each tick mark, an array of up to 30 elements. You can directly specify the location of each tick by setting ![XYZ].Ticks to the number of tick marks (the number of intervals +1) and storing the data values of the tick marks in ![XYZ].Tickv. If, by default, ![XYZ].Tickv(0) is equal to ![XYZ].Tickv(1), PV-WAVE will automatically determine the value of the tick mark.

Corresponding Plot Keyword: [XYZ]Title

A string containing the axis title.

Corresponding Plot Keyword: [XYZ]Type

Specifies the type of axis, 0 for linear, 1 for logarithmic, 2 for Date/Time.

Contains the normalized coordinates of the axis end points, the plot window. This field is set by PLOT, CONTOUR, and SURFACE. Changing its value has no effect. It is a two-element floating-point array.