Conventional routines

If you look at a number of TONTO modules, you will find that almost all of them will have a number of routines with the same name. These are called conventional routines, and they are always associated with the same kind of task in every module.

The presence of conventional routines makes the task of understanding and using a module slightly easier, since one has a pre-expectation of what tasks are performed by a certain routine. Indeed, if you want to write a new module within the TONTO system, it is best not to use the conventional routine names except for their intended purpose, otherwise you will confuse people.

The purpose of these conventional routines will be described below.

If you are interested in running TONTO, the most important conventional routine for you is the read routine or the process_input routine. You should read about them below.

copy(object)

This routine makes a copy of another object of the same type. Any pointers to objects are allocated before copying, so the routine leads to a memory leak.

create; destroy

The create routine is used to allocate memory for a pointer to a data type described by the module. Sometimes arguments are supplied to create in order to set default values at allocation time.

The destroy routine is used to deallocate memory for a pointer to a data type described by the module.

The use of these routine causes a memory "leak" which is monitored by memory checking routines in TONTO, provided these routines have been enabled at compile time.

created; destroyed

The created routine returns TRUE if the data object (assumed to be a pointer) has been allocated.

The destroyed routine returns TRUE if the data object (assumed to be a pointer) has been deallocated.

create_copy(object)

This routine first creates (i.e. allocates) a new object and then makes a copy of it, in the sense of the copy(object) routine.

data_length(keywords)

This routine is used to determine the length of a list of input data for a vector type object. The data is inputted from the stdin file and is assumed to be in the order specified in the keywords variable.

destroy_ptr_part

If a data type has and components which are pointers, then this routine is used to deallocate memory for pointer components.

nullify_ptr_part

If a data type has and components which are pointers, then this routine is used to nullify these pointer components. This is useful in cases where the multiple pointers are pointing to the same piece of memory. Multiple aliasing is rare in TONTO (it is inefficient and leads to concoluted code), but it is sometimes used to save memory.

process_input(word); process_input(keyword)

There are usually two routines with the name process_input. Both are used to map an inputted keyword, detected by routine read, to the actual module routine which performs the task.

The process_input(word) routine processes a single STR variable word, while the process_input(keyword) routine takes a sequence of STR values keyword as input. This latter routine is typically used to input lists of derived data according to a predefined sequence of keywords, specified in the macros file in the INPUT_DATA_ORDER variable for the module, or specified manually via a list_order= keyword.

Note that if any single STR variable is comprised of a list of blank separated keywords or data, then the process_input routine will recursively process these keywords or data as a separate file using the read routine. This is useful for embedding commands in list oriented data.

See the chapter called Using TONTO to do calculations> for more details.

put

The put routine, or any routine beginning with put is used to output information concerning the object to the textfile stdout.

read

The read routine is used to input a sequence of "keywords" from an input file. These keywords are then interpreted using the process_input routine, which may cause the input of additional data from the input file, or cause certain calculation to be performed, or both.

In the case of array or list type objects, there are three special keywords alwaqys recognised by the read routine: list= and list_order=.

The form of the input style for data and the allowed keywords for any module have been described respectively in the chapter called Using TONTO to do calculations> and the chapter called Keyword documentation for TONTO>.

read_data

The read_data routine is used to input a sequence of "keywords" for a list or vector type object. It is always called from the read routine.

read_units

This is an input routine which is used to set the default units to something other than atomic units. read_units reads a string from the input stream which it interprets as a new units symbol. The next object that is inputted is assumed to be in these units; after the next object has been inputted, the default units is returned back to the default atomic units. It is always associated with the units= keyword.

redirect; revert

When the redirect routine is available and called, the name of a new file is read from the stdin file, and this file is opened and used as the new stdin.

When the revert routine is used, the stdin reverts back to the original file.

These routines are quite similar to save and unsave but they are used in the context of I/O operations.

same_as; equals

These routines test whether the object has the same data values as another data object. The routines should be synonymous and provide a generalisation of the == operation.

save; unsave

When the save routine is available and called, a new object is created and a pointer to the original object is saved as a component of this new object.

The unsave routine will deallocate the new object and then create an object with its original state.

These routines are useful for objects that can create new versions of themselves from themselves.

set_defaults

This routine is used to set certain default values for the components of the data type described in the module. Default values may also be set by explicit initialisation of the type components using the DEFAULT or DEFAULT_NULL macros defined in the macros file. (These latter macros are not available on systems where the LANGUAGE_FORTRAN_90 compile option has been set due to unavailablity or problems with Fortran 95 compilers).

set_to

Assigns parts of the data object from other data types. For pointer objects, copies are not made, but pointer assignments are used. This routine can be thought of as an alias for, or generalisation of, the = operation.