Figure 1 shows a “before” and “after” situation that involves two functions, USER1 and USER2. In the BEFORE part of the example, USER1 contains both functions and resides below 16 megabytes. In the AFTER part of the example USER1 has moved above 16 megabytes. The portion of USER1 that requests data management services has been removed and remains below 16 megabytes.
Following the figure is a detailed coding example that shows both
USER1 and USER2.
Figure 1. Performing
I/O While Residing Above 16 Megabytes
USER1 application module:
*Module USER1 receives control in 31-bit addressing mode, resides in
*storage above 16 megabytes, and calls module USER2 to perform data
*management services.
*In this example, note that no linkage assist routine is needed.
USER1 CSECT
USER1 AMODE 31
USER1 RMODE ANY
*
* Save the caller's registers in save area provided
*
#100 SAVE (14,12) Save registers
BASR 12,0 Establish base
USING *,12 Addressability
Storage will be obtained via GETMAIN for USER2's work area (which
will also contain the save area that module USER2 will store into
as well as parameter areas in which information will be passed.)
Since module USER2 must access data in the work area, the work area
must be obtained below 16 megabytes.
LA 0,WORKLNTH Length of the work area
* required for USER2
#200 GETMAIN RU,LV=(0),LOC=BELOW Obtain work area storage
LR 6,1 Save address of obtained
* storage to be used for
* a work area for module
* USER2
USING WORKAREA,6 Work area addressability
The SAVE operation at statement #100 may save registers into a save area that exists in storage either below or above 16 megabytes. If the save area supplied by the caller of module USER1 is in storage below 16 megabytes, it is assumed that the high-order byte of register 13 is zero.
The GETMAIN at statement #200 must request storage below
16 megabytes for the following reasons:
- The area obtained via GETMAIN will contain the register save area in which module USER2 will save registers. Because module USER2 runs in 24-bit addressing mode, it must be able to access the save area.
- Because module USER2 will extract data from the work area to determine what function to perform, the area must be below 16 megabytes, otherwise, USER2 would be unable to access the parameter area.
LA 0,GMLNTH Get dynamic storage for
* module USER1 (USER1 resides
* above 16 megabytes)
#300 GETMAIN RU,LV=(0),LOC=RES Get storage above 16
* megabytes
LR 8,1 Copy address of storage
* obtained via GETMAIN
USING DYNAREA,8 Base register for dynamic
* work area
#400 ST 13,SAVEBKWD Save address of caller's
* save area
LR 9,13 Save caller's save area
* address
LA 13,SAVEAREA USER1's save area address
* Note - save area is below
* 16 megabytes ST 13,8(9) Have caller's save area
* point to my save area
LOAD EP=IOSERV Load address of data
* management service
* Entry point address
* returned will be pointer-defined
ST 0,EPA Save address of loaded
* routine.The GETMAIN at statement #300 requests that the storage to be obtained match the current residency mode of module USER1. Because the module resides above 16 megabytes, the storage obtained will be above 16 megabytes.
At statement #400, the address of the caller's save area is saved in storage below 16 megabytes.
Prepare to open input and output data base files:
MVC FUNCTION,OPEN1 Indicate open file 1
* for input
LA 1,COMMAREA Set up register 1 to
* point to the parameter
* area
#500 L 15,EPA Get pointer-defined address
* of the I/O service
* routine
#600 BASSM 14,15 Call the service routine
* Note: AMODE will change
#650 MVC FUNCTION,OPEN2 Indicate open file 2
* for output
LA 1,COMMAREA Setup register 1 to
* point to the parameter
* area
#700 L 15,EPA Get pointer-defined address
* of the I/O service
* routine
BASSM 14,15 Call the service routine
* Note: AMODE will changeThe entry point address loaded at statements #500 and #700 is pointer-defined, as returned by the LOAD service routine. That is, the low-order three bytes of the symbolic field EPA will contain the virtual address of the loaded routine while the high order bit (bit 0) will be zero to indicate the loaded module is to receive control in 24-bit addressing mode. The remaining bits (1-7) will also be zero in the symbolic field EPA.
The BASSM at statement #600 does the following:
- Places into bit positions 1-31 of register 14 the address of statement #650.
- Sets the high-order bit of register 14 to one to indicate the current addressing mode.
- Replaces bit positions 32-63 of the current PSW with the contents of register 15 (explained above)
The BSM instruction used by the called service routine USER2 to return to USER1 will reestablish 31-bit addressing mode.
Prepare to read a record from data base file 1:
READRTN DS 0H
MVC FUNCTION,READ1 Indicate read to file 1
XC BUFFER,BUFFER Clear input buffer
LA 1,COMMAREA Set up register 1 to
* point to the parameter area
L 15,EPA Get pointer-defined address
* of the I/O service routine
BASSM 14,15 Call the service routine
* Note: The BASSM will change
* the AMODE to 24-bit. The
* BSM issued in the service
* routine will reestablish
* 31-bit addressing mode.
#900 CLC STATUS,ENDFILE End of file encountered
* by module USER2 ?
BE EODRTN Close files and exit
MVC BUFFR31A,BUFFER Move record returned to
* storage above 16 megabytesAt statement #900, a check is made to determine if called module USER2 encountered the end of file. The end of file condition in this example can only be intercepted by USER2 because the EOD exit address specified on the DCB macro must reside below 16 megabytes. The end of file condition must then be communicated to module USER1.
Call a record analysis routine that exists above 16 megabytes:
LA 1,BUFFR31A Get address of first buffer
ST 1,BUFPTR+0 Store into parameter list
LA 1,UPDATBFR Get address of output
* buffer
ST 1,BUFPTR+4 Store into parameter list
LA 1,BUFPTR Set up pointers to work
* buffers for the analysis
* routine
L 15,ANALYZE Address of analysis routine
#1000 BASR 14,15 Call analysis routine
MVC BUFFER,UPDATBFR Move updated record to
* storage below 16 megabytes
* so that the updated record can
* be written back to the data baseAt statement #1000 a BASR instruction is used to
call the analysis routine since no AMODE switching is required. A
BALR could also have been used. A BALR executed while in 31-bit
addressing mode performs the same function as a BASR instruction.
The topic “Mode Sensitive Instructions” describes the instruction
differences.
MVC FUNCTION,WRITE1 Indicate write to file 1
LA 1,COMMAREA Set up register 1 to
* point to the parameter area
L 15,EPA Get pointer-defined address
* of the I/O service routine
* routine
BASSM 14,15 Call the service routine
* Note: The BASSM will set
* the AMODE to 24-bit. The
* BSM issued in the service
* routine will reestablish
* 31-bit addressing mode
B READRTN Get next record to processPrepare to close input and output data base files:
EODRTN DS 0H End of data routine
MVC FUNCTION,CLOSE1 Indicate close file 1
LA 1,COMMAREA Set up register 1 to
* point to the parameter area
L 15,EPA Get pointer-defined address
* of the I/O service routine
BASSM 14,15 Call the service routine
* Note: The BASSM sets
* the AMODE to 24-bit. The
* BSM issued in the service
* routine will reestablish
* 31-bit addressing mode
MVC FUNCTION,CLOSE2 Indicate close file 2
LA 1,COMMAREA Set up register 1 to
* point to the parameter area
L 15,EPA Get pointer-defined address
* of the I/O service routine
BASSM 14,15 Call the service routine
* Note: The BASSM sets
* the AMODE to 24-bit. The
* BSM issued in the service
* routine will reestablish
* 31-bit addressing modePrepare to return to the caller:
L 13,SAVEBKWD Restore save area address
* of the caller of module
* USER1
LA 0,WORKLNTH Length of work area and
* parameter area used by
* module USER2
FREEMAIN RC,LV=(0),A=(6) Free storage
DROP 6
LA 0,GMLNTH Length of work area used
* by USER1
FREEMAIN RC,LV=(0),A=(8) Free storage
DROP 8
XR 15,15 Set return code zero
RETURN (14,12),RC=(15)Define DSECTs and constants for module to module communication.
Define constants used to communicate the function module USER2 is
to perform.
DS 0F
READ1 DC C'R1' Read from file 1 opcode
WRITE1 DC C'W1' Write to file 1 opcode
OPEN1 DC C'O1' Open file 1 opcode
OPEN2 DC C'O2' Open file 2 opcode
CLOSE1 DC C'C1' Close file 1 opcode
CLOSE2 DC C'C2' Close file 2 opcode
ANALYZE DC V(ANALYSIS) Address of record
* analysis routine
ENDFILE DC C'EF' End of file indicator
WORKAREA DSECT
SAVEREGS DS 0F This storage exists
* below 16 megabytes
SAVEAREA EQU SAVEREGS
SAVERSVD DS F Reserved
SAVEBKWD DS F
SAVEFRWD DS F
SAVE1412 DS 15F Save area for registers 14-12
COMMAREA DS 0F Parameter area used to
* communicate with module
* USER2
FUNCTION DS CL2 Function to be performed
* by USER2
STATUS DS CL2 Status of read operation
BUFFER DS CL80 Input/output buffer
WORKLNTH EQU *-WORKAREA Length of this DSECTDefine DSECT work area for module USER1:
DYNAREA DSECT This storage exists
* above 16 megabytes
EPA DS F Address of loaded routine
BUFFR31A DS CL80 Buffer - above 16
* megabytes
BUFPTR DS 0F
DS A Address of input buffer
DS A Address of updated buffer
UPDATBFR DS CL80 Updated buffer returned
* by the analysis routine
GMLNTH EQU *-DYNAREA Length of dynamic area
ENDUSER2 service routine:
*Module USER2 receives control in 24-bit addressing mode, resides below
*16 megabytes, and is called by module USER1 to perform data
*management services.
USER2 CSECT
USER2 AMODE 24
USER2 RMODE 24
*
* Save the caller's registers in save area provided
*
SAVE (14,12) Save registers
BASR 12,0 Establish base
USING *,12 Addressability
LR 10,1 Save parameter area pointer
* around GETMAINs
USING COMMAREA,10 Establish parameter area
* addressability
Storage will be obtained via GETMAIN for a save area that module
USER2 can pass to external routines it calls.
LA 0,WORKLNTH Length of the work area
* required
GETMAIN RU,LV=(0),LOC=RES Obtain save area storage,
* which must be below
* 16 megabytes
LR 6,1 Save address of obtained
* storage to be used for
* a save area for module
* USER2
USING SAVEREGS,6 Save area addressability
LA 0,GMLNTH Get dynamic storage for
* module USER2 below
* 16 megabytes.Note: This GETMAIN will only be done on the initial call to this
module.
#2000 GETMAIN RU,LV=(0),LOC=RES Obtain storage below
* 16 megabytes
LR 8,1 Copy address of storage
* obtained via GETMAIN
USING DYNAREA,8 Base register for the
* dynamic work area
ST 13,SAVEBKWD Save address of caller's
* save area
LR 9,13 Save caller's save area
* address
LA 13,SAVEAREA USER1's save area address
* Note - save area is
* below 16 megabytes
The GETMAIN at statement #2000 requests that storage be obtained to match the current residency mode of module USER2. Because the module resides below 16 megabytes, storage obtained will be below 16 megabytes.
Note: The following store operation is successful because module
USER1 obtained save area storage below 16 megabytes.
ST 13,8(9) Have caller's save area
* point to my save area
.
.
.
.
* Process input requests
.
.
.
.
READ1 DS 0H Read a record routine
.
L 13,SAVEBKWD
LM 14,12,12(13) Reload USER1's registers
BSM 0,14 Return to caller - this
* instruction sets AMODE 31
WRITE1 DS 0H Write a record routine
.
L 13,SAVEBKWD
LM 14,12,12(13) Reload USER1's registers
BSM 0,14 Return to caller - this
* instruction sets AMODE 31
OPEN1 DS 0H Open file 1 for input
.
L 13,SAVEBKWD
LM 14,12,12(13) Restore caller's registers
BSM 0,14 Return to caller - this
* instruction sets AMODE 31
CLOSE1 DS 0H Close file 1 for input
.
L 13,SAVEBKWD
LM 14,12,12(13) Restore caller's registers
BSM 0,14 Return to caller - this
* instruction sets AMODE 31
OPEN2 DS 0H Open file 2 for input
.
L 13,SAVEBKWD
LM 14,12,12(13) Restore caller's registers
BSM 0,14 Return to caller - this
* instruction sets AMODE 31
CLOSE2 DS 0H Close file 2 for input
.
L 13.SAVEBKWD
LM 14,12,12(13) Restore caller's registers
BSM 0,14 Return to caller - this
* instruction sets AMODE 31
.
.Note: This FREEMAIN will only be done on the final call to this
module.
LA 0,GMLNTH Length of work area used
* by USER2
FREEMAIN RC,LV=(0),A=(8) Free storage
.
.
.DCB END OF FILE and ERROR ANALYSIS ROUTINES:
ENDFILE DS 0H End of file encountered
.
.
MVC STATUS,ENDFILE Indicate end of file to
* module USER1
.
L 13,SAVWBKWD
LM 14,12,12(13) Reload USER1's registers
BSM 0,14 Return to USER1
* indicating end of file
* has been encountered
.
.
.
.
ERREXIT1 DS 0H SYNAD error exit one
.
.
MVC STATUS,IOERROR Indicate I/O error to
* module 'USER1'
.
L 13,SAVWBKWD
LM 14,12,12(13) Reload USER1's registers
BSM 0,14 Return to USER1
* indicating an I/O error
* has been encountered
.
.
.
.
ERREXIT2 DS 0H SYNAD error exit two
.
.
MVC STATUS,IOERROR Indicate I/O error to
* module 'USER1'
.
L 13,SAVWBKWD
LM 14,12,12(13) Reload USER1's registers
BSM 0,14 Return to USER1
* indicating an I/O error
* has been encounteredNote: Define the required DCBs that module USER2 will process.
The DCBs exist in storage below 16 megabytes. The END OF DATA and
SYNAD exit routines also exist in storage below 16 megabytes.
INDCB DCB DDNAME=INPUT1,DSORG=PS,MACRF=(GL),EODAD=ENDFILE, x
SYNAD=ERREXIT1
OUTDCB DCB DDNAME=OUTPUT1,DSORG=PS,MACRF=(PL),SYNAD=ERREXIT2
* Work areas and constants for module USER2
IOERROR DC C'IO' Constant used to indicate
* an I/O error
ENDFILE DC C'EF' Constant used to indicate
* end of file encountered
SAVEREGS DSECT This storage exists
* below 16 megabytes
SAVEAREA EQU SAVEREGS
SAVERSVD DS F Reserved
SAVEBKWD DS F
SAVEFRWD DS F
SAVE1412 DS 15F Save area for registers 14-12
WORKLNTH EQU *-SAVEREGS Length of dynamic area
.
.
.
.
.
COMMAREA DSECT Parameter area used to
* communicate with module
* USER1
FUNCTION DS CL2 Function to be performed
* by USER2
STATUS DS CL2 Status of read operation
BUFFER DS CL80 Input/output buffer
.
.
DYNAREA DSECT This storage exists
* below 16 megabytes
.
.
.
.
.
.
GMLNTH EQU *-DYNAREA Length of dynamic area
.
.
END