Defining CDS Views with Input Parameters

In the previous lessons, you saw how powerful CDS views are when it comes to doing calculations on the database. Maybe you already asked yourself in how far the consumer of the CDS view can influence the way the calculations are done. Of course the consumer can provide a WHERE clause to perform a selection on the result. But how does that help when you want to choose the target currency for a currency conversion?

CDS views with input parameters close this gap. They allow the consumer of a view to provide additional information when retrieving data from this view. The CDS view in turn evaluates this information and takes it into account when calculating the results. Some possible use cases for parameters are as follows:

• The consumer specifies the target currency of a currency conversion.

• The consumer specifies whether prices are calculated with or without tax.

• The consumer provides a separator that is used when concatenating fields.

• the consumer specifies the language in which translatable text is returned.

Another important motivation for input views are CDS views with aggregations where you want to filter the data that enter the aggregation. If for example you calculate the total revenue and you want to specify a date up to which revenue should be taken into account.

Finally, SQL does not know about mandatory selection criteria. A consumer may provide a WHERE clause or might not. With a mandatory input parameter, the view can force the consumer to provide a necessary selection criterion - for example, a language key, a date or a username.

You define input parameters by adding WITH PARAMETERS after the CDS view entity name. The parameters are then defined in a comma-separated list.

Each input parameter must be typed with an elementary data type. The parameter name and the parameter type are separated by a colon (:). The type of a parameter can be a predefined ABAP dictionary type (in the form abap.<type>(<len>)), or a data element. Structure types, table types or reference types are not allowed.

You can use parameter annotations to provide metadata for parameters.

To access the input parameters Inside the CDS view definition, you have to use prefix $parameters followed by a period sign (.).

You can use an input parameter in the following positions:

• As standalone element in the element list
• As input for a case distinction
• As input for expressions and functions
• On the right-hand side of a condition in a WHERE clause
• On the right-hand side of a filter condition in a path expression

We will now look at some examples here.

The parameter, TargetCurrency, is used directly in the element list. A typical motivation could be that this element is used in a @semantics.amount.currencyCode: annotation for another element.

Here, a parameter is used in a CASE distinction, allowing the consumer to decide whether the free seats or the occupied seats are returned.

In this example, the input parameter TargetCurrency is used as input for a built-in function, namely the currency conversion function. It allows the consumer of a view to specify the currency in which the flight prices are displayed.

In this example, the input parameter Language is used in the filter condition of a path expression. It allows the consumer of the view to specify the language of the text in the element CurrencyName.

In this example, input parameter FirstFlightDate is used in the WHERE condition of the view definition. This establishes a kind of a mandatory selection criterion. The consumer is forced to filter the flights by a minimum flight date.

When you open the Data Preview tool for a CDS view which defines input parameters, you are prompted to enter actual values for these input parameters before you can analyze the result. Note the asterisks sign (*) next to the parameter names, indicating that the parameters are mandatory.

Only entries that are compatible with the parameter type are accepted. But the tool does not perform any further checks.

Hint

When the focus is on an input field, the screen displays the expected type above the input mask.

When you define a new CDS view and use a CDS view with input parameters as data source, you have to supply all input parameters with actual values. Let us have a look at an example:

This CDS view reads from a CDS view that defines four parameters.

The parameters are supplied inside a pair of parentheses that follow the name of the source view. As there is not just one parameter, the parameters are supplied in a comma separated list.

Hint

When you define a CDS view that reads from a CDS view with parameters, you can use code-completion (Ctrl + Space) to insert the full signature of the CDS view.

Each parameter name is followed by a colon sign (:), which serves as parameter assignment operator, and after that the actual value. One option is a literal as actual value. Another, very common option is to "forward" a parameter. This means that the calling view defines a parameter itself and uses it to supply the parameter of its data source. Therefore, the consumer of this view is responsible for supplying the actual value. With this technique, you can hand down information through an entire stack of CDS views.

The syntax for supplying the input parameters of a CDS view in ABAP SQL is very similar to the syntax that you use in CDS. The only difference is the assignment operator: In CDS, it is the colon sign ":" whereas in ABAP SQL the equals sign (=) is used instead.

To provide the actual values you can choose from the following options:

Literals

Depending on the type of the parameter, you can use number literals or text literals as actual values.

Host Variables

Instead of literals you can use ABAP constants or ABAP variables to provide the actual values. As usual in ABAP SQL, host variables and constants have to be escaped with the "at" sign (@). The type has to be compatible with the parameter type. In particular, only elementary ABAP data objects are allowed.

Host Expressions

You can even embed entire ABAP expressions in the ABAP SQL statement and use the result as actual value for a view parameter. These host expressions have to be surrounded by a pair of parentheses and prefixed with the "at" sign ( @). Note, that blanks are mandatory after the opening parenthesis and before the closing parenthesis. The expression has to have an elementary result and the type has to be compatible with the parameter type.

The ABAP runtime maintains various system fields that hold information of general interest: the system date and time, the logon client and language, the user name of the current user, and so on. When you want to use the values of these system fields in CDS entities, the recommended way is as follows:

1. In your CDS view, define input parameters with a type that matches the type of the system field, for example, a date or a language key.
2. Annotate the parameter with Environment.systemField: and choose the annotation value that is related to the system field you want to access, for example, #SYSTEM_DATE or #SYSTEM_LANGUAGE.

If a parameter is annotated like this, the ABAP runtime will automatically supply the parameter with the value of the related system field, in case no other value is provided by the consumer. As a consequence, you can still supply all parameters as before when you use the view as data source in an ABAP SQL statement. However, the syntax check only forces you to supply the parameters that are NOT linked to a system field. For those parameters that are link to a system field the ABAP runtime uses the value for the related system field as a kind of a default value.

In the example, the two parameters of the CDS view are linked to the system date and the system language. The ABAP code does not supply either of the parameters. Therefore, the ABAP runtime takes the values from the system fields.

Parameters that are linked to ABAP system fields, look very much like optional parameters. However, keep the following in mind: this mechanism only works when accessing the view from within ABAP. In CDS and on database level, the parameters remain mandatory parameters.

Currently the Environment.systemField annotation supports seven different values. The list shows them together with the related system field.

Note

For some of the system fields, direct access is not recommended in ABAP cloud. It is recommended that you use getter methods of ABAP class CL_ABAP_CONTEXT_INFO instead.

When you want to access the values of ABAP system fields in ABAP CDS, it is recommended that you define import parameters and annotate them with @Environment.systemField. An alternative are session variables. This technique does not require the definition of input parameters, which makes it easier to use. But using session variables can cause problems. This is because the session variables only contain values if the reading request comes from an ABAP system. In any other situation, the values of session variables are undefined

If the request does not originate from the ABAP system, the values of the session variables are undefined!

You can uses session variables an many different operand positions. The example uses one session variable in a filter expression, the other in the WHERE clause. The names of the session variables start with prefix $session.. Every session variable is related to a specific ABAP system field.

Currently, ABAP CDS offers six built-in session variables. The list shows them together with the related system field.

Note

In addition to the built-in session variables, there are also application session variables. They are required for specific applications and they are set by dedicated system programs. For details, refer to the ABAP keyword documentation.