dataset: structure

file

The file name of a Garfield library identifies the library to the operating system. The name of a Garfield library is normally chosen by the user.

In general, the file name should be entered the way it is usually entered on system where you run Garfield. There are however a few points to keep in mind:

Some operating systems, such as Unix, distinguish case in the file names while Garfield translates all normal commands to upper case. Unix file names furthermore sometimes contain symbols that act as separators in Garfield (blank, comma, colon, equal sign). To avoid problems, place double quotes around the file name on such systems.
You may use environment variables in Unix file names, prefixing them with a dollar sign ($). You may also use the tilde (~) to point to your the home directory and, in the CERN AFS area, the tilde followed by a user name for another user's home directory.
File names on Vax/VMS and OpenVMS can contain colons (:) which act as separators in Garfield. Here too, you have to place either single or double quotes around the file name.
On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes.

When you access a file via a procedure Call, then the file name is contained in a String and no further precautions need to be taken.

Garfield libraries are on most computers variable record length sequential files to the operating system. On IBM, the datasets are opened with a fixed record length of 133.

The first record is a line of length 133 which is only there to make sure the operating system doesn't reduce the record length between successive accesses. This record is written automatically when a new file is opened.

member

Garfield files are plain text files. For Garfield purposes, they are composed of one or more members - but the operating system will not be aware of this.

Each member is identified through a name, a string of 8 characters. As a rule, the user can chose the member name but users tend to leave the field empty (in which case it will be set to "< none >").

Since the various GET commands will by default search for the first member of the appropriate type, you can leave the member name blank if the file contains only one member of each type.

New members are appended to a file, they do not replace existing members.

Although a single file is allowed to contain several members with the same name and the same type, this is to be avoided since only the first of these members can be accessed. Problems of this kind occur for instance if you have a dataset that contains histograms which are retrieved, updated, and then written back to the file. The use of the DELETE-OLD-MEMBER global option is recommended in such cases.

The INDEX dataset command and the INQUIRE_MEMBER procedure can be used to find out which members are present in a dataset. The dataset command DELETE will mark members for deletion and PURGE will remove deleted members from a dataset.

Case is not relevant in member names. If, when writing, you surround the member name with double quotes, then the member will have the exact name that you entered. However, when reading, all case variations will be declared to match. For instance, a member called "ExB" in the file can be retrieved as "exb", "eXb", "EXB" etc.

Each member starts with a header record formatted as follows:

Character	Contents	Length
1	a percent sign (%)	1
2	a blank, changed to 'X' if the member is deleted	1
3-10	the string "Created "	8
11-18	day (dd/mm/yy) on which the member was written	8
19-22	the string " at "	4
23-30	time (hh.mm.ss) at which the member was written	8
31	is blank	1
32-39	member name	8
40	is blank	1
41-48	type of the member	8
49	is blank	1
50	double quote (")	1
51-79	remark	29
80	double quote (")	1

type

The type is used to ensure that e.g. the cell description reading routine doesn't attempt to read a signal. Thus, you may give the cell and track descriptions associated with a single chamber the same member name, and you can therefore use nearly identical GET statements in the cell, gas and signal sections.

The type given to a member is chosen by the program according to the following scheme:

Type	Description	Main user
ARRIVAL	Output of the ARRIVAL instruction	User
CELL	Compact format cell description	Internal
ISOCHRON	Equal time contours (isochrons)	User
GAS	Compact format gas description	Internal
GRAPHCOL	Colour table	Internal
GRAPHREP	Representation table	Internal
HIST	Histograms	Both
MATRIX	Matrices	Internal
MINIMUM	Output from the MINIMISE instruction	User
OUTPUT	General output	User
SIGNAL	Signals	User
TRACK	Prepared tracks	Internal
TRANSLAT	Input translation table	Internal
XTPLOT	Output from the XT-PLOT instruction	User

Types marked "User" are intended for use by the user and can freely be modified. Types marked "Internal" are not meant to be of use to the user, and should also not be modified.

remark

In addition to the name and a type, a remark string can be attached to a member. This string is chosen by the user and is meant to make identification of the member easier.

The remark has a length of 1 to 29 characters.

Go to the top level, to dataset, to structure, to the topic index, to the table of contents, or to the full text.

Formatted on 21/01/18 at 16:55.