Value representation

Because they run in a shell environment (the OGSH), SA CLI methods accept and return data as strings. However, the underlying API methods can accept and return other data types, such as numbers, Booleans, and objects. The sections that follow describe how the OGFS and SA CLI methods represent non-string data types.

SA objects in the OGFS

The SA data model includes objects such as servers, server groups, customers, and facilities. In the OGFS, these objects are represented as directory structures:

/opsw/Customer
/opsw/Facility
/opsw/Group
/opsw/Library
/opsw/Realm
/opsw/Server
. . .

The preceding list is not complete. To see the full list, enter ls /opsw.

Object attributes

The attributes of an SA object are represented by text files in the attr subdirectory. The name of each file matches the name of the attribute. The contents of a file reveals the value of the attribute.

For example, the /opsw/Server/@/buzz.example.com/attr directory contains the following files:

agentVersion
codeset
createdBy
createdDt
customer
defaultGw
36 Chapter 2
description
discoveredDate
facility
hostName
locale
lockInfo
loopbackIP
managementIP
manufacturer
. . .

To display the management IP address of the buzz.example.com server, enter the following commands:

cd /opsw/Server/@/buzz.example.com/attr
cat managementIP ; echo

Custom attributes

Custom attributes are name-value pairs that you can assign to SA objects such as servers. In the OGFS, custom attributes are represented as text files in the CustAttr subdirectory. You can create custom attributes in an OGSH session by creating new text files under CustAttr. The following example creates a custom attribute named MyGreeting, with a value of hello there, on the buzz.example.com server:

cd /opsw/Server/@/buzz.example.com/CustAttr
echo -n "hello there" > MyGreeting

For more examples, see the “Managing Custom Attributes” section in the SA Use section.

The self file

The self file resides in the directory of an SA object such as a server or customer. This file provides access to various representations of the current object, depending on the format specifier. For details, see Format specifiers.

To list the ID of the buzz.example.com server, enter the following commands:

cd /opsw/Server/@/buzz.example.com
cat .self:i ; echo

For a server, the default format specifier is the name. The following commands display the same output:

cat self ; echo
cat .self:n ; echo

The next command lists the attributes of a server in the structure format:

cat .self:s

Primitive values

The following table indicates how primitive values are converted between the API and their string representations in SA CLI methods. Except for Dates, primitive values do not support format specifiers. Dates support ID format specifiers.

Conversion between primitive types and SA CLI Methods

Primitive type	Java equivalent	Output from SA CLI method	Input to SA CLI methods
String	java.lang. String	Character string, presented in the encoding of the current session.	Character string, converted to Unicode from the current session encoding.
Number	byte, short, int, long, float, double; and their object equivalents	Decimal format, not localized. Scientific notation for very large or small values.	Examples - Decimal: 101, 512.34, -104 Hex: 0x1F32, 0x2e40 Octal: 0543 Scientific: 4.3E4, 6.532e-9, 1.945e+02
Boolean	boolean, Boolean	true or false	The string “true” and all mixed-case variants evaluate to true. All other values evaluate to false.
Binary data	byte[], Byte[]	Binary string. No conversion from session encoding.	Binary string. No conversion to session encoding.
Date	java.util. Calendar	Date value. By default, presented in this format: YYYY/MM/DD HH:MM:SS.mmm The time is presented in UTC. If an ID format specifier is indicated, the value is presented as the number of milliseconds since the epoch, in UTC.	Same as output.

Arrays

The representation of array objects depends on whether they are standalone (an array attribute file or a method return value) or contained in the structure of a complex object.

First, standalone array objects are presented according the underlying type, separated by new-line characters. Within an array element, a new-line character is escaped by \n and a back slash by \\.

Array values can be output or input using any representation supported by the underlying type. For example, by default, the getDeviceGroups method lists the groups as names:

All Windows Servers
Servers in Austin
Testing Pool

If you indicate the ID format specifier, (.getDeviceGroups:i) the method displays the IDs of the groups:

com.opsware.device.DeviceGroupRef:15960039
com.opsware.device.DeviceGroupRef:10390039
com.opsware.device.DeviceGroupRef:17380039

Second, an array contained in the structure of a complex object is represented as a set of name-value pairs, using the attribute as the name. The attribute appears multiple times, once for each element in the array. The order in which the attributes appear determine the order of the elements in the array. The following example shows a structure that contains two attributes, a string called subject and a three-element array of numbers called ranks:

{ subject=”my favorites” ranks=17 ranks=44 ranks=24 }

Arrays can also be represented by directories. Within an array directory, each array element has a corresponding file (for primitive types) or subdirectory (for complex types). The name of each entry is the index number of the array element, starting with zero.

For an array that is the attribute of a complex object, you should modify the array by editing its attribute file. This action completely replaces the array with the contents of the edited file.

For an array containing elements that are complex objects, you should modify the array by changing its directory representation. To change an element value, edit the element file. For example, suppose you have an array with five string elements. The ls command lists the elements as follows:

0 1 2 3 4

The following command changes the value of the third element:

echo -n "My new value" > 2