adshscripttool command (supports creation of job definition scripts) (Windows only)

Format

adshscripttool -fowner path-name
adshscripttool -fentry path-name
adshscripttool -fmode [-s {u|g|o|r|w|x}] mode
adshscripttool -exec {-m SIMPLE|MINIMUM}]
              {-r command-line|job-definition-script-file-path-name}
              [run-time-parameters]

To Page Top

Description

This command collects and outputs information in order to make it easy to create job definition scripts. The following table describes the arguments that can be specified and their purposes:

To Page Top

Arguments

-fowner

Specifies that the owner name of a file or folder is to be output to the standard output.

The owner name is output in the format domain-or-computer-name\user-name or user-name format.

Even if you use the cacls command to define Creator Owner, it might not be mapped to the file or folder owner. Before using the cacls command to specify an owner name, determine the owner name by executing the adshscripttool command with this option specified.

-fentry

Specifies that a list of account names registered in the ACL of a file or folder, separated by semicolons (;), is to be output to the standard output.

An account name is output in the format domain-or-computer-name\user-name or user-name.

path-name

Specifies the targeted file or folder.

-fmode

Specifies that the symbol or numeric value specified as the mode for the chmod command is to be parsed and that the changes made to the permissions for owners, groups, and other users are to be output as a 9-digit character string.

If a numeric value is specified, a value corresponding to mode bit ON is set to R and a value corresponding to mode bit OFF is set to D. If an error occurs, only E is output and processing terminates.

The following table explains the meaning of the character string that is output as the execution result of the adshscripttool command when the -fmode option is specified:

Digit number counted from the left side	Meaning
1	Owner's read permission
2	Owner's write permission
3	Owner's execute permission
4	Group's read permission
5	Group's write permission
6	Group's execute permission
7	Other users' read permission
8	Other users' write permission
9	Other users' execute permission

The following values are set in the individual digits:

Value	Meaning
A	Addition ((+) was set).
D	Deletion ((-) was set).
R	Substitution ((=) or numeric value was set).
0	Not specified.
E	The adshscripttool -fmode command terminated with an error.

-s[u|g|o|r|w|x]

Specifies one of the values listed below to indicate which of the digits specified when the -fmode option was specified are to be output. You can specify one of these values when you specify the -fmode option.

• u

  Corresponds to digits 1 to 3 of the output when the -fmode option was specified.

• g

  Corresponds to digits 4 to 6 of the output when the -fmode option was specified.

• o

  Corresponds to digits 7 to 9 of the output when the -fmode option was specified.

• r

  Corresponds to digits 1, 4, and 7 of the output when the -fmode option was specified.

• w

  Corresponds to digits 2, 5, and 8 of the output when the -fmode option was specified.

• x

  Corresponds to digits 3, 6, and 9 of the output when the -fmode option was specified.

mode

Specifies an 8-digit numeric value or symbol. You can specify mode when you specify the -fmode option.

• Specifying a numeric value

  Specify an octal number. If a non-octal number or a value that is greater than the octal value 07777 (4095 in decimal) is specified, an error occurs.

• Specifying a symbol

  Specify setting, addition, or deletion when nothing is specified (0 in the numeric value expression). The specification result of the symbol is output as the result.

  The table below shows what can be specified in a symbol. When specifying multiple items, separate them with a comma (,).

  Order in the symbol	Value that can be specified
  First	Specifies the item for which access permissions are being set. Multiple items can be specified concurrently. The items listed below can be specified. If the specification is omitted, All users is assumed. u: Owner g: Group o: Other a: All users
  Second	Specifies the mode's operation. Executes one of the following processes for the item specified by the first symbol: =: Sets access permission (overwriting). +: Adds access permission. -: Deletes access permission. You use the third symbol to specify the value to be set, added, or deleted. You can specify the second and third symbols following the third symbol. The third symbol can be omitted.
  Third	Specifies the access permission to be set. Multiple values can be specified concurrently. The following values can be specified: r: Read w: Write x: Execute If this symbol is omitted, the item for which access permission is to be set is erased. The erased value is set, added, or deleted according to the second symbol. Addition or deletion alone does not change the value. If s, t, u, g, or o is specified, it will be ignored.

-exec

Specifies that the command line specified in the -r option or the specified job definition script file is to be executed as a child job.

-m {SIMPLE|MINIMUM}

Specifies the mode to be used to output to the standard output or the standard error output. You can specify this option when the -exec option is specified.

For details about the simple output mode and the minimum output mode, see 3.3.4 Suppressing output of information and warning messages to job execution logs.

• SIMPLE

  Runs the child job in the simple output mode.

• MINIMUM

  Runs the child job in the minimum output mode.

A sample script in the child job format is run in the minimum output mode. Therefore, if you use this command within a sample script in the child job format, we recommend that you specify MINIMUM in the -m option.

-r command line

Specifies what is to be executed by a job from the command line. You can specify this option when the -exec option is specified.

The information specified in the -r option is not created as a job definition script file in the spool job directory. Therefore, for the job definition script file name that is displayed, such as in messages, "-r CMDLINE" is displayed, not the absolute path of the job definition script file.

Command line specification

You can specify on the command line any commands that can be described in a job definition script, such as shell operation commands and UNIX-compatible commands. The following example specifies the pwd command, which is a standard shell command:

adshscripttool -exec -m MINIMUM -r pwd

You can specify any contents that can be described in a job definition script file, such as multiple commands separated by command separators. The following example specifies multiple commands on the command line:

adshscripttool -exec -m MINIMUM -r "export DATA=file01 ; pgm001"

If you specify a space on the command line, you must enclose the command line specification in single or double quotation marks (' or "). Because metacharacters, such as $, *, and the semicolon (;), are expanded, depending on the command-execution shell, you must enclose them in double quotation marks (") or use an escape character (\).

Child job output information

If the -r option is specified, "-r CMDLINE" is displayed as the path name of the job definition script file in message texts and in the job definition script operation information that is output by JP1/Advanced Shell; the absolute path of the job definition script file is not displayed.

Positional parameter storage information

If positional parameter $0 is specified for command-line in the -r option, adshexec is stored in $0.

Relationship to the SPOOLJOB_CHILDJOB parameter

Note the following when the command is executed with the -r option specified and MERGE is specified for the SPOOLJOB_CHILDJOB parameter: The values listed below, instead of the absolute path for the job definition script file, are output for the symbols that indicate the start and end of a child job's job execution logs to be output to the root job's job execution logs. For details about the output format when MERGE is specified for the SPOOLJOB_CHILDJOB parameter, see 3.4.1(3) Merging a child job's spool job into the root job's spool job.

• Symbol indicating the start of a child job's JOBLOG

  >>>>>> [JOBLOG] "-r CMDLINE"

• Symbol indicating the end of a child job's JOBLOG

  <<<<<< [JOBLOG] "-r CMDLINE"

• Symbol indicating the start of a child job's standard error output (for normal execution)

  >>>>>> [STDERR] "-r CMDLINE"

• Symbol indicating the end of a child job's standard error output (for normal execution)

  <<<<<< [STDERR] "-r CMDLINE"

• Symbol indicating the start of a child job's standard error output and standard output (for debugging)

  >>>>>> [STDERR,STDOUT] "-r CMDLINE"

• Symbol indicating the end of a child job's standard error output and standard output (for debugging)

  <<<<<< [STDERR,STDOUT] "-r CMDLINE"

"-r CMDLINE" is also displayed as the job definition script file name in the script image file.

job-definition-script-file-path-name

~<path name>((1 to 247 bytes))

Specifies the path name of the job definition script file. You can specify a value when the -exec option is specified.

run-time parameters ~<character string>((1 to 1,022 bytes)))

Specifies the values to be stored in the positional parameters of the command line or job definition script file that is specified in the -r option. You can specify values when the -exec option is specified.

To include a space in a run-time parameter, enclose the character string in double quotation marks (").

To Page Top

Return codes

To Page Top

Usage examples

• The following shows a specification example of the -fowner option and the result that is output to the standard output.

  Contents of job definition script:

  adshscripttool -fowner test.txt

  Result that is output to the standard output:

  MYPC\user1

• The following shows a specification example of the -fentry option and the result that is output to the standard output.

  Contents of job definition script:

  adshscripttool -fentry test.txt

  Result that is output to the standard output:

  BUILTIN\Administrators;NT AUTHORITY\SYSTEM;MYPC\user1;BUILTIN\Users

• The following shows an example in which +w is specified in the -fmode option and the result that is output to the standard output.

  Contents of job definition script:

  adshscripttool -fmode +w

  Result that is output to the standard output:

  0A00A00A0

• The following shows an example in which ug-r is specified in the -fmode option and the result that is output to the standard output.

  Contents of job definition script:

  adshscripttool -fmode ug-r

  Result that is output to the standard output:

  D00D00000

• The following shows an example in which ug-w,u+w is specified in the -fmode option and the result that is output to the standard output.

  Contents of job definition script:

  adshscripttool -fmode ug-w,u+w

  Result that is output to the standard output:

  0A00D0000

• The following shows an example in which 655 is specified in the -fmode option and the result that is output to the standard output.

  Contents of job definition script:

  adshscripttool -fmode 655

  Result that is output to the standard output:

  RRDRDRRDR

• The following shows a specification example of the -fmode option and the result that is output to the standard output (in this example, +w is parsed with the -s w specification).

  Contents of job definition script:

  adshscripttool -fmode -s w +w

  Result that is output to the standard output (the second, fifth, and eighth digits of the result 0A00A00A0 are output):

  AAA

• The following shows a specification example of the -fmode option and the result that is output to the standard output (in this example, 655 is parsed with the -s r specification).

  Contents of job definition script:

  adshscripttool -fmode -s r 655

  Result that is output to the standard output (the first, fourth, and seventh digits of the result RRDRDRRDR are output):

  RRR

• The following shows a specification example of the -fmode option and the result that is output to the standard output (in this example, 655 is parsed with the -s uor specification).

  Contents of job definition script:

  adshscripttool -fmode -s uor 655

  Result that is output to the standard output (the first and seventh digits of the result RRDRDRRDR are output):

  RR

• The following shows an example in which a job definition script is specified to switch the execution of the cacls command on the basis of the symbol parsing result:

  username=`adshscripttool -fowner "$1"`      # Acquires the owner name.
  if [[ $? -ge 1 ]]                           # Error processing of adshscripttool -fowner
  then
    echo "adshscripttool -fowner error."
    return 1
  fi
  modebit=`adshscripttool -fmode $mode`       # Parses the mode. (mode=u+w)
  case $modebit in                            # 0A0000000 is stored in modebit.
    "AA0000000" ) cacls "$1" /E /G $username:C ;;
    "0A0000000" ) cacls "$1" /E /G $username:W ;;     # This cacls is executed.
            "E" ) echo "adshscripttool -fmode error." # Error processing of adshscripttool -fmode
                  return 1 ;;
  esac

• The following shows an example in which a job definition script is specified to delete all ACEs, except for those of the owner and Everyone:

  IFS=\;
  username=`adshscripttool -fowner "$1"`     # Acquires the owner name.
  if [[ $? -ge 1 ]]                          # Error processing of adshscripttool -fowner
  then
    echo "adshscripttool -fowner error."
    return 1
  fi
  set -A entry `adshscripttool -fentry $1`   # Acquires an account name list.
  for i in "${entry[@]}"
  do
    if ! [[ $i == "$username" || $i == "Everyone" ]]
    then
      cacls "$1" /E /R "$i"                  # Deletes all ACEs, except for those of the owner and Everyone.
    fi
  done

• The following shows an example in which a job definition script is specified to switch the execution of the cacls command according only to the definition content for the owner out of the numeric value parsing results:

  username=`adshscripttool -fowner "$1"`     # Acquires the owner name.
  if [[ $? -ge 1 ]]                          # Error processing of adshscripttool -fowner
  then
    echo "adshscripttool -fowner error."
    return 1
  fi
  modebit=`adshscripttool -fmode -s u $mode` # Parses the mode.(mode=644)
  case $modebit in                           # RRD------ is stored in modebit.
    "RRR" ) cacls "$1" /P $username:F ;;
    "RRD" ) cacls "$1" /P $username:C ;;          # This cacls is executed.
    "RDD" ) cacls "$1" /P $username:R ;;
    "DRD" ) cacls "$1" /P $username:W ;;
      "E" ) echo "adshscripttool -fmode error."   # Error processing of adshscripttool -fmode
            return 1 ;;
  esac

• The following shows an example of execution as a child job of the command line export DBPATH=C:\\HOME\\DBUSER; start -q:

  adshscripttool -exec -m MINIMUM -r 'export DBPATH=C:\\HOME\\DBUSER; start -q'

• The following shows an example in which the job definition script file ppstart.ash is executed as a child job:

  adshscripttool -exec -m MINIMUM ppstart.ash

To Page Top

Notes

• When the -fowner and -fentry options are specified, the command must be executed by the owner of the targeted file or folder. If this is not the case, the command might output an error message and terminate with an error.

• You cannot specify the -s option before the -fmode option. If the -s option is specified before the -fmode option, a command parsing error occurs.

• If an internal conflict is detected, the shell being executed is terminated. When an error other than an internal conflict is detected, processing of the shell being executed continues.

• If an error occurs while the security information of the ACEs is being viewed with the -fentry option specified, only the account names of the ACEs that were viewed successfully are output and processing terminates with an error.

• If a child job is executed with the -exec option specified, the command name that will be output to the job execution log is a JP1/Advanced Shell command (adshexecsub command).

To Page Top