vault Command

Syntax

add vault NAME [ADD_ITEM {ADD_ITEM}];

• ADD_ITEM provides more information about the vault you are creating. Although the clauses are not required to make the vault usable, they are used to define a vault location other than the current default host and path. In addition, the clauses can help users understand the purpose of the vault. The Add Vault clauses are:

  description VALUE

  icon FILENAME

  file MAPFILENAME

  [!|not]hidden

  indexspace SPACE

  tablespace SPACE

  pathvault

  pathvaulttablespace SPACE

  pathvaultindexspace SPACE

  interface LIBRARYFULLPATH

  external

  map STRING

  property NAME [to ADMINTYPE NAME] [value STRING]

  server SERVERNAME

  tablespace SPACE

File Clause

This clause defines the map or parameters filename for foreign or external vaults respectively.

The scott.map file is placed in the ENOVIA_INSTALL/api/mxff/ directory when the Studio Federation Toolkit is installed. The map file can be specified with the File clause. For example:

add vault scott
   interface d:\enoviaV6R2011\studio\api\mxff\mxff
   file d:\enoviaV6R2011\studio\api\mxff\scott.map;

Vault Types

There are three types of vaults: local, foreign and external. Most vaults are local. Foreign vaults are used with Adaplets™, which allow data from virtually any source to be modeled as objects. External vaults are used with external stores that contain data maintained by external servers.

When defining a vault in MQL, you don’t need to specify which type it is and there is no clause that allows you to specify the type. To define a vault type, include the clauses for that vault type:

• Local vaults, define the Oracle tablespace:
  • tablespace
  • indexspace
• Foreign vaults:
  • tablespace
  • interface
  • map
• External vaults:
  • file (parameters file)

Tablespace Clause

This clause is used to specify the data and index storage areas in which the data tables for an object vault are stored.

The names of the tablespaces and their associated storage are defined by the database administrator (DBA). This must be done prior to defining vaults. If you do not specify a tablespace name, the default data tablespace is used. Consult the database administrator about which tablespace you should use.

For SQL server, file groups are roughly the equivalent of the tablespaces used in other databases.

For more information, see the Installation Guide.

Indexspace Clause

This clause is used to specify the Oracle tablespace in which the index and constraint information for an object vault is stored.

The names of tablespaces and their associated storage are defined by the database administrator (DBA). This must be done prior to defining vaults. If you do not specify a tablespace name, the default index tablespace is used.

pathvault, pathvaulttablespace, and pathvaultindexspace Clauses

Use these clauses to define an optional path vault. The pathvault clause specifies that this vault contains path and pathtype data, not object data. Setting a pathvault for an object vault is irrevocable.

The pathvaulttablespace and pathvaultindexspace clauses are the same as the tablespace and indexspace clauses for the object vault, but are used for the path vault.

Use this syntax to define a path vault:

add vault NAME pathvault pathvaulttablespace SPACE pathvaultindexspace SPACE;

Path vaults are hidden; they do not show up when you use the list vault command. Path vaults do not contain any business object data.

Interface Clause

This clause is used to define the full path name of the library for a foreign vault. The Interface should be specified as ENOVIA_INSTALL/api/mxff/mxff, with no extension. The .dll or shared library file is then used to access the vault, depending on whether the client is a Windows or a UNIX client.

This field cannot be modified once the vault has been created. If changes are required, the vault must be deleted and then recreated. Deleting foreign vaults deletes only the database tables associated with it. The data from the foreign federation is left intact.

The interface can be used in more than one vault definition, but only by making a copy of it with a different name. For example, if the mxff interface is used to link a second database with 3DSpace (presumably with a different mapping), a copy of mxff should be created and renamed, and then referenced in the second foreign vault definition.

Use of the same interface (of the same name) by more than one vault will cause problems when accessing business objects. Each Foreign vault must use a uniquely named interface. The mxff library can be copied and renamed for different vaults.

Map Clause

This clause is used to specify a string which defines the schema map for a foreign vault.

The schema map indicates which metadata in the foreign data maps to what types of data in 3DSpace. It becomes part of the vault definition and is always referred to when accessing the data. The Map clause specifies the server, mode, and each table in the data source. For more information, see Adaplet Programming Guide: Mapping the Data.

Param Clause

This clause is used to specify a string of XML to define the parameters for an external vault. You can alternatively use the File clause to indicate a file that provides the XML parameters.

modify vault NAME [MOD_ITEM {MOD_ITEM}];

• NAME is the name of the vault you want to modify.
• MOD_ITEM is the type of modification you want to make. Each is specified in a Modify Vault clause, as listed in the following table. You only need to specify the fields to be modified.

  Modify Vault Clause	Specifies
  description VALUE	The current description, if any, changes to the value entered.
  icon FILENAME	The image is changed to the new image in the field specified.
  indexspace SPACE	The named indexspace is added to the vault.
  tablespace SPACE	The named tablespace is added to the vault.
  pathvault	Adds a pathvault to the object vault, resulting in a migration of path data from the object vault. Using the pathvault clause is irrevocable. Migrates all path data to the specified pathvault. This command should only be run when users are not using the system. Because it could take hours to run (time is proportional to the number of paths that need to be migrated) on a system with millions of paths, the execution of this command should be planned accordingly.
  pathvaulttablespace SPACE	Used with pathvaults only. The named pathvaulttablespace is added to the vault.
  pathvaultindexspace SPACE	Used with pathvaults only. The named pathvaultindexspace is added to the vault.
  name NAME	The current vault name changes to the new name entered.
  file MAPFILENAME	The name of the map file is changed.
  map STRING	The map schema information is replaced with the new string.
  hidden	The hidden option is changed to specify that the object is hidden.
  nothidden	The hidden option is changed to specify that the object is not hidden.
  property NAME [to ADMINTYPE NAME] [value STRING]	The named property is modified.
  add property NAME [to ADMINTYPE NAME] [value STRING]	The named property is added.
  remove property NAME [to ADMINTYPE NAME] [value STRING]	The named property is removed.

Each modification clause is related to the clauses and arguments that define the vault. When modifying a vault, you first name the vault to change and then list the changes to make. For example, the following command assigns new name and description to the vault called The Cleveland Project.

modify vault “The Cleveland Project”
   name "The San Diego Project"
   description "Includes data for San Diego area."
   file c:\enoviaV6R2011\studio\scott.map;

Syntax

The Clear Vault command is used to delete all business objects and associations in a vault:

clear vault NAME [minorrevision] [relationship] [full] [size NUMBER];

• NAME is the name of the vault you want to clear.
• NUMBER is the size of the transaction before a database commit. The Size clause only applies when any of the other optional clauses are included.

Once a vault has been established and used, you should NOT use the clear vault command. In addition, you should not use it when users are online. If the object vault has an associated path vault, clear vault clears both the object vault and the associated path vault.

Minorrevision Clause

Include this clause before actually clearing the vault to have first remove the business objects in the named vault from revision chains of objects in other vaults. This involves modifying rows in the vaults lxBO table (marking rows that need to be cleaned up). Upon successful execution of this command, all revision chains that need adjustment prior to the clear vault command are fixed.

Relation Clause

Include this clause before actually clearing the vault to first disconnect business objects in the named vault from objects in other vaults. This involves modifying rows in the vaults lxRO table (marking rows that need to be cleaned up). Upon successful execution of this command, all connections to objects in other vaults are removed.

Full Clause

Include this clause before actually clearing the vault to have first perform both a “clear vault relationship” and a “clear vault revision.” Additionally all tables of the vault are dropped and recreated, cleaning up the marked rows.

Size Clause

Include this clause of the clear vault command to indicate a transaction size before the relation or revision changes are committed to the database. For example, to remove all connections to or from objects in other vaults and commit the changes 100 at a time use the following:

clear vault MyVault relation size 100;

When used without the Revision, Relation or Full clauses, the Size clause is ignored.

copy vault SRC_NAME DST_NAME [MOD_ITEM {MOD_ITEM}];

• SRC_NAME is the name of the vault you want to copy from.
• DST_NAME is the name of the vault you want to copy to.
• MOD_ITEM are any of the clauses defined in Modify Vault.

Syntax

index vault NAME  [table TABLE_NAME [indexspace TABLESPACE_NAME]];

• NAME is the name of the vault to index. You can run the index vault command against any vault, including ADMINISTRATION.

Re-indexing vaults can improve find performance whether or not transaction boundaries have been used in the data loading process. If data is loaded from a sequentially sorted data file, the resulting index will be less than optimal. Re-indexing randomizes the index, making find performance noticeably better. Indexing a vault in this manner rebuilds the system indices that must be present for locating objects by name, type, and owner, as well as other SQL convertible fields.

When you index an object vault, it also indexes any associated path vault.

To show the SQL commands for a particular index vault command, without actually changing the indices, use the validate index vault command as follows:

validate index vault NAME [table TABLE_NAME [indexspace TABLESPACE_NAME]];

This is helpful to use on very large databases, where indexing a vault could take many hours. The validate output shows the SQL commands that need to be run. You could then manually run the commands in order, to make progress with minimal disruption.

Table Clause

Include this clause to indicate which database tables should be re-indexed. Only those columns that have indexing defined will be re-indexed. You should include up to and including the “_” in a table name, since what follows is specific to the vault specified. For example:

index vault "Engineering-1" table lxbo_;

This command might generate and execute SQL similar to:

alter index lxBO_abbe6b7a_lxOid_Index rebuild;
alter index lxBO_abbe6b7a_lxName_Index rebuild;
alter index lxBO_abbe6b7a_lxOwner_Index rebuild;
alter index lxBO_abbe6b7a_lxPolicy_Index rebuild;

The Engineering-1 vault is associated with the abbe6b7a table.

Indexspace Clause

Use this clause to specify an alternate database tablespace to use for processing this command. For example:

index vault “Engineering-1” table lxbo_ indexspace USER_DATA; 

This SQL generated is as follows:

alter index lxBO_abbe6b7a_lxOid_Index rebuild tablespace USER_DATA
alter index lxBO_abbe6b7a_lxName_Index rebuild tablespace USER_DATA;
alter index lxBO_abbe6b7a_lxOwner_Index rebuild tablespace USER_DATA;
alter index lxBO_abbe6b7a_lxPolicy_Index rebuild tablespace USER_DATA;
alter index lxBO_abbe6b7a_lxState_Index rebuild tablespace USER_DATA;

This command adds indices to all columns of lxBO_ table (of the vault Engineering-1) that have indexing defined, and the command would use tablespace USER_DATA to hold the index data. You must also include the table clause with using the indexspace clause.

Syntax

tidy vault NAME [modified after DATE] [modified before DATE];

• NAME is the name of the vault you want to fix. You can specify the ADMINISTRATION vault to remove unused records of deleted administration objects.
• [modified after DATE] is the date on or after which object were last modified.
• [modified before DATE] is the date on or before which object were last modified.

This command consolidates the fragmented database file. It deletes rows in the database tables that are marked for deletion. You must run tidy vault on all vault instances prior to running tidy vault ADMINISTRATION.

When you use the tidy vault command on an object vault, it also tidies any associated path vault. You cannot explicitly tidy a path vault.

When a business object is deleted, it also gets removed from any sets to which it belongs. This includes both user-defined sets and sets defined internally. IconMail messages and the objects they contain are organized as members of an internal set. So when the object’s vault is changed, it is not only removed from its sets, but it is also removed from all IconMail messages that include it. In many cases the messages alone, without the objects, are meaningless.

To address this issue, the change vault command includes the following additional functionality:

• Add the object clone from the new vault to all IconMail messages and user sets in which the original object was included.

The additional functionality could affect the performance of the change vault operation if the object belongs to many sets and/or IconMails. The default functionality has not been changed, but business administrators can execute the following MQL command to enable/disable this functionality for system-wide use:

set system changelattice update set | on  | off |; 

For example, to turn the command on for all users, use:

set system changelattice update set on; 

Once this command has been run, when users change an object’s vault through any application (that is, all products, 3DEXPERIENCE Platform), all IconMails that reference the object are fixed.

You can also fix IconMail at the time the change vault is performed (in MQL only). For example:

modify bus Assembly R123 A vault Engineering update set; 

print vault NAME;

• If the NAME contains embedded spaces, use quotation marks.

A print vault command lists only objects that have been updated (those objects for which there is a database table entry).

You cannot directly print a path vault, but you can use a selectable to view that information. To do so, use this syntax:

print vault OBJECTVAULTNAME select pathvault.suffix;

delete vault NAME;

• NAME is the name of the vault to be deleted.

Only empty vaults can be deleted. To remove all objects from a vault, use the clear vault command. For more information, see Clear Vault. When you delete an object vault, any associated path vault is also deleted.

This command searches the list of existing vaults. If the name is found and the vault contains no business objects, the vault is deleted. If the name is not found, an error message is displayed. If you attempt to delete a vault that contains business objects, an error message is displayed.

For example, to delete the vault named “1965 Bank Loans,” enter:

delete vault “1965 Bank Loans”;

After this command is processed, the vault is deleted and you receive an MQL prompt for another command.