introduction


introduction

  Garfield is a program for the detailed simulation of two-dimensional
  drift chambers consisting only of thin wires and infinite equipotential
  planes. As a general rule, no sacrifice in terms of numerical quality
  has been permitted in favour of CPU time or program length. Thus, the
  program has an entirely different range of application than say GEANT.

  It is a program that can be run both interactively and in batch on
  a wide variety of computers without significant change in outwards
  appearance. The program is fully command driven but if you desire to
  add some pieces, you'll find no major obstacles (the program has been
  written in Fortran-77 and uses Patchy as pre-processor).

  The help facility you are in at present is the normal Vax HELP on Vax
  computers and something closely resembling it on other machines. You
  can obtain further information by typing one of the items listed under
  "additional information". A return without input will take you back
  by one level. Wildcards are permitted: P* will match both PLANE and
  PERIODICITY, an asterisk at the end is always assumed. A question mark
  as only input will cause the list of alternatives to be redisplayed.

  This help file can also be read via WWW at the address:
  http://consult.cern.ch/writeup/garfield/help
  Examples of the use of the program can be found at:
  http://consult.cern.ch/writeup/garfield/examples

Additional Information on:

  • getting_started
  • input_format
  • syntax
  • special_characters
  • brackets
  • quotes
  • trouble
  • authors
  • origin
  • units
  • versions

  • &MAIN

      Garfield input exists at 3 levels:
    
      Main -> Cell section  -> algebra sub-section
                               graphics sub-section
                               ...
              Gas section   -> algebra sub-section
                               graphics sub-section
              ...
    
      The &MAIN command moves you back to the top level of program input,
      i.e. the level at which one enters the program. This level is used
      for instance to issue procedure calls that use cell or gas data.
      Since cell and gas data are made available only when leaving the
      respective sections, one can not perform e.g. drift line calculations
      before having left both the gas and cell sections.
    

    &CELL

      Enters the cell section. This is the first stage in most simulations.
      By entering this section, you clear the cell information entered in
      earlier cell sections, if any.
    
      Everything you enter, is simply stored. A comprehensive check of the
      input is only performed when leaving the section. That is also the
      time the compact format cell dataset is written, if requested, the
      layout is plotted, the cell description is printed etc.
    
      Format:
    
      &CELL
    

    Additional Information on:

  • overview
  • CELL-IDENTIFIER
  • DEFINE
  • DIELECTRICUM
  • FIELD-MAP
  • GET
  • GRAVITY
  • OPTIONS
  • PERIODICITY
  • PLANE
  • READ-FIELD-MAP
  • RESET
  • ROWS
  • SAVE-FIELD-MAP
  • SOLIDS
  • TUBE
  • WRITE

  • &MAGNETIC

      This is the command you type to set or change the setting of the
      magnetic field.
    
      The cell description is not touched by this, but any existing gas
      data is cleared when this section is entered since the transport
      properties of gasses depend on the magnetic field.
    
      Initially, the magnetic field is off.
    

    Additional Information on:

  • COMPONENTS
  • OPTIONS
  • SUSCEPTIBILITY

  • &GAS

      Enters the gas section. This section establishes the gas mixture to
      be used when drifting electrons and ions. The main quantities that
      are needed for such calculations are the electron and ion transport
      properties, as well as the cluster size distribution and the cluster
      spacing.
    
      Some of these properties can be computed: the Magboltz program will
      calculate the electron drift velocity, diffusion, Townsend and
      attachment coefficient for nearly arbitrary gas mixtures. The Heed
      program takes care of clustering, also for nearly arbitrary gas
      mixtures.
    
      If you have measured gas properties, or have access to measurements
      you trust, you can enter this data in the form of tables. One can
      also replace parts of the Magboltz tables with measurements.
    
      For rapid studies which do not require great accuracy, descriptions
      of a few common gas mixtures are built in to the program.
    
      All existing gas information is cleared by entering the gas section
      or the magnetic field section since the transport properties of gasses
      depend on the magnetic field.
    
      Format:
    
      &GAS
    

    Additional Information on:

  • overview
  • built_in
  • ADD
  • CLUSTER
  • EXTRAPOLATIONS
  • GAS-IDENTIFIER
  • GET
  • HEED
  • INTERPOLATION
  • MAGBOLTZ
  • MIX
  • OPTIONS
  • PARAMETERS
  • PLOT-OPTIONS
  • PRESSURE
  • RESET
  • TABLE
  • RANGE
  • TEMPERATURE
  • WRITE

  • &OPTIMISE

      Assists in finding optimal potential settings. The original settings
      may at any time be recovered by typing RESTORE (without arguments).
      The potentials are not restored by the program itself when you leave
      the section (which is probably what you want anyway !).
    
      This section also offers some instructions that modify the cell.
    
      Format:
    
      &OPTIMISE
    

    Additional Information on:

  • overview
  • ADD
  • AREA
  • BACKGROUND-FIELD
  • CHANGE-VOLTAGES
  • CHARGES
  • DELETE
  • DELETE-BACKGROUND-FIELD
  • DELETE-CHARGES
  • DELETE-FIELD-MAP
  • DISPLAY
  • DRIFT-AREA
  • FACTOR
  • FIELD-MAP
  • FORCES
  • GRID
  • LIST-CHARGES
  • OPTIONS
  • POINTS
  • PRINT-CELL
  • READ-FIELD-MAP
  • RESTORE
  • SAVE
  • SELECT
  • SET
  • TRACK

  • &FIELD

      The field section is used to inspect the electrostatic aspects
      of your chamber. The main command of the section (PLOT) enables
      you to plot contours, 3D views, vector fields and histograms of
      almost any field-related quantity.
    
      Format:
    
      &FIELD
    

    Additional Information on:

  • overview
  • AREA
  • angle
  • CHECK
  • GRID
  • MULTIPOLE-MOMENTS
  • OPTIONS
  • PLOT-FIELD
  • PRINT
  • SAMPLE
  • SELECT
  • TIME
  • TRACK

  • &DRIFT

      Enters the part of the program devoted to displaying the behaviour
      of electrons and ions in the chamber. Both the gas and the cell
      data play a role in the computations.
    
      The central instruction is the DRIFT command, but also ARRIVAL and
      XT-PLOT can be useful for a coarse chamber calibration.
    

    Additional Information on:

  • overview
  • AREA
  • ARRIVAL-TIME-DISTRIBUTION
  • CLUSTERING-HISTOGRAMS
  • DRIFT
  • GRAPHICS-INPUT
  • GRID
  • INTEGRATION-PARAMETERS
  • LINES
  • LORENTZ-ANGLE
  • MINIMISE
  • OPTIONS
  • PLOT-FIELD
  • PREPARE-TRACK
  • SELECT
  • SINGLE
  • SPEED
  • TABLE
  • TIME
  • TIMING
  • TRACK
  • XT-PLOT
  • WRITE-ISOCHRONES
  • WRITE-TRACK

  • &SIGNAL

      Enters the section performing signal calculations.
    
      Since SIGNAL calculation and processing is strongly experiment
      dependent, this section consists only of a series of building
      blocks with which you can build an hopefully detailed simulation
      of your signal.
    

    Additional Information on:

  • overview
  • ADD-NOISE
  • AREA
  • AVALANCHE
  • CHECK
  • CONVOLUTE-SIGNALS
  • FOURIER
  • GET-TRACK
  • GRID
  • INTEGRATION-PARAMETERS
  • OPTIONS
  • PLOT-FIELD
  • PLOT-SIGNALS
  • PREPARE-TRACK
  • REPEAT
  • RESOLUTION
  • SELECT
  • SIGNAL
  • THRESHOLD
  • TRACK
  • WRITE-SIGNAL
  • WRITE-TRACK

  • &STOP

      Terminates program execution decently. &EXIT and &QUIT are synonymous.
    

    variables

      In Garfield input, one makes frequent use of variables:
    
      For instance, when you make a contour plot of the electrostatic
      potential, you type "PLOT CONTOUR V". The "V" in this statement
      is a local variable of the PLOT command which is equal to the
      electrostatic potential at a given point.
    
      When using such local variables, you normally don't have to take
      any precaution.
    
      There are however also cases when you wish to have some variables
      under your own control. Such variables exist in Garfield and are
      called global variables, or "globals" for short. The name has
      been chosen to reflect the broader scope of globals, as compared
      to the local variables mentioned above. Local variables have a
      scope limited to one command, while global variables can be used
      across sections.
    
      Since these variables are essentially under your own control,
      they are for instance not automatically evaluated. It is the
      purpose of this help topic to explain their correct use. Please
      be familiar with the contents when using globals !
    
      Global variables can be used for a variety of things:
    
      - you can use them for doing ordinary arithmetic;
      - they are used to construct DO loops, to have some
        statements executed conditionally (IF statements)
        and they also appear in CALL and PARSE;
      - their value can be substituted in ordinary commands.
    

    Additional Information on:

  • defining
  • substituting
  • types
  • predefined

  • GLOBAL

      +------------------------------------------------+
      | Do not use curly brackets in GLOBAL statements |
      +------------------------------------------------+
    
      Assigns a value to a global variable. This statement has 2
      arguments, the name of the global variable (one may re-use
      a variable used before) and the value to be assigned to the
      global variable. The value to be assigned can be a formula
      in terms of other global variables (including the variable
      itself if it already had a value):
    
      Format:
    
      GLOBAL variable value
    
      Examples:
    
      Global my_name=`abc DEF`
    
      Global argon=80
      Global ethane=20
      Global member=`a`/string(argon)/`e`/string(ethane)
    
      (The first example assigns the character string "abc DEF" to the
      variable my_name. In the second example, a suitable member name
      of a compact gas description is constructed from the Argon and
      ethane contents. Note that no curly brackets are used.)
    

    VECTOR

      Creates a new 1-dimensional Matrix, also called vector, or reads
      new data into an already existing Matrix.
    
      Newly created Matrices are 1-dimensional and have a length that
      is equal to the number of elements entered.
    
      For existing 1-dimensional Matrices, a new vector is created that
      replaces the old one. For higher dimensional Matrices, however,
      the number of dimensions and the size are kept as they were, and
      new elements replace old elements in the order in which the Matrix
      is internally stored (opposite to the Fortran convention).
    
      The VECTOR statement can read data into one or more Matrices at the
      time. If more than one Matrix is present, then the statement should
      be followed by a series of lines which contain precisely one new
      element of each of the Matrices. If only one Matrix is present, then
      one may type an arbitrary number of elements on an arbitrary number
      of lines following the statement. In either case, there should be
      a blank line to signal that all elements have been entered.
    
      Format:
    
      VECTOR x y z ...              VECTOR x
      x1 y1 z1 ...                  x1 x2 x3 ...
      x2 y2 z2 ...                  ...
      ...                           ...
      xn yn zn ...                  ... xn
      (blank line)                  (blank line)
    
      Example:
    
      Vector zzz
      0 1 2 3 4 5 6
    
      Call reshape_matrix(zzz,2,4,pi)
    
      (The VECTOR statement results in a 1-dimensional matrix of length 7,
      called ZZZ, which contains the numbers 0 to 6. The RESHAPE_MATRIX
      procedure call re-arranges this vector to a 2x4 matrix. This matrix
      has one element more than the original vector, which is filled with
      the value PI.)
    

    CALL

      +-----------------------------------------------------------+
      |      Do not use curly brackets in CALL statements         |
      +-----------------------------------------------------------+
    
      CALL gives direct access to a wide variety of routines and data
      inside Garfield. Since this statement was originally intended
      as a debugging aid, most procedures do not attempt to perform a
      complete check of their arguments nor of the appropriateness of
      the procedure call. It is for instance technically possible to
      issue a CALL DRIFT_ELECTRON when neither the gas nor the cell are
      defined.
    
      To ensure that the procedures that rely on cell and gas data work,
      one should call them only after the cell and gas sections have
      been left (e.g. via &MAIN) - it is not enough to have entered the
      cell and gas data, cell and gas data become available to the
      procedures only when the sections have been left.
    
      Procedure arguments which are only used as input, must have the
      type shown in the description. Input arguments can be global
      variables but also expressions that result in a an object of the
      required type. Arguments that are only used for output need not
      be declared on beforehand. Worse, if they are declared then any
      string, histogram or matrix associated with it, will be lost.
      Output arguments must be simple global variables - not constants,
      nor expressions.
    
      Many procedures are overloaded in the C++ sense: the same name
      is used for several procedures that differ by the data types that
      they handle.
    
      Optional arguments are enclosed in square brackets in the
      descriptions below - these brackets should not be typed !
    
      Format:
    
      CALL procedure(arg1, arg2, ... )
    
      Examples: see the various procedures.
    

    Additional Information on:

  • overview
  • ADJUST_MATRIX
  • ATTACHMENT
  • AVALANCHE
  • BARYCENTRE
  • BOOK_HISTOGRAM
  • BOOK_MATRIX
  • CARTESIAN_TO_INTERNAL
  • CARTESIAN_TO_POLAR
  • CONVOLUTE
  • DELETE_HISTOGRAM
  • DELETE_MATRIX
  • DERIVATIVE
  • DIMENSIONS
  • DRIFT_ELECTRON
  • DRIFT_ELECTRON_3
  • DRIFT_ION
  • DRIFT_ION_3
  • DRIFT_MC_ELECTRON
  • DRIFT_MC_ION
  • DRIFT_MC_NEGATIVE_ION
  • DRIFT_NEGATIVE_ION
  • DRIFT_NEGATIVE_ION_3
  • DRIFT_INFORMATION
  • DRIFT_VELOCITY
  • ELECTRIC_FIELD
  • ELECTRIC_FIELD_3
  • EXTRACT_SUBMATRIX
  • FILL_HISTOGRAM
  • FIT_EXPONENTIAL
  • FIT_FUNCTION
  • FIT_GAUSSIAN
  • FIT_MATHIESON
  • FIT_POLYA
  • FIT_POLYNOMIAL
  • FORCE_FIELD
  • GAS_AVAILABILITY
  • GET_CELL_DATA
  • GET_CELL_SIZE
  • GET_CLUSTER
  • GET_DRIFT_LINE
  • GET_E/P_TABLE
  • GET_GAS_DATA
  • GET_HISTOGRAM
  • GET_MATRIX
  • GET_PERIODS
  • GET_RAW_SIGNAL
  • GET_SIGNAL
  • GET_X_PLANE_DATA
  • GET_Y_PLANE_DATA
  • GET_WIRE_DATA
  • HISTOGRAM_TO_MATRIX
  • INQUIRE_FILE
  • INQUIRE_HISTOGRAM
  • INQUIRE_MEMBER
  • INQUIRE_TYPE
  • INTEGRATE_CHARGE
  • INTEGRATE_FLUX
  • INTERNAL_TO_CARTESIAN
  • INTERNAL_TO_POLAR
  • INTERPOLATE
  • INTERPOLATE_i
  • ION_MOBILITY
  • LIST_HISTOGRAMS
  • LIST_MATRICES
  • LIST_RAW_SIGNALS
  • LONGITUDINAL_DIFFUSION
  • LORENTZ_ANGLES
  • MAGNETIC_FIELD
  • MAGNETIC_FIELD_3
  • MAP_INDEX
  • MATRIX_TO_HISTOGRAM
  • MULTIPLY_MATRICES
  • NEW_TRACK
  • PLOT_AREA
  • PLOT_CELL
  • PLOT_COMMENT
  • PLOT_CONTOURS
  • PLOT_DRIFT_AREA
  • PLOT_DRIFT_LINE
  • PLOT_END
  • PLOT_ERROR_BAND
  • PLOT_ERROR_BAR
  • PLOT_FRAME
  • PLOT_GRAPH
  • PLOT_HISTOGRAM
  • PLOT_LINE
  • PLOT_MARKER
  • PLOT_SURFACE
  • PLOT_TEXT
  • PLOT_TRACK
  • POLAR_TO_CARTESIAN
  • POLAR_TO_INTERNAL
  • PRINT
  • PRINT_HISTOGRAM
  • PRINT_MATRIX
  • PROJECT_LINE
  • PROJECT_MARKERS
  • RESHAPE_MATRIX
  • SOLVE_EQUATION
  • STORE_SIGNAL
  • STORE_SUBMATRIX
  • STRING_DELETE
  • STRING_INDEX
  • STRING_LENGTH
  • STRING_LOWER
  • STRING_MATCH
  • STRING_PORTION
  • STRING_UPPER
  • STRING_WORD
  • STRING_WORDS
  • TIME_LOGGING
  • TOWNSEND
  • THRESHOLD_CROSSING
  • TRANSVERSE_DIFFUSION
  • WEIGHTING_FIELD
  • WEIGHTING_FIELD_3
  • WRITE_HISTOGRAM
  • WRITE_MATRIX

  • DO_loops

      +-----------------------------------------------------------+
      |      Do not use curly brackets in DO statements           |
      +-----------------------------------------------------------+
    
      DO loops allow repeated execution of a set of lines. Loops in
      Garfield do not necessarily have a loop variable. If a loop has
      one, it will run through the range you indicate until either the
      WHILE or UNTIL condition fails resp. holds. In addition, there
      are instructions to leave the loop and to skip the remainder.
    
      Do not attempt to read in a file with < while in a DO loop.
    
      Format:
    
      [FOR var FROM from [STEP step] TO to] [WHILE while] [UNTIL until] DO
    
      [statement | LEAVE [var] | ITERATE [var]]
    
      ENDDO
    
      Example:
    
      For i from 1 to 5 do
      Say "Now I has the value {I}."
      Enddo
      Say "Finished !"
    

    Additional Information on:

  • FOR
  • var
  • from
  • step
  • to
  • while
  • until
  • LEAVE
  • ITERATE

  • IF_line

      +-----------------------------------------------------------+
      |      Do not use curly brackets in IF statements           |
      +-----------------------------------------------------------+
    
      The IF line is used to execute conditionally only one line,
      for instance a &STOP if the amount of CPU time left to the
      job is less than a few seconds. An IF line is also used to
      conditionally execute an entire DO loop.
    
      Format 1:
    
      IF cond THEN statement
    
      Format 2:
    
      IF cond THEN ... DO
    
      statement | LEAVE [var] | ITERATE [var]
    
      ENDDO
    
      Examples:
    
      If time_left<10 Then & Stop
      If vax Then Say "Running on a Vax."
    
      If x>10 Then For i From 10 To 1 Step -1 Do
           If 'entier(i/3+0.001)=3' Then Iterate
           Say "x+i/3 = {x+i/3}"
      Enddo
    

    IF_block

      +------------------------------------------------------------+
      | Do not use curly brackets in IF, ELSEIF, ITERATE and LEAVE |
      +------------------------------------------------------------+
    
      IF blocks are used to conditionally execute a group of statements
      and to execute only one of a set of groups of statements depending
      on a series of conditions. IF blocks may be nested and may also
      contain entire DO loops in their branches.
    
      Format:
    
      IF cond THEN
    
      [ELSEIF cond THEN]
    
      [ELSE]
    
      ENDIF
    
      Example:
    
      If vax Then
           get 'disk$food:[garfield]lasagne.dat'
      Elseif cray|apollo|sun Then
           If Cray Then $ fetch //food/garfield/lasagne.dat ...
                -t'fn=FOOD,ft=LASAGNE'
           get "//food/garfield/lasagne.dat"
      Elseif cms Then
           get food.lasagne.*
      Else
           Say "No GET for this machine; stopping."
           & Stop
      Endif
    
      In this example, a cell (or gas) compact description is fetched
      from a file - the name depends on the machine. In the case of
      the Cray, the file is first read from the IBM.
    

    PARSE

      This instruction enables you to make input files that prompt
      for parameters. For instance, in a magnetic field section,
      you could ask for the value of the magnetic field and then
      issue a COMPONENTS instruction with the B-field the user
      specifies. You could also ask the user to enter the name of a
      cell description and then load it from a library of such
      descriptions.
    
      If you're familiar with REXX, you'll note the similarity with
      the REXX command by the same name. Keep in mind however that
      the REXX syntax is far richer than what is offered here. Also,
      in Garfield, all input is automatically evaluated as expressions
      in terms of global variables. An error results if the syntax is
      not correct. This could for instance happen if you try to enter
      character input without surrounding quotes: an attempt would be
      made to evaluate the string as an expression in terms of the
      global variables.
    
      Format:
    
      PARSE  {GLOBAL var | INPUT | TERMINAL | VALUE expression} template
    
      Example 1: Get the piece before and after the decimal dot of pi**2
    
      Parse Val pi**2 int'.'frac
    
      Example 2: Ask for a yes/no answer
    
      &FIELD
      Global yes=true
      Global no=false
      Say "Make a 3D plot ? (yes/no)"
      Until OK Do
         Parse Terminal plot_3D
         Call inquire_type(plot_3D,type)
         If 'type=`Logical`' Then
            Global OK=true
         Else
            Say "Please give an answer that evaluates to TRUE or FALSE."
            Global OK=false
         Endif
      Enddo
      If plot_3D Then plot surface
    
      The global variables YES and NO are set respectively to the values
      TRUE and FALSE so that the user can simply type. The user may still
      answer with any expression that evaluates to a Logical (e.g.: 3>4,
      FALSE etc). Note that the variables YES and NO are defined in the
      default initialisation file.
    
      Example 3: Ask for a cell name
    
      Say "Please enter the name of the cell to be read:"
      Parse Terminal cell
      (The user responds with (note the quotes !): `DC1`)
      get cell.lib {cell}
    
      Note the use of the reverse quote in the user response: since
      the global variable CELL should be a string, it should be
      enclosed in quotes. Single and double quotes would disappear
      in the process since these quotes are not part of the string
      that is entered. An equivalent, but more clumsy, user response
      would have been '"DC1"', with an outer layer of single quotes
      to keep make the double quotes inside part of the string.
    

    Additional Information on:

  • GLOBAL
  • INPUT
  • TERMINAL
  • VALUE
  • template

  • SAY

      The SAY command outputs the string that follows it, performing
      substitions of global expressions as usual.
    
      Format:
    
      SAY string
    
      Example:
    
      Say "Only {time_left} seconds left !"
    

    comments

      Comment lines start with an asterisk.
    
      Format:
    
      * anything you wish
    

    datasets

      The dataset commands assist you in inspecting Garfield datasets.
      Garfield datasets are (for Garfield purposes only) organised as
      libraries (they are sequential datasets to the operating system).
      Each member in such a dataset has a member name and a type. There
      may in addition be a remark for easier identification.
    
      Garfield datasets can be moved between machines, you may also
      operate on such datasets on other computers if the OS allows,
      at CERN for instance you can read libraries on VM from the Vaxes.
    
      All dataset commands start with a % sign. If you have lots of
      dataset commands to do, you may prefer to enter the dataset
      subsection by typing only the % sign, without arguments. In the
      dataset subsection no % has to be prefixed to the commands.
      You may not enter other subsections from within the dataset
      subsection. EXIT will get you back to the section you came from.
    

    Additional Information on:

  • DEFAULT
  • DELETE
  • DUMP-HELP-FILE
  • EXIT
  • INDEX
  • LIST
  • PACK-HELP-FILE
  • PURGE
  • RECOVER

  • graphics

      Most of the graphics settings can be changed during the run.
      For instance, one can:
    
      - add, open and activate workstations,
      - control waiting and screen clearing before and after plots,
      - switch between linear and log scales,
      - add or change colour definitions,
      - change the appearance of elements of the plots.
    
      Settings that are common for most of your runs can be placed
      more conventiently in your .garfinit (or GARFINIT.DAT) file.
      This is for instance the case of the representations, as is
      illustrated in the default .garfinit distributed with Garfield.
    
      All graphics commands start with a ! sign. If you have lots of
      graphics things to do, you may prefer to enter the graphics
      subsection by typing only the ! sign, without arguments. In the
      graphics subsection no ! has to be prefixed to the commands.
      You may not enter other subsections from within the graphics
      subsection. EXIT will get you back to the section you came from.
    

    Additional Information on:

  • workstations
  • ACTIVATE-WORKSTATION
  • ADD-WORKSTATION
  • ARROW-TOP-ANGLE
  • CLEAR-SCREEN
  • CLOSE-WORKSTATION
  • COLOUR
  • CONTOUR-PARAMETERS
  • DEACTIVATE-WORKSTATION
  • DELETE-WORKSTATION
  • EXIT
  • GET-COLOURS
  • GET-REPRESENTATION
  • INQUIRE-DEFERRAL-UPDATE-STATE
  • INQUIRE-LEVEL
  • INQUIRE-OPERATING-STATE
  • INQUIRE-WORKSTATIONS
  • MAP-COLOURS
  • OPEN-WORKSTATION
  • OPTIONS
  • REPRESENTATION
  • RESET-COLOURS
  • SET-DEFERRAL-STATE
  • SHADING-MAP
  • STAMP
  • WRITE-COLOURS
  • WRITE-REPRESENTATION

  • input

      When you start Garfield, the program performs some initialisation
      and then waits for input from the normal input stream. For jobs that
      are not likely to be repeated, one would type the various commands
      at the terminal and have them executed immediately.
    
      If, on the other hand, it is likely that you will re-run a given set
      of commands several times, changing perhaps a few parameters, then it
      is probably more convenient to place the set of commands in a file
      which is then read by Garfield. You can also create such a file starting
      from the commands recorded during a session (file called "garflast.dat"
      or similar, depending on the system) and edit it.
    
      Reading a file that contains normal input statements, is achieved with
      the "<" command.
    
      Format:
    
      < dsname [<< label]
    
      Example:
    
      < cell_section
    
      (To read the file CELL_SECTION.DAT until the end of the file.)
    

    Additional Information on:

  • dsname
  • label

  • recording

      Garfield can at your request record your terminal input.
      The command to start recording to a file called dsname is:
    
      >> dsname
    
      To stop recording, type:
    
      >>
    
      Example:
    
      >> a.b
      Say "Recording on a.b"
      >> c.d
      Say "Recording on c.d"
      >>
      Say "Not recording anymore"
    

    Additional Information on:

  • dsname

  • output

      Rerouts most of the output to a dataset. To revert to terminal
      output, enter the command without dataset.
    
      Format to start rerouting:
    
      > dsname
    
      Format to stop rerouting:
    
      >
    
      Example:
    
      > field.map
      print ex,ey,e,v
      >
    
      (This example works in the field section. First the output is
      rerouted to the dataset FIELD.MAP, this file captures the long
      printout from the PRINT command and then output is sent to the
      terminal again.)
    
      This command is taken care of by the low-level input reading routine.
      The section doesn't see it and doesn't know either where the output
      is being sent.
    

    Additional Information on:

  • dsname

  • KERNLIB_errors

      When a CERN library routine detects an error, it calls the KERNLIB
      error processing routines. These routines keep a table that contains
      the number of times each error message should be printed and how
      many errors of the kind are allowed before execution is terminated.
    
      You should not normally see KERNLIB error messages, the instruction
      described below is therefore mainly useful for debugging the program.
    
      Format:
    
      ERROR-HANDLING MESSAGE mess-id
                     [PRINT {ALWAYS | NEVER | nprint}]
                     [ABEND {NEVER | nabend}]
    
      mess-id Is the identifier of the message as listed in the 'green
      book' of CERN program library writeups. Both nprint and nabend
      are meaningful only in the range 0 to 100. Execution is terminated
      at the nabend+1 occurence of the error.
    
      For further details, see short writeup N001 (KERSET).
    

    OPTIONS

      There are global and local options. The local ones are mentioned in
      the respective sections, the global ones are described here. Global
      and local options may freely be mixed in a single OPTIONS line.
    
      Format:
    
      OPTIONS [NODEBUG | DEBUG] ...
              [NOIDENTIFY | IDENTIFY] ...
              [NOINPUT-LISTING | INPUT-LISTING] ...
              [RECORDING | NORECORDING] ...
              [PROGRESS-PRINT | NOPROGRESS-PRINT] ...
              [ON-ERROR-CONTINUE | ON-ERROR-SKIP | ON-ERROR-TERMINATE] ...
              [NODUMP-ON-GRAPHICS-ERROR | DUMP-ON-GRAPHICS-ERROR] ...
              [WARN-BUT-WRITE | WARN-AND-NOWRITE | DELETE-OLD-MEMBER ]
    
      Example:
    
      OPT ID
    
      Note: Actions depending on the setting of the ON-ERROR-... options
            are only gradually being introduced.
    

    Additional Information on:

  • DEBUG
  • IDENTIFICATION
  • INPUT-LISTING
  • RECORDING
  • PROGRESS-PRINT
  • ON-ERROR-CONTINUE
  • ON-ERROR-SKIP
  • ON-ERROR-TERMINATE
  • WARN-BUT-WRITE
  • WARN-AND-NOWRITE
  • DELETE-OLD-MEMBER

  • translation

      Translation of input characters is useful if the program has not
      been transferred properly to your computer and as a result doesn't
      recognise some special characters (such as curly brackets, carets).
    
      Your terminal may also lack some keys.
    
      The initial translation table converts tabulation characters to
      spaces on Vax, Alpha and Unix computers.
    
      You may occasionally also have to bypass the translation mechanism
      by using or modifying the escape character.
    

    Additional Information on:

  • ESCAPE
  • TRANSLATE
  • GET-TRANSLATION-TABLE
  • WRITE-TRANSLATION-TABLE

  • shell

      Aegis, DCL, Unix and VM/CMS commands can be issued from inside the
      program without having to exit the program. You may wish to view
      the shell as a sub-section - like with the sub-sections, you stay
      in the shell if you omit the command.
    
      Format for a single line command:
    
      $ [Aegis, DCL, Unix or VM/CMS instruction]
    
      Format for an excursion:
    
      $                 $               $                $
      (Aegis commands)  (Vax commands)  (Unix commands)  (CMS commands)
      return            LO              exit             RETURN
    

    Additional Information on:

  • Aegis
  • DCL
  • CMS
  • Unix

  • algebra

      Garfield can evaluate certain formulae with symbolic parameters
      without need for external compilation and linking. Although the
      use of formulae is fairly intuitive, it may be useful for some
      applications to have good understanding of the way formulae are
      dealt with.
    
      Formulae can be typed as usual in Fortran, with some exceptions:
    
      * Blanks are significant separators, e.g. 'EXP X' is an acceptable
        formula (the quotes serve to keep the string together).
    
      * Identifiers (symbolic names) are up to 10 characters long.
    
      * Not all the Fortran instrinsic functions are available and some
        intrinsic functions have a different name. Known intrinsic
        functions include: SIN, COS, TAN, ARCSIN, ARCCOS, ARCTAN, SINH,
        COSH, TANH, ARCSINH, ARCCOSH, ARCTANH, EXP, LOG, SQRT, ABS,
        ENTIER, TRAILING, STRING, NUMBER, PRODUCT, SUM, REFERENCE,
        GLOBAL, TYPE, LANDAU. In addition, various random number
        generators (uniform, Gaussian, exponential, Poisson, Polya and
        Landau) are available. Further intrinsic functions can be added
        on request.
    
      * The data types are different from those in Fortran. The type
        of variable is implicitely declared when the variables is
        created. The type can change during execution, when a value of
        a different type is assigned to a variable. Currently, the
        following data types are known:
    
        - Undefined: existing unintialised variable or
          non-existing variables
        - Number: no distinction is made between (single
          precision) reals and integers
        - Logical: TRUE and FALSE, written without dots
        - String: character strings
        - Histogram: ordinary and autorange histograms
        - Matrix: matrices of numbers
    
      Certain kinds of mixed arithmetic are permitted, for instance
      between numbers and histograms and between numbers and matrices.
      Mixed arithmetic of logicals and numbers is not permitted, but
      could easily be added if useful.
    
      Evaluation is not as quick as true Fortran but thanks to a
      translation into a very simple internal code before evaluation
      starts, the losses for repeated evaluations are small to what
      would otherwise be needed in terms of human time. The internal
      code is referred to here as "instruction lists".
    
      The translation of the formula into an instruction list, is done
      independent of the data type. It may also be possible that the
      resulting instruction list can be executed for several data types.
    
      Instruction lists can be editted in the algebra editor which is
      entered by typing a @ instead of a formula. The editor behaves like
      a subsection. On exit of the editor, the function is used by the
      calling routine to perform its task.
    

    Additional Information on:

  • argument
  • arithmetic
  • calls
  • entry_points
  • goto
  • intrinsics
  • logicals
  • matrices
  • mode
  • results
  • return
  • storage
  • ADD-ENTRY-POINT
  • CLEAR-ENTRY-POINT
  • DELETE
  • DISPLAY-ENTRY-POINT
  • EXECUTE
  • EXIT
  • FUNCTION
  • GARBAGE-COLLECT
  • INSERT
  • LIST
  • MEMORY
  • OPTIONS
  • PRINT
  • REGISTER
  • RESET
  • RESULTS
  • SIMPLIFY
  • TEST
  • VARIABLES

  • control_keys

      Control keys can be used to interrupt the program.
    

    Additional Information on:

  • Apollo
  • Vax
  • CMS

  • Keyword index. Formatted on 10/11/98.