wlm_key2class Subroutine

Purpose

Retrieves a class name from a key.

Library

Workload Manager Library (libwlm.a)

Syntax

#include <sys/wlm.h

int wlm_key2class ( struct wlm_args *args, wlm_key_t key, void *ctx)

Description

The wlm_key2class subroutine retrieves a class name from a 64-bit key calculated using the wlm_class2key subroutine. The key-to-class translation is made by going through the WLM configuration files for the configuration named in the wlm_args structure pointed to by args (or all the WLM configuration files, if no configuration name is given), and translating all the class names to a 64-bit key until the matching key is found.

This process is time consuming and WLM offers the subroutines wlm_initkey and wlm_endkey for applications needing to translate several 64-bit keys back to class names. These subroutines can be used in conjunction with the wlm_key2class subroutine to speed up searches.

The wlm_initkey subroutine allocates a block of memory, calculates the keys corresponding to the class names in the configuration(s) in scope, stores the names with the corresponding keys in the memory buffer, and returns its address. This address is passed to the wlm_key2class subroutine using the ctx argument, so that wlm_key2class only needs to search through the memory buffer.

After all keys have been translated into class names, the application must call wlm_endkey to free the memory buffer. Alternatively, for an application translating only one key, it is possible to call wlm_key2class directly using a null pointer in the ctx argument. This causes the wlm_key2class subroutine to internally call wlm_initkey and wlm_endkey.

The method of retrieving class names through the WLM configuration files implies that if a class has been deleted between the time the class name was converted into a key and the call to the wlm_key2class subroutine, the name corresponding to the key will not be found and the wlm_key2class subroutine returns an error.

Parameters

Item Description
- args A pointer to a wlm_args structure:
  • confdir field needs to be initialized as described in wlm_initkey if wlm_initkey has not been previously invoked (ctx == NULL). Otherwise, the confdir field is ignored.
  • versflags field needs to be initialized with WLM_VERSION and optionally WLM_MUTE.
- ctx The context handler returned by wlm_initkey, or a NULL pointer otherwise. .
- key The search key.

Return Values

When the wlm_key2class operation is successful, the first class name matching the value of the key is returned in the name sub-field of the wlm_args structure pointed to by args.

Error Codes

If the wlm_key2class subroutine is unsuccessful, one of the following error codes is returned:

Item Description
WLM_BADVERS Bad version number.
WLM_NOT_INITED Missing call to wlm_init.
WLM_NOMEM Not enough memory.
WLM_NOCLASS No class matching the key was found.
WLM_EFAULT Invalid ctx or args argument.