Filtering is the way the request XML packet indicates the object to which the operation will be applied. The request XML filters data using a special <filter> section. A single filter can specify multiple database users, all specified either by ID or by database ID. It also can match multiple databases, specified either by ID, webspace ID, or webspace name.
Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.
<filter> ... </filter>
The filter node is of data type DatabaseFilterType (
database_input.xsd) which has the following graphical presentation:
- The id node is optional. It specifies the ID of a database. Data type: integer.
- The webspace-id node is optional. It specifies the ID of the webspace on which a database is added. Data type: integer.
- The webspace-name node is optional. It specifies the name of the webspace on which a database is added. Data type: string (Unicode).
A packet that retrieves information about databases on webspace MyDomain.com can look as follows:
<packet version="220.127.116.11"> <database> <get-db> <filter> <webspace-name>MyDomain.com</webspace-name> </filter> </get-db> </database> </packet>
If an operation uses filters in a request packet (del-db-user, get-db, get-db-users, get-default-user, del-db, assign-to-subscription), the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet:
- database ID
- webspace name
- webspace ID
- database user ID
It is done so to trace the request parameters in case of an error. Data type: anySimple.
If the filter node is left blank (
<filter/>), the filter-id parameter will hold the ID of the object. The blank filter means that all objects (like databases or database users) are matched by this rule.