11.3.1 adshcollect command (collects information)
Syntax
adshcollect maintenance-information-output-directory [-f definition-file-name] [-e environment-file-name] [-h logical-host-name]
Description
The adshcollect command enables batch-collection of the information required to investigate a failure.
To execute the adshcollect command, you start it from the command prompt in the case of Windows or from the shell in the case of UNIX.
In order to collect error information in the event of a failure, this command must be executed with the permissions of the executing user. However, to collect user-reply functionality information, it must be executed with an administrator role.
Collect the environment file that was being used when the failure occurred. If the environment file has been modified since the error occurred, reconstruct the environment file to match the operational environment at the time the failure occurred. If no environment file was being used when the failure occurred, there is no need to collect one.
- Note:
In the Windows edition, the adshcollect command might result in an error if an ampersand (&) is specified in an environment file.
If an ampersand (&) is specified in the job environment file, make a copy of the job environment file and delete the ampersand (&) from the copied file. In step 3, specify the copied job definition file in the -e option.
If an ampersand (&) is specified in the system environment file, make a backup by copying the system environment file to another directory and then delete the ampersand (&).
Create a definition file.
For collecting a core file or dump file, create a definition file at any location. There is no need to create a definition file except when a core file or dump file is required.
Execute the adshcollect command.
Specify the arguments described below and execute the adshcollect command. For notes on executing the adshcollect command, see Notes, below.
- Maintenance information output directory
Note the following points about the directory specified for the maintenance information:
The output directory for the maintenance information must be writable, and it must have sufficient space.
It must also be a directory that is not being used in JP1/Advanced Shell.
- Environment file name
Specify the path of the environment file collected in step 1 in the -e option or the ADSH_ENV environment variable. This specification is required only if an environment file was collected in step 1.
- Definition file name
Specify in the -f option the path of the definition file created in step 2. This specification is required only if a definition file was created in step 2.
- Logical host name
If the environment in which the failure occurred is a logical host, specify the logical host name in the -h option. This specification is required only if the environment in which the failure occurred is a logical host.
Arguments
- maintenance-information-output-directory
- Windows only
The files containing maintenance information are output to a destination directory. The directory name is in the following format:
ADSHyyyymmddhhmmss
yyyymmdd: Date when the adshcollect command was started
hhmmss: Time, in 24-hour local time, when the adshcollect command was started
Because Windows does not provide as a standard feature the equivalent of the UNIX tar command for handling maintenance information, you must use a user compression tool to compress the files in a standard format (such as ZIP or LZH).
- UNIX only
Specifies a destination directory for the tar archive files of collected information. Any required temporary files will also be created in this directory. The name of the archive file is in the following format:
ADSHyyyymmddhhmmss.tar
yyyymmdd: Date when the adshcollect command was started
hhmmss: Time, in 24-hour local time, when the adshcollect command was started
The disk space required for the compressed file containing maintenance information is as follows:
Size of system execution logs and trace logs + size of files specified in DUMP or CORE#
- #
DUMP files in a Windows environment and CORE files in a UNIX environment.
- -f definition-file-name
Specifies the name of the definition file that defines the maintenance information to be collected. You can specify the definition file in terms of an absolute path or a path relative to the current directory. For the contents to be set up, see Definition file and environment file settings, below.
Specification of a definition file name is optional. If definition-file-name is omitted, the DUMP or CORE maintenance information will not be collected.
- -e environment-file-name
Specifies an environment file when you want to specify a different file path from the one specified in the ADSH_ENV environment variable. You can specify an absolute path or a path relative to the current directory.
When this option is not specified
The file path specified in the ADSH_ENV environment variable is used for the environment file.
When this option and the ADSH_ENV environment variable are both not specified
Information is collected on the basis of the applicable settings in the system environment file.
When this option and the ADSH_ENV environment variable are both not specified and there is no system environment file
The default values for SPOOL_DIR, LOG_DIR, and TRACE_DIR are used.
- -h logical-host-name
Specifies the name of the logical host where the error information is to be collected. The environment file is parsed based on the specified logical host name.
If the -h option is specified but no logical host name is specified, the logical host name is obtained from the JP1_HOSTNAME environment variable. If the JP1_HOSTNAME environment variable is not defined, the command outputs usage information and terminates with an error. For details about the JP1_HOSTNAME environment variable, see the JP1/Base User's Guide.
Definition file and environment file settings
Define the information to be collected in a definition file and define the output destination for the collected information in an environment file.
Defining the definition file
The definition file contains #-adsh_conf
1, followed by keywords and their values delimited by the space. Specify all file names in terms of their absolute paths.
The table below shows the rules for keyword specifications in the definition file. Although all keywords are optional, nothing other than keywords, including comments, is permitted in the definition file. Note that no wildcard characters can be specified in any keyword value.
Table 11‒7: Rules for keyword specifications in the definition file Keyword
Specification contents
Specify more than once
DUMP (Windows only)
Specifies a dump file you want to collect, such as a Watson log. For details about Watson logs, see the Windows documentation.
If there are any spaces in the path, enclose the path in double quotation marks.
Y
(maximum of 16)
CORE (UNIX only)
Specifies a directory where core files can be found that need to be collected as error information. Files under the specified directory that have core as part of their name will be batch-collected.
Y
- Legend:
Y: Can be specified.
Defining the environment file
The table below shows the rules for keyword specifications in the environment file. All keywords are optional. If no keyword is specified, the information described under Default path name in the table will be collected. Note that no wildcard characters can be specified in any keyword value.
Table 11‒8: Rules for keyword specifications in the environment file Keyword
(environment setting parameter)
Specification contents
Default path name
Specify more than once
SPOOL_DIR
Path name of the spool root directory#
In the execution environment (Windows only)
shared-documents-folder\Hitachi\JP1AS\JP1ASE\spool
In the development environment (Windows only)
shared-documents-folder\Hitachi\JP1AS\JP1ASD\spool
In the execution environment (UNIX only)
/var/opt/jp1as/spool
N
LOG_DIR
Path name of the system execution log output directory#
In the execution environment (Windows only)
shared-documents-folder\Hitachi\JP1AS\JP1ASE\log
In the development environment (Windows only)
shared-documents-folder\Hitachi\JP1AS\JP1ASD\log
In the execution environment (UNIX only)
/opt/jp1as/log
N
TRACE_DIR
Path name of the trace log output directory#
In the execution environment (Windows only)
common-application-data-folder\Hitachi\JP1AS\JP1ASE\trace
In the development environment (Windows only)
commmon-application-data-folder\Hitachi\JP1AS\JP1ASD\trace
In the execution environment (UNIX only)
/opt/jp1as/trace
N
- Legend:
N: Cannot be specified.
- #
In Windows, if there are spaces in the path, enclose the path in double quotation marks.
Example definition file and environment file specifications
In Windows
The following is an example of specifying the definition file:
#-adsh_conf DUMP "C:\Program Files\Hitachi\JP1AS\JP1ASE\dump"
The following is an example of specifying the environment file:
#-adsh_conf SPOOL_DIR "C:\Documents and Settings\All Users\Documents\Hitachi\JP1AS\JP1ASE\spool" #-adsh_conf LOG_DIR "C:\Documents and Settings\All Users\Documents\Hitachi\JP1AS\JP1ASE\log" #-adsh_conf TRACE_DIR "C:\Documents and Settings\All Users\Application Data\Hitachi\JP1AS\JP1ASE\trace"
In UNIX
The following is an example of specifying the definition file:
#-adsh_conf CORE /home/user1/program1
The following is an example of specifying the environment file:
#-adsh_conf SPOOL_DIR /var/opt/jp1as/spool #-adsh_conf LOG_DIR /opt/jp1as/log #-adsh_conf TRACE_DIR /opt/jp1as/trace
List of files collected by the adshcollect command
The files collected by the adshcollect command and their maximum sizes are different in Windows and UNIX, as shown in the following tables.
File type |
File name |
Maximum size |
Collected |
---|---|---|---|
Spool management file |
[SPOOL_DIR in the environment file#]\adsh.jobid |
About 1 KB |
Y |
System execution log (JP1/Advanced Shell) |
[LOG_DIR in the environment file#]\AdshLog.log [LOG_DIR in the environment file#]\AdshLog_n.log (where n is the log file count) |
[LOG_FILE_SIZE in the environment file] |
Y |
[LOG_DIR in the environment file#]\AdshLog.conf |
About 1 KB |
Y |
|
Execution log for JP1/Advanced Shell internal processing |
commmon-application-data-folder\Hitachi\JP1AS\JP1ASE\uxpl\spool\uxpllog[n].txt (where n is the log file count, maximum 2) |
5 MB |
Y |
commmon-application-data-folder\Hitachi\JP1AS\JP1ASD\uxpl\spool\uxpllog[n].txt (where n is the log file count, maximum 2) |
5 MB |
Y |
|
commmon-application-data-folder\Hitachi\JP1AS\misc\uxpl\spool\uxpllog[n].txt (where n is the log file count, maximum 2) |
5 MB |
Y |
|
Trace log (JP1/Advanced Shell) |
[TRACE_DIR in the environment file#]\AdshTrace_[n].log (where n is the log file count: fixed at 4) Can be changed in the environment file. |
[TRACE_FILE_SIZE in the environment file] |
Y |
Trace log (custom job) |
commmon-application-data-folder\Hitachi\JP1AS\JP1ASV\trace\AdshTrace_1.log |
1 MB |
Y |
Trace log (editor) |
commmon-application-data-folder\Hitachi\JP1AS\JP1ASD\adshedit\trace\AdshTrace_1.log |
1 MB |
Y |
Trace log (JP1/Advanced Shell, JP1/Advanced Shell - Developer common commands) |
commmon-application-data-folder\Hitachi\JP1AS\misc\trace\AdshTrace_[n].log (where n is the log file count) |
8 MB |
Y |
Trace log (editor-specific features) |
commmon-application-data-folder\Hitachi\JP1AS\JP1ASD\adshedit\trace\adshedit.txt |
Depends on user environment settings. |
Y |
Log of the application-execution agent functionality (only for the execution environment) |
commmon-application-data-folder\Hitachi\JP1AS\JP1ASE\appexec\APPEXECAGENT.log commmon-application-data-folder\Hitachi\JP1AS\JP1ASE\appexec\APPEXECAGENT_n.log (where n is the log file count) |
About 5 MB |
Y |
Dump file |
Dump file in DUMP in the definition file |
Depends on user environment settings. |
O |
Environment file |
File in the ADSH_ENV environment variable, or file specified in the -e option |
About 1 KB |
O |
System environment file |
commmon-application-data-folder\Hitachi\JP1AS\product-name\conf\adshrc.ase |
About 1 KB |
O |
Host name set in the machine |
system-root-folder\system32\drivers\etc\hosts |
Depends on user environment settings. |
Y |
Service ports set in the machine |
system-root-folder\system32\drivers\etc\services |
Depends on user environment settings. |
Y |
Environment information file |
ADSHTMPyyyymmddhhmmss.txt
|
Depends on user environment settings. |
Y |
- Legend:
Y: Always collected by the adshcollect command.
O: Collected when the applicable adshcollect command option is specified.
- #
-
You can change the setting in the environment file. For default value of path name, see the above table.
File type |
File name |
Maximum size |
Collected |
---|---|---|---|
Spool |
[SPOOL_DIR in the environment file#]/.jobid |
About 1 KB |
Y |
System execution log |
[LOG_DIR in the environment file#]/AdshLog.log [LOG_DIR in the environment file#]/AdshLog_[n].log (where n is the log file count) |
[LOG_FILE_SIZE in the environment file] |
Y |
[LOG_DIR in the environment file#]/AdshLog.conf |
About 1KB |
Y |
|
Trace log |
[TRACE_DIR in the environment file#]/AdshTrace_[n].log (where n is the log file count) |
[TRACE_FILE_SIZE in the environment file] |
Y |
Core file |
Core file in the CORE keyword that is collected in the definition file |
Depends on user environment settings |
O |
User-reply functionality management daemon information |
Start log and pid file under /opt/jp1as/system |
About 1 KB |
Y |
Environment file |
File in the ADSH_ENV environment variable or file specified in the -e option |
About 1 KB |
O |
System environment file |
/opt/jp1as/conf/adshrc.ase |
About 1 KB |
Y |
Installed Hitachi products |
/etc/.hitachi/pplistd/pplistd |
Depends on user environment settings. |
Y |
Environment variables |
|
Depends on user environment settings. |
Y |
Environment information file |
ADSHTMPyyyymmddhhmmss.txt
|
Depends on user environment settings. |
Y |
Tar logs |
ADSHTARyyyymmddhhmmss.txt
|
About 1 KB |
Y |
- Legend:
Y: Always collected by the adshcollect command.
O: Collected when the applicable adshcollect command option is specified.
- #
-
You can change the setting in the environment file. For default value of path name, see the above table.
Notes
The maintenance information output directory must have adequate free space for the output files and temporary files to be created there.
The maintenance information output directory must be writable so that the output files and temporary files can be created there.
If the adshcollect command is forcibly terminated during execution, temporary files might still remain in the maintenance information output directory. In such a case, you will have to delete the temporary files manually.
(UNIX only) If you are using the user-reply functionality, execute the adshcollect command as a user with root privileges. If you execute it as a user without root privileges, you will not be able to collect the user-reply functionality information.
(Windows only) If you are using the user-reply functionality, execute the adshcollect command as a user with Administrators permissions. If you execute it as a user without Administrators permissions, you will not be able to collect the user-reply functionality information.
Do not specify any of the following special characters in the path of an output directory for maintenance information, environment file path, definition file path, path specified in SPOOL_DIR, LOG_DIR, or TRACE_DIR, DUMP path, CORE path, or the current directory path for executing the adshcollect command:
& ( ) [ ] { } ^ = ; ! ' + , ` ~ # %
If you specify an option for any of the adshcollect command arguments maintenance-information-output-directory, environment-file-name, definition-file-name, or logical-host-name, the option will be interpreted as the directory or file name or logical host name.