Manual:DIL Manual/restore()

Function:  unitptr restore( filename : string , u : unitptr );

  filename
         The name of the Unit file
  u
         The Unit you want to restore into or null if none
  Return
         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:

---~---~---~---~---~---~---~---~---

dilbegin chest_load ();
var
        waist:unitptr;/*to hold the null returned in this example*/
        chest:unitptr;/*pointer to the storage chest*/
code
{
chest:=load ("chest@myzone");/*get the container*/
if (chest==null)
        {
        log ("Error");/*log an error*/
        quit;
        }

waist:=restore("chest."+self.zoneidx,chest);
/*
restore given filename into chest
waist can be ignored in this dil since it is not used.
*/
link (chest, self);/*link chest into room*/
quit;/*dil load routine done destroy self.*/
}
dilend

---~---~---~---~---~---~---~---~---

Example 2:

---~---~---~---~---~---~---~---~---

dilbegin chest_load ();
var
        chest:unitptr;/*item to be loaded*/
code
{
chest:=restore("chest."+self.zoneidx,null);/*restore into chest*/
if (chest== null)/*see if something was restored*/
        chest:=load("donate_chest@"+self.zoneidx);
        /*load a new one if there is nothing restored*/

link (chest, self);/*link item into room*/
quit;/*destroy the load dil.*/
}
dilend

---~---~---~---~---~---~---~---~---

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
Store a Unit to a Unit file and
Delete a Unit file.

---~---~---~---~---~---~---~---~---