[ Up To Index ]
Merge engines are processes that watch outqueues. When a spool file arrives in the outqueue or is released in it the engine proceeds through the specified tests looking for a match with the spool file. If a match is found the engine processes the spool file with the specified form, check or form set and moves the original spool file to the archive outqueue.
The engine is a Data Queue Engine if a data queue is given. Otherwise the engine is a Polling Engine. Data Queue Engines block until a spool file arrives or is released in the outqueue and therefore are more economical with system resources than Polling Engines, which periodically poll the outqueue.
Engines are batch jobs that run in batch subsystems. The iDocs Utility Menu has an option to create the FMGBATCH subsystem if the user does not wish to run engines in QBATCH.
Option 4 from menu IDOCS displays the list of all defined engines:
4/29/08 iDocs Form Suite FM0450C1 11:27:42 Engine Definition Maintenance QSECOFR 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 18=Start (FMC0459) Opt Engine Description Status DCYTEST DCY Test *NONE POLLING Test Engine *NONE QUICKTEST QuickTest *NONE TESTCDA Test Engine cda *NONE TESTENG Test Engine *NONE MYENGINE My Engine *NONE Bottom F3=Exit F6=Add F7=Toggle Logging F8=Toggle Hold Status F21=Command
The status display shows the current status of the engine.
|Logging Status:||*ON - Engine logging is active|
|Hold Archive Status:||*ON - Archived entries will be placed on hold status|
Logging is a debugging tool. *ON enables engine logging and each engine process will record an entry in a data base file named FRMLOGF. Normally this value can be set to *OFF.
Hold Archive *ON places the resulting FMGLASER entries on hold (HLD) in the designated Archive output queue. An *OFF designation leaves the entries with a ready (RDY) status.
The status display shows the current status of the engine.
|*NONE - the engine is not running|
|*ACTIVE - the engine is running in a subsystem|
|*JOBQ - the engine is waiting in a jobqueue to enter a subsystem to run|
Note: For the display to detect a running engine, the job name in the subsystem must be the engine name. This setting is automatically made when launching the engine from this display using option 8. If you are manually starting an engine with the Submit Job command (SBMJOB) you must set this parameter:
SBMJOB CMD(CALL PGM(FMC0462) PARM('MYENGINE')) JOB(MYENGINE)
The above command starts a data queue engine named MYENGINE, specifying MYENGINE as the job name. MYENGINE will now show active in the engine display screen.
There is the same issue with automatic start/stop of engines.
Select this option to start the engine into a subsystem as a batch job. Specify the appropriate jobqueue at the prompt. Use QS36EVOKE if the subsystem FMGBATCH is not set up, otherwise use FMGJOBQ. Bear in mind that this subsystem and jobqueue should be multi-threaded. The QBATCH jobqueue ships from IBM as single threaded. The subsystem FMGBATCH and its jobqueue FMGJOBQ ship configured to support 2 concurrent engines. Any properly configured jobqueue that routes into any properly configured subsystem may be specified.
Select this option to end an engine. A datqueue engine will stop at the next point of inactivity. A polling engine will stop at the time of its next polling cycle, i.e. at the end of its wait period.
Select this option to start the data queue engine as a Thread Engine. A Thread engine is used when large print volumes are anticipated. It will prevent the 9999 spooled file limit for a data queue, where a job will error out when it has reached it max and need to be restarted. Each spool file job is batched instead of being run interactively. The batch jobs are sent to jobq QTXTSRCH as the default. The data area FMG/DSJOBQMON is used to store the default job queue used and can be changed if desired.
Note: If the Thread Engine is used, an archive output queue must be specified.
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.
To work with merge engines, go to menu IDOCS and take
4. Work with Engines
Use F6 to create a new engine or select an existing engine (not running) with option 1.
3/15/14 iDocs Form Suite FM0450C3 07:37:01 Engine Definition Maintenance DYOKANA Engine Name. . . . . . : IDOCSENG Description. . : iDocs Engine Archive Out Queue. . . : ARCHIVE Archive Library: IDOCS661 F4=List Data Queue . . . . . . : IDOCSDTAQ Dataque Library: IDOCS661 Engine Status. . . . . : Custom Command: Engine Type . . . . . : *SERIAL Test Type . . .: *FIRST *FIRST, *ALL Originating Spool Spool Form Resulting Resulting Prc Out Queue Library Attribute Attribute App SpoolFile Out Queue Grp F4=List F4=List Value F4=List Name F4=List IN QUSRSYS *FORM INVOICE INVOICE OUT More... F3=Exit F4=Prompt F7=Server View F8=Aggregation Settings F12=Previous F21=CMD 5250 MW 075/012
These are tests applied to each spool file arriving in the outqueue. A spool file is processed once with the form, check or form set specified for the first test that returns true.
|Originating Outqueue Considerations|
|Do not monitor outqueues attached to a printer or monitored by another engine as which entity will process the spool file is unpredictable. Use F4 to select the outqueue from a list.|
|Do not monitor an outqueue with the same name as any engine as the engine uses an outqueue by its own name in FMG as a work outqueue.|
|Resulting Outqueue Considerations|
|Specify *FORMDEF to use the destination outqueues from the form definition.|
|Any destination outqueue specified in the form will override this.|
|DO NOT specify an outqueue in library FMG of the same name as the engine.|
Originating Spool Spool Form Resulting Resulting Prc Out Queue Library Attribute Attribute App SpoolFile Out Queue Grp F4=List F4=List Value F4=List Name F4=List PRT02 QUSRSYS *FORM *STD DEMOCHK *FORMDEF Archive Queue: Library: Second File: Archive Queue: Library: Second File:
From the main screen you may press F7 to specify these additional parameters:
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 above, returns 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.
4/21/20 iDocs Form Suite FM0450C3 14:10:15 Engine Definition Maintenance KKRAMER Engine Name. . . . . . : SIGMAENG Description. . : SIGMA Test Engine Archive Out Queue. . . : SIGMASPLF Archive Library: QGPL Data Queue . . . . . . : SIGMAENGDQ Dataque Library: QUSRSYS Engine Status. . . . . : *ACTIVE Custom Command: Engine Type . . . . . : *AGGREGATE 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 SIGMAIN QUSRSYS *FORM ORD_SHIPTX SGSO IN More... F3=Exit F7=Server View F8=Aggregation Settings F12=Previous F21=CMD
By creating the engine as Engine Type Aggregate, you can utilize option F8 to enter the Aggregate Settings.
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 F13=PGM Template
In the Aggregate Setting screen shown above, the user can either specify a custom program (IDOCS 6.95) to 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.
/*¹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
One of the architectural advantages of the iDocs Suite is that a spool file can be processed by multiple engines serially. This enables functionality impossible within one form, formset or engine.
The key mechanism of daisy chained engines is the engine archive outqueue. The normal use of the archive outqueue is to store the original spool file for re-use. However, it can be used to hand off the original spool file to another engine by specifying as the archive outqueue an outqueue that is monitored as an originating outqueue by another engine.
------------- -------------- ------------- ------------ --------------- / engine 1 / -->>> / engine / -->>>> / engine 1 / -->>>> / engine 2 / -->>> / engine 2 / / orig outq / / 1 / / archive \ / / / / archive outq / ------------ -------------- / engine 2 / ------------ ---------------- | / orig outq/ | \ -------------- \ \ \ ----------- ----------- / normal / / normal / / output / / output / ------------ ------------
The engine setups would look something like this:
Engine 1 Setup:
6/08/10 iDocs Form Suite FM0450C3 11:27:27 Engine Definition Maintenance DYOKANA Engine Name. . . . . . : ENGINE1 Description. . : First Engine Archive Out Queue. . . : ARCHIVE1 Archive Library: FMG F4=List Data Queue . . . . . . : DTAQ1 Dataque Library: FMG Engine Status. . . . . : Custom Command: Remove Over Printing: N Originating Spool Spool Form Resulting Resulting Prc Out Queue Library Attribute Attribute App SpoolFile Out Queue Grp F4=List F4=List Value F4=List Name F4=List ORIGOUTQ1 FMG *FORM *STD FORMAPP1 NORMALOUT1
Engine 2 Setup:
6/08/10 iDocs Form Suite FM0450C3 11:27:27 Engine Definition Maintenance DYOKANA Engine Name. . . . . . : ENGINE2 Description. . : Second Engine Archive Out Queue. . . : ARCHIVE2 Archive Library: FMG F4=List Data Queue . . . . . . : DTAQ2 Dataque Library: FMG Engine Status. . . . . : Custom Command: Remove Over Printing: N Originating Spool Spool Form Resulting Resulting Prc Out Queue Library Attribute Attribute App SpoolFile Out Queue Grp F4=List F4=List Value F4=List Name F4=List ARCHIVE1 FMG *FORM *STD FORMAPP2 NORMALOUT2
The normal use of daisy chaining is to automate complex functionality. Some possible uses include:
(i.e. a user can get both an email and a fax )
Engines can be configured to automatically start and stop two ways.
Attention: This change should be done by a properly qualified programmer. A mistake in the startup program can render your system dysfunctional.
Presuming that the FMGBATCH subsystem has been installed and configured on your system, alter the system startup program ( system value QSTRUPPGM ) to execute the following:
ADDLIBLE FMG *FIRST
SBMJOB CMD(CALL PGM(FMC0462) PARM(ENGNAME)) JOB(ENGNAME) JOBD(FMGJOBD) JOBQ(FMGJOBQ) USER(FMGUSER)
You may create generic Job Schedule entries to start and stop engines from menu FMGUTILITY, option 2. See Schedule an Engine to Start/stop .
The easiest way to create entries is with the Utility menu. This option will generate JOBSCDE entries. You can them view the entries (WRKJOBSCDE) and modify them as needed.
Examples: To start and end a Data Queue engine named ENGINE1 in library IDOCS:
To start: CALL PGM(IDOCS/FMC0462) PARM('ENGINE1')
To end: CALL PGM(IDOCS/FMR0471) PARM('ENGINE1')
Essentially, iDocs is a pcl 5e and pcl 5c printer driver for the IBM i. Its output is printer ready pcl. As such its output does not need translating, and in fact such translation may corrupt the output.
There are two considerations:
The profile running the engine ( IDOCS in this section ) should have the following attributes set in the user profile:
The user profile should have access to the iDocs library:
GRTOBJAUT OBJ(iDocs library) OBJTYPE(*LIB) 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:
CHGPGM PGM(iDocs library /*ALL) USRPRF(*USER) USEADPAUT(*NO)
FMGJOBD Job Description has these settings:
This user profile should also have an entry in the system directory; you can use the command ADDDIRE to add the entry:
ADDDIRE USRID(IDOCS LCLSYSTM) USRD('iDocs user profile') USER(IDOCS) SYSNAME(*LCL)
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:
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.
[ Up To Index ]