13.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 client job
-
Collect files from client to relay system job
-
Acquire collected files from relay system job
-
Delete collected files from relay system 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] [/LC {ON|OFF}]
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 client 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 Collect files from client to relay system 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 system job. In the parameter file (or command argument), specify the job destination (relay system).
-
NETM_COLRESET
When the processing key is NETM_COLRESET, this command executes a Delete collected files from relay system job. In the parameter file (or a command argument), specify the job destination (relay system).
-
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.
-
-
/LC
In the argument /LC, write ON or OFF to specify whether to continue command processing even if you log off from Windows while executing this command as a background service by using the Task Scheduler or JP1/AJS.
-
ON
Continues command processing, even when you log off from Windows.
-
OFF
Forcibly ends command processing when you log off from Windows.
This argument is effective when this command is executed from a service on the following OS:
-
Windows Server 2003
When you enter this command from the command prompt, this command is executed as a foreground program. Therefore, in such cases, do not specify /LC ON.
You can also use a registry to set whether to continue command processing, even if you log off from Windows.
Note that the command operation differs depending on the combination of the specification of the argument /LC and the setting in the registry. For details, see 13.20 Command operation at logoff according to registry setting and logoff option.
-
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.
Specification content of parameter file |
Content |
Whether to specify |
Command argument |
|
---|---|---|---|---|
Tag |
Parameter |
|||
group |
Host group name |
Y#1 |
/g value |
|
host_name |
Host name |
Y#1 |
/h value |
|
destination_id |
ID name |
Y#1 |
/X value |
|
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_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_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 |
|
expiration_date |
Limit on package storage in relay system |
N |
-- |
|
expiration_days |
Number of days of package storage in relay system |
N |
-- |
|
installation_date_and_time |
Installation date and time |
N |
-- |
|
installation_timing |
Installation (collection) timing |
Y/N |
/tS or /tN |
|
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 |
-- |
|
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 |
/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 [/LC {ON|OFF}]
- To collect collected files from the relay server or delete collected files in the relay system:
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 [/LC {ON|OFF}]
- To unarchive files:
dcmcoll.exe NETM_UNARC [/G] [/Z] /z file-or-folder-to-be-unarchived /r storage-folder-for-unarchived-file [/LC {ON|OFF}]
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.
-
-
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
The Acquire collected files from relay system job or Delete collected files from relay system job requires a relay system to be specified as the job 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.
-
Notes on execution of remote collection job and restoration of archive file
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= \ }