adshcollect command (collects information)

Organization of this page

Format
Description
Arguments
Definition file and environment file settings
Example definition file and environment file specifications
List of files collected by the adshcollect command
Notes

Format

adshcollect maintenance-information-output-directory [-f definition-file-name] [-e environment-file-name] [-h logical-host-name]

To Page Top

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.

To Page Top

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

[Figure] yyyymmdd: Date when the adshcollect command was started

[Figure] 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

[Figure] yyyymmdd: Date when the adshcollect command was started

[Figure] 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 Job Management Partner 1/Base User's Guide.

To Page Top

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 [Figure] ₁, 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 10‒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 10‒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.

To Page Top

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

To Page Top

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.

Table 10‒9: Files collected by the adshcollect command and their maximum sizes (Windows only)
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] (`n` + 1) (MB)	Y
System execution log (JP1/Advanced Shell)	[`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] `n` (MB)	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
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` `yyyymmdd`: Date when the `adshcollect` command was started `hhmmss`: Time when the `adshcollect` command was started	Depends on user environment settings.	Y

Legend:

Y: Always collected by the adshcollect command.

O: Collected when the applicable adshcollect command option is specified.

#

Can be changed in the environment file. For the default path names, see Table 10-8 Rules for keyword specifications in the environment file.

Table 10‒10: Files collected by the adshcollect command and their maximum sizes (UNIX only)
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] (`n` + 1) (MB)	Y
System execution log	[`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] `n` (MB)	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 `number of executing user-reply functionality management daemons`	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	AIX or Linux `/etc/environment` HP-UX `/etc/profile` Solaris `/etc/skel/.profile`	Depends on user environment settings.	Y
Environment information file	`ADSHTMPyyyymmddhhmmss.txt` `yyyymmdd`: Date when the `adshcollect` command was started `hhmmss`: Time when the `adshcollect` command was started	Depends on user environment settings.	Y
Tar logs	`ADSHTARyyyymmddhhmmss.txt` `yyyymmdd`: Date when the `adshcollect` command was started `hhmmss`: Time when the `adshcollect` command was started	About 1 KB	Y

Legend:

Y: Always collected by the adshcollect command.

O: Collected when the applicable adshcollect command option is specified.

#

Can be changed in the environment file. For the default path names, see Table 10-8 Rules for keyword specifications in the environment file.

To Page Top

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.

To Page Top