File names and input/output drivers

Mosel handles data streams using I/O drivers: a driver is an interface between Mosel and a physical data source. Its role is to expose the data source in a standard way such that from the user perspective, all data sources can be accessed using the same methods (i.e. initializations blocks, file handling functions). Drivers are specified in file names: all Mosel functions supporting I/O operations though drivers can be given an extended file name. This type of name is composed of the pair driver_name:file_name. When Mosel needs to access a file, it looks for the specified driver in the table of available drivers. This table contains all predefined drivers as well as drivers published by modules currently loaded in memory. If the driver is provided by a module, the module name may also be indicated in the extended file name: module_name.driver_name:file_name. Using this notation, Mosel loads the required module if necessary (otherwise the file operation fails if the module is not already loaded). For instance it is better to use mmodbc.odbc:database than odbc:database.

The file_name part of the extended file name is specific to the driver and its structure and meaning depends on the driver. For instance, the sysfd driver expects a numerical file descriptor so file sysfd:1 is a valid name but sysfd:myfile cannot work. A driver may act as a filter and expects as file_name another extended file name (e.g. zlib.deflate:mem:myblk).

When no driver name is specified, Mosel uses the default driver which name is an empty string (myfile is equivalent to :myfile). This driver relies on OS functions to access files from the file system.

The tmp driver is an extension to the default driver: it locates the specified file in the temporary directory used by Mosel (i.e. tmp:toto is equivalent to getparam("tmpdir")/toto).

The null driver can be used to disable a stream: whatever written to file "null:" is ignored and reading from it is like reading from an empty file.

The mem driver uses a memory block instead of a file handled by the operating system. A file name for this driver is of the form mem:label[/minsize[/incstep]] where label is an identifier whose first character is a letter and minsize an optional initial amount of memory to be reserved (size is expressed in bytes, in kilobytes with suffix "k" or in megabytes with suffix "m"). The label being recorded in the dictionary of the model symbols it cannot be identical to any of the identifiers of the model (the function newmuid might be used to generate a unique identifier). The memory block is allocated dynamically and resized as necessary. By default the size of the memory block is increased by pages of 4 kilobytes: the optional parameter incstep may be used to change this page size (i.e. the default setting is "label/0/4k"). The special value 0 modifies the allocation policy: instead of being increased of a fixed amount, the block size is doubled. In all cases unused memory is released when the file is closed.
The mem driver may also be used to exchange data with an application using the Mosel libraries (refer to the Mosel Libraries Reference Manual for further explanation).

The tee driver can only be open for writing and expects as file name a list of up to 6 extended file names separated with `&': it opens all the specified files and duplicates what it receives to each of them. If only one file is given or if the string terminates with `&', output is also sent to the default output stream (or error stream if the file is used for errors). For instance, writing to the file "tee:log1&log2&" has the effect of writing at the same time to files "log1" and "log2" as well as sending a copy to the console.

The bin driver can only be used for initializations blocks as a replacement of the default driver: it allows to write (and read) data files in a platform independent binary format. This file format is generally smaller than its ASCII equivalent and preserves accuracy of floating point numbers. This driver can be used in 2 different ways: a single file including all records of the initialisations block is produced if a file name is provided. For instance, in the following example the file "mydata" will contain both A and B:

initialisations to "bin:mydata"
  A
  B
end-initialisations

With the second form (without file name) one file is generated for each record of the block. The following example produces 2 files: "mydata_A" to contain the values of record A and "mydata_B" for values of B:

initialisations to "bin:"
  A as "mydata_A"
  B as "mydata_B"
end-initialisations

When using this form in an initialisations to block, the option append may be specified such that files are open in append mode.

The other predefined drivers (sysfd, cb and raw) are useful when interfacing Mosel with a host application. They are described in detail in the Mosel Libraries Reference Manual.

I/O drivers provided by modules of the Mosel distribution are documented with the corresponding module (see Part Modules of this manual).