Using command-line processing

You can run one or more services by submitting service requests to the management server from the command line.

Before running a service, you must assign the service to a proxy and a management server by using the manager. The proxy and management server must be running to process the service request. You must also install InfoSphere® Data Architect and IBM Optim Designer to obtain the files that you need to run command-line processing.

There are two options for using the command line:

runservice script

The runservice script is located in the ida_folder\optim\designer\runservice folder, where ida_folder is the folder in which InfoSphere Data Architect is installed. You must open the command line in the ida_folder\optim\designer\runservice folder. The folder contains two script files, one for Microsoft Windows (runservice.bat) and one for Linux and UNIX (runservice.sh).

The runservice script requires that you add the root folder of a Java 6.0 JRE or JDK installation to the PATH environment variable.

The runservice script uses the following syntax when you run services that are assigned to a management server and proxy:

runservice {--service | -s} servicename:version
{--url | -u} serverURL {--continueOnError | -c} 
--service | -s servicename:version

The service name and version number (in n.n.n format). Required.

Service names are case-sensitive. If a service name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

For example: -s demosvc:1.0.0.

--url | -u serverURL
The location of the management server that hosts the registry and repository that contains the service. The location http://localhost:8080 is used by default.

For example: -u http://mgmtserver1:8080.

--continueOnError | -c

This parameter sets the script to continue sending services to the proxy for execution, even if a service fails to be started by the proxy.

The runservice script uses the following syntax when you run an exported service request:

runservice {-r|--serviceRequest} requestfilepath
{-u|-url} proxyURL {-j|--jarMap} mapfilepath 
{-v|--overrideValues} overridefilepath {-l|--logLevel} loglevel
{-t|--timeout} seconds|never {-p|--serviceResponse} responsefilepath
--serviceRequest | -r requestfilepath

The complete file path for the exported service request. Required.

Service request file names are case-sensitive. If the file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

For example: -r demosvc.jar.

--url | -u proxyURL
The location of the proxy that you want to use to run the service. The location http://localhost:12000 is used by default.

For example: -u http://proxy1:12000.

--jarMap | -j mapfilepath

The complete file path for the map file.

Map file names are case-sensitive. If the file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

--overrideValues | -v overridefilepath

The complete file path for the override file.

Map file names are case-sensitive. If the file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

--logLevel | -l loglevel
The log level for the service (that is, the lowest severity of messages to include in the log). Possible values are, from low to high: .
  • OFF
  • SEVERE
  • WARNING
  • INFO
  • CONFIG
  • FINE
  • FINER
  • FINEST
  • ALL

For example: -l INFO.

--timeout | -t timeoutseconds

Specifies the number of seconds to wait for a response before ending (or never wait). The runservice script waits 600 seconds by default.

--serviceResponse | -p serviceresponsefile

The complete file path of the file to which the service response is written.

java -jar com-ibm-nex-client-tool.jar command

The com-ibm-nex-client-tool.jar file is located in the ida_folder\optim\designer\runservice folder, where ida_folder is the folder in which InfoSphere Data Architect is installed. You must open the command line in the ida_folder\optim\designer\runservice folder.

The java -jar com-ibm-nex-client-tool.jar command uses the following syntax, where java_folder is the root folder of a Java 6.0 JRE or JDK installation. To avoid being required to enter the root folder every time that you enter this command, add the root folder to the PATH environment variable.

java_folder/java -jar com-ibm-nex-client-tool.jar 
{--service | -s} servicename:version
{--url | -u} serverURL {--continueOnError | -c}
--service | -s servicename:version

The data management service name and version number (in n.n.n format). Required.

Service names are case-sensitive. If a service name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

For example: -s demosvc:1.0.0.

--url | -u serverURL
The location of the management server that hosts the registry and repository that contains the service. Required.

For example: -u http://mgmtserver1:8080.

--continueOnError | -c

This parameter sets the script to continue sending services to the proxy for execution, even if a service fails to be started by the proxy.

Running multiple services

You can use the command line to run multiple services deployed to the same management server. The services are started one at a time in the specified order. run in parallel

Specify each service and version pair separated by a comma. Do not leave a space before or after a comma.

For example:

runservice -s service1:1.0.0,service2:1.0.0 -u http://mymgmtserver:8080 -c

Spaces in service names

If a service name contains a space or contains multibyte character set (MBCS) characters, the name must be enclosed in double quotation marks (" "). For example:

runservice -s "service name":1.0.0 -u http://mymgmtserver:8080

Running exported service request

You can use the command line to run a service request that has been exported to a file.

For example:

runservice -r C:\services\service1.jar -u http://myproxy:12000

Override file

An override file is an XML file that contains service request parameters. If you specify an override file when you run an exported service request, the runservice script uses the parameters in the override file when running the request.

You can use the runservice script to generate an override file that contains the parameters that are in a service request.

runservice {-g|--generateOverrideTemplate} requestfilepath
{-v|--overrideValues} overridefilepath {-i|--includeComments} {true|false}
--generateOverrideTemplate | -g requestfilepath

The complete file path for the exported service request. Required.

Service request file names are case-sensitive. If a service request file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

--overrideValues | -v overridefilepath
The complete file path for the new override file.

For example: -v C:\override\requestfileoverride.xml.

--includeComments | -i

Specify whether you want to include comments in the override file. Valid values are true and false. By default, no comments are included in the override file.

After you generate the override file, you can change the parameters in the override file. If you run a service request, you can specify the changed override file, and the runservice script uses the changed parameters to run the service request.

The override files use the same XML namespace as the service requests (http://www.ibm.com/nex/ecore/2.2.0/svc). The root element of the override file is always Overrides. The general format is a nested hierarchy of override groups and attributes derived from the override group and attribute descriptors found within the service request. When the runservice script generates an override template, the group and attribute elements are named by using the override group and attribute descriptor names.
<?xml version=”1.0” encoding=”UTF-8”?>
<svc:Overrides xmlns:svc=”http://www.ibm.com/nex/ecore/2.2.0/svc”>
    <svc:ParentGroup uuid=”...”>
        <svc:ChildGroup uuid=”...”>
            <svc:Attribute1 value=”...” uuid=”...” />
            <svc:Attribute2 value=”...” uuid=”...” />
            <svc:Attribute3 value=”...” uuid=”...” />
            ...
        </svc:ChildGroup>
        ...
    </svc:ParentGroup>
    ...
</svc:Overrides>
The override file must be encoded with UTF-8.

Map file

A map file is a file that the proxy uses to match the JDBC driver in a service request to a JDBC driver on the proxy. If the JDBC driver in a service request matches a line in the map file, the proxy uses the JDBC driver specified on that line. If the JDBC driver in a service request does not match any lines in the map file, the proxy uses the exact JDBC driver specified on the service request. (The proxy can be configured to use a more recent version of the JDBC driver if one exists on the proxy.)

The map file that is used by the runservice script is similar to a standard Java .properties file. Empty lines are ignored. Lines starting with the pound (#) character are treated as comments. All other lines must adhere to the following format:
<regex>=<path>
<regex> is a valid regular expression pattern that is to be used to match the name of a designer-provided .jar name. <path> is a fully qualified path to an actual .jar file on a proxy.
For example, a map file contains the following lines:
db2jcc4.*\.jar=/opt/IBM/sqllib/java/db2jcc4.jar
db2jcc4_license_cu.*\.jar=/opt/IBM/sqllib/java/db2jcc4_license_cu.jar
If a service request is set to use the JDBC driver db2jcc4-9.1.jar, the proxy runs the service request with the JDBC driver /opt/IBM/sqllib/java/db2jcc4.jar. If a service request is set to use the JDBC driver db2jcc4_license_cu-9.1.jar, the proxy runs the service request with the JDBC driver /opt/IBM/sqllib/java/db2jcc4_license_cu.jar

Encrypting a password

You can use the runservice script to encrypt a clear-text password in a service request.

runservice {-e|--encryptPassword} password 
--encryptPassword | -e password

The clear-text password that you want to encrypt. Required.

Looking up the start table

You can use the runservice script to display the start table (and other tables) in a service request.

runservice {-a|--startTable} requestfilepath
{-o|--otherTables } {true|false}
--startTable | -a requestfilepath

The complete file path for the exported service request whose start table is to be displayed. Required.

Service request file names are case-sensitive. If the file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

--otherTables | -o

Specify whether the other tables in the service request are to be included in the output. Valid values are true and false. By default, all tables are included.

Displaying a service request

You can use the runservice script to display the information in a service request.

runservice {-d|--displayService} requestfilepath
{-x|--xsltStylesheet} stylesheetpath
--displayService | -d requestfilepath

The complete file path for the exported service request whose information is to be displayed. Required.

Service request file names are case-sensitive. If the file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.

--xsltStylesheet | -x xsltfilepath

The complete file path for the XSLT stylesheet that is to be used to format the service request.

XSLT stylesheet file names are case-sensitive. If the file name contains a space or contains multibyte character set (MBCS) characters, you must enclose the name in double quotation marks.