DEFSYS

Authorization

Privilege Class: E

Purpose

Use DEFSYS to define a skeleton system data file (Class S, SDF) for a named saved system (NSS).

The skeleton file consists of a descriptor page that contains all information that is necessary to preserve the NSS with the SAVESYS command.

Operands

name

is the name of the NSS (a 1- to 8-character alphanumeric string).

Important: If you specify a name that is the hexadecimal number of a device, that device is IPLed instead of the NSS.

LOADDEV and DUMPDEV are reserved keywords and cannot be used as NSS names.

hexpage1-hexpage2

is a range of pages to be saved. hexpage1 and hexpage2 are the page numbers of available pages. When they are the same, only that page is saved. The range can be contained in a single 1 MB segment, or it can comprise a contiguous area in two or more segments. You can use multiple page ranges to define a 1 MB segment. However, the page descriptor codes of all page ranges in the same segment must have the same shared or exclusive attribute. (See the description of the type operand for information about page descriptor codes.)

Define only those pages whose data must be saved. Any page or pages in a segment that is not explicitly defined in a page range on the DEFSYS command defaults to the no data saved attribute. If other pages in the segment were defined with the shared attribute (page descriptor codes SR, SW, SN and SC), pages that are not specified on the command line become shared read-only pages whose data is not saved. No page descriptor codes correspond to this state; it has the same attributes as the state defined by page descriptor code SC except that CP does not write into these pages.

If other pages in the segment were defined with the exclusive attribute (page descriptor codes ER, EW and EN), any pages not specified on the command line become exclusive read/write pages whose data is not saved. This corresponds to page descriptor code EN.

The page number is a hexadecimal value less than or equal to X'7FEFF' (2047 MB). The following list shows examples of how hexadecimal storage addresses translate into hexadecimal page numbers:

Storage Address	Page Number
00000xxx	0
00001xxx	1
00022xxx	22
00333xxx	333
04444xxx	4444
3E6FFxxx	3E6FF
7F800xxx	7F800

type

refers to the 2-character page descriptor code of the page range in the NSS. It indicates the type of virtual machine access that is permitted to pages in the range.

The first character is either E for exclusive access or S for shared access. Sharing of storage between virtual machines is based on 1 MB segments, so that all 256 pages in any one segment must be either exclusive or shared.

The second character of the page descriptor code defines the storage protection characteristics of the page. These character designators are:

R

Indicates that page protection is used to make the page range read-only.

W

Means that the page is not protected, and users have read/write access.

N

Stands for read/write, no data saved, meaning that the page is treated as a new page when the user refers to it. The contents of, and storage keys for, no-data-saved pages are not saved by the SAVESYS command.

C

Stands for CP-writable, virtual machine read-only, no data saved, meaning virtual machines have read-only access to these pages, but CP services can change the data in the pages.

The contents of and storage keys for no-data-saved pages are not saved by the SAVESYS command.

Valid page descriptor codes are:

Code

Meaning

EW

Exclusive read/write access.

EN

Exclusive read/write access, no data saved.

ER

Exclusive read-only access.

SW

Shared read/write access.

SN

Shared read/write access, no data saved.

SR

Shared read-only access.

SC

CP-writable pages, shared read-only access by virtual machine, no data saved.

Any page ranges defined in segment zero must have an exclusive page descriptor code (EW, ER, or EN). If any pages in segment zero are defined with a shared access page descriptor code, the command is rejected.

MINSIZE=nnnnnnnK

MINSIZE=nnnnM

indicates the minimum storage size of the virtual machine into which the NSS can be loaded. The operand nnnnnnnK is the storage size in decimal kilobytes; nnnnM is the storage size in decimal megabytes.

Options

RSTD

indicates a restricted NSS. The user must have a corresponding NAMESAVE directory statement to access this NSS.

PARMREGS=m

PARMREGS=m-n

PARMREGS=NONE

specifies a range of general purpose registers to contain the IPL parameter string when the NSS receives control from the control program.

The operands m and n are decimal values from 0 to 15. If you specify two registers, n must be greater than or equal to m. If only one register is required, you can specify PARMREGS=m.

NONE specifies that no parameters can be passed to this NSS.

Note: If you want to use the AUTOCR, BATCH, NOSPROF, INSTSEG, or SAVESYS parameters of the IPL command, you must have PARMREGS=0-15 in the DEFSYS command for the CMS NSS.

VMGROUP

specifies that a user who IPLs this NSS becomes a member of a virtual machine group that is identified by the name of the NSS.

MACHMODE mm

specifies the set of virtual machine modes in which this NSS can be saved and IPLed.

The operand mm is a list of one or more virtual machine modes, separated by commas with no intervening blanks. Each entry in this list is one of the virtual machine mode designators ESA, XA, XC, or Z. ESA designates ESA/390 mode, although a guest can switch the virtual machine to z/Architecture® mode. XA is supported for compatibility and is functionally equivalent to ESA. XC designates ESA/XC mode, although a guest can switch the virtual machine to z/XC mode. Z designates a guest that runs only in z/Architecture mode.

If more than one machine mode is specified with this operand, the NSS is known as a multimode NSS. Special considerations apply regarding the information that is saved by the SAVESYS command and restored by the IPL command for a multimode NSS; see the description for the SAVESYS command for these special considerations. However, for purposes of determining if the NSS is multimode or not, the designations XA and ESA are considered synonyms. If both are specified, the pair is treated as a single machine mode specification rather than two. That is, specifying 'MACHMODE XA,ESA' does not result in the NSS being considered a multimode NSS.

Usage Notes

1. CP can process only one DEFSYS or SAVESYS command at a time. If CP is already processing a DEFSYS or SAVESYS command, processing of a subsequent DEFSYS or SAVESYS command is delayed. The SAVESYS command writes all page ranges, except those defined as EN or SN, to the associated system data file. The amount of time it takes for the command to complete is directly proportional to the amount of data to be written.
2. Defining an NSS at a high storage address that will be shared by many virtual machines might affect real storage availability. For each virtual machine, CP creates dynamic address translation (DAT) tables to reference the virtual machine storage. DAT tables include page tables, segment tables, and higher level (region) tables.

   CP keeps the page tables in page management blocks (PGMBKs). Each 8 KB PGMBK references 1 MB of virtual machine storage. For shared page ranges within an NSS, the associated segment table entries will point to the same page tables. However, for exclusive page ranges within an NSS, unique page tables are created for each user. PGMBKs might be pageable; as such, their impact on real storage depends on how frequently the MBs of storage they reference are used.

   Segment tables and region tables are allocated from host real storage and are not pageable:

   • To reference the page tables for a primary address space or data space up to 2 GB, 1 - 4 contiguous frames are allocated for the segment table, one frame for each 512 MB of storage.
   • For a primary address space larger than 2 GB, multiple segment tables are created, plus one or more region tables to reference the segment tables. Each region table occupies 1 - 4 contiguous frames. If needed, multiple levels of region tables are created.

   Because CP dynamically expands the size of a virtual machine to incorporate an NSS loaded at an address outside the virtual machine, the segment table for the virtual machine might also expand.

3. Page zero should always be saved for an operating system. If it is not saved, certain information might be lost. IBM® recommends that page zero is saved with the exclusive write (EW) page descriptor code.
4. Segment zero should always have the exclusive access attribute (EW, EN, or ER). If a shared page descriptor code (SW, SN, SR, or SC) is used for any pages in segment zero, the command is rejected.
5. Pages that are either defined as, or defaulted to, the no-data-saved attribute are initialized to a page of zeros when first referred to. If the pages are in an exclusive segment, changes are seen only by the one user. If the pages are in a shared segment, any changes that are previously made by any sharing user are visible to all other users sharing that same page.
6. A CP NSS (SC mode) contains CP-writable pages, to which virtual machine users have just read-only access. CP writes data into these pages, which can then be referred to by virtual machines. Serialization of data in the CP-writable pages can be arranged between the CP function that provides the data and the virtual machines that reference the data.
7. NSSs are loaded by using the IPL command. The use of the PARMREGS values is described with the IPL command.
8. When the user refers to any pages either defined as, or defaulted to, no-data-saved, the user gets a new page. A new page is assigned as a full frame of zeros, just as any page that does not have a copy that is backed on auxiliary storage.
9. Storage keys are not saved for pages that are either defined as, or defaulted to, no-data-saved. When these pages are first referred to, they have keys of zero. The virtual machine can set the keys for writable storage.
10. Each segment has an associated address range of 1 MB, regardless of the number of pages specified.
11. The maximum amount of storage available to a virtual machine is 2047 MB. To specify this value for MINSIZE, enter either '2047M' or '2096128K'.
12. If you do not specify the MACHMODE operand, the NSS can be saved (through the SAVESYS command) regardless of the saver's MACHINE value. However, the NSS can be IPLed only when the IPLer has the same MACHINE value as the saver.

    If you specify the MACHMODE operand, the NSS can be saved or IPLed only when the SAVESYS or IPL command is issued by a guest whose MACHINE value is specified on the MACHMODE operand.

13. Virtual machines that are designated as XA virtual machines (for example, by SET MACHINE XA) and virtual machines that are designated as ESA virtual machines are equivalent. Both designations cause the virtual machines to operate as ESA virtual machines. The virtual machine mode designations XA and ESA can be considered synonyms. Therefore:
    • NSSs that are defined by specifying MACHMODE ESA can also be saved when a virtual machine has been designated as an XA virtual machine.
    • NSSs that are defined by specifying MACHMODE XA can also be saved when a virtual machine has been designated as an ESA virtual machine.
    • An NSS that can be IPLed when a virtual machine has been defined as an ESA virtual machine can also be IPLed when a virtual machine has been defined as an XA virtual machine.
    • An NSS that can be IPLed when a virtual machine has been defined as an XA virtual machine can also be IPLed when a virtual machine has been defined as an ESA virtual machine.
14. Processing of a DEFSYS command might be delayed if DIAGNOSE code X'64' is concurrently performing the initial load of a large DCSS.
15. The NSS name _0___1__ is reserved for IBM use.
16. The reserved storage setting is not inherited by the new version of the NSS or DCSS if the following conditions are true:
    • A new version of a NSS or DCSS is created.
    • A previous version (with the same filename) exists.
    • The previous version had a reserved storage setting (as established by the SET RESERVED command).
    If you want reserved storage for the new version, you must explicitly enter the SET RESERVED command for the new NSS or DCSS after it is saved by using SAVESYS or SAVESEG.

Security Notes:

1. When RSTD is specified, only those users whose directory entries contain a NAMESAVE statement that specifies the same name as the DEFSYS operand are allowed to IPL the NSS. This restriction allows the installation to ensure data integrity by restricting access to NSSs that might contain sensitive data:
   • NSSs that contain shared writable storage (defined with the SW and SN page descriptor codes)
   • CP NSS (defined with the SC page descriptor code), which may contain sensitive data
2. Virtual machines that share read/write pages, which are defined with the SW and SN page descriptor codes, are responsible for the integrity of the shared data. The operating system that uses these shared writable pages should ensure that these virtual machines are properly protected from one another.

Messages

• HCP002E Invalid operand - operand
• HCP009E Invalid range - range
• HCP263E Too many operands were supplied for this command.
• HCP299E The Named Saved System (NSS) name could not be defined because a class S file with the same name already exists.
• HCP339E The command processing cannot complete because the page descriptor code invalid-code for the page range nnnnn-nnnnn should be exclusive.
• HCP422E The same option was specified twice.
• HCP423E The function requested is incompatible with a previously specified operand.
• HCP427E type {rdev|vdev|name[.userid]} system spool space full; file {closed|held|purged}
• HCP435E DEFSYS command processing cannot complete because a paging I/O error occurred while writing a page.
• HCP439E {User userid|*NSS|*IMG|*UCR|*NLS} spool fileid limit exceeded
• HCP440I Named Saved Segment (NSS) name was successfully defined in fileid fileid.
• HCP445E The Named Saved System (NSS) name could not be defined due to an unexpected error.
• HCP475I Fatal I/O error trying to read directory from volid [for user userid]
• HCP847E Maximum system spool file limit exceeded
• HCP1001E An operand is missing for option.
• HCP1013E An invalid operand was supplied for option - operand
• HCP1353E An invalid {name name|page range nnnnn-nnnnn} was detected in the DEFSYS command.
• HCP1354E An invalid storage page descriptor code invalid-code was detected for page range nnnnn-nnnnn.
• HCP1355E Segment number nnn was defined with both shared and exclusive page descriptor codes.
• HCP1356E nnnnn-nnnnn is a conflicting page range. Please check for overlaps and reissue the command.