HISTORICAL MANUALS
UNIVERSITY OF KENTUCKY
COMPUTING CENTER
CMS Resource Allocation Package
Version 1.0
This document describes the use
and operation of the CMS
Resource Allocation Package for
the UKCC's IBM 3081.
UU U KK K CCCC CCCC
UU U KK K CC CC
UU U KKK CC CC
UU U KK K CC CC
UUU KK K CCCC CCCC
First Edition, Revision 0 (January 1985)
This edition applies to Version 1.0 of the
CMS Resource Allocation Package running
under VM/CMS.
Users of this manual are encouraged to
report any errors or ambiguities, and to
make suggestions for improvements.
Contact a consultant at the address below.
Technical changes made to the contents of
this manual are indicated by a vertical
bar to the left of the change.
University of Kentucky
Computing Center
72 McVey Hall
Lexington, KY 40506-0045
Phone: 606/257-2900
Processed January 9, 1985-Waterloo SCRIPT - Version 83.1 (03/09/84)
Prepared by Herman Collins and Judy Lovan
CMS Resource Allocation Package
Section 1: Introduction
The CMS Resource Allocation Package Version 1.0 allows the
various departments at UK to allocate, control, and monitor their
instructional use of the IBM 3081 CMS facilities. The CMS RAP
program is modelled on the RAP program used on the PRIME system.
The programs have some differences because of the differences
between the PRIME and CMS and because this version of the CMS RAP
program must conform to the accounting procedures for the IBM 3081
that are used by the Computing Center.
To use the CMS RAP program, the user obtains a project number
and CMS userid from the Computing Center. Only the Computing
Center can create or update the project userid.
Once the project userid has been assigned, it can be used to
create two types of userids, grantor userids and student userids.
The differences between these two types of userids are described
in the Parameters Section. At the present time, grantor userids
should not be manipulated with the RAP program because there
should be one class for each project and one grantor for each
class. The project userid should be used to create the student
userids for the class. Larger departments may have several
project userids.
Creating a userid involves transferring some of the grantor's
resources to the new userid. Three resources may be transferred:
connect time, CPU time, and disk storage. The resources are
described in the Parameters Section of this manual.
RAP uses keywords followed by positional parameters.
"Positional parameters" means that the parameters are entered in a
specific sequence and that no parameter can be skipped. Its place
in the sequence must contain either data or a place holder. In
some instances, the place holder is an "*".
When RAP detects an error in a parameter, it prints an
"INVALID" message followed by the name of the parameter and the
invalid data. It then asks for valid data.
RAP creates a reader spool file in the logged on userid's CMS
reader. This file contains a header record followed by a record
for each userid created, updated, deleted, or listed during the
RAP session. After the RAP session, the file in the reader can be
input and stored as a CMS file, printed from the CMS file, printed
directly from the reader, or left in the reader. (Note: reader
files are automatically deleted after one week.)
Section 1: Introduction 1
CMS Resource Allocation Package
When RAP asks for data, it displays an "ENTER" message that
indicates what it expects to be entered. It then displays a
prompt character. If "Q" or "Quit" is entered when RAP is asking
for a parameter, processing of the present keyword will stop and
RAP will ask for a keyword. If "Q" or "Quit" is entered when RAP
is asking for a keyword, the RAP session will end.
When RAP accepts data from the terminal, it will accept a
maximum of 130 characters.
RAP also reads and writes a Userid file. The Userid file has
one record for every CMS user. If an error occurs when RAP tries
to read or write the file, a message will be displayed on the
terminal. These messages are listed in the File Error Section of
this manual.
Section 1: Introduction 2
CMS Resource Allocation Package
Section 2: Commands
RAP
To use the Resource Allocation Package, enter the "RAP"
command. This will allow the manipulation of userid records
for the current fiscal year.
HELP RAP name
"Name" may be any of the RAP HELP files. To display the menu,
enter HELP RAP MENU.
MANUAL BROWSE CMSRAP
This will display the RAP manual on the terminal.
MANUAL PRINT CMSRAP
This will print the RAP manual.
Section 2: Commands 3
CMS Resource Allocation Package
Section 3: Parameters
The parameters used by RAP are:
Parameter Function
connect Time a user can be logged on.
CPU CPU and I/O allocation.
disk Disk space for userid.
expires Expiration date.
id Student or grantor CMS userid.
num Number of student userids to be manipulated.
pw Password for the userid.
seq Sequencing for student userid suffixes.
The RAP parameters that allocate resources are positional
parameters. Each parameter is in the same position in all of the
keywords that use the parameter. Each parameter must be preceded
by at least one blank. The characters in the parameters should be
alphabetic or numeric except for the following special characters:
! for password to cause RAP to generate a random password.
* as a place holder or to cause RAP to use a default value.
- to subtract from a resource.
+ to add to a resource.
: to indicate following numbers are minutes in connect time.
. to indicate following numbers are cents in CPU allocation.
/ to separate month, day, and year in expiration date.
connect
The "connect" parameter is the time a userid can be logged on.
The units for connect are hours and minutes.
The hours and minutes must be numeric.
A ":" indicates that the numbers that follow are minutes.
If no ":" is present, the numbers are considered to be
hours.
The maximum value for minutes is 99.
If connect is missing, RAP will prompt for it.
For new records:
"connect" will be the logon time for the userid.
A "0" sets no limit on connect.
An "*" causes RAP to use the default connect.
Section 3: Parameters 4
CMS Resource Allocation Package
If the default is not set, RAP will prompt for connect.
For updating existing records:
A "0" sets no limit on connect.
An "*" is a place holder and connect will not be changed.
A leading "+" means add to the existing connect.
A leading "-" means subtract from the existing connect.
An unsigned number replaces the existing connect.
cpu
The "CPU" parameter defines the CPU time and CMS I/Os for a
user.
The units for CPU are dollars and cents.
This is because of the accounting on the IBM 3081.
The dollars and cents must be numeric.
A "." indicates that the numbers that follow are cents.
If no "." is present, the numbers are considered to be
dollars.
The maximum value for cents is 99.
If CPU is missing, RAP will prompt for it.
For new records:
"CPU" will be the CPU allocation for the userid.
A "0" sets no limit on CPU.
An "*" causes RAP to use the default CPU.
If the default is not set, RAP will prompt for CPU.
For updating existing records:
A "0" sets no limit on CPU.
An "*" is a place holder and CPU will not be changed.
A leading "+" means add to the existing CPU.
A leading "-" means subtract from the existing CPU.
An unsigned number replaces the existing CPU.
disk
The "disk" parameter is the disk space for a userid.
The unit for disk space is kilobytes. There are 1024 bytes in
a kilobyte. One byte is the same as one character.
The minimum disk space for any userid is 480 kilobytes.
At present, the maximum disk space for a student userid is 480
kilobytes.
Section 3: Parameters 5
CMS Resource Allocation Package
To request disk space in megabytes, append an M to the number
as
"1M" or "4M". One megabyte is 1024 kilobytes.
If the disk space is missing, RAP will prompt for it.
For new records:
"disk" will be the disk space for the userid.
A "0" sets no limit on the disk space.
A CMS userid with 0 disk space cannot be used.
An "*" causes RAP to use the default disk space.
If the default is not set, RAP will prompt for the disk
space.
For updating existing records:
An "*" is a place holder. The disk space cannot be changed.
expires
The "expires" parameter defines the expiration date for student
userids.
The units for expires are month, day, year.
The units must be numeric.
A "/" separates the units as, 01/17/84.
If expires is missing, RAP will prompt for "DATE".
For current fiscal year:
Expires cannot be less than the current date.
Expires cannot be greater than the end of the fiscal year.
For new fiscal year:
Expires cannot be less than the beginning of the fiscal
year.
Expires cannot be greater than the end of the fiscal year.
For new records:
"expires" sets the expiration date.
A "0" sets no limit on expires.
An "*" causes RAP to use the default expires date.
If the default is not set, RAP will prompt for "DATE'.
For updating existing records:
"expires" replaces the existing expiration date.
A "0" sets no limit on expires.
An "*" is a place holder and expires will not be changed.
Section 3: Parameters 6
CMS Resource Allocation Package
id
The "id" parameter is the student or grantor CMS userid.
The "id" of an existing CMS userid cannot be changed.
When the "id" parameter is required, RAP will prompt if it is
missing.
There is no place holder for "id", it cannot be an "*".
GRANTOR id
A grantor id is six (6) characters in length, with characters 1
through 3 being the same as characters 1 through 3 of the
logged on userid. This means that a userid starting with XYZ
cannot manipulate a userid starting with ZZZ. This precaution
is taken to prevent one department from inadvertently modifying
another department's userids.
STUDENT id
A student id is eight (8) characters in length, with characters
1 through 6 being the same as the id of the logged on user.
This means that grantor userid XYZ101 cannot manipulate a
student userid starting with XYZ102. Because of this, one
grantor cannot manipulate the student ids of another grantor.
The last two characters, characters 7 and 8, of the student id
are called the suffix. The "seq" parameter in the GROUP or
DELGRP keywords can be used to tell RAP what type of sequencing
to use for student userids generated by RAP. For all other
keywords, RAP will accept any combination of letters and
numbers as the suffix of a student userid.
num
The "num" parameter is used by some of the keywords to sepcify
that the same action be taken on the requested number of
student userids.
"num" must be numeric.
pw
The "pw" parameter is the password for a userid.
The password can be from 2 to 8 characters in length.
If the password is missing, RAP will prompt for it.
If RAP prompts, the password cannot be "Q" or "QUIT".
Section 3: Parameters 7
CMS Resource Allocation Package
This will cause the keyword to end.
Passwords for new userids are written in the reader file. They
are also displayed on the terminal when BRIEF is OFF.
Passwords for old userids are not available. They will always
be listed as "********". If the password for an existing
userid is reset, the password will then be written to the
reader file and also displayed on the terminal when BRIEF is
OFF.
For new records:
"pw" will be the userid password.
An "!" causes RAP to generate a random password.
An "*" causes RAP to use the default password.
If the default is not set, RAP will prompt for the
password.
The default password can be an "!" and RAP will generate
random passwords.
For updating existing records:
"pw" will replace the existing password.
An "!" causes RAP to generate a random password.
An "*" is a place holder and the password will not be
changed.
The random passwords generated by RAP are 4 letters in length.
The vowels and y are not included in the random passwords.
seq
The "seq" parameter is used to set the type of sequencing for
student userid suffixes.
"seq" is a two character parameter. The first character
defines the sequencing of the first character of the suffix and
the second character defines the sequencing of the second
character of the suffix.
Each character can be limited to alphabetic, numeric, or
alphanumeric. There are nine possibilities for sequencing.
Using "a" to indicate alphabetic, "n" to indicate numeric, and
"x" to indicate alphanumeric, the valid values for "seq" are:
"xx", "xa", "xn", "aa", "ax", "an", "nn", "na", and "nx". The
following table gives the range of each sequence with enough
intermediate values to indicate the pattern of the sequencing.
Seq Suffixes
xx AA ... AZ A0 ... A9 BA ... ZZ 0A ... 0Z 00 ... 99
xa AA ... AZ BA ... ZZ 0A ... 9Z
xn A0 ... A9 B0 ... Z9 00 ... 99
aa AA ... AZ BA ... ZZ
Section 3: Parameters 8
CMS Resource Allocation Package
ax AA ... AZ A0 ... A9 BA ... Z9
an A0 ... A9 B0 ... Z9
nn 00 ... 99
nx 0A ... 0Z 00 ... 09 1A ... 99
na 0A ... 0Z 1A ... 9Z
The number of possible combinations in each type of suffix is
as follows:
First Second Character
Character x a n
x 1296 936 360
a 936 676 260
n 360 260 100
Section 3: Parameters 9
CMS Resource Allocation Package
Section 4: Keywords
Some keywords are for student userids, some for grantor
userids, some for both, and some for neither. Following is a
summary of the keywords.
Grantor Student
Keywords Keywords Purpose of Keyword
Change Change Update one userid.
GDEFault DEFault Set defaults for parameters.
DELete DELete Delete one or more itemized userids.
DELGrp Delete a sequential group of student userids.
EXPIRE Delete student userids based on expiration date.
GROup Create a sequential group of student userids.
GList List List one or all userids.
GRantor New Create one new userid.
GREset Reset Update one userid.
The following keywords do not affect userids.
Keyword Purpose of Keyword
BRief Control displaying of records on terminal.
Help Access a RAP HELP file.
Quit End a keyword or a RAP session.
The minimum abbreviation for each keyword is capitalized in the
descriptions below. All parameter fields are free-format.
BRief <OFF ON>
Turns "brief output mode" on or off.
The default is OFF. When BRIEF is OFF, all new, updated,
listed, and deleted records are displayed on the terminal.
They are also written in the reader file.
When BRIEF is ON, no new, updated, or deleted record is
displayed on the terminal. Listed records are displayed on the
terminal. All of the records are written in the reader file.
To quit displaying records on the terminal, enter "BRIEF ON".
To start displaying records on the terminal, enter "BRIEF OFF".
Section 4: Keywords 10
CMS Resource Allocation Package
Change id <parmname value ...>
CHANGE updates the amount of one or more of a userid's
resources. (See also RESET and GRESET.)
Valid parmnames are: PAssword, DIsk, CONnect, CPU, EXPires.
At the present time, disk space cannot be changed.
The connect and CPU times may not be set to zero, or to less
than the amounts already used.
Example to add an hour and thirty minutes to the connect time
and to subtract $10.50 from the CPU allocation:
CHANGE XXX111AA CON +1:30 CPU -10.50
Example to change the connect time to 3 hours.
CHANGE XXX111AA CON 3
DEFault pw disk connect cpu expires
DEFAULT establishes defaults for student userids.
If a parameter is missing or specified as "*", then no default
value will be established for that parameter. If no default
has been established for a parameter and a new userid is to use
the defaults, RAP will ask for that parameter.
To turn off the student defaults, enter DEFAULT with no
parameters.
To query the current setting of the defaults, enter "DEFAULT
?".
Example to set defaults that generate random passwords.
DEFAULT ! 480 10:30 5.50 5/12/84
DELete id1 id2 id3 ...
DELETE deletes the userids listed.
A grantor userid with student userids cannot be deleted until
the student userids have been deleted. Only the grantor of the
student userids can delete its student userids.
If no userids are listed, DELETE will not prompt. It returns
to the keyword prompt.
Example to delete individual grantor and student userids.
Section 4: Keywords 11
CMS Resource Allocation Package
DELETE XXX115 XXX111AA XXX113 XXX111YZ
DELGrp id num <seq>
DELGRP deletes "num" sequential student userids using the
sequence type requested by "seq".
The first userid deleted will be "id". RAP will continue to
delete sequential student userids until "num" ids have been
deleted or the next sequential userid does not exist.
If "seq" is omitted, the sequence type is xx.
Example to delete 30 sequential student userids with alphabetic
suffixes.
DELGRP XXX111AA 30 AA
Example to delete 3 sequential student userids with the first
character of the suffix alphabetic and the second character
alphnumeric.
DELGRP XXX111AA 30 AX
EXPIRE
EXPIRE deletes student userids with expiration dates earlier
than the current date.
If no student userids are deleted, no records will be displayed
or punched to the reader file.
The expiration date for grantors is the end of the fiscal year
and they are automatically deleted at that time unless they are
renewed.
Example to delete expired student userids.
EXPIRE
GDEFault pw disk connect cpu
GDEFAULT establishes defaults for grantor userids. This is
similiar to DEFAULT which establishes defaults for student
userids.
If a field is omitted or specified as "*", then no default
value will be established for that parameter. If no default
has been established for a parameter and a new userid is to use
the defaults, RAP will ask for that parameter.
Section 4: Keywords 12
CMS Resource Allocation Package
To turn off the grantor defaults, enter GDEFAULT with no
parameters.
To query the current setting of the defaults, enter "GDEFAULT
?".
Example to set defaults that generate the same password for
every id.
GDEFAULT MMMM 15000 300 1000
GList <id>
GLIST lists information about the grantor "id".
If "id" is omitted, information about the logged on userid and
any sub-grantors will be listed. Omitting the parameter is
similiar to entering "List -ALL" except that GLIST lists
grantor userids instead of student userids.
GLIST always displays listed records on the terminal.
The resources are listed in columns across the screen in the
same relative positions as their corresponding parameters in
the keywords. The remaining connect and CPU times are listed
in columns to the right of the expiration date. The headings
for these columns are "REM-CON" and "REM-CPU".
Example to list logged on userid and all sub-grantors.
GLIST
GRantor id pw disk connect cpu
GRANTOR creates a new grantor userid.
Before using the GRANTOR keyword, the GDEFAULT keyword may be
used to set default values for fields that are specified as "*"
in the GRANTOR keyword.
The new userid will "belong" to the grantor creating it.
The resources allocated to a grantor may be used by the
grantor, or allocated to students or sub-grantors.
Example to create a new grantor with specific parameters.
GRANTOR XXX121 SOMETIME 300 12:00 17.83
Example to create a new grantor using preset GEDFAULTS.
GRANTOR XXX122 * * * *
Section 4: Keywords 13
CMS Resource Allocation Package
GREset id pw * connect cpu
GRESET updates the allocations for one or more of a grantors
resources. (See also CHANGE.)
An "*" holds the position of any parameter that is to remain
unchanged. At the present time, disk space cannot be changed
and its position is held with an "*".
The connect and CPU times may not be set to zero, or to less
than the amounts already used.
Example to add an hour and thirty minutes to the connect time
and to subtract $10.50 from the CPU allocation. The password
remains the same.
GRESET XXX110 * * +1:30 -10.50
Example to change the password and set connect to 3 hours.
GRESET XXX113 newpw * 3 *
GROup id num <seq>
GROUP creates "num" sequential student userids using the
sequence type specified by "seq".
The first userid created will be "id".
If a student userid in the sequence already exists, RAP will
end the GROUP keyword.
If "seq" is not specified, RAP will use the xx sequencing
pattern.
Before using the GROUP keyword, the DEFAULT keyword may be used
to set the amounts of the resources to be allocated to each
userid. If no defaults have been set, RAP will ask for each
parameter in the first userid and use the same parameters for
all of the remaining userids.
Example to create student userids XXX111BA through XXX111BC
with the default alphanumeric suffixes.
GROUP XXX111BA 3
Example to create student userids XXX11101 through XXX11130
with numeric suffixes.
GROUP XXX11101 30 NN
Section 4: Keywords 14
CMS Resource Allocation Package
Help
HELP displays information about the RAP keywords and
parameters.
List <id <num>> or List -ALL
LIST lists information about student userids.
If no parameter is specified, then information about the logged
on user will be listed.
If an id is specified, then information about that userid will
be listed.
If an id is followed by "num", then information about "num"
student userids will be listed. The first userid listed will be
"id".
If "num" student userids do not exist, RAP will end the LIST
keyword after the last existing student userid.
If -ALL is specified, then information will be listed for all
of the grantor's student userids.
LIST always displays listed records on the terminal.
The resources are listed in columns across the screen in the
same relative positions as their corresponding parameters in
the keywords. The remaining connect and CPU times are listed
in columns to the right of the expiration date. The headings
for these columns are "REM-CON" and "REM-CPU".
Example to list three student userids starting with XXX111BA.
LIST XXX111BA 3
New id pw disk connect cpu expires
NEW creates a new student userid.
Before using the NEW keyword, the DEFAULT keyword may be used
to set default values for fields that are specified as "*" in
the NEW keyword.
The new student userid will "belong" to the grantor creating
it.
A student userid cannot allocate its resources to any other
userid.
Section 4: Keywords 15
CMS Resource Allocation Package
Example to create a new student userid.
NEW ZZZ234A1 SECRET 50 5 6. 05/14/84
Quit
QUIT ends the RAP session.
Reset id pw * connect cpu expires
RESET updates the allocations for one or more of a students
resources. (See also CHANGE.)
An "*" holds the position of any parameter that is to remain
unchanged. At the present time, disk space cannot be changed
and its position is held with an "*".
The connect and CPU times may not be set to zero, or to less
than the amounts already used.
Example to subtract an hour from the connect time and to add
$5.00 to the CPU allocation. The other fields remain the same.
RESET XXX111AA * * -1 +5 *
Example to change the connect time to 3 hours.
RESET XXX111AA * * 3 * *
Section 4: Keywords 16
CMS Resource Allocation Package
Section 5: File Errors
In the process of creating CMS userids, RAP interacts with
several other programs. In some instances, one or more of these
programs will display a message on the terminal. These messages
are self explanatory and are not itemized in this manual.
In other instances, the programs produce a return code that RAP
analyzes to determine whether or not the requested action was
successful. RAP will display one of the following messages if it
is unsuccessful when trying to read or write a record on the
Userid file.
ACCESS DENIED id
The logged on userid is not authorized to manipulate the record
for "id".
RECORD NOT AVAILABLE, TRY LATER id
Some other program has exclusive control of the record for "id"
and RAP cannot manipulate it until the other program releases
control. Reenter the keyword at a later time.
RECORD ALREADY EXISTS id
RAP has tried to add a new userid record to the Userid file but
there is already a record on the file with the same "id".
RECORD NOT FOUND id
RAP has tried to read or delete a userid record that is not on
the Userid file.
CMS SERVER IS DOWN id
The program that places the "id" in the Userid file is not
operating at the present time. This error will cause RAP to
end the current session. The "id" was not written in the file.
Section 5: File Errors 17
CMS Resource Allocation Package
*** RAP FILE ERROR rc
"rc" is the error number. These types of errors cause RAP to
end the current RAP session. If the error persists, notify the
consultants at the Computing Center. Tell them that you were
using CMS RAP and give them your name, campus phone number, CMS
userid, "rc", location of terminal, date and time of the error,
and the keyword you were using when the error occurred.
Section 5: File Errors 18
CMS Resource Allocation Package
CONTENTS
Section 1. Introduction . . . . . . . . . . . . . . . . . . 1
Section 2. Commands . . . . . . . . . . . . . . . . . . . . 3
Section 3. Parameters . . . . . . . . . . . . . . . . . . . 4
Section 4. Keywords . . . . . . . . . . . . . . . . . . . . 10
Section 5. File Errors . . . . . . . . . . . . . . . . . . 17
Contents ii