`<do>`

A <do> clause within a <dynamic> provides the ability for <dynamic> variables to be updated when some variable within the scope of the <dynamic> is changed.

Description

<do> clauses are contained within a <dynamic> element and execute a query when variable values are changed, but before the <widget> entities in the <dynamic> are updated in response to the change. This allows <widget> entities within the <dynamic> to populate their values with the most current variable values based on changes in the <do> clause(s). It does this by executing a 1010data query when the variable provided to the onchange_ attribute is altered.

Furthermore, <do> allows you to specify which values from specific cells generated by the query results inside the <do> tags will be assigned to variables defined in a <dynamic>. The values are assigned to variables whose values should change using the valueN_, rowN_, and colN_ attributes, which specify where in the query results a value or values can be located.

Syntax

<dynamic [VAR_TO_TRIGGER_CHANGE] [VAR_TO_CHANGE]>
  <do onchange_="[VAR_TO_TRIGGER_CHANGE]" valueN_="[VAR_TO_CHANGE]" 
   rowN_="[ROW_NUMBER]" colN_="[COL_NUMBER]">
        [1010data_QUERY]
  </do>
</dynamic>

A [1010data_QUERY] may be specified between the opening and closing tags of the <do> clause. The results of the query provide data for the <do> to display.

Attributes

In addition to several built-in attributes, the <do> construct allows for the addition of some number (N) of valueN_, rowN_, and colN_ attributes that are numbered arbitrarily.

name

Specifies a name to identify the <do> clause within the QuickApp.

If a name is not explicitly specified, a system generated name is provided.

onchange_

onchange_ accepts a list of variables, separated by commas, defined within the scope of the <dynamic> that contains the <do> element.

When any of the variables referenced by onchange_ is altered, the <do> is executed.

onsame_

onsame_ accepts a list of variables, separated by commas, defined within the scope of the <dynamic> that contains the <do> element.

When all of the variables referenced by onsame_ remain the same in the current interaction, the <do> is executed.

onsubmit_

Accepts a value that is specified as the submit_ attribute from a button of the form <widget class_="button" type_="submit">.

As of version 10.15, onsubmit_ accepts a list of values, separated by commas.

The <do> clause is executed when the user clicks any button whose value specified as its submit_ attribute appears in the onsubmit_ list.

See the example in the submit button topic for an example. In addition, see Example: Using onsubmit_ with multiple values below.

onerr_

Accepts a string match expression for an error message.

The <do> clause is executed if and only if an untrapped error occurs in the processing of other <do> clauses at or below the same level.

The variable @doerr_ is set to the error message and @errdo_ to the name associated with the <do> clause in which the error occurred.

See Example: Using onerr_ to catch untrapped errors for an example.

(Available as of version 10.15)

action_

The action_ attribute specifies a system action to perform. Each action has a set of attributes that are specific to it. See the individual topic for details about a particular action.

Valid values are:

allocctrl: <do action_="allocctrl"> changes the subprocess allocation strategy used by MDB. (Available as of version 10.25)
See action_="allocctrl" for more information.
api: <do action_="api"> sends a 1010data API transaction.
See action_="api" for more information.
cacheclear: <do action_="cacheclear"> clears the cache after running the associated 1010data query, if specified. If no query is specified, this action simply clears the cache. (Available as of version 10.15)
See action_="cacheclear" for more information.
cachectrl: <do action_="cachectrl"> controls cache behavior and inspects cache statistics. (Available as of version 10.25)
See action_="cachectrl" for more information.
clearcache: <do action_="clearcache"> clears the cache before running the associated 1010data query, if specified. If no query is specified, this action simply clears the cache.
See action_="clearcache" for more information.
compcheck: <do action_="compcheck"> performs a compatibility check on a given 1010data query. (Available as of version 10.27)
See action_="compcheck" for more information.
files: <do action_="files"> retrieves a list of files in a valid FTP directory. (Available as of version 10.25)
See action_="files" for more information.
getdata: <do action_="getdata"> runs the given 1010data query and returns the results.
See action_="getdata" for more information.
getfilter: <do action_="getfilter"> gets the filter, if one exists, for a specified table. (Available as of version 10.23)
See action_="getfilter" for more information.
getquery: <do action_="getquery"> places the Macro Language code of a given query into an XML variable and/or as text into a dynamic variable. (Available as of version 10.23)
See action_="getquery" for more information.
hashdel: <do action_="hashdel"> removes a key/value association from the user-specific private store. (Available as of version 10.23)
See action_="hashdel" for more information.
hashget: <do action_="hashget"> retrieves the value associated with a given key from the user-specific private store. (Available as of version 10.23)
See action_="hashget" for more information.
hashput: <do action_="hashput"> saves a key/value association to the user-specific private store. (Available as of version 10.23)
See action_="hashput" for more information.
limits: <do action_="limits"> sets or inspects system settings. (Available as of version 10.25)
See action_="limits" for more information.
log: <do action_="log"> sends a message to the 1010data system logger. (Available as of version 10.23)
See action_="log" for more information.
password: <do action_="password"> changes a user's 1010data password. (Available as of version 10.29)
See action_="password" for more information.
qqtoqa: <do action_="qqtoqa"> loads a legacy Quick Query and constructs a QuickApp with the same functionality. (Available as of version 10.34)
See action_="qqtoqa" for more information.
query: <do action_="query"> runs the given 1010data query even if no data is retrieved or if the underlying block code has not changed. (Available as of version 10.15)
See action_="query" for more information.
savefile: <do action_="savefile"> saves the results of a 1010data query as a delimited file on the user's FTP account. (Available as of version 10.25)
See action_="savefile" for more information.
saveqa: <do action_="saveqa"> commits changes to the ops of a rendered and potentially modified QuickApp and saves them as a new QuickApp. (Available as of version 10.15)
See action_="saveqa" for more information.
savequery: <do action_="savequery"> expands a given 1010data query and saves the ops resulting from the expansion as a query. (Available as of version 10.23)
See action_="savequery" for more information.
savetable: <do action_="savetable"> executes a given 1010data query and saves the results as a table. (Available as of version 10.23)
See action_="savetable" for more information.
setfilter: <do action_="setfilter"> sets the filter on a specified table. (Available as of version 10.23)
See action_="setfilter" for more information.
syskill: <do action_="syskill"> kills active user sessions. (Available as of prod-9)
See action_="syskill" for more information.
userprofile: <do action_="userprofile"> sets or retrieves user profile data and preferences. (Available as of version 10.29)
See action_="userprofile" for more information.

If no action is specified, the default is getdata.

on_

on_ specifies when the <do> clause should execute.

Valid values are:

change

change accepts a list of variables, separated by commas, defined within the scope of the <dynamic> that contains the <do> element.

When any of the variables referenced by change is altered, the <do> is executed.

The difference between <do on_ "change"/> and <do onchange_/> is that with the on_ attribute, you can specify more than one condition, separated by commas, such as <do on_"render,change(@foo,@bar),submit(baz)"/>. The <do> is executed when any of the specified conditions are true.

explicit

Executes when a full <dynamic> query is submitted, whether or not it is already cached.

implicit

Executes when a transaction refers to it by tag.

init

Specifies that the <do> clause executes only on the initial rendering of the QuickApp.

interact

Specifies that the <do> clause only executes on subsequent interactions.

new

Triggered when a <dynamic> is first loaded/submitted (and cached), but never in any subsequent use of the cached <dynamic> even if it is rerendered.

old

The opposite of on_="new", it is triggered on subsequent reuse of a cached <dynamic>.

render

Executes when <dynamic> is initially called from a QA rendering routine.

This differs from on_="init" which could be executed multiple times when, for example, submitting a <dynamic> query from the GUI; on_="render" will be triggered only once per render. The condition on_="render(target)" is triggered only when rendering to a specific QA target, e.g. render(web) or render(xlsx).

same

same accepts a list of variables, separated by commas, defined within the scope of the <dynamic> that contains the <do> element.

When all of the variables referenced by same remain the same in the current interaction, the <do> is executed.

The difference between <do on_ "same"/> and <do onsame_/> is that with the on_ attribute, you can specify more than one condition, separated by commas, such as <do on_"render,same(@foo,@bar),submit(baz)"/>. The <do> is executed when any of the specified conditions are true.

submit(name)

This form executes when there is a submit to name.

This has the same effect as onsubmit_="name" but it is useful because can be combined with other states, e.g. a <do on_="render,submit(reset)"> that sets up the initial state of a QA could be useful in conjunction with a <widget class_="button" submit_="reset"/>.

Also supported by the on_ attribute is the form <do on_="list,of,states"> which sets up a trigger on any one of a list of dynamic states.

when_

when_ provides a way to conditionally trigger the <do> clause with boolean logic.

For example:

<do onchange_="@var" when_="{@var<>''}"/>

will not trigger the <do> clause if @var is an empty string.

valueN_

Accepts an arbitrary variable name. The value corresponding to the rowN_ and/or colN_ attributes is stored in the variable associated with the valueN_ attribute. N is a string used as an identifier (e.g., value1_).

More than one value may be stored using multiple valueN_ attributes, where N is a unique identifier for each and must correspond to the naming of the associated rowN_ and/or colN_ attributes (e.g., value1_="[VAR]" row1_="[ROW_NUMBER]" col1_="[COLUMN_NUMBER]" valuefoo_="[VAR]" rowfoo_="[ROW_NUMBER]" colfoo_="[COLUMN_NUMBER]", etc.).

If a value_ attribute is specified, but no corresponding row_ and col_ attributes, the variable associated with the value_ attribute is set to the scalar value in the first row of the first column in the result set of the query (or the empty string if there are no rows in the result set).

rowN_

Specifies a row number within the result set of the query. The value corresponding to the rowN_ and/or colN_ attributes is stored in the variable associated with the valueN_ attribute. N is a string used as an identifier (e.g., row1_).

Together, rowN_ and colN_ specify the location of a scalar value within the result set of a query.

Note: If both rowN_ and colN_ are 0, table metadata is saved as a package to the variable associated with the valueN_ attribute. (Available as of version 11.19)

If rowN_ is provided and colN_ is omitted, all the values in the row will be stored as a package in the variable associated with the valueN_ attribute. The keys of the package are the column names in the result set of the query, and the values can be referenced as @[VAR].[COLUMN_NAME].

Note: If the value of rowN_ is 0, column metadata is saved as a package to the variable associated with the valueN_ attribute. (Available as of version 11.19)

More than one row value may be specified using multiple rowN_ attributes, where N is a unique identifier for each. Note that the naming of a particular rowN_ attribute must correspond to the naming of the associated valueN_ and colN_ attributes (e.g., value1_="[VAR]" row1_="[ROW_NUMBER]" col1_="[COLUMN_NUMBER]" valuefoo_="[VAR]" rowfoo_="[ROW_NUMBER]" colfoo_="[COLUMN_NUMBER]", etc.).

If the value of rowN_ is a negative number, the row that number of rows back from the last row is used. (Available as of version 11.19)

colN_

Specifies either a column name or column number within the result set of the query. The value corresponding to the rowN_ and/or colN_ attributes is stored in the variable associated with the valueN_ attribute. N is a string used as an identifier (e.g., col1_).

Together, rowN_ and colN_ specify the location of a scalar value within the result set of a query.

Note: If both rowN_ and colN_ are 0, table metadata is saved as a package to the variable associated with the valueN_ attribute. (Available as of version 11.19)

If colN_ is provided and rowN_ is omitted, all the values of the column will be stored as a list-value in the variable associated with the valueN_ attribute.

Note: If the value of colN_ is 0, a list of the row numbers is saved as a list-value to the variable associated with the valueN_ attribute. (Available as of version 11.19)

More than one column value may be specified using multiple colN_ attributes, where N is a unique identifier for each. Note that the naming of a particular colN_ attribute must correspond to the naming of the associated valueN_ and rowN_ attributes (e.g., value1_="[VAR]" row1_="[ROW_NUMBER]" col1_="[COLUMN_NUMBER]" valuefoo_="[VAR]" rowfoo_="[ROW_NUMBER]" colfoo_="[COLUMN_NUMBER]", etc.).

If the value of colN_ is a negative number, the column that number of columns back from the last column is used. (Available as of version 11.19)

cntN_

Accepts rows or cols, which specifies whether the number of rows or the number of columns in the result set of the query is stored in the variable associated with the valueN_ attribute.

If a cntN_ attribute is specified, any corresponding rowN_ or colN_ attributes are ignored.

tablevalue_

The results of the <do> clause are stored as a table value in the dynamic variable associated with this attribute.

The variable associated with this attribute can be indexed using the following syntax:

@foo.bar provides a list consisting of the values in the column bar
@foo.17 provides a dictionary consisting of the row 17
@foo._cols provides a list of column names
@foo._rows provides the number of rows

See Example: Using the tablevalue_ attribute for an example.

(Available as of prod-9)

base_

The base table to which the <do>'s query will be applied.

insert_

The name of a <block> that contains a query. This block can be used as the query the <do> clause will execute when its conditions are met.

rowlimit_

Increases the maximum number of rows from the default of 1000.

trackvars_

When used within <dynamic>, <do trackvars_="1"> adds environment variables changed in the course of that <do> clause to the list of variables checked in onchange_="..." conditions in subsequent <do> clauses within the same interaction. Ordinarily, the onchange_ condition only tracks variables changed directly by user interaction.

The Second Form of `<do>`

The <do> construct may be used to assign a value to a variable defined in a <dynamic> based on a coordinate in a matrix (i.e., table) that results from a 1010data query. <do> may also be used to create new variables that can hold a single value or all the values in a given row or column. This form uses a slight different syntax than the first form of <do>. The value or values contained by the variable defined in the opening <do> tag may then be accessed by widgets, but cannot be assigned at any level. Here is an example:

<do value_="myvar" row_="1"/>

In the example above, myvar will contain all the variables in the first row of the base table. The values contained within myvar can be accessed via a dot syntax notation, as follows:

value="{@myvar.[COLUMN_NAME]}"

Multiple variables can also be defined within a <do>'s opening tag, using the value[N]_= syntax of the first form, except in this case, instead providing variables defined in the <dynamic> tag, new variables are defined. Here is an example:

<do value1_="myvar1" value2_="myvar2" row1_="1" col1_="store" row2_="2"/>

In the example above, myvar1 contains a single value: that located in the first row of the table under the store column. myvar2 contains all the values in the second row of the table, which can be accessed with the conventional dot syntax.

For an example use-case of the second form of <do>, see Example 2.

Example: First form

In this example, the <do> construct is used to supply values to variables of a small QuickApp that finds and displays the highest and lowest values for any numerical column in a base table. In this example, the QuickApp is built on a table of weather data. However, any table with numerical data can be used.

<note>Here the dynamic environment is established, 
      and the variables are declared</note>

<dynamic base="pub.demo.weather.wunderground.observed_daily" 
 metric="meantempi" highval="50" lowval="-50">

<note>The do clause will run a tabulation that finds the highest and  
      lowest values in a given column whenever the @metric variable 
      changes</note>

  <do onchange_="@metric" value1_="@lowval" row1_="1" col1_="1" 
     value2_="@highval" row2_="1" col2_="2" 
     base_="pub.demo.weather.wunderground.observed_daily">
    <tabu>
      <tcol source="{@metric}" name="lowvalcol" fun="lo"/>
      <tcol source="{@metric}" name="highvalcol" fun="hi"/>
    </tabu>
  </do>

<note>The first widget is a drop-down list of all the available metrics 
      in the base table. Text columns are filtered out.</note> 

  <layout name="layoutone">
    <widget base_="{@base}" class_="dropdown" label_="Metric:" 
     name="getmetrics" value_="@metric">
      <columns full="0"/>
      <sel value="(type='f''i')"/>
      <colord cols="name,label"/>
    </widget>

<note>Two additional widgets display the highest and lowest values based 
      on the results of the tabulation in the do clause</note>

    <layout name="layouttwo">
      <widget class_="field" label_="Lowest Value:" name="lowval" value_="@lowval"/>
      <widget class_="field" label_="Highest Value:" name="highval" value_="@highval"/>
    </layout>
  </layout>
</dynamic>

The QuickApp will display the disparity in values of any given column in the base table.

and

Example: Second form

In this example the drop-down widget provides a way for the user to choose a column that will be used as the comparison point for selecting rows. The variable var, defined in the opening <do> tag, is "packed" with the values of the row specified in the selrow dynamic variable. Rows from the base table will automatically be selected based on the value for the user-selected column and the value located at "{@var.{@column}}". Have fun!

<dynamic selrow="2" column="store" base="pub.demo.retail.item">
  <do base_="pub.demo.retail.item" value_="var" row_="{@selrow}">
    <colord cols="{@column}"/>
  </do>
  <widget base_="{@base}" class_="dropdown" label_="Column:" 
   name="getselval" value_="@column">
    <columns full="0"/>
    <colord cols="name,label"/>
  </widget>
  <widget base_="pub.demo.retail.item" class_="grid" label_="Selection" rowcol_="1" 
   clickable_="transid" value_="@val" selector_="@col" require_="{@column<>''}">
    <sel value="{@column}='{@var.{@column}}'"/>
  </widget>
</dynamic>

Example: Using the `tablevalue_` attribute

The following example illustrates how to store the results of a <do> clause in a table value variable using the tablevalue_ attribute. In this example, the results of the query contained within the <do> clause are saved as a table value in the dynamic variable do_results. The list widget then uses the results in the sku column of the result table to populate the widget using the initlist_ attribute. (The attribute listheight_ is set to 0 so that the list widget has the correct height to accommodate all the items in the list.)

<dynamic do_results="">
  <do base_="pub.demo.retail.item" tablevalue_="@do_results">
    <sel value="date=20120515"/>
    <sel value="store=1"/>
  </do>
  <widget class_="list" initlist_="{@do_results.sku}" 
   listheight_="0"/>
</dynamic>

Example: Using `onsubmit_` with multiple values

The following example illustrates how the onsubmit_ attribute can take a list of values, separated by commas. The list consists of the values of the submit_ attributes from buttons of the form <widget class_="button" type_="submit">. The <do> clause is executed when the user clicks any button whose submit_ attribute appears in the onsubmit_ list.

In this example, the <do> clause sets the variable show_alert to 1, which triggers the alert widget to display the specified notification. The buttons whose submit_ attributes are either this or that will trigger the <do> clause; the button whose submit_ attribute is the_other will not, since it is not in the onsubmit_ list.

<dynamic show_alert="0">
  <do onsubmit_="this,that">
    <set show_alert="1"/>
  </do>   
  <widget class_="button" type_="submit" submit_="this" text_="This"/>
  <widget class_="button" type_="submit" submit_="that" text_="That"/>
  <widget class_="button" type_="submit" submit_="the_other" text_="The Other"/>
  <widget class_="alert" mode_="notification" type_="success" 
   duration_="2" value_="@show_alert" text_="Button pressed!"/>
</dynamic>

Example: Using `onerr_` to catch untrapped errors

The following example uses <do onerr_="*"> to catch any untrapped errors. If the table specified in the field widget does not exist, the <do action_="query"> will result in an untrapped error. In this case, the <do onerr_="*"> is executed and sets the dynamic variable exists to 0, which determines what is displayed in the text widgets, and sets the dynamic variable errmsg to the value of the @doerr_ variable so that the error message can be displayed in the QuickApp.

<dynamic table="default.lonely" exists="0" result="" errmsg="">
  <do onsubmit_="get_info" action_="api" api_="gettab" value_="result">
    <name>{@table}
    </name>
  </do>
  <do>
    <do action_="query" base_="{@table}">
      <set exists="1"/>
    </do>
    <do onerr_="*">
      <set exists="0"/>
      <set errmsg="{@doerr_}"/>
    </do>
  </do>
  <layout arrange_="v">
    <layout>
      <widget class_="field" value_="@table"/>
      <widget class_="text" 
       text_="{if(@exists;'is accessible';'is not accessible')}"/>
      <widget class_="button" text_="Get title" 
       type_="submit" submit_="get_info" disabled_="{~@exists}"/>
    </layout>
    <widget class_="text" text_="{@result..tab['title']}" 
     visible_="{@exists}"/>
    <widget class_="text" text_="{@errmsg}" visible_="{~@exists}"/>
  </layout>
</dynamic>

The following is displayed for a table that exists:

The following is displayed for a table that does not exist:

Example: Using `trackvars_` to illustrate variable interactions

Use trackvars_="1" to have a <do> effectively run on_="init" and onchange_.

<dynamic foo="0" bar="0">
  <do on_="init" trackvars_="1">
    <set foo="1"/>
  </do>
  <do onchange_="foo">
    <set bar="{@bar+1}"/>
  </do>
  <widget class_="button" type_="set" value_="foo" newvalue_="{~@foo}"/>
  <widget class_="scope" refreshon_="1"/>
</dynamic>

Without trackvars_="1", the value of bar on init would still be 0. Note that in the image below it is 1.

<do>

Description

Syntax

Attributes

The Second Form of <do>

Example: First form

Example: Second form

Example: Using the tablevalue_ attribute

Example: Using onsubmit_ with multiple values

Example: Using onerr_ to catch untrapped errors

Example: Using trackvars_ to illustrate variable interactions