5.1.2 Variables
Variables are placeholders that are replaced by values in job definition scripts. You can create variables and reference their values. Variables can be inherited as environment variables to child processes by exporting them. The variables are also referred to as shell variables.
- Organization of this subsection
(1) Naming conventions for variables
You can assign to a created variable any name that observes the naming conventions. Alphabetic characters are always case sensitive. Therefore, two variables with the same name but with differences in case will be treated as different variables.
In a Windows environment, if you attempt to export a variable that name includes lowercase letters and use it as an environment variable, an error might result depending on the specification of the VAR_ENV_NAME_LOWERCASE parameter.
The naming conventions for variables are described below. For details about the naming conventions for environment variables, see (a) Naming conventions for environment variables (Windows only).
-
The only permitted characters are alphanumeric characters and the underscore (_).
-
A variable must being with a non-numeric character.
-
There is no limit to the length of a variable name. However, there is a limit to the length of an input line, and the CUI debugger imposes a limit to the length of a command (number of characters). We recommend that you observe these limitations for variables that are used in job definition scripts.
For details about the maximum length of an input line, see 5.1 Basic elements of job definition scripts. For details about the maximum length of a command entry in the CUI debugger, see 6.1.4 List of debugger commands (UNIX only).
(a) Naming conventions for environment variables (Windows only)
The supported environment variable names depend on the specification of the VAR_ENV_NAME_LOWERCASE parameter, as described in the following:
-
When DISABLE is specified in the VAR_ENV_NAME_LOWERCASE parameter
Environment variable names that include lowercase letters are not supported.
An attempt to export a variable name that includes lowercase letters results in an error.
-
When ENABLE is specified in the VAR_ENV_NAME_LOWERCASE parameter
Environment variable names that include lowercase letters are supported, except that you must not use lowercase letters in an environment variable name that begins with ADSH.
Following are notes about specification:
-
If a shell variable name consisting of lowercase letters is exported by a job definition script, the environment variable name that includes lowercase letters is passed as is to an external command that is called subsequently. Because environment variable names are not case-sensitive in Windows, environment variable names with the same spelling are treated as the same name and the last value exported is passed as the environment variable. However, shell variables are case-sensitive and they represent different values.
For example, in the following specification, lowercase is set first as the environment variable value and uppercase is set last as the environment variable value because environment variable names ABC and abc are not distinguished:
export abc=lowercase
export ABC=uppercase
-
If a shell variable is exported, the export attribute of shell variables with the same spelling within the scope of that shell variable becomes invalid. For arrays also, the export attribute of all elements becomes invalid.
For a local shell variable, the export attribute of shell variables with the same spelling outside the scope of that shell variable is valid, but outside the function processing, the environment variable value is recovered.
-
The setting of the VAR_ENV_NAME_LOWERCASE parameter determines whether lowercase letters are supported by commands and parameters, as described in the following:
Command or parameter |
VAR_ENV_NAME_LOWERCASE parameter setting |
|
---|---|---|
DISABLE |
ENABLE |
|
export parameter (environment setting parameter) |
Uppercase and lowercase letters are permitted, but they are not distinguished. |
Same as at the left |
export command, typeset -x command |
Shell variable names in lowercase letters are not supported. |
Shell variable names in lowercase letters are supported, but environment variable names are not case sensitive. Shell variables are case sensitive and treated as different shell variables. |
set command (-a option) |
All shell variables following the set command are exported, but an attempt to set values in shell variables consisting of lowercase letters results in an error. |
All shell variables following the set command are exported. If values are set in shell variables consisting of lowercase letters, those shell variables are also exported. However, environment variable names are not case sensitive. |
unset command, readonly command, read command |
Lowercase letters are supported because they specify shell variable names. |
Same as at the left |
#-adsh_file command, #-adsh_file_temp command, #-adsh_spoolfile command |
Lowercase letters are not supported in file environment variable definition names. |
Lowercase letters are supported in file environment variable definition names. However, environment variable names are not case sensitive. |
#-adsh_step_start command |
Job step names are used as shell variable names for storing step return values, but lowercase letters are supported. Lowercase letters are not supported in shell variable names that are specified in -stepVar. |
Same as at the left |
#-adsh_path_var command |
Lowercase letters are supported in variable names. |
Same as at the left |
Substitution by {environment-variable-name} of extended script commands |
Lowercase letters are supported in environment variable names. |
Same as at the left |
Shell variables watched by the GUI debugger |
Lowercase letters are supported in shell variable names. |
Same as at the left |
adshread command |
Lowercase letters are supported in shell variable names. |
Same as at the left |
for shell-variable |
Lowercase letters are supported in shell variable names. |
Same as at the left |
ENVIRON built-in variable in the awk command |
Environment variable names can be specified for subscripts, but lowercase letters are also supported. |
Same as at the left |
Arguments passed to the adshjava command's batch applications |
Environment variable names can be specified in system properties, but the adshjava command does not check character types. |
Same as at the left |
Environment variables collected by the operation information acquisition functionality |
Environment variable names and values are collected, but the environment variable names are not checked for character types. |
Same as at the left |
(2) Creating variables and assigning values to them
The following shows the format used to create a variable and to assign a value to it:
variable-name=value
You create a variable by specifying a variable name followed by an equal sign (=). You can use your created variables to write and to read values. To assign a value to the variable, specify the value to the right of the equal sign (=). Note the following about creating variables:
-
If a variable has the read-only attribute, an attempt to assign a value to the variable will result in an error and the job will terminate. You use the readonly standard shell command to change a variable's attribute to read-only (for details about the readonly command, see readonly command (sets the read-only attribute for variables or displays all read-only variables) in 9.3 Standard shell commands).
-
If you specify the name of a variable that has not been created, the variable will be created and the specified value will be assigned to it. When the value to be assigned is a character string, its length can consist of any number of characters.
When numeric values are assigned to variables defined by the typeset command as the integer type, or numeric values are assigned to variables used in arithmetic operations, the variable values and the results of the arithmetic operations must be within the range of -2147483648 to 2147483647. If a value outside this range is specified, correct results cannot be obtained.
-
Do not enter any spaces before or after the equal sign. If there is such a space, the variable will not be created.
-
To assign to a variable a character string that contains spaces or metacharacters, you must enclose the character string in quotation marks (' or "), which will disable the metacharacters or cause space characters to be recognized correctly as spaces. For details about metacharacters and disabling metacharacters, see 5.1.6 Metacharacters.
(3) Referencing the values of variables
(a) Referencing method
The following shows the formats used to reference the value of a variable:
$variable-name or ${variable-name}
You reference the value assigned to a variable by specifying a dollar sign ($) before the variable name. The variable with the matching variable name is referenced. If the variable name you specify contains an invalid character, only the characters up to that invalid character will be recognized as a variable name.
- Example in which an invalid character is specified in the name of a variable to be referenced
abc=xxx echo $abc@zzz -->xxx@zzz is output to the standard output.
To explicitly specify a variable to be referenced, enclose the variable name in curly brackets ({}). When a variable name is enclosed in curly brackets and characters that are not permitted for a variable name are used, those characters are processed as part of the variable name.
- Example for explicitly specifying variable abc and referencing its value
abc=xxx abcdef=yyy echo ${abc}def -->xxxdef is output to the standard output.
(b) Referencing method using offset (start point for referencing) and length (length to be referenced)
The following shows the formats used to reference a variable value by specifying offset (start point for referencing) and length (length to be referenced):
${variable-name:offset}
or
${variable-name:offset:length}
or
${variable-name::length}
To reference a specific part of the value assigned to the variable to be referenced, specify :offset or :offset:length following variable-name.
Only those characters and numeric values permitted by the variable naming rules can be specified for offset and length. You must observe the following rules in specifying variable names and numeric values for offset and length:
Specification value |
Specification rules |
---|---|
Numeric value (unsigned) |
Space and tab cannot be specified before or after the value. |
Numeric value (signed) |
There must be a space immediately before a sign. Space and tab cannot be specified before or after any other value. |
Variable |
Space and tab cannot be specified before or after the value. |
Default for offset |
Spaces are permitted, but tabs are not permitted. |
If the specification spans multiple lines, enter a slash (\) at the end of each line that is to be continued.
The following table describes the value ranges permitted for offset and length:
Type |
Value range (in characters)# |
Specification example |
---|---|---|
offset |
-65535 to 65535 |
If 0 is specified, the character string is output from the beginning. If a positive value is specified, the start point at which the character string is output is determined by counting the specified number of characters from the beginning of the character string + 1. If a negative value is specified, the start point is determined by counting the specified number of characters from the end of the character string.
|
length |
0 to 65536 |
|
- #
-
You can use either of the following methods to specify a numeric value:
-
As an octal, decimal, or hexadecimal value
The specified numeric value is identified automatically as follows:
Any character string beginning with 0x is assumed to be a hexadecimal number (for example, 0xa).
Any character string beginning with 0 is assumed to be an octal number (for example, 012.
Any numeric value that is neither octal nor hexadecimal is assumed to be a decimal number.
-0 is treated as being the same as 0.
If a numeric value has a sign (- or +), you must specify at least one space between the colon (:) and the sign.
-
As a variable names to which a numeric value is assigned
If no variable with the specified variable name exists or no value has been assigned to the specified variable, 0 is assumed as the variable value.
An error results if the specified variable references multiple variables recursively and the recursion count for offset exceeds 1,024 or the recursion count for length exceeds 1,025.
-
The notes below apply to specifying offset and length.
-
The following specifications result in a syntax error:
-
The character string specified for offset or length is not a numeric value or a variable name.
echo ${ABC:123D}
An error results because 123D is not a numeric value or a variable name.
-
A character string that is not a numeric value or a variable name is specified as a value to set to an offset or length variable name.
CNT=123D
echo ${ABC:CNT}
An error results because the specified variable value 123D is not a numeric value or a variable name.
-
offset is omitted illegally.
echo ${ABC:}
An error results because offset is not specified.
-
An arithmetic expression is specified for offset or length.
echo ${ABC:10-2}
An error results because an arithmetic expression is specified.
-
The variable specified for offset or length contains $ or ${}.
ABC=abcdefghijklmn
AA=1
echo ${ABC:$AA}
An error results because the variable specified for offset or length contains $ or ${}.
-
A tab is specified immediately before offset or length.
(The following example specifies a tab immediately before offset, where indicates a tab:)
ABC=abcdefghijklmn
AA=1
BB=1
echo ${ABC:AA:BB}
An error results because a tab is specified immediately before offset.
-
-
If the value specified for offset or for variable exceeds the length of the character string set in variable, the character string set in variable is not retrieved.
ABC=abcdefghijklmn echo ${ABC:20}
The character string set in variable ABC cannot be retrieved because the length of that character string is only 14 characters.
-
If the variable name specified for offset or length is undefined or the variable value is null, 0 is assumed as the value of offset or length.
-
If the attribute of the variable value that is specified for offset or length is changed by executing the typeset command, the number base might change depending on the method used (if zeros padding is specified with the -Z option, the value is treated as being in octal), resulting in a change to the reference range. Furthermore, the specified value might become invalid due to the change to the number base.
The example below uses the typeset command to change the attribute and specify zeros padding. As a result, the value 12 specified for variable L1 is interpreted as being an octal value.
ABC=abcdefghijklmnopqrstuvwxyz typeset -Z3 D1=4 typeset -Z3 L1=12 echo ${ABC:D1:L1}
012 (octal) is interpreted as 10 (decimal) and efghijklmn (10 characters) is output to STDOUT.
The example below uses the typeset command to change the attribute and specify zeros padding. As a result, 8 specified for variable D1 becomes 008 and is interpreted as an octal value. However, an error results because octal numbers must be in the range from 0 to 7.
ABC=abcdefghijklmnopqrstuvwxyz typeset -Z3 D1=8 typeset -Z3 L1=12 echo ${ABC:D1:L1}
An error results because 8 is specified as an octal number.
If the variable specified for offset or length is a recursive reference specification or circular reference specification, an error results. Examples are shown in the following:
-
Example of recursive reference specification
ABC=abcdefghijklmnopqrstuvwxyz
D1=D1
echo ${ABC:D1}
-
Example of circular reference specification
ABC=abcdefghijklmnopqrstuvwxyz
D1=D2
D2=D1
echo ${ABC:D1}
-
The following are examples of specifying offset and length.
-
Specifying offset(5)
ABC=abcdefghijklmn echo ${ABC:5}
-->fghijklmn is output to the standard output.
-
Specifying offset(5) and length(4)
ABC=abcdefghijklmn echo ${ABC:5:4}
-->fghi is output to the standard output.
-
Specifying offset(-1)
ABC=abcdefghijklmn echo ${ABC: -1}
-->n is output to the standard output.
-
Specifying the name of a variable that defines offset
DEF=abcdefghijklmn CNT=5 echo ${DEF:CNT}
-->fghijklmn is output to the standard output.
-
Specifying the names of variables that define offset and length
DEF=abcdefghijklmn CNT=5 LEN=4 echo ${DEF:CNT:LEN}
--> fghi is output to the standard output.
-
Specifying the name of a variable that defines offset
DEF=abcdefghijklmn CNT=-1 echo ${DEF:CNT}
-->n is output to the standard output.
-
Specifying variable xyz explicitly and referencing three characters of the value specified for the variable beginning with character 5, where variable xyz contains multibyte characters and the values of offset and length are assigned to variables CNT and LEN.
xyz=abcdefgh CNT=4 LEN=3 echo ${xyz: CNT: LEN}
-->is output to the standard output.
-
Specifying variable xyz explicitly and referencing 14 characters of the value specified for the variable beginning with character -17, where variable xyz contains multibyte characters and the values of offset and length are assigned to variables CNT and LEN.
xyz=abcdefgh CNT=-17 LEN=14 echo ${xyz: CNT: LEN}
-->fabcdefgh is output to the standard output.
(4) Formats and attributes permitted for variables
In JP1/Advanced Shell, you can specify formats and attributes for variables. The following tables describe the formats and attributes that can be specified for variables.
Format |
Description |
---|---|
Left-justified |
Left-justifies the value assigned to the variable. |
Right-justified |
Right-justifies the value assigned to the variable. |
Zero-padded |
Right-justifies the value assigned to the variable; if the value is a numeric value, pads any leading spaces with zeros. |
Lowercase conversion |
Converts all uppercase letters in the value assigned to the variable to lowercase letters. |
Uppercase conversion |
Converts all lowercase letters in the value assigned to the variable to uppercase letters. |
Attribute |
Description |
---|---|
Integer-type attribute |
Treats the value assigned to the variable as an integer. This attribute enables a base number used during output to be defined. |
Read-only attribute |
Sets the variable as being read-only. |
Export attribute |
Exports the variable. |
You use the typeset command to specify formats and attributes. For details about the typeset command, see typeset command (declares explicitly the attributes and values of variables and functions).
Examples of specifying formats for variables are shown below. These examples assume that each of the variables shown has been defined ( indicates a space). Each line of code is followed by an explanation of the coding.
STRn="AbCdeFgHiJk" NUMn="12345"
-
Contents of job definition script
typeset -L STR1 # Change STR1 to left-justified format echo $STR1 # Outputs STR1 typeset -L5 STR2 # Change STR2 to left-justified format # with an area length of 5 bytes echo $STR2 # Outputs STR2 typeset -R STR3 # Change STR3 to right-justified format echo $STR3 # Outputs STR3 typeset -R4 NUM1 # Change NUM1 to right-justified format # with an area length of 4 bytes echo $NUM1 # Outputs NUM1 typeset -Z9 STR4 # Change STR4 to zero-padded format with # an area length of 9 bytes echo $STR4 # Outputs STR4 typeset -Z9 NUM2 # Change NUM2 to zero-padded format with # an area length of 9 bytes echo $NUM2 # Outputs NUM2 typeset -l STR5 # Change STR5 to lowercase conversion # format echo $STR5 # Outputs STR5 typeset -u STR6 # Change STR6 to uppercase conversion # format echo $STR6 # Outputs STR6 typeset -i16 NUM3 # Change NUM3 to integer-type attribute # with hexadecimal representation echo $NUM3 # Outputs NUM3
-
STDOUT file contents of the executed job
******** JOB SCOPE STDOUT ******** AbCdeFgHiJk <-- Output result of STR1 AbCde <-- Output result of STR2 AbCdeFgHiJk <-- Output result of STR3 2345 <-- Output result of NUM1 CdeFgHiJk <-- Output result of STR4 000012345 <-- Output result of NUM2 abcdefghijk <-- Output result of STR5 ABCDEFGHIJK <-- Output result of STR6 16#3039 <-- Output result of NUM3