5.5.3 Function information arrays

Information about the functions that are executed by the adshexec command is stored in single-dimensional function information arrays.

Whether function information arrays are used is defined with the VAR_SHELL_FUNCINFO environment setting parameter. The array names are also determined by the specification of the VAR_SHELL_FUNCINFO environment setting parameter. For details about the VAR_SHELL_FUNCINFO environment setting parameter, see VAR_SHELL_FUNCINFO parameter (selects whether function information arrays are used).

Following are the characteristics of function information arrays:

Arrays of function information exist from the time a job definition script is executed to the time the job definition script is terminated. However, if functions are executed within a .ENV file, there are no function information arrays.
The range of the number of elements is from 0 to 65,535.
Attributes can be changed to the character string format attribute. Attributes cannot be changed to local variables in a function.
Because function information arrays have the read-only attribute, the values in arrays can be referenced only; values cannot be set nor can the arrays be disabled.

Organization of this subsection

(1) Types of function information arrays
(2) Structures of function information arrays
(3) Notes about function information arrays

(1) Types of function information arrays

The following table lists and describes the types of function information arrays.

Table 5‒33: Types and names of function information arrays
Type of array	Description	Array name
Type of array	Description	When TYPE_A is specified in VAR_SHELL_FUNCINFO	When TYPE_B is specified in VAR_SHELL_FUNCINFO
Called function name array	This array stores the names of all functions that are in the call stack. Element number `0` stores the name of the currently executing function. The lowest element stores `main`. If an external script was called with the `.` (dot) command (standard shell command) or the `#-adsh_script` extended script command, the array stores `source`.	`ADSH_FUNCNAME`	`FUNCNAME`
Function call line number array^#1	This array stores the line numbers of the script files for which all functions in the call stack were called. Element number `0` stores the line number that called the currently executing function. The lowest element stores `0`. For an external script, the array stores the line number that executed the `.` (dot) command (standard shell command) and the `#-adsh_script` extended script command. The attribute can be changed to the integer type.	`ADSH_LINENO`	`BASH_LINENO`
Function definition script file name array^#2	This array stores the names of the script files in which the functions in the call stack have been defined. Element number `0` stores the name of the script file that defines the currently executing function. The lowest element stores the absolute path of the job definition script name. For an external script, this array stores the absolute path of the external script file.	`ADSH_SOURCE`	`BASH_SOURCE`

#1

If a function is called within a trap action after a signal or a forced termination request has been received, the function call line number array stores the line number of the processing that called the trap action, not the processing within the trap action.

For example, in the definition below, function fn1 is called on line number 4. Because line number 4 is within the trap action, line number 6 is stored in the array.

1  fn1(){
2    echo ${ADSH_LINENO[*]}
3  }
4  trap fn1 INT
5
6  kill -INT $$
7  pwd

#2

If the adshexec command is executed with the -r option specified, -r CMDLINE is stored as the script file name in the function definition script file name array. The following shows an example:

C:\tmp>adshexec -m SIMPLE -r "echo ${ADSH_SOURCE[*]}"
-r CMDLINE
 
C:\tmp>

To Page Top

(2) Structures of function information arrays

This subsection explains the transitions among the arrays based on the example of the following job definition script (file name: func.ash):

1    fn3(){
2      echo "JP1/AS"
3    }
4    fn2(){
5      fn3
6    }
7    fn1(){
8      fn2
9    }
10   fn1

When this job definition script is run, the array status changes as shown in the following by the execution of function fn3:

[Figure]

To Page Top

(3) Notes about function information arrays

Because function information arrays cannot be changed within job definition scripts, during debugging using CUI or GUI, the user can reference values (by using the watch, print, and info variables commands), but cannot update the values (with the set command).
Arrays of function information are exported as follows:
- The contents of element 0 are inherited as variables, not as an array. However, for child jobs, function information arrays are overwritten because they are reset when a job starts.
- For the operation information for a child job, the exported values before being overwritten are output.
The name of afunction information array cannot be specified for the stepVar attribute in the #-adsh_step_start command. If the name of a function information array is specified, the command issues the KNAX6312-E message and terminates with an error.
(Windows only) The absolute path of the script file (including \ characters) is stored in the function definition script file name array. The echo and print commands handle this character (\) whenever it is encountered after shell variable expansion as an escape character. For this reason, if you output values from a function definition script file name array by using the echo and print commands, you must execute the commands as follows:
- If you use the echo command to output values, either specify the -E option or specify NO in the ESCAPE_SEQ_ECHO_DEFAULT environment setting parameter.
- If you use the print command to output values, specify the -r option.

To Page Top