Using Sort Subroutines (IBM Only)

The Sort program is part of the Endless PL/I for POSIX Systems run-time library. It copies each record to a temporary file, then has the system's sort command order the records by their sort fields, and finally reads the records back in sorted order. Records whose sort fields are equal stay in the order in which they were read. The temporary files are created in /tmp and removed when the sort ends; see Section 8.2.4, “Specifying Storage”.

The Endless PL/I for POSIX Systems Sort interface provides four entry points to the Sort program. Each entry point specifies a different combination of data source and destination, either from and to a file or from and to a subroutine, or a combination of the two. The entry points are described in Section 8.1.2, “Determining Which Entry Point to Use”.

The Sort program handles the complete sort operation. It communicates with the calling program, and any specified user-written input or output routines, by using return codes.

To use the Sort program, insert a CALL statement in your program. The CALL statement specifies one of the four Sort entry points. It must contain the correct arguments for the specified entry point. Once the Sort program is called, it does the following:

Note that user-written input or output routines become, for all purposes, part of the Sort program for the duration of the sort. The Sort program calls the routines at the appropriate point in processing. Return codes control the flow of control between the Sort program and the input or output routines, telling the Sort program whether it should call the routine again or continue to the next stage in processing.

When sorting in PL/I, the data can originate in a file and be output to another file, or it can originate and/or be output to a user-written PL/I subroutine. The simplest use of the Sort program is to sort a file and direct the results into another file. The input file must be in the current directory, and the output file is created in the current directory. By default, the input file is sortin and the output file is sortout; see Section 8.2.7, “Specifying a File Prefix”.

Using subroutines lets you manipulate the data before and/or after the sort. For example, you could read a file and sort only certain records, or you could print the resulting sorted data. The format of input and output routines is described more fully in Section 8.3, “Input and Output Routines”.

The Sort program interface provides four entry points. The following table lists the entry points to the Sort program and specifies the source and destination of data in each case:

The format of the call to any of the four sort entry points is:

CALL PLISRTx (sort-specification, record-specification, maximum-storage, return-code [,input-routine] [,output-routine] [,file-prefix,message-level] );

The sort-specification is the first argument to PLISRTx. It has the following syntax:

'bSORTbFIELDS=(start1,length1,format1,order1,...startn,lengthn,formatn,ordern)[OPTION1[...,OPTIONn]]b'

The record-specification is the second argument to PLISRTx. It has the following syntax:

'bRECORDbTYPE=RECTYPE[,LENGTH=(rec-length[,,min-length,modal-length)]b'

You can specify storage either by declaring a fixed binary (31) variable and passing the variable to the Sort routine, or by passing a constant value. For example, either one of the following calls will invoke the Sort program PLISRTA to sort a 40-byte character record using 512,000 bytes of storage:

DECLARE RETURN_CODE FIXED BIN(31);
CALL PLISRTA(' SORT FIELDS=(1,40,CH,D) ', ' RECORD TYPE=F,LENGTH=(40) ', 512000, RETURN_CODE);

or:

DECLARE RETURN_CODE FIXED BIN(31);
DECLARE MAXSTORAGE FIXED BIN(31) INITIAL(512000);
CALL PLISRTA(' SORT FIELDS=(1,40,CH,D) ', ' RECORD TYPE=F,LENGTH=(40) ',MAXSTORAGE,RETURN_CODE);

You must specify a value for storage, but it has no effect: the sort command manages its own memory, and uses temporary files when the data does not fit.

The Sort program needs space in /tmp for a copy of every record being sorted, plus a line of about twice the length of the sort fields for each record. The sort command may need further temporary space of its own (in /tmp, unless the environment variable TMPDIR names another directory).

The sort command is run through the shell with the environment variable LC_ALL set to C, so that the records are compared byte by byte and not according to the locale. It must be in the search path (PATH).

Only one sort can run at a time in a program. Do not call PLISRTA, PLISRTB, PLISRTC or PLISRTD from an input or output routine.

The required return code argument is a variable to contain the fixed binary(31) value returned by the sort program. The sort program returns one of the following:

In your calling program, declare a fixed binary(31) variable to contain return code.

To determine success or failure of the sort, check the return code after the call to the Sort program. If the sort-specification or record-specification is not valid, the Sort program also writes a message ending in “in SORT statement **** Execution aborted” to standard output and raises the ERROR condition; if an ON-unit for ERROR returns, the return code is 16.

For example, assume that the variable RETURN_CODE was declared for use with the Sort program. The following code calls PLISRTD to sort 80-byte records on a single 10-character field at the start of the record. The input and output routines are SORT_IN and SORT_OUT. After returning from the call, the code checks the success of the sort:

CALL PLISRTD (' SORT FIELDS=(1,10,CH,A) ',
          ' RECORD TYPE=F,LENGTH=(80) ',
               256000,RETURN_CODE,SORT_IN,SORT_OUT);
IF RETURN_CODE ^= 0 THEN
DO;
       PUT SKIP LIST ('Error! Return code = '||RETURN_CODE);
       SIGNAL ERROR;
END;

The input-routine argument is used with PLISRTB and PLISRTD. The output-routine argument is used with PLISRTC and PLISRTD. These arguments are required for the specified routines. They give the name of the user-written PL/I routine that supplies records to or accepts records from the Sort program. See Section 8.3, “Input and Output Routines” for more information on writing routines for use with the Sort program. See the preceding section for an example of calling PLISRTD, specifying the user-written input routine SORT_IN and the user-written output routine SORT_OUT.

The optional file prefix argument lets you replace the default prefix sort in the names of the input and output files the Sort program uses. Using a file prefix lets you sort several files in turn without renaming them. For example, you can specify 'TEMP' for the file prefix, as shown in the following example:

CALL  PLISRTA(' SORT FIELDS=(1,40,CH,D) ', ' RECORD TYPE=F,LENGTH=(40) ',STOR,RETURN_CODE,'TEMP');

In this case, PLISRTA reads TEMPin and writes TEMPout. The prefix is used exactly as given, followed by in or out in lower case; by default the files are sortin and sortout. The temporary files in /tmp are named after the prefix too.

The file prefix is at most four characters; a blank ends it early. A blank or null string selects the default prefix, sort.

If you omit this argument but require the message-level argument, specify a null string ('') in place of the file prefix argument.

The message-level argument is accepted for compatibility with other implementations of PL/I, where it controls the Sort program's diagnostic messages. Here the Sort program writes no such messages, so it has no effect. It must still be one of the following, or the sort fails; AP is assumed if it is omitted:

If you omit the file-prefix argument but require the message-level argument, specify a null string ('') in place of the file prefix argument. For example, the following call invokes PLISRTB to sort on the first 12 characters of a 30 character record in ascending order. Input is passed to the Sort program by a user-written routine called READ_DATA, the file prefix is defaulted to sort, and no messages are passed back:

CALL PLISRTB(' SORT FIELDS=(1,12,CH,A) ', ' RECORD TYPE=F,LENGTH=(30) ',MAXSTORAGE,RETURN_CODE, READ_DATA,' ','NO');

The PLIRETC built-in subroutine sets the PL/I return code. Use PLIRETC in your input and output routines to return a value to the Sort program. The PLIRETV built-in function returns the current value of the PL/I return code, so a program can also use the two for its own purposes, to pass a value from one procedure to another. Both are available in the ibm dialect only.

The format of the subroutine call is:

CALL PLIRETC(return-code)

The PL/I return code is zero when the program starts, and keeps the value of the most recent call to PLIRETC, in any procedure. The Sort program sets it as well: to 4 before it passes the first record to an output routine, so an output routine that does not call PLIRETC goes on receiving records. The PL/I return code is not passed to the operating system when the program ends; it is not the program's exit status.

For example, the following procedure records whether it found any errors, and its caller tests the result:

CHECK_INPUT: PROCEDURE;
    ...
    IF ERRORS_FOUND THEN CALL PLIRETC(8);
                    ELSE CALL PLIRETC(0);
END CHECK_INPUT;

    CALL CHECK_INPUT;
    IF PLIRETV ^= 0 THEN PUT SKIP LIST ('Errors in input.');

Use an input routine to manipulate the data in some way before sorting it. For example, you might want to print the data or generate or modify the sorting fields.

The input routine and the Sort program communicate using calls to PLIRETC. The Sort program recognizes two PLIRETC return codes from an input routine:

Any other return code is treated as 12: the record is included.

Calls made to PLISRTB or PLISRTD require an input routine. When using an input handling routine, the sort processing is as follows:

The input routine passes records back to the Sort program in the RETURN statement. Therefore you must specify the RETURNS attribute in the input routine PROCEDURE statement.

Returned records must be in character-string format. They can be fixed or varying. A varying string is padded with blanks to the record length given in the LENGTH argument, so sort-field positions count from the first character of the string. A varying string longer than the record length makes the sort fail.

SORT_INPUT_ROUTINE: PROCEDURE RETURNS(CHAR(80));
       /* you must specify the returns attribute. For varying
          strings, the length must be the maximum length.

       DECLARE CUST_RECORD CHARACTER(80);
       DECLARE CUSTOMER_FILE FILE RECORD INPUT;

       ON ENDFILE(CUSTOMER_FILE) BEGIN;
               PUT SKIP(2) LIST('End of customer file input.');
               CALL PLIRETC(8); /* signal end of input to Sort */
               GOTO END_ROUTINE;
       END;

/* Do any processing you require to get a record. */
/* For example, you could get the record from a file */
/* and then display the record. */
       READ FILE (CUSTOMER_FILE) INTO (CUST_RECORD);
       PUT SKIP LIST(CUST_RECORD);
/* signal Sort to include this record */
       CALL PLIRETC(12);

       RETURN(CUST_RECORD); /* return the record to Sort */

END_ROUTINE:
END SORT_INPUT_ROUTINE;

Use an output routine to do any post-sorting processing. For example, you might want to print the data or use the sorted data in a calculation.

The output routine and the Sort program communicate using calls to PLIRETC. The Sort program recognizes one PLIRETC return code from an output routine:

Any other return code stops the Sort program passing records to the output routine; the remaining records are not passed.

Calls made to PLISRTC or PLISRTD require an output routine. When using an output handling routine, the sort processing is as follows:

Note that the Sort program does not pass an end-of-data code to your output routine. Do any end-of-data processing after the Sort program returns to the calling program. A record of a CHARACTER VARYING output routine parameter is always passed at the full record length.

SORT_OUTPUT_ROUTINE: PROCEDURE(CUST_RECORD);

       DECLARE CUST_RECORD CHARACTER(80);
       DECLARE NEWCUST_FILE FILE RECORD OUTPUT;

/* Do any processing you require. */
/* For example, you could display the record. */
       PUT SKIP LIST(CUST_RECORD);
       CALL PLIRETC(4); /* request the next record */

       RETURN;
END SORT_OUTPUT_ROUTINE;

SORT_EXAMPLE1: PROCEDURE OPTIONS(MAIN);

/* declare a variable to hold the code returned by the Sort
/* program
*/
DECLARE RETURN_CODE FIXED BIN(31);

/* call the PLISRTA entry point of the sort routine. */

CALL PLISRTA (' SORT FIELDS=(5,20,CH,A,25,20,CH,A,45,1,CH,A) ',
                         ' RECORD TYPE=F,LENGTH=(120) ',
                         4000000,
                         RETURN_CODE,
                         'CUST');

SELECT (RETURN_CODE);
       WHEN(0) PUT SKIP LIST ('Sort completed successfully.');
       WHEN(16) PUT SKIP LIST ('Sort failed.');
       OTHERWISE
               PUT SKIP LIST('Invalid Sort return code'||RETURN_CODE);
END; /*select*/

END SORT_EXAMPLE1;

The example above sorts a customer file by name. The arguments of the call to PLISRTA are:

SORT_EXAMPLE2: PROCEDURE OPTIONS(MAIN);

/* declare a variable to hold the code returned by the Sort
/* program
*/
DECLARE RETURN_CODE FIXED BIN(31);


/* call the PLISRTD entry point of the sort routine. */

CALL PLISRTD (' SORT FIELDS=(5,20,CH,A,25,20,CH,A,45,1,CH,A) ',
                         ' RECORD TYPE=F,LENGTH=(120) ',
                         4000000,
                         RETURN_CODE,
                         SORT_INPUT,
                         SORT_OUTPUT,
                         'CUST');



SELECT (RETURN_CODE);
       WHEN(0) PUT SKIP LIST ('Sort completed successfully.');
       WHEN(16) PUT SKIP LIST ('Sort failed.');
       OTHERWISE
               PUT SKIP LIST('Invalid Sort return code'||RETURN_CODE);
END; /*select*/

SORT_INPUT: PROCEDURE RETURNS(CHAR(120) VARYING);
/* you must specify the returns attribute. For varying
   strings, the length must be the maximum length. */

       DECLARE CUST_RECORD CHARACTER(120) VARYING;
       DECLARE CUSTOMER_FILE FILE RECORD INPUT;

       ON ENDFILE(CUSTOMER_FILE) BEGIN;
               PUT SKIP(2) LIST('End of customer file input.');
               CALL PLIRETC(8); /* signal end of input to Sort */
               GOTO END_ROUTINE;
       END;

/* Do any processing you require to get a record. */
/* For example, you could get the record from a file */
/* and then display the record. */
       READ FILE (CUSTOMER_FILE) INTO (CUST_RECORD);
       PUT SKIP LIST(CUST_RECORD);
/* signal Sort to include this record */
       CALL PLIRETC(12);

       RETURN(CUST_RECORD); /* return the record to Sort */

END_ROUTINE:
END SORT_INPUT;

SORT_OUTPUT: PROCEDURE(CUST_RECORD);

       DECLARE CUST_RECORD CHARACTER(*);
       DECLARE NEWCUST_FILE FILE RECORD OUTPUT;

/* Do any processing you require. */
/* For example, you could display the record. */
       PUT SKIP LIST(CUST_RECORD);
       CALL PLIRETC(4); /* request the next record */

       RETURN;
END SORT_OUTPUT;

END SORT_EXAMPLE2;

The example sorts the same customer records by customer name, but the records pass through an input and an output routine. The elements of the call to PLISRTD are similar to the ones in the call to PLISRTA. The differences are: