PRISMAproduction/MVS V3.8 SPS Page Sort User's Guide

PRISMAproduction/MVS V3.8

SPS Page SortUser’s Guide

��

...and Training?

Our training centers hold seminarson the printing system described inthis manual. We can also conductoperator workshops on your premisesor in Poing on request.

Information:Phone +49 81 21 72-39 40Fax +49 81 21 77-39 50

Océ Printing Systems GmbHSiemensallee 285581 PoingGermany

October 2000 Edition

Copyright Océ Printing Systems GmbH 2000

All rights reserved, including rights of translation, reprinting,reproduction by coying or any other method.

Offenders will be liable for damages. All rights, including rights createdby patent grant or registration of a utility model or design, are reserved.

Delivery subject to availability; right of technical modifications reserved.All hardware and software names used are trademarks of their respective manufacturers

Preface

U26433-J-Z247-2-7600 1

Preface

Product Description

SPS Page Sort (PSORT) is a SPS/MVS APA product feature that provides the ability toperform transformations on an output print file. PSORT will take print jobs from the JESspool queue and rewrite re-sequenced pages back to the spool as a new print job. Youcan then print this new print job on an Océ Twin Printing System.

Paper cost reductions may potentially be realized by having PSORT convert simplexSYSOUT data to a continuous forms duplex format. This is accomplished by havingPSORT re-sequence the pages in a unique way. This transformation will allow all pages ofthe first half of a data set to print on the front side and all pages of the last half to print onthe back. This PSORT function (referred to as the re-sequencing option) contrasts withconventional duplex for continuous forms duplex printing, which prints all odd-numberedpages on the front and all even-numbered pages on the back.

Alternatively, you can configure the sorter to reverse the order of pages. This option mightbe useful for those shops that use roll-feed unwinders and then use a roll rewinder to holdthe output. The reverse order option allows you to take the output roll to another locationfor the post-processing which might have occurred directly from the output web. The pagere-sequencing option and the reverse option are mutually exclusive.

Throughout this document, we concentrate on the PSORT re-sequencing, rather than thereverse sequencing, because the implications of the re-sequencing option are morecomplex.

The PSORT facility is installed in two parts to aid modification by the end-user. The firstpart is a driver program (the “processor”) that interfaces with the JES spool. Theprocessor performs the transformations (the sorting), as well. The processor is installed aspart of the “Base Component” portion of the installation of SPS/MVS. The second part is acustomizable user exit that determines page boundaries and performs any required pre-processing of records. Although a sample of this exit is supplied with the product, thePSORT facility is not functional until this exit is installed, and (if needed) modified.

Summary of Amendments

2 U26433-J-Z247-2-7600


for SPS/MVS-APA Page Sort Version 3.8

• When sorting output groups, the sorter will force page breaks when unlike attributes arefound between successive datasets in the output group.

• Removal of record size limitations when sorting output groups.

• New option to allow user control over which text units are reserved by the sorter.

• Collation option for output groups having multiple copies.


for SPS/MVS-APA Page Sort Version 3.6

• Addition of the Reverse page re-ordering option

• Validation of dynamic output text units supplied by the user exit

• Option to perform page re-sequencing based upon the output group, rather than thedataset.

Contents

U26433-J-Z247-2-7600 3

Contents

Preface .................................................................................................................................1

Contents...............................................................................................................................3

1 An Overview of the Page Sort Facility ......................................................................71.1 System Requirements ...................................................................................................81.2 Technical Details ...........................................................................................................81.3 Expectations and Limitations.......................................................................................101.3.1 Reports in Data Binders ..........................................................................................101.3.2 Report Size Restrictions..........................................................................................101.3.3 Reports with Conditional Processing PageDefs .....................................................101.3.4 Using the Dataset Allocation Exit ............................................................................11

2 Installation .................................................................................................................132.1 Overview......................................................................................................................132.2 Required Installation Steps .........................................................................................132.3 Parameter File Samples..............................................................................................142.3.1 JCL for the SPS PSORT Started Task....................................................................162.3.2 JES2PARM .............................................................................................................182.3.3 SPS Initialization Member “SPSPRINT”..................................................................192.3.4 SPS Initialization Member “SETUPSSS” ................................................................192.3.5 Additional SPSPARM Considerations.....................................................................20

3 Operation ...................................................................................................................213.1 The PSORT Dummy Printer........................................................................................213.2 Setting an Input Limit...................................................................................................213.3 The Output Class ........................................................................................................223.4 Separator Pages .........................................................................................................223.5 SMF Data ....................................................................................................................22

4 Implementing the PSORT Record Exit ....................................................................254.1 Program Logic .............................................................................................................254.1.1 Responsibilities of the Sorter ..................................................................................264.1.2 Responsibilities of the Exit ......................................................................................264.2 General Programming Considerations........................................................................274.2.1 Two Ways of “Freeing” the Sorted Output Units to JES .........................................274.2.2 Rounding .................................................................................................................284.2.3 Correlating Input and Output Processing ................................................................284.2.4 Printing an Odd Number of Logical Pages..............................................................294.2.5 Duplicating Output Pages........................................................................................29

Contents

4 U26433-J-Z247-2-7600

4.2.6 Terminating Input File Processing...........................................................................304.2.7 Deleting Input Records............................................................................................304.2.8 Inserting Input Records ...........................................................................................304.2.9 Adding Records to Output Pages............................................................................304.2.10 Specifying the Output File Destination....................................................................304.2.11 Indicating a New Output Page ................................................................................314.2.12 Indicating a New Sorting Unit..................................................................................314.3 A Few DOs and DON’Ts .............................................................................................314.3.1 Absolutes.................................................................................................................324.3.2 Subject to Negotiation .............................................................................................324.4 Suggested Approach...................................................................................................324.4.1 Some Hints to the Programmer ..............................................................................334.4.2 Input Carriage Control.............................................................................................34

4.4.2.1 ASA ...................................................................................................................344.4.2.2 Machine.............................................................................................................354.4.2.3 No Carriage Control ..........................................................................................36

4.4.3 Structured Fields .....................................................................................................364.4.3.1 IMM — Invoke Medium Map .............................................................................374.4.3.2 IDM — Invoke Data Map...................................................................................37

4.4.4 Programming for Structured Fields .........................................................................374.4.5 Page Breaks............................................................................................................38

4.4.5.1 ASA ...................................................................................................................394.4.5.2 Machine.............................................................................................................394.4.5.3 No carriage control............................................................................................394.4.5.4 Page Break Detection Table (NEWTABLE)......................................................39

4.5 Flags Used by the Exit ................................................................................................404.5.1 IRXFLAGS...............................................................................................................404.5.2 IRXFLAG1...............................................................................................................414.5.3 IRXFLAG2...............................................................................................................434.5.4 IRXFLAG3...............................................................................................................444.5.5 IRXFLAG4, IRXFLAG5 and IRXFLAG6..................................................................45

4.5.5.1 IRXFLAG4.........................................................................................................454.5.5.2 IRXFLAG5 and IRXFLAG6 ..............................................................................45

4.6 Separator Pages .........................................................................................................464.6.1 Adjustments to the Banner Page ............................................................................464.7 Input Fields to the Exit.................................................................................................474.8 Variables for the IPLINE MACRO ...............................................................................494.8.1 SPSMSEPS.............................................................................................................514.8.2 Using the FORMS Control Table ............................................................................51

5 Text Units...................................................................................................................535.1 Text Units Used by the PSORT Exits..........................................................................535.2 Available Text Units.....................................................................................................545.3 The OUTADD Macro ...................................................................................................54

Contents

U26433-J-Z247-2-7600 5

5.4 Conflicting Text Units ..................................................................................................55

6 Troubleshooting Advice ...........................................................................................576.1 Debugging Code .........................................................................................................576.1.1 Variable Display ......................................................................................................576.1.2 Memory Dump Display............................................................................................576.2 Troubleshooting Text Units .........................................................................................576.3 Tracing SPS ................................................................................................................58

7 Two-up Printing.........................................................................................................657.1 Page Sequencing ........................................................................................................657.2 FormDef Source Code ................................................................................................667.3 PageDef Source Code ................................................................................................67

Appendix A Related Documentation..............................................................................69

Appendix B Messages and Codes .................................................................................71

Appendix C Alphabetic List of Text Units .....................................................................77

Appendix D Numeric List of Text Units .........................................................................81

Appendix E Sample SPSMSEPS Dataset Separator Page...........................................85

Appendix F IRXWAREA Field Descriptions ..................................................................91

List of Figures ...................................................................................................................95

Page Sort Overview

U26433-J-Z247-2-7600 7

1 An Overview of the Page Sort FacilityFor most installations, one of the largest expenses involved in printing is the cost of thepaper. If a continuous-forms duplex printing system is available, you can reduce papercosts by using the reverse side of most sheets. If you were to universally implementduplex printing, you could achieve paper savings approaching 50%.

For short reports, most users prefer individual sheets. If you need to keep these sheetstogether, you can staple them or punch holes in them for a three-ring binder. For longreports, such as large program listings, dumps, console logs, GTF traces, EREP reports,etc., stapling or three hole punching the output is unwieldy. Also, many users traditionallydeliver some long reports as fan-fold output, which, in some cases, is actually a moreuseful output format. This may be especially useful as an adjunct to report distributionsystems, which create large continuous-forms reports.

Océ Printing Systems has a unique solution to some problems for these long reports:PSORT. The page re-sequencing option of the PSORT software provides the papersavings of duplex printing, but does not decrease any “click” charges because PSORTcreates the same number of impressions. Without PSORT, duplex printing on cut sheetprinters would traditionally put the odd numbered pages on the front of the sheets and theeven numbered pages on the back of the sheets. The PSORT solution prints the output soyou can handle it in a traditional fan-fold manner and also duplexes it for paper costsavings. PSORT produces this output without the need to attach any specialized, post-processing equipment to the printing system.

Here is an example of how PSORT works. Assuming your listing has 1,000 logical pages,the PSORT processor rearranges the sequence of pages of your listing in the followingsequence:

(front side) (back side)

Page 1 Page 1,000

Page 2 Page 999

Page 3 Page 998

• •• •• •

Page 499 Page 502

Page 500 Page 501

Page Sort Overview

8 U26433-J-Z247-2-7600

When you print this new re-sequenced file on a Twin printing system, in duplex mode, youtake the 500 physical pages from the stacker and leaf through it from Page 1 to 500. Atthe end of the pile, turn the last sheet up and you see the backs of the pages. You cancontinue to leaf through the output from Page 501 to 1,000. If this re-sequencing iscombined with a “tumble duplex” FormDef, the page orientation will be correct.

If your listings are large, you can tell PSORT to divide them into independently sortedunits, to make handling more convenient.

By using the PSORT facility to print your standard SYSOUT, you can immediately realizethe benefits of your Twin printing system without using any post-processing machineryand without writing specific printing applications especially designed for a duplex printer.

1.1 System Requirements

Océ Printing Systems provides PSORT as a standard part of SPS/MVS. It is included inthe MVS Basic component. SPS Page Sort (also known as SPSSSORT) requiresMVS/ESA Version 3 for the minimum level of function. You need MVS/ESA Version 4 orlater, or any release of OS/390, for full functionality. The OUTADD text units forADDRESS, BUILDING, DEPT, NAME, OUTDISP, ROOM, and TITLE are not available inVersion 3. In order to implement PSORT in a Version 3 environment, you must modify thesupplied user exit examples to remove the usage of these text units. See Chapter 5 TextUnits on page 53 for details.

Certain options, such as output group preservation, are not relevant to JES3environments. Full functionality is available in any JES2 environment supported in theabove levels of MVS or OS/390.

1.2 Technical Details

The sorting function keeps all records, for any page, together as a unit. Thus, the mostcritical decision to be made is the location of page breaks. PSORT allows you to decidethe location of page breaks in the user exit, which is called SPSSIRX. SPSSIRX gives aninstallation the options to add, delete, or modify records. When the exit processes arecord, it may flag the record as a page start or sort group start. If no special processingflags are set, PSORT assumes that this record is merely a continuation of the currentpage. Unless the exit asks for record deletion, PSORT puts each record into an MVS dataspace as a holding area for the transformation.

Page Sort Overview

U26433-J-Z247-2-7600 9

At the end of the print file, or at some maximum “pile” size defined at installation time,PSORT re-introduces the records to the JES spool from the MVS data space. For the re-sequencing option, the order of the pages which PSORT re-introduces to the spoolalternates between the beginning of the data space (the first page) and the end of the dataspace (the last page). PSORT processes the pages moving towards the middle of thedata space, alternating between the two ends. The other option that can be selected is torequest reverse order. In this case, pages are selected from the end of the data space,moving toward the beginning. The exit can select only one of the two options for page re-sequencing: either the PSORT order or REVERSE order. The selection (which defaults tothe page re-sequencing option) is set during the Initialization call, and is set for theduration of the printer. These two options are a fixed characteristic of PSORT, and youcannot select any other page sequence.

The following figure illustrates the process for the page re-sequencing option.

Spool

MVS Data SpaceApplicationLine Data

PSORT

Exit

6

5

4

3

3

32

1

Figure 1: Block Diagram of PSORT Operation

1. User application writes line data to the spool file.

2. PSORT selects the job and reads the data set. PSORT checks the exit to determinepage breaks and special processing.

3. PSORT copies the pages to an MVS data space, maintaining page boundaries.

4. PSORT selects pages from the beginning of the report, alternating with

5. Pages from the end of the report, in reverse order.

6. PSORT writes the pages back to the spool file, into a different class or a differentdestination.

Page Sort Overview

10 U26433-J-Z247-2-7600

1.3 Expectations and Limitations

There are some circumstances when PSORT is not the correct solution to the simplex toduplex conversion of output in a print center. For these cases, a path should be plannedto allow those excluded print streams to bypass the PSORT virtual printer, either byhaving a different output class, destination, or formname, for example.

1.3.1 Reports in Data Binders

If you require that a report must be placed into a data binder, you may encounter aproblem. Most data binders are designed for simplex fanfold output. It actually isn’tpossible to look at the backsides of any sheets, unless the print was burst (torn or cut atthe fanfold perforation). If you need to place listings into binders and still have themduplexed, consider bypassing PSORT, using a tumble duplex FormDef, and having theoutput burst. Then, pages appear in the correct order in the binder. PSORT is designedfor reports that are not bound.

1.3.2 Report Size Restrictions

PSORT does have some architectural limits on report size. They are:

• You cannot have more than 32,767 lines per page

• There is a limit of 262,144 pages per sort

• There is a total size limit of 2,143,281,152 bytes per sort

The first bullet should not present any problem since most reports have from 55-80 linesper page. The last two bullets describe an issue that can be overcome using the user exitto segment the output. For perspective, a report of 262,144 pages would take 44 boxes offorms (3000 sheets each) to print. Since a report of this size is unwieldy to read on atabletop, most installations will want to segment large files anyway. You might considerlimiting the sort size to something smaller than a box of paper. See section 4.2.12,Indicating a New Sorting Unit, for details on how to implement file segmentation.

1.3.3 Reports with Conditional Processing PageDefs

In most cases, PSORT is unaware of any change in output formatting due to conditionalprocessing in a PageDef. Neither a new Copygroup nor new Pageformat will be known atsort time. This is important, because pages are actually printed in reverse order for thesecond portion of a report. Thus, a change in Copygroup for Pageformat, which shouldapply, to subsequent pages, doesn’t apply correctly at print time. While many special orunique data streams can be accommodated by coding for them in the user exit, it isvirtually impossible to create a version of the user exit that can handle this situation.

On the other hand, reports with imbedded Invoke Media Map (IMM) or Invoke Data Map(IDM) structured fields might still be acceptable if the user exit is appropriately

Page Sort Overview

U26433-J-Z247-2-7600 11

programmed. See section 4.4.3, Structured Fields, for details on programming for theserecords.

1.3.4 Using the Dataset Allocation Exit

By including a dataset allocation exit for the virtual printer, those print data streams thatmust be excluded from the PSORT process can be redirected to bypass the sorter. Thesample dataset allocation exit SPSMDSCM can be used as an example of this facility.This exit examines each print data stream. If the data stream uses a PageDef name ofEXCLUD, the file is placed back on the output queue in hold status. Since the file reallyneeds to be printed somewhere, the exit also issues a JES2 command to send the file tooutput queue C, and release it for print. For this example, there should be a real printer(not a virtual PSORT printer) that services class C output. We assume that the PSORTprinter is servicing an output class other than class C. In a similar manner, any attribute ofa print file can be tested, and if necessary, the file can be redirected to a more appropriateprocess.

Installation

U26433-J-Z247-2-7600 13

2 Installation

2.1 Overview

Océ packages the pre-processor sort function for SPS/MVS called SPSSSORT(commonly known as PSORT) in the base component of SPS/MVS; i.e., you have thefunction with any available SPS printer driver.

You run PSORT as an FSS printer, defined to JES like a real SPS printer. We call thisspecial FSS printer a “dummy” printer. SPS allows you three types of dummy printers,“LIP”, “APA” or “MD2.” You designate an SPS printer as a dummy by specifyingCUU(LIP), CUU(APA) or CUU(MD2) in the SPSPRINT member from the SPSPARMlibrary. PSORT uses the SPS driver for LIP printers, so you must specify:

CUU(LIP)

SETUPSSS also contains the parameter:

DRIVER(SPSSSORT)

This DRIVER parameter tells SPS to load the PSORT software instead of a real printerdriver. PSORT reads your original output file from the JES spool and writes one or morereplacement files back to the spool in a different class or destination.

2.2 Required Installation Steps

Perform the following steps to install PSORT:

• Install SPS according to the instructions in the manual “SPS/MVS Installation Guide”.You only need the SPS base product to run PSORT, but you will also need the printerdriver component to actually print with SPS/MVS. Support for continuous forms duplexprinting requires the IPDS printer driver.

1. Apply any PTF tape supplied with the product.

2. Define a JES printer for the PSORT dummy printer. Refer to section 2.20 of theSPS/MVS Installation Guide. See Figure 3: Typical JES2PARM for an example ofhow to do this for the PSORT environment.

Installation

14 U26433-J-Z247-2-7600

3. Create a new SPS procedure for the PSORT dummy printer or update your realprinter SPS procedure. Use member SPSIPROC from SPSSAMP as a model, if youchoose to create a new procedure. Figure 2: JCL for the PSORT Started Task isbased on SPSIPROC and has the following changes from the SPSSAMP member:

a) Concatenate the ENGLISH, ENGLISH0 and ENGLISH1 members in theSPSMSGDD DD statement. Concatenate the APA driver member ENGLISH2only if you run a real printer in the same FSS with PSORT.

b) Optionally, define two trace files for the PSORT dummy printer. You will needthese if any problems arise which would require diagnosis.

c) The DD statements for resource libraries are not required, and may beomitted from the PROC.

4. Define the PSORT dummy printer in the SPSPRINT member from the SPSPARMlibrary. A sample SPSPRINT member, containing a sample PSORT dummy printerdefinition named PRTSOR01, is in the SPSSAMP library. See Figure 4: TypicalSPSPRINT member.

5. Define the setup options for the PSORT dummy printer in the SPSPARM library. Asample member customized for PSORT called SETUPSSS resides in the SPSSAMPlibrary. Change the TRACELEV parameter to 0 (zero) unless you are diagnosing aproblem. See Figure 5: Member “SETUPSSS”.

• Implement a version of exit SPSSIRX that accommodates the input print data.

This step involves some analysis of the print environment, and whether all jobs can beprocessed by the sorter. See Chapter4 Implementing the PSORT Record Exit onpage 25 for details. To verify basic operation of the sorter, you may use one of thesupplied exits from SPSSAMP. The exit that handles most general line-data output iscalled SPSSIRXG. The load module for this (and the other) exit(s) are available inSPSLINK. The sorter will always use the module named SPSSIRX, so you will need torename SPSSIRXG to use it.

• For 1-up printing, create (or modify) a FormDef to provide Tumble Duplex. If you need2-up (or greater), the medium map must include Enhanced N_Up controls. Refer toTwo-up Printing page 65 of this document.

• Document your customized exit.

2.3 Parameter File Samples

The SPSPRINT member of SPSSAMP contains a sample entry for the dummy printerPRTSOR01. This dummy printer uses a sample SETUP member called SETUPSSS. TheSETUPSSS member contains the basic SETUP parameters for a printer driver that

Installation

U26433-J-Z247-2-7600 15

specifies a dummy LIP printer. While the following examples show only a JES2implementation, a similar set would also apply to a JES3 implementation.

Installation

16 U26433-J-Z247-2-7600

2.3.1 JCL for the SPS PSORT Started Task

//************************************************************//* SPS: START UP PROCEDURE FOR SPS *///* *///* THIS PROC IS RUNNING WITH 3.8 SPS USING SPSSSORT. *///* *///************************************************************//*//SPSS PROC PREFIX='SPS.V380'//*//* THE PROCEDURE NAME ON THE EXEC CARD SHOULD BE UNIQUE//* FOR EACH FSS SO THAT THE OPERATOR CAN ENTER OPERATING//* SYSTEM//* COMMANDS FOR A GIVEN FSS EASILY.//*//PRT1 EXEC PGM=SPSMFSS,TIME=NOLIMIT,REGION=5M//*//* SPS EXECUTION PROCEDURE//*//* STEPLIB ONLY NEEDED IF SPS MODULES ARE NOT INSTALLED//* IN LINK LIST.//*//STEPLIB DD DSN=&PREFIX..SPSLINK,DISP=SHR//*//* THE FOLLOWING DUMP DD (ALTERNATELY SYSABEND) SHOULD BE//* ALLOCATED TO RECEIVE ABEND DUMPS FROM SPS.//*//SYSUDUMP DD SYSOUT=X//* THE FOLLOWING DATA SET CONTAINS THE SPS MESSAGE FILES.//* THE BASE PRODUCT MESSAGES ARE IN ENGLISH. THE MESSAGES//* FROM THE SORTER ARE IN ENGLISH0. MESSAGES FROM THE LIP//* DRIVER ARE IN MESSAGE1. ALL THREE ARE NEEDED BY PSORT.//*//SPSMSGDD DD DSN=&PREFIX..SPSMESS(ENGLISH),DISP=SHR// DD DSN=&PREFIX..SPSMESS(ENGLISH0),DISP=SHR// DD DSN=&PREFIX..SPSMESS(ENGLISH1),DISP=SHR//*//* THE FOLLOWING DATA SET CONTAINS THE SPS PARAMETER FILE.//*//SPSPARM DD DSN=&PREFIX..SPSPARM,DISP=SHR//*//* THE FOLLOWING 2 TRACE DATA-SETS SHOULD BE ALLOCATED

Installation

U26433-J-Z247-2-7600 17

//* IF THE PARMAMETER TRACEFILE(USER) IS TO BE USED IN THE//* SETUP MEMBER FOR THE PRINTER (SPS PARAMETER LIBRARY).//*//* THERE SHOULD BE 2 OF THESE FILES FOR EACH PRINTER.//*//* THE LAST 4 CHARS OF THE DDNAME MUST BE THE PRINTER//* NUMBER//*//SPS10001 DD DSN=SPS.TRA10001,DISP=SHR,DCB=BUFNO=20//SPS20001 DD DSN=SPS.TRA20001,DISP=SHR,DCB=BUFNO=20

Figure 2: JCL for the PSORT Started Task

Installation

18 U26433-J-Z247-2-7600

2.3.2 JES2PARM

The JES2 parameter member defines the PSORT dummy printer and the real Twinprinter:

FSSDEF(SPS1) PROC=SPSIPROCFSSDEF(SPSS) PROC=SPSSSORT/*--------------------------------------------------------*//* OCE’ PRINTING SYSTEM - DUMMY PRINTER SPSSSORT *//*--------------------------------------------------------*/PRT(1) CLASS=B, START=NO, TRKCELL=YES, FSS=SPSS, MARK=YES, MODE=FSS, ROUTECDE=LOCAL, SEPDS=YES, CKPTPAGE=20, UCS=GT10, PRMODE=(LINE) <--- should not allow PAGE (PSORT

for line data)/*--------------------------------------------------------*//* OCE’ PRINTING SYSTEM – TWIN PRINTER *//*--------------------------------------------------------*/PRT(5) CLASS=X, START=NO, TRKCELL=YES, FSS=SPS1, MARK=YES, MODE=FSS, ROUTECDE=LOCAL, SEPDS=YES, CKPTPAGE=50, PRMODE=(PAGE,LINE), UCS=GT10

Figure 3: Typical JES2PARM

Installation

U26433-J-Z247-2-7600 19

2.3.3 SPS Initialization Member “SPSPRINT”

/* Root Member for SPS Initialization. *//* IN THIS EXAMPLE, PRT1 IS THE VIRTUAL PRINTER *//* (THE SORTER), AND *//* PRT5 IS A REAL TWIN PRINTING SUBSYSTEM. */

PRT(PRT1) CUU(LIP) SETUP(SETUPSSS)

PRT(PRT5) CUU(0480,0481) SETUP(SETUP480) FTBL(FORM480)

Figure 4: Typical SPSPRINT member

2.3.4 SPS Initialization Member “SETUPSSS”

/* DUMMY PSORT PRINTER SETUP INITIALIZATION PARAMETERS. *//* REQUIRED PARAMETER FOR SPSSSORT */ DRIVER(SPSSSORT) /* DRIVER NAME OF SORT PRE-PROC *//* PARAMETERS FOR THE SETUPSSS MEMBER *//* SPS MESSAGE PROCESSING */ MSGSP(YES) /* SUPPRESS DIAGNOSIS MESSAGES *//* SPS TRACE PROCESSING */ TRACELEV(0) /* TRACE LEVEL */ TRACEFILE(USER) /* TRACE FILE TYPE */

Figure 5: Member “SETUPSSS”

Installation

20 U26433-J-Z247-2-7600

2.3.5 Additional SPSPARM Considerations

The PSORT printer does not use all the flexibility available to an SPS-driven printer, becauseit is not a real printer. Only SPSPRINT and SETUPxxx (and possibly MSGSUxxx, if anymessage suppression is required) are used by the PSORT function. Refer to the “SPSAdministrator’s Guide” for more information.

KEYxxx

(optional)

MSGSUxxx

(optional)

FORMxxxx

(optional)

SETUPxxx

(recommended)

SPSPRINT(required)

DFLTffff

(optional)

HSMTffff

(optional)

Figure 6: Hierarchy of Parameter Members

Note: SETUPxxx is normally optional, however PSORT requires it (to specify theDRIVER parameter). Make sure you set tracing to Level 0 in your SETUPxxxmember for normal operations. Tracing causes a performance penalty.

Operation

U26433-J-Z247-2-7600 21

3 Operation

3.1 The PSORT Dummy Printer

PSORT is a dummy printer that starts like any other JES printer:

$sprt1

You can cancel, drain, or modify the PSORT printer like any other AFP printer:

$cprt1

$pprt1

$tprt1,q=S

3.2 Setting an Input Limit

Running small print jobs under ten pages is not an efficient use of PSORT. Océ suggestsyou set a lower limit on the line count of eligible print jobs. The JES2 command toaccomplish this setting is:

$tprt1,lim=500-*

The parameter for the PRT(nnn) initialization statement is:

limit=500-*

Operation

22 U26433-J-Z247-2-7600

You can leave the limit at “*-*” if you don’t want to reject any candidate input.

3.3 The Output Class

PSORT supports two modes:

1. A single output class that is hard-coded into the exit code. You cannot change thisclass without re-assembling the exit. Input can come from any class other than thedesignated output class.

2. You can set the output class the same as the input class, but the output destinationmust be different, and the workload selection criteria must be set so that output will notbe re-selected.

3.4 Separator Pages

To get the greatest possible paper savings when using PSORT, set job separator pagesOFF and data set separator pages ON:

$tprt5,sep=n,sepds=y

This advice applies only to the real Twin printer, Printer 5 in our example. The dummyPSORT printer, Printer 1 in our example, does not produce any banner pages.

3.5 SMF Data

The dummy PSORT printer will produce SMF type 6 records for installation accountingpurposes. However, the record and page counters will always be zero. In addition, theSMF type 6 records produced by the real printer (PRT5 in the foregoing examples) will notreflect the actual print job that produced the print file. In order to reconstruct correct printaccounting, one of two choices are required:

Operation

U26433-J-Z247-2-7600 23

1. Use the SMF records produced by the dummy printer to create a cross-reference tothe SMF records produced by the real printer. Use this cross-reference to produce thecorrect accounting information in the installation reports. In this case, no AccountingExit programming is required for SPS. Or,

2. Implement one or two SPS Accounting Exits: an optional one for the dummy printer tosuppress the SMF records (needed only if you find the records annoying or they arecausing a problem with the installation’s accounting system); and/or a required one forthe real printer to reconstruct the correct information as though the original job hadbeen printed.

If you choose the second option, implement the SPSM6SUP Accounting Exit for thedummy printer, and a second Accounting Exit for the real printer that updates the SMFtype 6 record. The information that is needed should be the same that most installationswill require to get the original job information onto the separator page. This informationcan be found in the SMF type 6 record that is passed to the SPS Accounting Exit. TheEnhanced SYSOUT Support section of the record contains a field called SMF6TU. Thisfield contains the characteristics of the original job as saved by the SPSSIRX exit in thedummy printer. IF ANY INFORMATION IS NEEDED FOR EITHER THE SEPARATORPAGE OR FOR RECONSTRUCTING THE SMF RECORD, YOU MUST SAVE THEINFORMATION IN THE RESERVED TEXT UNITS. A sample of the latter is in SPSSAMPas member SPSM6SRT. If you do not wish to have the dummy printer‘s SMF recordsproduced, there is a sample Accounting Exit, SPSM6SUP in SPSSAMP to perform thisfunction.

Implementing the Exit

U26433-J-Z247-2-7600 25

4 Implementing the PSORT Record Exit

4.1 Program Logic

To allow adaptation of the sort processing to meet customer needs, PSORT calls a userexit named SPSSIRX (SPS Sort Input Record eXit). PSORT cannot run without this exit.PSORT and SPSSIRX share a 4K workarea called IRXWAREA. The sorter usesIRXWAREA to inform the exit about various events. And the exit uses IRXWAREA tocontrol many aspects, or features, of the sorting process. The fields of IRXWAREA aredescribed in Appendix F IRXWAREA Field Descriptions.

The software calls the SPSSIRX exit for three different reasons:

1. Initialization Call

The system issues this call once per print session, and the exit uses this call to keepinformed about general parameters related to the sorting of all following listings. See bitIRXINIT in byte IRXFLAG1 in IRXWAREA, as well as all bits for flag IRXFLAGS.

2. Input Record Call

The sorter issues this call once per input record, before processing the record. Whenthe record number is ‘1’, the exit recognizes receipt of the first record of a new input file.Most control processing done by the exit occurs in this call type. The softwarerecognizes an input record call when flag bits IRXINIT and IRXOUTP are both zero.

The maximum number of lines per page is flexible, but the prime directive is to makethe number of allowed lines per page match all supported Page Definitions and DataMaps. You have the opportunity to examine the name of the PageDef at the inputrecord call for record number one. Whenever the record number is “1”, the exit knows itis beginning to process a new input data set.

There is sample code for creating a user exit in the SPSSIRX, SPSSIRXG, andSPSSIRXI members of SPSSAMP. These samples sort listings with ASA, machine orno carriage control characters. SPSSIRXI in SPSSAMP is specifically designed tohandle output groups as a single sort unit (IRXOPGRP is active). The most genericsample is called SPSSIRXG. The SPSSIRXG sample provides skeleton code to consulta set of Data Map tables, but you need to modify this code to suit the requirements of


26 U26433-J-Z247-2-7600

your installation. See “Structured Fields” on page 37 for a discussion of thismodification. See also fields IRXREC#, IRXRECA, IRXCC and IRXTRC in IRXWAREA.

Regardless of which sample is chosen as a starting point, the resulting code should beassembled and link-edited as a load module named SPSSIRX. This load moduleshould be available to SPS during PSORT execution.

3. Output Page Call

The software issues this call once per logical output page, after the sorter rewrites theoutput page to the spool. Output page calls give the exit an opportunity to appendrecords to the end of any output page. See bit IRXOUTP in byte IRXFLAG3 inIRXWAREA.

4.1.1 Responsibilities of the Sorter

• Initialize the exit work area at start-up time.

• Call the exit with IRXINIT set for any initialization the exit might require.

• Pass all input records to the exit, which may delete, modify, or insert records.

• Write whole pages to a work area.

• Return the resequenced pages back to the spool.

4.1.2 Responsibilities of the Exit

• The exit (SPSSIRX) allows control of output formats. Any data more complex than pureline data (SYSOUT) requires custom programming.

• The exit controls where page breaks occur, so it must recognize “Skip to Channel 1” (orequivalent) and page overflow.

• If channel skips 2–12 are in the print data, you need to program them into the exit.PSORT needs to know when page overflow occurs, and channel skips pose a greaterchallenge than simply counting single, double, and triple spaces.

• Certain “mixed” data streams are acceptable, but must be tested carefully. You canaccommodate some IMMs and IDMs with exit programming. Medium overlays maypresent a problem. Note: If your application uses more than one IDM, you will needto insert an IDM before EVERY page, since the actual print order might bereversed for any given segment of the print file. None of the sample exits implementthis. If your data streams contain IMMs, the exit may specify that a sort break shouldoccur. This is a probable requirement for any arbitrary print data stream. For FormDefscreated prior to N_Up, the IMM always forces a new sheet. When the contents of theback of the page containing the IMM may be from many pages away in the printstream, there is no way to know what the contents of any particular back page shouldcontain. Unless every application containing IMMs places an IMM on every page ANDyou are willing to recompile all the associated FormDefs to specify the N_Up statement


U26433-J-Z247-2-7600 27

INVOKE NEXT for every copygroup, the only viable action to take in SPSSIRX is toindicate a sort group break. Programming the exit to accommodate any other actionmay prove impossible.

• PSORT is designed to handle only the simplest PageDefs. However, unusualformatting, such as rotated text, may work correctly if the data stream is well behaved.

• When printing PSORT output, an installation may implement 2-up, 3-up and 4-up, butthe print-time FormDef requires Enhanced N_Up formatting. See Section 7 Two-upPrinting on page 65 for details on this implementation.

• Based upon criteria in the exit, PSORT groups output into “piles”. The software cantreat piles as separate output groups to begin printing before the software processes anentire input data set. This treatment of piles may not be desirable if you terminate inputdata later because of an invalid input record. However, making each pile a separateoutput group reduces spool space requirements and the elapsed time to receive thefinal print.

• The software stores the characteristics of the original print job in unused OUTPUTstatement JCL parameters. Each installation needs to evaluate which parameters willbe used for storing this information. Each installation will need to modify the bannerpage routines to make use of this information.

4.2 General Programming Considerations

4.2.1 Two Ways of “Freeing” the Sorted Output Units to JES

1. One input file becomes one unique output file, divided into many sorted units.By choosing this option, you cannot start printing an output file until the sortercompletes the reading and rewriting of the entire input file. The sorted units print in theoriginal sequence because JES does not see the individual sort units. Optionally, youcan set the exit to insert its own separator pages between the sort units. The sampleSPSSIRX exits use this modality, without separator pages.

2. Each sorted unit from an input file becomes a separate output group.You can print each sorted unit independently on different real printers. The exit maypass information to the sorter about the sequence of the sorted units, so thatinformation prints on the final header page for each unit. See “ Separator Pages” onpage 46 of this document for more information.

The sample exits set a limit of about 256K records on the input file before requesting thesorter to interrupt the input processing and make a new sorting unit. The 256K input linelimit results in approximately 2,000 physical pages for simple listings (assuming 60 linesper page, duplex).


28 U26433-J-Z247-2-7600

There are two flags in IRXWAREA DSECT, IRXNEWDS and IRXNEWDD that control theprocessing at sorted unit boundaries. If you set flag IRXNEWDD (which causes eachsorted unit to be a new output group), set it in every call to the exit.

Here are some reasons for creating several sorting units in an output file:

1. Several units avoid the possibility of a big input file exceeding the capacity ofthe data space used to temporarily store one sorting unit.

2. Several units allow the sorted units to print while the software continues toread a big input file.

3. Several units reduce JES spool space requirements.

4.2.2 Rounding

An option for processing files is to read the entire file before making any sort decisions.For files that generate multiple sorted units, you can ask the sorter to round the number ofpages per pile. You can request the software to determine the sorted unit boundary pointsbased on the number of physical pages. Then in the input processing, you control thesorted units at a record level.

Assume you have 2,400 physical pages and the exit requests a maximum output pile(sorted unit) of 1,000 physical pages. Without rounding, the result is three piles of 1,000,1,000 and 400 physical pages. With rounding, the result is three piles of 800 physicalpages each.

If you have any special requirements, you can control the processing of the sorted units atboth input and output.

The delivered exits set a maximum number of physical pages per pile to 5,000. Thisspecification exceeds the record limit of about 2,000 pages on input in the deliveredsample exit (see the section above). The setting of 5,000 physical pages per pile probablyprohibits the system from reaching the page limit, because the system usually reaches therecord limit first.

You request this rounding function in the initialization call using flags IRXMAXSH,IRXROUND, and field INXMAXSH in the IRXWAREA DSECT.

This rounding option is not viable for print files larger than 1,000,000 print lines, due to theexcessive storage requirements.

4.2.3 Correlating Input and Output Processing

When special processing requires part of a process to occur during the input record calland part of a process to occur during the output record call, you must establish a methodof correlation between the two calls. You accomplish this correlation by assigning specialvalues to the page identifier. (See fields IRXPGID and OPXPGIDV.) The software gives


U26433-J-Z247-2-7600 29

the same page identifier to the exit when it performs an output page call, as that of thepage that corresponds to the input record (see field OPXPGIDV).

For example, if a job consists of an odd number of output pages, you may request that thesorter generate a dummy page. This forces each pile to have an even number of pages,which eliminates the blank page when you reach the midpoint of the pile. It essentiallyplaces the blank page at the end of the file instead.

1. The exit may suppress the generation of this dummy page during any sort unit. Thissuppression is advantageous if the exit recognizes a simplex copy group and wishes toavoid wasting a sheet of paper for the dummy page.

2. Optionally, the exit may assign a special identifier to all dummy pages (usually x’FF’) sothe software can easily identify the dummy pages at page output time.

3. The exit may choose to assign the line count of each page to the page identifier. Thisassignment lets the software identify short pages at output time and optionally pad outto a full line count. Padding is vital when there is no carriage control in the data.

The SPSSIRXG member contains an implementation of this example.

4.2.4 Printing an Odd Number of Logical Pages

If a sorting unit has an odd number of logical pages (page sides), the sorter generates ablank logical page after the first logical page by default. This blank, so-called “dummypage,” prints on the backside of the first physical page to avoid a blank logical page in themiddle of the sorting unit. The software does not give any additional considerations to theN_Up implementations of the output.

The user exit can request the sorter to assign a specific page identifier for these dummypages. You can request this function in the initialization call using fields IRXDMYID andINXPGIDV in the IRXWAREA DSECT.

By setting the flag IRXNODMY in the exit, you can suppress the generation of this dummypage. This will be useful for special separator pages printed in simplex mode or othersimilar requirements.

4.2.5 Duplicating Output Pages

Another way to print an uneven number of logical pages is to request the sorter toduplicate the last logical page from a sorting unit. If the sorting unit has an even number oflogical pages after this duplication, the sorter does not generate a dummy page. Torequest this function, tell the exit to set the flag IRXDUPL after each input record call for asorting unit. This function is useful for separator pages that are part of the data stream, notsystem generated separator pages.


30 U26433-J-Z247-2-7600

4.2.6 Terminating Input File Processing

If the exit finds any error during the processing of an input file, it can request the sorter toterminate the processing of the file and return it to JES in a system hold state. The exitcan make this request when returning from an input record call. See the flag IRXTERM inthe IRXWAREA DSECT.

When the exit requests termination of the input file, the previous piles from the same filemay already be in the spool. If these piles are in the same output group, the sorter closesand de-allocates the output file, resets its output class (in order to purge this incompleteoutput), and places the input file on hold. The user exit can specify this so-called purgeclass. The default value for the sorter is class “Z,” which is the same class specified in thesample user exit. The exit can specify this purge class at the initialization call in flagIRXDEFPC and field INXDEFPC in the IRXWAREA DSECT.

4.2.7 Deleting Input Records

The exit can request the sorter to delete an input record, when returning from an inputrecord call, by setting flag IRXDEL on the IRXWAREA DSECT.

4.2.8 Inserting Input Records

The exit can request the sorter to add an input record via flag IRXADD and fieldIRXRECA1 in the IRXWAREA DSECT. This request inserts the new record after therecord passed to the exit in the input record call.

4.2.9 Adding Records to Output Pages

When the exit receives control at the output page call (after the sorter rewrites each re-sequenced page to the spool), the exit can add records to the end of these pages.

When the software calls the exit, all original records pertaining to the page are already inthe spool and the sorter passes the pointer to the output DCB to the exit. At read time andat output time, the software passes the page sequence numbers to the exit, as well as thenumber of records in the page and the page identifier. The exit can pass a page identifierto the sorter at input record time.

The sample SPSSIRXG has prototype code in comment statements. This prototype coderelates to the output page call. You can use this code as a model for any implementation.

See fields OPXDCBA, OPXISEQ, OPXOSEQ, OPXREC# and OPXPGIDV in theIRXWAREA DSECT.

4.2.10 Specifying the Output File Destination

When returning from the initialization call, the exit can specify the output class anddestination of the re-sequenced files written to spool.


U26433-J-Z247-2-7600 31

See flags IRXINIT, IRXCLASS, IRXDEST, IRXCLSOK, and fields INXCLASS, INXDESTand INXDESTL from the IRXWAREA DSECT. (See Appendix E.)

If you want multiple PSORT output classes, or destinations, you must run multiple copiesof the exit, each version coming from a different link library (STEPLIB).

4.2.11 Indicating a New Output Page

When returning from any input record call, the exit can indicate to the sorter that a recordstarts at a new page, for sorting purposes.

The sample user exit considers Channel 1 skips, from ASA or machine carriage control,as the indicators for a new page. For reports without carriage control, the sample user exitcounts 60 lines per page. If a page contains more than 60 print lines, the software insertsa page break.

Note: 60 print lines does not mean 60 input lines; it means the output spans 60 lines onthe page, including double and triple spacing.

A user-customized exit can account for any special criteria to decide the start of a newpage. The exit has access to the job name, PageDef name, FormDef name and most JCLparameters specified for the listing.

See bit IRXNEWPG in flag byte IRXFLAG2 and fields IRXPJSPA and IRXPPDSI inIRXWAREA.

4.2.12 Indicating a New Sorting Unit

When returning from any input record call, the exit can indicate to the sorter that therecord starts a new sorting unit (and a new page) by setting bit IRXNEWDS in flag byteIRXFLAG2. Setting this bit tells the sorter to interrupt the reading process and write all re-sequenced pages, processed since the last interruption (or beginning of the file). Thesoftware continues the read process, again calling the exit for each record.

Note: When the exit returns from the first record of a new file, it must indicate to thesorter a new sorting unit and new page.

4.3 A Few DOs and DON’Ts

The cardinal rule to remember: PSORT is for SYSOUT, including print data such asconsole logs, dumps, traces and assembler listings. The best data is pure line data thatusually prints on an impact printer. Any other type of print data requires programming ofthe exit, and may not even be possible.

PSORT is an aid to printing simplex data on a duplex continuous-forms printer. It is notintended to be a conversion tool to enhance the user’s print data with AFP.


32 U26433-J-Z247-2-7600

4.3.1 Absolutes

1. Each instance of PSORT can output to only one JES spool class. If you need multipleoutput classes, then multiple dummy printers must run.

The exception to this “absolute” is allowing the output data set to have the same classas the input, but then you must assign a different destination. You can assign thisdestination only at PSORT start-up, and you cannot change the assignment later. If youneed multiple destinations, then you must run multiple dummy printers. To run multipledummy printers, use a small STEPLIB to hold the exit.

2. PSORT is not worthwhile for short listings. The break-even point in paper consumptionis six to ten pages.

3. If you want to print data 2-up with PSORT, then you must use Enhanced N_Up in theFormDef. To use Enhanced N_Up, the customer needs the appropriate level of PPFAand/or SLE, and the twin system must have SRA controllers.

4.3.2 Subject to Negotiation

1. The processor assumes the data contains only skips to Channel 1. You mustaccommodate other channel skips with suitable programming.

2. The Data Maps in all PageDefs should have the same number of print lines. If thenumber of print lines is different, the exit must contain a table of PageDefs and DataMaps, with the number of lines in each.

3. You may need to program Conditional Processing into the exit, rather than allowing thePageDef to provide it. Conditional Processing may not be possible in all cases.

4. Invoke Medium Maps and Invoke Data Maps are the most common embeddedstructured fields. You must write code in the exit to accommodate these fields andmodify the resources to provide duplex output. If you can’t write this code and modifythe resources, the data wasn’t PSORT eligible to begin with. You must evaluate otherstructured field types on a case-by-case basis.

5. The customer should use a single standard paper size for all PSORT output.

4.4 Suggested Approach

1. Study this manual.

2. Obtain a complete sample of the data you want to process with PSORT. Do not agreeto implement anything other than pure line data until you have a chance to analyze thesamples.


U26433-J-Z247-2-7600 33

3. Study the source code for the exits (members SPSSIRX, SPSSIRXG, and/or SPSSIRXIin data set SPSSAMP). All sets of source code contain many comments, but SPSSIRXcontains some obscure logic concerning Invoke Medium Maps and Invoke Data Maps,which should be studied carefully for implementation of that logic.

4. Enable debugging WTOs in SPSSIRXG or SPSSIRXI and observe the operation ofPSORT on some of your target input, before attempting to modify either exit code.

5. Customize one of the example exits for the simplest possible sample of the data.Implement the exit and get it running to gain an understanding of the facility. If youneed a more complex implementation, run this first PSORT while you attempt toimplement the more complex exit.

6. Decide whether you can add features to the exit to accommodate the more complexcustomer data.

4.4.1 Some Hints to the Programmer

• You cannot read from a given spool class and then write back to that same class,unless you assign a different destination to the output. If you don’t assign a differentdestination, jobs circulate rapidly through PSORT and the resulting output resembles ashuffled deck of cards.

• All sample exits are well commented, but some obscure logic comes into play when theexits encounter Invoke Medium Map, Invoke Data Map, and Begin/End Documentstructured fields. You may wish to study this logic carefully.

• The exit controls page boundaries, not the sorter. The sorter passes a stream ofrecords to the exit, and expects the exit to set flag IRXNEWPG every time a recordstarts a new page.

• If you want the exit to split the input into multiple output piles, set IRXNEWDS inaddition to IRXNEWPG when you want to start a new pile. If you want these piles to beseparate output groups on the spool, also set IRXNEWDD.

• You get a single call for initialization, then one or more input record calls, then one ormore output page calls, then input record calls again. You can see an output record calleach time you set IRXNEWPG, plus an additional call for the dummy page if an outputpile has an odd number of pages. The sorter detects an odd number of pages andgenerates a dummy page unless the exit suppresses the dummy page. To suppressthe dummy page, set bit IRXNODMY at every input record call until the processreaches the end of that data set. The sorter pays attention to IRXNODMY only at thelast opportunity. You can’t set IRXNODMY once and forget it. You must keepreminding the sorter until you reach the end of the current output pile.

• You can delete input records, or add records behind them. If you add a record, thesoftware calls the exit for that new record before calling the exit for the next input recordfrom spool.


34 U26433-J-Z247-2-7600

• If you need to add a record before the current input record, you must capture therecord, change the original, and then add the original behind the changed copy. Youcan change the contents of a record (including the carriage control character and TRCbyte), but the sorter abends if you try to change the record length. This ABEND occursbecause the sorter maintains the records in a special chain. If you need to change thelength of a record, delete the original and add a new record to replace it.

• If you need to support 2-up, you need Enhanced N_Up in your FormDef. Refer to 7Two-up Printing on page 65.

• During the initialization call, set IRXOPGRP, IRXREVRS, both or neither. This is theonly time these flags will be checked, and the resulting output page flow will be set.

4.4.2 Input Carriage Control

There are three types of carriage control:

• ASA

• Machine

• None

You need to program the PSORT exit to handle all three carriage control types, unlessyou set the IRXOPGRP flag. If this flag is set in the initialization call, then the exit will onlyencounter Machine carriage control. Because multiple datasets within an output groupmight have different carriage control specified, some choice must be made for the outputfile. Machine carriage control is the most flexible option, so all output will be converted tomachine carriage control before the exit receives the record. If you do not set IRXOPGRP,then the output of PSORT always has the same carriage control type as the input file. Ifthe programmer does not want to support any particular type of carriage control, programthe exit to reject the input file and issue an error message.

4.4.2.1 ASA

The following chart shows the valid ASA carriage control codes for the sample exit:


U26433-J-Z247-2-7600 35

EBCDIC Hex Comments

1 x’F1’ Skip to Channel 1 and print.

(blank) x’40’ Space 1 line and print.

0 x’F0’ Space 2 lines and print.

– x’60’ Space 3 lines and print.

+ x’4E’ Overprint (line merge) previous line.

! x’5A’ Structured Field (described on page36).

Figure 7: Valid ASA Carriage Control Codes

ASA is an artificial carriage control system that makes it easy for a programmer. The printdriver, but not PSORT, is responsible for converting each ASA carriage control into one ortwo machine commands.

ASA takes the approach of “space then write,” positioning the printer according to thecarriage control byte, then printing the data.

Skips to Channels 2–12 (“2” through “0” and “A”, “B”, “C”) are not allowed unless you addlogic to the exit. The reason is: the exit must track the position of each input line on theoutput page. The exit must recognize when page overflow occurs, then break eachoverflowed page into two distinct output pages. If you do not produce two distinct outputpages, the FormDef causes the overflow lines to appear on the back of the page (due toduplexing), scrambling the front-back relationship of all following pages.

If you want to enable channel skips 2–12, you need to code the exit to track any supportedData Maps in all PageDefs you use. This coding is necessary so the exit “knows” whereeach channel falls on the output page. Other than the custom of making Channel 1 thefirst print line (this is a requirement for proper PSORT functioning), channels may fall inany order and at any printable location on the page. Remember, PSORT is for SYSOUT,so any extension of functionality must be implemented by EXIT code.

4.4.2.2 Machine

The following chart shows the valid Machine carriage control codes for the sample exit:

EBCDIC Hex Comments

(unprintable) x’01’ Write without spacing.

(unprintable) x’09’ Write and space one line.


36 U26433-J-Z247-2-7600

(unprintable) x’11’ Write and space two lines.

(unprintable) x’19’ Write and space three lines.

I x’89’ Write and skip to Channel 1.

(unprintable) x’0B’ Space one line immediately.

(unprintable) x’13’ Space two lines immediately.

(unprintable) x’1B’ Space three lines immediately.

(unprintable) x’8B’ Skip to Channel 1 immediately.

! x’5A’ Structured Field (see below).

Figure 8: Valid Machine Carriage Control Codes

Machine carriage control differs from ASA by taking the approach of “write then space”.The processor prints the data, and then the printer moves to another print line.

As with ASA, you must provide programming for Channels 2–12.

Remember, if you set IRXOPGRP, then all print is converted to machine carriage controlbefore the exit examines the records.

4.4.2.3 No Carriage Control

If an input file does not specify a carriage control, the exit counts lines and indicates apage break every 60 lines. The SPSSIRX code uses variable LINECT to set this number.The SPSSIRXG or SPSSIRXI code uses the variable DEFAULT#. In each example, thisvalue is set at assembly time, and may be changed if you require a different number. Ifyou want to code for multiple PageDefs or FCBs, you must change the exit to produce apage break at the appropriate line count.

The exit must pad out a dummy page if the sorter generates it. The reason is theprocessor uses the dummy page (a single blank line) to make reports, with an odd numberof pages, come out even. The sorter places this dummy page at the logical end of theinput data. When sorted, the last dummy page appears as the second page in the outputqueue, because it prints behind the first page. Because there are no channel skips toguide data placement, it is important for every output page to have the same number oflines.

4.4.3 Structured Fields

The PSORT exit allows a very small subset of the structured fields normally allowed in linedata. You may be able to accommodate other structured fields by adding the necessarylogic to the exit.


U26433-J-Z247-2-7600 37

Identifier Mnemonic Comments

D3 AB CC IMM Invoke Medium Map (Copy Group).

D3 AB CA IDM Invoke Data Map (Page Format).

Figure 9: Recognized Structured Fields

4.4.3.1 IMM — Invoke Medium Map

You can use Copy Groups to switch between simplex print for banner pages and duplexfor data. SPSSIRXG and SPSSIRXI contain code to recognize certain copy groups andtell the sorter to suppress the dummy page. If you do not suppress the dummy page,spurious blank pages appear after every banner page.

IMM records cause a page break (new physical sheet) like AFP printing. Page breaksmay disrupt the continuity of the output.

4.4.3.2 IDM — Invoke Data Map

As with the Copy Group, the exit provides code that you can customize to recognizecertain Page Formats, and perhaps adjust the page line count to match the PageDef inuse.

4.4.4 Programming for Structured Fields

SPSSIRXG includes 3 macros to make programming these IMM and IDM records easier:

1. PDEF pname, dmaplist, flags

This macro corresponds to an entry in the list of PageDefs that PSORT understands. Theoperands are:

Pname The name of the PageDef. Do not include theP1 prefix.

Dmaplist The address of the list of Data Maps in thisnamed PageDef.

Flags Dataset characteristics. These flags correspondto the values set in IRXFLAG5.

2. DMAP dname, numlines

This macro corresponds to an entry in the list of Data Maps associated with a PageDef.The dmaplist entry of the PDEF macro points to this list. The operands are:


38 U26433-J-Z247-2-7600

Dname The Data Map name. You may need to refer tothe source code for the PageDef. Data Map isalso known as PAGEFORMAT. If you don’thave the source code, the names of the DataMaps are listed in the Begin Data Mapstructured field (‘D3A8CA’x).

Numlines The number of lines in this named Data Mapbefore the system generates an implicit start ofnew page.

3. FDEF fname, pname, flags

This macro corresponds to an entry in the list of FormDefs that PSORT understands. Theoperands are:

Fname A valid FormDef name. Do not include the F1prefix.

Pname The only PageDef that you can use with thisnamed FormDef.

Flags Dataset characteristics. These flags correspondto the values set in IRXFLAG5.

Here are some suggestions for incorporating the logic of these three macros intoSPSSIRXG:

1. Create a table of PageDefs after label PDEFLIST.

2. Create a list of Data Maps at the dmaplist label for each PageDef; e.g., P1ONE#UP.

3. Specify the corresponding number of lines per page for the list of Data Maps.

4. Build a table of FormDefs after the label FDEFLIST if you need FormDef logic.

5. Add this logic to the exit. Statement labels LU$PDEF and LU$FDEF are located at theplaces to insert logic to accommodate your requirements.

6. Call LU$PDEF and/or LU$FDEF from SF$IMM, SF$IDM, INITSORT, or any otherappropriate program location.

4.4.5 Page Breaks

Under all circumstances, the exit keeps track of the number of lines printed on each page.If the page overflows, the exit must signal a page break to the sorter. The exit should thenmodify the output data as follows:


U26433-J-Z247-2-7600 39

4.4.5.1 ASA

No matter what the carriage control is, if an input line overflows the page, the exit changesthe record’s carriage control to “1” (Skip to Channel 1 and Print). This change places therecord at the top of a new page.

4.4.5.2 Machine

If an input line would cause page overflow, the exit copies the line to a work buffer andchanges the original record to an x’8B’ command (Skip Immediately to Channel 1). Theprocessor then indicates that a record must be added (IRXADD set to 1) and points to thecopy of the original record in the work buffer.

4.4.5.3 No carriage control

There is nothing you can do except tell the sorter the line starts a new output page.Dummy pages are padded out from a single line to DEFAULT#.

4.4.5.4 Page Break Detection Table (NEWTABLE)

Mixed mode print data presents a challenge to PSORT. The following input records causea page break when printing to an AFP:

• IMM — Invoke Medium Map

• IDM — Invoke Data Map

• Channel 1 — Skip immediately to Channel 1 (machine), Write and Skip to Channel 1(machine), and Skip to Channel 1 and Write (ASA).

The processor treats some combinations of these records as a single page break. Forinstance, this sequence may appear in mixed-mode data:

IMM

IDM

X’8B’

Together these three records cause a single page break, which is a feature of the AFParchitecture.

In order to accommodate all possible combinations of IMM, IDM, Channel 1, and ordinaryprint lines, SPSSIRXG and SPSSIRXI implement a new page lookup table, “NEWTABLE.”The software consults the table to determine when page breaks occur. Refer to thesample code for complete documentation of NEWTABLE.


40 U26433-J-Z247-2-7600

4.5 Flags Used by the Exit

4.5.1 IRXFLAGS

These flags are checked only during the initialization call and remain in effect for theduration of the PSORT dummy printer execution.

Value Name Comments

80 IRXOPGRP This flag determines whether pile boundaries occur at dataset level or atoutput group level. Setting this flag to 1 causes the sorter to process alldatasets within an output group as a single input file. Setting this flag to 0causes a pile break at the dataset level.

If you activate output group level sorting, all records encountered by theSPSSIRX exit will have machine carriage control.

This flag may be set by the exit, but only during the initialization call.

40 IRXREVRS This flag selects the option of merely reversing the pages within a pile. NoPSORT interleave of records from the beginning and end of file occurs. Thisoption is intended for SIMPLEX printing.


20 --- reserved ---

10 --- reserved ---

08 IRXTUPTY Text unit priority.

If this flag is set, then text units from SPSSIRX will override text units fromthe input file.

If this flag is not set, the text units from the input data set are preserved, andany conflicting text units supplied by the exit are discarded.


04 IRXRSVTU If set, the exit will supply the list of exactly six special reserved text units inthe field IRXRTUL.

If not set, the sorter will use the six default text units.


U26433-J-Z247-2-7600 41

02 IRXCPYCO When IRXOPGRP is set, this flag controls the collation of copies.

If set, print data sets within an output group which have identical copiesspecifications will be sorted as a group, and the copies value will apply to theentire group.

If not set, print data sets within an output group which don’t specify exactlyone copy will be sorted separately. The copies value will this apply to thisseparate print data set.

01 --- reserved ---

Figure 10: IRXFLAGS — Initialization Flags

4.5.2 IRXFLAG1

Once set, do not allow the exit to change the bits in Flag 1. The sorter does not changethe contents of Flag 1, except the processor sets the bit IRXINIT for the single initializationcall at start up time.

Value Name Comments

80 IRXINIT Calls the exit for initialization of the PSORT environment. The exit canspecify characteristics for all output data sets.

This flag resets after the first initialization call. Remaining flags ofIRXFLAG1 do not change.

Set by the sorter on the first call to the exit; never set again.

40 IRXCLASS Output class is in the exit in field INXCLASS. The sorter ignores this bit ifIRXCLSOK is set. Set by the exit, if needed.

20 IRXDEST Output destination is in the exit in fields INXDESTL and INXDEST.

Set by the exit, if needed.

10 IRXMAXSH Maximum number of physical pages in a pile is in the exit in fieldINXMAXSH. If not set, the default pile size is 1000 sheets.


08 IRXROUND Round output pile sizes to (approximately) equal values.

04 IRXDMYID A default page identifier for dummy page is in the exit in field INXPGIDV.


02 IRXCLSOK Do not override the output class; it’s OK. This flag tells the processor toignore IRXCLASS.


01 IRXDEFPC Default purge class is in the exit in field INXDEFPC.



42 U26433-J-Z247-2-7600

Figure 11: IRXFLAG1 — Initialization Flags


U26433-J-Z247-2-7600 43

4.5.3 IRXFLAG2

The exit may set these flag bits to tell the sorter about the status of the current inputrecord. The sorter clears the contents of Flag 2 before calling the exit with an input record.The contents are indeterminate when the processor calls the exit for initialization andoutput pages.

Value Name Comments

80 IRXNEWDS The current record starts a new output data set. When you set this bit, youmust set bit IRXNEWPG at the same time.

When returning from a call for the first input record of a data set, you mustset both IRXNEWDS and IRXNEWPG bits.

40 IRXNEWPG The current record starts a new page.

When returning from a call for the first input record (field IRXREC# containsa value of 1), you must set both IRXNEWDS and IRXNEWPG bits.

20 IRXDUPL Duplicate the last logical page in this sorting unit.

If the sorting unit has an even number of logical pages after this duplication,the sorter does not generate a dummy page. The exit should set the flagIRXDUPL after each input record call for a sorting unit.

10 IRXTUNIT Text Units are in the exit.

You can assign text units at the beginning of each input file.

08 IRXNEWDD Associates a new output data set with a new OUTADD, DYNALLOC andOPEN process.

04 IRXTERM Terminate the current input data set and return it to JES in system holdstate. You can request this operation when returning from any input recordcall.

When the exit requests termination of the input file, the sorter may havewritten the previous piles from the same file to the spool. If these piles areall written in the same output group, the sorter then closes and de-allocatesthe output file, resets its output class (in order to purge it), and places theinput file on hold.

02 IRXDEL Delete the current record.

01 IRXPGID Sets a page identifier in OPXPGIDV. This identifier is available inOPXPGIDV when the sorter calls the exit with an output page. The lastvalue returned for a page is the value that was captured by the sorter.Therefore, the value returned at output time is the line count for the page.

You need to tell the sorter to assign x’FF’ to dummy pages (see flagIRXDMYID in Flag 1). This assignment allows the system to identifydummy pages at output page time.

Figure 12: IRXFLAG2 — Status of Current Record


44 U26433-J-Z247-2-7600

4.5.4 IRXFLAG3

At entry, the exit tests bit IRXOUTP. If it is set, a page is in the spool, and the exit has theopportunity to add additional records to the end of that page. The exit may set the otherflags to tell the sorter about the status of the current record.

The sorter clears the contents of Flag 3 before calling the exit with an input record. Thecontents are indeterminate when the processor calls the exit for initialization and outputpages, except for bit IRXOUTP.

The processor tests this flag upon entry to the exit. If it is set, the processor branches tolabel “OUTPUTPG”.

Value Name Comments

80 IRXADD Process the current record according to the flags in IRXFLAG2 and addthe record that IRXRECA1 points to.

Note: The next call to the exit from the sorter is for the added record.

40 IRXNODMY Do not print a dummy page for this output data set.

If a sorting unit has an odd number of logical pages (page sides), thesorter generates a blank logical page after the first logical page.

If the exit does not want the sorter to create this dummy page, the exitmakes this request by setting the flag IRXNODMY when returning fromeach input record call for a sorting unit.

20 — reserved —

10 — reserved —

08 — reserved —

04 — reserved —

02 — reserved —

01 IRXOUTP A complete page is in the spool. The exit may then add additional recordsfor that page.

Figure 13: IRXFLAG3 — Status of Current Record


U26433-J-Z247-2-7600 45

4.5.5 IRXFLAG4, IRXFLAG5 and IRXFLAG6

The sample exits build Flags 4, 5, and 6 in the IRXUINFO portion of the IRXWAREADSECT. These flags have meaning only to the exit, and are used to maintain currentstatus information. They have no intrinsic meaning. The sorter clears these fields beforeinitialization, but does not clear, set, or check any flags after initialization. The usage ofthese flags for the samples is as follows:

4.5.5.1 IRXFLAG4

The exit uses Flag 4 to maintain internal information between calls

Value Name Comments

80 IRXTUINI Text units are initialized.

40 IRXTUSET Text units are set.

20 IRXSETNS At next input page, set a new output data set.

10 IRXINPUT Current call is for an input record (composite of neither bitIRXFLAG1/IRXINIT nor IRXFLAG3/IRXOUTP set).

08 — available for custom use —

04 WTO@EXIT Used by the WTO debugging routine.



Figure 14: IRXFLAG4 — Internal Status

4.5.5.2 IRXFLAG5 and IRXFLAG6

The sample exit SPSSIRXG builds these flags by examining conditions on the input dataset. Study the “BEHAVIOR” table, which you see only by setting flag &TESTBEH and re-assembling SPSSIRXG. These flags do not exist in the sample exit SPSSIRX.

After the exit constructs Flag 5 by setting bit fields to indicate the input conditions, it usesFlag 5 as an index to fetch a byte from the “BEHAVIOR” table. The fetched action byte isstored in Flag 6.


46 U26433-J-Z247-2-7600

4.6 Separator Pages

4.6.1 Adjustments to the Banner Page

Print jobs lose some of their characteristics when passed through PSORT. This lossoccurs because PSORT is a continuously running, started task, and has its own jobcharacteristics. When it opens a file for output, that file is associated with the PSORT task,not the original job. The processor takes print jobs from the spool, sorts them, and sendsthem back to spool via a DD statement that belongs to PSORT. Separator pages onlyapply to real printers, not the PSORT virtual printer.

Members in the SPS link library (SPSMHDRA, SPSMMSGA, SPSMSEPA andSPSMTLRA respectively) generate all banner pages (header, message, data setseparator, and trailer). Like-named members in the SPSSAMP library provide samplesource code. To specify a banner page with a name other than the default name, code anoverride in the SETUPxxx member of SPSPARM. For example:

SEPLMOD(SPSMSEPA)

Installations that depend on job separator pages need to make special provisions toalleviate this problem. You can correct this problem by coding the exit to move volatilebanner page information into alternate locations.

The sample exit code from SPSSAMP member SPSSIRX protects the following variables:

Original Variable New Location Comments

%JOBN %DEL1(1,8) Job name.

%JOID %DEL1(11,8) Job ID.

%PGNA %DEL2(1,20) Programmer name.

%GRPN %DEL3(1,8) Output group name.

%DDNA %DEL4(1,8) Data set DD name.

Figure 15: Banner Page Variables

Any job characteristic the installation deems important may be saved in this manner.


U26433-J-Z247-2-7600 47

4.7 Input Fields to the Exit

The following chart illustrates the relationship between the output fields available to theIPLINE macro and the input fields available to the PSORT exit.

These fields are valid before PSORT processes the data set.

SPSSIRX Field Width Comments

IRXADDR1 60 Delivery address line 1 from the OUTPUT JCL statement. If notpresent, you may use the WAADDR1 variable from the work attributessegment of the user profile definition in RACF, or a similar product.

IRXADDR2 60 See the discussion for IRXADDR1.



IRXBUIL1 60 Building from the OUTPUT JCL statement. If not present, you may usethe WABLDG variable from the work attributes segment of the userprofile definition in RACF, or a similar product.

IRXDEVAD 3 Printer address. This field is blank because the PSORT printer is adummy device.

IRXDEVNM 8 Printer name as coded in the SPSPRINT member.

IRXDSDDN 8 DDNAME of the print data set.

IRXDSSNM 8 Step name of print data set.

IRXGRPD 8 Destination of output.

IRXJOBID 8 Job number.

IRXJOBNM 8 Job name.

IRXPNAME 20 Programmer name from the JOB card.

IRXSOCL 1 Output class of printed job.

JSPJRMNO 60 Programmer room from OUTPUT statement. If not present, use theWAROOM variable from the work attributes segment of the user profiledefinition in RACF, or a similar product. Also the “R=” parameter of the


48 U26433-J-Z247-2-7600

/*JOBPARM card.

Figure 16: Input Banner Variables


U26433-J-Z247-2-7600 49

4.8 Variables for the IPLINE MACRO

The following chart illustrates the relationship between the output fields available to theIPLINE macro and the output fields the PSORT exit creates or adjusts.

IPLINEVariable Width

SPSSIRXField Comments

%ADDR 3 Printer address for the real printer used to print the data set.

%BLDN 60 IRXBUIL1 In the SPSSIRX sample in SPSSAMP, positions 1–8 contain theoriginal output group name.

%CLAS 1 INXCLASS Output class of printed job.

%CONT 5 START: original print job.CONTI: restart of a print job after a checkpoint.REPOS: restart of a print job after repositioning due to operatorcommand or an I/O error on the printer.

%COPY 3 Copy number.

%DATE 8 Print date in the format DD/MM/YY (Europe).

%DAT1 8 Print date in the format MM/DD/YY (USA).

%DDNA 8 DDNAME of the PSORT print data set. This variable is the same forall jobs that pass through PSORT.

%DEL1 60 IRXADDR1 Positions 1–8 contain the original job name. Positions 11–18 containthe original job number.

%DEL2 60 IRXADDR2 Positions 1–20 contain the original programmer name from the JOBcard.

%DEL3 60 IRXADDR3 Positions 1–8 contain the original output group name.

Figure 17: Variables for the IPLINE Macro


50 U26433-J-Z247-2-7600

IPLINEVariable Width

SPSSIRXField Comments

%DEL4 60 IRXADDR4 Positions 1–8 contain the original DDNAME of the print data set.

%DEPT 60 Department from the OUTPUT statement. If not present, use theWADEPT variable from the work attributes segment of the userprofile definition in RACF, or a similar product.

%DEST 8 IRXGRPD Destination of output.

%FORM 8 Form name specified in the DD SYSOUT statement in the JCL.

%GRPN 8 Group number

%GRP1 3 Group number.

%GRP2 3 Group number.

%JOBN 8 IRXJOBNM Job name of PSORT.

%JOID 8 IRXJOBID Job number of PSORT.

%NAME 60 Programmer name from the OUTPUT statement. If not present,use the WANAME variable from the work attributes segment of theuser profile definition in RACF, or a similar product.

%PGNA 20 IRXPNAME Programmer name from the JOB card of PSORT.

%PRTN 8 IRXDEVNM Printer name as coded in the SPSPRINT member.

%ROM1 60 JSPJRMNO Programmer room from OUTPUT statement. If not present, usethe WAROOM variable from the work attributes segment of theuser profile definition in RACF, or a similar product. Also the “R=”parameter of the /*JOBPARM card.

%RTIT 60 Report title from OUTPUT statement.

%SEGI 5 Printout segment identifier (JES2 V4 and above).

%STEP 8 IRXDSSNM Step name of print data set.

%SYID 4 SMF system name.

%TIME 8 Time of printing in format HH:MM:SS.

%USER

%US00 255 Installation-supplied user variables. There are 64 of them,numbered %US00 through %US63.


U26433-J-Z247-2-7600 51

Figure 18: Variables for the IPLINE Macro (cont’d.)

4.8.1 SPSMSEPS

See Appendix E Sample SPSMSEPS Dataset Separator Page for a sample of the codingfor the dataset separator page. The code in the Appendix uses the variables described inthis section.

4.8.2 Using the FORMS Control Table

When the output from PSORT is in a unique output class, you may specify that thealternate separator page module is active only for PSORT jobs. For instance, if thePSORT output is placed into output class Q, and standard non-PSORTed output is placedinto class J, prt5 (our real printer in the above examples) can be set to service bothclasses:

$tprt5,q=qj

If our SPSPRINT member contains:

PRT(PRT5) CUU(0480,0481) SETUP(SETUP480) FTBL(FORMxxx)

We can then use a FORMxxx member to specify the following:

FORM(++++++Q) MOD(HSMTssss)

The appropriate HSMTssss member would appear as

SEPLMOD(SEPMSEPS)

Text Units

U26433-J-Z247-2-7600 53

5 Text UnitsThe following information explains the indirect access PSORT uses for dynamic output(via the OUTADD macro) Text Units. See Appendix C for a description of the text unitsthat PSORT needs. See the IBM publication, MVS Programming: Authorized AssemblerServices Guide, for additional information on the usage of this function.

5.1 Text Units Used by the PSORT Exits

This chart is not absolute. You can always change the usage of these text units to free upone, or more, text units for your own use. The following table lists the text units which aremapped by default in the IRXWAREA DSECT.

Text Unit Description Comments

DOADDRES DeliveryAddress

Four 60-byte entries. The PSORT generic exit uses this field topreserve the Job Name, Job ID, Programmer’s Name, Output GroupName, and Data Set DD Name for the banner page exit.

DOBUILD BuildingLocation

One 60-byte entry.

DOROOM RoomIdentification

One 60-byte entry.

DODEPT DepartmentIdentification

One 60-byte entry set to blanks by the default exit. The generic exitreplaces this text unit in order to add a PageDef name to print datasets that lack PageDefs.

DOTITLE Separator PageTitle

One 60-byte entry set to blanks by the default exit. The generic exitreplaces this text unit in order to add a FormDef name to print datasets that lack FormDefs.

DOUSER User Defined Data 16 60-byte fields, which are unused in the generic exit.

Figure 19: OUTADD Text Units Used by the Generic Exit

Text Units

54 U26433-J-Z247-2-7600

5.2 Available Text Units

The exit allows you to set up to a maximum of six text units. The sample exits use only thefirst five, as described above, and initialize the sixth to blanks. The portion of theIRXWAREA DSECT that starts at label IRXTULST contains the six address constants thatpoint to the respective text units, which the exit may specify. Specify an address of zerofor any unused text unit pointer.

You can re-program any of the six text units. If you assign text units that are duplicates ofany text units associated with the original file, one or the other must be discarded. Youcontrol which is preserved via the IRXTUPTY flag of IRXFLAGS. If you set this flag on, theexit supplied text unit will be honored and the original attribute discarded. The defaultaction if IRXTUPTY is off is to discard the exit-supplied text units. This gives you theopportunity to override existing attributes of the input file, or to prevent the exit from settinginappropriate values.

The actual text unit area (which starts at label IRXADDR and ends just before labelIRXUINFO) may be used in any manner, but by default, the above six text units aremapped. Please see the source for the IRXWAREA DSECT to see an example of how toformat these text units.

5.3 The OUTADD Macro

The processor uses the OUTADD macro to create an output descriptor for a SYSOUTdata set. PSORT uses an OUTADD call to set some of its own text units, plus the textunits which are provided by the exit. When the sorter issues the OUTADD macro, the textunits supplied in the parameter list contain:

1. Information from the input print data set. Unless you supply an override in the user exitand set IRXTUPTY on, all attributes of the input data set transfer to the output data setexcept for DEFAULT and JESDS. While attributes generated as a result of theseparameters are preserved, the parameters themselves do not apply to the output.

2. Information passed from the exit when the IRXTUNIT flag of IRXFLAG2 is on, usuallyfor the first record in a file.

Text Units

U26433-J-Z247-2-7600 55

5.4 Conflicting Text Units

If the exit supplies a text unit that matches a text unit already associated with the input file,you will receive a warning message (SPR0012W) on the system log. This notificationalerts you to this conflict so that you can determine whether your override is appropriate. Ifyou wish to eliminate this message after the initial implementation phase is complete(especially if you expect the message to occur due to installation implementationdecisions), you may use the standard SPS message suppression method to eliminate themessage. See the SPS Administrator’s Guide for details on how to suppress messages.

Troubleshooting Advice

U26433-J-Z247-2-7600 57

6 Troubleshooting Advice

6.1 Debugging Code

6.1.1 Variable Display

The SPSSIRXG version of the exit program contains optional WTO code. You can issuea debugging WTO:

• at start-up of the program. The results show the assembly date and time of the exit.

• at calls to the exit. The results show the type of call (initialization, input, and output)along with the contents of the first five flag bytes.

• at return to the sorter. The results show the new contents of the flag bytes.

• when dumping banner page variables.

• when dumping text units.

• when displaying the contents of the JSPA and PDSINFO.

You enable debugging WTOs by setting switches in the source code and re-assemblingthe exit. The exit grows in size with each debugging feature you enable.

6.1.2 Memory Dump Display

If you are developing your exit from SPSSIRXG, you can display 24 bytes of exit memoryby loading Register 15 with the address of the first byte, and calling subroutine“WTO$DUMP”. You can include the dump code by setting a switch and re-assembling.There are examples of this technique sprinkled throughout the code. When you havefinished with your testing and are ready for the exit to become production code, youshould comment out these calls.

6.2 Troubleshooting Text Units

If you accidentally duplicate a text unit set by the sorter, but don’t understand why thisoccurred, you can do two tasks to check the sorter actions:


58 U26433-J-Z247-2-7600

1. Trace the sorter (“SPSSSORT”) using PER (see the appropriate IBM documentation).

2. Trace SPS.

6.3 Tracing SPS

An SPS trace shows calls to the system for setting text units. In addition, the trace showsthe SJFREQ call to obtain text units assigned to an input print data set.

1. Drain the dummy PSORT printer.

2. Run the failing job and make its output ready to print on the PSORT printer. Do nothave other jobs available for the PSORT printer to select for printing. For our traceexample, we use the JCL shown in Figure 20.

3. Follow the instructions in Section 6.5 of the “SPS/MVS Installation Guide” to enabletracing of the PSORT printer.

• Set the trace level to 3.

• Set the trace file to USER.

• Set the trace type to ALL.

4. Start the PSORT printer and note the time of the “OUTGRP=1.1.1” message on theoperator console.

5. Note the time of the ensuing SPR0006E or SPR0012W message.

6. Drain the PSORT printer.

7. Run FPTRACE (see Figure 20 Sample Trace Generation Job) with the followingparameters. Use the first time you noted from the OUTGRP=1.1.1 message asHHMMSS, and the second time from the SPR0006E or SPR0012W message ashhmmss:

• OUTPUT(TRACE)

• TIME (HHMMSS-hhmmss)

8. Scan the listing the trace produces and locate an entry like the following (look for “IPTTEXT UNIT DATA”):

PS BUFFER 018A 04 >>> IPT TEXT UNIT DATA 000001F0

TUDATA (03DFBEB4)

0000 E2D1D7C6 021C0109 D6E4E3D7 E4E34040 D6E4E340 40404040 00000000 000C0001 *SJPF....OUTPUT OUT

......*


U26433-J-Z247-2-7600 59

0020 007FE6C3 C1D1C5E2 40404040 40404040 40404040 40404040 40404040 40404040 *..WCAJES

*

0040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 *

*

0060 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 *

*

0080 40404040 40404040 40404040 40404040 40404040 40404040 40404040 40404040 *

*

00A0 40002E00 01002CE2 C9E2F1D9 D34BC2D3 E4C57BE7 4BC1C6D7 D3C9C240 40404040 *

......SIS1RL.BLUE#X.AFPLIB *

00C0 40404040 40404040 40404040 40404040 40404000 0D000100 04E2E3C4 40001000 *

.....STD ...*

00E0 010008E2 D6D9E340 40404000 15000100 01000016 00010000 00170001 00010000 *...SORT

...................*

0100 18000100 08D3C9D5 C5404040 40000100 01000104 00020001 0004C7E3 F1F50009 *.....LINE

...........GT15..*

0120 00010001 01 *.....

*

Figure 20: Sample Trace of Text Units

The above Figure should resemble your trace entry, but differs in the details due todifferent characteristics in your print file. The text unit list starts at offset 001C. A decodefollows:


60 U26433-J-Z247-2-7600

Key Key Name Text Unit

000C DODEST WCAJES

002E DOUSERLI SIS1RL.BLUE#X.AFPLIB (This text unit was explicitly supplied by anOUTPUT statement in the JCL).

000D DOFCB STD (This text unit is a JES default for the dummy printer).

0010 DOFORMS SORT (This text unit was explicitly supplied by an OUTPUT statement inthe JCL)

0015 DOLINECT x’00’

0016 DOMODIF6 x’00’

0017 DOMODIF7 x’00’

0018 DOPRMODE LINE (This text unit was explicitly supplied by an OUTPUT statement inthe JCL).

0001 DOBURST x’04’

0002 DOCHARS GT15 (This text unit is a JES default for the dummy printer).

0009 DOCOPIE9 x’01’ (Default of 1 copy).

Figure 21: Text Units Shown in Sample Trace

Notes:

• The trace shows the text units set by the exit, by the label “IPT SORT OUTADD TEXTUNITS” in the trace. By searching for this string in the trace you can check the formatof any text unit data supplied by the exit.

• As an alternative to using this trace facility, you may set equate &TXTUNIT to 1 andre-assemble the sample exit. This setting gives you a hexadecimal dump of the textunit list on the console.

• If you wish to set your own resource names such as PageDef and FormDef, makesure the resource names are blank first. Refer to the section that begins at label“IRXJOBNM” in work area IRXWAREA.


U26433-J-Z247-2-7600 61

//SUSER JOB 'ACCOUNT #','NAME',MSGLEVEL=(1,1)//*//* FPTRACE - UNLOAD SPS TRACE RECORDS//*//********************************************************//* SAMPLE JOB TO GENERATE ITF TAPE//********************************************************//*//S1 EXEC PGM=SPSMPTRC//STEPLIB DD DSN=SPS.SPSLINK,DISP=SHR//TRMSG DD SYSOUT=*//*TROUT DD DSN=ITF.desc.data,VOL=SER=volser,UNIT=TAPE,//* DISP=(NEW,KEEP)//TRIN1 DD DSN=SPS.TRA1nnnn,DISP=SHR//TRIN2 DD DSN=SPS.TRA2nnnn,DISP=SHR//SYSIN DD * PRTSEG(1,2,3)/*

Figure 20: Sample Trace Generation Job

Some information comes from the setup for the PSORT printer:

$DU,PRT781$HASP603 PRT781 UNIT=,STATUS=INACTIVE,BURST=NO,CKPTLINE=0,$HASP603 CKPTMODE=PAGE,CKPTPAGE=10,CKPTSEC=0,CREATOR=,$HASP603 DEVFCB=,DEVFLASH=****,FCB=STD,$HASP603 FORMS=(SORT,,,,,,,),FSS=PRT781,JOBNAME=,$HASP603 LASTFORM=SORT,LIMIT=(0,*),COPYMARK=DATASET,$HASP603 MARK=NO,MODE=FSS,NEWPAGE=DEFAULT,NPRO=0,$HASP603 PAUSE=NO,PLIM=(0,*),PRESELCT=NO,PRMODE=(LINE),$HASP603 QUEUE=A,RANGE=(J1,32767),ROUTECDE=(LOCAL),$HASP603 SEP=NO,SEPCHARS=DEFAULT,SEPDS=NO,SETUP=NOHALT,$HASP603 SPACE=,TRACE=NO,TRANS=DEFAULT,TRKCELL=YES,$HASP603 UCS=GT15,UCSVERFY=NO,VOLUME=(,,,),WRITER=,$HASP603 WS=(W,Q,R,PRM,LIM,F/UCS,FCB)

Figure 22: JES Printer Information


62 U26433-J-Z247-2-7600

STC17890 00000290 0003708E E2C9 E2F1 D9D3 D6E2 D1D6 C2F1 F7F8 F9F1 D7D9 E3F7 F8F14040STC17890 00000290 000370A6 4040 4000 F140 4040 4040 4040 0001 0001 D3D6 C3C1 D3404040STC17890 00000290 000370BE C9C3 C5C7 C5D5 C5D9 D5D6 D9D7 4040 4040 E2E8 E2E4 E3F24040STC17890 00000290 000370D6 C100 4040 4040 4040 4040 4040 4040 E2E3 C440 4040 4040D9C1STC17890 00000290 000370EC D9C1 E840 D3C1 E2E2 C9E3 C5D9 4040 4040 4040 4040 0001E4D0STC17890 00000290 0003713C 0000 0018 0000 0114 0000 0000 0000 019C 0000 01E0 00000000STC17890 00000290 00037154 0027 0004 003C E2C9 E2F1 D9D3 D6E2 4040 D1D6 C2F1 F7F8F9F1STC17890 00000290 00037250 0028 0001 003C F140 4040 4040 4040 4040 4040 4040 40404040STC17890 00000290 0003713C 0000 0018 0000 0114 0000 0000 0000 019C 0000 01E0 00000000STC17890 00000290 000372D8 0026 0001 003C 4040 4040 4040 4040 4040 4040 4040 40404040STC17890 00000290 0003731C 0010 0001 0008 D7E2 D6D9 E3F2 E4D7 0000 0000 0000 00000000STC17890 00000290 0003713C 0000 0018 0000 0114 0000 0000 0000 019C 0000 01E0 00000000STC17890 00000090 SPR0006E PRT781 : OUTADD for dynamic output descriptor failed,R15 = 0000000C , R0 = 0000030E , R1 = 00000010STC17890 00000090 SPR0010I PRT781 : Terminating SIS1RLOS.NORK .SYSUT2(00000001) due to SPSSSORT processing errorJOB17891 00000090 $HASP704 SIS1RLOS DATA SET UNPRINTABLE - OUTGRP=1.1.1HELD - FSS REASON( ) 00000090 $HASP704 HOLDRC=(002) FSI RELDS UNPRINTABLE-FSA

Figure 23: Console Log Showing WTO Dump

The above Figure is a hex dump of the JSPA and PDSINFO areas in IRXWAREA. Toproduce this hex dump, we set equate &NEWDATA to 1 and re-assembled the sampleSPSSIRX exit.

The following is a breakdown of the fields in IRXWAREA in the previous Figure.


U26433-J-Z247-2-7600 63

Label Width Contents Comments

IRXJOBNM 8 SIS1RLOS Job name.

IRXJOBID 8 JOB17891 Job ID.

IRXDEVNM 8 PRT781 Printer device name.

IRXDEVAD 3 — blanks — Device address in EBCDIC; blank if not a realprinter.

1 x’00’ Reserved.

IRXGRPNM 8 1 Output group name (“1” left-justified in a field ofblanks).

IRXGRP1 2 x’0001’ Output group ID 1 (halfword value).

IRXGRP2 2 x’0001’ Output group ID 2 (halfword value).

IRXGRPD 8 LOCAL Output group destination name.

IRXDSPNM 8 ICEGENER Data set procedure name.

IRXDSSNM 8 NORK Data set step name.

IRXDSDDN 8 SYSUT2 Data set DD name.

IRXSOCL 1 A SYSOUT class.

IRXPRIO 1 x’00’ Data set priority.

IRXFODEF 6 — blanks — FormDef name.

IRXPADEF 6 — blanks — PageDef name.

IRXFCB 4 STD FCB name.

IRXMODIF 4 — blanks — Modify name.

IRXPNAME 20 RAY LASSITER Programmer name.

Figure 24: IRXWAREA Fields Shown in WTO Dump

Two-Up Printing

U26433-J-Z247-2-7600 65

7 Two-up Printing

7.1 Page Sequencing

The following Figure shows how PSORT transforms a 100-page data set:

Figure 25: Example of Enhanced N_Up Output

In the example above, the processor receives input pages from the spool as “1-2-...99-100”. PSORT writes the pages back to spool as “1-100-2-99...”, expecting the output toplace the last page behind the first, and so on. If you use an ordinary duplex FormDef inconjunction with a 2-up PageDef, the printed output appears as “1-4” with “2-3” on thebackside.

992 11

10029910011

100

99

99

2

1002

backfront

backfront

Printed pagewith N_Up=2

Printed pagewith 2-up PageDef

PSORT outputUser’s Data

•••

•••

•••

•••

•••

•••

Two-Up Printing

66 U26433-J-Z247-2-7600

An N_Up FormDef solves this problem by re-sequencing front/back pages. N_Uppositions each sheet into logical pages. The output appears “1-2” and “99-100” by alteringthe natural order of partition usage. This modification produces the output the userexpects to see.

It is important to keep in mind the following:

• The sorter has no idea how the data prints. It only expects 1-up duplex printing.

• The exit must notify the sorter when a page break occurs. The sorter does not examinecarriage control, and does not count input lines.

• The exit needs to accommodate structured fields that change print formats. When youdo simplex/duplex switching, you must also suppress the dummy page whenappropriate. (You don’t want a dummy page in simplex. It serves no purpose.)

• If you want to print 2-up (or better), the copy group in the FormDef must specify N_Upto keep the pages properly sequenced.

7.2 FormDef Source Code

Note: If you want 2-up (or more) printing, SLE or PPFA must be current enough togenerate Enhanced N_Up FormDefs. In addition, the Twin printing system musthave SRA controllers.

COPYGROUP P2UPSORT OFFSET 0.10 IN 0.10 IN DUPLEX TUMBLE N_UP 2 PLACE 2 FRONT PLACE 1 BACK PLACE 1 FRONT PLACE 2 BACK ; SUBGROUP COPIES 1 FRONT ; SUBGROUP COPIES 1 BACK ;

Figure 26: N_Up Copy Group

Two-Up Printing

U26433-J-Z247-2-7600 67

7.3 PageDef Source Code

SETUNITS LINESP 12 LPI ; PAGEFORMAT P2UPSORT WIDTH 8.5 IN HEIGHT 5.5 IN DIRECTION DOWNLINEONE 0.5 IN 0.5 IN ; PRINTLINE FONT GT18 REPEAT 60 CHANNEL 1 POSITION MARGIN TOP ;

Figure 27: N_Up Page Format

The logical page is 1-up, and 5½ inches high. In Enhanced N_Up, the FormDef placeseach input page in a partition on the page. There are two partitions on each side of thesheet. Each partition uses the formatting of the PageDef to place lines of text. Therefore,you only need the print lines for a single partition in the PageDef.

Appendix A Related Documentation

U26433-J-Z247-2-7600 69

Appendix A Related DocumentationThe following manuals come with SPS. You need them for a successful installation.

Number Title

U20944-J-Z247-5-7600 SPS/MVS Installation Guide, Version 3.6.

U21745-J-Z247-5-7600 SPS/MVS APA Messages Guide, Version 3.6.

Figure 28: Required Océ Manuals

For a better explanation of the SPS parameter library and the meaningful parameters forPSORT, see the sample SETUPSSS member on page 19.

For an explanation of the SPS commands (not JES commands), use the SPSAdministrator‘s Guide. This information is not essential to use PSORT, but may be usefulfor some special user requirements. In addition you need this manual for the real (notPSORT) printer system. For AFP information, refer to the SPDS reference.

Number Title

U21020-J-Z247-5-7600 SPS/MVS APA Administrator’s Guide, Version 3.6.

U9737-J-Z247-X-7600 Siemens Nixdorf Printer Data Stream (SPDS) Model 4 ReferenceManual

Figure 29: Optional Océ Manuals

For information on PPFA, refer to the following.

Number Title

S544-3700 Page Printer Formatting Aid/370: User’s Guide and Reference.

Figure 30: Optional IBM AFP Manuals

For an explanation of some of the assembler language considerations for programmingthe exit, refer to the following. This information is not essential to use PSORT, but may beuseful for some special user requirements.

Appendix A Related Documentation

70 U26433-J-Z247-2-7600

Number Title

GC28-1467 MVS Programming: Authorized Assembler Services Guide.

GC28-1474 MVS Programming: Assembler Services Reference.

Figure 31: Optional IBM Programming Manuals

Appendix B Messages and Codes

U26433-J-Z247-2-7600 71

Appendix B Messages and CodesThe SPSSSORT facility contains four components:

1. SPS base product.

2. SPS line driver.

3. SPSSSORT processor.

4. The user exit (SPSSIRX).

You may receive messages and ABEND codes from any of these components. You canidentify the source of the messages and codes as follows:

MessagePrefix

SPSComponent ABENDs Notes

SPS SPS base Any except U513 and U512.Use the manual SPS/MVS APAMessages Guide, Version 3.6,Chapters 2 and 4, for explanationsof these messages and ABENDcodes.

SP1 SPS line driverThe SPS0513E messageaccompanies U512 or U513,which contains an ABENDtermination code (ATC) and anABEND reason code (ARC).The ATC defines the reason forthe ABEND.

Use the manual SPS/MVS LIPand SPS/MVS MOD2 MessagesGuide, Version 2.2, Chapters 3and 5, for explanations of thesemessages and ABEND codes.

SPRSPSSSORTprocessor(“sorter”)

Previously issued messagesexplain all ABENDs with usercode U512 or U513.

Refer to “SPSSSORT ProcessorMessages” on page 72 of thisguide.

SPSSIRXSPSSIRX userexit

None in sample code. Use your exit code to refer tothese messages. Refer to“SPSSIRX User Exit Messages”on page 75 of this guide.

Figure 32: Messages and Codes


72 U26433-J-Z247-2-7600

SPSSSORT Processor Messages

SPR0000E INCORRECT OPERATING SYSTEM LEVEL FOR SPSSSORT

Explanation: PSORT requires a minimum level of MVS/ESA Version V3 to function properly.The message indicates the minimum level environment is not available.

SPS Action: SPS terminates abnormally.

SPR0001E INPUT RECORD EXIT SPSSIRX NOT FOUND

Explanation: SPS tried to load the SPSSIRX user exit but did not find it in the link library.


SPR0002E DATA SPACE CREATION FAILED, FUNCTION=func, R15=rc, R0=rs

Explanation: During the creation of a data space, the processor encountered an unexpectedreturn code from MVS: func is either DSPSERV or ALESERV, rc and rs give thereturn and reason codes.

SPS Action: SPS terminates abnormally. (See the MVS Programming: Assembler ServicesReference for an explanation or rc and rs.)

SPR0003E OPEN FOR OUTPUT DATASET FAILED

Explanation: During the open process for an output data set, the processor encountered anunexpected return code from MVS.


SPR0004E CLOSE/UNALLOCATE FOR OUTPUT DATASET FAILED

Explanation: During the close or de-allocate process for an output data set, the processorencountered an unexpected return code from MVS.



U26433-J-Z247-2-7600 73

SPR0005E DYNALLOC FOR SYSOUT CLASS c FAILED, R15=rc, ERRORCODE=err

Explanation: During the dynamic allocation process for an output (SYSOUT) data set, theprocessor encountered an unexpected return code from MVS: c gives therequested SYSOUT class, rc the return code, and err the error information code.

SPS Action: SPS terminates the current input data set with message SPR0010I and continuesprocessing with the next input data set. (See the MVS Programming: AuthorizedAssembler Services Guide for an explanation of rc and err.)

SPR0006E OUTADD FOR DYNAMIC OUTPUT DESCRIPTOR FAILED, R15=rc,R0=rs, R1=tukey

Explanation: During the creation of an output descriptor for an output (SYSOUT) data set, theprocessor encountered an unexpected return code from MVS: rc and rs give thereturn and reason codes, and tukey gives the key of the failing text unit.

SPS Action: SPS terminates the current input data set with message SPR0010I and continuesprocessing with the next input data set. (See the MVS Programming: AssemblerServices Reference for an explanation of rc and rs.)

SPR0007E OUTDEL FOR DYNAMIC OUTPUT DESCRIPTOR FAILED, R15=rc,R0=rs

Explanation: During the deletion of an output descriptor for an output (SYSOUT) data set, theprocessor encountered an unexpected return code from MVS: rc and rs give thereturn and reason codes.

SPS Action: SPS continues processing with the next input data set. (See the MVSProgramming: Authorized Assembler Services Guide for additional information.)

SPR0008E SJFREQ GETSWB FAILED, R15=rc, REASON CODE=rs

Explanation: During the SJFREQ GETSWB services to obtain the print characteristics for thecurrent input data set in text unit form, the processor encountered an unexpectedreturn code from MVS: rc and rs give the return and reason codes.

SPS Action: SPS terminates the current input data set with message SPR0010I and continuesprocessing with the next input data set. (See the MVS Programming: AuthorizedAssembler Services Guide for additional information.)


74 U26433-J-Z247-2-7600

SPR0009E TERMINATION OF CURRENT INPUT DATASET REQUESTED BYINPUT RECORD EXIT SPSSIRX

Explanation: The input record exit SPSSIRX requested termination of the current input dataset.

SPS Action: SPS terminates the current input data set with message SPR0011I and continuesprocessing with the next input data set.

SPR0010I TERMINATING jobnm.stepnm.ddnm DUE TO SPSSSORTPROCESSING ERROR

Explanation: SPSSSORT terminates the current input data set because of a previousprocessing error: jobnm, stepnm and ddnm give the JOBNAME, STEPNAME andDDNAME. The previous error allows SPSSSORT to continue processing.

SPS Action: SPS terminates the current input data set and continues processing with the nextinput data set.

SPR0011I TERMINATING jobnm.stepnm.ddnm DUE TO SPSSIRX TERMINATIONREQUEST

Explanation: SPSSSORT terminates the current input data set because of a request fromSPSSIRX. jobnm, stepnm and ddnm give the JOBNAME, STEPNAME andDDNAME.

SPS Action: SPS terminates the current input data set and continues processing with the nextinput data set.

SPR0012W Duplicate Text Unit Found. TU KEY =

Explanation: SPSSSORT found duplicate text unit keys for the OUTADD function. This occursbecause the exit is supplying a text unit that was already assigned to the dataset.

SPS Action: The text unit from the exit is discarded.

SPR0013W Invalid ASA carriage control found &01 times.

Explanation: SPSSSORT found invalid ASA carriage control in the print file. The sorterconverts ASA to Machine carriage control

SPS Action: . A write and space command is substituted for any invalid specifications.


U26433-J-Z247-2-7600 75

SPSSIRX User Exit Messages

INPUT RECORD LENGTH EXCEEDS 1024 BYTES

Explanation: The exit needed to copy the current input record to a work buffer, but found therecord was longer than 1,024 bytes.

SPS Action: Processing of the input data set terminates.

UNEXPECTED MACHINE CARRIAGE CONTROL X’xx’

Explanation: The processor encountered an input record with an invalid machine carriagecontrol byte.


UNEXPECTED ASA CARRIAGE CONTROL X’xx’

Explanation: The processor encountered an input record with an invalid ASA carriage controlbyte.


UNEXPECTED STRUCTURED FIELD X’xxxxxx’

Explanation: The processor encountered an input record with an unrecognized StructuredField Identifier value. The exit recognizes only three structured fields:

D3EEEE — No Operation D3ABCC — Invoke Medium Map (Copy Group) D3ABCA — Invoke Data Map (Page Format)


UNEXPECTED INVOKE MEDIUM MAP NAME “........”

Explanation: The processor encountered an Invoke Medium Map (IMM) record with a mediummap (Copy Group) name not recognized by the PSORT exit. This messageprobably indicates a user error. Check to see if the user specified an acceptableMedium Map (“Copy Group”). If yes, then the table of medium map names in theexit requires updating.



76 U26433-J-Z247-2-7600

INTERNAL ERROR: BEHAVIOR TABLE ENTRY .. IS 0

Explanation: The processor consulted the behavior table for the current input data set. Theentry for the current set of conditions (PageDef name, FormDef name, JES Spoolclass, and carriage control type) was 0. This message indicates a programmingproblem. Contact the systems programmer responsible for maintaining thePSORT exit (SPSSIRX). The behavior table has an invalid entry for this particularcombination of conditions.


PSORT REJECTED INPUT DATA SET FOR REASON xx

Explanation: The processor consulted the behavior table for the current input data set. Theentry for the current set of conditions (PageDef name, FormDef name, JES Spoolclass, and carriage control type) indicates the data set is not suitable for PSORTprocessing. This message indicates a user error. The user must change one, ormore, of the following to clearly specify to PSORT how to process the input dataset:

PageDef nameFormDef name JES Spool class Carriage control type


UNEXPECTED INVOKE DATA MAP NAME “........”

Explanation: The processor encountered an Invoke Data Map (IDM) with an unrecognizedData Map (Page Format) name. This message probably indicates a user error.Check to see if the user specified an acceptable Data Map (“Page Format”). Ifyes, the table of medium map names in the exit requires updating.


Appendix C Alphabetic List of Text Units

U26433-J-Z247-2-7600 77


Key Value Description Comments

DOADDRES x’0027’ ADDRESS Used by the exit to pass data set information thatis lost when the data set passes through PSORT.Refer to “Separator Pages” on page 46.

DOBUILD x’0028’ BUILDING Used by the exit to pass data set information thatis lost when the data set passes through PSORT.

DOBURST x’0001’ BURST Burst (YES/NO).

DOCHARS x’0002’ CHARS Character set name.

DOCKPTLI x’0003’ CKPTLINE Checkpoint intervals by line count.

DOCKPTPA x’0004’ CKPTPAGE Checkpoint intervals by page count.

DOCKPTSE x’0005’ CKPTSEC Checkpoint interval by seconds.

DOCLASS x’0006’ CLASS JES spool class. Do not use if the exit specifies aclass in the initialization call.

DOCOMPAC x’0007’ COMPACT

DOCOMSET x’0032’ COMSETUP

DOCONTRO x’0008’ CONTROL

DOCOPIE9 x’0009’ COPIES Number of copies.

DOCOPIEA x’000A’ COPIES Group values.

DODATACK x’2022’ DATACK Data check (BLOCK, UNBLOCK, BLKCHAR,BLKPOS).

DODEFAUL x’000B’ DEFAULT YES/NO (used in OUTPUT JCL statement).

DODEPT x’0029’ DEPT Set up by the exit, but initialized to blanks. Thiskey is a good candidate for modification.

DODEST x’000C’ DEST Destination. Do not use if the exit specifies adestination in the initialization call.

DODPAGEL X’0023’ DPAGELBL

DOFCB x’000D’ FCB FCB name. Do not use. Is STD, the default FCBname.

DOFLASE x’000E’ FLASH Flash overlay name.

DOFLASF x’000F’ FLASH Flash count.


78 U26433-J-Z247-2-7600

Key Value Description Comments

DOFORMD x’001D’ FORMDEF Forms definition name.

DOFORMS x’0010’ FORMS Forms name. The sorter uses DOFORMS to copythe input print data set forms name to the output.

DOGROUPI x’0011’ GROUPID

DOINDEX x’0012’ INDEX

DOLINDEX x’0014’ LINDEX

DOLINECT x’0015’ LINECT

DOMODIF6 x’0016’ MODIFY Module name.

DOMODIF7 x’0017’ MODIFY

DONAME x’002D’ NAME

DONOTIFY x’002F’ NOTIFY

DOOUTBIN x’2023’ OUTBIN Output bin (cut sheet printers).

DOOUTDB x’002B’ OUTDISP Normal.

DOOUTDC x’002C’ OUTDISP Abnormal.

DOOVFL x’0033’ OVERFLOW

DOPAGEDE x’001F’ PAGEDEF Page Definition name.

DOPIMSG x’0021’ PIMSG

DOPRMODE x’0018’ PRMODE Usually LINE or PAGE. Specified in the OUTPUTJCL statement.

DOPRTY x’0019’ PRTY Priority.

DOROOM x’0026’ ROOM Room number. Used by the exit to pass data setinformation that is lost when the data set passesthrough PSORT.

DOSYSARE x’0024’ SYSAREA

DOTHRESH x’0022’ THRESHLD

DOTITLE x’002A’ TITLE Report title. Set up by the exit, but initialized toblanks. This key is a good candidate formodification.

DOTRC x’001A’ TRC Table reference characters (OPTCD=J in DCBparameter).

DOUCS x’001B’ UCS Universal Character Set.

DOUSERDA x’0031’ USERDATA Set up by the exit, but initialized to blanks. Thiskey is a good candidate for modification, but saveit for last. The key provides 20 fields of 60


U26433-J-Z247-2-7600 79

Key Value Description Commentscharacters.

DOUSERLI x’002E’ USERLIB User resource library. Specified in the OUTPUTJCL statement.

DOWRITER x’001C’ WRITER JES writer.

Figure 33: Alphabetic List of Dynamic Output Text Units

Appendix D Numeric List of Text Units

U26433-J-Z247-2-7600 81


Value Key Description Comments

x’0001’ DOBURST BURST Burst (YES/NO).

x’0002’ DOCHARS CHARS Character set name.

x’0003’ DOCKPTLI CKPTLINE Checkpoint intervals by line count.

x’0004’ DOCKPTPA CKPTPAGE Checkpoint intervals by page count.

x’0005’ DOCKPTSE CKPTSEC Checkpoint interval by seconds.

x’0006’ DOCLASS CLASS JES spool class. Do not use if the exit specifies anoutput class.

x’0007’ DOCOMPAC COMPACT

x’0008’ DOCONTRO CONTROL

x’0009’ DOCOPIE9 COPIES Number of copies.

x’000A’ DOCOPIEA COPIES Group values.

x’000B’ DODEFAUL DEFAULT YES/NO (used in OUTPUT JCL statement).

x’000C’ DODEST DEST Destination. Do not use if the exit specifies adestination in the initialization call.

x’000D’ DOFCB FCB FCB name. Do not use. Is STD, the default FCBname.

x’000E’ DOFLASE FLASH Flash overlay name.

x’000F’ DOFLASF FLASH Flash count.

x’0010’ DOFORMS FORMS Forms name. The sorter uses DOFORMS to copythe input print data set forms name to the output.

x’0011’ DOGROUPI GROUPID

x’0012’ DOINDEX INDEX

X’0013’ — —

x’0014’ DOLINDEX LINDEX

x’0015’ DOLINECT LINECT

x’0016’ DOMODIF6 MODIFY Module name.

x’0017’ DOMODIF7 MODIFY TRC.


82 U26433-J-Z247-2-7600


x’0018’ DOPRMODE PRMODE Usually LINE or PAGE. Specified in the OUTPUTJCL statement.

x’0019’ DOPRTY PRTY Priority.

x’001A’ DOTRC TRC Table reference characters (OPTCD=J in DCBparameter).

x’001B’ DOUCS UCS Universal Character Set.

x’001C’ DOWRITER WRITER JES writer.

x’001D’ DOFORMD FORMDEF Forms definition name.

x’001E’ — —

x’001F’ DOPAGEDE PAGEDEF Page Definition name.

x’0020’

x’0021’ DOPIMSG PIMSG

x’0022’ DOTHRESH THRESHLD

X’0023’ DODPAGEL DPAGELBL

x’0024’ DOSYSARE SYSAREA

x’0025’ — —

x’0026’ DOROOM ROOM Used by the exit to pass data set information thatis lost when the data set passes through PSORT.Refer to “Separator Pages” on page 46.

x’0027’ DOADDRES ADDRESS Used by the exit to pass data set information thatis lost when the data set passes through PSORT.

x’0028’ DOBUILD BUILDING Used by the exit to pass data set information thatis lost when the data set passes through PSORT.

x’0029’ DODEPT DEPT Set up by the exit, but initialized to blanks. Thiskey is a good candidate for modification.

x’002A’ DOTITLE TITLE Report title. Set up by the exit, but initialized toblanks. This key is a good candidate formodification.

x’002B’ DOOUTDB OUTDISP Normal.

x’002C’ DOOUTDC OUTDISP Abnormal.

x’002D’ DONAME NAME

x’002E’ DOUSERLI USERLIB User resource library. Specified in the OUTPUTJCL statement.

x’002F’ DONOTIFY NOTIFY


U26433-J-Z247-2-7600 83


x’0030’ — —

x’0031’ DOUSERDA USERDATA Set up by the exit, but initialized to blanks. Thiskey is a good candidate for modification, but saveit for last. The key provides 20 fields of 60characters.

x’0032’ DOCOMSET COMSETUP

x’0033’ DOOVFL OVERFLOW

x’2022’ DODATACK DATACK Data check (BLOCK, UNBLOCK, BLKCHAR,BLKPOS).

x’2023’ DOOUTBIN OUTBIN Output bin (cut sheet printers).

Figure 34: Numeric List of Dynamic Output Text Units

Appendix E Sample SPSMSEPS

U26433-J-Z247-2-7600 85

Appendix E Sample SPSMSEPS Dataset SeparatorPage

TITLE 'SPSMSEPS - SEPARATOR PAGE'

* THIS IS A REPLACEMENT FOR THE D/S SEPARATOR PAGE

SPACE ,

* REFER TO SECTION 10.1 OF THE SPS/MVS-APA

* ADMINISTRATOR'S AND USER'S GUIDE.

SPACE ,

* INFORMATION PAGES ARE LOAD MODULES THAT ARE MODIFIED AT TIME OF

* PRINTING. THEY MUST BE LINK-EDITED NOT REENTRANT, NOT REUSABLE,

* AND NOT REFRESHABLE, WITH ANY VALID RESIDENCY MODE. RMODE=ANY

* IS ADVISED, BUT IS NOT MANDATORY.

SPACE ,

* THE PARAMETERS ARE 'NORENT,NOREUS' (NOT REFRESHABLE IS ASSUMED)

* OR 'NORENT,NOREUS,RMODE=ANY'.

SPACE ,

SPLEVEL SET=4 USE XA TYPE MACROS

SPACE ,

IPAGINFO CC=ASA, X

COPIES=1, X

DATACK=(BLKCHAR,BLKPOS,BLKFCBL), X

DELETE=NO, MAINTAIN LMOD IN STORAGE X

MODESW=NO, X

NAME=SPSMSEPS, X

TRCTYPE=NO, X

TYPE=SEP

SPACE ,

* FORMDEF, PAGEDEF, AND CHARS HAVE NOT BEEN SPECIFIED SO THEY WILL

* BE TAKEN FROM THE SETUP MEMBER DEFAULTS.

SPACE ,

* THE FIRST LINE CONTAINS COLUMNS 1-62 1 11

*IPLINE ' 6 7 8 9 0 11

* 3456789012345678901234567890123456789012345678901'

SPACE ,

* 8-CHARACTER JOBNAME REQUIRES (14 X 8) - 2 = 110 CHARACTERS.

* THE CARRIAGE CONTROL BYTE ADDS 1 TO MAKE A TOTAL OF 111.


86 U26433-J-Z247-2-7600

SPACE ,

* THE "IPLINE" MAKES COLUMNS 10-71, FOR A TOTAL OF 62 CHARACTERS.

* THE CONTINUE LINE PROVIDES 16-64, FOR A TOTAL OF 49 CHARACTERS.

SPACE ,

* FOR EACH IPLINE, THE FIRST COLUMN IS FOR CARRIAGE CONTROL!

SPACE ,

* THE JOB NAME IN BLOCK LETTERS, WHICH REQUIRES 12 PRINT LINES (1-12)

SPACE ,

IPLINE '1@DEL1(1,8) X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

SPACE ,

* TWO BLANK LINES (13 & 14)

SPACE ,

IPLINE ' '

SPACE ,

IPLINE ' '

SPACE ,

* THE JOB NUMBER IN BLOCK LETTERS (LINES 15-26)

SPACE ,

IPLINE ' @DEL1(11,8) X

'

IPLINE ' X


U26433-J-Z247-2-7600 87

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

SPACE ,


SPACE ,

IPLINE ' '

SPACE ,

IPLINE ' '

SPACE ,

* FOUR LINES FOR JES VARIABLES (LINES 29-32)

SPACE ,

IPLINE ' DATE: %DATE CLASS: %CLAS COPY: %COPY X

'

IPLINE ' TIME: %TIME FORM: %FORM X

'

IPLINE ' DEST: %DEST JOB NAME: %JX

OBN '

IPLINE ' START/CONTI/REPOS = %CONT PRTR: %PRTN JOB NBR: %JX

OID '

SPACE ,


IPLINE ' '

SPACE ,

IPLINE ' '

SPACE ,


88 U26433-J-Z247-2-7600

* THE PSORT-PASSED PGMR NAME IN BLOCK LETTERS (LINES 35-46). PSORT

* WILL PASS THE ORIGINAL NAME IN COLS 1-8 OF THE 2ND DELIVERY ADDRESS

SPACE ,

IPLINE ' @DEL2(1,8) X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

IPLINE ' X

'

SPACE ,


SPACE ,

IPLINE ' '

SPACE ,

IPLINE ' '

SPACE ,

* THE PSORT-PASSED ROOM NUMBER IN BLOCK LETTERS (LINES 49-60).

SPACE ,

IPLINE ' BBBBBBBBBBB IIIIIIIIII NN NN @ROM1(1,5) X

'

IPLINE ' BBBBBBBBBBBB IIIIIIIIII NNN NN X

'

IPLINE ' BB BB II NNNN NN X

'

IPLINE ' BB BB II NN NN NN X

'


U26433-J-Z247-2-7600 89


'

IPLINE ' BBBBBBBBBB II NN NN NN X

'

IPLINE ' BBBBBBBBBB II NN NN NN X

'


'

IPLINE ' BB BB II NN NNNN X

'

IPLINE ' BB BB II NN NNN X

'

IPLINE ' BBBBBBBBBBBB IIIIIIIIII NN NN X

'

IPLINE ' BBBBBBBBBBB IIIIIIIIII NN N X

'

SPACE ,

IPEND

Appendix F IRXWAREA Field Descriptions

U26433-J-Z247-2-7600 91


Offset Field Name Length Format Description0 IRXSAVE 18F Binary Save area for SPSSIRX

48 IRXEYE 16 Char Eye catcher: “SPSSIRX WORKAREA”

58 IRXFLAG1 1 Binary Flag byte 1

59 IRXFLAG2 1 Binary Flag byte 2

5A IRXFLAG3 1 Binary Flag byte 3

5B IRXFLAGS 1 Binary Flag byte

5C IRXRECA1 4 Address Address of record to be added whenIRXADD is set in IRXFLAG3

60 INXMAXSH 4 Integer Maximum number of physical pages in a pilewhen IRXMAXSH is set

64 INXDESTL 2 Integer Length of output destination (INXDEST)

66 INXDEST 8 Char Output destination

6E INXCLASS 1 Char Output class for sorted output

6F INXPGIDV 1 Char Default page identifier for dummy pages

70 INXDEFPC 1 Char Default purge class

71 3 Reserved

74 OPXDCBA 4 Address Address of output DCB

78 OPXISEQ 4 Integer Page input sequence number

7C OPXOSEQ 4 Integer Page output sequence number

80 OPXREC# 2 Integer Number of records in current output page

82 OPXPGIDV 1 Integer Page identifier set during input recordprocessing (or zero)

83 1 Reserved

84 IRXRECA 4 Address Address of input record during call toSPSSIRX for input record processing

88 IRXREC# 4 Integer Input record number. This value starts at 1for each new input data.

8C IRXCC 1 Binary Carriage control type indicator


92 U26433-J-Z247-2-7600

8D IRXTRC 1 Binary Table reference character indicator

8E IRXJOBN 8 Char Job Name for current file

96 IRXJOBID 8 Char Job ID

9E IRXDEVNM 8 Char Logical Printer name

A6 IRXDEVAD 3 Reserved

A9 1 Reserved

AA IRXGRPNM 8 Char Output group name (before sort)

B2 IRXGRP1 2 Integer Output group number (before sort)

B4 IRXGRP2 2 Integer Output group copy number (before sort)

B6 IRXGRPD 8 Char Output group destination name

BE IRXDSNM 24 Char Fully qualified output dataset name (beforesort). This field is broken down into thefollowing three fields.

BE IRXDSPNM 8 Char Dataset procedure name

C6 IRXDSSNM 8 Char Dataset step name

CE IRXDSDDN 8 Char Dataset DD name

D6 IRXSOCL 1 Char SYSOUT class

D7 IRXPRIO 1 Char Dataset priority

D8 IRXFODEF 6 Char FORMDEF name

DE IRXPADEF 6 Char PAGEDEF name

E4 IRXFCB 4 Char FCB name

E8 IRXMODIF 4 Char Modify name

EC IRXPNAME 20 Char Programmer’s name

100 IRXPJSPA 4 Address Address of the JSPA (before sort)

104 IRXPPDSI 4 Address Address of the PDSINFO (before sort)

108 IRXRTUL 12 List Exit-supplied list of special reserved textunits if IRXRSVTU is on

114 40 Reserved

13C IRXTULST 0 Start of list of text unit addresses

13C IRXTADDR 4 Offset Offset to text unit for Delivery Address orzero

140 IRXTBUIL 4 Offset Offset to text unit for Building Location orzero

144 IRXTDEPT 4 Offset Offset to text unit for DepartmentIdentification or zero

148 IRXTROOM 4 Offset Offset to text unit for Room Identification orzero


U26433-J-Z247-2-7600 93

14C IRXTTITL 4 Offset Offset to text unit for Separator Page Title orzero

150 IRXTUSER 4 Offset Offset to text unit for User Data or zero

154 IRXADDR Text units for Delivery Address

154 2 Binary Should have the value AL2(DOADDRES)

156 IRXADDR# 2 Integer Number of address lines used. Should be1<=N<=4

158 IRXADDR1 62 Char Address Line 1


1D4 IRXADDR3 62 Char Address Line 3


250 IRXBUILD Text units for Building Location

250 2 Binary Should have the value AL2(DOBUILD)

252 IRXBUIL# 2 Integer Number of lines used for BUILDING. Shouldbe 1.

254 IRXBUIL1 62 Char Building Location

292 2 Reserved

294 IRXDEPT Text units for Department Identification

294 2 Binary Should have the value AL2(DODEPT)

296 IRXDEPT# 2 Integer Number of lines used for DEPT. Should be1.

298 IRXDEPT1 62 Char Department Identification

2D6 2 Reserved

2D8 IRXROOM Text units for Room Identification

2D8 2 Binary Should have the value AL2(DOROOM)

2DA IRXROOM# 2 Integer Number of lines used for ROOM. Should be1

2DC IRXROOM1 62 Char Room Identification

31A 2 Reserved

31C IRXTITLE Text units for Separator Page Title

31C 2 Binary Should have the value AL2(DOTITLE)

31E IRXTITL# 2 Integer Number of lines used for TITLE. Should be 1

320 IRXXTITL1 62 Char Separator Page Title

35E 2 Reserved


94 U26433-J-Z247-2-7600

360 IRXUSERD Text units for USERDATA

360 2 Binary Should have the value AL2(DOUSERDA)

362 IRXUSER# 2 Integer Number of lines used for User Data. Shouldbe 1<=N<=16.

364 IRXUSE01 62 Char First (or only) USERDATA subparameter(parameter)

3A2 IRXUSE02 62 Char Second USERDATA subparameter

3E0 IRXUSE03 62 Char Third USERDATA subparameter

41E IRXUSE04 62 Char Fourth USERDATA subparameter

45C IRXUSE05 62 Char Fifth USERDATA subparameter

49A IRXUSE06 62 Char Sixth USERDATA subparameter

4D8 IRXUSE07 62 Char Seventh USERDATA subparameter

516 IRXUSE08 62 Char Eighth USERDATA subparameter

554 IRXUSE09 62 Char Ninth USERDATA subparameter

592 IRXUSE10 62 Char Tenth USERDATA subparameter

5D0 IRXUSE11 62 Char Eleventh USERDATA subparameter

60E IRXUSE12 62 Char Twelfth USERDATA subparameter

64C IRXUSE13 62 Char Thirteenth USERDATA subparameter

68A IRXUSE14 62 Char Fourteenth USERDATA subparameter

6C8 IRXUSE15 62 Char Fifteenth USERDATA subparameter

706 IRXUSE16 62 Char Sixteenth USERDATA subparameter

744 IRXUINFO variable Remainder of IRXWAREA for use by theSPSSIRX user exit. The maximum size ofIRXWAREA is 4096 bytes (x’1000’)

List of Figures

U26433-J-Z247-2-7600 95

List of FiguresFigure 1: Block Diagram of PSORT Operation............................................................... 9Figure 2: Typical JES2PARM ......................................................................................... 18Figure 3: Member “SETUPSSS” .................................................................................... 19Figure 4: Hierarchy of Parameter Members ................................................................. 20Figure 5: Valid ASA Carriage Control Codes ............................................................... 35Figure 6: Valid Machine Carriage Control Codes ........................................................ 36Figure 7: Recognized Structured Fields ....................................................................... 37Figure 8: IRXFLAGS — Initialization Flags................................................................... 41Figure 9: IRXFLAG1 — Initialization Flags ................................................................... 42Figure 10: IRXFLAG2 — Status of Current Record ..................................................... 43Figure 11: IRXFLAG3 — Status of Current Record ..................................................... 44Figure 12: IRXFLAG4 — Internal Status ....................................................................... 45Figure 13: Banner Page Variables................................................................................. 46Figure 14: Input Banner Variables................................................................................. 48Figure 15: Variables for the IPLINE Macro ................................................................... 49Figure 16: Variables for the IPLINE Macro (cont’d.) .................................................... 51Figure 17: OUTADD Text Units Used by the Generic Exit .......................................... 53Figure 18: Sample Trace of Text Units.......................................................................... 59Figure 19: Text Units Shown in Sample Trace ............................................................. 60Figure 20: Sample Trace Generation Job ..................................................................... 61Figure 20: Sample Trace Generation Job ..................................................................... 61Figure 21: JES Printer Information................................................................................ 61Figure 22: Console Log Showing WTO Dump ............................................................. 62Figure 23: IRXWAREA Fields Shown in WTO Dump ................................................... 63Figure 24: Example of Enhanced N_Up Output ........................................................... 65Figure 25: N_Up Copy Group......................................................................................... 66Figure 26: N_Up Page Format........................................................................................ 67Figure 27: Required Océ Manuals ................................................................................. 69Figure 28: Optional Océ Manuals .................................................................................. 69Figure 29: Optional IBM AFP Manuals .......................................................................... 69Figure 30: Optional IBM Programming Manuals.......................................................... 70Figure 31: Messages and Codes ................................................................................... 71Figure 32: Alphabetic List of Dynamic Output Text Units .......................................... 79Figure 33: Numeric List of Dynamic Output Text Units .............................................. 83