Utility Functions

In addition to the SPPS Functions, there are several Utility Functions that augment the NCAR GKS package. The members of this set functions discussed here are:

NGCKOP - function to check if a given workstation is open.
NGDOTS - draws filled dots or circles with any size or color.
NGMFTC - temporarily close a metafile workstation.
NGPICT - controls breaks in a picture drawing sequence.
NGREOP - reopens a metafile for appending.
NGSRAT - Saves/restores/sets NCAR GKS primitive attribute settings.

NGCKOP

NGCKOP is a function that takes a GKS workstation identifier as an argument and returns a "1" if the workstation is open and a "0" otherwise.

------------------------------------------------------
              Argument          |   Type    | Mode 
------------------------------------------------------
INTEGER FUNCTION NGCKOP (WKID)  |  Integer  | Input
------------------------------------------------------

WKID: Integer GKS workstation identifier.

The statement:

      IOPEN = NGCKOP(WKID)

will set IOPEN to "1" if the workstation whose identifier is WKID is currently open, otherwise IOPEN will be set to "0".

NGDOTS

The GKS standard requires that marker type 1 always be displayed as the smallest possible dot. For this reason a dot marker will not be scaled, regardless of the value of the marker size scale factor supplied to GSMKSZ. The NGDOTS utility has been added to allow for drawing dots or circles at any size and in any color.

------------------------------------------------------
  Argument           |   Type    | Mode  | Dimension
------------------------------------------------------
CALL NGDOTS (X,      |   Real    | Input | NUM
             Y,      |   Real    | Input | NUM
             NUM,    |  Integer  | Input |
             SIZE,   |   Real    | Input |
             ICOLOR) |  Integer  | Input |
------------------------------------------------------

X: Specifies the X world coordinates where a sequence of circular filled dots (or circles) is to be drawn.
Y: Specifies the Y world coordinates where a sequence of circular filled dots (or circles) is to be drawn.
NUM: The number of dots (or circles) to be drawn.
SIZE: Specifies the size, in world coordinate Y-axis units, of the diameter of each dot to be drawn.
ICOLOR: The GKS color index specifying what color the dots will be.

The coordinates must be world coordinates and not user coordinates. NGDOTS does not respect the log scaling or axis reversal options of the SET call and will report a warning if these are not set to their default values.

The dots are scaled appropriately so that they will be circular when the normalization transformation does not preserve aspect ratio.

The algorithm is to construct a single circle and then translate it to the various coordinate positions. The original circle is computed by using trig functions to get points in the first octant, and then using symmetries to get the rest of the points on the circle.

The number of points used for the circle is adjusted depending on the relative size of the circle. The maximum number of points is 512 and the minimum is 8.

If circles are desired rather than dots, then toggle the ngmisc parameter CT (see the man page for ngmisc_params which describes all of the available ngmisc parameters) with a call to NGSETI:

      CALL NGSETI('CT',1)

before NGDOTS to get circles, and

      CALL NGSETI('CT',0)

before calling NGDOTS to get dots. The default is to draw dots.

Assuming that normalization transformation 0 is in effect and that color index 2 has been defined as red in a call to GSCR, then

        CALL NGDOTS(0.5, 0.25, 1, 0.1, 2)

would draw a single red dot at world coordinate position (.5,.25) with a diameter of 0.1 .

Assuming that normalization transformation 0 is in effect and that color index 2 has been defined as red in a call to GSCR, then

        CALL NGDOTS(0.5, 0.25, 1, 0.1, 2)

would draw a single red dot at world coordinate position (.5,.25) with a diameter of 0.1 .

Do an "ncargex fngngdts" for a relevant example.

NGMFTC

NGMFTC temporarily closes an NCGM, allowing for subsequent reopening with NGREOP.

-----------------------------------------
  Argument           |   Type    | Mode  
-----------------------------------------
CALL NGMFTC (WKID)   |  Integer  | Input 
-----------------------------------------

WKID: Integer GKS workstation identifier.

NGMFTC can be called at any time after a metafile workstation has been opened, even in the middle of drawing a picture. The primary use of NGMFTC is to allow for writing to more than one metafile in a single job execution. Since NCAR GKS does not allow for having more than a single NCGM workstation open at a time, you can use NGMFTC to stop output to one metafile while you write to another metafile and then resume output to the initial metafile.

If you simply want to suspend output to a metafile workstation, but do not need to write to another metafile workstation, simply use the GKS entry GDAWK to deactivate the workstation, thus suspending output, and GOPWK to reactivate the workstation when you want to resume output.

For saving the state of all primitive attribute values of an NCGM workstation at the time of the temporary close and restoring them at the time of the reopen with NGREOP, see the documentation for NGSRAT.

If NGMFTC is used and NGREOP is not subsequently invoked to reopen the file so that it can be terminated normally in the same job step, then an improperly terminated metafile will result from the temporary close.

Do an "ncargex pgkex27" for a relevant example.

NGPICT

NGPICT can be utilized to handle breaks in a GKS picture drawing sequence. The actions taken depend on whether the designated workstation is a metafile or an output/input workstation. An option is provided for prompting the user when an output/input workstation is ready and waiting after a pause. NGPICT is designed to be used when more precise control over individual workstations is desired than that offered by FRAME. This might be desirable, for example, when an application is controlling several simultaneously active workstations. To use NGPICT one should be opening GKS workstations with GOPWK rather than with OPNGKS.

-----------------------------------------
  Argument           |   Type    | Mode  
-----------------------------------------
CALL NGPICT (WKID,   |  Integer  | Input 
             ACTION) |  Integer  | Input 
-----------------------------------------

WKID

designates the workstation identifier of a workstation as it was specified in a GOPWK call.

ACTION

specifies the action to be taken on the workstation WKID. Legal values are:

0: Execute an UPDATE WORKSTATION on WKID. All pending action items for WKID are made current. All buffers are flushed.
1: Execute an UPDATE WORKSTATION followed by a CLEAR WORKSTATION. The workstation screen is cleared after being made current.
2: Execute an UPDATE WORKSTATION followed by a pause waiting for a mouse click or a key click.
3: Execute an UPDATE WORKSTATION followed by a pause followed by a CLEAR WORKSTATION after the pause has been terminated by a mouse click or a key click.
4: Same as 3 except a "<READY>" prompt is issued in the lower left corner of the window after the UPDATE WORKSTATION.

If WKID designates a metafile, then a CLEAR WORKSTATION is done which inserts an END PICTURE into the metafile. The result produced in this case would be the same as that resulting from a call to FRAME. The only valid actions for a metafile workstation are 0 and 1.

If WKID=2 designates a metafile workstation, then

        CALL NGPICT(2,1)

would duplicate the action of a FRAME call.

If WKID=2 designates an X11 workstation, then

        CALL NGPICT(2,4)

would cause a pause in the X11 window and wait for a key click or a mouse click. A "<READY>" prompt, indicating that the window is waiting for a mouse click or a key click, would appear at the lower left of the X11 window after the window has been updated. After a mouse click in the X11 window, that window will be cleared before program execution continues.

NGREOP

NGREOP is called to reopen an existing NCAR Graphics metafile for appending. The reopened metafile may be a complete metafile that was created in the same job step, or a different job step, or the metafile may be an incomplete one that has been temporarily closed with a call to NGMFTC.

------------------------------------------------------
  Argument           |   Type    | Mode  | Dimension
------------------------------------------------------
CALL NGREOP (WKID,   |  Integer  | Input | 
             CONID,  |  Integer  | Input |
             ITYPE,  |  Integer  | Input |
             FNAME,  | Character | Input |
             IOPT,   |  Integer  | Input |
             IAT,    |  Integer  | Input | 14
             RAT,    |  Integer  | Input |  7
             NCOLRS, |  Integer  | Input | 
             NSTART, |  Integer  | Input |
             CTAB)   |   Real    | Input | 3 x NCOLRS
------------------------------------------------------

WKID

designates a GKS workstation identifier.

CONID

designates a GKS conection identifier.

ITYPE

specifies the workstation type. Currently the only valid value is "1". This subroutine may be augmented to accommodate PostScript files in the future.

FNAME

specifies the filename of the metafile being opened for appending.

IOPT

specifies the desired action:

0: reestablish the color table only (using the color table in argument CTAB described below). The attributes of the reopened workstation will be set to default values and may well be out of sync with the current GKS attributes. action items for WKID are made current. All buffers are flushed.
1: reestablish the color table and GKS state (the GKS state as supplied in arguments IAT and RAT described below). The state values will not be flushed to the metafile.
2: reestablish the color table and GKS state and flush the GKS state values to the metafile.
3: reestablish the color table and flush the current GKS state values to the metafile (not the values in IAT and RAT).

IAT

contains GKS integer state variables as detailed in the documentation for NGSRAT.

RAT

contains GKS floating-point state variables as detailed in the documentation for NGSRAT.

NCOLRS

specifies the number of colors in the color table supplied in argument CTAB, described below.

NSTART

specifies the color index associated with the first color in the color table CTAB (all other color indices are filled in in sequence). For example, if NCOLRS = 3 and NSTART = 4, then the color values defined in CTAB would be used to define color indices 4, 5, and 6.

CTAB

specifies a color table used to initialize the reopened metafile. This color table does not necessarily have to agree with the color table in effect when the original metafile was created.

The most common usage of NGREOP would be in conjunction with usage of NGSRAT and NGMFTC. NGMFTC would be used to temporarily close a metafile and NGSRAT used to save the state of the GKS primitive attributes at the time of the close. To reopen the temporarily closed metafile you would call NGREOP with the attribute settings previously saved and a setting of IOPT of 2. NGMFTC can be used to temporarily close a metafile any time after that metafile has been opened, even in the middle of a picture.

NGREOP only reopens the metafile and does not activate it. It will be necessary to call GACWK before sending graphics primitives to the reopened metafile.

NGREOP can also be used to reopen a previously created metafile - either created in an independent job step, or in the same job step.

The following sequence:

        CALL NGMFTC(1)
        CALL NGSRAT(2, IAT, RAT)

          ... do stuff

        CALL NGREOP(CALL NGREOP(1, 2, 1, 'gmeta1', 2, 
       +            IAT, RAT, NCOLS, 0, CTAB)

would temporarily close the metafile with workstation ID of 1 (in this case a metafile with name "gmeta1") and save the GKS state variables at the time of the close. Then the call to NGREOP would reopen the metafile for appending.

Do an "ncargex pgkex27" for a relevant example.

NGSRAT

NGSRAT can be used to save, restore, or set all NCAR GKS primitive attribute values in a single call.

------------------------------------------------------
  Argument           |   Type    | Mode  | Dimension
------------------------------------------------------
CALL NGSRAT (IOPT,   |  Integer  | Input | 
             IAT,    |  Integer  | Input | 14
             RAT)    |   Real    | Input |  7
------------------------------------------------------

IOPT

specifies the desired action:

0

save the current settings of all attributes internal to the subroutine, i.e. not in the IAT and RAT arrays.

1

restore the context from the most recently saved state.

2

return the current context in the output arrays IAT (integer attributes) and RAT (floating-point attributes) as follows:

IAT(1): Clip indicator
IAT(2): Line type
IAT(3): Polyline color index
IAT(4): Marker type
IAT(5): Polymarker color index
IAT(6): Text font
IAT(7): Text precision
IAT(8): Text color index
IAT(9): Text path
IAT(10): Text horizontal alignment
IAT(11): Text vertical alignment
IAT(12): Fill area interior style
IAT(13): Fill are style index
IAT(14): Fill area color index
RAT(1): Linewidth scale factor
RAT(2): Marker scale factor
RAT(3): Character expansion factor
RAT(4): Character spacing
RAT(5): Character height in world coordinates
RAT(6): Character up vector, X component in world coordinates
RAT(7): Character up vector, Y component in world coordinates

3

set the context to the values specified in the IAT and RAT arrays (as described above).

IAT

An integer array, of length 14, that has meaning only if IOPT equals 2 or 3.

RAT

A real array, of length 7, that has meaning only if IOPT equals 2 or 3.

If you want to save the state of the NCAR GKS primitive attribute settings, call NGSRAT with a first argument of 0. When the first argument is 0, the IAT and RAT arrays (second and third arguments) are ignored and the state values are stored internally to NGSRAT.

To restore the NCAR GKS primitive attribute values to what they were as of the last time NGSRAT was called with argument IOPT = 0, then call NGSRAT with first argument of 1. IAT and RAT are ignored in this case.

If you call NGSRAT with a fist argument of 2, then the current settings of the NCAR GKS primitive attribute values are returned in arrays IAT and RAT as per the description of IAT and RAT above.

If you call NGSRAT with a fist argument of 3, then arrays IAT and RAT must be supplied and the values therein will be used to set the NCAR GKS primitive attribute values as per the description of IAT and RAT above.

A common use of NGSRAT would be in conjunction with NGMFTC and NGREOP for saving the GKS state after writing to one metafile, writing to a new metafile, and then restoring the GKS state when reopening the initial metafile.

The following sequence:

        CALL NGSRAT(0,IAT,RAT)

          ... do some setting and drawing

        CALL NGSRAT(1,IAT,RAT)

would save the values of all NCAR GKS primitive attributes before the code that does setting and drawing and then restore the attribute values after the setting and drawing.

Do an "ncargex pgkex27" for a relevant example.