Summary of Data Space Operations

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:
  1. 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.
  2. 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.

  3. The DMSSPLA service is not required to establish addressability to the virtual machine's own primary address space.