wlm_assign Subroutine

Purpose

Manually assigns processes to a class or cancels prior manual assignments for processes.

Library

Workload Manager Library (libwlm.a)

Syntax

#include <sys/wlm.h>

int wlm_assign ( args)

struct wlm_assign *args;

Description

The wlm_assign subroutine:

The target processes are identified by their process ID (pid) or by their process group ID (pgid). The wlm_assign subroutine allows specifying processes using a list of pids, a list of pgids, or both.

The name of a valid superclass or subclass must be specified to manually assign the target processes to a class. If the target class is a superclass, each process is assigned to one of the subclasses of the specified superclass according to the assignment rules for the subclasses of this superclass.

A manual assignment remains in effect (and a process remains in its manually assigned class) until:

The name of a valid superclass or subclass must be specified to manually assign the target processes to a class. The assignment can be done or canceled at the superclass level, the subclass level, or both. The interactions between automatic assignment, inheritance and manual assignment are detailed in the Manual class assignment in Workload Manager in AIX® Version 7.1 Operating system and device management.

Flags in the wa_versflags field described below are used to specify if the requested operation is an assignment or cancellation and at which level.

To assign a process to a class or cancel a prior manual assignment, the caller must have authority both on the process and on the target class. These constraints translate into the following:

This defines three levels of privilege among the persons who can manually assign processes to classes, root being the highest. For a user to modify or terminate a manual assignment, the user must be at the same level of privilege as the person who issued the last manual assignment, or higher.

Note: The wlm_assign subroutine works with the in-core WLM data structures. Even if the WLM current configuration is a set, it applies to the currently loaded regular configuration. If an assignment is made to a class that does not exist in all configurations of the set, it will be lost when the first configuration that does not contain this class is activated (when the class is deleted).

Parameter

Item Description
args Specifies the address of the struct wlm_assign data structure containing the parameters for the desired class assignment.

The following fields of the wlm_args structure and the embedded substructures can be provided:

Item Description
wa_versflags Needs to be initialized with WLM_VERSION. The flags values available, defined in the sys/wlm.h header file, are:
  • WLM_ASSIGN_SUPER
  • WLM_ASSIGN_SUB
  • WLM_ASSIGN_BOTH
  • WLM_UNASSIGN_SUPER
  • WLM_UNASSIGN_SUB
  • WLM_UNASSIGN_BOTH
wa_pids Specifies the address of the array containing the process IDs of processes to be manually assigned. When this list is empty, a NULL pointer can be passed together with a count of zero (0).
wa_pid_count Specifies the number of PIDS in the above array. Could be zero (0) if using only pgids to identify the processes.
wa_pgids Specifies the address of the array containing the process group identifiers (pids) of processes to be manually assigned. When this list is empty, a NULL pointer can be passed together with a count of zero (0).
wa_pgid_count Specifies the number of PGIDs in the above array. Could be zero (0) if using only pids to identify the processes. If both pids and pgids counts are zero (0), no process is assigned, but the operation is considered successful.
wa_classname Specifies the full name of the superclass (super_name) or the subclass (super_name.sub_name) of the class you want to manually assign processes to. The class name field is ignored when canceling an existing manual assignment.

Return Values

Upon successful completion, the wlm_assign subroutine returns a value of 0. If the wlm_assign subroutine is unsuccessful, a non-0 value is returned. The routine is considered successful if some of the target processes are not found, (to account for process terminations) or are not assigned/deassigned due to a lack of privileges, for instance. If none of the processes in the lists can be assigned/deassigned, this is considered an error.

Error Codes

For a list of the possible error codes returned by the WLM API functions, see the description of the wlm.h header file.