Note: Of the following examples, numbers 1, 2, 8, 9, and
10 are reentrant. The others can be made reentrant using similar
constructs.
Example 1
Define an exit named MYEXIT with the following characteristics: - Exit routines are to get control in AMODE 31
- FASTPATH=YES is allowed on REQUEST=CALL
- All CALL FASTPATH=YES requests will be in PSW key 2 (or key 0,
which is allowed regardless of the value specified via KEY).
⋮ CSVDYNEX REQUEST=DEFINE,EXITNAME=LEX,
AMODE=31,FASTPATH=YES,KEY=2,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,MF=(E,DYNEXL)
*
* Place code to check return/reason codes here
⋮
⋮
* Data Declarations
LEX DC CL16'MYEXIT'
LMOD DC CL8'MYMOD'
CSVEXAA LIST answer area
CSVEXRET Return code information
DYNAREA DSECT
LRETCODE DS F
LRSNCODE DS F
CSVDYNEX MF=(L,DYNEXL)
⋮
Example 2
Associate exit routine named MYMOD with exit MYEXIT. Make the routine
inactive. The load module is in data set 'MY.DSN'. When you want
the exit routine to get control, make the routine active. CSVDYNEX REQUEST=ADD,EXITNAME=LEX,
MODNAME=LMOD,STATE=INACTIVE,DSNAME=LDSN,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,MF=(E,DYNEXL)
*
* Place code to check return/reason codes here
⋮
⋮
* Change MYMOD to be active. Leave its jobname filtering unchanged. *
CSVDYNEX REQUEST=MODIFY,EXITNAME=LEX,
MODNAME=LMOD,STATE=ACTIVE,JOBNAME=LJOB,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,MF=(E,DYNEXL)
*
* Place code to check return/reason codes here
⋮
* Data Declarations
LEX DC CL16'MYEXIT'
LMOD DC CL8'MYMOD'
LJOB DC XL8'0000000000000000' Jobname is to be unchanged
LDSN DC CL44'MY.DSN'
CSVEXAA LIST answer area
CSVEXRET Return code information
DYNAREA DSECT
LRETCODE DS F
LRSNCODE DS F
CSVDYNEX MF=(L,DYNEXL)
Example 3
Issue the CSVDYNEX CALL request with FASTPATH=NO processing. Ask
the system to return information from the exit routine that has the
highest return code. Assume that: - MYEXIT has been defined to be FASTPATH=NO and AMODE=31
- MYMOD has been associated with exit MYEXIT.
⋮
MVC LRUBBITS,=X'40040000' Indicate regs 1,13 for exit rtn
LA 1,LPARMLIST Address of parameter list for routine.
* The parameter list must be set up
* prior to the CSVDYNEX invocation
ST 1,LRUBR1 Save in RUB register 1 slot
LA 1,LSAVEAREA Address of save area
ST 1,LRUBR13 Save in RUB register 13 slot
XC LNEXTTOKEN,LNEXTTOKEN Initialize next token
*
CSVDYNEX REQUEST=CALL,EXITNAME=LEX,
FASTPATH=NO,NEXTTOKEN=LNEXTTOKEN,
RUB=LRUB,RETINFO=HIGHEST,
RETAREA=LRETAREA,RETLEN==AL4(RETALEN),
RETCODE=LRETCODE,RSNCODE=LRSNCODE
*
NC LRSNCODE,=AL4(CSVDYNEXRSNCODEMASK) And off extra bits
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN) Was there an error
BH ERROR1 Yes, process error
BL OK RC=0, have information
CLC LRSNCODE,=AL4(CSVDYNEXRSNNOMODULES) Any routines?
BE DEFAULT No routines, do default processing
OK DS 0H Process return information
LA 2,LRETAREA Get address of return area
USING EXRET,2 Return information header
***********************************************************************
* Place code to process return information here. Because the *
* request was RETINFO=HIGHEST, only one set of information is *
* returned. You can look at EXRETABEND to tell if the routine abended.*
* If it abended, EXRETABENDCODE and EXRETABENDRSNCODE are set. *
* If it did not abend, EXRETCODE, EXRETRSN, and EXRETR1 are set. *
***********************************************************************
DROP 2 Release using
DEFAULT DS 0H Process default
* Place code to process default here
⋮
ERROR1 DS 0H Process error
* Place code to process error here
⋮
RETALEN EQU L'EXRETHDR+L'EXRETINFO Size of return area
* This is an area big enough for one
* entry which is all that is needed since
* RETINFO=HIGHEST is specified.
LRETAREA DS (RETALEN)CL1 Return area
LEX DC CL16'MYEXIT' Name of exit
LNEXTTOKEN DS D Next Token
LRETCODE DS F Return code
LRSNCODE DS F Reason code
LRUB DS 0XL12 RUB area
LRUBBITS DS BL.32 Register bits
LRUBR1 DS A Register 1 for exit routine
LRUBR13 DS A Register 13 for exit routine
LSAVEAREA DS 18F Standard save area
LPARMLIST DS A Parameter list
CSVEXRET Return code information
Example 4
Issue the CSVDYNEX CALL request with FASTPATH=NO processing. Ask
the system to return all information from the exit routines, limited
by the space provided in the area specified on the RETAREA keyword. ⋮
MVC LRUBBITS,=X'40040000' Indicate regs 1,13 for exit rtn
LA 1,LPARMLIST Address of parameter list for routine.
* The parameter list must be set up
* prior to the CSVDYNEX invocation
ST 1,LRUBR1 Save in RUB register 1 slot
LA 1,LSAVEAREA Address of save area
ST 1,LRUBR13 Save in RUB register 13 slot
XC LNEXTTOKEN,LNEXTTOKEN Initialize next token
LAB0 DS 0H
*
CSVDYNEX REQUEST=CALL,EXITNAME=LEX,
FASTPATH=NO,NEXTTOKEN=LNEXTTOKEN,
RUB=LRUB,RETINFO=ALL,
RETAREA=LRETAREA,RETLEN==AL4(RETALEN),
RETCODE=LRETCODE,RSNCODE=LRSNCODE
*
NC LRSNCODE,=AL4(CSVDYNEXRSNCODEMASK) And off extra bits
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN) Was there an error
BH ERROR1 Yes, process error
BL OK RC=0, have information
CLC LRSNCODE,=AL4(CSVDYNEXRSNNOMODULES) Any routines?
BE DEFAULT No routines, do default processing
OK DS 0H Process return information
LA 2,LRETAREA Get address of return area
USING EXRET,2 Return information header
L 3,EXRET#RET Number of entries in area
***********************************************************************
* There will be 1 or 2 entries in the return information area due *
* to the request for RETINFO=ALL (if there were 0, the reason code *
* of CSVDYNEXRSNNOMODULES would have been returned, and that was *
* processed earlier). If you were dynamically allocating the return *
* information area, you could use field EXRET#REM to indicate how *
* many more entries remain so that you could allocate an area large *
* enough so that all the remaining exit routines would be called on *
* the next REQUEST=CALL. *
***********************************************************************
⋮
PROCENT DS 0H Process an entry
***********************************************************************
* Place code to process a return information entry here. *
* You can look at EXRETABEND to tell if the routine abended. *
* If it abended, EXRETABENDCODE and EXRETABENDRSNCODE are set. *
* If it did not abend, EXRETCODE, EXRETRSN, and EXRETR1 are set. *
***********************************************************************
LA 2,L'EXRETINFO(2) Move to next entry. Note that once
this is done, you can no longer reference the
fields in area EXRETHDR.
DROP 2 Release using
BCT 3,PROCENT If more entries, continue
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN)
BNE LAB2 No more exits, done
CLC LRSNCODE,=AL4(CSVDYNEXRSNMOREMODULES)
BE LAB0 More exits, continue
LAB2 DS 0H No more exits
* Place code to process no-more-exits here
⋮
DEFAULT DS 0H Process default
* Place code to process default here
⋮
ERROR1 DS 0H Error
* Place code to process errors here
⋮
* Data Declarations
RETALEN EQU L'EXRETHDR+2*L'EXRETINFO Size of return area
* Room for 2 routines' information
* is provided
LRETAREA DS (RETALEN)CL1 Return area
LEX DC CL16'MYEXIT' Name of exit
LNEXTTOKEN DS F Next Token
LRETCODE DS F Return code
LRSNCODE DS F Reason code
LRUB DS 0XL12 RUB area
LRUBBITS DS BL.32 Register bits
LRUBR1 DS A Register 1 for exit routine
LRUBR13 DS A Register 13 for exit routine
LSAVEAREA DS 18F Standard save area
LPARMLIST DS A Parameter list
CSVEXRET Return code information
⋮
Example 5
Issue the CSVDYNEX CALL request with FASTPATH processing. Ask
the system to return all information from the exit routines, limited
by the space provided in the area specified on the RETAREA keyword.
Provide the CSVDYNEX RECOVER request within the recovery code you
provide for an abnormally ending exit routine. ⋮
* Establish recovery for the exit routine *
ST 12,MYBASEREG Save basereg for ESTAEX routine
XC FOOTPRINT,FOOTPRINT Clear footprints
ESTAEX MYESTAEX,CT,PARAM=MYPARAM
⋮
* *
* Set up for fast-path call. Note that it is necessary to *
* clear the NextToken area (LNEXTTOKEN) prior to the first *
* REQUEST=CALL and it is necessary to clear the first *
* four bytes of the workarea prior to each REQUEST=CALL. *
* *
MVC LRUBBITS,=X'40040000' Indicate regs 1,13 for exit rtn
LA 1,LPARMLIST Address of parameter list for routine.
* The parameter list must be set up
* prior to the CSVDYNEX invocation
ST 1,LRUBR1 Save in RUB register 1 slot
LA 1,LSAVEAREA Address of save area
ST 1,LRUBR13 Save in RUB register 13 slot
XC LNEXTTOKEN,LNEXTTOKEN Clear token
CALLEXIT DS 0H Retry label from recovery
XC LWORKAREA(4),LWORKAREA Clear first 4 bytes
* Issue REQUEST=CALL, specifying FASTPATH processing, and *
* RETINFO=ALL, meaning information about all exit routines called *
* will be returned to the RETAREA. *
LA 2,LRETAREA Return area
USING EXRET,2
XC EXRET#RET,EXRET#RET Clear the field. This ensures that
* if recovery is entered, the return area can be
* examined. See comment in REQUEST=RECOVER processing.
DROP 2
OI FOOTPRINT,INCSVDYNEX Set footprint for recovery
CSVDYNEX REQUEST=CALL,EXITNAME=LEX,
FASTPATH=YES,NEXTTOKEN=LNEXTTOKEN,
WORKAREA=LWORKAREA,RUB=LRUB,RETINFO=ALL,
RETAREA=LRETAREA,RETLEN==AL4(RETALEN),
RETCODE=LRETCODE,RSNCODE=LRSNCODE
NI FOOTPRINT,X'FF'-INCSVDYNEX Reset footprint for recovery
NC LRSNCODE,=AL4(CSVDYNEXRSNCODEMASK) And off extra bits
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN) Was there an error
BH ERROR1 Yes, process error
BL OK RC=0, have information
CLC LRSNCODE,=AL4(CSVDYNEXRSNNOMODULES) Any routines?
BE DEFAULT No routines, do default processing
OK DS 0H Process return information
* Place code to process return information here
⋮
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN) Check return code
BL LAB2 Must be RC=0, no more exits, done
CLC LRSNCODE,=AL4(CSVDYNEXRSNMOREMODULES) Check reason code
BE CALLEXIT More exits, continue
LAB2 DS 0H No more exits
* Place code to process no-more-exits here
⋮
B ENDCALL Join common path
DEFAULT DS 0H Default
* Place code to process default here
⋮
B ENDCALL Join common path
ERROR1 DS 0H Error
* Place code to process error here
⋮
B ENDCALL Join common path
ENDCALL DS 0H Common path
ESTAEX 0 Remove recovery routine
⋮
DS 0D Doubleword align
LWORKAREA DS CL512 Work area
RETALEN EQU L'EXRETHDR+2*L'EXRETINFO Size of return area. Room for
* 2 routines' information is provided.
LRETAREA DS (RETALEN)CL1 Return area
LEX DC CL16'MYEXIT' Name of exit
LNEXTTOKEN DS D Next Token
LRETCODE DS F Return code
LRSNCODE DS F Reason code
LRUB DS 0XL12 RUB area
LRUBBITS DS BL.32 Register bits
LRUBR1 DS A Register 1 for exit routine
LRUBR13 DS A Register 13 for exit routine
LSAVEAREA DS 18F Standard save area
LPARMLIST DS A Parameter list
MYPARAM DS 0F ESTAEX parameter area
MYBASEREG DS F Base register
FOOTPRINT DS X Footprint byte
INCSVDYNEX EQU X'80' Bit 0 of footprint
⋮
* ESTAEX routine *
MYESTAEX DS 0H
* ESTAEX routine entry linkage *
PUSH USING
DROP , Avoid using mainline's regs yet
USING *,15 Temporary addressability
LA 3,12 No-SDWA constant
CR 0,3 Is SDWA provided
BE RLAB1 No, branch
LR 3,1 Save address of SDWA
L 2,0(1) Get address of user parameter
L 2,0(2) Get address of MYPARAM
B RLAB2 Skip No-SDWA path
RLAB1 DS 0H No SDWA
SLR 3,3 Set 0 for SDWA address
* Reg 2 has address of user parameter
RLAB2 DS 0H
* ESTABLISH addressability to mainline information *
L 12,MYBASEREG-MYPARAM(2) Get basereg
POP USING
ST 14,SAVER14 Save return address
TM FOOTPRINT,INCSVDYNEX Were we within CSVDYNEX?
BZ RLAB3 No, skip this
NI FOOTPRINT,X'FF'-INCSVDYNEX Turn off footprint
***********************************************************************
* Issue REQUEST=RECOVER. Note that this simplified example does not *
* examine return information from CSVDYNEX CALL to determine where *
* the error occurred. *
* *
* The NEXTTOKEN returned should be used on the next REQUEST=CALL *
* when the return and reason codes indicated that there were *
* more routines to call. *
* The return information (RETAREA) does not indicate (in field *
* EXRET#REM) how many more routines remain to be called. *
* The RETAREA field passed on REQUEST=CALL might have information in *
* it as well. If you zeroed the EXRET#RET field prior to the call,the *
* return area can be examined (except for EXRET#REM) as can be done *
* for REQUEST=CALL - i.e., using the EXRET#RET value to indicate *
* the number of return information entries that are present *
* (when REQUEST=CALL specified RETINFO=ALL) or the number of *
* exit routines called (when REQUEST=CALL specified HIGHEST, LOWEST *
* *
* Information is returned for each routine called, limited by amount *
* of space provided in the area specified on the RETAREA keyword. *
***********************************************************************
CSVDYNEX REQUEST=RECOVER,EXITNAME=LEX,
NEXTTOKEN=LNEXTTOKEN,WORKAREA=LWORKAREA,
RETAREA=RRETAREA,RETLEN==AL4(RRETALEN),SDWA=0(3),
RETCODE=LRETCODE,RSNCODE=LRSNCODE
NC LRSNCODE,=AL4(CSVDYNEXRSNCODEMASK) Clear unused bits
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN)
BH RERROR1 RC>4 => error, stop calling
BL RLAB3 RC=0 => no more routines, CALL is done
CLC LRSNCODE,=AL4(CSVDYNEXRSNMOREMODULES) Check reason code
BNE RLAB3 No more routines, done with REQUEST=CALL
LA 15,CALLEXIT Retry label
ST 15,RETADDR Save it
B PROCREC Join common recovery
RLAB3 DS 0H No REQUEST=RECOVER needed
LA 15,ENDCALL Retry label
ST 15,RETADDR Save it
PROCREC DS 0H Process REQUEST=RECOVER return info
LA 2,RRETAREA Get address of return area
USING EXRET,2 Return information header
***********************************************************************
* Place code to process return information here. *
* There will be only one set of information returned. *
* You can look at EXRETRECOVERFLAGS to tell what happened. *
* Those flags can indicate whether there was a problem with the *
* exit routine or with the interface information that you provided. *
***********************************************************************
DROP 2 Release using
B COMMON Join common code
RERROR1 DS 0H Error case
* Put code here to process error case *
⋮
LA 15,ENDCALL Retry label
ST 15,RETADDR Save it
COMMON DS 0H No REQUEST=RECOVER needed
* Put code here to process the rest of the recovery *
⋮
EXIT DS 0H Exit from recovery
L 4,RETADDR Get retry address
LTR 3,3 See if SDWA exists
BZ RLAB6 No SDWA, branch
SETRP WKAREA=(3),RC=4,RETADDR=(4),FRESDWA=YES
B RLAB7
RLAB6 DS 0H No SDWA
LR 0,4 Set retry address
LA 15,4 Indicate to retry
RLAB7 DS 0H Exit from recovery
L 14,SAVER14 Restore return address
BR 14 Return
SAVER14 DS A Saved return address
RETADDR DS A Retry address
RRETALEN EQU L'EXRETHDR+L'EXRETINFO Size of return area
RRETAREA DS (RETALEN)CL1 Return area
DS 0D
CSVEXAA LIST answer area
CSVEXRET Return code information
IHASDWA
Example 6
List information about all exits in the system. ⋮
L 2,=AL4(INITEXAA) Initial answer area size
ST 2,SIZEEXAA Save it
GETMAIN RU,LV=(2) Allocate the answer area
ST 1,EXAA@ Save address of answer area
LAB1 DS 0H
L 4,EXAA@ Address of answer area
***********************************************************************
* Issue the CSVDYNEX LIST request *
***********************************************************************
CSVDYNEX REQUEST=LIST,ANSAREA=(4),ANSLEN=SIZEEXAA,
RETCODE=LRETCODE,RSNCODE=LRSNCODE
*
CLC LRETCODE(4),=AL4(CSVDYNEXRC_WARN) Warning?
BNE LAB2 No, request successful or error
* Yes, not enough room
LR 3,2 Save current size
L 2,EXAAHTLEN-EXAAHDR(4) Get required size
FREEMAIN RU,A=(4),LV=(3) Release old area
ST 2,SIZEEXAA Save it
GETMAIN RU,LV=(2) Allocate new area
ST 1,EXAA@ Save address of answer area
B LAB1 Retry List operation
LAB2 DS 0H
CLC LRETCODE(4),=AL4(CSVDYNEXRC_OK) Success?
BNE LAB3 No, error
* Process information in answer area when RC=0 *
USING EXAAHDR,4 EXAAHDR DSECT
L 5,EXAAH#REC Find how many EXAAE entries
LTR 5,5 Are there any entries
BZ LAB4 No, join common path
L 4,EXAAHFIRST@ Get first entry
USING EXAAE,4 EXAAE DSECT
LAB5 DS 0H EXAAE loop
*
* Put code to process information contained in EXAAE here
⋮
LH 7,EXAAE#ENT Get number of EXAAM entries
N 7,CLEAR0TO15 Clear bits 0 to 15
* Are there any routines
BZ LAB7 No, move to end of EXAAE loop
L 6,EXAAEFIRSTENT@ Get first EXAAM
LAB6 DS 0H EXAAM loop
USING EXAAM,6 EXAAM DSECT
* Put code to process information contained in EXAAM here
⋮
L 6,EXAAMNEXT@ Get next EXAAM
DROP 6 EXAAM DSECT
BCT 7,LAB6 Continue while there are more
LAB7 DS 0H Bottom of EXAAE loop
L 4,EXAAENEXT@ Get next EXAAE
BCT 5,LAB5 Continue while there are more
B LAB4 Skip error case
LAB3 DS 0H Error return
* Process error case *
⋮
LAB4 DS 0H Common path
L 2,SIZEEXAA Get size of area
L 4,EXAA@ Get address of area
FREEMAIN RU,A=(4),LV=(2) Release area
⋮
* Data Declarations
EXAA@ DS A Address of answer area
SIZEEXAA DS F Size of answer area
TEMPSIZE DS F Temporary
MODLEN EQU 20*EXAAM_LEN Room for 20 routines' information
EXLEN EQU 10*EXAAE_LEN Room for 10 exits' information
INITEXAA EQU EXAAHDR_LEN+MODLEN+EXLEN Initial size of answer area
LRETCODE DS F Return code
LRSNCODE DS F Reason code
CLEAR0TO15 DC X'0000FFFF' Mask to clear bits 0-15
CSVEXAA LIST answer area
CSVEXRET Return code information
Example 7
Determine if a particular exit has any routines associated with
it at this moment. You might use this request if the setup for the
CSVDYNEX CALL was very extensive. ⋮
CSVDYNEX REQUEST=QUERY,EXITNAME=LEX,QTYPE=CALL,
WORKAREA=LWORKAREA,
RETCODE=LRETCODE,RSNCODE=LRSNCODE
NC LRSNCODE,=AL4(CSVDYNEXRSNCODEMASK) Clear unused bits
CLC LRETCODE,=AL4(CSVDYNEXRC_WARN)
BE LAB1 Warning, didn't find any routines
BH ERROR1 Some sort of error
* Otherwise, RC=0
* Place code to set up and call the exit using REQUEST=CALL here
⋮
B LAB9 Join common path
LAB1 DS 0H No routines found
* Possible reason codes at this point are:
* CSVEXRETRSNNOMODULES,
* CSVEXRETRSNQUERYNOTFOUND, and
* CSVEXRETRSNIMPLICITLYDEFINED.
* Place code to process default here
*
B LAB9 Join common path
ERROR1 DS 0H Error
*
* Handle other conditions
⋮
* Data Declarations
LAB9 DS 0H End of processing
DS 0D Doubleword align
LWORKAREA DS CL512 Work area
LEX DC CL16'MYEXIT' Name of exit
LRETCODE DS F Return code
LRSNCODE DS F Reason code
CSVEXAA LIST answer area
CSVEXRET Return code information
Example 8
Tell the system how to handle information that returns from multiple
routines. In this example, if the return code from an exit routine
is greater than the value 4 (KEEPRCCOMP=GT and KEEPRC parameters),
and the issuer of CSVDYNEX REQUEST=CALL specified RETINFO=LAST, RETINFO=LOWEST,
or RETINFO=HIGHEST, the system keeps the return code and passes it
back to the caller of the exit. ⋮
CSVDYNEX REQUEST=ATTRIB,EXITNAME=LEX,
KEEPRC=KEEPRCCVAL,KEEPRCCOMP=GT,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,MF=(E,MYPLIST)
* CHECK return codes
⋮
* Data Declarations
LEX DC CL16'MYEXIT' Name of exit
KEEPRCCVAL DC F'4' Keep any return code > this
DYNAREA DSECT
LRETCODE DS F Return code
LRSNCODE DS F Reason code
CSVDYNEX MF=(L,MYPLIST) Define storage
CSVEXAA LIST answer area
CSVEXRET Return code information
Example 9
Delete routine MYMOD from exit MYEXIT. ⋮
CSVDYNEX REQUEST=DELETE,EXITNAME=LEX,
MODNAME=LMOD,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,MF=(E,DYNEXL)
*
* Place code to check return/reason codes here
⋮
* Data Declarations
LEX DC CL16'MYEXIT'
LMOD DC CL8'MYMOD'
CSVEXAA LIST answer area
CSVEXRET Return code information
DYNAREA DSECT
LRETCODE DS F
LRSNCODE DS F
CSVDYNEX MF=(L,DYNEXL)
Example 10
Remove the definition of MYEXIT. CSVDYNEX REQUEST=UNDEFINE,EXITNAME=LEX,
RETCODE=LRETCODE,RSNCODE=LRSNCODE,MF=(E,DYNEXL)
* Place code to check return/reason codes here
⋮
* Data Declarations
LEX DC CL16'MYEXIT'
CSVEXAA LIST answer area
CSVEXRET Return code information
DYNAREA DSECT
LRETCODE DS F
LRSNCODE DS F
CSVDYNEX MF=(L,DYNEXL)
|