CEE3SRT — call DFSORT

Purpose

This CWI interface establishes an exit DSA and call DFSORT.

Syntax

void CEE3SRT (dfsort_extended_plist, ret_code) 
STRUCT    *dfsort_extended_plist;
INT4      *ret_code;
CEE3SRT
Call this CWI interface as follows: 
L      R12,A(CAA)            Get the address of CAA in R12
L      R15,CEECAACELV-CEECAA(,R12)
L      R15,2916(,R15)
BALR  R14,R15
dfsort_plist
The address of the extended parameter list that is passed to DFSORT. The DFSORT extended parameter list is shown in Figure 1. Language Environment reserves the use of the address of the ESTAE area pointer (+X'14' into the extended parameter list). Language Environment gets the exit address to establish the environment for the member-specified exit, before this exit gets control. It is the caller's responsibility to adhere to the DFSORT interface, as described in the z/OS DFSORT Application Programming Guide.
Figure 1. DFSORT's extended parameter list
SORTEPL  DSECT
CONTROL  DS    A        Addr of control statements or zero
E15_E32  DS    A        Addr of user exit E15 or E32, or zero
E35      DS    A        Addr of user exit E35 or zero
USER     DS    A        User exit addr constant or zero
ALTSEQ   DS    A        Addr of ALTSEQ translation table or zero
ESTAE    DS    A        Addr of ESTAE area pointer or zero
E18      DS    A        Addr of user exit E18 or zero
E39      DS    A        Addr of user exit E39 or zero
END_MARK DS    F        F'-1' to indicate the end
ret_code
The return code from the DFSORT invocation which is contained within R15 upon return from DFSORT. Refer to the DFSORT library for detailed information on the return codes. It is the CEE3SRT caller's responsibility to manage the DFSORT return code. For example, COBOL would save it in the SORT-RETURN special register.

Usage notes

  • Note the following restrictions:
    • DFSORT does not run under CICS®. Language Environment calls DFSORT using EXEC CICS LOAD and BALR 14,15 while executing under CICS.
    • DFSORT is not supported in a POSIX(ON) environment.
    • Language Environment only supports E15, E35, and E32 exits.
  • Identifying restrictions on DFSORT invocation on a per-HLL basis is the responsibility of the particular HLL.
  • Language Environment calls DFSORT using SVC LINK while executing under z/OS.
  • The caller of CEE3SRT must provide and manage the DFSORT exit addresses using the extended parameter list. Typically, the address of an exit identifies an HLL library routine which, in turn, calls a user routine. If no user exit routine is needed, a zero can be specified in the extended parameter list.

    Language Environment gets the exit address in the DFSORT PLIST and replaces it with a Language Environment routine so that Language Environment can, among other things, establish R12 and R13 to point to the CAA and a DSA respectively prior to calling the caller's supplied exit.

  • When a DFSORT user exit is called, the registers are as follows:
    R1
    Address of a parameter list for the particular exit
    R12
    Address of the CAA
    R13
    Address of a standard DSA-formatted save area with a valid NAB established
    R14
    The return address
    R15
    Address of the exit's entry point
  • Invocation of DFSORT from within a DFSORT user exit is restricted in Language Environment.
  • R15 is used to pass return codes back to DFSORT from the user exit.
  • The exit address that is passed to CEE3SRT is called, honoring the AMODE bit, and with R12 and R13 established as described above.
  • Language Environment uses the ESTAE area pointer. For additional information, see Error handling within SORT exits.
  • A new enclave is not created when calling DFSORT in z/OS even though an RB boundary is crossed.
  • CEE3SRT restores the program mask from the value in the CAA upon return from the call. If the program mask is altered (using CEE3SPM or a dynamic call) in the DFSORT user exit, the effect persists upon return from DFSORT.