SA CLI method parameters and return values

This section discusses the details of method context (instance or static), parameter usage, return values, and exit status.

Method context and the self parameter

In the OGFS, a method resides in multiple locations. The location of a method is related to its context, which is either instance or static.

The method with instance context resides in method directory of a specific SA object. The method invocation does not require the self parameter. The instance of the object affected by the method is implied by the method location. The following example changes the customer of the d04.example.com server:

cd /opsw/Server/@/d04.example.com/method
./setCustomer customer:i=9

A method with static context resides in a single location under /opsw/api. The method invocation requires the self parameter to identify the instance affected by the method. In the following static context example, self:i specifies the ID of the managed server:

cd /opsw/api/com/opsware/server/ServerService/method
./setCustomer self:i=230054 customer:i=9

Passing arguments on the command-line

The command-line arguments are specified as name-value pairs, joined by the equal sign (=). The name-value pairs are separated by one or more white space characters, typically spaces. The names on the command-line match the parameter names of the corresponding Java method in the SA API.

For example, in the SA API, the setCustomField method has the following definition:

public void setCustomField(CustomFieldReference self,
	java.lang.String fieldName, java.lang.String strValue)...

The following SA CLI method example assigns a value to a custom field of the server with ID 3670039:

cd /opsw/api/com/opsware/server/ServerService/method
./setCustomField self:i=3670039 \
fieldName="Service Agreement" strValue="Gold"

Writer’s Note: check the above command by running it (TBD)

As described in the previous section, a method with an instance context does not require the self parameter. The following setCustomField example is equivalent to the preceding example:

cd /opsw/.Server.ID/3670039
./setCustomField \
fieldName="Service Agreement" strValue="Gold"

You can specify the command-line arguments in any order. The following two SA CLI method invocations are equivalent:

./setCustomField fieldName="My Stuff" strValue="abc"
./setCustomField strValue="abc" fieldName="My Stuff"

To specify a null value for a parameter, either omit the parameter or insert a white space after the equal sign. In the following examples, the value of myParam is null:

./someMethod myField="more info" myParam= anotherParam=9834
./someMethod myField="more info"          anotherParam=9834

Specifying the type of a parameter

If a method has an abstract type for a parameter, you must specify the concrete type as well as the value. In the following example, the com.opsware.folder.FolderRef type is required:

cd /opsw/api/com/opsware/folder/FolderService/method
./remove self:i="com.opsware.folder.FolderRef:730555"

If you do not specify the concrete type, the following error message is displayed:

Object type type-name is abstract. Specify a concrete sub-type.

Complex objects and arrays as parameters

To pass an argument that is a complex object, enclose the object’s attributes in curly braces, as shown in Structure format specifier syntax .

The following example creates a public server group named AllMine. The create method has a single parameter, pattern, which encloses the parent and shortName attributes in curly braces. In this example, getPublicRoot returns 2340555, the ID of the top public group.

cd /opsw/api/com/opsware/device/DeviceGroupService/method
./.getPublicRoot:i ; echo
./create “pattern={ parent:i=2340555 shortName=’AllMine’ }”

Specify array parameters by repeating the parameter name, once for each array element. For example, the following invocation of the assign method specifies the first two elements in the array parameter named policies:

cd /opsw/api/com/opsware/swmgmt
cd SoftwarePolicyService/method
./attachPolicies self:i=4220039 \
policies:i=4400335 policies:i=4400942

Overloaded methods

A Java method name is overloaded if multiple methods in the same class have the same name but different parameter lists. With overloaded SA CLI methods, the argument names on the command-line indicate which method to invoke. The setCustomField method, for example, is overloaded to support the setting of different data types. The following two commands invoke different versions of the method:

./setCustomField \
fieldName="Service Agreement" strValue="Gold"
./setCustomField \
fieldName=hmp longValue=2245

Return values

If the API method underlying an SA CLI method returns a value, then the SA CLI method outputs the value to stdout. As with Unix commands, you can redirect a method’s stdout to a file or assign it to an environment variable.

To change the representation of the return value, insert a leading period and append a format specifier to the method name. The following example returns server references as IDs, instead of the default names:

cd /opsw/api/com/opsware/server/ServerService/method
./.findServerRefs:i

If you indicate a format specifier that is incompatible with the method’s return type, the file system responds with an error.

Exit status

Like Unix shell commands, SA CLI methods use the exit status ($?) to indicate the result of the call. An exit status of zero indicates success; a non-zero indicates an error. SA CLI methods output error messages to stderr.

Exit status codes for SA CLI methods

Exit status	Category	Description
0	Success	The method completed successfully.
1	Command-Line Parse Error	The command-line for the method call is malformed and could not be parsed into a set of options (--option[=value]) and parameter values (param=value).
2	Parameter Parse Error	The parameter values could not be parsed into the object types required by the API.
3	API Usage Error	The call failed because of a usage error, such as an invalid parameter value.
4	Access Error	The user does not have permission to perform the operation.
5	Other Error	An error occurred other than those indicated by exit statuses 1- 4.

For example, the following bash script checks the exit status of the getDeviceGroups method:

#!/bin/bash

cd /opsw/Server/@/toro.snv1.corp.example.com/method
./getDeviceGroups
cmnd_exit_status=$?
if [ $cmnd_exit_status -eq 0 ]
then
	echo "The command was successful."
else	
	echo "The command failed."
	echo "Exit status = " $cmnd_exit_status	
fi

An SA CLI method invokes an underlying API method. If the API method throws an exception, the SA CLI method returns a non-zero exit status. When debugging a method call, you might find it helpful to view information about a thrown exception. The
/sys/last-exception file in the OGFS contains the stack trace of an exception thrown by the most recent API call. After this file has been read, the system discards the file contents.