This is an old revision of the document!
Table of Contents
[ Up to Main Menu ]
The iDocs SmartRouter™
Functionality
The iDocs SmartRouter is a dataqueue engine that sorts, bursts, filters and routes *SCS spool file on a page by page basis, optionally assigning external printer file attributes. It's distinguishing feature is its ability to work simultaneously with external spool file attributes and spool file content.
The top level container is the SmartRouter Definition. The SmartRouter Definition may contain 9,999 application definitions.
The Application definition is the second level container. It may contain 9,999 targets, and may be conditioned upon 9,999 logical tests.
The Target is the output definition. It may also be conditioned upon 9,999 logical tests..
The Condition is a logical test on an external spool file attribute or internal spool file content. Conditions are used to enable or disable applications and to control output to targets.
The Smart Router is bundled into the iDocs Suite. Older standalone versions may still be installed at customer sites.
Installation
The Smart Router is part of the iDocs library and is installed by default. It is a keyed product. Your salesrep can obtain an evaluation license key for you. You will need to install key values PREPRC1 and PREPRC2 using the iDocs key mechanism.
Configuration
To configure the SmartRouter, issue the command SR3 (SmartRouter v3) or take option option 13 iDocs Smart Router from the iDocs menu.
At the first screen you may create up to 9,999 preprocessor definitions.
5/12/09 iDocs SmartRouter PR0010H1 14:50:40 SR Engine Definition Maintenance QSECOFR Type options, press enter. 2=Change 3=Copy 4=Delete 5=View 7=Rename 8=Start 9=End Opt SR Engine Description Status JOBLOG Example Application *NONE Bottom F3=Exit F5=Refresh F6=Add
Use F6 to create or option 2 to change an existing Smart Router definition:
4/24/13 iDocs Smart Router 3.30 PR0010R4 10:30:45 SR Engine Definition Maintenance DYOKANA SR Engine Name/Desc: JOBLOG Job Log Data Queue Name/Lib: JOBLOGDTAQ DCYQC Archive Outque/Lib.: OUTQARC DCYQC Process Spool File.: *JOBQ *CALL, *JOBQ Job Queue Name .: DCYJOBQ *JOBD, Name Library . . . .: DCYQC Job Priority. . .: 9 1-9, *JOBD F4=Prompt F12=Cancel Enter-Output Queue Maintenance 5250 MW 035/004
Do not name the engine beginning with a Q. IBM reserves the letter Q for operating system objects.
Similarly do not use Q as the first letter for the dataqueue name.
- DataQueue name and library: the name of the dataqueue to which the SmartRouter engine will listen for spool files. This dataqueue can not be in use by other dataqueue engines such as those of iDocs, iMail, or iView. The SmartRouting engine will create the dataqueue for you and connect it to the outqueues when you start the engine.
- Archive outqueue and library: endpoint for the original spool file.
- Process Spool File: Specify *JOBQ to process a spool file in a separate job via SBMJOB. The parameters of the SBMJOB call are provided in the next three parameters. Use *CALL to process a spool file via a CALL, resulting in processing in the same job as the engine.
- Job Queue Name: Provide the name of a job queue if processing with the *JOBQ option. Single threaded job queues will process Smart Routing jobs serially. Multi threaded jobqueues will process them concurrently.
- Job Queue Library: Library containing the job queue.
- Job Priority: Priority of the job in the jobqueue.
To configure the use of a jobqueue for processing rather than default call logic in
versions 3.20 and earlier see Engine Processing Mode.
Press <enter> to proceed to the next configuration screen.
9/10/13 iDocs SmartRouter PR0055R1 17:41:12 SR Outqueue Maintenance KKRAMER SR Engine Name/Desc: JOBLOG Job Log Data Queue Name/Lib: JOBLOGDTAQ QC Archive Outque/Lib.: OUTQARC QC Type option, press enter. 4=Delete Outqueue .....Outqueue...... Process at Opt Name Library Start-up OUTQ1 QC Y OUTQ2 QC N More... F3=Exit F4=Prompt F5=Refresh F12=Cancel
- When pressing <enter> at the dataqueue configuration screen the outqueue selection screen appears. Key the outqueues that you wish the Smart Router to monitor for spool files in the subfile listing and press <enter>. F4 prompt on the name column will list outqueues.
- Process At Startup: Specify Y or N. The Smart Router, a dataqueue engine, normally processes spool files as they are released into the outqueue. If 'Y', spool file entries that exist in the data queue will be processed at start-up. If 'N', they will not be processed until held and then released. The default (if left blank) is 'N'.
Press <enter> to save changes. Then press F12 to return to the main Smart Router engine listing, then continue the configuration using option 2 - change.
Applications
Option 5 - View from the main Smart Router engine listing permits you to drill down to applications contained within the SmartRouter.
5/12/09 iDocs SmartRouter PR0020H1 14:55:01 Application Definition Maintenance QSECOFR SR Engine Name/Desc: JOBLOG Example Application Data Queue Name/Lib: JOBLOGDTAQ DCYQC Archive Outque/Lib.: OUTQARC DCYQC Type option, press enter. 3=Copy App 4=Remove App 6=Spoolfile Cond 8=Targets Opt Engine App Description Form App Act MAINAPP Main Application JOBLOG MAINAPP2 Main Appl 2 JOBLOG MAINAPP3 Main Appl 3 JOBLOG More... F3=Exit F4=Prompt F5=Refresh F12=Cancel
To add and application key its name and description on an empty line and press <enter>.
Form App: This is the name of the associated iDocs form. The form is used to provide mapped field definitions. These definitions can be used to test internal spool file content and map spool file content to output in the targets. This is the sole way the internal spool file content is specified in the Smart Router.
Use option 6 to Work with Conditions for the application. These conditions will be evaluated only for the first page in each spool file, and if they evaluate to TRUE the entire spool file will be processed by the application. All applications with either no conditions or with conditions evaluating to TRUE will process the spool file.
Use option 8 to work with targets for the application. A target is a copy of the spool file that is filtered by the conditions attached to it. Target conditions are evaluated for each page in the spool file and when TRUE the page is written to the target.
Targets
9/14/18 iDocs SmartRouter PR0030H1 18:10:52 Target Definition Maintenance KKRAMER SR Engine Name/Desc..: OFACKTEST Test Ack for Adel W Application Name/Desc: OFACKTEST Ack test Form App Reference...: OFACKADEL2 Type options and press enter: 3=Copy, 4=Delete, 6=Conditions, 8=Insert Text Target Name/Desc....: HANDOFFEQ IF EQ Destination Outq/Lib: HANDOFF OFERRER Output type.........: *COPY *NONE *PAGE *COPY *BURST *SORT *SORTBRST Set SPLF Owner......: *SPLOWNER, User profile Override Command....: More... F3=Exit F4=Prompt F5=Refresh F8=Insert Map Field F12=Cancel
This screen shows any existing targets of the application. You can add targets by scrolling down and appending to the list.
- Target Name/Desc: A Unique name for the target.
- Destination Outq/Lib: i5/OS outqueue into which the output will be written.
Output Type
Output Target Types | |
---|---|
*NONE | Discard spool file page, NULL output |
*PAGE | Burst every page |
*COPY | Output un-burst, i.e. all output to the target is in one spool file. |
*BURST | Burst output to this target using the bursting definitions in the iDocs form or check specified. |
*SORT | Sor output to this target using the sort definitions in the iDocs form or check specified. |
*SORTBRST | Sort and burst output to this target using the sorting and bursting definitions in the iDocs form or check specified. |
- Override Command: Prompt this field using F4 to assign constant values to external spool file attributes of the output spool files from this target.
- Use option 6 to add / maintain conditions attached to targets.
- Use F8 to assign spool file mapped fields to external spool file attributes of the output spool files from this target.
Conditions
Conditions are entered via option 6, and are attached to applications and/or targets.
- When attached to the application, the conditions are evaluated once at the beginning of the processing of a spool file. If the tests fail, the application and all its targets are not considered further for the spool file.
- Conditions attached to a target are evaluated at each spool file page, and if true the spool file page is included in the output for the target.
9/14/18 iDocs SmartRouter PR0035H1 18:17:03 Target Spoolfile Page Conditions KKRAMER SR Engine...: OFACKTEST Test Ack for Adel W Application.: OFACKTEST Ack test Form App Ref: OFACKADEL2 Target Name/Desc....: HANDOFFEQ IF EQ Destination Outq/Lib: HANDOFF OFERRER Output type.........: *COPY *USRPRF *USRDTA *OUTQUE Line and Attribute or Attribute or *SPLFILE *FORM *JOBNAME Nbr or Mapped Field Test Map Fld or Value *OUTLIB *TOTALPG F8=Edit 0001 &TRIGGER *EQ *BLANKS 0002 0003 0004 0005 0006 More... F3=Exit F23=Delete F5=Refresh F6=Insert F12=Cancel
Attribute or Mapped Field
Mapped Field Types | |
---|---|
iMail To Address | |
*TESTBODY | test body |
*TRIGGER | Trigger for SR Condition |
There is a feature where you can name your document is using the &EMAIL option: Press F8 when cursor is at &EMAIL and the following PR0035W3 window appears:
9/14/18 iDocs SmartRouter PR0035H1 18:17:03 Target Spoolfile Page Conditions KKRAMER PR0035W3 SR Testing Values Ap F Field . . : &EMAIL Ta Test . . : *EQ, *LT, *LE, *GT, *GE, *NE, *IN D O Test value (&MapField, *Attribute,Value, Value1 Value2..) TA *OUTQUE L M *JOBNAME OTALPG 0 0 0 0 More... 0 F4=Prompt F8=Cond. Named Object F10=Save 0 More... F3=Exit F23=Delete F5=Refresh F6=Insert F12=CancelYou can now use the F8=Cond. Named Object option to name the object. The PR0036W1 window is displayed as shown below:
9/14/18 iDocs SmartRouter PR0035H1 18:17:03 Target Spoolfile Page Conditions KKRAMER PR0035W3 SR Testing Values Ap PR0036W1 F Fi Named Objects of Conditional Lists Ta Te D 1=Select 2=Edit 4=Delete O Te Opt Name Description EMAILLINE Find eMail address on line UTQUE L EVEN2-6 Even Pages 2, 4, 6 BNAME IDOCS Test G ODD1-5 Odd Pages 1 - 5 0 REPORTS Reports ID 0 0 0 0 F 0 F3=Exit F6=Add re... F3=Exi
Line and Attribute or Attribute or Nbr or Mapped Field Test Map Fld or Value 0001 *SPLFILE *EQ QPJOBLOG 0002 AND *USRPRF *EQ QSECOFR 0003 0004 0005
- And/Or: As implied.
- Attribute or Mapped Field: Data source for condition. This can be an external printer file attribute with prepended asterisk, or the name of an iDocs mapped field prepended with an ampersand (&). The mapped field is from the iDocs form specified in the Application definition. This is promptable. If a mapped field is specified the value used is the value for the spool file page currently processing and thus potentially changes for each page. If an external printer file attribute is specified this value of course is unchanging. The software will trim this value before evaluating, so leading and trailing blanks are discarded.
- Test: The tests are performed using the C Standard Library Function strcmp(). Both source and comparison value are treated as character data. The tests are:
Tests | |
---|---|
*EQ | Equals |
*NE | Not Equals |
*GT | Greater Than |
*GE | Greater Than or Equal To |
*LT | Less Than |
*LE | Less Than or Equal To |
- Attribute or Map Fld or Value: The comparison data for the test. This can be an external printer file attribute with a prepended asterisk, an iDocs mapped field with prepended ampersand (&), or a constant value without quotation marks. The software will trim this value before evaluating, so leading and trailing blanks are discarded. The following external spool file attributes are supported as comparands:
Comparand keyword | Meaning |
---|---|
*USRPRF | User profile owning the spool file |
*USRDTA | Spool file user data |
*OUTQUE | Spool file outqueue |
*OUTLIB | Spool file outqueue library |
*SPLFILE | Spool file name |
*FORM | Spool file form type |
*JOBNAME | Spool file job name |
*TOTALPG | Spool file total pages |
Starting and Ending a SmartRouter™ Engine
From menu option 13, select option 8 to start, option 9 to end. You must specify a job queue into which the engine is launched. The job queue must feed into a batch subsystem. Job queue QS36EVOKE is configured as a multi threaded job queue leading into subsystem QBATCH by default in i5/OS as shipped from IBM; this is usually a good choice. You can also use FMGJOBQ but should check that it is multi threaded first.
Engine Processing Mode
Versions 3.11 - 3.20:
This functionality was removed in version 3.30. See the second configuration screen.
As shipped the SmartRouter engine processes jobs serially as part of the engine thread, i.e. it invokes the Smart Routing processor using a 'CALL' command.
Because the processor opens a spool file for each possible target for each input spool file, it can quickly exhaust the maximum number of spool files in the system value QMAXSPLF. Therefore, one can configure the engine to process spool files in a separate thread using 'SBMJOB' rather than 'CALL'.
In the library PRRLOAD3 is a data area PRJOBQ. The engine loads this data area upon startup. If it is blank the engine will 'CALL' the SmartRouting processor; if it contains the name of a jobqueue it will use 'SBMJOB' to submit the Smart Routing processor to the jobqueue named in the data area. The data area must be in the engine library list. If the processor is separately invoked into a jobqueue for each input spool file each processing will start a new spool file number sequence.
Scheduling Engine Start / Stop
Start
Add the following entry to the schedule jobs:
SBMJOB CMD(CALL PGM(PRR0459) PARM(SRENGINE)) JOB(SRENGINE) JOBQ(QS36EVOKE)
Where:
- SRENGINE is the name of the Smart Router engine definition.
Do not use Q as the first letter of an engine definition. Q is reserved for operating system objects.
Do not name engines names in use elsewhere on your system. Give the engine a truly unique name.
- QS36EVOKE is the name of a jobqueue, multi-threaded preferred but not required. QS36EVOKE ships by default as unlimited multi-threaded routing into subsystem QBATCH and is a good default choice.
Note that the JOB parameter, specifying job name, must precisely match the Smart Router engine definition name. This is done to provide a means of recognising the engine when ending the engine from the scheduled jobs function (see below).
Stop
To end a SmartRouter engine from the job scheduler, presuming that the job name is unique on your system, add this command to the job schedule:
ENDJOB JOB(SRENGINE) OPTION(*IMMED)
where SRENGINE is the job name of the engine and name of the Smart Router engine configuration.
Warning -- job selection is by job name and if you specify this incorrectly you can shut down any job so named, including operating system jobs.
Do not use Q as the first letter of an engine definition. Q is reserved for operating system objects.
Upgrading the Smart Router
Smart Router upgrades in iDocs version 6 are part of COPYDATA, the iDocs migration utility. If upgrading from an earlier release of the standalone Smart Router follow the below instructions.
To manually upgrade the Smart Router into the version integrated into the iDocs Suite please do the following:
- Shutdown the Smart Router engines.
- Then copy the following files from the Smart Router library (PRRLOAD) to the iDocs library (IDOCS):
CPYF FROMFILE(PRRLOAD/PRDAPPLM) TOFILE(IDOCS/PRDAPPLM) FROMMBR(*FIRST) TOMBR(*FIRST) MBROPT(*REPLACE) CRTFILE(*NO) FMTOPT(*MAP *DROP)
CPYF FROMFILE(PRRLOAD/PRDCOND) TOFILE(IDOCS/PRDCOND) FROMMBR(*FIRST) TOMBR(*FIRST) MBROPT(*REPLACE) CRTFILE(*NO) FMTOPT(*MAP *DROP)
CPYF FROMFILE(PRRLOAD/PRDMASTER) TOFILE(IDOCS/PRDMASTER) FROMMBR(*FIRST) TOMBR(*FIRST) MBROPT(*REPLACE) CRTFILE(*NO) FMTOPT(*MAP *DROP)
CPYF FROMFILE(PRRLOAD/PRDOUTQUE) TOFILE(IDOCS/PRDOUTQUE) FROMMBR(*FIRST) TOMBR(*FIRST) MBROPT(*REPLACE) CRTFILE(*NO) FMTOPT(*MAP *DROP)
CPYF FROMFILE(PRRLOAD/PRDTARGET) TOFILE(IDOCS/PRDTARGET) FROMMBR(*FIRST) TOMBR(*FIRST) MBROPT(*REPLACE) CRTFILE(*NO) FMTOPT(*MAP *DROP)
- Replicate the contents of data area PRJOBQ if it exists in the old stand-alone library:
DSPDTAARA DTAARA(PRRLOAD/PRJOBQ)
where JOBQUEUE is the name of a job queue from PRRLOADOLD/PRJOBQ.
CHGDTAARA DTAARA(IDOCS/PRJOBQ) VALUE('JOBQUEUE')
- Using the Smart Router configuration program SR3, press <enter> through all configuration screens to make certain any required defaults are written into the files.
Exporting / Importing Smart Router Applications
They are 02 commands: SAVIFDSR to save SR applications and RSTIFDSR to restore SR applications
Save Smart Router Applications (SAVIFDSR) Type choices, press Enter. Smart Router Name(s) . . . . . . __________ Name, *ALL + for more values __________ Save to file . . . . . . . . . . __________ Name Library . . . . . . . . . . . *CURLIB Name, *CURLIB Smart Router library . . . . . . *LIBL Name, *LIBL, *CURLIB Target release . . . . . . . . . *CURRENT *CURRENT, *PRV, V4R4M0...
Details of SAVIFDSR:
+ Smart Router Name(s): specify one, several or all SR applications user wants to save
+ Save to file: specify the save file where SR applications will be saved into
+ Smart Router library: specify the production library of Smart Router. The data of SR files in this library will be saved
Restore Smart Router Apps (RSTIFDSR) Type choices, press Enter. Restore from save file . . . . . __________ Name Library . . . . . . . . . . . *CURLIB Name, *CURLIB Smart Router library . . . . . . *LIBL Name, *LIBL, *CURLIB Overwrite existing application *NO *YES, *NO
Details of RSTIFDSR:
+ Restore from save file: specify the Save file contains the SR applications saved
+ Smart Router library: specify the production library of Smart Router. The SR saved applications will be restored to this library
+ Overwrite existing application: specify whether the existing applications in production library will be overwritten or not.
[ Up to Main Menu ]