Format specifiers

Format specifiers indicate how values are displayed or interpreted in the SA CLI environment. You can apply a format specifier to a method parameter, a method return type, the self file, and an object attribute. To indicate a format specifier, append a colon followed by one of the letters shown in the following table.

If a format specifier is indicated for a file or a method return value, a period must precede the file or method name. For method return values that have format specifiers, the leading period is not included.

Summary of format specifiers

Format specifier	Description	Valid object types	Allowed as method parameter?
:n	Name: A string identifying the object. Unique names are preferred, but not required. For objects that do not have a name, this representation is the same as the ID representation.	SA objects	Yes. If the name is ambiguous, an error occurs.
:i	ID: A format that uniquely identifies the object type and its SA ID. Also known as an object reference.	SA objects; Dates (java.util. Calendar) objects	Yes. If the type is clear from the context, the type may be omitted.
:s	Structure: A compact representation intended for specifying complex values on the command-line. Attributes are enclosed in curly braces.	Any complex object	Yes
:d	Directory: Represents an attribute as a directory in the OGFS.	Any complex object that is an attribute. This representation cannot be used for method parameters or return values.	No

Position of format specifiers

A format specifier immediately follows the item it affects. For files, a format specifier follows the file name. In the following example, note the leading period:

cat .self:s

When applied to a method return type, a format specifier follows the method name. The following invocation displays the IDs of the groups returned:

./.getDeviceGroups:i

With method parameters, a format specifier follows the parameter name and precedes the equal sign, as in the following example:

./setCustomer self:i=9977 customer:i=239

A method parameter with a format specifier does not have a leading period.

Default format specifiers

Every value or object has a default format specifier. For example, the name format specifier is the default for the osVersion attribute. The following two cat commands generate the same output:

cd /opsw/Server/@/d04.example.com/attr
cat osVersion
cat .osVersion:n

The name format specifier is the default for SA objects stored in the Model Repository, such as servers and customers. The structure format specifier is the default for other complex objects.

Examples of ID format specifier

The next example displays the ID of the facility that the d04.example.com server belongs to:

cd /opsw/Server/@/d04.example.com/attr
cat .facility:i ; echo

(The preceding echo command is optional. It generates a new-line character, which makes the output easier to read. The semicolon separates bash statements entered on the same line.)

The output of a value with the ID format specifier is prefixed by the Java class name. For example, if the facility value has an ID of 39, then the previous cat command displays the following output:

com.opsware.locality.FacilityRef:39

The following invocation of the getDeviceGroups method lists the IDs of the public server groups that d04.example.com belongs to:

cd /opsw/Server/@/d04.example.com/method
./.getDeviceGroups:i

For more ID format examples, see The self file.

Structure format specifier syntax

The structure format represents complex objects, which can contain various attributes. You might use this format to specify a method parameter that is a complex object. For examples, see Complex objects and arrays as parameters.

The structure format is a series of name-value pairs, separated by white space characters, enclosed in curly braces. Each name-value pair represents an attribute. The structure format has the following syntax:

{ name-1=value-1 name-2=value-2 . . . }

Here’s a simple example:

{ version=10.1.3 isCurrent=true }

Any white space character can be used as a delimiter:

{
	version=10.1.3
	isCurrent=true	
}

Attributes can be specified as structures, enabling the representation of nested objects. In the following example, the versionDesc attribute is represented as a structure:

{
program=agent
versionDesc={
		version=10.1.3
		isCurrent=true
		comment="Latest version"	
		}
}

To specify an array within a structure, repeat the attribute name. The following structure contains an array named steps that has three elements with the values 33, 14, and 28.

{ moduleName="Some Initiator" steps=33 steps=14 steps=28 }

Examples of structure format specifier

The following example specifies the structure format for the facility attribute:

cd /opsw/Server/@/d04.example.com/attr
cat .facility:s

This cat command generates the following output. Note that customers is an array, which contains an element for every customer associated with this facility.

{
	modifiedBy="192.168.9.246"
	customers="Customer Independent"
	customers="Not Assigned"
	customers="Opsware Inc."
	customers="Acme Inc."
	. . .
	ontogeny="PROD"
	createdBy=
	status="ACTIVE"
	createdDt=-1
	realms="Transitional"
	realms="C39"
	realms="C39-agents"
	modifiedDt=1146528752000
	name="C39"
	displayName="C39"	
}

The following invocation of getDeviceGroups indicates the structure format specifier for the return value:

cd /opsw/Server/@/d04.example.com/method
./.getDeviceGroups:s

This call to getDeviceGroups displays the following output. Because d04.example.com belongs to two server groups, the output includes two structures. In each structure, the devices array has elements for the servers belonging to that group.

{
	dynamic=true
	devices="m302-w2k-vm1.dev.example.com"
	devices="d04.example.com"
	. . .
	status="ACTIVE"
	34 Chapter 2
	public=true
	fullName="Device Groups Public All Windows Servers"
	description="test"
	createdDt=-1
	modifiedDt=1142019861000
	parent="Public"
}
{
	dynamic=true
	devices="opsware-nibwp.build.example.com"
	devices="glengarriff.snv1.dev.example.com"
	devices="millstreet"
	. . .
	fullName="Device Groups Public z_testsrvgroup"
	. . .
}

The structure format specifier is the default for methods that retrieve value objects (VOs). For example, the following two calls to getServerVO are equivalent:

cd /opsw/Server/@/d04.example.com/method
./.getServerVO:s./getServerVO

In this example, getServerVO displays the following output:

{
	managementIP="192.168.198.93"
	modifiedBy=
	manufacturer="DELL COMPUTER CORPORATION"
	use="UNKNOWN"
	discoveredDate=1145308867000
	origin="ASSIMILATED"
	osSPVersion="RTM"
	locale="English_United States.1252"
	reporting=false		
	netBIOSName=
	previousSWReg=1147678609000
	osFlavor="Windows Server 2003, Standard Edition"
	peerIP="192.168.198.93"
	modifiedDt=1145308868000
	. . .
	serialNumber="HVKZS51"
}

This structure represents the ServerVO class of the SA API. Every attribute in this structure corresponds to a file in the attr directory. In the next example, the getServerVO and cat commands both display the value of the serialNumber attribute of a server:

cd /opsw/Server/@/d04.example.com
./method/getServerVO | grep serialNumber
cat attr/serialNumber ; echo

Examples of directory format specifier

The following command changes the current working directory to the customer associated with the server d04.example.com:

cd /opsw/Server/@/d04.example.com/attr/.customer:d

The next command lists the name of this customer:

cat /opsw/Server/@/d04.example.com/attr/\
.customer:d/attr/name

The directory specifier can be used only in command arguments that require directory names. The following cat command fails because it attempts to display a directory:

cat /opsw/Server/@/d04.example.com/attr/.customer:d # WRONG!

However, the next command is legal:

ls /opsw/Server/@/d04.example.com/attr/.customer:d