1-Tight job synchronization
This is the case where a main program, instead of directly calling another program, submits a job performing the program call and immediately enters a wait status
until the submitted job completes its execution. See Figure 2.
This is usually done in the main job to avoid to set up an environment that could prevent the subsequent execution of other tasks.
A common example is a HTTP server CGI job which doesn't want to start a JVM, and would rather submit a job to call a program that starts a JVM, but needs to wait for its completion
in order to provide an adequate response to the client.
Use procedure SBMSYNCJOB() to submit a tightly synchronized job:
D sbmSyncJob pr 10i 0
D sbmCmd 2000 const options(*varsize)
D waitSecs 10i 0 const
D sbmJobname 28
|
| Figure 3 - Procedure SbmSyncJob() to submit a tightly synchronized job |
- Description - A job is submitted to run the command specified in the input variable sbmCmd and the process waits until the submitted job completes execution.
A return code provides information about the completion of the submitted job.
- Input variables:
- A character string (sbmCmd) of up to 2000 characters, containing the command to be executed in the submitted job (example: CALL PGM(...) )
- Wait time (Binary 4): number of seconds to wait for completion of the submitted job.
It MUST be -1 (meaning *NOMAX).
- Output variables:
- Return code (Binary 4): completion status of the submitted job. Possible values:
- 0 - The submitted job completed normally
- -1 - The command to be executed had errors and the job was not submitted
- -2 - The submitted job ended abnormaly.
- sbmJobname - The returned qualified name of the submitted job.
NOTE - The qualified name of the submitted job is returned also in data area QTEMP/SBMTSYNJOB .
RPG CODING EXAMPLE
/copy SYNCJOB/qrpglesrc,hspecsbnd
/copy SYNCJOB/qrpglesrc,prototypeb
/copy SYNCJOB/qrpglesrc,syncjob_p
/copy SYNCJOB/qrpglesrc,usec
D rc s 10i 0
D sbmCmd s 512
D sbmJobname s 28
... ...
D dq s 2 inz('''''')
D dqdq s 5 inz(''''' ''''')
D parm1 s 6 inz('XXXXXX')
D parm2 s 6 inz('YYYYYY')
/free
sbmCmd='CALL PGM(QGPL/PGMA) PARM(' + dq + parm1 + dqdq + parm2 + dq +')';
rc=SbmSyncJob(sbmCmd:-1:sbmJobname); //submit job and wait for its completion
... ... ...
|
| Figure 4 - RPG example of submitting a tightly synchronized job |
See this page for the source of a RPG demo of submitting several tightly synchronized jobs.
CL CODING EXAMPLE
PGM
DCL VAR(&RETCODE) TYPE(*INT)
DCL VAR(&CMD) TYPE(*CHAR) LEN(2000)
DCL VAR(&WAITTIME) TYPE(*INT) VALUE(-1)
DCL VAR(&SBMJOBNAME) TYPE(*CHAR) LEN(28)
... ... ...
DCL VAR(&DQ) TYPE(*CHAR) LEN(2) VALUE('''''')
DCL VAR(&DQDQ) TYPE(*CHAR) LEN(5) VALUE(''''' ''''')
DCL VAR(&PARM1) TYPE(*CHAR) LEN(6) VALUE('XXXXXX')
DCL VAR(&PARM2) TYPE(*CHAR) LEN(6) VALUE('YYYYYY')
... ... ...
CHGVAR VAR(&CMD) VALUE('CALL PGM(QGPL/PGMA) PARM(' +
*CAT &DQ *CAT &PARM1 *CAT &DQDQ *CAT +
&PARM2 *CAT &DQ *CAT ')')
CALLPRC PRC(SBMSYNCJOB) PARM((&CMD) (&WAITTIME) +
(&SBMJOBNAME)) RTNVAL(&RETCODE)
... ... ...
|
| Figure 5 - CL example of submitting a tightly synchronized job |
NOTE - To create such a CL program:
- CRTCLMOD MODULE(mylib/mypgm) SRCFILE(mylib/qclsrc) DBGVIEW(*SOURCE)
- CRTPGM PGM(mylib/mypgm) MODULE(mylib/mypgm) BNDDIR(SYNCJOB/SYNCJOB) ACTGRP(*CALLER)
See this page for the source of a RPG demo of submitting several tightly synchronized jobs.
Command SBMTSYNJOB makes it easier
Instead of writing program code as shown in Figure 4 and Figure 5 above, you may obtain the same result by simply invoking command SYNCJOB/SBMTSYBJOB:
Submit tightly synch.zed job (SBMTSYNJOB)
Type choices, press Enter.
Command to be executed . . . . . CMD ______________________________________
________________________________________________________________________________
________________________________________________________________________________
Prompt command to be executed . PROMPT *NO_ *YES, *NO
|
| Figure 5a - An easier way to submit a tightly synchronized job |
Use this command to submit a job and to wait until the submitted job completes.
NOTE - The qualified name of the submitted job is returned in data area QTEMP/SBMTSYNJOB .
- Command to be executed (CMD) - The command that the submitted job must execute.
- Prompt command to be executed (PROMPT) - Enter
- *YES - to have the command prompted, so that you may specify some parameters.
- *NO - not to prompt the command before executing it.
2-Loose job synchronization
This is the case where a main program, instead of directly calling other programs, submits some jobs performing the program calls,
then continues its own processing and finally waits for the completion of the submitted jobs. See Figure 3.
This is usually done in the main job to reduce execution time through parallel job processing.
Two procedures are used to implement loose job synchronization (parallel job processing): a procedure for submitting the job and a procedure to wait for job completion.
- A - Procedure to submit a loosely synchronized job
Use procedure SBMSYNCJOB() to submit a loosely synchronized job:
D sbmSyncJob pr 10i 0
D sbmCmd 2000 const options(*varsize)
D waitSecs 10i 0 const
D sbmJobname 28
D resource 10
|
| Figure 6 - Procedure SbmSyncJob() to submit a loosely synchronized job |
- Description - A job is submitted to run the command specified in the input variable sbmCmd. The program then continues its execution
and will later on stop and wait for the completion of the submitted job.
A return code provides information about the success of the submit job command.
- Input variables:
- A character string (sbmCmd) of up to 2000 characters, containing the command to be executed in the submitted job (example: CALL PGM(...) )
- Wait time (Binary 4): number of seconds to wait for completion of the submitted job.
It MUST be 0 (meaning "do not wait").
- Output variables:
- Return code (Binary 4): success of the submit job command. Possible values:
- 0 - The job was successfully submitted
- -1 - The command to be executed had errors and the job was not submitted.
- sbmJobname - The returned qualified name of the submitted job.
- resource - A returned resource name to be used in procedure WaitSync() to wait for the completion of the submitted job.
- B - Procedure to wait for the completion of a loosely synchronized job
Use procedure WAITSYNC() to wait for the completion of a loosely synchronized job:
D WaitSync pr 10i 0
D sbmJobName 28
D resource 10
D waitSecs 10i 0 const options(*nopass)
|
| Figure 7 - Procedure WaitSync() to wait for the end of a loosely synchronized job |
- Description - Wait for the completion of a job previously submitted through procedure SbmSyncJob().
A return code provides information about the completion of the submitted job.
- Input variables:
- A 10 character string (sresource) containing a resource name returned by the previous SbmSyncJob() procedure and identifying the submitted job
- Wait time (Binary 4): number of seconds to wait for completion of the submitted job.
This parameter is optional. If specified, it MUST be -1 (meaning *NOMAX). If omitted, -1 is assumed.
- Output variables:
- Return code (Binary 4): completion status of the submitted job. Possible values:
- 0 - The submitted job completed normally
- -2 - The submitted job ended abnormaly
- -3 - The submitted job was still active when the wait time expired
- sbmJobname - The returned qualified name of the submitted job.
RPG CODING EXAMPLE
/copy SYNCJOB/qrpglesrc,hspecsbnd
/copy SYNCJOB/qrpglesrc,prototypeb
/copy SYNCJOB/qrpglesrc,syncjob_p
/copy SYNCJOB/qrpglesrc,usec
D rc s 10i 0
D sbmCmd s 512
D sbmJobname s 28
D resource s 10
... ...
D dq s 2 inz('''''')
D dqdq s 5 inz(''''' ''''')
D parm1 s 6 inz('XXXXXX')
D parm2 s 6 inz('YYYYYY')
/free
sbmCmd='CALL PGM(QGPL/PGMA) PARM(' + dq + parm1 + dqdq + parm2 + dq +')';
rc=SbmSyncJob(cmd:0:sbmJobname); //submit job, don't wait for its completion
... ... ...
... perform further duties ...
... ... ...
// Wait for the completion of the submitted job
rc=WaitSync(sbmjobname:resource);
... ... ...
|
| Figure 8 - RPG example of submitting a loosely synchronized job and waiting later on for its completion |
See this page
for the source of a RPG demo of submitting several loosely synchronized jobs in parallel execution.
CL CODING EXAMPLE
PGM
DCL VAR(&CMD) TYPE(*CHAR) LEN(512)
DCL VAR(&WAITTIME) TYPE(*INT)
DCL VAR(&SBMJOBNAME) TYPE(*CHAR) LEN(28)
DCL VAR(&RESOURCE) TYPE(*CHAR) LEN(10)
DCL VAR(&RETCODE) TYPE(*INT)
DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(256)
... ... ...
DCL VAR(&DQ) TYPE(*CHAR) LEN(2) VALUE('''''')
DCL VAR(&DQDQ) TYPE(*CHAR) LEN(5) VALUE(''''' ''''')
DCL VAR(&PARM1) TYPE(*CHAR) LEN(6) VALUE('XXXXXX')
DCL VAR(&PARM2) TYPE(*CHAR) LEN(6) VALUE('YYYYYY')
... ... ...
CHGVAR VAR(&WAITTIME) VALUE(0) /* do not wait for +
completion of a submitted job */
/*===============================================================*/
/* Submit a loosely synchronized job */
CHGVAR VAR(&CMD) VALUE('CALL PGM(QGPL/PGMA) PARM(' +
*CAT &DQ *CAT &PARM1 *CAT &DQDQ *CAT +
&PARM2 *CAT &DQ *CAT ')')
CALLPRC PRC(SBMSYNCJOB) PARM((&CMD) (&WAITTIME) +
(&SBMJOBNAM1) (&RESOURCE1)) RTNVAL(&RETCODE)
IF COND(&RETCODE *EQ -1) THEN(DO)
CHGVAR VAR(&MSGDTA) VALUE('Command ''' *CAT &CMD +
*TCAT ''' rejected by validity check')
SNDPGMMSG MSGID(CPF9898) MSGF(QSYS/QCPFMSG) +
MSGDTA(&MSGDTA) TOPGMQ(*PRV) MSGTYPE(*ESCAPE)
RETURN
ENDDO
... ... ...
... perform other duties
... ... ...
/*===============================================================*/
/* Wait for the end of the 1st submitted job */
CALLPRC PRC(WAITSYNC) PARM((&SBMJOBNAME) (&RESOURCE)) +
RTNVAL(&RETCODE)
IF COND(&RETCODE *NE 0) THEN(DO)
CHGVAR VAR(&MSGDTA) VALUE('Submitted job ' *CAT +
&SBMJOBNAME *TCAT ' ABNORMALLY ended')
SNDPGMMSG MSGID(CPF9898) MSGF(QSYS/QCPFMSG) +
MSGDTA(&MSGDTA) TOPGMQ(*PRV) MSGTYPE(*ESCAPE)
ENDDO
RETURN
ENDPGM
|
| Figure 9 - CL example of submitting a loosely synchronized job and waiting later on for its completion |
NOTE - To create such a CL program:
- CRTCLMOD MODULE(mylib/mypgm) SRCFILE(mylib/qclsrc) DBGVIEW(*SOURCE)
- CRTPGM PGM(mylib/mypgm) MODULE(mylib/mypgm) BNDDIR(SYNCJOB/SYNCJOB) ACTGRP(*CALLER)
See this page for the source of a RPG demo of submitting several loosely synchronized jobs.
|