cwbUN_GetAdminValueEx

Purpose

This API returns an indication of whether the current user on the specified iSeries™ server is allowed or denied use of a specific administrable function. An Administrable function is any function whose use can be controlled through the Application Administration subcomponent of iSeries Navigator.

Note: iSeries Navigator plug-ins should use the cwbUN_GetAdminValue API instead of cwbUN_GetAdminValueEx.

For example, the Application Administration subcomponent allows an administrator to control whether a user can access several functions in iSeries Navigator. One of these functions is 'Job Management'. The cwbUN_GetAdminValueEx API can be used to programmatically determine if the current user can use the Job Management function by specifying the name of the Administrable function that corresponds to Job Management. See the CWBUNPLA.H header file for a list of Administrable function names that are supported in iSeries Navigator.

This API provides the same function as cwbUN_GetAdminValue, except that it is designed to accept a system object handle instead of a system name.

Syntax

CWBAPI unsigned int WINAPI cwbUN_GetAdminValueEx(
    cwbCO_SysHandle* pSysHandle,
    char*   adminFunction,
    cwbUN_Usage& usageValue);

Parameters

cwbCO_SysHandle* pSysHandle

A pointer to a system object handle. The system name must be specified in the system object prior to calling this API. The cwbUN_GetAdminValueEx API's behavior is based on whether the system object has obtained a signon to the iSeries server:

Not Signed On->: cwbUN_GetAdminValueEx will signon to the iSeries server. The latest Application Administration settings for the user will be downloaded from the iSeries server if they are not already cached on the client PC.
Signed On->: If the system object was signed on to the iSeries server specifying that the iSeries userID and password should be validated (Validate Mode), then the cwbUN_GetAdminValueEx API will be using a snapshot of Application Administration settings that were accurate at the time the signon was completed. If the signon was done without validating the userID and password, then it is possible that cwbUN_GetAdminValueEx will use a copy of the Application Administration settings that may be as much as 24 hours old.

char* adminFunction

A pointer to an ASCII string that contains the name of the Administrable function. The string must be null terminated and has a maximum length of 30 bytes + 1 byte for the NULL terminator. See CWBUNPLA.H for a list of supported input values.

cwbUN_Usage& usageValue

This value is only valid if the return code of CWB_OK is returned. One of two values will be returned:

cwbUN_granted: User is allowed use of the function.
cwbUN_denied: User is denied use of the function.

Return Codes

The following list shows common return values:

CWB_OK: The API was successful.
CWBSY_USER_CANCELLED: The user cancelled the user ID and password prompt presented by the API.

Usage

This API determines if the current iSeries user (as defined by the input system object) is allowed to use the specified function. If no user is currently signed on to the specified iSeries server, the API will sign the user on, possibly displaying a user ID and password prompt.

This API can only be used to check Administrable functions that are in the iSeries Navigator or the Client Applications function category.