The BLD, BLDB, and REXEC commands support the ability to wait and not return control to Dimensions until the remote task being executed has completed.
Use the following parameters in the BLD, BLDB, and REXEC commands to control wait processing:
/BATCH and /NOBATCH
Default: /BATCH
If you specify /NOBATCH, after the BLD or BLDB command has run it waits in turn for each of the started jobs. You can also set the variable DM_MAX_REXEC_WAIT in dm.cfg to specify the longest wait time (in seconds) for the server. If you do not set this variable, the server waits indefinitely until the database is updated with a job completion record. Each job may succeed or fail. A job may also timeout if you have enabled the timeout option.
Alternatively, use the RLIST <job-id> /WAIT command to achieve the same outcome. If there are different jobs being issued, you can achieve a higher degree of parallelism using the RLIST facility. You can also use the dm.cfg variable DM_MAX_REXEC_WAIT with RLIST.
If a BLD or BLDB command starts more than one job, use the above mechanism to wait for all of them.
When a BLD, BLDB or REXEC command is started, the variable DM_JOB_ID is returned containing the job ID in the form R-uid. If a BLD or BLDB command starts more than one job, DM_JOB_ID is the first job started only. In addition, two other variables are also returned for the BLD and BLDB commands, DM_JOB_NAME and DM_JOB_STATII. Both these variables are arrays.
DM_JOB_NAME has elements with names of the same form as DM_JOB_ID.
DM_JOB_STATII has elements containing SUCCEEDED, FAILED, BACKGROUND, TIMEOUT, or ERROR.
BACKGROUND is only seen when /batch is used.
TIMEOUT appears if DM_MAX_REXEC_WAIT has been exceeded.
ERROR only occurs if there are database errors encountered trying to obtain the job status record.
If a build job starts a known number of builds, for example three, the syntax looks like this:
BLD ... /BATCH
SAVE BIG_NAMES DM_JOB_NAME
a:
RLIST &(BIG_NAMES(0)). /WAIT
RLIST &(BIG_NAMES(1)). /WAIT
RLIST &(BIG_NAMES(2)). /WAIT
Build waits for all three jobs to complete, and additional processing is done at a: to force a higher degree of parallelism. If you use the Dimensions DTK to initiate the processing, the PcmsApi functions PcmsGetSymbolInfo and PcmsGetStringSymbolValue can obtain and work with these data items.
Use the following additional parameters with /WAIT on the REXEC command:
/CAPTURE
Generates a one time certificate.
/BATCH
Distributed platforms: choose between synchronous and asynchronous execution of the REXEC job.
MVS: the started job is always asynchronous and /NOBATCH does not cause a process to wait.
For all platforms, if you use RLIST <job-id> /WAIT you have to connect back to Dimensions and issue an RSTAT command to update the final status of the job. Failure to do so will cause RLIST /WAIT processing for this job to wait indefinitely or time out.
NOTE Check that the client session timeout is less than the maximum time you expect to wait for a job or for jobs to complete.