Difference between revisions of "Manual:DIL Manual/restore()"

From DikuMUD Wiki
Jump to navigation Jump to search
(XML import)
(checked against the compiler and the interpreter; example compiles)
Line 1: Line 1:
−
<span id="bfrestore"></span>
+
= restore() =
 +
'''Function''' (unitptr). Loads units saved with store() back into the game.
  
−
  '''Function:'''  <i><!--CODE-->unitptr restore( filename : string , u : unitptr );</i><!--ENDCODE-->
+
  restore(filename : string, u : unitptr)
  
−
<!--TERM--> '''filename'''
+
Reads the file that [[Manual:DIL Manual/store()|store()]] wrote and loads the units in it into
−
<!--DEFINITION-->         The name of the Unit file
+
<code>u</code>, or into the unit running the program when <code>u</code> is null. Units inside
−
<!--TERM--> '''u'''
+
other units come back inside them, and equipment a character wore is worn again. With
−
<!--DEFINITION-->         The Unit you want to restore into or null if none
+
<code>store()</code> this keeps things through a reboot: a chest's contents, a room's donations,
−
<!--TERM--> '''Return'''
+
parcels in a mail system.
−
<!--DEFINITION-->         if 'u' null returns a pointer to the Unit loaded, if 'u' not null returns null and loads Units from the specified file into the unit 'u'
 
  
−
restore loads a copy of a unit or units which were previously saved with the
+
== Parameters ==
−
'store' command. Just as with "load", the unit is put inside the unit which
+
{| class="wikitable"
−
executes the restore command unless the 'u' argument is not null.  If the 'u'
+
! Name !! Type !! Meaning
−
argument is an unitptr like room, object, npc, or pc the items restored will be
+
|-
−
placed inside the 'u' Unit..
+
| filename || string || The file's name, as given to <code>store()</code>: letters, digits, <code>_</code> and <code>.</code> only, at most 512 characters.
−
'''Note''', It is only possible to restore items as long as the main-database
+
|-
−
contains a reference for the unit 'name@zone'.  Use 'Store' and 'Restore'
+
| u || unitptr || The unit to put them in, or null for the unit running the program.
−
sparingly, remember that items saved in player's inventories are automatically
+
|}
−
saved in this instance.
 
−
The 'store' and 'restore' are perfect for operations such as mud mailing
 
−
objects from player to player, storage devices for players that will keep
 
−
inventory through a reboot. Even the ability to save a players inventory while
 
−
they fight in an arena and restore it to them undamaged when finished. Finally
 
−
it could be used to save a donation room through reboots since it can be used on
 
−
a room to store the contents of a room any NPC or objects in the room would be
 
−
saved through reboot.
 
−
'''Disk access is always slow'''.
 
−
If you use 'Restore' on a continuous basis always attempt to keep file sizes to
 
−
a minimum for quick loading.  Otherwise you might cause serious delays on the
 
−
server. If the Dil that uses Restore saves at certain times try to make it so
 
−
the saves are spread out over as large amounts of time as possible.
 
  
−
'''Example 1:'''
+
== Returns ==
−
<i><!--CODE-->
+
unitptr: the first unit loaded, whether <code>u</code> is null or not. That is the container
−
---~---~---~---~---~---~---~---~---
+
when it was stored with <code>store(u, name, TRUE)</code>, and otherwise the first of the stored
 +
contents (the others are in <code>u</code> too). Null when there is no such file, or it is
 +
empty.
  
−
dilbegin chest_load ();
+
== Notes ==
−
var
+
* The files are in the <code>units</code> folder of the zone's DIL file directory, or of the
−
        waist:unitptr;/*to hold the null returned in this example*/
+
  server's <code>dil_file_dir</code> (<code>server.cfg</code>) when the zone has none.
−
        chest:unitptr;/*pointer to the storage chest*/
+
* A name with other characters (a <code>/</code>, a space) is refused with a line in the zone's
−
code
+
  log, and the result is null.
−
dilend
+
* Restoring doesn't remove the file: restore it twice and you have two copies. Remove it with
 +
  [[Manual:DIL Manual/delunit()|delunit()]] when it has served.
 +
* <code>store()</code> of a unit with nothing in it writes no file, so an older file stays and
 +
  is restored. Use <code>delunit()</code> 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 <code>zonelist</code> is 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 ==
 +
<pre>
 +
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
  
−
</i><!--ENDCODE-->
+
  heartbeat := PULSE_SEC * 300;
−
'''Example 2:'''
+
  :start:
−
<i><!--CODE-->
+
  pause;
−
---~---~---~---~---~---~---~---~---
+
  if (self.inside == null)
−
 
+
      i := delunit(fn);           // store() of an empty chest writes nothing
−
dilbegin chest_load ();
+
  else
−
var
+
      store(self, fn, FALSE);     // the contents, not the chest
−
        chest:unitptr;/*item to be loaded*/
+
  goto start;
−
code
+
}
 
dilend
 
dilend
 +
</pre>
 +
A chest that keeps its contents through reboots: it puts back what it held, then saves its
 +
contents every five minutes.
  
−
---~---~---~---~---~---~---~---~---
+
== See also ==
−
 
+
* [[Manual:DIL Manual/store()|store()]]
−
</i><!--ENDCODE-->
+
* [[Manual:DIL Manual/delunit()|delunit()]]
−
'''Note:'''  Example 1 is to be used if 'storall' was used not storing a container.
+
* [[Manual:DIL Manual/load()|load()]]
−
Example 2 is for items stored with 'store' with the container saved as
+
* [[Manual:DIL Manual/savestr()|savestr()]]
−
well.
 
−
'''See Also'''
 
−
[[#bpstore|Store a Unit to a Unit file]] and
 
−
[[#bfdelunit|Delete a Unit file]].
 
−
 
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
<span id="bfrestore"></span>
 
−
 
 
−
'''Function:'''  <i><!--CODE-->unitptr restore( filename : string , u : unitptr );</i><!--ENDCODE-->
 
−
 
 
−
<!--TERM-->  '''filename'''
 
−
<!--DEFINITION-->        The name of the Unit file
 
−
<!--TERM-->  '''u'''
 
−
<!--DEFINITION-->        The Unit you want to restore into or null if none
 
−
<!--TERM-->  '''Return'''
 
−
<!--DEFINITION-->        if 'u' null returns a pointer to the Unit loaded, if 'u' not null returns null and loads Units from the specified file into the unit 'u'
 
−
 
 
−
restore loads a copy of a unit or units which were previously saved with the
 
−
'store' command. Just as with "load", the unit is put inside the unit which
 
−
executes the restore command unless the 'u' argument is not null.  If the 'u'
 
−
argument is an unitptr like room, object, npc, or pc the items restored will be
 
−
placed inside the 'u' Unit..
 
−
'''Note''', It is only possible to restore items as long as the main-database
 
−
contains a reference for the unit 'name@zone'.  Use 'Store' and 'Restore'
 
−
sparingly, remember that items saved in player's inventories are automatically
 
−
saved in this instance.
 
−
The 'store' and 'restore' are perfect for operations such as mud mailing
 
−
objects from player to player, storage devices for players that will keep
 
−
inventory through a reboot.  Even the ability to save a players inventory while
 
−
they fight in an arena and restore it to them undamaged when finished.  Finally
 
−
it could be used to save a donation room through reboots since it can be used on
 
−
a room to store the contents of a room any NPC or objects in the room would be
 
−
saved through reboot.
 
−
'''Disk access is always slow'''.
 
−
If you use 'Restore' on a continuous basis always attempt to keep file sizes to
 
−
a minimum for quick loading.  Otherwise you might cause serious delays on the
 
−
server.  If the Dil that uses Restore saves at certain times try to make it so
 
−
the saves are spread out over as large amounts of time as possible.
 
−
 
 
−
'''Example 1:'''
 
−
<i><!--CODE-->
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
dilbegin chest_load ();
 
−
var
 
−
        waist:unitptr;/*to hold the null returned in this example*/
 
−
        chest:unitptr;/*pointer to the storage chest*/
 
−
code
 
−
dilend
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
</i><!--ENDCODE-->
 
−
'''Example 2:'''
 
−
<i><!--CODE-->
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
dilbegin chest_load ();
 
−
var
 
−
        chest:unitptr;/*item to be loaded*/
 
−
code
 
−
dilend
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
</i><!--ENDCODE-->
 
−
'''Note:'''  Example 1 is to be used if 'storall' was used not storing a container.
 
−
Example 2 is for items stored with 'store' with the container saved as
 
−
well.
 
−
'''See Also'''
 
−
[[#bpstore|Store a Unit to a Unit file]] and
 
−
[[#bfdelunit|Delete a Unit file]].
 
−
 
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 

Revision as of 23:04, 14 November 2026

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

  • The files are in the units folder of the zone's DIL file directory, or of the
 server's dil_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 zonelist is 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.

See also