Add Store Command

Syntax

Before defining a DesignSync store, configure the DesignSync server to:

• Allow BrowseServer access to the system administrator user that will create the store.
• The communication protocol used by the DesignSync server needs to match the protocol in use on the 3DSpace Service. If you want to use secure protocol (SSL/HTTPS) to communicate between DesignSync and the 3DSpace Service, you must configure SSL on your DesignSync server and install the digital certificate onto the 3DSpace Service. For more information, see Collaboration and Approvals Administration Guide: DesignSync File Access.

A file store is defined with the Add Store command:

add store NAME [ADD_ITEM {ADD_ITEM}];

• NAME is the name of the store you are defining. All stores must have a name unique in the database. The name can contain spaces. Do not include the @ sign in the name, as that is used internally by 3DSpace. You should assign a name that has meaning to both you and the user. For more information, see About Administrative Object Names.
• ADD_ITEM provides more information about the store you are creating. The only required clause for store creation is the Type clause. Other clauses can help to further define the store. The Add Store clauses are:

  description VALUE

  fcs FCS_URL

  prefix PREFIX

  copyonwrite

  checksum [on|off]

  checksumwarnonly [on|off]

  [on|off]line

  indexport PORT

  icon FILENAME

  [un]lock

  type captured|designsync|external [params paramsString |file paramsFile] [vault defaultVault] [filter FILTER_CLASS_NAME] [trigger REPLICATION_TRIGGER_CLASS [replicationtrigger REPLICATION_TRIGGER_CLASS] [deletetrigger DELETE_TRIGGER_CLASS]

  CAPTURED_ITEM | DS_ITEM

  [!|not]hidden

  property NAME [to ADMINTYPE NAME] [value STRING]

  • CAPTURED_ITEM is:

    filename hashed

    host HOST_NAME

    password PASSWORD

    path PATH_NAME

    port PORT_NUMBER

    protocol PROTOCOL_NAME

    permission OWNER_ACCESS [,GROUP_ACCESS [,WORLD_ACCESS]]

    user USER [params paramsString|file paramsFile] [external] [filter FILTER_CLASS_NAME] trigger REPLICATION_TRIGGER_CLASS [replicatontrigger REPLICATION_TRIGGER_CLASS] [deletetrigger DELETE_TRIGGER_CLASS]

  • DS_ITEM is:

    host HOST_NAME

    path PATH_NAME

    port PORT_NUMBER

    user USER

    password PASSWORD

    protocol PROTOCOL_NAME

    class EXTERNAL_PROTOCOL_NAME

  • OWNER_ACCESS is [r][w][x]
  • GROUP_ACCESS is [r][w][x]
  • WORLD_ACCESS is [r][w][x]

The path clause is required only for captured files. Although all other clauses are optional, the following defaults are assumed:

FCS Clause

For captured and external stores, type in the FCS URL in the FCS URL text box. You must define the FCS URL for FCS file replication. The FCS URL is not required for file checkin and checkout operations.

When an FCS URL is not defined, the system uses the URL of the local MCS. Since there are two ways to connect to the 3DSpace Service, the MCS URL can only be inferred when connecting through the application server, usually at port 8080. The other way to connect is through the server, usually at port 1099, but an MCS URL cannot be inferred when connecting this way because an MCS URL is not defined. This means if you are connecting through the server and need to perform FCS operations that require an FCS URL, you must manually define the FCS URL.

Include the Web application name. The syntax is:

fcs http://host:port/WEBAPPNAME

For example:

fcs http://host:port/ematrix

If using Single Sign On (SSO) with FCS, the FCS URL should have the fully qualified domain name for the host. For example:

fcs http://HOSTNAME.MatrixOne.net:PORT#/ematrix

You can also specify a JPO that will return a URL. For example:

fcs ${CLASS:prog} [-method methodName] [ args0 … argN]

You can also specify settings in framework.properties or web.xml to control various parts of the FCS system such as: the length of time a ticket or receipt is valid, and how many tickets or receipts the system retains before deleting them. For more information, see File Collaboration Server Guide.

DesignSync stores do not require an FCS URL and one should NOT be defined for them.

Type Clause

This clause identifies how the files are stored and accessed. You can specify one of the three store types: captured, designsync, or external.

Once you decide how to store and control your files, you can specify the store type by adding a Type clause to your Add Store command. All file store definitions must have a Type clause to be usable. The following example creates a store to hold captured files:

add store Drawings
   description "Storage for electronic drawings"
   host RELIABLE
   path ${MATRIXHOME}/Drawings
   type captured;

File Name Hashing

Captured stores generate hashed names for checked in files based on a random number generator and timestamp. If a name collision occurs, it will retry with a new hashname up to 100 tries, then return an error. Since the files for captured stores are physically stored on disk, the names are hashed to be recognized by 3DSpace only.

A file copied from a store to a location goes through the same file naming algorithm.

When a file is checked into a captured store (or location) a 2-level directory structure is created below the store/location’s directory path. Each subdirectory name is derived from the hashed file name and is 2 characters long. The first 2 characters of the hashed name are the first level subdirectory name; the 3rd and 4th characters are the second level subdirectory name. For example, a captured and hashed store named Docs is defined to use the directory Docs. A file is checked in that uses this store and the hashed name generated is dd24c8c236e6875e.c06. The file is put into the following directory on the store’s host machine:

Docs/dd/24/dd24c8c236e6875e.c06

The database includes the subdirectories in the file name. The format.file select output includes this information in the locationfile[ ] and capturedfile sub-select output as shown below:

format.file.locationfile[Docs] = dd/24/dd24c8c236e6875e.c06

format.file.capturedfile = dd/24/dd24c8c236e6875e.c06

FCS used with 3DEXPERIENCE web apps does not support non-hashed stores. Any existing non-hashed stores must be converted to hash stores to be used with 3DEXPERIENCE web apps.

Lock Clause

This clause locks a store from the user for all write activities. Business objects with a policy using a locked store cannot have files checked in (written), but files can be checked out (read) or deleted. This is useful when backups are being made or when a store is full. The default is unlocked.

For example:

add store "Vellum CAD Drawings"
   locked  
   type captured;

A locked store prevents file checkin, but still allows file checkout or deletion. You can prevent files from being deleted or checked out by adding a trigger on the RemoveFile or Checkout events.

Path Clause

This clause is required for captured and DesignSync stores. For captured stores, the path identifies where the file store is to be placed on the host. All files and folders referencing a store will be relative to its path. Paths should not include the @ sign, as that is used internally by 3DSpace. A store should NOT point to the same directory as a location since this might cause unnecessary file copying.

Stores should use actual host names and paths, not mounted directories. For captured stores, the path must be exported to all users that need access to the files.

A captured store will create a directory for the captured files. When a file is checked into a captured store (or location), a 2-level directory structure is created below the store/location’s directory path. Each subdirectory name is derived from the hashed file name and is 2 characters long.

The following Add Store command creates a file store located in MATRIXHOME\Training on the Reliable host:

add store Training
   description "Storage for training information"
   host Reliable
   path ${MATRIXHOME}/Training
   type captured;

For DesignSync stores, the path should indicate where files, folders, and modules should be looked for and put in the DesignSync system (or “repository”, as it is sometimes called), and correspond to part of the string used in the “setvault” DesignSync command.

A path is not required when you create a DesignSync store and can instead be defined later when a file, folder or module is checked into the store. DesignSync stores should only be created without a path if you plan to use the store for files and folders. If you plan to use the store for modules, you should define a path of “/Modules/*” since modules can ONLY be checked into stores with a path of “/Modules.” Files and Folders can be check into stores with any path except “/Modules.

For example, to set up a store for a DesignSync project that uses this setvault command:

dss setvault sync://src.matrixone.net/Projects/Documents/Release

the path would be:

Projects/Documents/Release

Prefix Clause

A prefix can be added to the path defined for a captured store or location to enhance file management operations. A prefix adds a subdirectory to the path. For example, when you add the prefix project1 to a store with a path of c:\enovia\stores\store1\, the c:\enovia\stores\store1\project1 directory is created.

add store store1 prefix project1;

Prefix names are limited to 64 characters and can only include upper and lowercase letters and numbers. Adding “\” and “/” to the prefix is not allowed. A store or location can only have one prefix defined at a time.

A prefix separates the path into the main path and the path with the prefix. For example, if a folder has a file limit and that limit is reached, you can modify the store’s prefix to redirect file checkins to the new directory. On UNIX platforms, if the current file storage is full, you can modify the prefix to use a new mounted drive. Modifying the prefix will affect where files are stored in future checkin operations.

modify store NAME prefix PREFIX;

You can only add and modify prefixes using MQL.

Import and export operations are not aware of prefixes. When you import or export from the current version or versions with the prefix option, you need to manually migrate the prefixes using an MQL or Tcl script.When you import from older versions without the prefix option, the prefix is defaulted to an empty string.

Host Clause

This clause identifies the host system to contain the file store being defined. If a host is not specified, the current host is assumed and assigned. If the store is to be physically located on a PC and accessed through a network drive, the store host name must be set to localhost. Host names should not include the @ sign, as that is used internally by 3DSpace.

For DesignSync stores, the Host should be set to the name of a DesignSync server. For example:

src.matrixone.net 

File stores can be created and can exist across networks. Depending on who uses a file store, you might install it on a system local to its users. That speeds up access and avoids placing additional loads on network communications.

File stores that are frequently used by all nodes within a network should be contained on a centrally located node. If a file store is used extensively by one system, you might want to place the store on that system to improve access time and communications requirements.

For example, the following command defines a store (Video) that resides on the system called Reliable in a directory defined by the environment variable MATRIXHOME:

add store Video
   description "Storage for video data"
   host Reliable
   path ${MATRIXHOME}
   type captured;

If files will need to be checked in and out via the Web, you should install a file 3DSpace Service on the file store host machine. For more information, see File Collaboration Server Guide.

Protocol and Port Clauses

When creating a captured or designsync store, you can include the parameters protocol and port. The protocol defined for a captured store determines the file access given by the controlling FCS.

protocol PROTOCOL_NAME [port PORT_NUMBER]

• PROTOCOL_NAME is file for captured stores. DesignSync stores use a protocol of either http or https.
• Each protocol has a default port that is used if not specified in the store definition. Include the port subclause to specify a port other than the default.

This protocol is not related to the protocol used for file transfers between FCSs during synchronization operations. The HTTP/S protocol is always used for these operations.

For example:

add store MyStore type captured host Reliable 
path ${MATRIXHOME}/MyStore protocol file user Engineering password secret;

Permission Clause

File permissions are no longer supported for captured stores, and have no effect on files and folders that are managed by the FCS.

User and Password Clauses

For DesignSync stores, the User and Password clauses are used to specify a valid DesignSync user and password; therefore, you must adhere to DesignSync naming conventions.

The initial connection to DesignSync is made by the user defined here, and access privileges for non-file operations in DesignSync are based on this user account. However, file (and folder) operations are performed by the current context user, not this user. Therefore, the DesignSync store user specified must be set up with the “Swi tchUser” privilege in the AccessControl file in DesignSync, and this must be done before creating the store. For more information, see Access Privilege Definitions.

For file operations, the context user is subject to access controls in effect for both 3DSpace and DesignSync. For example, if a checkin is attempted via the Semiconductor Accelerator, and the user does not have both 3DSpace and DesignSync checkin access, the operation will fail. If the checkin is successful, in DesignSync the author is listed as the user that checked in the file.

Since a 3DSpace username can contain characters not permitted in a DesignSync username, such as spaces and Japanese characters encoded in UTF-8, there is an encoding/decoding that occurs between the 2 systems. For example, a space in a 3DSpace username is represented in DesignSync with a “+”.

Vault Clause

When adding an external store you must include the Vault clause to specify the external vault to be used in conjunction with the external store. The Vault clause only has meaning if both it and the store are marked as external.

File or Param Clause

When adding an external store you can use either the File or Params clause to include optional parameters for use with the external vault. For example:

add store wsStore type external vault wsVault file paramsFile.xml;

DeleteTrigger Clause

The DeleteTrigger clause allows you to implement alternate behavior for when files are being deleted from a store or location. To add a no-delete policy on a store, you can use the out of the box implementation in com.matrixone.fcs.backend.NoFileDelete. For example:

add store MyStore type captured deletetrigger com.matrixone.fcs.backend.NoFileDelete;

You can also write your own Java class that implements the com.matrixone.fcs.mcs.DeleteTrigger interface to insert any customized behavior, such as altering the file delete list. It can be either a JPO or a regular Java class that can be found in the classpath.

The DeleteTrigger that is set for a store automatically applies to all locations that are associated with that store, unless it is overridden at a particular location. The DeleteTrigger clause is only valid on captured stores (and locations).

ReplicationTrigger Clause

The ReplicationTrigger clause allows you to implement alternate behavior when files within the store are replicated based on file replication rules set in the governing object’s policy. For example, you could write your own Java class that implements the com.matrixone.fcs.mcs.ReplicationTrigger interface to insert any customized behavior such as blocking the replication or getting a file from a different source. It can be either a JPO or a regular Java class that can be found in the classpath.

The ReplicationTrigger clause is only valid on captured stores, and not locations.

Checksum Clause

The Checksum clause allows you to activate or deactivate the usage of checksums, which FCS uses to perform a file integrity check at checkout to determine if the file to be checked out has been modified (corrupted) since it was last checked in. When checksums are activated, FCS will compute and send a checksum to the MCS when a file is checked in. Then when a file is checked out, FCS computes a checksum of the file to be checked out and compares it with the checksum saved on the MCS for the previously checked in version of the file. If the checksums differ, FCS returns an error and the file checkout fails.

The default is off.

Using checksums to check file integrity has a performance cost. The checksum computation is based on streamed data, which increases FCS checkin and FCS checkout time slightly, but the increase is a reasonable tradeoff for the increased data integrity.

ChecksumWarnOnly Clause

The checksumwarnonly clause allows you to set the behavior of FCS when it detects a corrupted file by comparing checksums during checkout. By default, FCS returns an error and the checkout process fails. When checksumwarnonly is turned on, the invalid checksum is logged, but no exception is thrown, so the checkout succeeds, although the user is warned.

The default is off.

This checksumwarnonly parameter applies only when the checksum parameter is turned on.