![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
![]() ![]() |
Examples are an X-terminal, a printer, a PostScript file, a mouse or a set of crosshairs.
In interactive jobs, Garfield by default usually has only X-terminal output, while in batch it will have only PostScript output.
These defaults can be changed both with the command line line arguments -terminal and -metafile and from the running program via the commands described below.
Workstations can be in 3 states in Garfield, 2 of which are also in the GKS definition:
Moving between the 3 states is accomplished with the following set of commands:
state | reached from previous by | to return to previous |
---|---|---|
defined | ADD-WORKSTATION
| DELETE-WORKSTATION
|
open | OPEN-WORKSTATION
| CLOSE-WORKSTATION
|
active | ACTIVATE-WORKSTATION
| DEACTIVATE-WORKSTATION
|
A workstation that is to be activated, must already be open.
The argument is an alphanumeric string designating the workstation, two workstations are predefined: TERMINAL and METAFILE. You can define additional workstations via !ADD-WORKSTATION.
Format:
! ACTIVATE-WORKSTATION workstation
Example:
! deact metafile (make some plots) ! act metafile (make final version of plots again)
You do not wish to fill the metafile with useless plots. Therefore, you first make a few tests without metafile active and once you are happy with them, you activate the metafile and make the plots again.
Two workstations are predefined in Garfield: TERMINAL and METAFILE, you may not create workstations by those names (unless you delete them first).
After !ADD-WORKSTATION, the workstation is in the state 'defined', which in GKS terminology means that the workstation is neither 'open' nor 'active'. Use !OPEN-WORKSTATION and !ACTIVATE-WORKSTATION to first open and then activate the newly defined workstation.
For output-only workstations (2nd format), a file name must be given. In both formats, either the type (e.g. MG600 or APPENDIX_E) or the GKS identifier (the driver number) must be specified, but not both. The connection identifier and the offset between logical unit and connection identifier are both optional and can both be used together with TYPE and with GKS-IDENTIFIER.
Format for input/output workstations:
! ADD-WORKSTATION name [TYPE type] [GKS-IDENTIFIER GKSid] [CONNECTION-IDENTIFIER conid]
Format for output (metafile, PostScript etc) workstations:
! ADD-WORKSTATION name [TYPE type] [GKS-IDENTIFIER GKSid] [OFFSET offset] FILE-NAME file
Example:
!add postscript type ps file-name garfield.ps
This instruction adds a PostScript formatted metafile.
The angle should be entered in degrees.
Format:
!ARROW-TIP-ANGLE angle
Example:
!arrow-angle 60
This would make the tip angles twice the default.
[The default setting is 30 degrees.]
The length should be specified as a fraction of the total length of the arrow.
Format:
!ARROW-TIP-LENGTH fraction
Example:
!arrow-length 0.2
This would make the tip a bit shorter than the default.
[The default setting is 0.3.]
Format:
!CLEAR-SCREEN
Before !CLOSE-WORKSTATION, the workstation should be in the state 'open', afterwards it is in the state 'defined'. It can be re-opened with !OPEN-WORKSTATION and then be activated with !ACTIVATE-WORKSTATION.
Any file attached to the workstation being closed, will also be closed. This file may be overwritten if you perform an !OPEN-WORKSTATION again.
Format:
! CLOSE-WORKSTATION workstation
Example:
!close metafile
This will deactivate workstation METAFILE if still active, then close the workstation and close the file receiving the graphics output.
Each workstation has (at least) two predefined colours: the colour used by default for all items: FOREGROUND and the screen which is in BACKGROUND, items plotted with this colour are therefore normally invisible.
For each additional colour, you have to state how much red, blue and green there is in it, each on a scale of 0 to 1 inclusive. White (or FOREGROUND) has 1 for all three, the BACKGROUND has 0 for all three.
The format allows for a workstation to be specified, this should for the time not be used.
Format:
! COLOUR colour_name RED red BLUE blue GREEN green [WORKSTATION wkid]
Examples:
! COL RED BLUE 0 GREEN 0 RED 1 ! COL LIGHT_BLUE BLUE 1 RED 0 GREEN 1
However, if the area over which the contours are to plotted is much smaller than 1, then contours will occasionally be "jumping" from one contour segment to another, with the default set of parameters. This can be cured by lowering the epsilon parameters by a factor of 10.
Contour plotting works as follows:
Format:
! CONTOUR-PARAMETERS [ BISECTION-ITERATIONS n_bisection ] ... [ EPSILON-GRADIENT eps-gradient ] ... [ EPSILON-TRACING eps_tracing ] ... [ GRID-TOLERANCE tol ] ... [ NEWTON-ITERATIONS n_Newton ] ... [ STEP-MAXIMUM steps ]
Example:
area -0.01 -0.01 0.01 0.01 !cont-par eps-gra 1e-4 eps-tra 1e-4 plot cont V
Since the area is small, the step size scaling factor for computing gradients and for making steps perpendicular to the gradient are reduced to 10**-4.
Additional information on:
After this operation, the workstation is in the GKS state 'open'. The workstation can then be closed via !CLOSE-WORKSTATION or re-activated by !ACTIVATE-WORKSTATION.
This instruction is used to disable temporarily graphics output to the metafile (e.g. when you wish to optimise some parameters without getting a huge metafile) or to the terminal.
Format:
! DEACTIVATE-WORKSTATION workstation
Example:
! deact terminal
Temporarily suspends graphics output to the terminal.
After this operation, all information about the workstation is lost. A workstation can therefore not be opened or activated again after a !DELETE-WORKSTATION - it has to be added to the tables again with !ADD-WORKSTATION.
Format:
! DELETE-WORKSTATION workstation
Example:
!delete metafile
You opened the metafile by accident and decide you don't need a metafile at all during this run.
Format:
EXIT
The representation and colour tables are closely connected. When retrieving representations and colours, the recommended approach is to first read the colours and then the representations. Since the representations contain a colour sequence number (assigned on the basis of the colour table present when processing REPRESENTATION statements) rather than a colour name, reading a new colour table without updating the colour references in the representation table, can create incorrect colour references. Representation files do contain colour names, ensuring correct references.
You may modify colours after having retrieved them from a file - modifications of colours do not change their sequence number.
Format:
! GET-COLOURS dsname [member]
Examples:
!GET-COL TEST PARROT
Picks up the member PARROT on dataset TEST.
Be sure that all colours that are referenced by the representations in the file, are defined before issuing a !GET-REPRESENTATION command. In practice, this means that GET-COLOURS commands should precede !GET-REPRESENTATION commands. Items that reference an undefined colour will be shown with a colour set to FOREGROUND.
Format:
! GET-REPRESENTATION dsname [member]
Examples:
!GET-REP TEST MG*
Picks up the first member that matches MG*, presumably MG600.
Format:
! INQUIRE-DEFERRAL-UPDATE-STATE
Example:
!inq-def
Format:
!INQUIRE-LEVEL
Format:
!INQUIRE-OPERATING-STATE
Format:
!INQUIRE-WORKSTATIONS
All distances are measured in Normalised Device Coordinates (NDC) which cover the graphics screen from 0 to 1 both in x and in y. The image in Garfield figures covers both in x and in y, the range [0.1, 0.9] leaving the margins for labels, numbers, comments, the time stamp and the title.
Format:
!LAYOUT [ X-NUMBER x_number ] ... [ Y-NUMBER y_number ] ... [ X-DECADE x_decade ] ... [ Y-DECADE y_decade ] ... [ X-LABEL x_label ] ... [ Y-LABEL x_label ] ... [ TITLE title ]
Additional information on:
Format:
!MAP-COLOURS
A workstation to be opened must already have been defined, for instance via !ADD-WORKSTATION. After !OPEN-WORKSTATION, the workstation is in the GKS state 'open' and can be activated by means of !ACTIVATE-WORKSTATION.
Format:
! OPEN-WORKSTATION workstation
Example:
!add falco type falco !open falco !act falco
This example shows how to add, open and activate a workstation named FALCO of type FALCO.
If you switch GRID on, a coordinate grid is plotted on top of your plots.
The gas plots have forced vertical logarithmic scales, the logarithmic/linear options are reset when these plots are produced. These options are otherwise not touched.
Format:
! OPTIONS [GRID | NOGRID] ... [TIME-STAMP | NOTIME-STAMP] ... [LOGARITHMIC-X | LINEAR-X] ... [LOGARITHMIC-Y | LINEAR-Y] ... [CLEAR-BEFORE-PLOT | NOCLEAR-BEFORE-PLOT] ... [CLEAR-AFTER-PLOT | NOCLEAR-AFTER-PLOT] ... [WAIT-BEFORE-PLOT | NOWAIT-BEFORE-PLOT] ... [WAIT-AFTER-PLOT | NOWAIT-AFTER-PLOT] ... [DISPLAY-CONTROL-CHARACTERS | EXECUTE-CONTROL-CHARACTERS]
Example:
!OPT GRID
(The plots that follow will have a grid overlaid.)
Additional information on:
Each item is associated with one or more primitives: polyline, text, polymarker or fill area. Each of the primitives has a series of attributes.
Example: the title of the plot is a piece of text and the attributes of text you can change are the font, the character quality, character size etc.
Per REPRESENTATION statement, you may modify only one item; if an item consists of more than one primitive, you are further restricted to only one of these.
If the attributes are omitted, the current representation is shown. If the item is omitted, all representations are displayed.
Format:
! REPRESENT item attribute value attribute value ...
Examples:
!rep title text-font -7, text-precision stroke, text-colour red, ... character-height 0.03 !rep isochrones linetype solid polyline-colour blue !rep isochrones polymarker-colour blue !rep isochrones
The first example will ensure the title is plotted in the locally defined (font number is negative) font -7, using the colour RED (which you are supposed to have defined beforehand). The characters will be a bit larger than default.
The next two examples show how isochrones can be plotted in blue. Isochrones consist both of lines segments and single points, hence two statements are needed: polyline and polymarker.
The last example inquires the representation of the isochrones. Both the polyline and polymarker attributes are shown.
Additional information on:
Format:
!RESET-COLOURS
Format:
!SET-DEFERRAL-STATE ... { AS-SOON-AS-POSSIBLE | BEFORE-NEXT-INTERACTION-GLOBALLY | ... BEFORE-NEXT-INTERACTION-LOCALLY | AT-SOME-TIME } ... { SUPPRESSED | ALLOWED}
The map contains the shaded variations of the the colours of the fill area representations BOX-TICKMARKS, PLANES, CONDUCTORS-1, CONDUCTORS-2, CONDUCTORS-3, DIELECTRICA-1, DIELECTRICA-2 and DIELECTRICA-3 representations that are used for one or more solids.
These shades are only generated during execution of the AREA statement. No colour memory is allocated for representations that are not in use - it can therefore be that parts of the shading map are left empty.
The number of shades of each colour can be set with the COLOURS option of the AREA command.
This string may contain expressions in terms of global variables.
Whether the time stamp appears at all is controled with the TIME-STAMP graphics option.
Format:
! STAMP string
Examples:
!stampglobal vc=2000 ... !stamp "Vc=\{vc\}"
In the first example, you ask the program to display the current time stamp comment string. In the second example, you first set a global variable VC, probably in the &CELL section. You then include the value of this variable in the stamp. Note the use of the escape character (backslash, see ESCAPE): without backslash, VC would be substituted and subsequent changes in the value of VC would not be reflected in the string that is plotted. With the backslash, the { and } are preserved as part of the string and substitution of the value of VC is done only when the string is plotted.
Format:
! WRITE-COLOURS DATASET dsname [member] [REMARK remark]
Example:
! WR-COL TEST.DAT PARROT "Lots of bright colours"
Representation datasets are read with GET-REPRESENTATION.
Format:
! WRITE-REPRESENTATION DATASET dsname [member] [REMARK remark]
Example:
! WR-REP TEST.DAT MG600 "For Monterey terminals"
Formatted on 0103-05-16 at 14:05.