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.
- Syntax 1
function-name() { command : (omitted) }
- Syntax 2
function function-name { command : (omitted) }
The naming conventions for functions are the same as for variables.In addition, a function cannot have the same name as any standard shell command, extended shell command, or the following commands:
-
bg
-
bind
-
fc
-
fg
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 (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 9.3.1 . command (executes a shell script) in 9.3 Standard shell commands. For details about the #-adsh_script command, see 9.5.7 #-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
or
#-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.
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
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:
-
******** Contents of the STDOUT file of the executable job ******** typeset -i var <- Result of the 8th line. Already defined the variable var with the integer type abc <- Result of the third line. Updated the variable var with abc readonly var=abc <- Result of the fourth line. Variable var is read-only attribute readonly ADSH_DIR_BIN=/opt/jp1as/bin/ readonly ADSH_DIR_CMD=/opt/jp1as/cmd/ readonly ADSH_DIR_PARTS_EN=/opt/jp1as/parts/en/ readonly ADSH_DIR_PARTS_JA=/opt/jp1as/parts/ja/ 123 <- Result of the 10th line. Variable var is recovered after completion of function. readonly ADSH_DIR_BIN=/opt/jp1as/bin/ readonly ADSH_DIR_CMD=/opt/jp1as/cmd/ readonly ADSH_DIR_PARTS_EN=/opt/jp1as/parts/en/ readonly ADSH_DIR_PARTS_JA=/opt/jp1as/parts/ja/ typeset -i var <- Result of the 12th line. Same as the output result of the 8th line.
(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 9.3.29 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 Oct 29 15:41:17 JST 2015
(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 9.3.29 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 commands)
The example below shows how to use the function-preload functionality by using the typeset -fu command. JP1/Advanced Shell provides autoload as an alias of the typeset -fu command. In this example, the preload functionality is executed for 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.