Input routines are normally used to process data in some way before it is sorted, such as printing it, (see Figure 39 and Figure 41), or generating or manipulating 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, and a return code of 12, which means the record passed is to be included in the sort. SORT continues to call the routine until a return code of 8 is passed. This means that all records have already been passed, and 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 E15 routine must be a fixed or varying character string. 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 is 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. Examples of an input routine are given in Figure 39 and Figure 41.
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 sets a return code from SORT to your PL/I program of 16-sort failed.
It should be noted that a call to PLIRETC sets a return code that is passed by your PL/I program, and is available to any job steps that follow it. When an output handling routine has been used, it is a 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 Figure 40.
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 is normally
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. */
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 */In addition, to code the input user exit routine, the explicit attributes of the E15 must be specified in the program unit that calls PLISRTx if E15 is not nested in that program unit.
plisort: proc options(main);
dcl e15 entry returns(char(2000) varying);
/* Code to do your processing goes here */
call plisrtb(' SORT FIELDS=(5,10,CH,A) '
' RECORD TYPE=V,LENGTH=(2000) ',
0,
retcode,
e15);
/* Code to do your processing goes here */
end plisort;
*PROCESS
E15: proc returns (char(2000) varying);
/* Returns option must be used specifying
length of data to be sorted, maximum length
if varying strings are passed to sort. */
dcl string char(2000) varying;
/* A character string variable is normally
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. */
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 */
/* 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 */