VCS
1. Setup Information  


This chapter--the recommended starting point for VCS users--provides basic setup information, including instructions on configuring and running VCS in interactive vs batch mode, as well as an initial orientation to using the software.

Other chapters of this User's Guide contain tutorial Examples on how to exercise different software capabilities, Hints on the features and functions of each interactive panel, and details on VCS Scripts.


1.1 Before Running VCS

The steps that should be followed before running VCS are described in this section. These include putting in place various input files, setting fonts for XGKS, and adding additional continental map files if desired.


Recommended Input Files

It is strongly recommended that two input files be put in place before attempting to run VCS. These include a file for specifying initial attributes and a file for printing hard copy. See also instructions on other input files for setting XGKS fonts, mapping continents, and running scripts in subsequent sections.

At start-up, VCS reads a script file named initial.attributes that defines the initial appearance of the VCS Interface. Although not required to run VCS, this initial.attributes file contains many predefined settings to aid the beginning user of VCS. The path to the file must be:

/$HOME/PCMDI_GRAPHICS/initial.attributes

where /$HOME denotes the user's home directory. (Note, when VCS is executed for the first time, a /PCMDI_GRAPHICS subdirectory will be created automatically if it has not already been created.)

The contents of the initial.attributes file can be customized by the user. This is most easily accomplished in interactive mode by bringing the VCS Interface to a state having the desired appearance at start-up, and then saving this state by accessing the Script I/O Panel and selecting the blue `Replace the initial.attributes File' button there. This action will place a new initial.attributes file with the desired settings in the user's

/$HOME/PCMDI_GRAPHICS

directory. For recovery purposes, the old initial.attributes file is copied to file initial.attributes% in the same directory.

VCS graphical displays can be printed only if the user customizes a HARD_COPY file (included with the VCS software) for the home system. The path to the HARD_COPY file must be:

/$HOME/PCMDI_GRAPHICS/HARD_COPY

where /$HOME denotes the user's home directory. The HARD_COPY file contains the following necessary information for printing at the user's home site:

Note, it is recommended that VCS users read the entire contents of the HARD_COPY file for additional information on printing in VCS. See also the Example on Printing CGM Files and Hints on the Print CGM Panel.


Setting XGKS Fonts

XGKS is an implementation of the ANSI Graphical Kernel System in C, the programming language used to develop VCS. XGKS fonts pertain to those used for graphical displays on the VCS Canvas.

Before running VCS, it is necessary to set the environment variable XGKSFontDir. That is, enter:

setenv XGKSFontDir /the_absolute_path/fontdb.SGI for SGI

setenv XGKSFontDir /the_absolute_path/fontdb.Solaris for Sun Solaris

setenv XGKSFontDir /the_absolute_path/fontdb.DEC for DEC Alpha

etc...

where /the_absolute_path denotes the absolute path on the user's home system to the relevant fontdb file.

It is best if this setenv statement is included in the .login or .cshrc file located in the user's home directory (/$HOME).

Note, if VCS aborts with the message:

"XGKS: can't load font 1 from path ./fontdb - aborting"

then the XGKSFontDir variable is improperly set.

Nine XGKS font styles are supported:

See the Hints on the Text Editor Panel for information on how to choose the desired XGKS font style within VCS.

See also information below on the user's option of setting fonts for the VCS windows (other than the VCS Canvas) when running in interactive mode.



Continents Mapping Options

One has the option of using continental maps that are predefined or that are user-defined. Predefined continental maps are either internal to VCS or are specified by external files. User-defined continental maps are specified by additional external files that must be read as input.

VCS has two internal continents maps: "Fine Continents" and "Coarse Continents". The "Fine Continents" map includes smaller islands and highly detailed coastlines, while the "Coarse Continents" map excludes these features. If continents are not defined by the user or if specified continents are not found by VCS, then the "Fine Continents" map is used as the default.

Included with the VCS executable are three ASCII continent files: the data_continent_states ("United States") file includes "Fine Continents" and the boundaries of the 48 continental United States; the data_continent_political ("Political Borders") file includes "Fine Continents" and political borders of sovereign countries; and the data_continent_river ("Rivers") file includes "Fine Continents" and major North American rivers. (It is anticipated that a world rivers file will be made available at a later date.)

These external continent files must be located in the user's

$HOME/PCMDI_GRAPHICS

directory. If VCS cannot find a specified external continents file, then it will use "Fine Continents" as the default.

As many as six additional continental map files can be defined by the user. These files must be located in the user's

$HOME/PCMDI_GRAPHICS

directory and must be named: data_continent_other7, data_continent_other8, ... , data_continent_other12, respectively.

The ASCII format for the external continents files is:

number of x-y coordinates; line-type value; values of x-y coordinates

The number of x-y coordinates is twice the number of map points to be connected by the defined continental line type. A maximum of 100 map points (200 x-y coordinates) are allowed.

The line-type values are integers ranging from 0 to 11, where:

0 signifies "No Continents"

1 signifies "Fine Continents"

2 signifies "Coarse Continents"

3 signifies "United States" (with "Fine Continents")

4 signifies "Political Borders" (with "Fine Continents")

5 signifies "Rivers" (with "Fine Continents")

Values 6 through 11 signify the line type defined by the files data_continent_other7 through data_continent_other12.

The x-y coordinates are pairs of floating-point values having units of degrees longitude-degrees latitude, respectively.

Consider the following example:

6  1 102.500 63.500 105.000 73.550 107.500 66.000 
8 7 98.500 45.000 101.000 47.500 103.500 40.000 101.000 42.500 
... 
-99 -99 

The first line specifies that continental line-type value 1 (i.e., "Fine Continents") is to be used to connect 3 points whose 6 x-y coordinates are 102.500 degrees longitude-63.500 degrees latitude, 105.000 degrees longitude-73.550 degrees latitude, 107.500 degrees longitude-66.000 degrees latitude.

The second line of this example specifies that user-defined continental line-type value 7 is to be used to connect 4 points whose 8 x-y coordinates are 98.500 degrees longitude-45.000 degrees latitude, 101.000 degrees longitude-47.500 degrees latitude, 103.500 degrees longitude-40.000 degrees latitude, 101.000 degrees longitude-42.500 degrees latitude.

The entries -99 -99 indicate that no more data are to be read in (i.e., denotes end-of-file).

It is recommended that the user view the other external continents files (e.g., data_continent_states) for further insights on the required ASCII format. See also the Example on Changing the Continental Outlines for information on how to implement these mapping options within VCS.



1.2 Running VCS: Command Line Options

The software can be run either interactively by use of the VCS Interface or in batch mode by use of VCS scripts (or in a combination of these modes). The following paragraphs describe how to exercise various options in executing VCS in these modes.



Running in Interactive Mode

To execute VCS in interactive mode, it is sufficient to enter

vcs

on the command line. It then will take a few moments for the VCS Interface to appear in an initial state determined by the settings in the initial.attributes file. (In this case, the VCS Interface will take up the entire monitor screen.) Options for executing VCS subject to additional criteria are described below.

The VCS Interface need not occupy the entire monitor screen (the default condition). The preferred size and position of the VCS window can be specified at the command line:

vcs -geom (width) x (height) + x_position + y_position

Here width represents the desired window length on the x axis, and height represents the desired window length on the y axis, where both are expressed in screen pixel units. Here also x_position represents the window's top left x-corner position, and y_position represents the window's top left y-corner position (both expressed in screen pixel units).

The font to be used by the window managers (as distinct from the XGKS fonts that pertain to the VCS Canvas) also can be (but need not be) specified at the command line:

vcs -font "font_name"

The font_name is a hyphenated string that must be surrounded by quotes ("..."). It takes the form

"-fndry-family-weight-slant-swidth-adstyl-pxlsz-ptSz-resx-resy-spc-avgwidth-rgstry-encdng"

Examples of font_names:

"-adobe-courier-bold-r-normal--14-140-75-75-m-90-iso8859-1" (the VCS default)
"-bitstream-charter-medium-r-normal--9-60-72-0-*-77-iso8859-1" 
"-*-times-*-r-*-*-17-*-*-*-*-*-*-*" 

Note, however, that parts of the VCS Interface may become distorted with the selection of too small or large a font.

During an interactive session, VCS can be run in quiet mode (i.e., without sound signals accompanying status messages) by entering:

vcs -quiet

A continuous script file to record all operations performed during an interactive VCS session can be saved by assigning an output file on the command line:

vcs -o /path/output_script_filename

The replay of this output script file will not reproduce the manipulations of buttons and menus that are seen during the interactive session, but will reproduce the graphics displays. The appropriate output files also will be saved.



Running in Batch Mode

In executing VCS in batch mode, a script file is read immediately after the initial.attributes file. The script file for batch-mode operation is assigned on the command line as follows:

vcs -i /path/input_script_filename

While reading this script file, VCS proceeds in batch mode, where only the VCS Canvas appears, displaying plots. After completion of the script, the VCS Interface appears showing the last plot displayed in batch mode. On option, other script files then can be selected as input for an interactive session with VCS.

To avoid display of the VCS Interface after executing the input script, enter the following:

vcs -ni /path/input_script_filename

While reading this script file, VCS proceeds in batch mode, where only the VCS Canvas appears, displaying plots. After completion of the script, VCS will exit without displaying the VCS Interface.

See also the Examples on Saving and Running Scripts and on Running in Noninteractive Modes. See the chapter on VCS Scripts for details on script syntax.


1.3 An Orientation to Using VCS

The following information orients the new user to basic VCS concepts, terminology, and operations, with an emphasis on use of the software in interactive mode. See the Example on Running in Noninteractive Modes and the chapter on VCS Scripts for details on running the software in batch mode.


The VCS Model

In the VCS model, the data display is defined by a trio of named attribute sets, designated the primary elements. These include: the data, which define what is to be displayed; the picture template, which determines the appearance of each segment of the display; and the graphics method, which specifies the display technique. Panels for manipulating these primary elements are color-coded in the VCS Interface: attributes associated with the data are represented in red, those with the graphics method in blue, and those with the picture template in green.

In addition, detailed specification of the primary elements' attributes is provided by eight secondary elements:

The initial.attributes file specifies the tables of primary and secondary element attributes assigned at the beginning of a VCS session. The user may subsequently modify these attributes.



Software Capabilities

By combining primary and secondary elements in various ways (either interactively through operations performed on VCS panels or in batch mode by use of VCS scripts), the VCS user exercises virtually complete control over the appearance of the data display. Among other capabilities, the user can



The VCS Interface

The VCS Interface (see figure) is the means by which the software is used in an interactive mode. The left half of the VCS Interface, whose appearance remains the same during an entire interactive session, consists of the Main Menu, the Message Panel, and the VCS Canvas. The right half of the VCS Interface changes in appearance according to which VCS panels are accessed by the user. Initially, however, the right half of the VCS Interface includes (see figure): a Page Description Panel; Template, Graphics Method, and Data Panels; and Data Selection and Data Selection Browser Panels .

The Main Menu, which occupies the top-left portion of the VCS Interface, is the means by which many VCS panels are accessed (the remainder being accessed from panels brought up via the Main Menu). The Main Menu may be displayed either in compact or in full view:


When displayed in compact view, each pulldown menu has a tear-off selection, which appears as a dashed line in the first menu element. The tear-off enables the menu selections to be retained on the display to facilitate subsequent operations. Note, panel-access instructions in this User's Guide (as well as in Hints displays within VCS) assume that the Main Menu is displayed in compact view.

To display the Main Menu in full view, select the `View All Menu Items' from the `File' category of the compact Main Menu (i.e., Main Menu: `File' -> `View All Menu Items'). (To revert to compact view, select the `Main Menu' button in the upper left corner of the full-view display.) To initiate VCS with the Main Menu in full view, save the state of a VCS session with the Main Menu in this mode as a new initial.attributes file.

The Message Panel is located below the Main Menu in the left half of the VCS Interface. Status messages confirming the execution of various operations in VCS, as well as error messages indicating the failure of intended actions, appear on the Message Panel during the course of a VCS interactive session. If VCS is not run in quiet mode, these messages will be accompanied by sound signals.

The VCS Canvas, located below the Message Panel in the bottom left half of the VCS Interface, is the space in which data variables are displayed by means of eleven different graphics methods in VCS. The VCS Canvas may be expanded to take up the full size of the VCS Interface. A variety of other options also are available (see Hints on the VCS Canvas).

Some 44 panels are required to fully exercise the capabilities of VCS. As an interactive session proceeds, some VCS panels cover others that were accessed previously. As necessary, the display of any covering panel may be turned off (thereby revealing an underlying panel) by selecting the `Skull and Crossbones' button that is located in the upper left corner of each VCS panel.


Use of Mouse Buttons

In using VCS interactively, all 3 mouse buttons are utilized. Overall, the left button is used most frequently, while the right button is used least frequently.

The left button is used for selection in VCS (as it is in any X-window/Motif environment). Selection involves a two-stage process in which the user moves the mouse pointer to a particular point on the screen (e.g., over the red `Apply' button on the VCS Interface) and then presses the left mouse button. (Note, where a selection process is described in other words in the VCS documentation--e.g., as in "press the red `Apply' button"--it should be understood that selection with the left mouse button is intended.)

Sometimes selection involves clicking (i.e., pressing and releasing in quick succession) the left button once or twice (e.g., when selecting a data variable using the Data Selection Panel--see also Step 3 of the Example on Creating Plots by Different Graphics Methods). In other instances, selection involves pressing and holding the left button until another operation (e.g., highlighting a particular item in a popup menu) is completed; only then is the left button released.

The middle mouse button is used for copy and drop operations in VCS. A typical example is:

This two-step operation effects a copy of the data attribute set from the Data Panel and a drop of the data attribute set onto the picture descriptor form, which causes the data to be plotted on the VCS Canvas.

The right button is used for deletion in VCS, as for example when deleting a data attribute set name from the red Data Panel.

Note, in a few instances the left, middle, and right mouse buttons are utilized differently than described above (e.g., in using the Colormap Editor/Table Panel, the Dimension Manipulation Panel, and the VCS Canvas). Where this is the case, the required mouse-button operations are spelled out clearly in the documentation.


Further Help with VCS

When any panel is accessed interactively within VCS, a brief description of its purpose and basic instructions on its use are provided--at the user's option--in the form of Hints displays (also reproduced in this User's Guide). Note, because they cover other VCS panels, the Hints displays must be moved aside as VCS is operated. The more experienced user may therefore wish to turn off these Hints displays.

When `Hints On' is specified (via Main Menu: `Info' -> `Hints On'), selection of a VCS panel causes display of associated Hints. Turn off these Hints via Main Menu:`Info' -> `Hints Off'. To initiate VCS without displaying Hints, save the state of a VCS session with the Hints turned off as a new initial.attributes file.

In addition to the Hints, numerous tutorial Examples are included in this User's Guide to illustrate how to perform functions that often require more than one VCS panel. The Examples are divided according to the one's skill level (i.e., "Beginning", "Intermediate", and "Advanced"). It is recommended that the user first follow an appropriate example to learn how to perform the rudiments of a desired VCS function, and then refer to the associated Hints for supplemental information.

Finally, for those interested in running VCS in batch mode, this User's Guide also documents the details of VCS Scripts. Note, unlike the Hints, the Examples and Scripts documentation do not appear as displays within VCS.



Last update January 3, 1997. For further information, contact: Dean N. Williams (vcs@pcmdi.llnl.gov)
This page is maintained by Anna McCravy (mccravy@pcmdi.llnl.gov)
 and LLNL Disclaimers
UCRL-ID-120121