The connection command is used to access information about links in generic network objects (see
network
command). In many respects the behavior of connection objects in networks is comparable to that of bonds in ensembles, and the commands for handling connections are similarly structured. For example, just like bonds can be identified by a list of the participating atoms, connections can be selected by a list of the participating vertices.
Pseudo connection labels first , last and random are special values, which select the first connection in the connection list, the last, or a random connection.
The command edge is an alias for connection , allowing the use of a more standard nomenclature, but without the benefit of a matching prefix on the names of connection properties.
The following connection commands are supported:
connection append nhandle label property value ?property value?..
Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.
connection append $nhandle $c C_IDENT “_v2”
connection connection nhandle label
Return the connection label stored in property C_LABEL . This is useful in case the label is not the straightforward connection label, but some other specification type, such as a vertex pair.
connection connection $nh [list $v1 $v2]
connection create nhandle vertex_list ?uniqueness? ?property value?...
Create a new connection which links the vertices specified in the vertex list argument. In contrast to the handling of bonds in ensembles, there can be multiple connections with the same set of vertices in a network, and self-links (linked the same vertex as source and destination) are allowed. In some contexts the order of the vertices registered in a connection matters, i.e. the connections are interpreted as directional.
By setting the uniqueness flag, the presence of a connection duplicate is detected and in that case the old label of the existing connection is returned, instead of creating a new connection. The possible values of the uniqueness parameter are no (or 0, the default), undirected (or 1, the vertices are matched regardless of the order in the specified list) and directed (or 2, the vertices are matched in the same order as in the argument list).
The magic vertex label value
new
can be used in the vertex list to automatically create one or more new vertices with this command instead of referring to existing vertices. The new vertices are added to the vertex list and have the same properties as vertices created explicitly with a
vertex create
command.
An initial set of property values for the new or re-used connection can be set by the optional property/value arguments.
connection defined enandle label property
This command checks whether a property is defined for the connection. This is explained in more detail in the section about property validity checking. Note that this is not a check for the presence of property data! The
network valid
command is used for this purpose
connection delete nhandle ?label?...
connection delete nhandle all
Delete specific or all connection from the network. The vertices participating in the deleted connection remain in the network.
connection dget nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the connection get command. The difference between
connection get
and
connection dget
is that the latter does not attempt computation of property data, but rather initializes the property values to the default and return that default if the data is not yet available. For data already present,
connection get
and
connection dget
are equivalent.
conenction exists nhandle label ?filterlist?
Check whether this connection exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns 0 if the connection does not exist, or fails the filter, and 1 in case of successful testing.
connection exists $nhandle 99
connection exists $nhandle [list 1 2]
The second example checks whether a connection between vertices 1 and 2 exists. Instead of using a single label, all connection labels may be substituted by a list of the labels of their vertices.
connection filter nhandle label filterlist
Check whether a connection passes a filter list. The return value is 1 for success and 0 for failure.
connection get nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
connection get $nhandle [list $v1 $v2] C_ONTOLOGY_LINK
yields the ontology link type data of connection 1 as a list. If the information is not yet available, an attempt is made to compute it. If the computation fails, an error results.
For the use of the optional property parameter list argument, refer to the documentation of the ens get command.
Variants of the
connection get
command are
connection new, connection dget, connection nget, connection show, connection sqldget, connection sqlget, connection sqlnew
and
connection sqlshow
.
connection index nhandle label
Get the index of the connection. The index is the position in the connection list of the network. The first position is index 0.
connection index $nhandle 99
connection new nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The difference between
connection get
and
connection new
is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.
connection nget nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The difference between
connection get
and
connection nget
is that the latter always returns numeric data, even if symbolic names for the values are available.
connection set nhandle label property value ?property value?..
Standard data manipulation command. It is explained in more detail in the section about setting property data.
connection set $nhandle 1 C_IDENT “bla”
connection show nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The difference between
connection get
and
connection show
is that the latter does not attempt computation of property data, but raises an error if the data is not present and valid. For data already present,
connection get
and
connection show
are equivalent.
connection sqldget nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The differences between
connection get
and
connection sqldget
are that the latter does not attempt computation of property data, but initializes the property value to the default and return that default, if the data is not present and valid; and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
script processing.
connection sqlget nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The difference between
connection get
and
connection sqlget
is that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
script processing.
connection sqlnew nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The differences between
connection get
and
connection sqlnew
are that the latter forces re-computation of the property data, and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
script processing.
connection sqlshow nhandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
For examples, see the
connection get
command. The differences between
connection get
and
connection sqlshow
are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
script processing.
connection subcommands
Lists all subcommands of the connection command. Note that this command does not require a network handle, or a connection label.
connection vertices nhandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of the vertices which are participating in the connection. This is explained in more detail in the section about object cross-references.
connection vertices $nhandle 1