14.4 dcmcoll.exe (collecting files)

This section describes the dcmcoll command, which collects files.

You can check the result of a job executed by this command in the Job Status window of the managing server.

Function

This command creates and executes the following jobs related to remote collection:

• Collect files from agent job

• Remote-collect files from agent to relay computer job

• Acquire collected files from relay computer job

• Delete collected files from relay computer job

This command also unarchives collected archive files.

Format

dcmcoll.exe [processing-key] [/G] [/Z] [/s]
            /i parameter-file-1 [parameter-file-2]
            [/o output- file-name]

Arguments

• processing-key

  This argument specifies the type of job to be executed. Specify one of the processing keys listed below immediately after the command name. When this argument is omitted, specification of NETM_COLLECT is assumed.

  • NETM_COLLECT

    When the processing key is NETM_COLLECT, this command executes a Collect files from agent job. In the parameter file (or command arguments), specify the job destination, file to be collected, and storage directory for collected file.

  • NETM_COLTOS

    When the processing key is NETM_COLTOS, this command executes a Remote-collect files from agent to relay computer job. In the parameter file (or command arguments), specify the job destination, file to be collected, and storage directory for collected file.

  • NETM_COLTOM

    When the processing key is NETM_COLTOM, this command executes an Acquire collected files from relay computer job. In the parameter file (or command argument), specify the job destination (a relay system or management relay server).

  • NETM_COLRESET

    When the processing key is NETM_COLRESET, this command executes a Delete collected files from relay computer job. In the parameter file (or a command argument), specify the job destination (a relay system or management relay server).

  • NETM_UNARC

    When the processing key is NETM_UNARC, this command unarchives an archive file (with the extension of dmz). In the parameter file (or command arguments), specify the name of the file to be unarchived, the directory storing the file, and the directory to store unarchived files.

• /G

  When the argument /G is specified and the processing key is NETM_UNARC, this command directly stores unarchived files in the directory specified as the restoration destination. When the processing key is other than NETM_UNARC, this argument is ignored even if specified.

  When the argument /G is omitted, this command automatically generates a directory with the same name as the host name of the job destination under the directory specified as the directory to store unarchived files.

  Do not specify this argument when you need to distinguish the job-destination host from others.

• /Z

  When the argument /Z is specified and the processing key is NETM_UNARC, this command deletes the archive file at the same time as unarchiving the file. The directory having stored the archive file is not deleted.

  When the processing key is other than NETM_UNARC, this argument is ignored even if specified.

• /s

  When the argument /s is specified, this command creates a job, and then stores it without execution. When the processing key is NETM_UNARC, this argument is ignored even if specified.

  When this command is executed with this argument specified, the job number is not output to the output file.

• /i

  In the argument /i, specify one or two full path names of the parameter files to be used. When specifying two full path names, separate them by a space. Specifying more than two full path names will cause this command to fail.

  When two parameter files are specified, JP1/IT Desktop Management 2 interprets individual files while linking their contents with each other. If you define the information on the job destination and the information on file collection and restoration in separate parameter files, you can conveniently change the content of either file when you want to re-execute this command.

  Because unnecessary parameters are ignored, the parameter files can be shared for file collection and file restoration. Specifying the same parameter in both parameter files will cause an error.

• /o

  In the argument /o, specify the full path name of the output file.

  When the processing key is NETM_UNARC, this argument is ignored even if specified. When the processing key is other than NETM_UNARC, always specify this argument.

  When this command ends normally, the items listed below are output to the specified output file. If the output file already contains data, the data is overwritten.

  • Job name

  • Job number

  • Path name of job storage folder

  The job number (value of jobno) identifies the job that is started. When you need to delete the job or check the job status, write the value of jobno to the parameter file.

  When the argument /s is specified, the job number is not output.

  When the argument /s is specified, the output file can be used as a parameter file for the dcmjexe command without change. When the argument /s is not specified, the output file can be used as a parameter file for the dcmjbrm, dcmrtry, dcmstat, and dcmstsw commands.

Correspondence between the specification contents of parameter file and command arguments

The contents of the parameter file for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file and the command arguments corresponding to them.

Table 14‒4: Correspondence between parameter file contents and command arguments (dcmcoll command)

Specification content of parameter file		Content	Whether to specify	Command argument
Tag	Parameter
JOB_DESTINATION	group	Host group name	Y#1	/g value
	host_name	Host name	Y#1	/h value
JOB_DESTINATION_ID	destination_id	ID name	Y#1	/X value
FILE_COLLECTION	source_path	Name of file to be collected	Y#2	/y value
	dmz_path	Storage folder for collected file (for collection) or file/folder to be unarchived (for restoration)	Y#3	/z value
	unarc_path	Storage folder for unarchived file	Y#4	/r value
JOB_ATTRIBUTE	job_generator	Job name	Y/N#5	/j value
	jobno	Job number	N	--
	job_folder	Path name of job storage folder	Y/N	/l value
	unsuspended	Whether to distribute during suspension	N	--
JOB_SCHEDULE	job_entry_date	Job registration date and time	Y/N#6	/jst value
	job_execution_date	Job execution date and time	Y/N#6	/jsx value
	job_expiration_date	Job expiration date	Y/N#6	/jsp value
SCHEDULE	expiration_date	Expiration date of package storage on relay computer	N	--
	expiration_days	The relay computer holds relayed packages for	N	--
	installation_date_and_time	Installation date and time	N	--
	installation_timing	Installation (collection) timing	Y/N	/tS or /tN
OPTION	compress	Whether to compress	Y/N	/uY or /uN
	restore	Whether to restore at upgrade	N	--
	reboot	Computer restart after installation	N	--
	processing_dialog	Whether to display processing message during installation	N	--
USER_PROGRAM_INSTALLATION_CONDITIONS	external_program_executed_before_installation	External program to be started before installation (collection)	Y/N	/b value
	external_program_executed_after_installation	External program to be started after installation (collection)	Y/N	/a value
	external_program_error_handler	External program to be started at installation (collection) error	Y/N#7	/e value
	external_program_handler	External program to be started	N	--
	exit	How to report the processing result of external program	N	--
	action	Action to take when processing result is error	N	--
	wait	Monitoring method	N	--
	timeout	Monitoring time	N	--
	wait_code	Monitoring code	N	--

Command formats without using any parameter file

The following shows the command formats to be used when you specify only command arguments without using a parameter file.

To collect files from managed computers:

dcmcoll.exe {[NETM_COLLECT]|NETM_COLTOS} [/s]
            {[/g host-group- name] [/h host-name]|/X ID-name}
            /y name-of-file-to-be-collected /z path-name-of-storage-folder-for-the-files-to-be-collected
            [/j job-name] [/l path-name-of-job-storage-folder]
            [/jst job-registration-date-and-time] [/jsx job-execution-date-and-time]
            [/jsp job-expiration-date]
            [{/tS|/tN}] [ {/uY|/uN}]
            [/b external-program-to-be-started-before-file-collection]
            [/a external-program-to-be-started-after-file-collection]
            [/e external-program-to-be-started-at-file-collection-error]
            /o output-file-name

To collect or delete files collected on a relay system or management relay server:

dcmcoll.exe {NETM_COLTOM|NETM_COLRESET} [/s]
            {[/g host-group- name] [/h host-name]|/X ID-name}
            [/j job-name] [/l path-name-of-job-storage-folder]
            [/jst job-registration-date-and-time] [/jsx job-execution-date-and-time]
            [/jsp job-expiration-date]
            /o output-file-name

To unarchive files:

dcmcoll.exe NETM_UNARC [/G] [/Z]
            /z file-or-folder-to-be-unarchived
            /r storage-folder-for-unarchived-file

Return codes

The following table lists the return codes that are output when the dcmcoll command is executed:

Code	Meaning	Action to be taken
0	The managing server started the job, or restoration of archive file ended normally.	None
1	The parameter file cannot be opened, or the file format is incorrect.	Check the specification of the parameter file or its description format.
2	An invalid value was specified in a command argument or the parameter file.	Check the values specified in command arguments and the parameter file.
3	Connection to the database failed.	Check database settings in the setup of the managing server.
4	The output file cannot be opened.	Check the specification of the output file.
5	Connection to the JP1/IT Desktop Management 2 service failed.	Check whether the service of JP1/IT Desktop Management 2 - Manager has started.
7	Restoration of one or more archive files failed.	Check the path name of each archive file. The full path name of the archive file might exceed 259 single-byte characters. (The full path name consists of the name of the storage directory for unarchived file, name of file creation directory (name of the storage directory for archive file), and name of unarchived file or directory.)
12	Other error occurred.	Reference the event log.

Notes

• Specifiable numbers of job destinations and the files to be collected

  • When you use the parameter file for specification, you can specify a maximum of 200 job destinations (such as hosts, host groups, and ID groups) per single execution of the dcmcoll command. For 200 job destinations, you can specify a maximum of 100 files or directories to be collected.

  • When using command arguments for specification, you can specify only one job destination and one file to be collected.

  • Even if multiple job destinations and files to be collected have been specified in the parameter file, all those specifications become invalid when a job destination and a file to be collected are specified by using command arguments.

  • When you execute a command, do not specify the same destination more than once. It will execute the same jobs at a destination for multiple times.

• Route to a job destination

  You can specify a route to a job destination. Even if the same job destination is specified as multiple definitions with different routes, only the first definition is valid.

• Jobs destined for a relay system or management relay server

  The Acquire collected files from relay computer and Delete collected files from relay computer jobs specify a relay system or management relay server as the destination. If a managed computer is specified as the destination of either job, the job results in an error, or is kept in the running state.

• Collection-destination and restoration-destination directories

  • When files are collected, a directory with the same name as the job-destination host name is automatically created under the directory specified as the collection destination. Files are archived when they are collected, and stored as an archive file (with the extension.dmz) in the directory whose host name corresponds to the collected files.

  • When an archive file is unarchived, a directory with the same name as the host name corresponding to the archive file is automatically created under the directory specified as the restoration destination (in a similar way to file collection). Note, however, that, if multiple archive files are unarchived at the same time, any files of the same name and included in different archive files will overwrite one another. Therefore, if you want to unarchive multiple archive files, some of which include a file of the same name, execute the dcmcoll command specifying different restoration-destination directories for the different archive files.

  • When an archive file is unarchived by the dcmcoll command with the argument /G specified, files are extracted directly in the directory specified as the restoration destination. If the archive files collected from multiple job destinations are unachieved at a time by the dcmcoll command with /G specified, all extracted files overwrite one another, and cannot be sorted out by job destination. Use the argument /G only when unarchiving a single archive file.

  • When an archive file is unarchived by the dcmcoll command without the argument /G specified, a directory with the same name as the job-destination host name is automatically created under the directory specified as the storage destination for unarchived files. When, however, the directory storing the archive file to be unarchived is specified in the argument /z or the dmz_path parameter in the FILE_COLLECTION tag, no directory is created. Then, files are extracted directly in the directory specified as the storage destination for unarchived files.

    If you need to sort out unarchived files by job destination, specify the directory you specified for file collection in the argument /z or the dmz_path parameter in the FILE_COLLECTION tag.

• Specification of the path name of job storage folder

  When you execute the dcmcoll command specifying the path name of a folder not defined in the Job Definition window as the path name of job storage folder, the specified folder is created. The created job storage folder is not deleted, even after command execution. If you do not use this folder, delete it after the job is complete.

• Points to be noted when not using a parameter file

  • If the collection destination is a workstation (UNIX system), specify any drive as the drive of the collection destination directory. However, the specified drive will be ignored during collection, and files will be collected according to the specified directory. In the following example, the drive name c: is ignored.

    Example: c:/user/tmp

    When you use a backslash (\) to separate each directory, there is no need to specify a drive name.

    Example: \user\tmp

• Notes on specifying external programs

  • If the collection destination is a workstation (UNIX system), and you specify external programs, use a parameter file to execute commands.

• Notes on execution of remote collection job and restoration of archive file

  See 9.1.4 Notes on executing remote collection.

• Notes on execution of the command

  If you pause the command by pressing of the (Ctrl + C, or else) keys during the execution, the job definitions that the command has created might not be deleted.

  If you pause the command, check the job definition window on the remote install manager and delete job definitions if necessary.

Example

The following example shows use of this command to collect files from the directories SDerror.dir, SDerror2.dir, and SDerror3.dir under the directory C:\temp on the hosts dmp491 and dmp492 on which JP1/IT Desktop Management 2 - Agent (agent) is running. The parameter file defines operations to start collection when the managed computer starts, and to activate an external program before and after collection, and if a collection error occurs.

Creating the parameter file

Specify the hosts and the attributes of the files to be collected as shown below, and then save the parameter file under any name.

** dcmcoll Parameter File Sample
 
JOB_DESTINATION{
host_name=dmp492.soft.hitachi.co.jp
host_name=dmp491
group = \grp\gname1
group = \grp\gname2;\grp\gname3
}
SCHEDULE{
installation_timing = S
}
OPTION{
compress=Y
}
USER_PROGRAM_INSTALLATION_CONDITIONS{
external_program_executed_before_installation = "C:\test B.exe"
external_program_executed_after_installation = C:\testA.exe -x "a aa"
external_program_error_handler = "C:\test E.exe"
}
FILE_COLLECTION{
source_path= C:\temp\SDerror.dir
source_path= C:\temp\SDerror2.dir;C:\temp\SDerror3.dir
dmz_path= C:\temp\collection
}

Executing the command

To store the created parameter file as C:\Dmbat\dcmcoll.txt and acquire the output file as C:\Dmbat\out.txt, specify the command as follows:

dcmcoll.exe /i C:\Dmbat\dcmcoll.txt /o C:\Dmbat\out.txt /j tempcollection

Checking the output file

When the command ends normally, the job name, job number, and path name of job storage folder are output to the file C:\Dmbat\out.txt as follows:

JOB_ATTRIBUTE{
job_generator= NETM_COLLECT_03_12_11_13_34_36
jobno= JB03121113315383
job_folder= \
}

To Page Top