)
...: ])
NOTE: builtin.echo called with 1 parameters.
NOTE: parameter 1: list = {'item1', 'item2',
{key1 = 'value1',
key2 = {value2 = {0, 1, 1, 2, 3}}}}
The SWAT package also includes a utility function called vl (for “value list”). This function returns an enhanced type of dictionary that enables you to build nested structures quickly and easily. It can be used directly in place of the dict call in the preceding code in its simplest form, but it can also be used outside of the action to build up parameter lists before the action call.
The primary feature of the dictionary object that vl returns is that it automatically adds any key to the dictionary when the key is accessed. For example, the following code builds the same nested structure that the previous example does.
In [16]: params = swat.vl()
In [17]: params.list[0] = 'item1'
In [18]: params.list[1] = 'item2'
In [19]: params.list[2].key1 = 'value1'
In [20]: params.list[2].key2.value2 = [0, 1, 1, 2, 3]
In [21]: params
Out[21]:
{'list': {0: 'item1',
1: 'item2',
2: {'key1': 'value1', 'key2': {'value2': [0, 1, 1, 2, 3]}}}}
As you can see in Out[21], just by accessing the key names and index values as if they existed, the nested parameter structure is automatically created behind the scenes. However, note that this does make it fairly easy to introduce errors into the structure with typographical errors. The object will create key values with mistakes in them since it has no way of telling a good key name from a bad one.
Using the special dictionary returned by vl does create some structures that might be surprising. If you look at Out[21], you see that the list parameter, which was a Python list in the previous example, is now a dictionary with integer keys. This discrepancy makes no difference to SWAT. It automatically converts dictionaries with integer keys into Python lists.
Using Python’s ** operator for passing a dictionary as keyword arguments, you see, as follows, that we get the same output from the echo action as we did previously while using the contents of our vl object.
In [22]: out = conn.echo(**params)
NOTE: builtin.echo called with 1 parameters.
NOTE: parameter 1: list = {'item1', 'item2',
{key2 = {value2 = {0, 1, 1, 2, 3}},
key1 = 'value1'}}
In addition to constructing parameters, you can also tear them down using Python syntax. For example, the following code deletes the value2 key of the list[2].key2 parameter.
In [23]: del params.list[2].key2.value2
In [24]: params
Out[24]: {'list': {0: 'item1', 1: 'item2',
2: {'key1': 'value1', 'key2': {}}}}
With the ability to construct CAS action parameters under our belt, there are a couple of features of the CAS parameter processor that can make your life a bit easier. We look at those in the next section.
Automatic Type Casting
So far, we have constructed arguments using either the exact data types expected by the action or the arbitrary parameters in echo. However, the CAS action parameter processor on the server is flexible enough to allow passing in parameters of various types. If possible, those parameters are converted to the proper type before they are used by the action.
The easiest form of type casting to demonstrate is the conversion of strings to numeric values. If an action parameter takes a numeric value, but you pass in a string that contains a numeric representation as its content, the CAS action processor parses out the numeric and sends that value to the action. This behavior can be seen in the following action calls to history, which shows the action call history. The first call uses integers for first and last, but the second call uses strings. In either case, the result is the same due to the automatic conversion on the server side.
# Using integers
In [25]: out = conn.history(first=5, last=7)
NOTE: 5: action session.sessionname / name='py-session-1',
_apptag='UI', _messageLevel='error'; /* (SUCCESS) */
NOTE: 6: action builtins.echo...; /* (SUCCESS) */
NOTE: 7: action builtins.echo...; /* (SUCCESS) */
# Using strings as integer values
In [26]: out = conn.history(first='5', last='7')
NOTE: 5: action session.sessionname / name='py-session-1',
_apptag='UI', _messageLevel='error'; /* (SUCCESS) */
NOTE: 6: action builtins.echo...; /* (SUCCESS) */
NOTE: 7: action builtins.echo...; /* (SUCCESS) */
Although the server can do some conversions between types, it is generally a good idea to use the correct type. There is another type of automatic conversion that adds syntactical enhancement to action calls. This is the conversion of a scalar-valued parameter to a dictionary value. This is described in the next section.
Scalar Parameter to Dictionary Conversion
Many times when using an action parameter that requires a dictionary as an argument, you use only the first key in the dictionary to specify the parameter. For example, the history action takes a parameter called casout. This parameter specifies an output table to put the history information into. The specification for this parameter follows: (You can use conn.history? in IPython to see the parameter definition.)
casout : dict or CASTable, optional
specifies the settings for saving the action history to an
output table.
casout.name : string or CASTable, optional
specifies the name to associate with the table.
casout.caslib : string, optional
specifies the name of the caslib to use.
casout.timestamp : string, optional
specifies the timestamp to apply to the table. Specify
the value in the form that is appropriate for your
session locale.
casout.compress : boolean, optional
when set to True, data compression is applied to the table.
Default: False
casout.replace : boolean, optional
specifies whether to overwrite an existing table with the same
name.
Default: False
... truncated ...
The first key in the casout parameter is name and indicates the name of the CAS table to create. The complete way of specifying this parameter with only the name key follows:
In