More than one IOSADMF request can be active for a hiperspace. When
you have more than one active IOSADMF request, keep track of the requests
and ensure that all data transfer is complete before deleting the
hiperspace. If there are outstanding active requests and you issue
DSPSERV DELETE for a hiperspace, your program will abnormally end
and the hiperspace will not be deleted. If you cannot determine
whether all outstanding IOSADMF requests have completed, you can issue
IOSADMF APURGE to stop any outstanding requests.
If you have a single unit of work that creates the hiperspace,
issues the IOSADMF requests, and deletes the hiperspace, you do not
have to be concerned about outstanding requests; the system completes
the data transfer before processing the delete request. The following
is an example of data transfer using the ADMF.
***********************************************************************
*02* Description = Sample program to illustrate how to use the *
* IOSADMF services. *
* *
* *
*02* Function = *
* *
* ADMFSAMP does not perform any useful work; *
* however it does illustrate how the IOSADMF *
* services are used. ADMFEXMP will create a *
* hiperspace, create an address space buffer, *
* initialize the address space buffer, use *
* HSPSERV to write data to the hiperspace *
* from the address space buffer, and then *
* use IOSADMF to read data from the hiperspace *
* back into the address space buffer. *
* In more detail, here is what ADMFEXMP does: *
* - Changes mode to supervisor state key 0. *
* IOSADMF requires the caller to be authorized. *
* - Obtains a dynamic area. ADMFSAMP is *
* reentrant and therefore requires a *
* dynamic area. ADMFSAMP was written *
* as a reentrant routine for illustration *
* and independence of caller's mode or *
* key. *
* - Determines if ADMF is available on the *
* current machines by issuing IOSADMF with *
* the AQUERY service. *
* - Creates a hiperspace *
* - Obtains an address space buffer area and *
* clears it. *
* - Initializes the address space buffer area *
* - Writes the address space buffer pages to *
* the hiperspace *
* - Clears the address space buffer area *
* - Fixes the page address space storage *
* - Uses IOSADMF to read the hiperspace pages *
* back into the address space storage areas *
* - Cleans up resources and returns to caller *
* *
* Again, this routine is only for illustration *
* purposes. *
* *
* *
* SECURITY NOTICE = This sample should be used ONLY on a test *
* system. It does not contain authorization *
* checking required for running on a *
* production system. *
* *
* ENVIRONMENT: AMODE = 31 *
* RMODE = 31 *
* STATE = SUPERVISOR *
* KEY = 0 *
* RENT = YES *
* *
* *
* INPUT: NONE *
* *
* REGISTER USAGE: *
* R9 BASE REGISTER FOR LOAD MODULE *
* R6 POINTS TO DYNAMIC AREA *
* ALL OTHERS STANDARD USAGE *
*.....................................................................*
EJECT
ADMFEXMP CSECT
ADMFEXMP AMODE 31 31-BIT ADDRESSING MODE
ADMFEXMP RMODE ANY Rmode any
SPACE 1
*.....................................................................*
* REGISTER ASSIGNMENTS *
*.....................................................................*
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6 Dynamic area register
R7 EQU 7
R8 EQU 8
R9 EQU 9 Module base register
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
SPACE 3
TITLE 'ADMFEXMP - ADM Sample for AQUERY'
*.....................................................................*
* *
* Standard Entry Linkage *
* *
*.....................................................................*
PRINT GEN
USING *,R9 Sets up base reg
LR R9,R15 Establish module base
ENTRY STM R14,R12,12(R13) Save caller's regs
MODESET KEY=ZERO,MODE=SUP
LA R0,DYNSIZE Load length of dynamic area
STORAGE OBTAIN,LENGTH=((R0)),SP=233 Gets dynamic area
LR R6,R1 Gets dynamic area address
USING DYNAREA,R6 Sets up dynamic area
ST R13,SAVEBK Save caller's save area addr
ST R6,SAVEFW Save ADMFEXMP save area address
B MAINLINE
DC CL8'ADMFEXMP'
DC CL8'&SYSDATE'
DC CL8'&SYSTIME'
TITLE 'ADMFEXMP - ADMF mainline '
*.....................................................................*
* *
* MAINLINE *
* *
*.....................................................................*
MAINLINE DS 0H
L 10,X'10' Load CVT pointer
USING CVT,10
TM CVTDCB,CVTOSEXT Is the OSLEVEL extension present
BNO NO_ADMF No, pre-MVS/SP Version 3 system
*
TM CVTOSLV1,CVTH4430 Running on version HBB4430?
BNO NO_ADMF No, pre-HBB4430 system. ADMF
* supported on HBB4430 and above
*
* Running on HBB4430 system. Must determine if ADMF
* software and hardware have been installed on this
* processor
*
*.....................................................................*
* *
* Issues the IOSADMF macro with the AQUERY parameter *
* to determine if the ADMF hardware and software are *
* available. *
* *
* Note - the IOSADMF macro may be issued on an HBB4430 *
* system, however, the full support for ADMF requires *
* the ADMF PTF as well as hardware support. *
* *
*.....................................................................*
IOSADMF AQUERY, X
CROSSOVER=CROSSOVER_#, X
RETCODE=ADMF_INSTALLED_RC, X
RSNCODE=REASONCODE, X
MF=(E,ADMFLIST)
L R15,ADMF_INSTALLED_RC Obtains return code from
* parameter list
LTR R15,R15 Test for 0 return code
BNZ NO_ADMF
ADMF_INSTALLED DS 0H ADM support is available
*.....................................................................
*
* ADMF is installed and available. Begin function processing to
* illustrate how ADMF is used
*
*.....................................................................
*
BAL R14,CREATE_HS Build Hiperspace
LTR R15,R15 Test for 0 return code
BNZ EXIT Exit if bad RC
BAL R14,AS_STORAGE Get address space storage
BAL R14,INIT_AS Initialize addr space storage
BAL R14,ISSUE_HSPSERV Initialize HS space storage
LTR R15,R15 Test for 0 return code
BNZ EXIT Exit if bad RC
BAL R14,ISSUE_IOSADMF Use ADMF to read data from HS
*.....................................................................
* Begins clean up operations
*.....................................................................
DSPSERV DELETE,STOKEN=HSSTOKEN
LR R3,R1 Loads area addr in R3
A R3,LENGTH_AS_AREA Adds length of area to addr
BCTR R3,0 Subtracts 1 to get end addr
PGSER R,FREE,A=(R1),EA=(R3),ECB=0
L R3,LENGTH_AS_AREA
STORAGE RELEASE,SP=229,ADDR=ASPTR,LENGTH=(R3)
B EXIT
NO_ADMF DS 0H
*.....................................................................
*
* ADM support is either not installed or not
* available on this release
*
*.....................................................................
WTO 'ADMFEXMP - ADMF not installed. Sample ends', X
ROUTCDE=(11),DESC=(2)
LA R3,12 Loads failing return code
ST R3,RETURNCODE Stores return code for X
future use
EXIT DS 0H
L R13,SAVEBK Reloads caller's save
* area addr into 11
L R12,RETURNCODE Saves return code
* in reg 12
LA R0,DYNSIZE Loads dynamic area size
* FREEMAIN R,LV=(0),A=(6),SP=233 Frees dynamic area
STORAGE RELEASE,SP=233,ADDR=(R6),LENGTH=(R0)
MODESET KEY=NZERO,MODE=PROB
LM R14,R11,12(R13) Loads return regs
LR R15,R12 Loads return code
BR R14 Returns to caller
*
*
SPACE 2
*.....................................................................
*
* Subroutine to create Hiperspace
*
* DSPSERV creates a non-shared standard hiperspace
*
* Since this sample is for illustration only, the hiperspace size
* will be one block, or one page, larger than the CROSSOVER value.
*
*.....................................................................
CREATE_HS DS 0H Create Hiperspace routine
STM R14,R12,12+LCL_SAVEAREA Save registers
L R1,CROSSOVER_# Obtains the CROSSOVER #
AL R1,=F'1' Adds one to the CROSSOVER
ST R1,NUM_BLOCKS Stores the number of blocks
DSPSERV CREATE, X
NAME=HSNAME, X
TYPE=HIPERSPACE, X
HSTYPE=SCROLL, X
SHARE=NO, X
BLOCKS=NUM_BLOCKS, X
STOKEN=HSSTOKEN, X
ORIGIN=HSORIG, X
MF=(E,DSPSLIST)
ST R15,RETURNCODE Saves return code
LTR R15,R15 Test for 0 return code
BNZ SKIP_ALESERV Skip ALESERV if bad RC
*.....................................................................
*
* The IOSADMF service requires an ALET as input. The following
* ALESERV service will place the hiperspace ALET on the program's
* access list.
*
*.....................................................................
ALESERV ADD, X
STOKEN=HSSTOKEN, X
ALET=HSALET, X
AL=WORKUNIT, X
MF=(E,ALESLIST)
SKIP_ALESERV DS 0H
LM R14,R12,12+LCL_SAVEAREA Load Register
L R15,RETURNCODE Loads return code
BR R14 Returns to caller
*.....................................................................
*
* Subroutine to obtain and initialize address space storage areas
*
*.....................................................................
AS_STORAGE DS 0H Obtains address space storage
STM R14,R12,12+LCL_SAVEAREA Save registers
L R5,ONE_PAGE
L R3,NUM_BLOCKS Loads the size of hiperspace
* NOTE: For this sample, the
* hiperspace and address
* space areas are made to
* be the same size for
* simplicity.
MR R2,R5 Calculates length of storage
* to obtain
ST R3,LENGTH_AS_AREA
STORAGE OBTAIN,LENGTH=((R3)),BNDRY=PAGE,SP=229
*
ST R1,ASPTR Saves the addr of data area
L R2,ASPTR Loads R2 with address of
* the obtained area in
* preparation for clearing
* using the MVCL.
L R3,LENGTH_AS_AREA Loads length of area into R3
SR R4,R4 Setting R4/R5 pair to zero
SR R5,R5 tells MVCL to clear area
MVCL R2,R4 Clear obtained area
*
LM R14,R12,12+LCL_SAVEAREA Load Register
BR R14 Returns to caller
*.....................................................................
*
* Subroutine to initialize the address space area with data to be
* stored in the hiperspace.
*
* This subroutine loops through all of the address space buffer
* pages and initializes each page with some text data.
* The data placed in the address space buffer area is dummy data
* for illustration. It places some text at the top of each
* page and places the page number in hex after the text.
*
*.....................................................................
INIT_AS DS 0H Initialize addr space area
STM R14,R12,12+LCL_SAVEAREA Save registers
BLOCK_INDEX EQU R2 Make loop control easier to X
read by using equate for index
AS_POINTER EQU R3 Make address space area easierX
to follow by using equate
LA BLOCK_INDEX,1 Initializes block index
L AS_POINTER,ASPTR Gets addr space pointer
USING PAGE_MAP,AS_POINTER Use the PAGE_MAP dummy X
section
INIT_LOOP DS 0H Beginning of WHILE loop
CL BLOCK_INDEX,NUM_BLOCKS IF block_index greater X
num_blocks THEN
BH INIT_COMPLETE Exits loop if complete
MVC PAGE_TEXT_TAG,BLOCK_CONST Place text tag
ST BLOCK_INDEX,PAGE_INDEX_TAG Place hex tag
AL BLOCK_INDEX,=F'1' Index to next page
AL AS_POINTER,ONE_PAGE Point to next page
B INIT_LOOP
INIT_COMPLETE DS 0H
LM R14,R12,12+LCL_SAVEAREA Load Register
BR R14 Returns to caller
*.....................................................................
*
* Subroutine to Initialize the Hiperspace
* ---------------------------------------
*
* HSPSERV initializes hiperspace blocks. Before the hiperspace
* can be used by IOSADMF, it must be initialized using the HSPSERV
* service. The HSPSERV service causes hiperspace pages to be
* backed with actual expanded storage pages. Even though ADMFEXMP
* created the hiperspace earlier, the system does not actually
* allocate expanded storage pages until data is placed into them.
* The following HSPSERV service will cause expanded storage pages
* to be backed.
*.....................................................................
ISSUE_HSPSERV DS 0H Initialize hiperspace routine
STM R14,R12,12+LCL_SAVEAREA Save registers
L R2,ASPTR Loads address space pointer
ST R2,ASPTR1 Saves address space pointer X
in range list
L R2,HSORIG Loads hiperspace block pointer
ST R2,HSORIG1 Saves hiperspace pointer in X
range list
L R2,NUM_BLOCKS Loads number of blocks to move
ST R2,NUMBLKS1 Saves number of blocks to X
move in range list
LA R2,SWRITLST Loads address of ranglist
ST R2,SWRITADDR Saves address of ranglist
LA R13,HSP_SAVEAREA
HSPSERV SWRITE, X
STOKEN=HSSTOKEN, X
HSPALET=HSALET, X
RANGLIST=SWRITADDR, X
MF=(E,HSPSLIST)
ST R15,RETURNCODE Saves return code
LM R14,R12,12+LCL_SAVEAREA Load Register
L R15,RETURNCODE Loads return code
BR R14 Returns to caller
*.....................................................................
*
* Subroutine to use the IOSADMF service to read data from hiperspace
* ------------------------------------------------------------------
*
* IOSADMF
*
*.....................................................................
ISSUE_IOSADMF DS 0H Uses the IOSADMF service
STM R14,R12,12+LCL_SAVEAREA Save registers
LR R3,R1 Loads area addr in R3
A R3,LENGTH_AS_AREA Adds length of area to addr
BCTR R3,0 Subtracts 1 to get end addr
PGSER R,FIX,A=(R1),EA=(R3),ECB=0
L R2,ASPTR Loads R2 with address of X
the address space area in X
preparation for clearing X
using the MVCL. R3 will X
contain the area's length
L R3,LENGTH_AS_AREA Loads length to clear
SR R4,R4 Setting R4/R5 pair to zero
SR R5,R5 tells MVCL to clear area
MVCL R2,R4 Clear target area for the X
AREAD operation. For X
illustration purposes, the X
address space area is X
reused for the ADMF AREAD
L R2,ASPTR Loads address space pointer
ST R2,ASPTR2 Saves address space pointer X
in range list
L R2,HSORIG Loads hiperspace block pointer
ST R2,HSORIG2 Saves hiperspace pointer in X
range list
L R2,NUM_BLOCKS Loads number of blocks to move
ST R2,NUMBLKS2 Saves number of blocks to X
move in range list
LA R2,AREADLST Loads address of ranglist
ST R2,AREADADDR Saves address of ranglist
IOSADMF AREAD, X
ALET=HSALET, X
RANGLIST=AREADADDR, X
MF=(E,ADMFLIST)
ST R15,RETURNCODE Saves return code
LM R14,R12,12+LCL_SAVEAREA Load Register
L R15,RETURNCODE Loads return code
BR R14 Returns to caller
*......................................................................
* .
* Constants .
* .
*......................................................................
HSNAME DC CL8'ADMFHSPS' Name for the hiperspace
ONE_PAGE DC F'4096' Length of one page of
* storage
BLOCK_CONST DC CL7'Block #:'
*......................................................................
* .
* DSECTs to map save areas and dynamic areas .
* .
*......................................................................
DYNSTART DS 0H
DYNAREA DSECT
* Save area
SAVEXX DS F
SAVEBK DS F
SAVEFW DS F
SAVER14 DS F
SAVER15 DS F
SAVER0 DS F
SAVER1 DS F
DS 11F
DS 0D Force doubleword alignment
* Save area for internal subroutines
SPACE 2
LCL_SAVEAREA DS 18F Local save area
HSP_SAVEAREA DS 32F HSPSERV save area
DS 0D Force doubleword alignment
*......................................................................
* .
* List forms of macros. The list and execute forms of these macros .
* are used because this module is reentrant. .
* .
*......................................................................
LIST_DSPSERV DSPSERV MF=(L,DSPSLIST)
DSP_END DS 0D
LIST_HSPSERV HSPSERV MF=(L,HSPSLIST)
HSP_END DS 0D
LIST_IOSADMF IOSADMF MF=(L,ADMFLIST)
ADMF_END DS 0D
ALESLIST ALESERV MF=L
ALES_END DS 0D
*......................................................................
* .
* Work variables and data structures local to this module .
* .
*......................................................................
HSSTOKEN DS CL8 STOKEN for the hiperspace
HSALET DS CL4 ALET for the hiperspace
ASPTR DS 1F Location of addr space
* storage
NUM_BLOCKS DS F Number of blocks in
* hiperspace
HSORIG DS F Hiperspace origin
CROSSOVER_# DS F Crossover number
SWRITADDR DS F Address of SWRITE ranglist
AREADADDR DS F Address of AREAD ranglist
ADMF_INSTALLED_RC DS F ADMF installed return code
LENGTH_AS_AREA DS F Length of addr space area
WORKAREA DS CL144 Work area for HSPSERV
DS 0F
SWRITLST DS 0CL12 SWRITE range list
ASPTR1 DS F Start of address space
HSORIG1 DS F Target location in hiperspace
NUMBLKS1 DS F Number of 4k blks in swrite
DS 0F
AREADLST DS 0CL12 AREAD and SREAD range list
ASPTR2 DS F Target location in AS
HSORIG2 DS F Start of hiperspace source
NUMBLKS2 DS F Number of 4k blocks in read
*
RETURNCODE DS F
REASONCODE DS F
END_DYN DS 0D
DYNSIZE EQU *-DYNAREA Calculates Dynamic area
*
PAGE_DSECT DSECT Mapping of a page
PAGE_MAP DS 0CL4096
PAGE_TEXT_TAG DS CL8 Top of page tag
PAGE_INDEX_TAG DS F Page index in hex
SPACE 2
ADMFEXMP CSECT
TITLE 'ADMFEXMP - DSECT MAPPINGS'
EJECT
CVT LIST=YES,DSECT=YES
END ADMFEXMP
z/OS MVS Programming: Extended Addressability Guide
Copyright IBM Corporation 1990, 2014