Table Of Contents

Device Management Functions

asyncDiscoverDevices

asyncPollDeviceLicenseInfo

createDevicesByIPAddr

createDevicesByUDI

deleteAsyncOperationJobRecords

deleteDevices

getAsyncOperationJobRecords

getAsyncOperationStatus

killAsyncOperation

listAllAsyncOperationJobRecords

listAllDevicesInGroup

listAllGroupsByDevice

listDeviceIdsByFilter

listRunningAsyncOperationJobRecords

readDevices

reCreateDevices

setAsyncOperationJobComment

writeDevices

Device Management Functions

---

This chapter provides information about the following device management functions:

•asyncDiscoverDevices

•asyncPollDeviceLicenseInfo

•createDevicesByIPAddr

•createDevicesByUDI

•deleteAsyncOperationJobRecords

•deleteDevices

•getAsyncOperationJobRecords

•getAsyncOperationStatus

•killAsyncOperation

•listAllAsyncOperationJobRecords

•listAllDevicesInGroup

•listAllGroupsByDevice

•listDeviceIdsByFilter

•listRunningAsyncOperationJobRecords

•readDevices

•reCreateDevices

•setAsyncOperationJobComment

•writeDevices

asyncDiscoverDevices

Synopsis

String asyncDiscoverDevices(UserToken token, String subnet, String subnet_mask, String 
group, DiscoveryAuthInfo dev_auth_info, Device.TransportMethod[] transports, 
IDStatusListener listener) throws RemoteException;

Description

This function generates an inventory of devices that are discovered in the given subnet and adds the devices to the specified device group.

The Cisco License Manager currently supports Cisco IOS Telnet and secure shell (ssh) for non-agent-enabled device discovery, thus prolonging the discovery time. If the network devices are configured the same way, you can provide the transport method (such as HTTP, Telnet, or ssh), which speeds up the discovery and reduces the discovery process time. If a null or empty string array is passed in, Cisco License Manager uses all supported methods to discover the devices.

This function is nonblocking and returns a request ID to the caller immediately. While calling this function, the client program provides a listener object that implements the IDStatusListener interface. When the operation is complete, the onStatus() method in the listener object is invoked.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
subnet	String, mandatory	Network address	The subnet to conduct the auto-discovery.
subnet_mask	String, mandatory	—	The subnet mask.
group	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The group to which the discovered devices should be added.
dev_auth_info	DiscoveryAuthInfo, mandatory	—	A DiscoveryAuthInfo is used when communicating with discovered devices to retrieve license information. If no authentication is needed for the devices in the network, this parameter can be set to null. DiscoveryAuthInfo contains an array of username and password pairs and an array of enable passwords. When Cisco License Manager tries to communicate with the device, the instances of DiscoveryAuthInfo are tried one at a time until they can be authenticated by the device. If Telnet is used, there are only three tries.
listener	IDStatusListener object, mandatory	—	An object that implements the IDStatusListener interface.
transports	Device. TransportMethod array, optional	HTTP, Telnet, ssh	If the devices in a subnet are set up with the same device discovery method, the device discovery process is speeded up because Cisco License Manager uses only the specified method to quickly determine if the device license is supported. This parameter specifies which connection transport is used. Cisco License Manager uses the specified transports by entry order. If null or zero length is entered, Cisco License Manager uses all available methods to discover the device.

Return

This function returns a request ID to the caller. When the operation is complete, the status is provided as the input parameter of the onStatus() method. The listener will receive an IDStatus object whilch contains a list of IDStatusItem objects. Each IDStatusItem object contains the device ID of the discovered devices.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown. The input parameter of the onStatus() method in the IDStatusListener contains the error codes and messages. More than one error code and message may be contained in the IDStatus object. The following example shows the error codes and messages in the onStatus() method:

		public void onStatus(IDStatus status) {

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

			for (int i = 0; i < items.length(); i++) {

				// Get the individual object ID returned by the operation.

				String id = items[i].getID();

				// Get the individual error code corresponding to 

				// the object ID.

				int item_err_code = items[i].getErrorCode();

				// Get the individual error message corresponding to 

				// the object ID.

				String item_err_msg = items[i].getErrorMessage();

			}

		}

asyncPollDeviceLicenseInfo

Synopsis

String asyncPollDeviceLicenseInfo(UserToken token, String[] dev_ids, IDStatusListener 
listener) throws RemoteException;

Description

This function communicates with the given devices, retrieving license information from them and storing the information in the inventory.

This function is nonblocking and returns a request ID to the caller immediately. While calling this function, the client program provides a listener object that implements the IDStatusListener interface. When the operation is complete, the onStatus() method in the listener object is invoked.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.
listener	IDStatusListener object, mandatory	—	An object which implements IDStatusListener interface.

Return

This function returns a request ID to the caller. When the operation is complete, the status is provided as the input parameter of the onStatus() method. The listener will receive IDStatus when the operation is completed. The IDStatus contains the list of IDStatusItem, which includes the device ID and the error code and error message of the individual device poll operation.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown. The input parameter of the onStatus() method in IDStatusListener contains the error codes and messages. More than one error code and message may be contained in the IDStatus object. The following example shows the error codes and messages in the onStatus() method:

		public void onStatus(IDStatus status) {

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

			for (int i = 0; i < items.length(); i++) {

				// Get the individual object ID returned by the operation.

				String id = items[i].getID();

				// Get the individual error code corresponding to 

				// the object ID.

				int item_err_code = items[i].getErrorCode();

				// Get the individual error message corresponding to 

				// the object ID.

				String item_err_msg = items[i].getErrorMessage();

			}

		}

createDevicesByIPAddr

Synopsis

DeviceStatus createDevicesByIPAddr(UserToken token, String[] ips, String group, 
DeviceAuthentication[] dev_auth_info, Device.TransportMethod[] transports) throws Remote 
Exception;

Description

This function creates device objects in the inventory using a given IP address and associates devices with the specified group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
ips	Array of string, mandatory	IP address	An array of IP addresses. Each address is used for creating a device object.
group	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the device group.
dev_auth_info	Array of Device Authentication, mandatory	—	An array of DeviceAuthentication values is used when communicating with discovered devices to retrieve license information. Each entry in the array is used to connect to the IP address in the IP array. DeviceAuthentication contains username, password, and enable password.
transports	Device. TransportMethod array, optional	HTTP, Telnet, ssh	This parameter specifies which connection transport method is used for each IP entry. Cisco License Manager assumes that the caller knows the connection method used for each device.

Return

This function returns DeviceStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			DeviceStatus status = createDevicesByIPAddr(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			DeviceStatusItem[] items = status.getDeviceStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual object returned by the operation.

			Device device = items[i].getDevice();

			// Get the individual error code corresponding to 

			// the object.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the object.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

createDevicesByUDI

Synopsis

DeviceStatus createDevicesByUDI(UserToken token, String[] udis) throws RemoteException;

DeviceStatus createDevicesByUDI(UserToken token, String[] udis, String group) throws 
RemoteException;

Description

This function creates device objects in the inventory using a given unique device identifier (UDI). The second form of the function also adds the created devices to the specified group. If the group is not specified, the device is added to the default group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
udis	Array of string, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	An array of UDIs. Each UDI is used for creating a device object.
group	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the device group.

Return

This function returns DeviceStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			DeviceStatus status = createDevicesByUDI(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			DeviceStatusItem[] items = status.getDeviceStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual object returned by the operation.

			Device device = items[i].getDevice();

			// Get the individual error code corresponding to 

			// the object.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the object.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

---

Note This API can be used for creating a device that contains member devices. The following is an example of API code with a master switch and member switch in a switch stack:

		// Create 3 device objects, where dev_objs[0] is the master switch,

 		// dev_objs[1] is member switch 1 and dev_objs[2] is member switch 2.

		String dev_udi[] = {"MasterSwitch", "MemberSwitch1", "MemberSwitch2"};

		Device[] dev_objs = 

				LicenseManager.createDeviceByUDI(token, dev_ids[]);

		// Associate 2 member switches to their master switch.

		dev_objs[0].member_device_ids = new String[2];

		dev_objs[0].member_device_ids[0] = dev_ids[1];

		dev_objs[0].member_device_ids[1] = dev_ids[2];

		// Write the changes to the data storage.

		LicenseManager.writeDevice(token, dev_ids);

---

deleteAsyncOperationJobRecords

Synopsis

IDStatus deleteAsyncOperationJobRecords(UserToken token, String[] job_ids) throws 
RemoteException;

Description

This function allows you to delete job records that are associated with your username.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
job_ids	Array of string, mandatory	—	Array of Job IDs. Each Job ID is the request ID that is returned from an asynchronous function call.

Return

This function returns an IDStatus object. If the operation is not successful, the IDStatus returns a non ClmErrors.SUCCESS error code. If the operation is successful, the IDStatus contains an IDStatusItem array and each IDStatusItem contains the job ID and the error status of the delete operation.

Error and Exception

When an overall function error occurs, this function returns none ClmErrors.SUCCESS value in the IDStatus. The Job ID and the error code can be retrieved from the IDStatusItem array.

If a system error prevents the operation from completing, a RemoteException is thrown.

deleteDevices

Synopsis

IDStatus deleteDevices(UserToken token, String[] dev_ids) throws RemoteException;

Description

This function deletes device objects from the inventory using the given device IDs. All devices belong to a group. If a device does not belong to a user-defined group, it belongs to the default group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.

Return

This function returns IDStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			IDStatus status = deleteDevices(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual ID returned by the operation.

			String id = items[i].getID();

			// Get the individual error code corresponding to 

			// the ID.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the ID.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.

getAsyncOperationJobRecords

Synopsis

ClmJob getAsyncOperationJobRecords(UserToken token, String job_id) throws RemoteException;

Description

This function returns the ClmJob that is associated with the asynchronous function. The job_id is the request ID returned from the asynchronous call.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
job_id	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	Job ID returned from asynchronous operation.

Return

This function returns ClmJob. If job_id does not exist, this function returns null. Otherwise it returns the ClmJob for the specific job_id.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

getAsyncOperationStatus

Synopsis

ProgressStatus getAsyncOperationStatus(UserToken token, String job_id) throws 
RemoteException;

Description

This function provides information about the progress of an asynchronous function. The job _id is essential to track the progress. If the task_id is not provided, an error in the ProgressStatus is returned.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
job_id	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	Job ID returned from asynchronous operation.

Return

This function returns ProgressStatus, and it includes the overall status indicating if this function has completed successfully or not. The detail of the ProgressStatus contains an array of target IDs and an array of integers indicating the progress of the individual targets (for example, 0 indicates complete, 1 indicates pending, and 2 indicates processing). Also included is a string for the function that is currently being performed and the overall progress percentage.

Error and Exception

When an overall function error occurs, this function returns none 0 in the ProgressStatus. If the asynchronous task is completed, the entry of the task is removed and the overall status returns a task_id not found error. You have to check if the callback has been returned to determine if the task_id that is passed is incorrect.

If a system error prevents the operation from completing, a RemoteException is thrown.

killAsyncOperation

Synopsis

Status killAsyncOperation(UserToken token, String job_id) throws RemoteException;

Description

This function kills the asynchronous operation.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
job_id	String, mandatory	Up to 64 ASCII characters in the range of x21 to x7A	Job ID, which is the same as the request ID, returned from asynchronous operation.

Return

This function returns a Status object.

Error and Exception

When an overall function error occurs, this function returns a none SUCCESS value in Status.

If a system error prevents the operation from completing, a RemoteException is thrown.

listAllAsyncOperationJobRecords

Synopsis

ClmJobStatus listAllAsyncOperationJobRecords(UserToken token, boolean include_all_user) 
throws RemoteException;

Description

This function returns all of the Cisco License Manager jobs that contain information about the asynchronous operation stored in the inventory that you initiated. This function returns all complete, incomplete, and running Cisco License Manager jobs.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
Include_all_user	Boolean, mandatory	True, False	If true, this parameter returns all records. If false, this parameter returns only records with the username.

Return

This function returns a ClmStatus object.

Error and Exception

When an overall function error occurs, this function returns a none SUCCESS value in the ClmJobStatus object. The ClmJob can be retrieved from the ClmJobStatusItem array.

If a system error prevents the operation from completing, a RemoteException is thrown.

listAllDevicesInGroup

Synopsis

String[] listAllDevicesInGroup(UserToken token, String group) throws RemoteException;

Description

This function returns an array of device IDs that belong to the given device group. If the group is null, this function returns an array of device IDs that belong to the default group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
group	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The name of the device group, or null if the function is looking for ungrouped devices.

Return

This function returns an array of device IDs if the group is valid. Otherwise, if the group is invalid or empty, a non-null array of size zero is returned.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown. When an error occurs, this function returns null.

listAllGroupsByDevice

Synopsis

String[] listAllGroupsByDevice(UserToken token, String dev_id) throws RemoteException;

Description

This function returns an array of groups to which the given device belongs.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.

Return

This function returns an array of groups if the device is valid.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs, this function returns null.

listDeviceIdsByFilter

Synopsis

String[] listDeviceIdsByFilter(UserToken token, String device_type, String device_model, 
String[] features) throws RemoteException;

Description

This function returns a list of device IDs that contains the device_type, device_model, and license feature.

Each filter can be set to null for no filtering. If all the filters are set to null, the operation is treated as an error and null is returned.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
device_type	String, optional	—	String that represents device type.
device_model	String, optional	—	String that represents device model.
features	Array of string, optional	—	Array of string that represent the license feature names.

Return

This function returns an array of string. Each string is a device ID.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs, this function returns null. An array length of zero means that no device is found.

listRunningAsyncOperationJobRecords

Synopsis

ClmJobStatus listRunningAsyncOperationJobRecords(UserToken token, boolean 
include_all_user) throws RemoteException;

Description

This function returns all of the Cisco License Manager jobs that contain information about the running asynchronous operations that you initiated.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
Include_all_user	Boolean, mandatory	True, False	If true, this parameter returns all records. If false, this parameter returns only records containing the username.

Return

This function returns a ClmStatus object.

Error and Exception

When an overall function error occurs, this function returns a none SUCCESS value in the ClmJobStatus object. The ClmJob can be retrieved from the ClmJobStatusItem array.

If a system error prevents the operation from completing, a RemoteException is thrown.

readDevices

Synopsis

DeviceStatus readDevices(UserToken token, String[] dev_ids) throws RemoteException;

Description

This function uses the given device ID to retrieve an array of device objects from the inventory.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.

Return

This function returns DeviceStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			DeviceStatus status = readDevices(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			DeviceStatusItem[] items = status.getDeviceStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual object returned by the operation.

			Device device = items[i].getDevice();

			// Get the individual error code corresponding to 

			// the object.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the object.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

reCreateDevices

Synopsis

DeviceStatus reCreateDevices (UserToken token, Devices[] devs, String group, 
DeviceAuthentication[] dev_auth_info, Device.TransportMethod[] transports) throws 
RemoteException;

Description

This function allows the user to modify existing device objects and provides an opportunity to change device authentication information and setting a new transport method. Cisco License Manager tries to reconnect to the device using newly provided information and verifies that the changes are correct.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
devs	Array of Device, mandatory	Device objects	An array of device objects that already exist in the inventory. If the device object does not exist in the inventory, it is created and placed in the inventory.
group	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the device group.
dev_auth_info	Array of DeviceAuthentication, mandatory	—	An array of DeviceAuthentication values is used when communicating with discovered devices to get license information. Each entry in the array is used to connect to the IP address in the IP array. DeviceAuthentication contains username, password, and enable password.
transports	Device. TransportMethod array, mandatory	HTTP, Telnet, ssh	This parameter specifies which connection transport is used for each IP entry. Cisco License Manager assumes that the caller knows the connection method used for each device.

Return

This function returns DeviceStatus objects. The following example shows the error code, error messages, and returned objects in the status:

		DeviceStatus status = reCreateDevices (..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			DeviceStatusItem[] items = status.getDeviceStatusItems()

			// Iterate through the list to get individual status.

	for (int i = 0; i < items.length(); i++) {

		// Get the individual object returned by the operation.

		Device device = items[i].getDevice();

		// Get the individual error code corresponding to 

		// the object.

				int item_err_code = items[i].getErrorCode();

		// Get the individual error message corresponding to 

		// the object.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

setAsyncOperationJobComment

Synopsis

Status setAsyncOperationJobComment(UserToken token, String job_id, String comment) throws 
RemoteException;

Description

This function allows you to set the comment in a job records that are associated with your username.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
job_id	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The Job ID. Each Job ID is the request ID that is returned from an asynchronous function call.
comment	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The comment that describes the job.

Return

This function returns the Status object. If the operation is not successful, Status returns the none ClmErrors.SUCCESS error code.

Error and Exception

When an overall function error occurs, this function returns none ClmErrors.SUCCESS in the Status.

If a system error prevents the operation from completing, a RemoteException is thrown.

writeDevices

Synopsis

IDStatus writeDevices(UserToken token, Device[] devices) throws RemoteException;

Description

This function writes the given device objects into the inventory. The input device objects can be new instances of devices returned by the createDevices() function or existing ones retrieved from the inventory by the readDevices() function.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
devices	Array of devices, mandatory	—	An array of device objects, which can be new instances of a device class or existing ones retrieved from the inventory by the readDevice() function.

Return

This function returns IDStatus objects. The following example shows the error code, error message, and returned objects in the status:

			IDStatus status = writeDevices(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual ID returned by the operation.

			String id = items[i].getID();

			// Get the individual error code corresponding to 

			// the ID.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the ID.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.