connection Command

[add|print|check|modify|
delete|disconnect|
freeze|thaw|
query|log] connection NAME [CLAUSE];

• NAME is the connection or the instance of the relationship type you are adding.
• CLAUSE provides additional information about the connection.

The syntax and clauses for working with connections and business objects is similar. For more information, see Connect Business Object.

Syntax

add connection RELTYPE [ADD_ITEM {ADD_ITEM}] [preserve];

• RELTYPE is the connection or the instance of the relationship type you are adding.
• preserve, if used, indicates that the connection should not update the modification date for the business object.
• ADD_ITEM is an Add Connection clause which provides more information about the connection you are creating.

  The Add Connection clauses are:

  to BO_NAME

  from BO_NAME

  torel CONNECTION

  fromrel CONNECTION

  ATTRIBUTE_NAME_VALUE

  interface INTERFACE_NAME

  access ACCESS_ID [as MASK]

  ownership OWNERSHIP_ID [as MASK]

  relationshiprule NAME

  owner USER_NAME

  organization ORGANIZATION_NAME altowner1 USER_NAME is still supported for backwards compatibility.

  project PROJECT_NAME altowner2 USER_NAME is still supported for backwards compatibility.

  physicalid UUID

  logicalid UUID

To and From Clauses

The To and From (and Torel and Fromrel) clauses of the Add Connection command define the ends of the connection. Use the To and From clauses with a business object ID. Use the Torel and Fromrel clauses with a connection ID.

All connections will occur between either two business objects, two connections, or a business object and a connection. When looking at a connection, the objects are connected TO and FROM one another. You must define the connection with one To clause and one From clause in your Add Connection command. If either clause is missing or incomplete, the connection will not be created.

Both the To and From clauses use the same set of subclauses because they define the same information about each connected object. The separate values you use to define each connection end will vary according to the type of connection you are making and the types of objects involved.

The rules governing the creation of business objects and connections (for example, definitions of type, relationship type, policy, and so on) are only enforced at the time creation. These rules will be ignored during later modifications of those business objects and connections.

For example, changing the type of business object on one end of a connection will ignore the type restrictions defined on the relationship. This behavior is allowed to support a dynamic modeling environment.

check connection cestamp ID CESTAMP {ID CESTAMP}; 

CEStamp (Concurrent Engineering Stamp) implements optimistic offline lock, a method to prevent conflict between concurrent transactions by detecting a conflict and rolling back the transaction. When you have the cesstamp value, you can pass it to a program to validate a modification.

delete connection CONNECTION [preserve];

• CONNECTION is the ID of the relationship to be deleted or defines the buisness object connection in this format:

  businessobject BO_NAME |from| BO_NAME relationship NAME
                         | to |

• preserve, if used, indicates that the deletion should not update the modification date for the business object.

disconnect connection CONNECTION [preserve];

• CONNECTION is the nave of the
• preserve, if used, indicates that the disconnection should not update the modification date for the business object.

Syntax

For example:

print connection OBJECTID;

The results of the above could be something like:

Relationship Drawing
   From bus obj 50402
   To bus obj 50402
   relationship[Drawing].isfrozen = FALSE
   relationship[Drawing].propagatemodifyfrom = FALSE
   relationship[Drawing].propagatemodifyto = FALSE
   history
   create - user: adami time: Thu May 22, 1997 6:29:20 PM
     from: Drawing 50402 A to: Assembly 50402 B

If the connection’s ID is unknown, the following can also be used:

print connection bus OBJECTID to|from OBJECTID relationship RELTYPE;

• OBJECTID is the OID of the connection. It can also include the in VAULTNAME clause, to narrow down the search.

The result of print connection with object ends specified will be ambiguous when multiple relationships between the two objects exist.

Select Commands

Select commands enable you to view a listing of the field names that make up the connection definition. Each field name is associated with a printable value. By selecting and listing the field names that you want, you can create a subset of the connection’s contents and print only that subset. The system attempts to produce output for each Select clause input, even if the object does not have a value for it. If this is the case, an empty field is output.

Select can be used as a clause of the print connection and in query where clauses (for more information, see Select Clauses in Queries.

Reviewing the List of Field Names

The first step is to examine the general list of field names. This is done with the command:

print connection selectable;

The Selectable clause is similar to using the ellipsis button in the graphical applications—it provides a list from which to choose.

When the command above is processed, MQL lists all selectable fields with their associated values:

print connection selectable;
connection selectable fields :
    name
    type.*
    attribute[].*
    businessobject.*
    to.*
    toall
    tomid.*
    torel.*
    from.*
    fromall.*
    frommid.*
    fromrel.*
    history.*
    isfrozen
    propagatemodifyto
    propagatemodifyfrom
    id
    method.*
    program.*
    execute.*
    rule[].*
    originated
    modified
    context.*
    index.*
    interface.*
    expression[]
    evaluate[]
    reserved
    reservedby.*
    reservedcomment
    reservedstart
    owner.*
    organization.* or altowner1.* (see below)
    project.* or altowner2.* (see below)
    updatestamp
    cestamp

MQL connection commands still support the altowner1 and altowner2 keywords when specified explicitly. For example:

print connection select altowner1 altowner2;

is supported and the result prints altowner1 = XXX / altowner2 = YYY. Where those keywords cannot be specified explicitly, they are not shown but organization and project , respectively, are shown instead. For example:

print connection selectable;

shows organization = XXX and project = YYY.

Some of the fields are followed by square brackets and/or a " .* ". The asterisk denotes that the field can be further expanded, separating the subfields with a period. If only one value is associated, the name appears without an asterisk. For example, the Name field has only a single value that can be printed. On the other hand, a field such as type has other items that can be selected. If you expand the Type field, you might find fields such as type.name, type.description, and type.policy. This means that from any connection, you could select a description of its type and find out other valid policies for it. For more information, see Print Business Object.

Syntax

modify connection CONNECTION [MOD_ITEM {MOD_ITEM}];

• CONNECTION is the name or ID of the connection you want to modify.
• MOD_ITEM is the type of modification you want to make. Each is specified in a Modify Relationship clause, as listed in the following table. You only need to specify fields to be modified:

  Modify Relationship Clause	Specifies
  to BO_NAME	A modification is made to the business object on the TO end. For more information, see Changing Connection Ends.
  from BO_NAME	A modification is made to the business object on the FROM end. For more information, see Changing Connection Ends.
  torel CONNECTION /	A modification is made to the connection on the TO end. For more information, see Changing Connection Ends.
  fromrel CONNECTION	A modification is made to the connection on the FROM end. For more information, see Changing Connection Ends.
  ATTRIBUTE_NAME VALUE	The specified attribute is changed to that of the new attribute. Attributes of connections can be modified if the user has modify access on the objects or connections on both ends of the connection.
  add interface INTERFACE_NAME	This interface listed here is added to the connection. When you add an interface to a connection, it obtains all of the attributes defined for the interface, even those that were not defined for the connection. This allows for ad hoc attributes for connections. Moreover, when you add an interface to a connection, it gives you the ability to classify the connection by virtue of the interface hierarchy. To add or remove interfaces from connections, you must have ChangeType access on the object on the FROM end of the connection. If the FROM end is not a business object and it is a connection, the system looks for ChangeType access on the TO end of the connection. If neither end of the connection is a business object, any relationship rule defined is checked. History is recorded when you add or remove interfaces from connections. You can only add an interface to a connection of a relationship type that is added to the interface definition. For information on how to add a relationship to an interface, see MQL Concepts: Interfaces.
  remove interface INTERFACE_NAME	This interface listed here is removed from the connection.
  add access ACCESS_ID [as MASK]	Adds the business object or relationship identified by the ACCESS_ID to the connection, optionally as a mask.
  remove access ACCESS_ID	Removes the specified access from the connection.
  add ownership OWNERSHIP_ID [as MASK]	Adds the organization and project, business object, or relationship identified by the ACCESS_ID to the connection, optionally as a mask.
  remove ownership OWNERSHIP_ID	Removes the specified ownership from the connection.
  add history VALUE [comment VALUE]	A history Tag and a Comment can be specified with this clause. The Tag is the VALUE you enter after add history as a name for the custom history entry. A user/time/date/current stamp is automatically applied when this command executes. The comment is the VALUE (or text) you enter to describe the history item you are adding.
  delete history DEL_HISTORY_ITEM	System administrators only can purge the history records of a business object. For more information, see Delete History.
  reserve [user USER] [comment VALUE]	To attach reservation data to an object: username, date, optional comment. The user clause can be included only by system administrators to reserve a connection on behalf of someone else. The reserve access mask controls the changing of the reserve status of an object or connection. For more information, see Reserving a Business Object.
  unreserve	To attach reservation data to an object: username, date, optional comment. The user clause can be included only by system administrators to unreserve a connection on behalf of someone else. The unreserve access mask controls the changing of the reserve status of an object or connection. For more information, see Reserving a Business Object.
  !reserve	To attach reservation data to an object: username, date, optional comment. The user clause can be included only by system administrators to reserve a connection on behalf of someone else. T he reserve access mask controls the changing of the reserve status of an object or connection. For more information, see Reserving a Business Object.
  owner USER_NAME	The owner of the connection is changed to the owner specified here.
  organization ORGANIZATION_NAME (or altowner1 USER_NAME )	The additional owner of the connection is changed to the specified organization. You must have ChangeOwner privileges to set the owning organization.
  project PROJECT_NAME (or altowner2 USER_NAME )	The additional owner of the connection is changed to the specified project. You must have ChangeOwner privileges to set the owning project.
  updatestamp STAMP	The stamp value is a DCE UUID 16 byte ID used by applications to mark significant changes to the connection.
  refresh-autoinheritance	Recalculates all inheritancerules for the specified CONNECTION.
  originated VALUE	Changes the date that the connection was created.
  modified DATE	Sets the date of the modification.

Any combination of IDs and full specification by type name and revision (or relationship name) are allowed. When using type, name and revision you can also include in VAULTNAME.

Reserving a Connection

To mark a business object or connection as reserved:

When a reservation is made, the following information is sent for storage in the database:

• Person reserving the object.
• Time when the object is reserved.
• Comments entered when the reservation is made.

The comment string is optional and has a 254 character limit. Comments longer than 254 characters are truncated and only the first 254 characters are stored in the database.

You can use reservation data to control concurrent modification in two ways:

• Code controlling the display of an editing page can check the reserved status beforehand, and reject the editing request if the object is reserved.
• Define access rules to control any access. For more information, see policy Command Syntax.

The privilege to reserve or unreserve an object can be specific in access rules using the reserve and unreserved access mask. Unreserving a business object or connection by providing the wrong OID or Type Name Revision will result in an error message. Unreserving a business object or connection that is not reserved will result in a warning.

Obtaining Connection IDs

To obtain the IDs of all connections, use the relationship ID selectable item.

For example:

The following is a possible result that can be saved to a file for an Output clause:

1 Drawing from Drawing 50402 A
   id = 19.24.5.16
1 Process Plan from Process Plan 50402-1 C 
   id = 19.26.6.6

For more information, see Expand Business Object.

Changing Connection Ends

It is possible to specify a new object to replace the existing object on the end of a connection. This is comparable to using the drop connect feature, and dropping an object on top of a relationship arrow (to replace the child object) in the Navigator window.

The operation actually performs a disconnect and then a connect action, and so relies on those accesses to determine if the user can perform the action. The user must also have modify access on the connection. Use the keywords to and from or torel and fromrel on the modify connection commands. For example:

• BO_NAME is the ID or Type Name Revision of the business object.

To change the direction of the relationship, use both a ‘to’ and a ‘from’ BO_NAME clause. For example, assume that Assembly 50402 B is currently on the FROM end of the relationship. The following command would reverse the direction:

modify connection 62104.18481.14681.40078 to Assembly 50402 B
 from 62104.18481.13184.46733;

Adding or Removing Connection Ownerships

Connections can have multiple owners. To add an ownership to or remove an ownership from a connection:

modify connection ID add|remove ownership [ORGANIZATION] 
[PROJECT] [for COMMENT] [as ACCESS];

• ID is the identifier for the specific connection.
• ORGANIZATION is a role object that represents an organization.
• PROJECT is a role object that represents a project.
• COMMENT is a short string that is primarily used for annotation.
• ACCESS is a comma-separated list of security tokens.

The ORGANIZATION, PROJECT, and COMMENT together provide a unique identifier for the ownership entry. Tokens following "for" constitute the ownership comment; those following "as" constitute the access mask.

The following are some examples of usage:

modify connection ID add ownership "MyCompany" "MyProject" for "ownership”;
modify connection ID add ownership "Supplier1" "MyProject" for "Project Applicability";
modify connection ID add ownership "Supplier2" "MyProject" as show,read,checkout;
modify connection ID remove ownership "Supplier1" "MyProject" for "Project Applicability";

Syntax

freeze connection CONNECTION;

• CONNECTION is the ID of the relationship to be frozen or defines the buisness object connection in this format:

  businessobject BO_NAME |from| BO_NAME relationship NAME
                         | to |

When objects are cloned or revised, their existing relationships are either floated, replicated, or removed. When a frozen connection is floated, the new connection is frozen as well. Replicated connections take on the thawed state.

thaw connection ID;

Users must have thaw access on the objects on both the to and FROM end of the connection.

query connection [QUERY_ITEM {QUERY_ITEM}] [SELECT] [DUMP] [RECORDSEP] [tcl] [output FILENAME];

• QUERY_ITEM is a Query Connection clause.

  to BO_NAME

  from BO_NAME

  torelationship CONNECTION_ID

  fromrelationship CONNECTION_ID

  where EXPR

  type PATTERN

  relationship PATTERN

  vault PATTERN

  limit N

  includeAdaplet

  size N

  orderby FIELD_NAME

• BO_NAME is the name of the business object that make up the toend or the fromend.
• CONNECTION_ID id the id of the connections that make up the toend or the fromend.
• EXPR is the string containing the value of the where clause.
• PATTERN for is a name pattern for the relationship or vault.
• FIELD_NAME is the selectable you specify for sorting when using the orderby clause. You can prefix the FIELD_NAME with a “+” to sort in ascending order or “-” to sort in descending order. If no prefix is specified, the results are sorted in ascending order. You can use a maximum of three orderby clauses in a query connection command.

For example:

query connection to Part T22 0 where ATTR_NAME==”Material Used” 
orderby +name orderby type; 

The includeAdaplet flag is used to include Adaplet vaults in query searches if mxEnv.sh is configured to exclude those vaults.

To exclude Adaplet vaults from query searches, set the value of this parameter in mxEnv.sh to TRUE: MX_IGNORE_ADAPLET_VAULTS_DURING_QUERY

If you then want to include Adaplet vaults in a search, add the includeAdaplet flag to the query connection command. For example:

query connection where name==manager includeAdaplet select from to dump;

For information about other query connection clauses, see Expand Business Object.

Query connection commands cannot be saved for later evaluation as can be done with the add query command.

The syntax is:

log connection CONNECTION CONNECTION_EVENT [EVENTMONITOR [EVENTMONITOR] ]; 

• CONNECTION is the ID of the relationship to be deleted or defines the buisness object connection in this format:

  businessobject BO_NAME |from| BO_NAME relationship NAME
                         | to |

• CONNECTION_EVENT is event relationship custom
• EVENTMONITOR identifies the event monitor: eventmonitor NAME