To exploit data space support, use the routines provided in the
CMS callable services library (CSL), VMLIB CSLLIB. These routines,
which employ CP functions, provide CMS system services for creating,
controlling, and deleting data spaces. See the z/VM: CP Programming Services
for more information on the CP functions. The application must execute
in AR mode for the time necessary to complete any manipulation of or
direct reference to data in a data space.
An application running in a virtual machine that is allowed to
own a data space can perform the following operations,
each of which corresponds to a CSL routine:
- Create a data space (DMSSPCC)
- Delete a data space (DMSSPCD)
- Establish addressability to an address space (DMSSPLA)
- Permit other users (virtual machines) or applications to access
its address space (DMSSPCP)
- Isolate its address space from other users (DMSSPCI)
- Restore other users' access permission to use an address space
(DMSSPCR)
- Release pages of address space storage (DMSSPCRP)
- Remove addressability of an address space (DMSSPLR)
- Ask for the identification token and size of any address space
it owns or is permitted to access (DMSSPCQ).
A data space can be created and deleted only from an
XC virtual
machine that has been authorized using an XCONFIG ADDRSPACE directory
statement. With the SHARE option on that directory statement, your
application can share address spaces it created with applications
running on other virtual machines.
If the application is running in an ESA or XA virtual machine,
it must specify BASE for the name parameter on the DMSSPCC (Create Data Space)
routine. This indicates to the system that data space structures are
to be created for the virtual machine primary address space. These
structures allow sharing of the primary address space.
An application running in a virtual machine that is allowed to
access an address space belonging to another virtual machine can perform
the following operations, each of which corresponds to a CSL routine:
- Ask for the identification token of the address space it needs
to access
- Establish addressability to the address space
- Copy from the address space into its own virtual storage (only
for ESA and XA virtual machines)
- Remove addressability of the address space.
Note: Although data space management also can be performed
using CP macros and DIAGNOSE codes, do not use that interface in any
program that uses the CMS interface. CMS relies on the CP interface and any mixing
of the interfaces may inhibit CMS from performing its error checking.
Thus, performing data space management directly using data space
CP macros or DIAGNOSE codes along with the CMS interface may cause
unexpected results.
Table 1 summarizes the data space callable services
support in terms of what virtual machine mode the call can be made
from and whether the call must be made from the owner virtual machine.
Table 1. Data
Space Callable Services Summary
Service : |
May be Called from |
Is the
Owner |
Not Owner But Permitted
(1) |
ESA or XA mode |
XC mode |
DMSSPCC - Create Data Space |
yes (2) |
yes |
becomes owner |
n/a |
DMSSPCD - Delete Data Space |
yes (2) |
yes |
yes |
no |
DMSSPCRP - Release Address Space Pages |
yes (2) |
yes |
yes |
no |
DMSSPCQ - Query Address Space |
yes |
yes |
yes |
yes |
DMSSPCP - Permit Address Space Access |
yes (2) |
yes |
yes |
no |
DMSSPCI - Isolate Address Space |
yes (2) |
yes |
yes |
no |
DMSSPCR - Restore Address Space Access |
yes (2) |
yes |
yes |
no |
DMSSPCPY - Copy from Address Space |
yes |
no |
yes |
yes |
DMSSPLA - Establish Address Space Addressability |
yes |
yes |
yes (3) |
yes |
DMSSPLR - Remove Address Space Addressability |
yes |
yes |
yes |
yes |
Note:
- The virtual machine that intends to access an address space owned
by another virtual machine must be given permission to access by the
owning virtual machine and must have the address space identification
token (ASIT) or the name and owner of the data space
passed to it (or the name and owner are a fixed for all permitted
users) by the owning virtual machine. Having this, the permitted
virtual machine must obtain an ALET to be able to access the address
space.
- An application can call this routine only for address spaces owned
by the virtual machine in which it is executing. The only address
space an ESA or XA virtual machine owns is its primary address space.
When
DMSSPCC is called from an ESA or XA virtual machine, only the name
of BASE is accepted. No additional address space is created, but
CMS creates and maintains data space structures that allow sharing
of the user's primary address space by other virtual machines.
When
DMSSPCD is called from an ESA or XA virtual machine, only the ASIT
of the primary address space is accepted. No address space is deleted.
However, CMS does delete all data space related structures that were
created and maintained for the primary address space.
When DMSSPCRP
is used from an ESA or XA. virtual machine, only zeros can be specified
for the ASIT to indicate the primary address space. The pages released
are those of the primary address space.
- The DMSSPLA service is not required to establish addressability
to the virtual machine's own primary address space.
|