Description

The requirements for the caller are:

Before using the DIV macro, the caller must first create either a linear data set object or a hiperspace object. The user must also supply a standard 72-byte save area.

• When you attach a new task, you cannot pass ownership of a mapped virtual storage window to the new task. That is, you cannot use the ATTACH or ATTACHX keywords GSPV and GSPL to pass the mapped virtual storage.
• While your program is in cross-memory mode, your program cannot invoke data-in-virtual services; however, your program can reference and update data in a mapped virtual storage window.
• The task that obtains the ID (through DIV IDENTIFY) is the only one that can issue other DIV services for that ID.
• When you identify a data-in-virtual object using the IDENTIFY service, you cannot request a checkpoint until you invoke the corresponding UNIDENTIFY service.
• When you use DIV with the IARVSERV macro to share data in virtual storage, you must follow several requirements; see the chapter about sharing data through IARVSERV in z/OS MVS Programming: Assembler Services Guide. The DIV macro does not support VSAM extended format linear data sets for use as a DIV object for which the size is greater than 4GB.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

• By using the DIV macro, you might reduce the amount of I/O. The SAVELIST service additionally improves performance of the application when it is necessary to inspect and verify data only in pages that have changed.
• Using LOCVIEW=MAP on a DIV ACCESS request degrades performance. Use LOCVIEW=NONE request whenever possible. You can use LOCVIEW=MAP request for small data objects without significant performance loss.
• Using RETAIN=YES on a DIV UNMAP request can degrade performance. Using RETAIN=YES causes the system to read more pages from the object.

The standard form of the DIV macro is written as follows:

The IDENTIFY, ACCESS, MAP, SAVE, SAVELIST, RESET, UNMAP, UNACCESS, and UNIDENTIFY parameters, which designate the services of the DIV macro, are mutually exclusive. You can select only one. The parameters are explained as follows:

IDENTIFY

Selects the data-in-virtual object (linear data set or hiperspace) that you want to process. When you specify IDENTIFY, you must also specify ID and TYPE. ID specifies the address of an eight-byte field into which the IDENTIFY service returns a unique eight-byte name. When you invoke other data-in-virtual services, you use this identifier, or token, as input. The use of the ID is associated only with your task; that is, all services for this ID must be requested by the same task that obtained the ID.

When the object is a data set, you must also specify TYPE=DA and DDNAME. When the object is a nonshared standard hiperspace, you must specify TYPE=HS and STOKEN.

ACCESS

Requests permission to access a data-in-virtual object. When you specify ACCESS, you must also specify ID and MODE, and you may optionally specify SIZE or LOCVIEW. ID specifies the token which identifies the object you want to access. If your object is a hiperspace, ACCESS allows either multiple readers or one updater. Therefore, the system does not accept a read request if there is already an updater, and it does not accept an update request if there is any other user currently accessing the same object. You cannot access a hiperspace as a data object if it is, or has been on an access list.

MAP

Establishes addressability to the object in a specified range of virtual storage, called the virtual window. When you specify MAP, you must also specify ID and AREA, and you may optionally specify OFFSET, SPAN, STOKEN, RETAIN, and PFCOUNT. Specify STOKEN when your window is in a data space or a standard hiperspace. If your window is in an address space, your object can be either a linear data set or a nonshared standard hiperspace. If your window is in a data space or a hiperspace, your object can be only a linear data set.

If you specified TYPE=DA, you can issue more than one MAP with different STOKENs. You cannot mix data space and hiperspace maps with address space maps under the same ID at any one time.

RESET

Releases changes made in the window since the last SAVE operation. When you specify RESET, you must also specify ID, and you may optionally specify OFFSET, SPAN, and RELEASE. If the window corresponds to blocks on the object, the current contents of the object will replace the data that has changed in the window when the program next references the window. RESET does not change the object.

Do not specify RESET for a storage range that contains DREF storage.

SAVE

Writes changed pages from the window to the corresponding blocks in the object. When you specify SAVE, you must also specify ID, and you may optionally specify OFFSET, SPAN, SIZE, and STOKEN. The system writes changed pages from the window into the blocks specified by OFFSET and SPAN. SAVE cannot change the size of a hiperspace object.

Do not specify SAVE for a storage range that contains DREF storage.

Optionally, SAVE accepts a user list that the application specifies through the LISTADDR and LISTSIZE parameters. The user list contains information returned by the SAVELIST service. If you specify a user list as input for SAVE, you cannot specify OFFSET and SPAN, and the system saves only those pages specified in the user list.

SAVELIST

Returns the addresses of the first and last changed pages in each range of changed pages within the window. The mapped ranges may be either address spaces, data spaces, or hiperspaces. If more than one data space or hiperspace is mapped onto a DIV object, the selected range must be contained within a single data space or hiperspace.

UNMAP

Terminates a virtual window by removing the correspondence between virtual pages in the window and blocks in the object. After the UNMAP is complete, the contents of the pages depend on the value you specify for RETAIN; the virtual pages in the former window either retain the current view of the object or appear as if they had just been obtained.

When you specify UNMAP, you must also specify ID and AREA, and you may specify RETAIN and STOKEN if the object is a data set and the window is in a data space or a hiperspace. UNMAP has no effect on the object itself and does not save data from the virtual window. If you want to save the data in the window, invoke SAVE before you invoke UNMAP.

If you issued multiple MAPs with different STOKENs, use STOKEN on UNMAP. If you do not specify STOKEN, the system scans the mapped ranges and unmaps the first range that matches the virtual area regardless of the data space it is in. Issuing UNACCESS or UNIDENTIFY automatically unmaps all mapped ranges.

UNACCESS

Relinquishes your permission to read from or write to a data-in-virtual object. When you specify UNACCESS, you must also specify ID, which provides the address of the unique name that was returned by the IDENTIFY service. When you invoke UNACCESS, any outstanding windows for the specified ID are automatically unmapped with an implied RETAIN=NO.

UNIDENTIFY

Ends the use of a data-in-virtual object under a previously assigned ID. When you specify UNIDENTIFY, you must also specify ID, which provides the address of the unique name that was returned by the IDENTIFY service. If the object is still accessed or mapped under the specified ID, the system will automatically unaccess and unmap it with an implied RETAIN=NO.

,ID=addr

Specifies the address of a field in storage where the IDENTIFY service stores a unique eight-byte name that it associates with the object. This name acts as a token and is the output value from the IDENTIFY service. It is a required input value for all the other services.

,AREA=addr

Specifies the address of a four-byte field in storage containing a pointer to the start of the virtual window. You must specify the AREA parameter when you invoke the MAP and the UNMAP services. The starting address for an UNMAP request must be identical to the starting address of its corresponding MAP request. Address space virtual storage that is occupied by a window must meet the following requirements:

• The window must begin on a 4096-byte (page) boundary and must be a multiple of 4096 bytes long.
• Virtual storage within the window must have been obtained from a single, pageable, private area subpool owned by the task that issued the IDENTIFY.
• The window cannot contain VIO storage.
• Pages within the window cannot be page fixed.

Data space and hiperspace virtual storage that is occupied by a window must meet the following requirements.

• The window must be on a 4096-byte boundary and must be a multiple of 4096 bytes long.
• The data space or hiperspace must be owned or created by the task specifying the MAP service.
• The data space or hiperspace must exist until you specify the UNMAP service for all mapped ranges.
• The specified mapped range must lie within the current bounds of the data space or hiperspace.

,DDNAME=addr

Specifies the address of a field containing the ddname for the data set object when you specify TYPE=DA on IDENTIFY. The first byte of the field must be the number of characters in the ddname. The bytes following the first byte must contain the EBCDIC characters of the ddname itself. The ddname must conform to the standard syntax for ddnames (one through eight alphameric or national characters). DDNAME is required when you invoke IDENTIFY with TYPE=DA for a data set object but is not allowed when you specify TYPE=HS for a hiperspace object. Do not specify a DDNAME that corresponds to a VSAM extended format linear data set for which the size is greater than 4GB, because the DIV macro does not support them for use as a DIV object.

Encrypted linear VSAM data sets are supported. For more information, see z/OS DFSMS Using Data Sets.

,LISTADDR=listaddr

Specifies the address of a 4-byte field that contains a pointer to the user list that the caller provides for the SAVELIST service.

,LISTSIZE=listsize

Specifies the address of a 4-byte field that contains the number of entries in the user list for the SAVELIST service. The size of the list must be a minimum of three entries and a maximum of 255 entries, where each entry contains two words.

,LOCVIEW=MAP

,LOCVIEW=NONE

Specifies whether the system is to create a local copy of the data-in-virtual object. For hiperspace objects, you must specify LOCVIEW=NONE or use the default.

LOCVIEW=MAP specifies that the system is to establish a local copy of the data set object for the specified range. Use MAP to maintain a consistent view in the virtual storage window of data on permanent storage in environments where there are multiple writers or at least one reader and writer at the same time to the object.

LOCVIEW=NONE specifies that the system is not to create a local copy of the object. NONE is the default. Use NONE in environments where there is either a single writer, OR one or more readers, but not both at the same time.

,MODE=READ

,MODE=UPDATE

Specifies whether the object is being accessed for the purpose of reading or updating. If you are using the SAVE service to update an object, specify MODE=UPDATE. Otherwise, specify MODE=READ to signify read-only access to the object. You must specify MODE whenever you specify ACCESS.

,OFFSET=addr

,OFFSET=*

Specifies the beginning of a continuous range of blocks in a data-in-virtual object. OFFSET is used with SPAN to define a continuous range of blocks in an object. OFFSET designates the location of the first block in the range, and SPAN designates how many blocks are in the range. An OFFSET value of zero designates the first block (the beginning) of an object. The system permits an OFFSET beyond the current end of the object as long as it remains within the maximum number of blocks allowed for the object and also within the absolute limit of (2**20)-1 blocks. If you omit OFFSET or specify OFFSET=*, the system uses a default OFFSET of zero. You can specify the OFFSET parameter with MAP, RESET, and SAVE.

,RETAIN=YES

,RETAIN=NO

Determines what data appears in the window when you invoke the MAP service, and what data is left in virtual storage when you invoke UNMAP.

When you specify RETAIN=YES with MAP, the data in the virtual range stays the same. The system considers all pages in the range changed. When you specify RETAIN=NO (or use the default) with MAP, data in the object replaces the data in virtual range.

When you specify RETAIN=NO with UNMAP, the data in the virtual range becomes freshly obtained. When you specify RETAIN=YES with UNMAP, the virtual range retains its current view.

,SIZE=addr

,SIZE=*

Specifies the address of a field where the system stores the size of the object. The system returns the size in this field whenever you specify SAVE or ACCESS and also specify SIZE. When the system returns control after executing a SAVE, the value that it returns is the minimum number of blocks that must be mapped to ensure that the entire object is mapped. If you omit SIZE or specify SIZE=*, the system does not return the size.

If you specified TYPE=DA for a linear data set object, and you specify SIZE, the macro returns the current size of the object in the four-byte location that SIZE designates.

If you specified TYPE=HS for a hiperspace object, and you specify SIZE, ACCESS returns two sizes in the eight-byte location. The first is the current size of the hiperspace (in 4K byte units), and the second is the maximum size of the hiperspace (also in 4K byte units).

Specify SIZE only when you specify ACCESS or SAVE.

,SPAN=addr

,SPAN=*

Specifies the address of a four-byte field containing the number of blocks that are to be processed. Use SPAN only with the MAP, RESET, or SAVE services, which operate only on a range of contiguous blocks. SPAN indicates how many blocks are in the range. It is used with OFFSET, which indicates the first block of the range.

For the RESET and SAVE services, the block range can include noncontiguous mappings of an object. This lets you reset or save several maps in a single DIV macro invocation.

For the MAP service, the block range can extend beyond the end of the object, but it cannot extend beyond the maximum size allowed for the object. You can create a window that exceeds the size of the object. The maximum span allowed is (2**20)-1 blocks.

If you omit SPAN or specify SPAN=*, or if the four-byte field contains zero, the system uses the SPAN default value. For the SAVE and RESET services, the default value is the number of blocks in the object from the specified or defaulted block to the end of the last mapped range. For the MAP service, the default is the current size of the object in blocks, minus the value specified by OFFSET. If the offset value is beyond the end of the object, the span defaults to one when you omit SPAN.

,STOKEN=addr

Specifies the address of an eight-byte field that identifies a hiperspace or data space. STOKEN is valid only with the IDENTIFY, MAP, SAVE, and UNMAP parameters. Specify STOKEN with MAP to map a linear data set object onto data space or hiperspace virtual storage, or to unmap data space or hiperspace storage.

With MAP, the system maps the permanent object into the data space or hiperspace that the STOKEN represents. If you do not specify STOKEN, the mapping applies to the primary address space. With UNMAP, STOKEN identifies which data space or hiperspace contains the window to be unmapped.

If you specified TYPE=HS for a hiperspace object, specify STOKEN with IDENTIFY. The system does not verify the STOKEN until you use the associated ID with ACCESS.

,TYPE=DA

,TYPE=HS

TYPE=DA specifies that your program is using a data definition statement to identify a VSAM linear data set as the data object. The DIV macro does not support VSAM extended format linear data sets for use as a DIV object for which the size is greater than 4GB. TYPE=HS specifies that your program is using STOKEN to identify a hiperspace as the data object. The hiperspace must be a nonshared standard type and must be owned by the task issuing the IDENTIFY. Only the owner of the hiperspace can issue any subsequent ACCESS, MAP, and SAVE. You can use a nonshared standard hiperspace if no program has ever issued ALESERV ADD for that hiperspace. You cannot issue ALESERV ADD for a nonshared standard hiperspace while it is a data object.

,PFCOUNT=nnn

Specifies the additional pages the system is to read into real storage on a page fault. nnn is an unsigned decimal number from 0 to 255. If you specify an integer greater than 255, the system uses 255. Zero is the default. If you omit PFCOUNT or specify PFCOUNT=0, the system reads blocks from the data object one at a time. In any case, the system reads in successive pages only to the end of the virtual range of the mapped area containing the originally referenced page.

Use PFCOUNT if your program accesses the mapped object in a sequential manner. Because you get a page fault the first time you reference each page, reading into real storage multiple consecutive pages on each page fault might decrease the number of page faults and improve your program's performance.

PFCOUNT applies to movement of pages from the object to central storage. PFCOUNT does not apply to movement of changed or unchanged data that the system has moved to the real storage as a direct result of system management of the real storage.

,RELEASE=YES

,RELEASE=NO

Specify RELEASE=YES to release all virtual pages in the reset range. Specify RELEASE=NO or use the default to release only changed pages in the reset range. RELEASE=NO does not replace unchanged pages in the window with a new copy of pages from the object. It replaces only changed pages. If another ID might have changed the object itself while you viewed data in the window, specify RELEASE=YES to reset all pages. Any subsequent reference to these pages will cause the system to load a new copy of the data page from the object.

DIV might abnormally terminate with abend code X'08B'. See z/OS MVS System Codes for an explanation and programmer response.

When the system returns control to the caller after the DIV macro executes, it supplies a return code in the low-order (rightmost) byte of general register 15 and a reason code in the two low-order bytes of register 0. After an unsuccessful completion, the system abnormally terminates the caller and supplies an abend code of X'08B' and a reason code in the two low-order bytes of general register 15. See z/OS MVS System Codes for a detailed explanation of the reason codes for abend code X'08B'.

The hexadecimal values of the reason and return codes are: