Step 7: Enter an ENROLL USER Command

To create new SFS file spaces in a file pool, use the ENROLL USER command. You must have file pool administration authority to enter the command. An abbreviated format of the command is:

To create new BFS file spaces in a file pool, use the ENROLL USER command with the BFS operand. You must have file pool administrator authority to enter the command. An abbreviated format of the command is:

Options

For a complete command description, see ENROLL USER.

For SFS, the userid corresponds to the user ID that is to be enrolled in the file pool. This is the CP user ID of the person you are enrolling. If the user is on a processor in another TSAF or CS collection, that user should first be assigned a user ID on a processor within your TSAF or CS collection before he or she is enrolled. If the user is on a processor in an SNA network, that user should first be assigned a user ID on your processor or on a processor within your TSAF or CS collection before he or she is enrolled. See Setting Up a File Pool for Remote Use for additional considerations.

The BLOCKS option indicates the number of 4096-byte blocks that are to be allocated for the file space. The maximum number of blocks you can assign to a file space is 2,147,483,647. (The practical limit is somewhat less than the number of 4KB blocks in the file pool.) Remember the blocks assigned represent potential (or logical) space. The server does not need real DASD space until files are created in the file space.

The number of blocks specified represents the maximum number of committed blocks. (That is, blocks that a user or application wants to permanently write to the file pool.) For SFS, there is no restriction, other than the physical DASD space in the storage group, on the number of uncommitted blocks a user or application can consume. This lets an application, for example, create a temporary work file that exceeds the number of unused blocks available to the user. When the application no longer needs the temporary file, the application can either:

Roll back the file instead of committing it, or
Erase the file before committing it, then commit the file instead of rolling it back.

For BFS, this concept of uncommitted blocks is not pertinent because all blocks used are committed when they are submitted to the file pool server.

If you do not specify BLOCKS, the file space is not given any initial space (blocks). A file space without space still has a top directory. The user can create a directory structure and put objects other than files in the file space.

The STORGROUP option identifies the storage group to which the file space is to be assigned, regardless of whether you have given it any space. The number specified must be between 2 and the maximum number of storage groups defined for the file pool, inclusive. The storage group must exist. That is, it must have at least one minidisk assigned to it. If you omit this parameter, the file space is assigned to storage group 2.

The BFS operand specifies the file space is to be created is a Byte File System file space (BFS). The USER owning_userid option identifies the VM user ID whose UID should become the owning UID of the top directory of the file space.

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

If you do not remember which storage groups exist in the file pool, enter:

query filepool storgrp filepoolid

For filepoolid, substitute the name of the file pool in question. The resultant display shows valid storage groups for a file pool.

A portion of the display might look like this:

 Storage        4K Blocks       4K Blocks
 Group No.        In-Use          Free
     1           296 -  34%        580
     2           264 -  18%       1218
     3             0 -   0%       1482
     4             0 -   0%       1482
     5             0 -   0%       1482

For example, to enroll SFS user Mary in the file pool named TEST1 without space to create files, enter:

enroll user mary test1 (storgroup 3

Mary is assigned to storage group 3. To enroll user Bob in the same file pool with 1000 blocks of space (4,096,000 bytes), enter:

enroll user bob test1 (blocks 1000 storgroup 2

Bob is assigned to storage group 2. All 1000 of Bob's blocks will be allocated from that storage group.

Another example, is to enroll BFS file space JoAnne in the file pool named OURS1 without space to create files, enter:

enroll user joanne ours1 (bfs user joanne group ourgroup

JoAnne is assigned to storage group 2 by default.

When enrolling a group of SFS file spaces, try using the NAMES command to create a list of file spaces. Then enter an ENROLL USER command for the nickname. Suppose you define a nickname SALEDEPT that identifies all users in the sales department. To enroll those users, each with 100 blocks, enter:

enroll user saledept test1 (blocks 100 storgroup 5

Each name in the names files will be enrolled individually.

Do not enroll user IDs beginning with a plus (+) or minus (-) character, or that contain a period (.) or colon (:). These characters are used for directory names, of which user ID is a part. If you were to use these characters in a user ID and then specify that user ID in a directory name, CMS would not be able to tell whether the characters are part of the user ID or directory separator characters.

Also, be aware that deadlocks can occur when file spaces are enrolled concurrently by different administrators, especially if the user 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.

Note: For some administrative tasks you might find it desirable to communicate with all the users of a storage group or all the enrolled file pool users. To make it easier to communicate with groups of file pool users, consider using the NAMES command to create and maintain a list of users for each storage group. Also consider creating a nickname that contains a list of all the storage group nicknames. By doing this, you can easily communicate file pool news to users using the NOTE or TELL commands.

In some situations it might be useful to be able to list information about enrolled file spaces in storage group order. An example of an exec to do so is in WHO EXEC.

Note: The CSL routine that corresponds to the ENROLL USER command is DMSENUSR. For information on DMSENUSR, see z/VM: CMS Callable Services Reference.