Using IOMI Flags

Various IOMI methods support flags. The write methods require that an OMI_TRUSTED_CLIENT flag be set to authenticate write operations. Other methods support flags to expand or filter metadata retrieval requests, or to request optional behaviors. See Summary Table of IOMI Flags for a list of the available flags and the methods for which they are supported.

IOMI flags are specified as numeric constants in the FLAGS parameter of a method call. For example, to specify the OMI_ALL (1) flag in a GetMetadata call, specify the number 1 in the FLAGS parameter. To specify more than one flag, add their numeric values together and specify the sum in the FLAGS parameter. For example, OMI_ALL (1) + OMI_SUCCINCT (2048) = 2049. This flag combination gets all properties for the specified object, excluding properties for which a value has not been defined.

Most flags do not require additional input. When a flag does require additional input, you must supply this input in a special XML element in the OPTIONS parameter. For example, the OMI_XMLSELECT flag, which invokes search criteria to filter the objects retrieved by the GetMetadataObjects method, requires you to specify the search criteria in an <XMLSELECT search="criteria"> element. The GetMetadata method OMI_TEMPLATE flag, which enables you to request additional properties for metadata objects, requires that you submit a string identifying the additional properties in a <TEMPLATES> element. These additional XML elements are submitted in the OPTIONS parameter. See Summary Table of IOMI Options for a list of these special XML elements.

Some methods, like GetMetadata and GetMetadataObjects, support many flags. GetMetadata flags can be used in the GetMetadataObjects method when the OMI_GET_METADATA flag is set. When more than one flag is set, each flag is applied unless a filtering option is used. For example, GetMetadata flags specified in a GetMetadataObjects request retrieve properties only for objects remaining after any <XMLSELECT> criteria have been applied. When search criteria are specified in the INMETADATA parameter of a GetMetadata call to filter the associated objects that are retrieved and the OMI_ALL flag is set, GetMetadata retrieves properties only about associated objects that meet the search criteria.

When a template is used, the properties and any search criteria specified in the template are applied in addition to any properties requested by other GetMetadata parameters.