Calling a split user exit program
A user program can be used in these scenarios:
1.If you want to split up the input spooled file for each unique value found in a position in the spooled file. This is done by setting a spooled file attribute in the user program.
2.If you want to add extra spooled file data, that cannot be found via a simple SQL selection as shown below.
You can select a user program after the page selection above:
Change Split Definition SPL310D
Split definition name . : IF400ONLY Description . . . . . . : Sort IF400 Pages
Split detail description : IF400 ONLY
User exit program Program name . . . . . . *NONE *NONE, *SQL, name Library . . . . . . . __________ name
F3=Exit F12=Cancel
|
This screen can be used to call a user exit program, that e.g. inserts information in the spool entry resulting from the split.
InterForm400® will call the program with a set of parameters consisting of up to either 5 or 10 lines each containing a field of up to 30 positions. The amount of exit parameters depends on the format:
01 equals 5 exit parameters,
02 equals 10 exit parameters,
03 equals the 10 exit parameters as well as 300 character parameter, that contains all attributes of the original spooled file.
For additional information on return parameters look into the sample programs, SPLEXIT, SPLEXIT02, SPLEXIT03 and SPLEXIT04 in the source file APISRC in library APF3812. Please notice that the spooled file attribute parameters are all RETURN parameters, that are empty when the program is called.
These various programs differs in these manners:
Source |
Parameter format |
Description |
SPLEXIT |
01 |
This was the first (simple) kind of split exit program supported. The program get up to 5 texts from the spooled file and returns up to 10 texts into the new splitted spooled file. |
SPLEXIT02 |
02 |
Same as SPLEXIT with the only difference, that you here can get up to 10 texts from the spooled file. |
SPLEXIT03 |
03 |
Same as SPLEXIT02 with the only difference, that you here get a complete data structure with ALL the information of the spooled file that triggered the split definition. |
SPLEXIT04 |
04 |
This is a unicode exit program. This is needed if you want to use a split definition to change the contents of a unicode spooled file. Please notice that all text returned from the program are expected to be in unicode, where the other split exit programs above run in the codepage of the spooled file (or AFC job if not defined). |
One example could be a customer ID which the user exit program use to look up a fax number in a database, which is returned to InterForm400 to be inserted in the new, splitted spooled file:
Change Split Definition SPL310D
Split definition name . : IF400ONLY Description . . . . . . : Sort IF400 Pages
Split detail description : IF400 ONLY User exit program Program name . . . . . . GETFAXNR *NONE, SQL, name Library . . . . . . . QGPL name Format . . . . . . . . . 02 01, 02, 03, 04 (UCS2) When to call . . . . . . 1 1=Every page 2=When exit parm changes Exit parameter data 3=First time the seqnbr is selected 1. Linenbr. 13_ Position 57_ - 60_ 6. Linenbr. ___ Position ___ - ___ 2. Linenbr. ___ Position ___ - ___ 7. Linenbr. ___ Position ___ - ___ 3. Linenbr. ___ Position ___ - ___ 8. Linenbr. ___ Position ___ - ___ 4. Linenbr. ___ Position ___ - ___ 9. Linenbr. ___ Position ___ - ___ 5. Linenbr. ___ Position ___ - ___ 10. Linenbr. ___ Position ___ - ___ Return data is to be printed in the following positions 1. Linenbr. 14_ Startposition 60_ 6. Linenbr. ___ Startposition ___ 2. Linenbr. ___ Startposition ___ 7. Linenbr. ___ Startposition ___ 3. Linenbr. ___ Startposition ___ 8. Linenbr. ___ Startposition ___ 4. Linenbr. ___ Startposition ___ 9. Linenbr. ___ Startposition ___ 5. Linenbr. ___ Startposition ___ 10. Linenbr. ___ Startposition ___ F3=Exit F12=Cancel
|
You might want to break up the spooled file for each possible value in a certain position in the spooled file. To achieve this you select the line and positions in the screen above and in your exit program you simply copy the incoming value (e.g. &entrytxt1) into a variable containing a spooled file attribute e.g. &formtype. Please notice, that this works fine EVEN if the same value is found on pages that are NOT successive - those pages are always merged into one spooled file with the same attributes.
The field ‘When to call’ above indicates when to call the user program mentioned above:
1=Every page
The user program is called for each page where the relevant sequence line is selected.
2=When exit parm changes
Normal programs are deterministic i.e. for a fixed set of input values the output will always be the same. If that is the case for your program you should consider this setting. The values that the program returned the first time will be used for the subsequent pages containing the same values for the exit parms. In this way you can save a bit of processing time by not calling your program more than needed.
3=First time the seqnbr is selected
The first time the user program is called the returned parameters are stored and reused for the subsequent calls. Please note, that if multiple sequence numbers use this option while being called alternately the returned parameters can be mixed up!
NOTE: If you return spooled file attributes like described above, then please note that if you return blanks, then the spooled file attribute of the splitted spooled file(s) will the same as the original spooled file i.e. if the original spooled file has ‘*STD’ as the formtype and you return blanks then the formtype of the new spooled file(s) will be ‘*STD’.
TIP: You can only add to (not overwrite) the contents of the spooled file by use an exit program. If you want to overwrite the contents you can use the CRTPBSPLF command.
WARNING: All exit programs called by InterForm400 must be owned by QSECOFR. If it is not the AFC job will halt with an error message. Change the owner with the command: CHGOBJOWN OBJ(library/program) OBJTYPE(*PGM) NEWOWN(QSECOFR). Refer to this to see what is required in order to be able to change the owner..
