Rational Developer for System z
Enterprise PL/I for z/OS, Version 3.8, Programming Guide

E15—Input handling routine (Sort Exit E15)

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.

Figure 47. Flowcharts for input and output handling subroutines
Flowcharts for input and output handling subroutines

Skeletal code for a typical input routine is shown in Figure 48.

Figure 48. Skeletal code for an input procedure
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.

Note:
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 an output handling routine has been used, 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 Figure 52.

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)