location Command

Locations contain alternate host and path information for a captured store. The host and path in the store definition is considered to be the default location for the store, while any associated location objects identify alternate file servers.

Think of a location as another store—it is defined as file “location.” The same rules apply as in specifying a store.

For conceptual information on this command, see Locations and Sites.

This page discusses:

User Level

System Administrator

Add Location

Use the add location command to defined a location.

Syntax

add location NAME [ADD_ITEM {ADD_ITEM}];
  • ADD_ITEM is an Add Location clause that provides more information about the location you are creating.

The Add Location clauses are: 

[!|not] hidden
 
description VALUE
 
fcs FCS_URL
 
host HOST_NAME
 
icon FILENAME
 
password PASSWORD
 
path PATH_NAME
 
prefix PREFIX
 
permission OWNER_ACCESS [,GROUP_ACCESS [,WORLD_ACCESS]]
 
port PORT_NUMBER
 
indexport PORT
 
property NAME [to ADMINTYPE NAME] [value STRING]
 
protocol PROTOCOL_NAME
 
url VALUE
 
user USER_NAME
 
deletetrigger DELETE_TRIGGER_IMPLEMENTATION

Host Clause

This clause identifies the system that is to contain the location being defined. If a host is not specified, the current host is assumed and assigned.

If the location is to be physically located on a PC and accessed through a network drive, the host name must be set to localhost. For example: 

add location host localhost

Protocol and Port Clauses

When creating a location object for captured stores, you can include the parameters protocol and port . Protocol and port can be defined when creating a location object for captured stores. The protocol defined for a location determines the file access given by the controlling FCS. 

protocol PROTOCOL_NAME

  • PROTOCOL_NAME is file for captured store locations and HTTP or HTTPS for DesignSync locations.

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.

Each protocol has a default port that is used if not specified in the location definition. Include the Port clause to specify a port other than the default. 

port PORT_NUMBER

If a location does not have a protocol specified, 3DSpace looks at other object attributes to determine which protocol was likely intended.

  • If the host is not ‘localhost’ (or empty), and there is no username/password, the protocol used will be 'file' (local file system).
  • If it is a designsync store, the default is http.

These checks eliminate the need to add protocol/port parameters to store/locations added prior to version 9.

Password Clause

The password provides access to the DesignSync account.

The Password clause uses the following syntax: 

password PASSWORD

  • PASSWORD is the DesignSync password.

Path Clause

The path identifies where the location is to be placed on the host. A location should NOT point to the same directory as a store since this could cause unnecessary file copying. When a location is defined, a directory for the captured files is created.

If an invalid directory is specified for the PATH parameter during location or store creation, only a warning is issued. The transaction will not abort and the location or store is created with the invalid directory. Any checkin or copy operation using this new location or store will fail.

For example, you could use the following clause: 

path Drawings

An absolute path can also be entered; however, the parent directory must already exist. For example, in the following command, if the /stores directory does not exist on the target host, the location will not be created. 

path stores/store1

Prefix Clause

A prefix can be added to the path defined for a captured store or location to enhance file management operations. For more information, see Prefix Clause (for the store command).

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.

Warning: Do not directly modify or change folders and files managed by the FCS in any way (rights, size, and so on).

User Clause

When moving files to/from a store location, the DesignSync username defines the DesignSync account used. The User clause uses the following syntax: 

user USER_NAME
  • USER_NAME is the DesignSync username.

FCS Clause

If using FCS for file checkins and checkouts with a captured location, you must specify the URL for the location’s server.

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]

For information about FCS processing and configuration, see the File Collaboration Server Guide.

Delete Trigger 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 location, you can use the out of the box implementation in com.matrixone.fcs.backend.NoFileDelete. For example: 

add location MyLocation 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.

Copy Location

You can copy a location based on an existing location, and change the definition of the new location as part of the copy process. 

copy location SRC_NAME DST_NAME [MOD_ITEM {MOD_ITEM}];
  • SRC_NAME is the name of the existing location.
  • DST_NAME is the name of the location to create based on the existing index.
  • MOD_ITEM clauses can be any of the clauses listed in Modify Location.

Modify Location

After a location is defined, you can change the definition with the Modify Location command. This command lets you add or remove defining clauses and change the value of clause arguments. 

modify location NAME [MOD_ITEM {MOD_ITEM}];
  • NAME is the name of the location to modify.
  • MOD_ITEM is the type of modification to make. Each is specified in a Modify Location clause, as listed in the following table. You need to specify only fields to be modified.
    Modify Location Clause Description
    description VALUE The description is changed to the new value specified.
    host HOST_NAME The host name is changed to the value specified.
    icon FILENAME The image is changed to the new image in the file specified.
    protocol PROTOCOL_NAME The protocol is changed to the value specified.
    port PORT_NUMBER The port is changed to the number specified.
    name NAME The location name is changed to the new name.
    password PASSWORD The DesignSync password is changed to the value entered.
    path PATH_NAME The current comment, if any, is changed to the value entered.
    prefix 'PREFIX_NAME(,PREFIX_NAME)' The prefix is changed to the value specified. You can include a comma-separated list of prefixes.

    When writing files to disk, the app use the location with the most available disk space. The prefix works with these properties in the FCS side Framework.properties file:

    ematrix.fcs.prefix_usage_thresholds: defines the percent threshold over which that prefix will not be used for writing files as long as there is another prefix eligible. The value for this property can be in percentage (default is 80%), absolute value of remaining disk space (measured in mebibytes), or percentage, absolute value . For example: ematrix.fcs.prefix_usage_thresholds=80%,1000

    Any prefix that exceeds the threshold is not eligible for writing. If all prefixes have exceeded the threshold, then all of the prefixes become eligible for writing.

    ematrix.fcs.prefix_usage_refresh: defines the minimum delay between 2 free disk space computations on prefixes (in seconds, default = 60 seconds).

    online The location is put online.
    offline The location is taken offline.
    indexport PORT Specifies a port for the index.
    permission OWNER_ACCESS [,GROUP_ACCESS [,WORLD_ACCESS]] File permissions are no longer supported for captured stores, and have no effect on files and folders that are managed by the FCS.
    Warning: Do not directly modify or change folders and files managed by the FCS in any way (for example, rights, size, and so on).
    user USER The DesignSync username is changed to the name specified.
    url VALUE The current URL is changed to the new one entered.
    fcs FCS_URL The current FCS URL is changed to the new one entered. When defining the FCS for a location, a location can only be tied to a single store. For more information, see File Collaboration Server: FCS Locations.
    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.
    deletetrigger DELETE_TRIGGER_IMPLEMENTATION Captured file delete behavior is modified. DELETE_TRIGGER_IMPLEMENTATION implements the com.matrixone.fcs.mcs.DeleteTrigger interface. It can be either a JPO or a regular Java class that can be found in the classpath. For more information, DeleteTrigger Clause.

Each modification clause is related to the clauses and arguments that define the location.

When you modify a location, you first name the location and then list the modifications. For example, the following command changes the permissions of the NY-Documents location: 

modify location "NY-Documents"   permission rw, r, r;

When this command is executed, the permissions of the location become read/write for the owner and read-only for group and world.

Print Location

The Print Location command prints the location definition to the screen allowing you to view it. When a Print command is entered, MQL displays the various clauses that make up the definition. 

print location LOCATION select FIELD;
  • LOCATION is the name of the specific location instance.
  • FIELD lets you specify data to present about the location being printed.

Synchronize Location

Synchronization ensures that users access the latest versions of files when checking out or viewing files in a replicated environment. After a new location is added for a store, you can synchronize the location with an existing location defined for that store.

Before you can synchronize two locations, a copy of the files checked into the source location must be available to the FCS of the destination location and the exact file system checked into the source location must be copied to the destination location via HTTP or other means.

After the file system is copied, a System Administrator must verify that it has been copied exactly to the destination location, retaining all directories and physical files. The sync command will not attempt to verify this. If any files are not correctly copied to the destination location, errors could result in subsequent commands that attempt to access those absent files.

Once the file system is copied correctly, you can then synchronize the two locations with the sync location command. A database record is created and any business object with files in the source location is now aware of the exact copies of those files in the destination location.

It is highly recommended that the destination location be empty with no records referring to it before the source location directory is copied. Errors could occur if the new location is not empty.

To synchronize two locations defined for a store, use the Sync Location command: 

sync location NAME_SOURCE to NAME_DEST;
  • NAME_SOURCE is the name of the source location. This location should contain the data you would like to replicate in the new location.
  • NAME_DEST is the name of the destination location. This location is the newly created location for the store that you would like to synchronize with the source location.

Validate Location

The Validate Location command can be used to identify files in a location that are not associated with any business object in the database. The command requires an input file that lists all files relative to the store’s or location's directory. You must have System Administrator privileges to run the validate command.

Syntax

validate location LOCATION_NAME |fcsfileexist [prefix PREFIXNAME] [file FILEFILE] [indexmode]            |;
                                |fcsorphanfileexist [prefix PREFIXNAME]                                  |
                                |fcsorphanfiledelete [prefix PREFIXNAME]                                 |
  • LOCATION_NAME is the location to check.
  • prefix is the keyword
  • PREFIXNAME narrows the scope of the operation.
  • FILEFILE is the name of the file to validate.
  • indexmode can be one of these values:
    • noindex - (default) the command executes the file existence check without using a file index.
    • index - the command process the file index if it exists and if it is valid. If the file index does not exist, processing with using an index.
    • forceindex - the command allows processing only if the file exists and is valid.

For more information, see validate Command.

Delete Location

If a location becomes obsolete, you can delete that location using the Delete Location command. 

delete location NAME;
  • NAME is the name of the location to be deleted.

Searches the list of defined locations. If the name is not found, an error message is displayed. If the name is found, the location is deleted.

Purge Location

The Purge Location command removes all files from the location. 

purge location NAME [PURGE_ITEM {PURGE_ITEM}];
  • NAME is the name of the location to be purged.
  • PURGE_ITEM is one of the following:
    • commit N
    • continue
    • before DATE
    • beforeAtime DATE
    • [!|not]deletefiles

The date restriction allows you to remove only files that were last checked in prior to the date specified in the command. For example, if you want to purge only files last checked in prior to February 28, 2008 at 9:57:32 AM EST in the location called Shelton, you would enter the following MQL command: 

purge location Shelton before “Thu Feb 28, 2008 9:57:32 AM EST”;

The date format used in this command must be the same format configured in the variable MX_NORMAL_DATETIME_FORMAT for dates in the 3DEXPERIENCE Platform. The time zone in the date restriction must be the MCS time zone and should not be the location time zone.

Emptyprefix Location

The Emptyprefix Location command clears the location that uses that prefix. Clearing the prefix results in copying files stored under that prefix to other eligible prefixes (results in a new hashname for the file), and then deleting the file in the cleared prefix. The copy location for the files is determined the same was as when writing new files (for more information, see the prefix row above).

You cannot stop and restart the emptyprefix command. If the prefix does not exist, no error occurs and the command does nothing. 

emptyprefix location LOCATION_NAME prefix 'PREFIX_NAME' commit N;
  • N is the number of distinct files and is optional. If not specified, 100 is used.

Rehash Location

The rehash location command regenerates file names in the existing format for the specified location. If the specified location contains files that are not hashed, the command copies the file using the current prefix (generating a hash name), commits the change, and safely deletes the non-hashed file if the commit succeeded. If the specified location contains files that are already hashed, by default, the command preserves the files and does not rehash those files. 

rehash location NAME [OPTION];
  • NAME is the name of the location.
  • OPTION can be one or both of these clauses:
    • commit N specifies the number of files to rehash prior to committing the changes. If you specify commit without a value, the command fails.
    • force executes the command on all files in the specified location.