CMS Programming Interface

This chapter introduces and defines the CMS programming interface. It describes the different interface groups, the intent of each group, and the facilities that make up the group.

The CMS programming interface is a way for you to get CMS to do work for you. It is made up of:
  • CMS preferred interface group
  • CMS compatibility group
  • OS/MVS and DOS/VSE group.
To understand the concept of the CMS programming interface groups, you should first understand the virtual machine environments in which CMS runs.
z/VM® provides two versions of CMS:
ESA/390 CMS (generally referred to simply as CMS)
CMS runs in the following virtual machine architectures:
ESA/390 (ESA or XA virtual machine)
An ESA virtual machine simulates IBM® Enterprise Systems Architecture/390 (ESA/390), which is a superset of IBM Enterprise Systems Architecture/370 (ESA/370), which is a superset of IBM System/370 Extended Architecture (370-XA). The XA virtual machine designation is supported for compatibility; an XA virtual machine is functionally equivalent to an ESA virtual machine.
ESA/XC (XC virtual machine)
An XC virtual machine processes according to IBM Enterprise Systems Architecture/Extended Configuration (ESA/XC), which is an architecture unique to virtual machines. Although XC virtual machines run with dynamic address translation off, they can take advantage of a subset of dynamic address translation architectural features, and in particular, data spaces.
z/Architecture® CMS (z/CMS)
z/CMS runs in the following virtual machine architectures:
z/Architecture (ESA or XA virtual machine)
z/Architecture uses 31-bit addressing mode in an ESA ,XA, or Z virtual machine. CMS programs can use z/Architecture instructions, including those that operate on 64-bit registers, while permitting existing ESA/390 architecture CMS programs to continue to function without change.

When z/CMS is IPLed in an ESA/390 (ESA or XA) virtual machine, z/CMS switches the virtual machine to z/Architecture mode and thereafter executes in z/Architecture mode.

z/XC (XC virtual machine)
A z/XC guest uses VM Data Spaces with z/Architecture in the same way that an ESA/XC guest uses VM Data Spaces with Enterprise Systems Architecture. CMS applications that run in z/Architecture can use multiple address spaces. z/CMS can use VM Data Spaces for accessing Shared File System (SFS) Directory Control (DIRCONTROL) directories. z/XC supports programs that employ z/Architecture instructions and registers (within the limits of z/CMS support) and programs that exploit data spaces in the same CMS session.

When z/CMS is IPLed in an XC virtual machine, z/CMS switches the virtual machine to z/XC mode and thereafter executes in z/XC mode.

Unless otherwise indicated, CMS means either version, and descriptions of CMS functions apply to both CMS and z/CMS. For information on the z/CMS specifications and how to use z/CMS, see z/VM: CMS Planning and Administration.

The virtual machine mode is defined by using the MACHINE or GLOBALOPTS directory statement, the CP SET MACHINE command, or the Systems Management application programming interfaces.

Note: CP does not support System/370 architecture (370 mode) virtual machines. However, the 370 Accommodation Facility allows many CMS applications written for System/370 virtual machines to run in ESA/390 and ESA/XC virtual machines. The CP level of the 370 Accommodation Facility is activated with the CP SET 370ACCOM command. The CMS level of the 370 Accommodation Facility is activated with the CMS SET CMS370AC command. In addition, although the 370 option of the GENMOD command is not supported, modules previously generated with the 370 option can be run in an ESA/390 or ESA/XC virtual machine by issuing the CMS SET GEN370 OFF command. For more information about the 370 Accommodation Facility, see z/VM: CP Programming Services. See z/VM: CP Commands and Utilities Reference for information on the SET 370ACCOM command and see z/VM: CMS Commands and Utilities Reference for information on the SET CMS370AC and SET GEN370 commands.
The relationships between the virtual machine modes are summarized in Table 1.
Table 1. Comparison of CMS Virtual Machine Architectures
CMS Version Virtual Machine Architecture Mode1 Virtual Machine Architecture Addressing Scheme Addressable Primary Storage Addressable Data Space2
CMS ESA, XA3 ESA/390 31-bit 2047 MB 2 GB per data space4
CMS XC ESA/XC 31-bit and access registers 2047 MB 2 GB per data space
z/CMS ESA, XA3, Z z/Architecture5 31-bit6 2047 MB7 2 GB per data space4
z/CMS XC z/XC8 31-bit6 and access registers 2047 MB7 2 GB per data space
Notes:
  1. Architecture mode is set by using the SET MACHINE command and the MACHINE statement of the directory entry.
  2. Multiple data spaces are possible.
  3. The XA designation is supported for compatibility. An XA virtual machine is functionally equivalent to an ESA virtual machine.
  4. Data spaces can be read but cannot be modified. Data spaces can be modified only in virtual machines that run in XC architectur mode.
  5. When z/CMS is IPLed in an ESA/390 virtual machine, z/CMS switches the virtual machine to z/Architecture and thereafter executes in z/Architecture mode.
  6. Although z/CMS does not exploit or explicitly support 64-bit addressing mode, programs running on z/CMS can enter 64-bit addressing mode.
  7. Although z/CMS does not directly exploit storage above 2047 MB, z/CMS can be IPLed in a virtual machine with more than 2 GB of storage and allows programs to use storage above 2 GB.
  8. When z/CMS is IPLed in an XC virtual machine, z/CMS switches the virtual machine to z/XC and thereafter executes in z/XC mode.

With the CMS preferred interface, you can use macros, callable services (routines), and functions to code an application that is architecture-independent. The application can run in ESA, XA, and XC virtual machines. Therefore, you can write and assemble applications that are portable across the architectures.