5.1.2 Variables

(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

(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. Example: The following shows the reference target when 0, 3, or -1 is specified for offset for data consisting of 10 characters:
length	0 to 65536	Example: The portion of the character string enclosed in the highlighted box indicates the range of characters to be output when offset=3 and length=3 are specified for data consisting of 10 characters:

#

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.