3.6 Input and output
====================

SINGULAR's input and output (short, I/O) is realized using links.
Links are the communication channels of SINGULAR, i.e., something
SINGULAR can write to and read from.  In this section, a short
overview of the usage of links and of the different link types is given.

For loading of libraries, see LIB. For executing program scripts,
see filecmd.

Monitoring
----------
A special form of I/O is monitoring.  When monitoring is enabled,
SINGULAR makes a typescript of everything printed on your terminal
to a file.  This is
useful to create a protocol of a SINGULAR session.  The
monitor command enables and disables this feature
(see monitor).


How to use links
----------------
Recall that links are the communication channels of SINGULAR, i.e.,
something SINGULAR can write to and read from using the functions
write and read. There are furthermore
the functions dump and getdump which store resp.
retrieve the content of an entire SINGULAR session to, resp. from,
a link.  The dump and getdump commands are not available
for DBM links.

For more information, see write, read, dump,
getdump.

Example:
  ring r; poly p = x+y;
  dump("MPfile:w test.mp");   // dump the session to the file test.mp
  kill r;                     // kill the basering
  listvar();
==> // LIB                  [0]  string standard.lib
  getdump("MPfile:r test.mp");// read the dump from the file
  listvar();
==> // r                    [0]  *ring
==> //      p                    [0]  poly
==> // LIB                  [0]  string standard.lib

Specifying a link can be as easy as specifying a filename as a string.
Except for MPtcp links, links even do not need to be explicitly opened
or closed before, resp. after, they are used.  To explicitly open or
close a link, the open, resp. close, commands may be
used (see open, close).

Links have various properties which can be queried using the
status function (see status).

Example:
  link l = "MPtcp:fork";
  l;
==> // type : MPtcp
==> // mode : fork
==> // name : 
==> // open : no
==> // read : not ready
==> // write: not ready
  open(l);
  status(l, "open");
==> yes
  close(l);
  status(l, "open");
==> no

ASCII links
-----------
Data that can be converted to a string that can be written into files for
storage or communication with other programs. The data are written in
plain ASCII format. Reading from an ASCII link returns a string --
conversion into other data is up to the user. This can be done, for
example, using the command execute (see execute).

ASCII links should primarily be used for storing small amounts of data,
especially if it might become necessary to manually inspect or
manipulate the data.

See ASCII links, for more information.

Example:
  // (over)write file test.ascii, link is specified as string
  write(":w test.ascii", "int i =", 3, ";");
  // reading simply returns the string
  read("test.ascii");
==> int i =
==> 3
==> ;
==> 
  // but now test.ascii is "executed"
  execute(read("test.ascii"));
  i;
==> 3

MPfile links
------------
Data is stored in the binary MP format.  Read and write access is very
fast compared to ASCII links.  All data (including such data that cannot
be converted to a string) can be written to an MPfile link.  Reading
from an MPfile link returns the written expressions (i.e., not a string,
in general).

MPfile links should primarily be used for storing large amounts of data
(like dumps of the content of an entire SINGULAR session), and if
the data to be stored cannot be easily converted from or to a string
(like rings, or maps).

MPfile links are implemented on Unix-like operating systems only.

See MPfile links, for more information.

Example:
  ring r;
  // (over)write MPfile test.mp, link is specified as string
  write("MPfile:w test.mp", x+y);
  kill r;
  def p = read("MPfile:r test.mp");
  typeof(p); p;
==> poly
==> x+y

MPtcp links
-----------
Data is communicated with other processes (e.g., SINGULAR
processes) which may run on the same computer or on different ones.  Data
exchange is accomplished using TCP/IP links in the binary MP format.
Reading from an MPtcp link returns the written expressions (i.e., not a
string, in general).

MPtcp links should primarily be used for communications with other
programs or for parallel computations (see, for example,
Parallelization with MPtcp links).

MPtcp links are implemented on Unix-like operating systems only.

See MPtcp links, for more information.

Example:
  ring r;
  link l = "MPtcp:launch"; // declare a link explicitly
  open(l);  // needs an open, launches another SINGULAR as a server
  write(l, x+y);
  kill r;
  def p = read(l);
  typeof(p); p;
==> poly
==> x+y
  close(l); // shuts down SINGULAR server

DBM links
---------
Data is stored in and accessed from a data base.  Writing is
accomplished by a key and a value and associates the value with the key
in the specified data base.  Reading is accomplished w.r.t. a key,
the value associated to it is returned.  Both the key and the value have to
be specified as strings.  Hence, DBM links may be used only for data
which may be converted to or from strings.

DBM links should primarily be used when data needs to be accessed not in a
sequential way (like with files) but in an associative way (like with
data bases).

See DBM links, for more information.

Example:
  ring r;
  // associate "x+y" with "mykey"
  write("DBM:w test.dbm", "mykey", string(x+y));
  // get from data base what is stored under "mykey"
  execute(read("DBM: test.dbm", "mykey"));
==> x+y


<font size="-1">
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; User manual for <a href="http://www.singular.uni-kl.de/"><i>Singular</i></a> version 2-0-4, October 2002,
generated by <a href="http://www.gnu.org/software/texinfo/"><i>texi2html</i></a>.
</font>

</body>
</html>
