Skip to main content  
        iSeries home   |   Easy400  
Public-Source
 
Introduction
 
 How to
 
 Download
 
 

 
SYNCJOB  
How to
1- Tight job synchronization   2- Loose job synchronization

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.

  1. 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.

  2. 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.