PURGEWG



PURGEWG

     Purges the specified user-defined workgroup(s).  If no workgroup
     is specified, it executes all the deferred purgescans.

SYNTAX


PURGEWG [;PURGESCAN]

or

PURGEWG [WORKGROUP=] {workgrpspec }
{(workgrpspec [,workgrpspec ]...)}

[ [;ONERROR=] {CONTINUE} ]
{QUIT }

[ {;CONFIRM } ]
{;NOCONFIRM }
{;CONFIRMALL}

[ {;SHOWERRORS } ]
{;NOSHOWERRORS }

[ {;NOSHOW} ]
{;SHOW }

[ {;PURGESCAN } ]
{;NOPURGESCAN}

PARAMETERS


workgrpspec The user-defined workgroup(s) to be purged.
Wildcarding is allowed. This is a required
parameter. If "@" is specified, only the user-
defined workgroups are purged (the five system-
defined workgroups cannot be purged).

CONTINUE Allows PURGEWG to continue until the end of
the list is reached. CONTINUE is the default option.

QUIT Quits the execution of PURGEWG when it
encounters an error and sets the CIERROR
variable to the last execution error.

CONFIRM Requests the user to validate the purge. If
the user responds with "YES", the PURGEWG is
executed. This option only asks for verification
of the workgrpspec parameter. Valid responses are
"YES" or "NO". Pressing [Break] while being
prompted is equivalent to responding with a "NO".
CONFIRM is the default for sessions, unless the
workgrpspec is specified as a single workgroup.

NOCONFIRM The purge continues without verification from
the user. NOCONFIRM is the default for jobs or if
workgrpspec is specified as a single workgroup.

CONFIRMALL Requests verification for each workgroup
before the purge is executed. Proper response is:

"Y" or "YES" to purge the workgroup,

"N", "NO", or [Return] to retain the workgroup

"Q", "QUIT", or [Break] to stop the command

The CONFIRMALL option is ignored in jobs.

NOSHOW Suppresses the display of each successfully
purged workgroup. NOSHOW is the default.

SHOW Displays the name of each successfully purged
workgroup.

SHOWERRORS Displays each lower-level error which prevents a
workgroup from being deleted. The name of the
workgroup is shown, followed by the error
message. By default lower-level errors are not
displayed.

NOSHOWERRORS Suppresses the display of low-level errors.
NOSHOWERRORS is the default.

PURGESCAN The PURGESCAN option instructs the Workload
Manager to rescan processes belonging to
purge pending workgroups after executing the
PURGEWG command. This is the default action.

NOPURGESCAN The NOPURGESCAN option instructs the Workload
Manager to defer the rescan of processes belonging
to purge pending workgroups until it receives an
explicit request. To request a rescan, issue the
PURGEWG ;PURGESCAN command.

OPERATION

     The PURGEWG command is used to purge existing, user-defined
     workgroups. The command requires a workgrpspec which allows for
     an individual workgroup or a list of workgroups. In addition, the
     workgroup  name(s) may be wildcarded.   If "@" is specified, only
     the user-defined workgroups are purged; the five system-defined
     workgroups cannot be purged.

     The PURGEWG command handles user prompting through three
     options, CONFIRM, CONFIRMALL, and NOCONFIRM. The
     CONFIRM option requests verification of the PURGEWG command
     as a whole. That is, CONFIRM only asks for verification  of the
     workgrpspec parameter. The CONFIRMALL option provides user
     prompting for each workgroup. The NOCONFIRM option overrides
     all verification.

     Since the job environment does not support user prompting,
     the CONFIRM and CONFIRMALL options are ignored.

     By default the PURGEWG command does not display the name of
     each purged workgroup. However, this default can be overridden
     with the SHOW option.

     The ONERROR keyword provides a way for the user to specify how
     PURGEWG should respond after an error occurs while trying to
     purge an individual workgroup (for example, trying to purge a
     default workgroup, which is not allowed). The CONTINUE
     option continues the execution of the PURGEWG command until
     the end of the list is reached. QUIT,  quits the execution of
     PURGEWG where it encountered the error. When purging a list of
     workgroups one of three results can occur:

     o The purge succeeded on all workgroups. As a result, the CIERROR
       variable remains unchanged.

     o The purge failed on some of the workgroups. As a result, the
       CIERROR variable is set to the value CIWARN nnnn.

o The purge failed on all of the workgroups. As a result, the
CIERROR variable is set to the value CIERR nnnn.

When ONERROR=QUIT is specified, CIERROR is set to the
last error which stopped the execution.

In addition, the following variables are set only when a list of
workgroups is specified.

o HPNUMSELECTED: Contains the number of workgroups
selected. It contains the number of workgroups matched in the
workgrpspec unless the user responded "NO" to verification
prompts.

o HPNUMSUCCEEDED: Contains the number of workgroups
successfully purged.

o HPNUMFAILED: Contains the number of workgroups which did
not get purged.

When PURGEWG is discontinued before it reaches the end of the
list, the difference between HPNUMSELECTED and
HPNUMSUCCEEDED + HPNUMFAILED indicates the number of
workgroups which were selected, but did not have a purge tried
against them.

When a workgroup is purged, the Workload Manager needs to rescan
the affected member processes. The cost of such a rescan depends
upon the number of processes and workgroups involved. There
are situations in which the system manager may want to defer the
rescan. In terms of the workgroup, the system cannot complete the
purge until all member processes have found a new workgroup. A
workgroup in such a state is considered to have a purge pending.
The scan of processes assigned to purge-pending workgroups is a
subset of a system-wide scan. That is, a system-wide scan checks
every process on the system. A purge-pending scan only checks
processes that are assigned to purge-pending workgroups. While a
purge-pending scan is performed by default, the NOPURGESCAN
option allows the user to defer the rescan.

The CI supports a second syntax, which is used to explicitly
initiate a purge-pending scan without requiring the purging of a
workgroup.

PURGEWG [;PURGESCAN]

Logically, a workgroup in the purge-pending state no longer exists.
That is, the workgroup can not accept new members. However,
the workgroup physically exists until either its last member
has died or is moved to another workgroup, or if a scan is
performed. It is desirable to allow for the creation of a new
workgroup using the name of a purge-pending workgroup.
Therefore, when a workgroup goes into the purge-pending state,
the system renames the workgroup to the previous name prepended
with a "~". The last character may be truncated to keep the new
name to 255 characters. The SHOWWG command displays the workgroup
with its new name so that the user knows that the workgroup is in
the purge-pending state.

The purging of a user-defined workgroup will be deferred while a
scan (for example, system-wide or purge-pending) is in progress.

The PURGEWG command may be issued from a session, job,
program or in BREAK. Pressing [Break] aborts execution of this
command. PURGEWG requires System Supervisor (OP) or System
Manager (SM) capability.

WARNING

Misuse of the ability to defer a scan of processes assigned to purge-
pending workgroups could significantly impact system performance.

NOTE

PURGEWG @ will not attempt to purge the five default workgroups,
since they cannot be deleted.


EXAMPLE(S)

     To purge all user-defined workgroups, enter:

     PURGEWG @; noconfirm
     2 workgroups matched
     2 workgroups selected. 2 workgroups succeeded. 0 workgroups failed.
     :

     PURGEWG @; noconfirm; show
     2 workgroups matched
      User_WG1
      User_WG2
     2 workgroups selected. 2 workgroups succeeded. 0 workgroups failed.
     :

     To purge just the User_WG1 workgroup, enter:

     PURGEWG User_WG1
     1 workgroups matched
     1 workgroups selected. 1 workgroups succeeded. 0 workgroups failed.
     :

     To purge the User_WG1 and User_WG2 workgroups by specifying
     a list, enter:

     PURGEWG (User_WG1, User_WG2)
     2 workgroups matched
     CONTINUE PURGE ? (YES/NO) yes
     2 workgroups selected. 2 workgroups succeeded. 0 workgroups failed.
     :

     To purge the User_WG1 and User_WG2 workgroups by specifying
     a wildcard, enter:

     PURGEWG User_WG#
     2 workgroups matched
     CONTINUE PURGE ? (YES/NO) yes
     2 workgroups selected. 2 workgroups succeeded. 0 workgroups failed.
     :

     To purge the User_WG1 and User_WG2 workgroups and request
     confirmation, enter:

     PURGEWG User_WG#; confirmall
     2 workgroups matched
      User_WG1 ? (N/Y) Y
      User_WG2 ? (N/Y) Y
     2 workgroups selected. 2 workgroups succeeded. 0 workgroups failed.
     :

RELATED INFORMATION

Commands:   NEWWG, ALTWG, SHOWWG, TUNE, SHOWQ, ALTPROC, SHOWPROC

Manuals :   MPE/iX Intrinsics Reference Manual (32650-90028)
            Using the HP3000 Workload Manager (B3879-90001)