Output handling routines are normally used for any processing that is necessary after the sort. This could be to print the sorted data, as shown in Figure 52 and Figure 53, or to use the sorted data to generate further information. The output handling routine is used by Sort when a call is made to PLISRTC or PLISRTD. When the records have been sorted, Sort passes them, one at a time, to the output handling routine. The output routine then processes them as required. When all the records have been passed, Sort sets up its return code and returns to the statement after the CALL PLISRTx statement. There is no indication from Sort to the output handling routine that the last record has been reached. Any end-of-data handling must therefore be done in the procedure that calls PLISRTx.
The record is passed from Sort to the output routine as a character string, and you must declare a character string parameter in the output handling subroutine to receive the data. The output handling subroutine must also pass a return code of 4 to Sort to indicate that it is ready for another record. You set the return code by a call to PLIRETC.
The sort can be stopped by passing a return code of 16 to Sort. This will result in Sort returning to the calling program with a return code of 16–Sort failed.
The record passed to the routine by Sort is a character string parameter. If you specified the record type as F in the second argument in the call to PLISRTx, you should declare the parameter with the length of the record. If you specified the record type as V, you should declare the parameter as adjustable, as in the following example:
DCL STRING CHAR(*);
Figure 54 shows a program that sorts varying length records.
A flowchart for a typical output handling routine is given in Figure 47. Skeletal code for a typical output handling routine is shown in Figure 49.
E35: PROC(STRING); /*The procedure must have a character string
parameter to receive the record from Sort*/
DCL STRING CHAR(80); /*Declaration of parameter*/
(Your code goes here)
CALL PLIRETC(4); /*Pass return code to Sort indicating that the next
sorted record is to be passed to this procedure.*/
END E35; /*End of procedure returns control to Sort*/You should note that a call to PLIRETC sets a return code that will be passed by your PL/I program, and will be available to any job steps that follow it. When you have used an output handling routine, it is good practice to reset the return code with a call to PLIRETC after the call to PLISRTx to avoid receiving a nonzero completion code. By calling PLIRETC with the return code from Sort as the argument, you can make the PL/I return code reflect the success or failure of the sort. This practice is shown in the examples at the end of this chapter.