Buffer return exit routine

An application can manage its own pool of buffers to be retained for multiple uses by coding a buffer return exit routine that assumes control of the buffers after they are freed by a user. By default, buffers are returned to CSM when the current owner issues the IVTCSM REQUEST=FREE_BUFFER macroinstruction. An application that provides the address of its buffer return exit on the FREERTN parameter of the IVTCSM REQUEST=GET_BUFFER macroinstruction receives ownership when the buffers are freed by another user.

The buffer return exit routine is scheduled to execute in the address space which owns the buffer to ensure that the owning environment still exists.

The buffer return exit routine is called by a CSM routine that receives control from the SRB scheduler. The CSM routine passes the address of the parameter list to the buffer return exit routine in register 1. To map the passed parameter list, the buffer return exit routine should include a DSECT that issues the LIST form of the IVTFREE macro. For example:

name    DSECT
        IVTFREE MF=(L,listaddr)

The parameter list contains the address of the buffer list and the number of buffer entries in the list. The following sample output shows the LIST form of the IVTFREE macroinstruction with a listaddr value of FREPL:

         FREPL    DS    0D                 ++ IVTFREE PARM LIST
         FREPL_XVERSION DS XL1             ++ INPUT XVERSION
         FREPL_XRSVFREE1 DS CL03           ++ RESERVED  XRSVFREE1
         FREPL_XBUFLIST DS A               ++   XBUFLIST
         FREPL_XBUFNUM DS F                ++   XBUFNUM
0000C    FREPLL   EQU   *-FREPL            ++ LENGTH OF PLIST

Each buffer list entry is mapped by the IVTBUFL DSECT. The application can examine the tokens in each entry to correlate them with the buffers referenced by the original GET_BUFFER request. When a buffer return exit is driven, the pageability of the buffer might have changed. The original buffer address, token, and length remains the same.

After regaining ownership of the buffers, the application can determine whether to release the buffers back to CSM using the FREE_BUFFER request. To prevent looping, the application must not specify FREETO=USER on the FREE_BUFFER request This would reschedule the application's buffer return exit. To return the buffers back to CSM, the buffer return exit should specify FREETO=CSM on the FREE_BUFFER request.