webMethods Product Suite  | Complete Installation and Upgrade Information for Software AG Products | Command Central | Command Central Developer Reference | Using the Command Line Interface | Invoking Commands from Scripts | Parameters to Use with the cc Task
 
Parameters to Use with the cc Task
Note: Beginning with Command Central and Platform Manager version 9.5.1, Software AG recommends that you use the inputFormat and outputFormat parameters in place of the format, accept, and mediatype parameters.
The following table lists the parameters you can use with the cc tasks when executing commands on a Command Central server and/or a Platform Manager server.
Parameter and Description
accept
Deprecated. Optional. Use outputFormat in place of accept.
Specifies the format for the returned data. You supply a content type with the accept parameter that is used on the HTTP Accept request header sent to Command Central or Platform Manager. For example:
accept="json"   
accept="xml"   
accept="csv"   
accept="tsv"
If you omit the accept parameter, xml is used.
Note: Use either the accept or the format parameter to specify the format of the returned data. If you specify both, the value you specify with the accept is used.
checkevery
Optional. Specifies the number of seconds the command waits before checking for expected output specified by the expectedvalues parameter. For example:
checkevery="10"
This parameter is only applicable when you also specify the expectedvalues parameter. If you specify the expectedvalues parameter but omit checkevery, the command uses the value of the CC_CHECK_EVERY environment variable. If the CC_CHECK_EVERY environment variable is not set, the command uses 15 seconds.
command
Optional. Specifies a Command Central or Platform Manager command to execute. For example, to execute the following command:
sagcc list landscape nodes
In a script, use the following:
<cc command="sagcc list landscape nodes" />
Another example might be to execute the following command:
sagcc create landscape nodes alias=n1 url=localhost
In a script, use the following:
<cc command="sagcc create landscape nodes alias=n1   
url=localhost" />
Note: Do not include the command options as described in Common Options. Instead use the corresponding attributes listed in this table. For example, if you want to specify the format “json”, use format="json" and not --format json. In other words, to execute:
sagcc create landscape nodes alias=n1 url=localhost --format json
In a script, use the following:
<cc command="sagcc create landscape nodes alias=n1 url=localhost"   
format="json"/>
debug
Optional. Specifies you want extra information returned that you can use for debugging issues, in addition to the returning service output. The extra information includes:
*HTTP service request
*URL of the Command Central or Platform Manager server to which the request was sent
*Request content type
*Accept header for the request
*HTTP response code from the request
*Response content type
*Response content length
error
Optional. Specifies the file for error output. You can specify:
*Absolute directory path and filename. For example:
error="c:\outputs\errors.xml"
*Relative directory path and filename. For example:
error="outputs\errors.json"
*Filename of a file in the same directory where you initiated the script. For example:
output="errors.xml"
If you omit the error parameter, the command output is written to the console.
If you specify both the error and the errorproperty parameters, the command writes the error output to both locations identified by the parameters.
errorproperty
Optional. Specifies the name of a property where you want error output stored if a command fails and failonerror="false". For example:
errorproperty="error.property"
If you specify both the error and the errorproperty parameters, the command writes the error output to both locations identified by the parameters.
expectedvalues
Optional. Specifies the expected values from a command. For example:
expectedvalues="STOPPED"
Use the expectedvalues parameter in conjunction with the checkevery and wait parameters.
Tip: Using wait="0" with expectedvalues acts as s simple assertion mechanism to confirm that the output contains what you expect before executing the next step.
If you omit the expectedvalues parameter, the command completes without expecting a specific value.
If the expected values that you specify do not match the actual values, the build fails and stops.
failonerror
Optional. Specifies whether to fail the entire script if an error occurs executing the command. Specify:
*true if you want the script to fail and stop if an error occurs.
*false if you want the script to continue even if the command fails. If the command fails, the error is written to the file specified with the error property, the errorproperty parameter is set with the command output, and the script can perform additional processing to check the output.
For example:
failonerror="false"
If you omit the failonerror parameter, command uses true.
format
Deprecated. Optional. Use outputFormat in place of format.
Specifies the format you want a command to use for the data it returns. For example:
format="xml"
Command Central and Platform Manager support the following formats:
*Tab-separated values (tsv)
*Plain text (txt)
*XML (xml)
*Comma-separated values (csv)
*JavaScript Object Notation (json)
*ZIP (zip)
*PDF (pdf)
If you omit the format parameter, the command uses xml.
Although Command Central and Platform Manager support these formats, a specific command might only support a subset of the formats. Refer to the documentation for a specific command to determine the exact formats that it supports and to determine the default format for the command.
Note: Not all commands support plain text. If you specify txt for a command that does not support this format, the command uses tsv or xml based on the formats the command supports.
Note: Use either the accept or the format parameter to specify the format of the returned data. If you specify both, the value you specify with the accept is used.
info
Optional. Sets the level of information to log to INFO.
If you omit both the info and quiet attributes, info is used.
input
Required for some actions if inputstring is omitted. Identifies a file that contains the input data for the operation. For example, when creating a new installation, you are required to provide an alias name and URL for the installation. You would supply the alias name and URL in the input data file.
When you specify one of the following actions with the operation or method parameters, specifying input is required. It is not applicable for other actions.
*Operations: POST, CREATE. ADD, PUT, UPDATE, EXEC
*Methods: POST, PUT
Additionally, specifying input is required when using the command parameter if the command you specify requires input.
Supported file types for an input data file are XML (.xml), JavaScript Object Notation (.json), and properties (.properties). Although Command Central and Platform Manager support these formats, a specific command might only support a subset of the formats. Refer to the documentation for a specific command to determine the exact formats that it supports and to determine the default format for the command.
When identifying the input file, you can specify:
*Absolute directory path and filename. For example:
input="c:\templates\input.xml"
*Relative directory path and filename. The path is relative from where you initiated the script. For example:
input="templates\input.xml"
*Filename of a file in the same directory where you initiated the script. For example:
input="input.xml"
inputFormat
Optional. Specifies the content type of the input data for a command. You can specify the same values for inputFormat and ouputFormat.
The default value is taken from the input file extension if the extension matches the short version of a supported media type. If the input file extension does not match the short version of a supported media type, the default is text/plain.
inputstring
Required for some actions if input is omitted. Specifies a string that contains the actual input data for the operation.
When you specify one of the following actions with the operation or method parameters, specifying input is required. It is not applicable for other actions.
*Operations: POST, CREATE. ADD, PUT, UPDATE, EXEC
*Methods: POST, PUT
Additionally, specifying input is required when using the command parameter if the command you specify requires input.
For example, to change the data for the instance with ID “IS-PRIMARYPORT”, for the component with ID “IntegrationServer-instanceName”, running on the node with ID “sag01”, you could use the following:
<cc command="update configuration data sag01   
IntegrationServer-instanceName IS_PRIMARYPORT   
inputstring="valid.instance.id" mediaType="text/plain"   
format="txt" />
Note: Use the inputstring attribute when the input data is simple. For more complex data, use the input attribute.
log
Optional. Specifies the file for log information. Log information is written whether commands are successful or encounter errors.
The logged results include:
*Service output
*Errors that occur while interpreting a command
Note: If the error occurs while the initializing a command, the error is written to the console rather than the file specified with the log parameter
*Debug information if the debug parameter is specified
The log information is written to the console if you do not specify the error or output attributes.
mediatype
Deprecated. Optional. Use inputFormat in place of mediatype. Specifies the content type of the input data for a command.
method
Required if operation is omitted. Use as part of the command parameter. Specifies the operation to execute against a resource. For example:
method="PUT"
Command Central and Platform Manager support the following operations:
*GET to retrieve data.
*POST to add or create a new resource.
*PUT to update data for a resource.
*DELETE to delete a data.
If you omit the method parameter, you must specify the operation parameter to specify the action to execute. Use either the method parameter or the operation parameter, but not both.
operation
Required if method is omitted. Use as part of the command parameter. Specifies the operation to execute against a resource. For example:
operation="LIST"
Command Central and Platform Manager support the following operations:
*GET or LIST to retrieve data.
*POST, CREATE, ADD, or EXEC to add/create a new resource or execute an action against a resource.
*PUT or UPDATE to update data for a resource.
*DELETE or REMOVE to delete data.
*OPTIONS or WADL to retrieve information for supported services.
If you omit the operation parameter, you must specify the method parameter to specify the action to execute. Use either the method parameter or the operation parameter, but not both. If you specify both, the operation parameter is used.
output
Optional. Identifies a file for command output. You can specify:
*Absolute directory path and filename. For example:
output="c:\outputs\results.xml"
*Relative directory path and filename. The path is relative from where you initiated the script. For example:
output="outputs\results.json"
*Filename of a file in the same directory where you initiated the script. For example:
output="results.xml"
If you omit the output parameter, the command output is written to the console.
If you specify both the output and the outputproperty parameters, the command writes the output to both locations identified by the parameters.
outputFormat
Optional. Specifies the format you want a command to use for the data it returns. For example:
outputFormat="xml"
Command Central and Platform Manager support the following formats:
*Tab-separated values (tsv)
*Plain text (txt)
*XML (xml)
*Comma-separated values (csv)
*JavaScript Object Notation (json)
*ZIP (zip)
*PDF (pdf)
The outputFormat parameter accepts any value for the HTTP Accept request header sent to Command Central or Platform Manager.
If you omit the outputFormat, but include an -o option in the command, Platform Manager determines the output format from the file extension. If you include a value for the outputFormat, for example:
sagcc list landscape nodes -p manage -output-format xml -o D:\f.json
Platform Manager uses the outputFormat value, in the example the output format will be XML.
If you omit the outputFormat parameter and do not include an -o option, the command uses xml.
Although Command Central and Platform Manager support these formats, a specific command might only support a subset of the formats. Refer to the documentation for a specific command to determine the exact formats that it supports and to determine the default format for the command.
Note: Not all commands support plain text. If you specify txt for a command that does not support this format, the command uses tsv or xml based on the formats the command supports.
outputproperty
Optional. Specifies an ANT property to hold the result of the command. For example:
outputproperty="output.property"
If you omit the outputproperty, the output is written to the console.
If you specify both the output and the outputproperty parameters, the command writes the output to both locations identified by the parameters.
password
Optional. Specifies the password to use for authentication on the server. For example:
password="secret"
If you omit the {--password | -p} attribute, the command uses the value you specify with the ccsetup task. If you do not specify the password with the ccsetup task, the command uses the CC_PASSWORD environment variable. If the CC_PASSWORD environment variable is not set, the build fails indicating the password is not set.
path
Required if service and resource are omitted. Use as part of the command parameter. Specifies a path that identifies the service and resource on which the command acts. To form the path, separate the service and resource by a forward slash (/) or a space. For example:
path="inventory/components"
or
path="inventory components"
Note: Use either the path parameter or the service and resource parameters to identify the service and resource on which to act.
quiet
Optional. Sets the level of information to log to ERROR.
resource
Required if path is omitted. Use as part of the command parameter. Specifies the resource against which to execute the command. For example:
resource="components"
Examples of resources you can supply are:
*components
*environments
*fixes
*logs
*nodes
*products
When you use the resource parameter, you must also specify the service parameter to identify the service.
Note: Use either the service and resource parameters or the path parameter to identify the service and resource on which to act.
responseCodeProperty
Optional. Specifies an ANT property to hold the response code. For example:
responseCodeProperty="response.property"
*If a command ends successfully, the property you specify will contain a response code that is 400 or less
*If a command ends with an error and failonerror is set to false, the property you specify will contain an error code
retry
Optional. Use only in conjunction with syncJob. Specifies the number of times to resubmit the command when Command Central gets restarted during a command operation and does not respond within the time interval specified in the waitForCC option. If waitForCC is specified with no value, the command uses the value of the CC_WAIT environment variable, or 120 seconds if CC_WAIT is not specified.
For example:
retry="1"
If you do not include retry or you specify retry="0", the command will not be resubmitted.
Use retry, syncJob and waitForCC to execute commands with long-running operations more reliably.
server
Required if omitted from the ccsetup task. Identifies the server on which to execute the command. You can specify either a Command Central or Platform Manager server. For example:
server="http://localhost:8092/spm"
If you omit server from the cc task, the command uses the value you specify with the ccsetup task. If you omit server from both tasks, the command uses http://localhost:8090/cce.
service
Required if path is omitted. Use as part of the command parameter. Specifies the service that provides the resource on which the command acts. For example:
service="inventory"
Examples of services you can supply are:
*configuration
*diagnostics
*inventory
*jobmanager
*landscape
*lifecycle
*monitoring
*resources
When you use the service parameter, you must also specify the resource parameter to identify the resource.
Note: Use either the service and resource parameters or the path parameter to identify the service and resource on which to act.
syncJob
Required if retry is used. When you use this option, Command Central monitors and reports progress details while the job is running, and returns the job status and status description after the job completes. When you omit this option, Command Central does not monitor and report the job progress. To enable job monitoring:
syncJob="true"
Even if waitForCC is not included in your script, specifying syncJob automatically triggers waitForCC. If you use only syncJob and omit waitForCC, the command uses the value of the CC_WAIT environment variable, or 120 seconds if CC_WAIT is not specified.
If you execute a command with syncJob and expectedValues, the result that the command returns is verified against the specified expected values.
Use syncJob, retry and waitForCC to execute commands with long-running operations more reliably. This will ensure that the command is resubmitted in case Command Central is restarted during the operation.
username
Optional. Specifies the user name to use for authentication. For example:
username="Administrator"
The following lists the order used to determine the value used for the user name:
1. Value set with the cc task.
2. Value set with the ccsetup task.
3. Value defined in the CC_USERNAME environment variable.
4. “Administrator”
wait
Optional. Specifies how many seconds to wait for a long-running operation to return the expected values specified by the expectedvalues parameter. For example:
wait="160"
This parameter is only applicable when you also specify the expectedvalues parameter. If you specify the expectedvalues parameter but omit wait, the command uses the value of the CC_WAIT environment variable. If the CC_WAIT environment variable is not set, the command uses 120 seconds.
waitForCC
Optional. Specifies the time interval in seconds the command waits for Command Central to come online after starting or restarting Command Central. If you omit this option, the command fails when Command Central is not online. For example:
waitForCC="60"
Both wait and waitForCC use the value of the CC_WAIT environment variable. Use waitForCC in conjunction with wait if you specify a value for waitForCC higher than 120 seconds. In this case, specify a value for wait higher than the value of waitForCC.
When you monitor a long-running job, you can use waitForCC and syncJob to continue monitoring the job even after Command Central is restarted.
Using waitForCC is most helpful with commands that trigger long-running jobs, for example the apply composite templates command. However, you can use waitForCC with any command.

Copyright © 2007-2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.