Manual:DIL Manual/restore()
restore()
Function (unitptr). Loads units saved with store() back into the game.
restore(filename : string, u : unitptr)
Reads the file that store() wrote and loads the units in it into
u, or into the unit running the program when u is null. Units inside
other units come back inside them, and equipment a character wore is worn again. With
store() this keeps things through a reboot: a chest's contents, a room's donations,
parcels in a mail system.
Parameters
| Name | Type | Meaning |
|---|---|---|
| filename | string | The file's name, as given to store(): letters, digits, _ and . only, at most 512 characters.
|
| u | unitptr | The unit to put them in, or null for the unit running the program. |
Returns
unitptr: the first unit loaded, whether u is null or not. That is the container
when it was stored with store(u, name, TRUE), and otherwise the first of the stored
contents (the others are in u too). Null when there is no such file, or it is
empty.
Notes
- A program read from a file (a room's or object's program when the zone boots, a unit brought back with restore(), a
recallprogram on a player) doesn't run until the first event reaches it, and that event only takes it as far as itswait(): the event itself is lost. A room program waiting for a command misses the first one after a boot. Programs on units that%resetloads start at once and aren't affected. - The files are in the
unitsfolder of the zone's DIL file directory, or of the
server'sdil_file_dir(server.cfg) when the zone has none.
- A name with other characters (a
/, a space) is refused with a line in the zone's
log, and the result is null.
- Restoring doesn't remove the file: restore it twice and you have two copies. Remove it with
delunit() when it has served.
store()of a unit with nothing in it writes no file, so an older file stays and
is restored. Use delunit() when the unit is empty, as in the example.
- A unit whose definition no longer exists in its zone comes back as slime
(The slimy remains of ...).
- Only zones whose access level in
zonelistis 10 or less may use it. In other
zones the program stops at once, and the attempt is logged.
- It reads the disk: don't call it often.
Example
dilbegin keep_chest();
var
u : unitptr;
i : integer;
fn : string;
code
{
fn := "chest_" + self.nameidx + "." + self.zoneidx;
u := restore(fn, self); // put back what was in it before the reboot
heartbeat := PULSE_SEC * 300;
:start:
pause;
if (self.inside == null)
i := delunit(fn); // store() of an empty chest writes nothing
else
store(self, fn, FALSE); // the contents, not the chest
goto start;
}
dilend
A chest that keeps its contents through reboots: it puts back what it held, then saves its contents every five minutes.