# Entity An entity is a system element, such as a D3 process, a serial port, or a device, with which data can be exchanged. Note: The notion of entity is introduced in an attempt to generalize I/O between processes and devices. This topic introduces the fundamental notions necessary to understand the principles of data flow within the D3 environment. ## Entity ID Each entity in the system is allocated a unique 32-bit entity ID. Some entity IDs are created by the system, and therefore may vary in time (for example a TCP/IP connection gets a new entity ID every time a connection is created). Other entity IDs are constant, such as the D3 process entity IDs. At the user level, entity IDs are encoded as a one-letter code followed by a null or positive number: | P | D3 process or PIB. | | --- | --- | | S | Serial device. | | T | Telnet terminal emulation. | | E | TCP/IP connection. | | U | UDP/IP connection. | | Q | Message queue. | P11 for D3 process 11, S24 for the serial device 24, E1657 for the TCP/IP connection 1657, are examples of entity IDs. If specifying a D3 process, the P can be omitted. For example, 11 is also the entity ID of D3 process 11. ## Standard Input/Standard Output Data can be sent to an entity by any other entity in the system. An entity can send its output *only* to one other entity. For example, a D3 port, or PIB, is an entity in the system. Its input can be a TCL command or data to an FlashBASIC input statement, or its output can be the result of a TCL command or from a FlashBASIC print statement. The D3 process can receive data from two different terminals, as in tandem, but can send its output only to one terminal. A serial port is also an entity, though the notion of input and output might be less intuitive; its input is the data that must be transmitted to the serial device and its output is the data it receives from the device. Data can also be exchanged through the attachment of another entity. ## Forwarding An entity input data can optionally be forwarded to an another entity in the system. This mechanism can be viewed as a duplication of the incoming data. For example, in tandem, the input to the serial port associated to the terminal in tandem is forwarded to the terminal that initiated the tandem connection, thus displaying the D3 process output to both terminals. ## Output Link The output link is the manner in which an entity sends its output to another entity. There can be only one output link for each entity, but an entity can be the target, or destination, of any number of output links. If an entity does not have an output link, its data flow is stopped until an output link is created. In the case of a D3 process, for example, the process would be suspended. In the case of a serial device, an x-off would be sent to stop the incoming data flow once the internal buffers are full. ## Forwarding Link The forwarding link is the way by which an entity forwards (duplicates) its input to another entity. There can be only one forwarding link for each entity, but an entity can be the target or destination of any number of forwarding links. ## Association An association is a combination of entities, along with the various links that regulate the data flow among them, that is treated as a whole. For example, in tandem, the D3 process and the two terminals interacting with it constitute an association. ## Special Entities The system automatically creates the following special entities: | BB | Byte Bucket. All data sent or forwarded to this entity is discarded. For example, the output link of a D3 phantom process is the byte bucket. The entity ID of the byte bucket is -1. | | --- | --- | | CO | Console. This entity can be reassigned to any entity in the system. For UNIX: By default, data sent or forwarded to this entity is logged into a UNIX file. For Windows: By default, data sent or forwarded to this entity is discarded. The entity ID of the console is -2. | | NULL | Null entity. This special entity does not accept any data. In other words, if an entity attempts to send its output to this entity, it will be suspended. The entity ID of the NULL entity is 0. | ## Attachment An entity can attach to another entity to obtain exclusive usage of this entity. For an entity to be attached successfully, it must not be already attached, it must not have an output link, and no other entity can have a forwarding or output link to it. Note that an attached entity can have a forwarding link to another entity. Once an entity has attached another entity, it can send data to it and receive data from it independently from the normal data flow going through the links. In other words, If entity A has its output link to entity B, and attaches to entity C, it can send data through its standard output to B, and data to C using the attachment. At the application level, data can be exchanged with an attached entity through the FlashBASIC get and send commands. Note: Once an entity has been attached, you can create any link to or from this entity. Data sent to or read from an entity through the attachment mechanism is not passed through the input/output translation mechanism, and data sent to it cannot be forwarded to another entity. ## Entity Classes The system distinguishes the following classes of entities: | Cloning | Clones or duplicates itself when another entity attempts to establish a link or to attach to it. For example, inside a given virtual machine, there is only one TCP/IP entity with the ID E0. When a D3 process needs to establish a TCP/IP connection, it attaches to E0, which clones itself and allocates a free entity ID (for example, E1657). Communication then takes place with this clone. When the D3 process detaches from the clone, the clone is destroyed. | | --- | --- | | Cloned | Result of the duplication of a cloning entity. Its life span is usually limited and it is destroyed when it is detached. | | Special | Either the NULL entity, the Byte Bucket, or the Console. | | Normal | Defined as not being any of the previous classes. PIB, Serial Ports are example of normal entities. | ## See also - [dev-make command (UNIX)](https://d3codex.com/tcl/dev-make-command-unix/) - [dev-remov command](https://d3codex.com/tcl/dev-remov-command/) - [devs file](https://d3codex.com/systemfiles/devs-file/) - [list-tandems command](https://d3codex.com/tcl/list-tandems-command/) --- Source: https://d3codex.com/definitions/entity/ - part of the D3Codex reference.