Input routines are normally used to process the data in some way before it is sorted. You can use input routines to print the data, as shown in the Figure 51 and Figure 53, or to generate or manipulate the sorting fields to achieve the correct results.
The input handling routine is used by Sort when a call is made to either PLISRTB or PLISRTD. When Sort requires a record, it calls the input routine which should return a record in character string format, with a return code of 12. This return code means that the record passed is to be included in the sort. Sort continues to call the routine until a return code of 8 is passed. A return code of 8 means that all records have already been passed, and that Sort is not to call the routine again. If a record is returned when the return code is 8, it is ignored by Sort.
The data returned by the routine must be a character string. It can be fixed or varying. If it is varying, you should normally specify V as the record format in the RECORD statement which is the second argument in the call to PLISRTx. However, you can specify F, in which case the string will be padded to its maximum length with blanks. The record is returned with a RETURN statement, and you must specify the RETURNS attribute in the PROCEDURE statement. The return code is set in a call to PLIRETC. A flowchart for a typical input routine is shown in Figure 47.
Skeletal code for a typical input routine is shown in Figure 48.
E15: PROC RETURNS (CHAR(80));
/*---------------------------------------------------------------*/
/*RETURNS attribute must be used specifying length of data to be */
/* sorted, maximum length if varying strings are passed to Sort. */
/*---------------------------------------------------------------*/
DCL STRING CHAR(80); /*--------------------------------------------*/
/*A character string variable will normally be*/
/* required to return the data to Sort */
/*--------------------------------------------*/
IF LAST_RECORD_SENT THEN
DO;
/*---------------------------------------------------------------*/
/*A test must be made to see if all the records have been sent, */
/*if they have, a return code of 8 is set up and control returned*/
/*to Sort */
/*---------------------------------------------------------------*/
CALL PLIRETC(8); /*-------------------------------------------*/
/* Set return code of 8, meaning last record */
/* already sent. */
/*-------------------------------------------*/
RETURN('');
END;
ELSE
DO;
/*------------------------------------------------*/
/* If another record is to be sent to Sort, do the*/
/* necessary processing, set a return code of 12 */
/* by calling PLIRETC, and return the data as a */
/* character string to Sort */
/*------------------------------------------------*/
****(The code to do your processing goes here)
CALL PLIRETC (12); /*--------------------------------------*/
/* Set return code of 12, meaning this */
/* record is to be included in the sort */
/*--------------------------------------*/
RETURN (STRING); /*Return data with RETURN statement*/
END;
END; /*End of the input procedure*/Examples of an input routine are given in Figure 51 and Figure 53.
In addition to the return codes of 12 (include current record in sort) and 8 (all records sent), Sort allows the use of a return code of 16. This ends the sort and causes Sort to return to your PL/I program with a return code of 16–Sort failed.