Chapter 17

Server and System Control

All creatures pass into My nature at the end of a cycle and are reborn at the beginning of creation.
--Bhagavat Gita

The aspects of the language covered so far have mostly been operations which take place in the isolated realm of the world. This chapter covers the additional commands which make it possible to interact with the rest of the computer, including access to files, programs, and other BYOND worlds.

1. A Note on Platform Independence

The operating system running on a computer is called the platform by programmers. At the present moment, BYOND can be used in both the Microsoft Windows and UNIX operating systems. Additional versions are in progress for other systems.

Whenever possible, it is better to write programs that are platform independent, which means they will work the same in any operating system. The DM language practically guarantees this by providing a syntax which relies as little as possible on the peculiarities of the external computational environment. In fact, the BYOND system behaves in many ways like a virtual operating system, insulating your code from the real operating system, and thus providing the same environment regardless of the machine it is running on.

However, in order to provide access to files and other programs on the computer, some platform dependencies are necessary. For example, the file names in UNIX are case-sensitive whereas in Windows they are not. That means when specifying a file name in a Windows environment you could get away with any combination of upper and lower case, whereas if you run the same code in UNIX it will only work if the case matches the name of the file exactly. It is therefore good practice to at least be consistent and use the same case throughout your code when referring to the same file.

File paths are relative to the current directory (unless an absolute path is given). The current directory is always the same directory as the world dmb file. On a UNIX platform, the / character is used in paths after each sub-directory. Normally, in Windows one would use the \ character for this purpose; however, DM allows you to use the / character instead. This is more convenient because it is not treated as a special character inside a text string.

2. shell

The shell instruction passes a command to the operating system. The command interpreter is often called a shell--hence the name for this instruction. This is a sleeping call which only returns after the operation has finished.

shell (Cmd)
Cmd is the command text.
Returns the exit status of the command.

The syntax of the command is obviously entirely operating system dependent. It normally consists of a program name followed by a number of arguments. If the command generates output or expects input, you will need to redirect the input and output to files, which in UNIX and Windows is done with the < and > operators.

The following example runs the "dir" command and displays the result. 

mob/verb/list_files()
   shell("dir > dir.txt")
   usr << browse("dir.txt")

3. File Operations

4. file2text

The file2text instruction reads a file into a text string. This could be used for a variety of purposes, including access to output generated by a shell() command.

file2text (File)
File is the name of the file.
Returns contents as a text string.

5. text2file

The text2file instruction is the complement of file2text. It appends a text string to a file. If the file does not exist, it will be created.

text2file (Txt,File)
Txt is the text string.
File is the file to append to.

6. file

The file instruction returns a reference to a file object. The primary use for such an object is with the input/output operators. Outputting a file to a player was discussed in section 11.2.7. It is also possible to send output to a file or get input from a file.

file (Path)
Path is the name of the file.
Returns a reference to the file.

Using a file as the target for output of the << operator has the same effect as calling text2file(). The output value is appended to the file. Similarly, reading input from a file with the >> operator is the same as file2text(). The file is loaded into a text string and stored in the specified variable.

File << Output
File >> Variable

7. fcopy

The fcopy instruction copies one file to another. The source file may be a real external file or a file in the cache. If the destination file already exists, it will be replaced.

fcopy (Source,Dest)
Source is the source file.
Dest is the destination file.
Returns 1 on success and 0 on failure.

8. fdel

The fdel instruction deletes a file from the file system.

fdel (File)
File is the name of the file.
Returns 1 on success and 0 on failure.

It works with entire directories too (so be careful for heaven's sake). As a precaution, it only accepts directory names when you end them with a slash "/".

9. flist

The flist instruction generates a list of files at the specified path in the file system and whose names begin in the specified way.

flist (Path)
Path is the path to get the listing of.
Returns a list of files and sub-directories.

Only files and sub-directories directly contained in the specified path are listed (i.e. not the contents of the sub-directories too). The file names in the list do not contain the path information but just the bare file name. Sub-directories in the list are identified by a trailing "/" appended to the name.

The format of the path is "dir1/dir2/.../file". Only files matching "file" are listed, so be sure to append a "/" to the end of a directory name if you wish to see its contents. Otherwise, all you will get is the directory name back with a "/" appended.

10. Running other Worlds

It is sometimes desirable for one master world to launch child worlds. For example, you might have a main world with side-adventures (dungeons etc.) taking place in separate sub-worlds. This might be more efficient since areas that are rarely used could be activated only when needed.

The ultimate use of this technique is a world hosting service which allows users to upload their own world files. These are then launched and shut down as they are accessed by players. If you do not have your own dedicated network connection, you may wish to make use of such a service to host your worlds.

10.1 startup

The startup instruction runs another world. It sleeps until the network address of the new world has been determined.

startup (File,Port=0,Options,...)
File is the dmb file to run.
Port is the network port to use.
Options includes any additional parameters.
Returns network address of the new world.

The network address of a world includes two parts. The first is the IP address of the machine it is running on. The second is the port number. These are combined in a text string of the form "ip:port". The port specified must not be in use by any other programs. The default value of zero indicates that any available port should be used.

The additional options that may be specified are described in the following list.

  • -once This option automatically shuts down the server when all players have logged off.

  • -log This option takes an additional argument which is used as the server's output file. All debugging notices (from proc crashes) and any output sent to world.log is appended to this file. The path to the file is relative to the new server's working directory, which is the location of the .dmb file.

  • -safe This option runs the world in a special protective security mode. The world code may only access files in the same directory (or below) as the .dmb file and access to the shell instruction is disabled. This is the default mode if the world is run from its own safe directory. Such a directory is recognized when it has the same name as the world .dmb file (e.g. inferno/inferno.dmb).

  • -ultrasafe This is the same as -safe except only access to temporary files is allowed. This is the default if the world is not run from its own safe directory.

  • -trusted In this mode, all operations are permitted. The world may access files in any directory and may run shell commands. Of course the operating system may apply restrictions, but BYOND will allow the world to try anything.

  • -params The following argument is interpreted as a parameter string as described in section 10.9. The variable world.params is initialized from this data. You may use -params multiple times; the individual parameter strings are simply concatenated to form the final result.

  • -quiet This simply disables informational output that the server normally displays when it boots up.

    10.2 Control over Child Worlds

    Communication with a child world may be done through world.Export(). In this case, the child world's world.Topic() procedure is called with a special master flag to indicate that the message came from the world which started it. (See section 8.2.4 for a review of these procs.)

    By default, a child world will respond to the special topics "Del" and "Reboot" by calling world.Del() and world.Reboot() respectively. This is only done if the message comes from the master world, since otherwise anyone could send the message and shut your world down.

    Another useful topic is "ping", which can be used to determine if a child world is still alive and running.

    10.3 shutdown

    The shutdown instruction may be used to close a child world or to wait for it to exit normally.

    shutdown (Address,Natural=0)
    Address is the network address of the world.
    Natural is 1 to suppress sending of "Del" message.
    Returns exit status of the child world.

    The address should be the same text string returned by startup(). If the second argument is omitted or zero, this is equivalent to calling world.Export() with the given address and "Del" as the topic. Otherwise, this instruction simply waits for the child world to die naturally of its own accord.

    With no arguments at all, this instruction causes the current world to shut down. The same thing can be achieved by calling world.Del().