Query Parameter Reference

This document describes the various parameters supported by the SAP xApp Manufacturing Integration and Intelligence (SAP xMII) Query Objects, as well as techniques for using these parameters within Web script functions.

Common Query Parameters

*Name*	*Description*	*Data Type*	*Default*	*Usage*
Server	Name of the server to use for the query	String	None	This value must refer to a valid server name as defined in the Data Servers Editor.
Mode	Name of the mode (type) to use for the query	String	None	This value must refer to a valid mode name for the specified connector. A mode can refer to a namespace query mode (tagnames for a tag server, or table names for a relational database), a support capability for a specific server, or functional data retrieval modes. Refer to the specific server documentation for details on supported modes.
Method	Name of the method (additional behaviors for a given mode) to use for the query	String	None	Most modes do not utilize this parameter. It is used in many of the statistical query modes in both the Tag and Alarm query types (MIN, MAX, AVG, for example).
RowCount	Maximum number of rows to be returned by the query	Integer	60 or 100	This provides a "limiter" on the number of rows that a given query will return. In addition, certain Tag connectors can use this value to provide "interpolated" data values over a given time interval. Refer to the connector-specific documentation for the impact of this parameter on historical data retrieval. This parameter also controls the maximum number of items that will be returned from namespace queries (tags, tables, columns, etc.).
InlineTransform	The fully qualified URL for the XSLT stylesheet to be used for pre-processing of data returned from a connector	String	None	Once data has been returned from any connector, this parameter may be used to apply a stylesheet to the data in order to manipulate, summarize, alter meta data, or perform required pre-processing before the data is returned to the requester for final processing. It can be used in addition to the Stylesheet parameter which is used to format the data specific to the request device.
Param.1 ... Param.32	Dynamic parameter values that are passed to the connector and inserted into the appropriate locations in the query string or URL	String	None	These parameters provide an alternative to changing other SQL, Alarm, or XML properties at runtime and provide a cleaner mechanism for changing query behaviors dynamically based on filtering or other criteria. They may be set through the applet's QueryObject setParam(int ParamNumber, String value) method. You can also retrieve the current value through the getParam(int ParamNumber) method.
XParamName.1 ... XParamName.16	Dynamic Transform Parameter variable names that are passed to the stylesheet and may be used as variables in the InlineTransform	String	None	These parameters are specific to Inline Transform use. They represent variable names that may be used within the XSL file specified in the InlineTransform parameter. They may be set through the applet's QueryObject setXParamName(int ParamNumber, String value) method. You can also retrieve the current value through the getXParamName(int ParamNumber) method.
XParamValue.1 ... XParamValue.16	Values corresponding to the XParamName above	String	None	These parameters are specific to Inline Transform use. They represent actual values that are substituted at runtime for variable names that may be used within the XSL file specified in the InlineTransform parameter. They may be set through the applet's QueryObject setXParamValue(int ParamNumber, String value) method. You can also retrieve the current value through the getXParamValue(int ParamNumber) method.
NumberFormat	The format used when outputting floating point values	String	0.00	Refer to the table below for NumberFormat symbols and patterns.
DateFormat	The format used when parsing input dates and when outputting date/time values	String	MM/dd/yyyy HH:mm:ss	This parameters controls both the parsing of the StartDate/EndDate parameters on input and the formatting of date values on output. It is essential that, if using the StartDate/EndDate parameters to specify time, that the DateFormat parameter correspond to the same format used in the input strings. Refer to the table below for DateFormat symbols and patterns.
StartDate	Starting date/time for a time-based query	String	None	This value is a string, in the date format specified in the DateFormat parameters, that indicates the beginning of a time interval to be used in a query.
EndDate	Ending date/time for a time-based query	String	None	This value is a string, in the date format specified in the DateFormat parameters, that indicates the end of a time interval to be used in a query.
Duration	Number of time units to be used in calculating relative time intervals	Integer	60	When used in tandem with the DurationUnits, StartDate, EndDate, and Time parameters, this parameter is used to calculate the range of date/times for a query.
DurationUnits	Specifies the time units that will be applied to the Duration property when calculating relative time intervals	String	M (Minutes)	Valid values are S, M, H, and D, corresponding to seconds, minutes, hours, and days, respectively.
CacheDuration	Number of time units to be used for caching query results	Integer	0	Used in conjunction with the CacheDurationUnits parameter to determine how long the cached query results will be used before they expire and need updating.
CacheDurationUnits	Specifies the time units that will be applied to the CacheDuration property when retaining cached query results	String	M (Minutes)	Valid values are S, M, H, and D, corresponding to seconds, minutes, hours, and days, respectively.
IsCachable	Used to Enable or Disable query caching.	Boolean	false	When set to true this parameter enables query caching for the associated query template and will use the CacheDuration and CacheDurationUnits parameters for cached results retention.
Time	Alternative means for specifying the starting date/time for a time-based query	String	None	This value is a string, beginning with the "day" indicator, followed by the @ character (also known as the "at sign"), followed by the time in military/24 hour format, including hours, minutes and seconds. The value of the day indicator can include: Today, Yesterday, Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. Samples would be: Today@08:00:00 (today at 8 AM), Thursday@16:15:00 (Thursday at 4:15 PM). When using a day-of-the-week indicator, the system will typically provide the "last" day, except in the case where the day-of-the-week matches the current day, in which case it first looks at the start time to determine whether to use the current date or a week prior.
TimePeriod	Alternative means for specifying the starting date/time and duration for a time-based query	String	None	This value must correspond to a user-defined "TimePeriod" as configured using the Time Intervals editor. A time period encapsulates the Time, Duration, and DurationUnits parameters into a single entity, which is stored and defined centrally on the Web server, and can be changed without requiring modification to HTML links/queries.
Schedule	Alternative means for specifying the starting date/time and duration for a time-based query	String	None	This value must correspond to a user-defined "Schedule" as configured using the Time Period Schedules editor. A Schedule encapsulates an ordered series of user-defined "TimePeriods" into a single entity, which is stored and defined centrally on the Web server, and can be changed without requiring modification to HTML links/queries. The system defined TimePeriods 'CurrentShift' and 'PreviousShift' (default is CurrentShift) can be used to cycle through the Time Periods defined in the Schedule. A specific TimePeriod that has been defined in the schedule can also be referenced by name.
AllowFuture	Used to allow or prevent query dates from going into the future	Boolean	true	This value can be used to clamp the EndDate of a given query to the Webserver's current time. When this parameter is set to false, and using a known StartDate with no available EndDate and an appropriate Duration, a query can be forced to have the EndDate set to now.
IntervalCount	The number of time intervals to be used when performing repetitive queries for a range of time intervals	Integer	1	A time range can be divided automatically into evenly spaced interval for statistical analysis. For example, suppose that a query uses a date range of 24 hours, and the IntervalCount parameter is set to 12. In this scenario, 12 sets of values would be returned, each based on a two hour time interval. Note: This parameter only applies to Tag connectors that support Statistics mode.

Parameters Common To Tag and SQL Query Types

Wildcard character	Description	Example
%	Any string of zero or more characters.	WHERE title LIKE %computer% finds all book titles with the word computer anywhere in the book title.
_ (underscore)	Any single character.	WHERE au_fname LIKE _ean finds all four-letter first names that end with ean (Dean, Sean, and so on).
[ ]	Any single character within the specified range ([a-f]) or set ([abcdef]).	WHERE au_lname LIKE [C-P]arsen finds author last names ending with arsen and beginning with any single character between C and P, for example Carsen, Larsen, Karsen, and so on.
[^]	Any single character not within the specified range ([^a-f]) or set ([^abcdef]).	WHERE au_lname LIKE de[^l]% all author last names beginning with de and where the following letter is not l.

Wildcard character

Description

Example

Any string of zero or more characters.

WHERE title LIKE %computer% finds all book titles with the word computer anywhere in the book title.

_ (underscore)

Any single character.

WHERE au_fname LIKE _ean finds all four-letter first names that end with ean (Dean, Sean, and so on).

[ ]

Any single character within the specified range ([a-f]) or set ([abcdef]).

WHERE au_lname LIKE [C-P]arsen finds author last names ending with arsen and beginning with any single character between C and P, for example Carsen, Larsen, Karsen, and so on.

[^]

Any single character not within the specified range ([^a-f]) or set ([^abcdef]).

WHERE au_lname LIKE de[^l]% all author last names beginning with de and where the following letter is not l.

Text: 4 or more pattern letters uses the full form, less then 4 uses the short or abbreviated form if one exists.

Number: The minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of 'y' is 2, the year will be truncated to 2 digits.

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not embraced within single quotes.

Format	Pattern Result
"yyyy.MM.dd G 'at' hh:mm:ss z"	1996.07.10 AD at 15:08:56 PDT
"EEE, MMM d, ''yy"	Wed, July 10, '96
"h:mm a"	12:08 PM
"hh 'o''clock' a, zzzz"	12 o'clock PM, Pacific Daylight Time
"K:mm a, z"	0:00 PM, PST
"yyyyy.MMMMM.dd GGG hh:mm aaa"	1996.July.10 AD 12:08 PM

Format

Pattern Result

"yyyy.MM.dd G 'at' hh:mm:ss z"

1996.07.10 AD at 15:08:56 PDT

"EEE, MMM d, ''yy"

Wed, July 10, '96

"h:mm a"

12:08 PM

"hh 'o''clock' a, zzzz"

12 o'clock PM, Pacific Daylight Time

"K:mm a, z"

0:00 PM, PST

"yyyyy.MMMMM.dd GGG hh:mm aaa"

1996.July.10 AD 12:08 PM

Example Date/Time Formats

Example Number Formats

0.00;(0.00) = display values with two decimal places, and surround negative values with parentheses (the semicolon character delimits the formatting for positive and negative values)

#,##0 PSI = display values with a no decimal places, a comma as a thousands separator and the text " PSI" following the value

Symbol	Meaning
0	A digit
#	A digit, zero shows as absent
.	Placeholder for decimal separator
,	Placeholder for grouping separator
-	Default negative prefix
%	Multiply by 100 and show as percentage
?	Multiply by 1000 and show as per mille
¤	Currency sign. Will be replaced by currency symbol; if doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator
X	Any other characters can be used in the prefix or suffix
'	Used to quote special characters in a prefix or suffix

*Name*	*Description*	*Data Type*	*Default*	*Usage*
TagName	One or more tag names to be queried	String Or String List	None	The name of a tag in the underlying data source. This parameter can be repeated multiple times in a URL if multiple tags are to be queried, and multiple tags can be passed in a single parameter as a comma-separated list of tag names. Note: This parameter can only be used in URL-based queries.
TagName.1 ... TagName.128	A tag name to be queried	String	None	The name of a tag in the underlying data source to query. There are a maximum of 128 tag names in a single query. This is the parameter used by the applets when querying the server, and can also be used in URL-based queries.
TagValue.1 ... TagValue.128	Tag value corresponding to the TagName above	String	None	The value of the tag to be written to the underlying tag data source. The indexed TagValue must correspond to the same TagName index.
Resolution	Time interval in seconds between data retrieved for a "History" query	Integer	0	This parameter is used to provide retrieval resolution for interpolated values when performing a "History" query. The default of 0 provides an automatic setting allowing for the even sampling between the StartDate and EndDate, taking into consideration the RowCount of the query. Note: Not all data sources support this capability, and this parameter has no effect on a "HistoryEvent" query.
TotalizerFactor	A conversion factor that will be applied to the totalizer (TOT) statistic method	Floating Point	1.0	The area under the curve (effectively a "totalizer" value) can be calculated by multiplying the time-weighted average by the width of the time interval in seconds. However, quite often, the instrument or measurement is in different units (perhaps gallons per minute versus per second), and the TotalizerFactor parameter can be used to perform the correction.

*Name*	*Description*	*Data Type*	*Default*	*Usage*
Tables	The list of tables to be used in constructing the SQL query Applies to "Query" Mode	String List	None	A list containing one or more database tables or views to be used in the SQL query. An example might be: Lot,QC
Columns	The list of columns to be used in constructing the SQL query Applies to "Query" Mode	String List	None	A list containing one or more database columns to be used in the SQL query. These column names can also include table qualifiers, aggregate functions, column aliases, and so on. An example might be: Lot.MaterialCode,QC.State,SUM(Inventory) As TotalQty
JoinExpr	The "static" portion of the SQL where clause, which typically does not change and would include table relations Applies to "Query" Mode	String	None	This value is a string containing a SQL "WHERE clause" expression. The "WHERE" keyword should not be included, as it will automatically be inserted. This parameter is optional and need not be utilized. An example might be: (Lot.ID = QC.ID) AND (QC.State = 'Released')
FilterExpr	The "dynamic" portion of the SQL where clause, which might be modified at runtime to change the subset of data being queried Applies to "Query" Mode	String	None	This value is a string containing a SQL "WHERE clause" expression. The "WHERE" keyword should not be included, as it will be inserted automatically. This parameter is optional and need not be utilized. Lot.MaterialCode LIKE 'URANIUM%' AND Inventory > 0
SortExpr	The "order by" portion of the SQL statement that controls record ordering Applies to "Query" Mode	String List	None	This value is a string containing a SQL "ORDER BY" expression. The "ORDER BY" keywords should not be included, as they will be inserted automatically. This parameter is optional and need not be utilized. This parameter contains a comma-separated list of column names (and optional sort order indicator : ASC or DESC). An example might be: Lot.ID ASC,TotalQty DESC
GroupingExpr	The "group by" portion of the SQL statement that controls record ordering Applies to "Query" Mode	String List	None	This value is a string containing a SQL "GROUP BY" expression. The "GROUP BY" keywords should not be included, as they will be inserted automatically. This parameter is optional and need not be utilized. This parameter contains a comma-separated list of column names and is used in tandem with aggregate functions in the Columns parameter. An example might be: Lot.MaterialCode,QC.State
DateColumn	Specifies the name of a database column that can be used when constructing the "Where" clause for date-sensitive queries	String	None	This value is a string containing the name of a database column that, when provided, will enable the query to automatically append the appropriate SQL syntax to specify a date range as requested in the date-oriented query parameters. This is a VERY powerful capability and dramatically reduces the effort needed to create dynamic, time-oriented queries. This information is used along with system configuration information for a particular data server, such as InternalDateFormat, DatePrefix, and DateSuffix, to construct the appropriate SQL expression to limit records to a specific date range.
Query	Provides the SQL statement to be executed Applies to "FixedQuery", "FixedQueryWithOutput", or "Command" Mode	String	None	This value contains the complete SQL statement to be executed. This could be an SQL query, and SQL DDL statement, or an SQL update/insert/delete statement. It could also be a call to a stored procedure that may or may not return data. A few examples might be: SELECT territory,SUM(sales) FROM salesresults WHERE productcode = 'Shoes' GROUP BY territory EXEC sp_InventoryReceive 'Sneakers','LOT001',1200 EXEC sp_InventoryPurge
QueryParams	Provides parameters to be used when executing stored procedures Applies to "FixedQuery", "FixedQueryWithOutput", or "Command" Mode	String List	None	This value contains parameters that will be appended to the Query parameter when constructing the SQL statement. This is generally only applicable when the Query parameter includes a call to a stored procedure. An example (perhaps used in tandem with example #3 in the Query parameter section) might be: 'Shoes','3-25-2000'

*Name*	*Description*	*Data Type*	*Default*	*Usage*
SourceTemplate.1 ... SourceTemplate.32	Fully qualified template name to be used by the aggregate query object	String	None	Up to 32 query templates can be mapped into an aggregate query in the following format: Directory/TemplateName Example: UserTemplates/LineSpeedQuery
SourceName.1 ... SourceName.32	User defined template alias to the corresponding SourceTemplate	Sting	None	Named alias used to reference the underlying query template and configure Mapped Parameters Example: PlantLineSpeeds
MappedParamSource.1 ... MappedParamSource.32	Aggregate query parameter name to be mapped to the source template(s)	String	None	Query Parameter from the Aggregate Query object to be applied to the MappedParamTarget in the underlying template alias Example: Param.1
MappedParamTarget.1 ... MappedParamTarget.32	Query parameter in the underlying Source Template(s) to map the corresponding MappedParamSource parameter	String	None	Uses the following format, where an asterisk () is used to map the parameter to all associated SourceTemplates: SourceName.QueryParameter Examples: .StartDate, PlantLineSpeeds.Duration

*Name*	*Description*	*Data Type*	*Default*	*Usage*
Cube	This is the name of the cube to be used for namespace queries	String	None	Used for namespace queries
Query	This is the MDX expression that is to be executed.	Sting	None	Required for data retrieval
NullAsZero	This is a boolean flag to indicate if null numeric values should be replaced with zeros.	Boolean	false	If false, nulls are replaced with the minimum value for the data type in the Java language (for instance, the minimum value for a Double is 4.9e-324)
ColumnAlias.1 ... ColumnAlias.128	These parameters are used, if supplied, as returning column names.	String	None	This is similar to using a "select column as alias" statement in ANSI SQL

Query Parameter Reference

Common Query Parameters

Parameters Common To Tag and SQL Query Types

Example Date/Time Formats

Example Number Formats

Parameters Specific To Tag Queries

Parameters Specific To SQL Queries

Parameters Specific To Alarm Queries

Parameters Specific To XML Queries

Parameters Specific To Aggregate Queries

Parameters Specific To Xacute Queries

Parameters Specific To OLAP Queries