Generated from C.65.00 /SYSADMIN/PUB/MYCICAT last modified on Sun Aug 29 15:08:37 2004
Creates a new, user-defined workgroup, either directly,
via command line input, or indirectly, through a file. (NM)
NOTE: THIS COMMAND IS AVAILABLE ONLY TO CUSTOMERS WHO HAVE
PURCHASED THE HP 3000 WORKLOAD MANAGER (PRODUCT # B3879AA).
NEWWG ^filename [;VALIDATE]
or
NEWWG [WORKGROUP=] workgrp
[;MEMB_LOGON=] logon
[;MEMB_PROGRAM=] program_file
[;MEMB_QUEUE=] queue_attribute
[;BASE=] base
[;LIMIT=] limit
[ [;MINQUANT=] min]
[ [;MAXQUANT=] max]
[ [;BOOST= {DECAY } ]
{OSCILLATE}
[ [;TIMESLICE=] tslice]
[ [;MINCPUPCT=] minpercent]
[ [;MAXCPUPCT=] maxpercent]
[ [;POSITION=] existingwg]
Misuse of this command can significantly degrade system operating efficiency.
Use the first parameter and option described below (filename and
VALIDATE) when you invoke the NEWWG command to specify an indirect
file. Use the remaining parameters to enter new workgroup information
at the command line.
filename The name of the indirect file which contains
workgroup specifications. The file name must
be preceded with the "^" (caret) character.
When you specify an indirect file, the current
user-defined workgroup configuration is replaced
with the valid workgroup specification in the file.
This action is atomic: either all workgroups
are created or, if there were syntax errors,
none are created. A system-wide scan is done
after all workgroups are created to determine
workgroup membership for all processes on the
system.
Note that this is an indirect file, and not
a command file. A command file would have
a NEWWG command for each workgroup and a
system-wide scan would be done after each
workgroup creation. Creation would not be atomic.
Refer to the File Format section for a description
of the parameters valid for use within the indirect
file. They include all of the parameters valid for
the command-line specification except POSITION
since POSITION is actually the workgroup's position
within the indirect file.
VALIDATE Specify the VALIDATE option to check the indirect
file for the correct syntax and see the errors.
No workgroup replacement occurs. This option lets
you ensure that when you subsequently issue the
NEWWG command specifying this indirect file, the
operation will not fail due to syntax errors.
NEWWG allows positional parameters until you
specify the first high-level keyword.
workgrp The name of the workgroup you are creating.
This is a required parameter.
The workgroup name follows the convention for CI
variables and Job Control Words (JCWs) and can
be a maximum of 255 alphanumeric characters or
underscores, where the first character cannot
be numeric or an underscore. The user-specified
name (including case) is preserved, though
comparisons are case-insensitive. All 255
characters are significant.
The following names, expressed in any case (all
upper, all lower, or mixed), are unavailable:
AS_Default, BS_Default, CS_Default, DS_Default,
ES_Default, and Natural_wg.
The following parameters for logon, program file and queue attribute
constitute the membership criteria for the workgroup. You must specify
at least one membership criterion. You may enter multiple
specifications, using commas as delimiters. A parameter that you
do not specify is assumed to be a match.
OR is used between values within each parameter and, AND is used across
specified parameters. That is, a process must match one of the
specifications for each of the specified parameters. Membership
conflicts are resolved by assigning the process to the first matching
workgroup defined. That is, a first-fit algorithm is used. Once a
match is found no further workgroups are considered.
logon Specifies the job/session, user, and account
name of potential workgroup members. The
job/session name is optional, but if specified,
it must be enclosed in double quotes (" "). The
user and account name are required. Wildcarding
is supported. The format is shown below:
MEMB_LOGON = (logonname [,logonname]...)
Where logonname is:
"job/session name, username.acctname"
or
username.acctname
program_file Specifies the program files of potential
workgroup members. The program_file must
be a fully qualified MPE/iX file name or absolute
Hierarchical File System (HFS) file name. However,
wildcarding is supported. The format is shown
below:
MEMB_PROGRAM = (program_file [,program_file]..)
Note that for HFS file names, comparison is
case-sensitive. Thus, if the file exists in the
MPE name space, you must specify it in upper
case, for example, /SYS/PUB/WMTEST instead of
/sys/pub/wmtest.
queue_attribute Specifies the traditional queue attribute.
This parameter is provided for compatibility.
It enables the system manager to collect processes
into workgroups without having to change their
existing logon priority or job card. Any current
specification or alteration of the queue
(via HELLO, JOB, LINK, ALTPROC, AIFPROCPUT,
GETPRIORITY) will continue to set the queue
attribute, but this attribute can be used to
determine the workgroup membership of the process.
As new job streams or tasks are created, avoid
specifying the scheduling queue and allow
workgroup membership to be determined by the
other categories such as MEMB_LOGON and
MEMB_PROGRAM.
You can enter the following values for
queue_attribute: AS, BS, CS, DS, and ES.
MEMB_QUEUE = (queue_attribute [,queue_attribute]..)
base An integer specifying the highest priority
at which processes executing in the specified
workgroup begin their Dispatcher transactions.
The base is a required scheduling characteristic.
limit An integer specifying the lowest priority which
processes executing in the specified workgroup
can attain. The limit must be greater than or
equal to the base. The limit is a required
scheduling characteristic.
Priority is inversely related to the integer
number (for base and limit). A higher priority
process has a lower numeric priority. The priority
values for base and limit may range from 150 to 255.
While the full range is provided for compatibility,
it is recommended that the base priority not exceed
152. User processes running at priorities greater
than 152 can adversely affect system performance.
min The minimum number of milliseconds that a process
may use the CPU before its priority is reduced.
The min is a lower bound for the quantum value.
The quantum value determines the rate of priority
decay for processes within the workgroup. Values
range between 1 and 32767. The minimum quantum is
an optional scheduling characteristics with a
default value of 1 millisecond.
max The maximum number of milliseconds that a
process may use the CPU before its priority
is reduced. The max is an upper bound for the
quantum value. The quantum value determines
the rate of priority decay for processes within
the workgroup. The value of max must be greater
than or equal to the value of min. Again, values
range between 1 and 32767. The maximum quantum is
an optional scheduling characteristics with a
default value of 2000 milliseconds.
DECAY Indicates if the workgroup is to demonstrate the
default decay behavior associated with circular
queues. If set, a process will decay normally
to the limit priority and will return to the
base priority when the Dispatcher transaction is
completed. The boost property is an optional
scheduling characteristic with a default value of
DECAY.
OSCILLATE Indicates if the workgroup is to demonstrate
oscillation. If set, a process will be placed
back to the base priority once its priority has
decayed to the limit priority, even if it has
not completed a Dispatcher transaction.
tslice The maximum number of milliseconds a process in the
workgroup can hold a CPU before returning to the
Scheduler to have its priority recalculated. Values
must be multiples of 100, with a minimum value of
100 and a maximum value of 32700. The timeslice is
an optional scheduling characteristic with a
default value of 200 milliseconds.
minpercent Indicates the minimum percent of time which
the CPU will be made available to the workgroup's
member processes. Within the target workgroup,
this CPU time is allocated according to the
processes' priorities. The workgroup is guaranteed
this minimum percentage of time even if higher-
priority processes in other workgroups are ready to
run.
If the processes in the workgroup do not require as
much CPU time as their guaranteed minimum, that time
will be available to processes in other workgroups.
The default value for this optional workgroup
characteristic is that the workgroup is not
guaranteed any minimum CPU percent and that CPU
allocation is based on process priority only.
maxpercent Indicates the maximum percent of time which the CPU
will be made available to the workgroup's member
processes. The workgroup will be limited to this
maximum percentage of time even no other process in
another workgroup is ready to run. In other words,
a workgroup will be limited to this maximum
percentage of time even if the system must
remain idle for the remainder of the time.
The default value for this optional workgroup
characteristic is that there is no maximum which
would prevent a workgroup's processes from getting
the CPU time their priorities warrant.
existingwg The POSITION parameter, existingwg, indicates where
the new workgroup should be positioned within the
set of existing, user-defined workgroups. (Recall
that workgroups are maintained in an ordered file.)
The existingwg value is the name of an existing,
user-defined workgroup. The new workgroup will be
inserted before the existing workgroup. The
POSITION specification is optional. If omitted,
the new workgroup is appended to the list of
existing user-defined workgroups.
You may want to define workgroups with "dummy" membership criteria that would never match process attributes. Such workgroups will not have natural members, but can be used as the target of an ALTPROC;WG= command. Such workgroups should be placed after all user-defined workgroups to minimize the number of workgroups that must be scanned to determine process workgroup membership.
The NEWWG command will accept an indirect file as input. This
file should be an ASCII file (for example, the file may be
temporary or permanent and have fixed or variable length records).
The file will contain the specifications for creating user-defined
workgroups. The current workgroup configuration will be replaced
by the workgroup configuration given in the indirect file.
Workgroup creation will not begin until all specifications
within the file have passed a syntax check. Furthermore, the system
will consider the creation an atomic operation (for example,
either all workgroups within the file will be created or none).
A system-wide scan will be performed once all workgroups are
created to determine process workgroup membership.
The specification for an individual workgroup is given below.
The parameters shown match those described when using the
command line. The POSITION parameter is not valid within the
indirect file. A workgroup's position in the list of workgroups
is determined by the position within the file.
Workgroup = workgrp
;Memb_Logon = (logon)
;Memb_Program = (program_file)
;Memb_Queue = (queue_attribute)
;Base = base
;Limit = limit
;MinQuant = min
;MaxQuant = max
;Boost = {DECAY | OSCILLATE}
;Timeslice = tslice
;Mincpupct = minpercent
;Maxcpupct = maxpercent
Multiple specifications are permitted within a particular
membership category (with commas as delimiters), and each
category need not be specified (unspecified categories are
assumed matches). A minimum of one category is required.
For example, if the only specification given were QUEUE=(CS),
the workgroup will capture all processes with the CS queue
attribute (with any logon, running any program). Since only
the QUEUE category has been specified, the other categories
are assumed matches. An "&" or [Return] may be used to indicate
the continuation of a specification onto a new line.
Only BASE and LIMIT are required scheduling parameters. The
others are optional and will be set to default values unless
explicitly changed.
The example above shows each parameter on a new line. However,
the entire workgroup specification may reside in one physical
record. The only restriction is that you may not have two
workgroup specifications in the same physical record.
Specifications may be "commented out" by using the COMMENT
keyword, as shown below. Characters appearing on the same line
and after the COMMENT keyword will be ignored.
COMMENT Workgroup = Old_Finance_WG
COMMENT ;Memb_Logon = @.TEST
COMMENT ;Memb_Program = EDITOR.PUB.SYS
COMMENT ;Memb_Queue = ES
COMMENT ;Base = 200
COMMENT ;Limit = 230
COMMENT ;MinQuant = 200
COMMENT ;MaxQuant = 1000
COMMENT ;Boost = DECAY
COMMENT ;Timeslice = 400
COMMENT ;Mincpupct = 20
COMMENT ;Maxcpupct = 30
Before you invoke the NEWWG command and specify an indirect file to
replace workgroups, you may want to use the SHOWWG command and redirect
the output to create an ASCII file that describes the existing
configuration. For example, to create an ASCII file named "currentwg"
enter:
SHOWWG @; format=wgfile > currentwg
SAVE currentwg
Substitute a file name of your own choosing, and make certain that it
is unique.
The system manager creates workgroups to reflect a partitioning
of the system workload and control the allocation of the CPU(s)
to user processes on the system. There is no hard limit to
the maximum number of workgroups that a system may have. The
system will always be configured with five default workgroups.
The default workgroups exist to support system processes, and to
provide backward compatibility.
Each workgroup consists of three components, a name, membership
criteria, and scheduling characteristics. The membership criteria
(the MEMB_LOGON, MEMB_PROGRAM and MEMB_QUEUE parameters), determine
process assignment. Workgroup assignment is made at each process
create, whenever one of the process attributes on which membership
can be based is changed, and when workgroups are purged or new
workgroups are created. Membership conflicts are resolved by
keeping the workgroups in an ordered list. A process will be
assigned to the first workgroup whose membership criteria is
matched. That is, a first-fit algorithm is used. Once a match
is found, no other workgroups are considered. Therefore, it is
appropriate to order your workgroup specifications from those
with the most precise membership criteria, to those with more
general membership criteria.
The scheduling characteristics define the scheduling policies which
govern processes within the workgroup. The MPE/iX Dispatcher is
priority-driven, giving a CPU to the highest priority process that
is ready to run. Each workgroup has a base and a limit,
defining the priority range for processes within that workgroup.
Processes will begin their Dispatcher transactions at the base
priority and decay towards the limit priority as they consume
system resources. The process priority will never drop below the
limit of the workgroup. If the boost property of the workgroup
is set to oscillate, the process priority will be reset to the
base priority when it decays to the limit priority.
Processes completing Dispatcher transactions (typically via a
terminal read) are reset to the base priority.
Each of the five default workgroups represents one of the five
scheduling queues, AS, BS, CS, DS, and ES. A default workgroup
has a specific queue's scheduling policies and specifies that
scheduling queue as its only membership criteria. By defining
the default workgroups as the last five workgroups in the
ordered list, the Scheduler can guarantee that all processes
will be assigned to a workgroup.
The user-defined workgroups can control all user processes.
System processes, however, are placed in one of the five default
workgroups and handled appropriately by the Scheduler. A user
can customize the workgroup characteristics to reflect the CPU
scheduling needs of the various components of the system workload.
The SHOWWG command offers a format option, WGFILE, whose output
has a format suitable as input to NEWWG. You may use CI I/O
redirection to place the output from SHOWWG into a file. For
example, SHOWWG @;FORMAT=WGFILE > filename, and then issue the
SAVE command to save it.
Creation of a new workgroup can affect the workgroup assignment
of existing processes. As a result, the Scheduler will need to scan
all processes on the system and adjust their workgroup membership
as necessary. This is referred to as a system-wide scan. For
first release, system-wide scans are performed after each NEWWG
command. Therefore, an indirect file provides a performance
advantage by allowing the definition of multiple workgroups with
a single system-wide scan (once all workgroups are created).
The NEWWG command may be issued from a session, job, program or
in BREAK. Pressing [Break] has no effect on this command.
NEWWG requires System Supervisor (OP) or System Manager (SM)
capability.
The following default settings are established when the system is
booted from the system disk (a START RECOVERY or START NORECOVERY)
unless the user has customized a workgroup configuration.
Setting ||AS_Default||BS_Default ||CS_Default||DS_Default||ES_Default
= base || 13 || 100 || 152 || 202 || 240
= limit || 99 || 150 || 200 || 238 || 253
= min || N/A || N/A || 1 || 2000 || 2000
= max || N/A || N/A || 2000 || 2000 || 2000
= boost || N/A || N/A || DECAY || DECAY || DECAY
= tslice || 1000 || 1000 || 200 || 200 || 200
=mincpupct || N/A || N/A || N/A || N/A || N/A
=maxcpupct || N/A || N/A || N/A || N/A || N/A
Processes within the workgroup are not constrained to have their priorities fall within the specified base and limit values. N/A refers to the fact that the scheduling characteristic is Not Applicable for the system-defined workgroup. For example, processes within the AS_Default or BS_Default workgroup (usually system processes) do not experience decay. Therefore, these workgroups do not support the concept of a quantum or boost priority. Also, CPU percentages are not available for the default workgroups; they apply only to user-defined workgroups.
The following example creates a user-defined workgroup named
Program_Development:
NEWWG Program_Development; memb_program= (editor.pub.sys,&
qedit.@.@, hpedit.@.@);memb_logon=("nm@,@.mytest")]; base= 160;&
limit= 170; boost= oscillate
or (using positional parameters),
NEWWG Program_Development,memb_program=(editor.pub.sys,&
qedit.@.@, hpedit.@.@);memb_logon=("nm@,@.mytest")],160,&
170,,,oscillate
This workgroup has a base priority of 160, a limit of 170, the
default minimum and maximum quantum of 1 and 2000 milliseconds,
has an oscillating boost property, and the default timeslice of
200 milliseconds. The membership criteria requires a program of
editor.pub.sys or qedit.@.@ or hpedit.@.@, AND a logon equal
to nm@,@.mytest. This workgroup will be appended to the end of
the user-defined workgroups.
To create a second workgroup, ahead of the workgroup in the
previous example, enter:
NEWWG Program_Test; memb_logon= (@.test); base= 175;&
limit= 190; boost= oscillate; position= Program_Development
or (using positional parameters),
NEWWG Program_test,memb_logon=(@.test),175,190,,oscillate,,&
Program_Development
This workgroup has a base priority of 175, a limit of 190, the
default minimum and maximum quantum of 1 and 2000 milliseconds,
has an oscillating boost property, and the default of 300
milliseconds. The membership criteria requires a logon equal
to @.test.
To validate the indirect file named spec1.workgrp.system for
correctness, enter:
NEWWG ^spec1.workgrp.system; validate
To have NEWWG replace the current workgroup configuration with
the workgroups specified in spec1.workgrp.system, enter:
NEWWG ^spec1.workgrp.system
Commands: SHOWPROC, TUNE, SHOWQ, NEWWG, ALTWG, PURGEWG, SHOWWG
Manuals : MPE/iX Intrinsics Reference Manual (32650-90028)
Using the HP3000 Workload Manager (B3879-90001)
Back to Main Index