Your program uses the ACCESS service to request permission to read
or update the object. ACCESS has two required parameters: ID and
MODE, and two optional parameters: SIZE and LOCVIEW.
The following example shows one way to code the ACCESS service.
DIV ACCESS,ID=DIVOBJID,MODE=UPDATE,SIZE=OBJSIZE
ID: When you issue a DIV macro
that requests the ACCESS service, you must also specify, on the ID
parameter, the identifier that the IDENTIFY service returned. The
task that issues ACCESS must own the corresponding ID. The ID parameter
tells the system what object you want access to. When you request
permission to access the object under a specified ID, the system checks
the following conditions before it grants the access:
- You previously established the ID specified with your ACCESS request
by invoking IDENTIFY.
- You have not already accessed the object under the same unique
eight-byte ID. Before you can reaccess an already-accessed object
under the same ID, you must first invoke UNACCESS for that ID.
- If your installation uses RACF®,
you must have the proper RACF authorization
to access the object.
- If you are requesting read access, the object must not be empty.
Use the MODE parameter to request read or update access.
- If the data object is a hiperspace, the system rejects the request
if the hiperspace:
- Has ever been the target of an ALESERV ADD.
- Has one or more readers and one updater.
(That is, the hiperspace can have readers and it can have one updater,
but it can't have both.)
- If the data object is a linear data set, the system
rejects the request if the linear data set:
- Is a VSAM extended format linear data set for which the size is
greater than 4GB.
MODE: The MODE parameter specifies
how your program will access the object. You can specify a mode parameter
of READ or UPDATE. They are described as follows:
- READ lets you read the object, but prevents you from using SAVE,
to change the object.
- UPDATE, like READ, lets you read the object, but it also allows
you update the object with SAVE.
Whether you specify READ or UPDATE, you can still make changes
in the window, because the object does not change when you change
the data in the window.
SIZE: The SIZE parameter specifies
the address of the field where the system stores the size of the object.
The system returns the size in this field whenever you specify SAVE
or ACCESS with SIZE. If you omit SIZE or specify SIZE=*, the system
does not return the size.
If you specified TYPE=DA with IDENTIFY for a data set object, SIZE
specifies the address of a four-byte field. When control is returned
to your program after the ACCESS service executes, the four-byte field
contains the current size of the object. The size is the number of
blocks that the application must map to ensure the mapping of the
entire object.
If you specified TYPE=HS with IDENTIFY for a hiperspace object,
ACCESS returns two sizes. The first is the current size of the hiperspace
(in blocks). The second is the maximum size of the hiperspace (also
in blocks). When specifying SIZE with an ID associated with a hiperspace
object, you must provide an eight-byte field in which the system can
return the sizes (4 bytes each).
LOCVIEW: The LOCVIEW
parameter allows you to specify whether the system is to create a
local copy of the data-in-virtual object.
If your object is a hiperspace, you cannot specify LOCVIEW=MAP.
If your object is a data set, you can code the LOCVIEW parameter
two ways:
- LOCVIEW=MAP
- LOCVIEW=NONE (the default if you do not specify LOCVIEW)
If another program maps the same block of a data-in-virtual object
as your program has mapped, a change in the object due to a SAVE by
the other program can sometimes appear in the virtual storage window
of your program. The change can appear when you allocate the data
set object with a SHAREOPTIONS(2,3), SHAREOPTIONS(3,3), or SHAREOPTIONS(4,3)
parameter, and when the other program is updating the object while
your program is accessing it.
If the change appears when your program is processing the data
in the window, processing results might be erroneous because the window
data at the beginning of your processing is inconsistent with the
window data at the end of your processing. For an explanation of SHAREOPTIONS,
see
z/OS DFSMS Using Data Sets. The relationship between SHAREOPTIONS
and LOCVIEW is as follows:
- When you allocate the data set object by SHAREOPTIONS(2,3), SHAREOPTIONS(3,3),
or SHAREOPTIONS(4,3), the system does not serialize the accesses that
programs make to the object. Under these options, if the programs
do not observe any serialization protocol, the data in your virtual
storage window can change when other programs invoke SAVE. To ensure
that your program has a consistent view of the object, and protect
your window from changes that other programs make on the object, use
LOCVIEW=MAP. If you do not use LOCVIEW=MAP when you invoke ACCESS,
the system provides a return code of 4 and a reason code of hexadecimal
37 as a reminder that no serialization is in effect even though the
access was successful.
- When you allocate the object by SHAREOPTIONS(1,3), object changes
made by the other program cannot appear in your window because the
system performs automatic serialization of access. Thus, when any
program has update access to the object, the system automatically
prevents all other access. Use LOCVIEW=NONE when you allocate the
data set by SHAREOPTIONS(1,3).
Note: The usual method of
programming data-in-virtual is to use LOCVIEW=NONE and SHAREOPTIONS(1,3).
LOCVIEW=MAP is provided for programs that must access a data object
simultaneously. Those programs would not use SHAREOPTIONS(1,3).
LOCVIEW=MAP requires extra processing that degrades performance.
Use LOCVIEW=NONE whenever possible although you can use LOCVIEW=MAP
for small data objects without significant performance loss. When
you write a program that uses LOCVIEW=MAP, be careful about making
changes in the object size. Consider the following:
- When a group of programs, all using LOCVIEW=MAP, have simultaneous
access to the same object, no program should invoke any SAVE or MAP
that extends or truncates the object unless it informs the other programs
by some coding protocol of a change in object size. When the other
programs are informed, they can adjust their processing based on the
new size.
- All the programs must create their maps before any program changes
the object size. Subsequently, if any program wants to reset the
map or create a new map, it must not do so without observing the protocol
of a size check. If the size changed, the program should invoke UNACCESS,
followed by ACCESS to get the new size. Then the program can reset
the map or create the new map.