User Tools

Site Tools


pub:workwithmergeengine

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
pub:workwithmergeengine [2017/11/09 19:08] – external edit 127.0.0.1pub:workwithmergeengine [2023/09/19 13:35] (current) – [Detail Information] kkramer
Line 25: Line 25:
  Logging Status: *ON                                  Hold Archive Status: *ON    Logging Status: *ON                                  Hold Archive Status: *ON  
  1=Select  3=Copy  4=Delete  5=View  7=Rename  8=Start 9=End  10=Thread 11=Group  1=Select  3=Copy  4=Delete  5=View  7=Rename  8=Start 9=End  10=Thread 11=Group
-                                                                                + 18=Start (FMC0459)                                                                                
              Opt Engine       Description                 Status                              Opt Engine       Description                 Status                
                  DCYTEST      DCY Test                    *NONE                                   DCYTEST      DCY Test                    *NONE                 
Line 106: Line 106:
 **Note:** If the Thread Engine is used, an archive output queue must be specified.     **Note:** If the Thread Engine is used, an archive output queue must be specified.    
  
 +=== Option 18=Start (FMC0459) ===
  
 +This is fundamentally identical to selecting with Option 8, but provides the ability to retain the originating spool file user attributes for the resulting output.   
  
 ===== Add / Maintain Merge Engine ===== ===== Add / Maintain Merge Engine =====
Line 155: Line 157:
   * **Engine Status**: Current status of the engine.   * **Engine Status**: Current status of the engine.
   * **Custom Command**: Command to invoke a [[customengines | custom engine]].   * **Custom Command**: Command to invoke a [[customengines | custom engine]].
-  * **Engine Type**: ***SERIAL** for normal processing and ***AGGREGATE** to perform aggregation (see below).+  * **Engine Type**: ***SERIAL** for normal processing and **[[#aggregation_options |*AGGREGATE]]** to perform aggregation. 
   * **Test Type:**: ***FIRST** to process just the first target matched or ***ALL** to process every matching target.   * **Test Type:**: ***FIRST** to process just the first target matched or ***ALL** to process every matching target.
  
Line 200: Line 202:
   * **Spool Attribute Value**: Value to use in the spool attribute test.   * **Spool Attribute Value**: Value to use in the spool attribute test.
   * **Form App**: Form, check or form set to use in processing the spool file. Use F4 to select the form, check or form set from a list of these objects.   * **Form App**: Form, check or form set to use in processing the spool file. Use F4 to select the form, check or form set from a list of these objects.
-  * **Resulting SpoolFile Name**: Optional spool file name for the *USERASCII output spool file. Since *USERASCII spool files can not be viewed through the greenscreen it can be helpful to give the *USERASCII spool file name reflective of its contents.+  * **Resulting SpoolFile Name**: The output PCL spooled file name from iDocs Engines is named “FMGLASER” reflective of its contents. You can specify a resulting spool file name here.  A new enhancement in iDOCS 8 (09/19/23) allows administrators to configure the iDocs Engine to use the originating spool file name as the output PCL spool file name's nameTo configure the iDocs Engine to use the originating spool file’s name as the PCL’s spool file name use *SPLFNAME or *FILE as values in the Resulting SpoolFile Name field on the iDocs Engine line. See the below example where the first line in the iDocs Engine configuration below will use FMGLASER as the PCL File Name in the output. The second line in the iDocs Engine configuration will use the originating spool file’s name as the PCL File Name in the output. 
 +  {{:pub:idocs:splfname.png?600|}} 
   * **Resulting Out Queue**: Outqueue to place the resulting *USERASCII spool file. This is the **electronic document**. Use F4 to specify the outqueue from a list.    * **Resulting Out Queue**: Outqueue to place the resulting *USERASCII spool file. This is the **electronic document**. Use F4 to specify the outqueue from a list. 
  
Line 234: Line 237:
 ===== Aggregation options ===== ===== Aggregation options =====
  
-In iDocs 6.5 the Aggregation Engine feature was added.  This option allows you to combine multiple spool files into a single pdf to be emailed.  By creating the engine as Engine Type Aggregateyou can utilize option F8 to enter the Aggregate Settings+In iDocs 6.5 the Aggregation Engine feature was added.  This option allows you to combine multiple spool files into a single pdf to be emailed.  
 + 
 +The aggregating engine operates by accumulating output until the trigger, as defined on the screen abovereturns true. At that time it outputs the accumulated document ( as one document ) and clears the document cache. This feature has its most common use in creating one unified attachment for email delivery. If there are multiple documents that need be attached to an email, then this feature can amalgamate them into one attachment.
 <html><pre> <html><pre>
-                           Aggregate Setting                                  +  4/21/20                      iDocs Form Suite                       FM0450C3   
-                                                                              + 14:10:15                Engine Definition Maintenance                KKRAMER    
-  Select Form to Combine/Aggregate . . .       *ALL                           +                                                                                 
-                                                                              + Engine Name. . . . . . : SIGMAENG   Description. . : SIGMA Test Engine          
-                                                                              + Archive Out Queue. . . : SIGMASPLF  Archive Library: QGPL                       
-  Sweep the outputs when                                                      + Data Queue . . . . . . : SIGMAENGDQ Dataque Library: QUSRSYS                    
-  AND/OR Field       Op  Value (Characters)                                   + Engine Status. . . . . : *ACTIVE    Custom Command:                             
-         *USRDTA       LASTPAGE                                           + Engine Type  . . . . . : <span style="color: red;">*AGGREGATE</span> Test Type . . .: *FIRST *FIRST, *ALL        
-                                                                              +        Originating        Spool     Spool      Form       Resulting  Resulting  
-                                                                              + Prc Out Queue  Library    Attribute Attribute  App        SpoolFile  Out Queue  
-                                                                              + Grp                                 Value                 Name                  
-                                                                              +     SIGMAIN    QUSRSYS    *FORM    ORDER_ACK  SGACKNW               IN          
-                                                                              +     SIGMAIN    QUSRSYS    *USRDTA  PO610A     SGPOFORM              IN          
-                                                                    More...   +     SIGMAIN    QUSRSYS    *FORM    ORD_SHIPTX SGSO                  IN          
-                                                                              +                                                                                 
-                                                                              +                                                                                 
-   F4=Prompt   F5=Refresh   F10=Save    F12=Previous  +                                                                                 
 +                                                                                 
 +                                                                                 
 +                                                                                 
 +                                                                                 
 +                                                                        More...  
 + F3=Exit   F7=Server View   <span style="color: red;">F8=Aggregation Settings</span>   F12=Previous   F21=CMD     
 +</pre></html>   
 +                                                                                
 +  By creating the engine as Engine Type Aggregate, you can utilize option **F8** to enter the Aggregate Settings. 
 +   
 +<html><pre> 
 +                                                                     FM0450W8  
 +                            Aggregate Setting                                  
 +                                                                               
 +   Select Form to Combine/Aggregate . . . . .   *ALL                           
 +   User program to check aggregate condition.   TTRAN       USERPGM            
 +                                                                               
 +   Sweep the outputs when                                                      
 +   AND/OR Field       Op  Value (Characters)                                   
 +                                                                               
 +                                                                               
 +                                                                               
 +                                                                               
 +                                                                               
 +                                                                               
 +                                                                     More...   
 +                                                                               
 +                                                                               
 +    F4=Prompt   F5=Refresh   F10=Save    F12=Previous    <span style="color: red;">F13=PGM Template</span>      
 +                                                               
 +                                                                              
 </pre></html>                                                               </pre></html>                                                              
  
-The aggregating engine operates by accumulating output until the trigger, as defined on the screen above, returns true. At that time it outputs the accumulated document as one document and clears the document cacheThis feature has its most common use in creating one unified attachment for email deliveryIf there are multiple documents that need be attached to an email, then this feature can amalgamate them into one attachment.+ In the Aggregate Setting screen shown above, the user can either specify a custom program (IDOCS 6.95to handle the business logic of Aggregation __or__ define “Sweep the outputs when”The custom program will override the definition in “Sweep the outputs when” 
 + 
 +**F13** will assist the user in creating a program along with the parameters that the iDocs engine will utilize when calling the the custom program. A sample CL program is shown below. 
 + 
 +<html><pre> 
 +/*¹iDocs sample user program for Aggregate engine·                             + 
 +  ¹Once this program is specified in iDocs aggregate engine,                   + 
 +  ¹iDocs will call it to check if the aggregate criteria is matched or not   + 
 +  ¹if TRUE then &RETURN is 'Y' else &RETURN is blank.                          + 
 +  ¹                                                                            + 
 +  ¹Input parameters:                                                           + 
 +  ¹  - &SPLNAME : SCS spool file name which is being processed by iDocs engine + 
 +  ¹  - &SPLNBR  : SCS spool file number                                        + 
 +  ¹  - &JOBNAM  : SCS spool file job name                                      + 
 +  ¹  - &JOBUSR  : SCS spool file job user                                      + 
 +  ¹  - &JOBNBR  : SCS spool file job number                                    + 
 +  ¹                                                                            + 
 +  ¹Output parameters:                                                          + 
 +  ¹  - &RETURN  : If this parameter is Y then iDocs will complete the group    + 
 + ¹                and aggregate all PCLs in group into 1 PCL                   + 
 +*/ 
 +             PGM        PARM(&SPLNAME &SPLNBR &JOBNAME &JOBUSER + 
 +                          &JOBNBR &RETURN) 
 + 
 +             DCL        VAR(&SPLNAME) TYPE(*CHAR) LEN(10) 
 +             DCL        VAR(&SPLNBR) TYPE(*DEC) LEN(6 0) 
 +             DCL        VAR(&JOBNAME) TYPE(*CHAR) LEN(10) 
 +             DCL        VAR(&JOBUSER) TYPE(*CHAR) LEN(10) 
 +             DCL        VAR(&JOBNBR) TYPE(*CHAR) LEN(6) 
 +             DCL        VAR(&RETURN) TYPE(*CHAR) LEN(1) 
 + 
 +/*¹If &RETURN is 'Y' then it's end of the spool files group, + 
 +¹  and iDocs will aggregate the PCL files into 1 PCL·*/
  
 +             ENDPGM
 +             
 +</pre></html>            
 ===== Daisy Chaining Engines  ===== ===== Daisy Chaining Engines  =====
  
Line 344: Line 415:
   * The **FMGBATCH** subsystem can be created from menu FMGUTILITY, option 1. The default configuration is limited and the configuration should be reviewed by a qualified system administrator.   * The **FMGBATCH** subsystem can be created from menu FMGUTILITY, option 1. The default configuration is limited and the configuration should be reviewed by a qualified system administrator.
   * **Never call** the iDocs engine from the startup program, instead submit it with SBMJOB. If you call it the startup program will never progress beyond the call statement and thus never complete. Additionally CALLing the engine will cause it to run under the user profile running the startup program (user QSYS) which causes problems. iDocs engines will run in any properly configured batch subsystem.   * **Never call** the iDocs engine from the startup program, instead submit it with SBMJOB. If you call it the startup program will never progress beyond the call statement and thus never complete. Additionally CALLing the engine will cause it to run under the user profile running the startup program (user QSYS) which causes problems. iDocs engines will run in any properly configured batch subsystem.
-  * Program **FMC0462** is a dataqueue engine; use **FMC0460** for a polling engine. (**FRM0471** ends either one).+  * Program **FMC0462** is a data queue engine; use **FMC0460** for a polling engine. (**FMR0471** ends either one).
   * The **one parameter** to the FMC0462 or FMC0460 call should be the name of the engine in upper case.   * The **one parameter** to the FMC0462 or FMC0460 call should be the name of the engine in upper case.
   * The **job name** should be the engine name in upper case.   * The **job name** should be the engine name in upper case.
Line 394: Line 465:
  
 The user profile should have access to the iDocs library:\\ The user profile should have access to the iDocs library:\\
-**GRTOBJAUT OBJ(FMG) OBJTYPE(*LIB) USER(IDOCS) AUT(*ALL)**\\ +**GRTOBJAUT OBJ(**//iDocs library//**) OBJTYPE(*LIB) USER(IDOCS) AUT(*ALL)**\\ 
-**GRTOBJAUT OBJ(FMG/*ALL) OBJTYPE(*ALL) USER(IDOCS) AUT(*ALL)**+**GRTOBJAUT OBJ(**//iDocs library//** /*ALL) OBJTYPE(*ALL) USER(IDOCS) AUT(*ALL)** 
 + 
 +You may use the below command to __permanently__ grant the required permissions for iDocs:\\ 
 +**CHGAUT OBJ('/qsys.lib/**iDocs.library**/*') USER(*PUBLIC) DTAAUT(*RWX) OBJAUT(*ALL)**\\
  
 If there are no object authority issues with iDocs you might want to disable adopted authority on the programs:\\ If there are no object authority issues with iDocs you might want to disable adopted authority on the programs:\\
-**CHGPGM PGM(FMG/*ALL) USRPRF(*USER) USEADPAUT(*NO)**+**CHGPGM PGM(**//iDocs library//** /*ALL) USRPRF(*USER) USEADPAUT(*NO)**
  
 ==== Job Description Settings ==== ==== Job Description Settings ====
Line 418: Line 492:
  
  <html><br/></html>  <html><br/></html>
 +===== Engine Troubleshooting Q & A =====
  
 +**Q.** When I submit the engine it prompts me for the job queue. What is this?\\
 +**A.** A job queue is an IBM i object that contains entries for jobs that are waiting to be processed by the system.
 +
 +**Q.** When I submit the engine it runs normally, but afterwards no one else can process their jobs submitted to batch?\\
 +**A.** In this case the engine has been submitted to a single thread job queue that can only process a single job at a time. The solution to this bottleneck is to submit the engine to a multi thread job queue. Create one or use a pre-configured multi thread job queue such as QS36EVOKE.
 +
 +**Q.** Polling Engine starts for 60 seconds and ends normally without processing any entries?\\
 +**A.** Check each originating output queue and insure that they all still exist on the system.
 +
 +**Q.**The engine runs and the original spool fie is successfully copied to the archive out queue, yet the merged spool file disappears.\\
 +**A.** The writer may not be responding correctly. Follow these steps to fix the writer: end the writer, vary off the device, vary on the device with a reset, restart the writer. If this doesn't resolve the issue, verify that the printer is HP4 compatible.
 +
 +**Q.** After the engine is submitted, it ends several days later in error?\\
 +**A.** There could be numerous reasons why the engine has ended in error after successfully running without interruption. Most common is that the engine has been running for many weeks accumulating system resources and job structures. **It is recommended that an engine be stopped and restarted weekly.** Other specific causes:\\ 
 +  *   A lock on the engine record has occurred from a backup routine. Its best to make a single backup of the iDocs library whenever the definitions have been added or altered and set it aside, then remove the iDocs library from the backup definition.
 +  *   An engine will end abnormally if the job's message queue has filled up. This could be the case if the engine has been running for weeks. To remedy this type of abnormal end change the system value QJOBMSGQFL value to *WRAP. This will prevent the job queue from filling up. CHGSYSVAL SYSVAL(QJOBMSGQFL) VALUE(*WRAP).
 +  * If the engine has been running for weeks, it could end abnormally if it exceeds the maximum printer output files that can be created per job. Support was added to V5R1M0 to allow a job to create up to 999,999 spooled files. To remedy this type of abnormal end change the IBM i system value QMAXSPLF value from the default value of 9999 to the maximum of 999999. CHGSYSVAL SYSVAL(QMAXSPLF) VALUE(999999). 
 +  * If the engine is processing a large volume of spool files there could be an abend due to 'QSPOOL job not closing'. Keeping spooled files with jobs allows job commands such as Work with Submitted Jobs (WRKSBMJOB) to work with the spooled files even after the job has ended. Detaching spooled files from jobs reduces the use of system resources by allowing job structures to be recycled when the job ends. The default for QSPLFACN is *KEEP. CHGSYSVAL SYSVAL(QSPLFACN) VALUE(*DETACH): When the job ends, the spooled files are detached from the job and the job is removed from the system.
 +
 +Note: You must have *ALLOBJ and *SECADM special authorities to change system values. A change to the system value takes effect immediately; therefore, there is no need to IPL the system after making the change.
 +
 +
 +
 + <html><br/></html>
  
 ---- ----
pub/workwithmergeengine.1510283314.txt.gz · Last modified: 2022/06/25 17:02 (external edit)