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

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="bpstore"></span>
+
= store() =
 +
'''Procedure.''' Saves a unit, or what is inside it, to a file.
  
−
  '''Function:'''  <i><!--CODE-->store( u : unitptr , filename : string , container : integer );</i><!--ENDCODE-->
+
  store(u : unitptr, filename : string, container : integer)
  
−
<!--TERM--> '''u'''
+
Writes the objects and NPCs inside <code>u</code>, with everything inside them, to a file.
−
<!--DEFINITION-->         The Unit that has the contents to be stored or is to be stored
+
When <code>container</code> is TRUE, <code>u</code> itself is saved too, with its contents.
−
<!--TERM--> '''filename'''
+
[[Manual:DIL Manual/restore()|restore()]] loads the file back, so things can be kept through a
−
<!--DEFINITION-->         The name of the file you want to store the Units to
+
reboot: a clan chest, a parcel for a player, an arena fighter's belongings.
−
<!--TERM--> '''container'''
 
−
<!--DEFINITION-->         Do you want to save the container 'TRUE' for yes, 'False' for no
 
  
 +
== Parameters ==
 +
{| class="wikitable"
 +
! Name !! Type !! Meaning
 +
|-
 +
| u || unitptr || The unit to save.
 +
|-
 +
| filename || string || The file's name: letters, digits, <code>_</code> and <code>.</code> only, at most 512 characters.
 +
|-
 +
| container || integer || TRUE: save <code>u</code> and its contents. FALSE: only the contents.
 +
|}
  
−
Store saves a copy of a unit or units. If the container value is 'TRUE'
+
== Notes ==
−
everything inside  including the container itself will be saved. If the container
+
* The file goes in the <code>units</code> folder of the zone's DIL file directory (the last column of the zone's line in <code>vme/etc/zonelist</code>), or of <code>dil_file_dir</code> in <code>server.cfg</code> when the zone has none. An existing file is replaced.
−
argument is 'FALSE' only the contents of the object will be saved. You will want
+
* Only zones with access level 10 or less (the fourth column of <code>zonelist</code>) may use it. In other zones the program stops and the zone log says "attempt to violate system access security (storeall)". The zone that counts is that of the program's template (the one copied onto the unit), not that of a function it called.
−
to use the 'TRUE' value when saving something like a Clan chest that has items
+
* A name with other characters (a <code>/</code>, a space) is refused with a line in the zone log; nothing is saved.
−
inside to store and has extras on the chest that you also wish to keep. The
+
* Only objects and NPCs are saved, never players, and not units with <code>UNIT_FL_NOSAVE</code>. Worn equipment is saved as worn.
−
'FALSE' value for container would be good for temporary storage of PC inventory
+
* A room can't be saved, its contents neither: with TRUE the zone log says "attempt to save a container that is either a room or pc", with FALSE nothing is written. A player's inventory can be saved with FALSE.
−
or for storing room contents.
+
* When there is nothing to save, no file is written, and an older file stays. Remove it with [[Manual:DIL Manual/delunit()|delunit()]].
 +
* The units are only copied: they stay in the game.
 +
* It writes to disk: don't call it often.
  
−
 
+
== Example ==
−
The 'store' and 'restore' are perfect for operations such as
+
<pre>
−
mud mailing objects from player to player, storage devices for players that will
+
dilbegin send_parcel(bag : unitptr, toname : string);
−
keep inventory through a reboot.  Even the ability to save a players inventory
+
code
−
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
+
  if (bag.type != UNIT_ST_OBJ)
−
used on a room to store the contents of a room any NPC or objects in the room
+
      return;
−
would be saved through reboot.
+
  store(bag, tolower(toname) + ".parcel", TRUE);  // the bag and what is in it
−
 
+
  destroy(bag);
−
 
+
  return;
−
'''Disk access is always slow'''.
+
}
−
If you use store on a continues basis, it is essential that you do so ONLY if it
 
−
is needed and even then, only at amply spaced intervals.  Otherwise you might
 
−
cause serious delays on the server.  Remember that items saved in player's
 
−
inventories are automatically saved in their instance.
 
−
'''Example 1:'''
 
−
<i><!--CODE-->
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
dilbegin save_contents ();
 
−
code
 
 
dilend
 
dilend
 +
</pre>
 +
Puts a bag and what is in it in storage for another player, who fetches it with <code>restore()</code> (see [[Manual:DIL Manual/delunit()|delunit()]]).
  
−
---~---~---~---~---~---~---~---~---
+
== See also ==
−
 
+
* [[Manual:DIL Manual/restore()|restore()]]
−
</i><!--ENDCODE-->
+
* [[Manual:DIL Manual/delunit()|delunit()]]
−
'''Example 2:'''
+
* [[Manual:DIL Manual/savestr()|savestr()]]
−
<i><!--CODE-->
 
−
 
 
−
 
 
−
dilbegin save_container_n_contents ();
 
−
code
 
−
dilend
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
</i><!--ENDCODE-->
 
−
'''See Also'''
 
−
[[#bfrestore|Store a Unit to a Unit file]] and
 
−
[[#bfdelunit|Delete a Unit file]].
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
<span id="bpstore"></span>
 
−
 
 
−
'''Function:'''  <i><!--CODE-->store( u : unitptr , filename : string , container : integer );</i><!--ENDCODE-->
 
−
 
 
−
<!--TERM-->  '''u'''
 
−
<!--DEFINITION-->        The Unit that has the contents to be stored or is to be stored
 
−
<!--TERM-->  '''filename'''
 
−
<!--DEFINITION-->        The name of the file you want to store the Units to
 
−
<!--TERM-->  '''container'''
 
−
<!--DEFINITION-->        Do you want to save the container 'TRUE' for yes, 'False' for no
 
−
 
 
−
 
 
−
Store saves a copy of a unit or units.  If the container value is 'TRUE'
 
−
everything inside  including the container itself will be saved. If the container
 
−
argument is 'FALSE' only the contents of the object will be saved.  You will want
 
−
to use the 'TRUE' value when saving something like a Clan chest that has items
 
−
inside to store and has extras on the chest that you also wish to keep.  The
 
−
'FALSE' value for container would be good for temporary storage of PC inventory
 
−
or for storing room contents.
 
−
 
 
−
 
 
−
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 store on a continues basis, it is essential that you do so ONLY if it
 
−
is needed and even then, only at amply spaced intervals.  Otherwise you might
 
−
cause serious delays on the server.  Remember that items saved in player's
 
−
inventories are automatically saved in their instance.
 
−
'''Example 1:'''
 
−
<i><!--CODE-->
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
dilbegin save_contents ();
 
−
code
 
−
dilend
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
</i><!--ENDCODE-->
 
−
'''Example 2:'''
 
−
<i><!--CODE-->
 
−
 
 
−
 
 
−
dilbegin save_container_n_contents ();
 
−
code
 
−
dilend
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 
−
 
 
−
</i><!--ENDCODE-->
 
−
'''See Also'''
 
−
[[#bfrestore|Store a Unit to a Unit file]] and
 
−
[[#bfdelunit|Delete a Unit file]].
 
−
 
 
−
---~---~---~---~---~---~---~---~---
 

Revision as of 23:21, 14 November 2026

store()

Procedure. Saves a unit, or what is inside it, to a file.

store(u : unitptr, filename : string, container : integer)

Writes the objects and NPCs inside u, with everything inside them, to a file. When container is TRUE, u itself is saved too, with its contents. restore() loads the file back, so things can be kept through a reboot: a clan chest, a parcel for a player, an arena fighter's belongings.

Parameters

Name Type Meaning
u unitptr The unit to save.
filename string The file's name: letters, digits, _ and . only, at most 512 characters.
container integer TRUE: save u and its contents. FALSE: only the contents.

Notes

  • The file goes in the units folder of the zone's DIL file directory (the last column of the zone's line in vme/etc/zonelist), or of dil_file_dir in server.cfg when the zone has none. An existing file is replaced.
  • Only zones with access level 10 or less (the fourth column of zonelist) may use it. In other zones the program stops and the zone log says "attempt to violate system access security (storeall)". The zone that counts is that of the program's template (the one copied onto the unit), not that of a function it called.
  • A name with other characters (a /, a space) is refused with a line in the zone log; nothing is saved.
  • Only objects and NPCs are saved, never players, and not units with UNIT_FL_NOSAVE. Worn equipment is saved as worn.
  • A room can't be saved, its contents neither: with TRUE the zone log says "attempt to save a container that is either a room or pc", with FALSE nothing is written. A player's inventory can be saved with FALSE.
  • When there is nothing to save, no file is written, and an older file stays. Remove it with delunit().
  • The units are only copied: they stay in the game.
  • It writes to disk: don't call it often.

Example

dilbegin send_parcel(bag : unitptr, toname : string);
code
{
   if (bag.type != UNIT_ST_OBJ)
      return;
   store(bag, tolower(toname) + ".parcel", TRUE);   // the bag and what is in it
   destroy(bag);
   return;
}
dilend

Puts a bag and what is in it in storage for another player, who fetches it with restore() (see delunit()).

See also