ENROLL USER

Read syntax diagramSkip visual syntax diagram ENRoll USEr filespaceidnickname1filepoolid:(2(3Options)
Options
Read syntax diagramSkip visual syntax diagramBLOcks0BLOcksblksSTOrgroup2STOrgroupstorgrpSFSBFSUSER*USERowning_useridGROUP*GROUPowning_groupnameNOTypeTYPeSTACKFIFOLIFOFIFOLIFO
Notes:
  • 1 The default is the default file pool ID for your virtual machine. If there is no default file pool ID, the command fails.
  • 2 The defaults you receive appear above the line in the Options fragment.
  • 3 You can enter Options in any order between the parentheses.

Authorization

Repository File Pool Administrator

Purpose

Use the ENROLL USER command to enroll a user or create a Byte File System (BFS) in a specific file pool. This command provides function equivalent to the CSL Routine DMSENUSR - Enroll File Space, which is described in z/VM: CMS Callable Services Reference.

Operands

filespaceid
identifies the file space to be enrolled. This is either a user ID to be enrolled or the name of the Byte File System (BFS) to be created. Do not enroll a user ID that begins with a plus (+) or a minus (-) or that contains a colon (:) or a period (.). These characters are used as separator characters in SFS directory IDs and the file space ID is a part of the SFS directory ID. Also, BFS file space IDs may not contain the slash (/) or X'00' characters.
nickname
identifies a nickname that represents a user ID, a BFS, or a list of user IDs. (Use the NAMES command to define nicknames.) You may not use a nickname representing a list if any of the file spaces in the list are Byte File System.
filepoolid
filepoolid:
identifies the file pool in which the file space is to be created. If not specified, the default file pool ID for your virtual machine is used.

Options

BLOcks blks
is an optional parameter that indicates the number of 4096-byte file blocks that can be consumed by the file space.

When ENROLL USER is entered with the BLOCKS option, physical DASD space is not immediately reserved. Physical DASD space is used only as it is needed. The BLOCKS value is a limit to the number of blocks a user is allowed to consume. The BLOCKS value represents committed blocks, (that is, blocks permanently written to the file pool).

For SFS file spaces, there is no limit, other than the physical space available in the storage group, on the number of uncommitted blocks a user or application can consume.

For BFS file spaces, consumption greater than the BLOCKS value is not allowed.

The blks can range from 1 through 2,147,483,647. If the BLOCKS option is omitted, the file space is created with 0 blocks.

STOrgroup storgrp
is an optional parameter where storgrp specifies the storage group to which the user is assigned. All explicitly enrolled file pool users are assigned to some storage group even if they do not have space in the file pool. The storgrp can range from 2 through 32767, but must not be greater than the MAXDISKS value for the file pool. (MAXDISKS is set during file pool generation and can be changed by the FILESERV REGENERATE command.) The storage group specified must exist (that is, must have minidisks assigned to it), even if you are not allocating space in the file pool. If not specified, this parameter defaults to 2.
SFS
specifies the file space to be created is an SFS file space. SFS is the default.
BFS
specifies the file space is to be created is a Byte File System (BFS).
USER owning_userid
identifies the VM user ID whose UID should become the owning UID of the top directory of the file space.

USERID * indicates the owning UID or GID (or both) of the top directory of the file space should be the same as those associated with the VM user ID on which the command was entered.

GROUP owning_groupname
identifies the group name whose GID should become the owning GID of the top directory of the file space.

GROUP * indicates the owning GID should be the same as that associated with the VM User ID on which the command was entered.

NOType
suppresses the display of the file space IDs to be enrolled. NOType is the default.
TYPe
displays at the terminal the file space IDs to be enrolled.
STACK FIFO
STACK LIFO
places the information in the console stack rather than displaying it at the terminal. FIFO is the default.
LIFO
specifies the information is stacked in a last in, first out order. This option is equivalent to STACK LIFO.
FIFO
specifies the information is stacked in a first in, first out order. This option is equivalent to STACK FIFO.

Usage Notes

Common Notes for SFS and BFS

  1. Note that deadlocks can occur when file spaces are enrolled concurrently by different administrators, especially if the file space IDs are standardized (USER1, USER2, USER3, for example). In this case, one of the jobs is automatically rolled back. If this occurs, retry the command.
  2. You can change the amount of space a file space is allowed to consume by entering the MODIFY USER command.
  3. You can move the file space to a different storage group by using the FILEPOOL UNLOAD and FILEPOOL RELOAD commands. For instructions on how to do this, see FILEPOOL UNLOAD and FILEPOOL RELOAD.
  4. Use the QUERY ENROLL command to determine who is enrolled in a file pool. The QUERY ENROLL command is described in z/VM: CMS Commands and Utilities Reference.
  5. Entering an ENROLL USER command for a user ID of PUBLIC is not the same as entering an ENROLL PUBLIC command. ENROLL PUBLIC lets all user IDs connect to the file pool. ENROLL USER PUBLIC simply lets the user ID PUBLIC connect to the file pool.

    When ENROLL PUBLIC has been entered for a file pool, a subsequent QUERY ENROLL USER FOR ALL command will show <PUBLIC> in its output. If a user ID of PUBLIC is enrolled, PUBLIC (without the < and > characters) will be displayed. If both ENROLL USER PUBLIC and ENROLL PUBLIC have been entered for the file pool, you will see both PUBLIC and <PUBLIC> in the QUERY ENROLL output.

    Specifying either <PUBLIC> or * as the user ID to be enrolled is not allowed. An error message will be issued.

  6. If the ENROLL USER command is entered from an EXEC or ASSEMBLER program, and the file pool specified is active (that is, has some work on it which has not been committed or rolled back) on the current default work unit, the command will cause an error.
  7. You can change the name of a file space using the FILEPOOL RENAME command.
  8. Because DFSMS/VM uses file space IDs beginning with DFSMS you should avoid enrolling a file space ID that begins with DFSMS. Also if you do enroll such a file space, DFSMS/VM will not manage anything in that file space. See z/VM: DFSMS/VM Storage Administration for more information.
  9. Enrolling a BFS file space means no SFS file space can be created for a user with that same name.

Notes for SFS only

  1. If a nickname that represents a list of user IDs was specified, and the enrollment is unsuccessful for one file space in the list, enrollment of all file spaces in the list will be unsuccessful.
  2. When an ENROLL USER command is entered, the following applies for the specified user IDs regardless of whether the BLOCKS option is specified. The user:
    • Can connect to the file pool.
    • Is given a top directory. The name of the top directory is the user ID.
    • Can exercise all privileges explicitly granted to PUBLIC.
    • Can exercise all privileges explicitly granted to the user ID.
  3. If the BLOCKS option is omitted, the specified user ID is not given a file space in the file pool. The user is given a top directory, as always, and can create a directory structure and put aliases in it. But, the user cannot create base files in his or her own directories. If the user has WRITE or directory control write (DIRWRITE) authority to other users' directories, the user can create files in those directories (assuming those other users have space allocated to them).

    Even if the user has no file space, he or she can still exercise all privileges explicitly granted to PUBLIC. For example, suppose user TOM is enrolled without space. User GARY grants WRITE authorization to his PC FORUM file to PUBLIC. TOM can connect to the file pool and create an alias to the PC FORUM file. Even though TOM has no space of his own, he can still write to the PC FORUM file.

    Users without file space can exercise all privileges explicitly granted to the user ID. For example, user JACK might grant READ authority on one of his files to user IRA. Even if user IRA has no space of his own, he still has a top directory and can create an alias to JACK's file.

  4. If the BLOCKS option is specified, the user is given a file space in which he or she can create base files. The user can authorize others to write to his or her directories and files, in which case others will be able to use blocks in that file space.
  5. If you specify a nickname and the NODE tag in the NAMES file indicates the user is on another processor, you must also specify the LOCALID tag.
  6. A warning threshold of 90 percent is established for a user when you enroll the user with space (the BLOCKS option is specified). When the number of file blocks a user consumes exceeds 90 percent of his or her total allocated space, CMS issues a warning message to the user. Others who are authorized to write to the file space may also receive the warning message.

    Users may change their default threshold warning percent by using the SET THRESHOLD command or the administrator can change the threshold warning percent for any file space with the SET THRESHOLD command with the FOR userid or FOR nickname option.

  7. Note you can enroll a user ID in a file pool even if no such user ID exists in the z/VM® system directory. This lets you enroll a set of user IDs in a file pool before they are added to your z/VM system.

Notes for BFS only

  1. When a BFS file space is created, the owning UID is given read, write, and search permission for the top directory. Group and public permissions are not given. The owner of the file space or a BFS superuser can use the OPENVM PERMIT command to change permissions associated with the directory.
  2. If the BLOCKS option is omitted, the Byte File System is created, but is not allocated any space in the file pool. Users can create BFS objects that do not require space. This excludes only non-empty regular files.
  3. If the BLOCKS option is specified, a Byte File System is created in which users can create BFS regular files as well as other BFS objects.
  4. Threshold values are not established or maintained for Byte File System file spaces.
  5. You cannot enter the ENROLL USER command with the BFS option while in subset mode, DOS mode, or running on a level of CP which is earlier than VM/ESA Version 2 Release 1.
  6. The user ID provided on the USER option and group name provided on the GROUP option are translated into a UID and a GID based on the values in the POSIX database on the system on which the command is issued. This database can be in the z/VM CP directory, or managed by an External Security Manager (ESM). When using these values, the administrator who is issuing the command should be on the same system as the file pool containing the new BFS or results are unpredictable.
  7. To specify a user ID on the USER option, the requesting VM user ID must be authorized to obtain a user entry in the POSIX database. To specify a group name on the GROUP option, the requestor must be authorized to obtain a group entry in the database.

    Typically, the requesting VM user ID has the attribute POSIXOPT QUERYDB ALLOW set, either through a statement in its CP directory entry or through a specified or defaulted setting in the system configuration file not overridden in the directory entry.

    If that is not the case, one of the following must be true:
    • The external security manager (ESM) grants the requestor the authority to read the entry.
    • An ESM is either not installed or defers authorization to CP, and one of the following is true:
      • The requestor is a superuser (has an effective UID of 0).
      • The current real or effective UID or GID matches the UID or GID for the specified user or group.
      • For a GID, the requestor is a member of the specified group.

Messages and Return Codes

In addition to the messages listed below, this command displays other system messages. These system messages are listed in z/VM: CMS and REXX/VM Messages and Codes.

This command internally issues IDENTIFY, FINIS, NUCXDROP, and NUCXLOAD commands. Therefore, messages from those commands can also be displayed. (For more information about those commands, see z/VM: CMS Commands and Utilities Reference.)

Messages:

  • DMS029E Incorrect parameter parm in the option option field [RC=24]
  • DMS065E option option specified twice [RC=24]
  • DMS066E option1 and option2 are conflicting options [RC=24]
  • DMS109S Virtual storage capacity exceeded [RC=109]
  • DMS389E Incorrect operand: operand [RC=24]
  • DMS637E Missing node ID for the AT operand [RC=24]
  • DMS647E Userid not specified for nickname in userid NAMES file [RC=32]
  • DMS647E Localid not specified for userid at node in user's NAMES file [RC=32]
  • DMS653E Error executing command rc=nn [RC=40]
  • DMS1166E Userid filespaceid is already enrolled [RC=40] {User ID userid | Group name groupid} cannot be resolved.
  • DMS1175E Storage group does not exist [RC=40]
  • DMS1175E Storage group does not exist. The file pool must be regenerated [RC=40]
  • DMS1201E STACK option cannot follow FIFO or LIFO [RC=24]
  • DMS1209E Nickname nickname resolved to more than one name; only one Byte File System can be created at a time [RC=40]
  • DMS2023E File pool filepoolid does not support the requested option [RC=88]
  • DMS2132E Error obtaining UID or GID [RC=104]
  • DMS2132E Error obtaining UID or GID. User not authorized [RC=104]
  • DMS2132E Error obtaining UID or GID. User not found [RC=104]
  • DMS2132E Error obtaining UID or GID. Group not found [RC=104]
  • DMS2132E Error obtaining UID or GID. Database not available [RC=104]
  • DMS2132E Error obtaining UID or GID. Command not allowed in CMS/DOS environment, in CMS subset mode, or on this level of CP [RC=104]