14.16 dcmstsw.exe (monitoring job execution status)
This section describes the dcmstsw command, which monitors the execution status of a job.
Function
This command monitors (on the managing server) the execution status of a job specified in a parameter file or on the command line, and starts a specified external program when the job enters specified execution status.
Format
dcmstsw.exe [monitoring-interval] [monitoring-condition] /i parameter-file-name
Arguments
-
monitoring-interval
In this argument, specify the interval of monitoring job execution status in seconds. The default monitoring interval is 900 seconds (15 minutes).
-
monitoring-condition
In this argument, specify the timing of starting a specified external program.
-
When ALL is specified, the external program is started when the job enters the specified execution status at all job destinations.
-
When this argument is omitted, the external program is started when the job enters the specified execution status at one or more job destinations.
-
-
/i
In the argument /i, specify the full path name of the parameter file to be used.
You can use also the output file output by the dcmcoll command (without /s specified), dcminst command (without /s specified), or dcmjexe command as the parameter file.
Correspondence between the specification contents of parameter file and command arguments
The contents of the parameter file available for this command can also be specified in command arguments. The following table shows the specification contents of the parameter file, and their corresponding command arguments.
Specification content of parameter file |
Content |
Whether to specify |
Command argument |
|
---|---|---|---|---|
Tag |
Parameter |
|||
job_generator |
Job name |
N |
-- |
|
jobno |
Job number |
Y |
/jn value |
|
job_folder |
Path name of job storage folder |
Y/N#1 |
/l value |
|
unsuspended |
Whether to distribute during suspension |
N |
-- |
|
external_program_executed_before_installation |
External program to be started before installation (collection) |
N |
-- |
|
external_program_executed_after_installation |
External program to be started after installation (collection) |
N |
-- |
|
external_program_error_handler |
External program to be started at installation error |
N |
-- |
|
external_program_handler |
External program to be started |
Y |
/ep value |
|
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 |
Maximum execution period |
Y/N#2 |
/wt value |
|
wait_code |
Monitoring code |
Y/N#3 |
/wc value |
- Legend:
-
Y: The parameter must be specified.
Y/N: The parameter can be omitted.
N: The parameter is not necessary (is ignored even when specified).
--: The content cannot be specified by using a command argument.
- #1
-
If this parameter is omitted, this command searches all the folders or files under the root folder to find the specified job, and then monitors the job's execution status
- #2
-
Specify a value larger than the monitoring interval. The default maximum monitoring period is 86,400 seconds (1 day).
- #3
-
Specify the job execution status or a maintenance code. For details about the value to be specified, see 14.19.20 USER_PROGRAM_INSTALLATION_CONDITIONS (specifying external programs). When this parameter is omitted, the specified external program is started when a job execution error occurs.
Command format without using any parameter file
The following shows the command format to be used when you specify only command arguments without using a parameter file.
dcmstsw.exe [monitoring-interval] [monitoring-condition] /jn job-number [/l path-name-of-job-storage-folder] /ep external-program-to-be-started [/wt maximum-execution-period] [/wc monitoring-code]
Return codes
The following table lists the return codes that are output when the dcmstsw command is executed:
Code |
Meaning |
Action to be taken |
---|---|---|
0 |
The command 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. |
Check the values set in command arguments. |
3 |
Connection to the database failed. |
Check database settings in the setup of the managing server. |
4 |
The specified external program is not found. |
Check the path name of the external program. |
5 |
|
|
12 |
Restoration of one or more archive files failed. |
Reference the event log. Possible causes are a system error, a syntax error in a command argument, or rejection of processing. |
Notes
-
In the parameter file, specify the job number that was output to the output file by the dcmcoll command (without /s specified), dcminst command (without /s specified), or dcmjexe command.
-
This command is terminated when one of the following conditions is met:
-
The external program is started.
-
The time specified as the maximum execution period has passed.
-
All the jobs being monitored end normally when a value other than NORMAL is specified as the monitoring code.
-
The job being monitored is deleted.
-
The managing server stops.
-
-
Do not specify ALL as the monitoring condition when an ID group job is specified as the job to be monitored. Specifying ALL as the monitoring condition causes an error (indicated by the return code 2).
Example
The following example shows use of this command to execute the external program C:\aaa.exe when all the jobs executed by the local managing server end normally. Assume that the monitoring interval is 5 minutes and the maximum execution period is 1 hour.
- Creating the parameter file
-
Specify the job number output to the output file by the dcmjexe command in the parameter file as shown below.
If the output file output by the dcmjexe command has been stored, you can specify the stored file as the parameter file.
** dcmstsw Parameter File Sample JOB_ATTRIBUTE{ job_generator= Collect-slip-file-0001 jobno= JB02100720481602 job_folder= \batch-definition }
- Executing the command
-
When the output file output by the dcmjexe command is stored as C:\DMbat\para\.txt, specify the command as follows:
dcmstsw.exe 300 ALL /i C:\DMbat\para.txt /ep C:\aaa.exe /wt 3600 /wc NORMAL