5.1.4 Functions

You can use functions by defining them in the same job definition script files and external files. The following shows the formats used to define functions.

Format 1

function-name() {
      command
      :
      (omitted)
}

Format 2

function function-name {
      command
        :
      (omitted)
}

The naming conventions for functions are the same as for variables. A function cannot have the same name as any standard shell command or extended shell command. For details about the naming conventions for variables, see 5.1.2(1) Naming conventions for variables.

If you define a function in a job definition script that is not the job definition script in which the function is to be executed, you must use the . (dot) command or the #-adsh_script command to call the job definition script in which the function is defined before the function executes.

The formats are shown below. For details about the . (dot) command, see . command (executes a shell script) in 9.3 Standard shell commands. For details about the #-adsh_script command, see #-adsh_script command (calls an external job definition script file from the job definition script that is running) in 9.5 Extended script commands.

. name-of-file-defining-the-function

#-adsh_script name-of-file-defining-the-function

If a function defined in a job definition script has the same name as another function in the same job definition script, in a job definition script called by the . (dot) command, or in a job definition script called by the #-adsh_script command, the function defined immediately before the execution location of the identically named function is executed.

The format used to execute a function is shown below. You can specify arguments in a function. The specified arguments are stored after the positional parameter $1 within the function.

function-name [args]

In the positional parameter $0 in the function, the following information is stored according to the format used:

For a function defined in format 1, its shell script name is stored.
For a function defined in format 2, its function name is specified.

The following table explains the relationship between positional parameters and whether function arguments are specified.

Table 5‒4: Relationship between positional parameters and whether function arguments are specified
Positional parameter in the program calling the function	Function argument	Positional parameter when the function begins	Positional parameter when control returns from the function
Specified	Specified	Value specified in the argument	Value of the positional parameter in the program calling the function
Specified	Omitted	No value	Value of the positional parameter in the program calling the function
Omitted	Specified	Value specified in the argument	No value (value of the positional parameter in the program calling the function)
Omitted	Omitted	No value	No value (value of the positional parameter in the program calling the function)

Organization of this subsection

(1) Local variables in functions
(2) Trace mode
(3) Function preload functionality

(1) Local variables in functions

In JP1/Advanced Shell, you can use the typeset command in a function to define local variables that are valid within the function. When the function is completed, the defined variables are restored to their status before the function was executed. The following shows an execution example of local variables in a function.

Contents of job definition script:

0001 : myfunc(){             # Define the myfunc function
0002 :   typeset -r var=abc  # Define the var local variable with the read-only attribute in the function
0003 :   echo $var           # Output the value of the var variable
0004 :   readonly -p         # Output the variable with the read-only attribute
0005 :   return 0
0006 : }
0007 : typeset -i var=123    # Define the var variable with the integer-type attribute
0008 : typeset | grep var    # Output the attribute of the var variable
0009 : myfunc                # Execute the myfunc function
0010 : echo $var             # Output the value of the var variable after function execution
0011 : readonly -p           # Output the variable with the read-only attribute
0012 : typeset | grep var    # Output the attribute of the var variable
0013 : exit 0
0014 :

Contents of the STDOUT file of execution job:

********   JOB SCOPE STDOUT    ********
typeset -i var            <-- Result of line 8. The var variable has been defined as having the integer type.
abc                        <-- Result of line 3. The var variable has been updated to abc.
readonly var=abc           <-- Result of line 4. The var variable has the read-only attribute.
readonly ADSH_DIR_BIN=/opt/jp1as/bin/
readonly ADSH_DIR_CMD=/opt/jp1as/cmd/
123                        <-- Result of line 10. The value of the var variable has been restored after function execution.
readonly ADSH_DIR_BIN=/opt/jp1as/bin/
readonly ADSH_DIR_CMD=/opt/jp1as/cmd/
typeset -i var             <-- Result of line 12. Same output results as in line 8.

To Page Top

(2) Trace mode

By enabling the trace mode for a function, you can execute the commands specified in the function at the same time that the contents of the commands are output to the standard error output.

You use the typeset standard shell command to place a function in the trace mode. For details about the typeset command, see typeset command (declares explicitly the attributes and values of variables and functions) in 9.3 Standard shell commands.

The following shows an example of a typeset command specification and its standard error output results:

Contents of job definition script

0001 : fn(){
0002 :   echo "--- `date`"
0003 : }
0004 : typeset -ft fn
0005 : fn

Standard error output results of the function in the trace mode

+ date
+ echo --- Thu Mar 28 16:00:00 JST 2013

To Page Top

(3) Function preload functionality

The function preload functionality enables you to define only the code functions used in the shell script to be defined during execution. When the function preload functionality is used, batch job execution performance improves compared with when this functionality is not used because you can avoid executing common code functions regardless of the execution.

The following explains how to use the function preload functionality.

Create a file containing function definitions (function definition file) and save it using the function name as the file name.

If you define multiple functions in the function definition file, all the specified functions are defined. Note that if a function name defined in the function definition file already exists, that function definition is overwritten.

If information other than function definitions, such as commands, is specified in the function definition file, that information functions in the same manner as external scripts.
In the job definition script, specify the following command to enable the function preload functionality:
```
typeset -fu function-name [function-name-2...]
```
For function-name, specify the name of the function with the same name as the function definition file name.

JP1/Advanced Shell provides autoload as an alias of the typeset -fu command. The format of autoload is as follows:
```
autoload function-name [function-name-2...]
```
For details about the typeset command, see typeset command (declares explicitly the attributes and values of variables and functions) in 9.3 Standard shell commands.

For details about autoload, see 5.1.5 Command alias definitions.
In the FPATH shell variable, specify the directory that contains the function definition file.

If a function with the preload functionality enabled is not defined in the specified function definition file, the contents of the function definition file with the specified function name are loaded from the directory specified in the FPATH shell variable and then all the functions specified in the file are defined. You can specify the FPATH shell variable in job definition scripts and environment files.

(a) Example of using the preload functionality (using the typeset -fu and autoload commands)

This example uses the preload functionality with the typeset -fu and autoload commands. This example applies the function preload functionality to the functions auto1, auto2, and auto3.

Contents of the function definition file (/home/jp1as/autoload/auto1):

0001 : function auto1 {     # Defines the auto1 function
0002 :  echo "start auto1 in FPATH file"
0003 :  return 11
0004 : }

Contents of the function definition file (/home/jp1as/autoload/auto2):

0001 : autoxx() {          # Defines the autoxx function (auto2 is not defined)
0002 :   echo "start autoxx in FPATH file"
0003 :   return 255
0004 : }

Function definition files in the /home/jp1as/autoload directory:

auto1

auto2

(Function definition file auto3 does not exist)

Contents of the job definition script (/home/jp1as/test.ash):

0001 : export FPATH="/home/jp1as/autoload"  # Specify FPATH
0002 :
0003 : typeset -fu auto1 auto2  # Apply the preload functionality to the auto1 and auto2 functions
0004 : autoload auto3           # Apply the preload functionality to the auto3 function
0005 :
0006 : auto1                    # Execute the auto1 function
0007 : auto2                    # Execute the auto2 function
0008 : auto3                    # Execute the auto3 function

Execution results:

********  JOB CONTROLLER MESSAGE  ********
14:40:37 152263 KNAX0091-I ADSH152263 The job started.
14:40:37 152263 KNAX7901-I The adshexec command will wait for all asynchronous processes at the end of the job.
14:40:37 152263 KNAX7902-I The adshexec command will run in tty stdin mode.
14:40:37 152263 KNAX6112-I Execution of the command export (line=1) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s
14:40:37 152263 KNAX6112-I Execution of the command typeset (line=3) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s
14:40:37 152263 KNAX6112-I Execution of the command typeset (line=4) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s
14:40:37 152263 KNAX6112-I Execution of the command echo (line=2) finished successfully. exit status=0 execution time=0.000s CPU time=0.000s
14:40:37 152263 KNAX6112-I Execution of the command return (line=3) finished successfully. exit status=11 execution time=0.000s CPU time=0.000s^#1
14:40:37 152263 KNAX6046-E The function "auto2" is not defined in the function definition file "/home/jp1as/autoload/auto2". filename="/home/jp1as/test.ash" line=7^#2
14:40:37 152263 KNAX6044-E The function definition file "auto3" was not found in the FPATH directory. filename="/home/jp1as/test.ash" line=8^#3
14:40:37 152263 KNAX0101-E ADSH152263 An error occurred during execution of the job.
14:40:37 152263 KNAX0098-I ADSH152263 The job ended. exit status=127 execution time=0.004s CPU time=0.000s

#1: Indicates that the execution result of the auto1 function is normal termination.
#2: The auto2 function already exists in the function definition file with the same name in the directory specified in FPATH. Because that function definition file does not contain a definition of the auto2 function, the KNAX6046-E message is issued and the function terminates with an error.
#3: For the auto3 function, the directory specified in FPATH does not contain a function definition file with the function name. Therefore, the KNAX6044-E message is issued and the function terminates with an error.

(b) Notes

Once a function is defined by loading its function definition file by using the preload functionality, no function definition file with the same file name will be loaded again. However, if the function is invalidated by the unset command and then is re-executed, the function definition file with the same name will be loaded again.
If the function preload functionality is enabled for a function but the function has already been defined in the same shell script, in a shell script called by the . (dot) command, or in a shell script called by the #-adsh_script extended script command, the function definition file is not loaded.
If the same function is defined in multiple function definition files, the last function defined takes effect. If you define multiple functions in a single function definition file, make sure that there is no duplication of function names.

The following shows an example definition of the fn1 function in multiple function definition files and the output results.

Contents of the function definition file /home/jp1as/autoload/fn1:

0001 : fn1(){ # fn1 function definition 1

0002 : echo "start fn1"

0003 : return 1

0004 : }

Contents of the function definition file /home/jp1as/autoload/fn2:

0001 : fn2(){ # fn2 function definition

0002 : echo "start fn2"

0003 : return 2

0004 : }

0005 : fn1(){ # fn1 function definition 2

0006 : echo "start fn1 in fn2"

0007 : return 21

0008 : }

Contents of the job definition script /home/jp1as/test.ash:

0001 : export FPATH="/home/jp1as/autoload" # Specify FPATH

0002 : typeset -fu fn1 fn2 # Enable the preload functionality for the fn1 and fn2 functions

0003 : fn1 # Execute the fn1 function

0004 : fn2 # Execute the fn2 function

0005 : fn1 # Re-execute the fn1 function

Results output to the standard output

start fn1 fn1 of definition 1 is executed.

start fn2

start fn1 in fn2 fn1 of definition 2 is executed.
If the function preload functionality is enabled for an undefined function, the job definition script is placed in undefined status until a function definition file is loaded. Therefore, nothing is displayed by using the CUI debugger's info functions command.

To Page Top