Arguments

(1) Dynamically-specified arguments and statically-specified arguments

The arguments which refer to value, they are called dynamically-specified arguments.

The arguments which do not refer to value, they are called statically-specified arguments. If you specify a dynamically-specified argument, the value of the argument changes every time the input data is processed. This applies to cases such as specifying a variable in input settings and matching settings as an argument.

If you specify a statically-specified argument, the value is fixed and will not change upon execution.

This applies to cases where a fixed value, character string ($DSTR), or numeric value ($DNUM) is specified as an argument for the utled command.

(2) Available character strings for arguments

Fixed character strings or reference values can be specified as arguments.

Available reference value is basically the same as the dynamic specification that is used when executing queries to virtual tables.

Table 5.3 Available reference values for arguments

Reference value	Meaning
$VAR	Variable
$INUM	Field number
$INAME	Field name
$DNUM	Numeric value
$DSTR	Character string
$MINUM	Matching number
$RCOUNT	Number of records

(3) Example of argument specification

Multiple arguments can be specified. The following examples show how to specify numeric type and character type as an argument.

Numeric type example

If multiple variables and constants are used with operation symbols, the computed result is used as an argument.

Example:

$INUM(3) + 4 * $DNUM10

 

If $INUM(3) is 2 and $DNUM10 is 3, the result is 14 (= 2 + 4 * 3).

 

Available operators are the operators used in the select statements of SQLite.

Character type example

The variable is replaced with the character string of the variable.

Example:

$INUM(3) + 4 * $DNUM10

 

If $INUM(3) is 2 and $DNUM10 is 3, the result is "2 + 4 * 3".

(4) Availability of arguments in components

If input data is mapped, the mapped data is passed to ARG0 is handed to the common component as an implicit argument.

The implicit argument has the same data type as the field.

If ARG0 to ARG5 are specified in common components and also mapping or specification is omitted, then the default value of each data type is used.

The following shows the availability of arguments in components.

Table 5.4 Availability of arguments in components

Component type	Argument(ARG0)	Arguments (ARG1 to 5)
Date	Cannot be used (#1)	Cannot be used (#1)
Time	Cannot be used (#1)	Cannot be used (#1)
Fixed string	Cannot be used (#1)	Cannot be used (#1)
Fixed numeric character string	Cannot be used (#1)	Cannot be used (#1)
Function	Used as actual data to be processed.	Can be specified as $ARG[1-5]. If dynamic specification is applied to an argument that cannot be dynamically specified, the argument is handled as NULL.
Virtual query	Can be used as $ARG0.	Can be used as $ARG[1-5].
Virtual query (for initial processing)	Can be used as $ARG0. NULL (type M null character) is used when referenced. The value is not inherited even when it is set.	Can be used as $ARG[1-5]. If they are referenced when dynamic specification is used, the reference value part is handled as the initial value of the field type. The value is not inherited even when it is set. Can be referenced if the data type is a static character string. The value is inherited when it is set.
Lua script	Can be used as av0.	Can be used as av[1-5].
Lua script (for initial processing)	Can be used as av0. NULL (type M null character) is used when referenced. The value is not inherited even when it is set.	Can be used as av[1-5]. If they are referenced when dynamic specification is applied, the reference value part is handled as the initial value of the field. The value is not inherited even when it is set. Can be referenced if the data type is a static character string. The value is inherited when it is set.

#1

:

When you specify this field, the specified value is recognized not as an argument but as a character string. (Example: If you specify $ARG0, it is processed as a character string $ARG0.)

 

You can specify ARG[1-5] for the arguments of a function; however, if ARG[1-5] is reference value, such as $INUM, the arguments are checked whether the function can accept reference values. If the function cannot accept reference values, an error will occur.

The reference values can be used in the following functions.

• COALESCE

• CALC_MONTHS

• IF

(5) Components for initial processing

In virtual queries and Lua scripts, there is processing that can be executed only once before the actual processing. Components that execute such processing are called components for initial processing. The purpose of components for initial processing is shown as follows.

Table 5.5 Components for initial processing

Component Type	Purpose	Examples of use
Lua script (for initial processing)	To apply special processing to the arguments (ARG1 to 5). The processing result is used as new arguments.	Obtains, calculates, and formats today's date to use for arguments. Obtains an environment variable and uses its value as an argument. Creates a currency exchange rate that is not fluctuated inside data processing, and uses it as an argument.
	To perform initial processing for a user of DataMagic.	Outputs message to the standard output. Sets environment variables
Virtual query (for initial processing)	To apply special processing to the arguments (ARG1 to 5). The processing result is used as new arguments.	Obtains, calculates, and formats today's date to use for arguments.
	To create a component ID specific table.	Creates a virtual table for data conversion to use in a virtual query used during execution of common components.

Notes when executing components for initial processing:

• The target data to be processed by the function does not exist. Referencing the target data results in an empty character string.

• Although argument ARGx can be referenced, the arguments in dynamically-specified argument cannot be referenced. If you attempt to reference dynamically-specified arguments, they are handled as the initial value of each type.

• If the result value is returned to the 0th argument (implicit argument), the value cannot be inherited. If the result value is returned the ARGx other than the 0th, and the argument is a statically-specified argument, the ARGx is replaced with the returned value.

Example of creating a temporary table to be used to return a list by using a virtual query

To create an initial processing component by using a virtual query, see the example below to understand how to create and use a temporary table to return a list.

Example:

 create table Prefecture list (name, no); insert into Prefecture list values ('Hokkaido', 1); insert into Prefecture list values ('Aomori', 2); insert into Prefecture list values ('Iwate', 3);

Because the virtual query and its initial processing component share the same statement handles, a table created by an initial processing component can be referenced from its parent virtual query.

(6) Lua data types that can be used as a return value

The following table describes the Lua data types that can be used as a return value.

If other Lua data types are set as a return value of data processing, an error occurs during the processing.

Table 5.6 Lua data types and use as return value

Lua data type	Use as return value
Nil(LUA_TNIL)	Can be used
Boolean (LUA_TBOOLEAN)	Cannot be used
Numeric value (LUA_TNUMBER)	Can be used
Character string (LUA_TSTRING)	Can be used
Function (LUA_TFUNCTION)	Cannot be used
User data (LUA_TLIGHTUSERDATA, LUA_TUSERDATA)	Cannot be used
Thread (LUA_TTHREAD)	Cannot be used
Table (LUA_TTABLE)	Cannot be used

(7) Examples of processing arguments

This section describes the behavior when an argument specified in a common component is referenced and set, and the flow of tasks of the argument.

Processing illustrated in the examples

Addition of the accounts receivable.

The ordering country and the exchange rate are not modified during data processing.

Processing of the initial processing component

Obtains the ordering country from the environment variable, and determines the exchange rate.

Processing of ordinary components

1. Obtain the current accounts receivable as the processing target data

2. Obtain the country name from the ordering country

3. Specify single item and a parenthesized language name in the product name.

4. Obtain the unit price from the product master

Use the result of Existing accounts receivable + (Quantity * Price / Exchange rate) as the new accounts receivable, and return the value.

In addition, the following special specifications shall be applied.

• For a company whose ordering country is other than CN, +1 shall be added to the quantity as a reserve item.

• If the conversion result of the ordering country to Japanese is identical with the Japanese characters representing China, +1 shall be added to the exchange rate.

 

The table below describes the arguments that are specified in this example.

 

The following components are also added. They help explain that values are not inherited even when they are set. This would be unnecessary processing for actual data.

Initial processing component 3

Initial processing component 4

Initial processing component 5

Argument settings

Argument	Description of Argument	Representation of Argument		Argument Type	Type of Argument Specification
		non-Lua	Lua
Processing target data	Accounts receivable	$ARG0	av0	Character string	Cannot be specified (dynamically)
Argument 1	Product name	$ARG1	av1	Character string	Dynamic
Argument 2	Quantity	$ARG2	av2	Numeric value	Dynamic
Argument 3	Ordering country	$ARG3	av3	Character string	Static
Argument 4	Exchange rate	$ARG4	av4	Numeric value	Static

Data processed by the ordinary component (actual data to be processed)

Argument	Description of Argument	Type of Argument Specification
Processing target data	Accounts receivable	10(Numeric value)
$MINUM(2,4)	Product name	Product(Character)
$INAME(Quantity)	Quantity	3