TMCore Command Line Tools


Table of Contents

Introduction
tmimport : XTM Import Utility
Command Synopsis
Usage Examples
tmexport : XTM Export Utility
Command Synopsis
Usage Examples
tmdelete : Deletion Utility
Command Synopsis
Usage Examples
npcl : Topic Map Schema Utility
Command Synopsis
Usage Examples
tmdiag: Topic Map Diagnostic Utility
Command Synopsis
Usage Examples
TMServiceQueryInvoker: TMService Query Diagnostic Utility
Command Synopsis
Usage Examples

Introduction

This document describes the command line tools distributed with TMCore. Each tool is documented in a separate section detailing the purpose of the tool and the command line parameters it takes.

tmimport : XTM Import Utility

The tmimport command can be used to import data from an XTM file into a topic map in the TMCore system. The imported data can either be merged with an existing topic map or loaded into a new topic map.

Command Synopsis

tmimport [/host:<string>] [/database:<string>] [/userid:<string>] [/password:<string>] [/mapname:<string>] [/verbose] {filename}

Table 1. tmimport Parameter Summary

Parameter (Short Form)

Description

/host (/h)

Specifies the name or IP address of the database server that hosts the TMCore system database.

Defaults to 'localhost'.

/database (/d)

Specifies the name of the database catalog that contains the TMCore system tables.

Defaults to 'topicmap'.

/userid (/u)

Specifies the database user ID to use when connecting to the database.

If this parameter is omitted, the connection will instead use the current Windows login for database authentication.

/password (/p)

Specifies the password to use when connection to the database.

This parameter is ignored if the /userid: parameter is not present. If the /userid: parameter is present and this parameter is omitted, the program will attempt to connect to the database using the specified user ID and no password.

/srcuri (/s)

Specifies the URI which will be used for the resolution of relative paths contained in the XTM file.

If this parameter is not specified, then relative paths will be resolved against the path to the imported file.

/mapname (/m)

Specifies the name of the topic map to be populated with the XTM data.

If the TMCore system does not contain a topic map with that name, then a new topic map will be created. If a topic map already exists with the specified name, then the XTM data will be merged with the existing data in the named topic map. If this parameter is omitted, then the value of the /srcuri: parameter will be used as the topic map name.

If both this parameter and the /srcuri: parameter are omitted, then the file:// URI of the imported XTM file will be used as the topic map name.

/verbose (/v)

Give more verbose error messages.

filename

The path to the XTM file to be imported.

Usage Examples

tmimport c:\mymap.xtm

Imports data from mymap.xtm into the TMCore system. All relative URIs will be resolved against the path to the topic map expressed as a file:// URI (i.e. against file://c/mymap.xtm). This URI will also be used as the name of the imported topic map in the TMCore system (if a topic map with this name already exists, then the data from mymap.xtm will be merged into the existing topic map).

tmimport /host:tmserver /database:test c:\mymap.xtm

Operates in the same way as the first example, but connects to a remote database server and a non-default catalog. Note that even when importing data into a remote server, all file paths are still resolved locally and the topic map name will still be generated from the file:// URI of the local file.

tmimport /userid:tmguy /password:ihearttms c:\mymap.xtm

Operates in the same way as the first example, but uses a database account to authorise access to the TMCore system.

tmimport /srcuri:http://www.example.com/tmdata/mymap.xtm mymap.xtm

Imports data from mymap.xtm into the TMCore system. All relative URIs will be resolved against the URI http://www.example.com/tmdata/mymap.xtm. This URI will also be used as the name of the imported topic map in the TMCore system.

tmimport /srcuri:http://www.example.com/tmdata/index.xtm /mapname:index.xtm mymap.xtm

Imports data from mymap.xtm into the TMCore system. All relative URIs will be resolved against the URI http://www.example.com/tmdata/index.xtm. The data will be imported into the topic map named index.xtm (if the topic map does not already exist, it will be created).

tmexport : XTM Export Utility

The tmexport command can be used to export topic maps from the TMCore system as XTM files. The utility includes an option to dump all of the topic maps from the system as XTM, or to specify selected topic map(s) to export.

Topic maps are always exported to a file in the current directory with the file name being the same as the topic map name in the topic map system. Any special characters in a topic map name that are not allowed as file name characters will be replaced with the underscore (_) character.

Command Synopsis

tmexport [/host:<string>] [/database:<string>] [/userid:<string>] [/password:<string>] [/all] [/force] [/verbose] {mapname...}

Table 2. tmexport Parameter Summary

Parameter (Short Form)

Description

/host (/h)

Specifies the name or IP address of the database server that hosts the TMCore system database.

Defaults to 'localhost'.

/database (/d)

Specifies the name of the database catalog that contains the TMCore system tables.

Defaults to 'topicmap'.

/userid (/u)

Specifies the database user ID to use when connecting to the database.

If this parameter is omitted, the connection will instead use the current Windows login for database authentication.

/password (/p)

Specifies the password to use when connection to the database.

This parameter is ignored if the /userid: parameter is not present. If the /userid: parameter is present and this parameter is omitted, the program will attempt to connect to the database using the specified user ID and no password.

/all (/a)

Specifies that all topic maps in the TMCore system should be exported.

If this parameter is specified then any topic map names provided on the command-line will be ignored and all topic maps will be exported.

/force (/f)

If this switch is specified on the command line, then the application will silently overwrite existing files. Otherwise, you will be prompted for each possible file overwrite.

/verbose (/v)

Give more verbose error messages.

mapname

The name of the topic map to be exported. You may specify multiple topic map names on the command line by separating each name with a space. If a topic map name contains a space, use quotes on the command line (e.g. tmexport "My Topic Map").

Usage Examples

The following examples do not show examples of the /host /database /userid or /password options which work exactly as for the tmimport application.

tmexport mymap.xtm

Exports the topic map in the TMCore system with the name 'mymap.xtm'. The data will be written to a local file named mymap.xtm.

tmexport mymap.xtm myothermap

Exports the topic maps in the TMCore system with the names 'mymap.xtm' and 'myothermap'. The data will be written to the files mymap.xtm and myothermap respectively.

tmexport /a /f

Exports all topic maps from the TMCore system to XTM files in the local directory. This export will silently overwrite any existing files in the same directory when a name-clash occurs (because of the /f option).

tmdelete : Deletion Utility

The tmdelete command can be used to remove a topic map from the TMCore system. Because this deletion cannot be reversed, by default the command will prompt you to confirm that you really want the deletion to be performed.

Command Synopsis

tmdelete [/host:<string>] [/database:<string>] [/userid:<string>] [/password:<string>] [/force] [/verbose] {mapname}

Table 3. tmdelete Parameter Summary

Parameter (Short Form)

Description

/host (/h)

Specifies the name or IP address of the database server that hosts the TMCore system database.

Defaults to 'localhost'.

/database (/d)

Specifies the name of the database catalog that contains the TMCore system tables.

Defaults to 'topicmap'.

/userid (/u)

Specifies the database user ID to use when connecting to the database.

If this parameter is omitted, the connection will instead use the current Windows login for database authentication.

/password (/p)

Specifies the password to use when connection to the database.

This parameter is ignored if the /userid: parameter is not present. If the /userid: parameter is present and this parameter is omitted, the program will attempt to connect to the database using the specified user ID and no password.

/force (/f)

If this command line option is specified, then the topic map will be deleted without a confirmation prompt. Use with caution!

/verbose (/v)

Give more verbose error messages.

mapname

The name of the topic map to be deleted

Usage Examples

tmdelete mymap

Deletes the topic map named 'mymap' from the TMCore server on the local machine using the default catalog 'topicmap'.

tmdelete /host:tmserver /database:test mymap

Operates in the same way as the first example, but connects to a remote database server and a non-default catalog.

tmdelete /userid:tmguy /password:ihearttms mymap

Operates in the same way as the first example, but uses a database account to authorise access to the TMCore system.

tmdelete /force mymap

Deletes the topic map named 'mymap' from the TMCore server on the local machine without prompting for confirmation.

npcl : Topic Map Schema Utility

The npcl command can be used to work with the NetworkedPlanet Constraint Language (NPCL). Using this tool you can:

  1. Export an NPCL schema from a topic map.

  2. Import an NPCL schema into a topic map, either updating or replacing existing schema information.

  3. Generate an NPCL schema by example, based on a topic map.

The npcl command works with NPCL schema files that use the NPCL XML syntax. You can read more about NPCL in the Engine API Guide document.

Command Synopsis

npcl [/host:<string>] [/database:<string>] [/userid:<string>] [/password:<string>] [/verbose] [/sibase:<base uri>] /action:{add|overwrite|export|generate} /mapname:<topic map name> /npcl:<filename>

Table 4. npcl Parameter Summary

Parameter (Short Form)

Description

/host (/h)

Specifies the name or IP address of the database server that hosts the TMCore system database.

Defaults to 'localhost'.

/database (/d)

Specifies the name of the database catalog that contains the TMCore system tables.

Defaults to 'topicmap'.

/userid (/u)

Specifies the database user ID to use when connecting to the database.

If this parameter is omitted, the connection will instead use the current Windows login for database authentication.

/password (/p)

Specifies the password to use when connection to the database.

This parameter is ignored if the /userid: parameter is not present. If the /userid: parameter is present and this parameter is omitted, the program will attempt to connect to the database using the specified user ID and no password.

/verbose (/v)

Give more verbose error messages.

/sibase (/si)

Used only for the generate action. This parameter specifies a base URI for generating subject identifiers for topics which do not currently have one but are required to do so to be included in the NPCL schema.

The generated subject identifier for a topic will be created by concatenating the display name for the topic (converted to lower case) with the base URI, with an additional numeric suffix if required to make the identifier unique.

If this option is omitted, the subject identifiers are instead generated in the form 'urn:x-tmcore:topicid:database id of topic', which will be recognised by the NPCL import process and will ensure that those topics are correctly updated with schema information.

If you are generating a schema that you wish to then import back into the same topic map, we recommend that you OMIT this option. If you are generating a schema that you want to use on other topic maps, we recommend that you SPECIFY this option.

/action (/a)

Specifies the action to be performed. This parameter is REQUIRED and must have one of the following values:

add

Specifies that the NPCL file should be imported into the topic map, adding to any existing schema information.

overwrite

Specifies that the NPCL file should be imported into the topic map, replacing all existing schema information.

export

Specifies that the schema information in the topic map should be written to the NPCL file.

generate

Specifies that the topic map should be processed to generate a schema based on the actual usage of types, scopes etc. in the topic map. The schema will be written to the specified NPCL file.

/mapname (/m)Specifies the name of the topic map to be read from or written to (depending on the action chosen).
/npcl (/n)Specifies the path to the NPCL XML file to be read from or written to (depending on the action chosen). On an export or generate action, if the file already exists, you will be prompted to confirm the overwriting of the file.

Usage Examples

npcl /a:export /m:mytopicmap.xtm /n:mytopicmap-schema.npcl

Exports the NPCL Schema information from the TMCore topic map named "mytopicmap.xtm" to a local NPCL XML file named mytopicmap-schema.npcl.

npcl /a:overwrite /m:mytopicmap.xtm /n:new-schema.npcl

Replaces the NPCL Schema information contained in the TMCore topic map named "mytopicmap.xtm" with the schema defined in the NPCL XML file named new-schema.npcl.

npcl /a:add /m:mytopicmap.xtm /n:new-schema.npcl

Adds the NPCL Schema information contained in the local NPCL XML file named new-schema.npcl to the schema information contained in the TMCore topic map named "mytopicmap.xtm".

npcl /a:generate /m:mytopicmap.xtm /n:mytopicmap-schema.npcl

Infers a new NPCL Schema based on the actual usage of types, scopes etc. in the TMCore topic map named "mytopicmap.xtm". The inferred schema is written to the local NPCL XML file named mytopicmap-schema.npcl. Topics in the source topic map which do not have subject identifiers but are required to do so by the restrictions of NPCL will have subject identifiers generated using the default form 'urn:x-tmcore:topicid:database id of topic'. This allows a subsequent import of the schema information into the same topic map (using the /a:add or /a:overwrite options) to locate and update those topics correctly.

npcl /a:generate /m:mytopicmap.xtm /n:mytopicmap-schema.npcl /si:http://www.example.com/psi/ontology/

Infers a new NPCL Schema based on the actual usage of types, scopes etc. in the TMCore topic map named "mytopicmap.xtm". The inferred schema is written to the local NPCL XML file named mytopicmap-schema.xml. Topics in the source topic map which do not have subject identifiers but are required to do so by the restrictions of NPCL will have subject identifiers generated using the custom subject identifier prefix 'http://www.example.com/psi/ontology/'. On a subsequent import of the schema information into the same topic map, the topics with these generated subject identifiers will be created as new topics and will not properly update the topics from which they were generated. This option is most useful when you want to generate a schema from one topic map and then import that schema into a different topic map or use it as the basis for creating a new topic map from scratch.

tmdiag: Topic Map Diagnostic Utility

The tmdiag command can be used to query topic maps searching for information about a particular topic map, topic or topic attribute. Using this tool you can:

  1. Get a list of topic maps in the database.

  2. Display information about any topic map object:

    1. Topic Map

    2. Topic

    3. Topic name

    4. Occurrence

    5. Association

    6. Association Role

Command Synopsis

tmdiag [/host:<string>] [/database:<string>] [/userid:<string>] [/password:<string>] [/objectid:<integer>]

Table 5. npcl Parameter Summary

Parameter (Short Form)

Description

/host (/h)

Specifies the name or IP address of the database server that hosts the TMCore system database.

Defaults to 'localhost'.

/database (/d)

Specifies the name of the database catalog that contains the TMCore system tables.

Defaults to 'topicmap'.

/userid (/u)

Specifies the database user ID to use when connecting to the database.

If this parameter is omitted, the connection will instead use the current Windows login for database authentication.

/password (/p)

Specifies the password to use when connection to the database.

This parameter is ignored if the /userid: parameter is not present. If the /userid: parameter is present and this parameter is omitted, the program will attempt to connect to the database using the specified user ID and no password.

/verbose (/v)

Give more verbose error messages.

/objectId (/o)

The non-negative integer identity of a topic map object in the database that is to be searched for.

If no value is specified or 0 is specified then a list of the topic maps in the database is displayed.

/name (/n)A topic name to search for. % and _ may be used as wildcards for any string or a single character respectively.
/subjectidentifier (/s)A full or partial specification of a subject indicator. % and _ may be used as wildcards for any string or a single character respectively. Specifying this option will display all topics that match the subject identifier pattern given, so care should be taken with this option when specifying very commonly used patterns, such as http%.
/occValueUsed to find an occurrence by value. % and _ may be used as wildcards for any string or a single character respectively.
/occResourceUsed to find an occurrence by resource. % and _ may be used as wildcards for any string or a single character respectively.

Usage Examples

tmdiag

Displays a list of topic maps available in the local topicmap database.

tmdiag /o:23

Displays information about the topic map object with identity 23.

TMServiceQueryInvoker: TMService Query Diagnostic Utility

The TMServiceQueryInvoker command can be used to invoke customized queries on the TMCore TMService web service. It can be used for testing purposes by developers, or for diagnosing faults in TMService query declarations in web.config.

Command Synopsis

TMServiceQueryInvoker [/host:<string>] [/database:<string>] [/userid:<string>] [/password:<string>] [/objectid:<integer>]

Table 6. npcl Parameter Summary

Parameter (Short Form)

Description

/url (/u)

Specifies the URL to the TMService asmx endpoint.

Defaults to http://localhost/tmws/TMService.asmx.

/action (/a)Either query or queries depending on which method of TMService you wish to invoke.
/query (/q)The name of the query that is to be invoked.
/param (/p)

Specifies a parameter to be passed to the query.

Usage Examples

TMServiceQueryInvoker "/u:http://localhost/tmws/TMService.asmx" /query:EPiModule_GetAllTypes /param:4333 /a:query

Invokes the EPiModule_GetAllTypes query on the TMService deployed at http://localhost/tmws/TMService.asmx passing a single parameter: 4333.

TMServiceQueryInvoker /query:SitecoreModule_SearchTopicsByNameAndTypes /param:5423 /param:64226 /a:queries

Invokes the SitecoreModule_SearchTopicsByNameAndTypes query on the TMService passing two positional parameters: 4333 and 64226. As the TMRQL defined by this query returns multiple data tables we also specify /a:queries.