general.entity Definition/General

general.entity

Command general.entity Definition/General
Applicable release versions: AP 6.1
Category General (155)
Description represents a system element, like a Pick process, a serial port, a device, with which data can be exchanged.
This section introduces the fundamental notions necessary to understand the principles of data flow within the Pick 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, and some are constant, like the Pick process entity ids. At the user level, entity IDs are encoded as a one letter code followed by a null or positive number:
P Pick process or PIB.
S Serial device.
T Telnet terminal emulation.
E TCP/IP connection.
U UDP/IP connection.
Q Message queue.

P11 for Pick process 11, S24 for the serial device 24, E1657 for the TCP/IP connection '1657', are examples of entity IDs. If specifying a Pick process, the 'P' can be omitted. For example, '11' is also the entity ID of Pick 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 Pick port, or PIB, is an entity in the system: its input can be a TCL command or data to an Pick/BASIC INPUT statement, and its output can be the result of a TCl command or from a Pick/BASIC PRINT statement. The Pick 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 which 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 (see below).

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 which initiated the tandem connection, thus displaying the Pick process output to both terminals.

Output Link
The output link is the way by 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 Pick process, for example, the process would be suspended. In the case of a serial device, an XOFF 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 which regulate the data flow among them, that is treated as a whole. For example, in tandem, the Pick process and the two terminals interacting with it constitute an association.

Special Entities
The system creates automatically the following special entities:

BB Byte Bucket. All data sent or forwarded to this entity is discarded. For example, the output link of a Pick 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. By default, data sent or forwarded to this entity is logged into a Unix file (on Unix implementation), or discarded (other implementations). 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 sent 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 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, then 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 Pick/BASIC GET and SEND statements.
Notes: Once an entity has been attached, it is permitted to create any link from or to this entity.
Data sent to or read from an entity through the attachment mechanism, is not passed through the input/output translation mechanism (see "set-imap" and "set-iomap"), and data sent to it cannot be forwarded to another entity.

Entity Classes
The system distinguishes the following classes of entities:
Cloning: A cloning entity is an entity which '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, which has the ID 'E0'. When a Pick process, for example, needs to get a TCP/IP connection, it attaches to E0, which clones itself, allocates a free entity ID, for example E1657. Communications then takes place with this clone. When the Pick process detaches from the clone, the clone is destroyed.

Cloned: A cloned entity is the result of the duplication of a cloning entity. Its lifespan is usually limited and it is destroyed when it is detached.

Special: A special entity is either the NULL entity, the Byte Bucket or the Console.

Normal: A 'normal' entity is defined as not being any of the previous classes. PIB, Serial Ports are example of 'normal' entities.
Syntax
Options
Example
Purpose
Related filename.devs
tcl.:ent-link
tcl.dev-make
tcl.dev-remov
tcl.:ent-mon
tcl.list-tandems
tcl.:ent-list
tcl.:ent-status