Reporting API reference

This section describes reporting-related requests.

All database examples provided in this guide are specific to MySQL. If you use a different database, use syntax that is appropriate for your respective database.

Creates a named filter for a specific table.

Non-global filters are stored by user ID; therefore, the same name can be used by more than one user.

==Required Arguments

tableName

Description: A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

Description: A short string that uniquely identifies the filter.

filterQuery

Description: A SQL order by clause for the associated table.

==Optional Arguments

global

Description: Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

order

Description: A SQL order by clause. Used to specify ordering for the query result set.

==Syntax

cmtool createFilter <tableName> <filterName> <filterQuery> [optionals...]

==Example

cmtool createFilter ec_agents linuxAgents ""platform = ’linux’" --global true

Creates a global filter that selects Linux agents only.

Deletes a named filter for a specific table.

==Required Arguments

tableName

Description: A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

Description: A short string that uniquely identifies the filter.

==Optional Arguments

global

Description: Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

==Syntax

cmtool deleteFilter <tableName> <filterName> [optionals...]

==Example

cmtool deleteFilter ec_agents linuxAgents --global true

Retrieves information about the current resource load.

==Required Arguments

None

==Optional Arguments

None

==Result Tags

agentsAvailable

Description: The total number of active agents in the cluster.

agentClusterShortage

Description: The difference between the maximum number of agents requested by all builds and the number of agents that were assigned.

agentDemand

Description: The total maximum number of requests for agents by all running builds.

agentLicenseShortage

Description: The difference between the maximum request for agents by all builds and the number of agents the license allows.

agentsInUse

Description: The total number of agents assigned to builds.

buildsDuration

Description: The average amount of time the current builds have been running.

buildsRunning

Description: Average number of simultaneous builds running during a specific time period.

createTime

Description: The time when the item was created.

duration

Description: The number of milli-seconds the build has been running.

resourceName

Description: This name is used on the eMake parameter: --emake-resource, and can be specified in a build class. It is used in the ea_resource table and also matches the resource requirement string for eMake.

resourceStatId

Description: The resource ID number that uniquely identifies every resource.

==Example

cmtool getCurrentServerLoad

Retrieves a named filter for a specific table.

==Required Arguments

tableName

Description: A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

Description: A short string that uniquely identifies the filter.

==Optional Arguments

global

Description: Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

==Syntax

cmtool getFilter <tableName> <filterName> [optionals...]

==Example

cmtool getFilter ec_agent agentFilter

Retrieves a list of saved filters for the current user.

==Required Arguments

None

==Optional Arguments

filter

Description: The query to use to limit the result set. For a list of possible SQL values, see the getAgents command.

maxResults

Description: The maximum number of elements to return from a query.

firstResult

Description: The starting index for the query result set. The argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

Description: A SQL order by clause. Used to specify ordering for the query result set.

==Syntax

cmtool getFilters [optionals...]

==Example

cmtool getFilters --filter "table_name = ’ec_agent’ && user_name is null"

Retrieves a list of all global filters for the agent table.

Updates a named filter for a specific table.

==Required Arguments

tableName

Description: A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

Description: A short string that uniquely identifies the filter.

filterQuery

Description: A SQL order by clause for the associated table.

==Optional Arguments

global

Description: Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

order

Description: A SQL order by clause. Used to specify ordering for the query result set.

==Syntax

cmtool modifyFilter <tableName> <filterName> <filterQuery> [optionals...]

==Example

cmtool modifyFilter ec_agent agentFilter "id 750" --order agent_name