| 1 | Continuation handle | Input | Char(20) |
| 2 | Receiver variable | Output | Char(*) |
| 3 | Length of receiver variable | Input | Binary(4) |
| 4 | Format name | Input | Char(8) |
| 5 | User profile name | Input | Char(10) |
| 6 | Function selection criteria | Input | Char(*) |
| 7 | Desired CCSID | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
#include <qsyfnusg.h>
void QsyRetrieveUserFunctionInfo
(char Continuation_handle[20],
void *Receiver_variable,
int *Length_of_receiver_variable,
char Format_name[8],
char User_profile_name[10],
Qsy_Selcrtr_T *Function_selection_criteria,
int *Desired_CCSID,
void *Error_code);
Service Program: QSYFNUSGThe Retrieve User Function Information (OPM, QSYRTUFI; ILE, QsyRetrieveUserFunctionInfo) API retrieves usage settings for a specified user profile for one or more functions.
The value returned to the user in the receiver variable when only partial exit information is returned. This parameter must be set to blanks on the first call to this API. This parameter is used when more information is available to return than what could fit in the receiver variable. When you specify a continuation handle for this parameter, all other parameters must have the same values as the call to the API that generated the continuation handle. Failure to do so may result in incomplete or inaccurate information.
Entries are only returned in their entirety; the API never returns anything less. If there is not enough space for the entire entry, the continuation handle is set to something other than blanks.
The variable that is to receive the usage information requested.
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.
The format of the usage information to be returned.
You must use one of the following format names:
| UFNI0100 | User function usage information |
| UFNI0200 | The same information as UFNI0100, plus an indicator of where the user's usage setting comes from, the function name information, the function group ID, and the function product ID. |
| UFNI0300 | The same information as UFNI0200, plus additional indicators of where the user's usage setting and source come from if the *ALLOBJ authority is ignored, and where the user's usage setting and source come from if the *ALLOBJ and specific usage setting are ignored. |
The name of the user profile to retrieve function usage information for.
You may specify the following special value.
| *CURRENT | The usage information for the user currently running is returned. |
The selection criteria to be used when selecting which functions to return usage information for. No CCSID normalization is performed. It is recommended that you use characters from the invariant character set for the comparison data.
The information must be in the following format:
| Number of selection criteria | BINARY(4) The total number of selection criteria. Specify 0 if no selection criteria are specified. If 0 is specified, usage information for all registered functions will be returned. The maximum value for this field is 1. |
| Selection criteria array | CHAR(*) The selection criteria. Refer to Format for Function Selection Criteria for more information. |
The CCSID that the returned text fields should be converted to. The text fields will be returned in this CCSID even if data loss occurs. If you want to ensure that data loss does not occur, you may specify 65535 or 13488 (UCS-2).
The following can be specified for the desired CCSID:
| 0 | The text fields are converted to the default CCSID for the job. |
| CCSID | The text fields are converted to the specified CCSID. The CCSID value must be from 1 to 65535. If 65535 is specified, then no CCSID conversion is done on the text. |
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following information is returned for the UFNI0100 format. This format provides function usage information for a user profile. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(20) | Continuation handle |
| 28 | 1C | BINARY(4) | Offset to first function entry |
| 32 | 20 | BINARY(4) | Number of function entries returned |
| 36 | 24 | BINARY(4) | Length of function entry |
| 40 | 28 | CHAR(*) | Reserved |
| Function entry information. These fields are repeated for each function entry returned. | |||
| CHAR(30) | Function ID | ||
| CHAR(1) | Usage indicator | ||
| CHAR(*) | Reserved | ||
The following information is returned for the UFNI0200 format. This format provides function usage information for a user profile, plus the usage source indicator, function name information, function group ID, and function product ID. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(20) | Continuation handle |
| 28 | 1C | BINARY(4) | Offset to first function entry |
| 32 | 20 | BINARY(4) | Number of function entries returned |
| 36 | 24 | BINARY(4) | Length of function entry |
| 40 | 28 | CHAR(*) | Reserved |
| Function entry information. These fields are repeated for each function entry returned. | |||
| CHAR(30) | Function ID | ||
| CHAR(1) | Usage indicator | ||
| CHAR(1) | Usage source | ||
| CHAR(10) | Function-name message-file name | ||
| CHAR(10) | Function-name message-file library name | ||
| CHAR(7) | Function-name message ID | ||
| CHAR(330) | Function-name message text | ||
| CHAR(3) | Reserved | ||
| BINARY(4) | Function-name message-text CCSID | ||
| CHAR(330) | Function name | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Function name CCSID | ||
| CHAR(30) | Function product ID | ||
| CHAR(30) | Function group ID | ||
| CHAR(*) | Reserved | ||
The following information is returned for the UFNI0300 format. This format returns the same information as format UFNI0200, plus where the user's usage setting and usage source come from if the *ALLOBJ authority is ignored, and where the user's usage setting and usage source come from if the *ALLOBJ authority and specific usage setting are ignored. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(20) | Continuation handle |
| 28 | 1C | BINARY(4) | Offset to first function entry |
| 32 | 20 | BINARY(4) | Number of function entries returned |
| 36 | 24 | BINARY(4) | Length of function entry |
| 40 | 28 | CHAR(*) | Reserved |
| Function entry information. These fields are repeated for each function entry returned. | |||
| CHAR(30) | Function ID | ||
| CHAR(1) | Usage indicator | ||
| CHAR(1) | Usage source | ||
| CHAR(10) | Function-name message-file name | ||
| CHAR(10) | Function-name message-file library name | ||
| CHAR(7) | Function-name message ID | ||
| CHAR(330) | Function-name message text | ||
| CHAR(3) | Reserved | ||
| BINARY(4) | Function-name message-text CCSID | ||
| CHAR(330) | Function name | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Function name CCSID | ||
| CHAR(30) | Function product ID | ||
| CHAR(30) | Function group ID | ||
| CHAR(1) | Usage indicator ignoring *ALLOBJ | ||
| CHAR(1) | Usage source ignoring *ALLOBJ | ||
| CHAR(1) | Usage indicator ignoring *ALLOBJ and ignoring specific usage setting | ||
| CHAR(1) | Usage source ignoring *ALLOBJ and ignoring specific usage setting | ||
| CHAR(*) | Reserved | ||
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
If the continuation handle is set to a value other than blanks, this field contains an approximation of the total bytes available. At a minimum, this field contains the actual number of bytes available.
Bytes returned. The number of bytes of data returned.
Continuation handle. The handle that is returned when more data is available to return, but the receiver variable is not large enough. The handle indicates the point in the repository that the retrieval stopped. If the handle is used on the next call to the API, the API returns more data starting at the point that the handle indicates. This field is set to blanks when all information is returned.
Function group ID. The ID of the function group that the function is grouped with. If the function is not grouped with a function group, this field is set to *NONE.
Function ID. The ID of the function.
Function name. The text for the function name. This value is converted to the CCSID value specified in the desired CCSID parameter.
Function name CCSID. The CCSID value that is associated with the function name in the function registration facility.
Function-name message-file name. The name of the message file that contains the function name. If no message file name is specified, this field contains blanks.
Function-name message-file library name. The name of the library in which the function name message file resides. If no message file name is specified, this field contains blanks.
Function-name message ID. The message identifier for the function name. If no message file name is specified, this field contains blanks.
Function-name message text. The first-level text for the function-name message ID. This value is converted to the CCSID value specified in the desired CCSID parameter.
When the message text is retrieved from the message file, the message file library is added to the product portion of the library list, and *LIBL is specified for the library name. If the library cannot be added to the product portion of the library list, then *LIBL is still used to search for the message. If the message is not found, then the message file library is searched for the message.
If no message file name is specified, this field contains blanks.
Function-name message-text CCSID. The CCSID value that the function-name message text is stored in.
Function product ID. The ID of the product that the function is registered for.
Length of function entry. The length of a function entry that is returned. This value should be used in determining the displacement to the next function entry.
Number of function entries returned. The number of function entries returned. If the receiver variable is not large enough to hold all of the information, this number contains only the number of function entries actually returned.
Offset to first function entry. The offset to the first function entry returned. The offset is from the beginning of the structure. If no entries are returned, the offset is set to zero.
Reserved. An ignored field.
Usage indicator. Whether the user is allowed to use the function.
This parameter contains one of the following values:
| 1 | The user is not allowed to use the function. |
| 2 | The user is allowed to use the function. |
Usage indicator ignoring *ALLOBJ. Whether the user is allowed to use the function if this API ignores the *ALLOBJ authority.
This parameter contains one of the following values:
| 1 | The user is not allowed to use the function. |
| 2 | The user is allowed to use the function. |
Usage indicator ignoring *ALLOBJ and ignoring specific usage setting. Whether the user is allowed to use the function if this API ignores the *ALLOBJ authority and his specific usage setting.
This parameter contains one of the following values:
| 1 | The user is not allowed to use the function. |
| 2 | The user is allowed to use the function. |
Usage source. An indicator as to why the user is allowed or is not allowed to use the function.
This parameter contains one of the following values:
| 1 | The user has *ALLOBJ special authority. |
| 2 | The user has a specific usage setting for the function. |
| 3 | One of the user's groups has *ALLOBJ special authority. |
| 4 | One of the user's groups has a specific usage setting for the function. |
| 5 | The default usage setting for the function was used. |
| 9 | The usage source could not be determined. |
Usage source ignoring *ALLOBJ. An indicator as to why the user is allowed or is not allowed to use the function if this API ignores the *ALLOBJ authority.
This parameter contains one of the following values:
| 2 | The user has a specific usage setting for the function. |
| 3 | One of the user's groups has *ALLOBJ special authority. |
| 4 | One of the user's groups has a specific usage setting for the function. |
| 5 | The default usage setting for the function was used. |
| 9 | The usage source could not be determined. |
Usage source ignoring *ALLOBJ and ignoring specific usage setting. An indicator as to why the user is allowed or is not allowed to use the function if this API ignores the *ALLOBJ authority and specific usage setting.
This parameter contains one of the following values:
| 3 | One of the user's groups has *ALLOBJ special authority. |
| 4 | One of the user's groups has a specific usage setting for the function. |
| 5 | The default usage setting for the function was used. |
| 9 | The usage source could not be determined. |
This table shows the format for the function selection criteria parameter. For a detailed description of each field, see Field Descriptions.
| Type | Field |
|---|---|
| BINARY(4) | Size of criteria entry |
| BINARY(4) | Comparison operator |
| BINARY(4) | Function control key |
| BINARY(4) | Length of comparison data |
| CHAR(*) | Comparison data |
Comparison data. The data to compare to the function information.
Comparison operator. The comparison value to be used when comparing the function information with the comparison data.
The following value can be specified:
| 1 | The comparison data equals the function information |
Function control key. The function control to be compared. Refer to Function Control Keys for more informaiton.
Length of comparison data. The length of the data to compare to the function information. The length of the comparison data must be valid for the function control key that is specified.
Size of criteria entry. The size of the selection criteria entry, including this field.
The following table shows the valid function control keys for the key field area of the selection control record. For a detailed description of each field, see Field Descriptions.
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(1) | Function category |
| 3 | CHAR(30) | Function product ID |
| 4 | CHAR(30) | Function group ID |
| 5 | CHAR(30) | Function ID |
Function category. The category of the function.
The possible values are:
| 1 | Locally managed client functions within IBM i Navigator are selected. |
| 2 | Locally managed client functions not within IBM i Navigator are selected. |
| 3 | Host functions are selected. |
| 4 | Centrally managed client functions within IBM i Navigator are selected. |
| 5 | Centrally managed client functions not within IBM i Navigator are selected. |
| 7 | All locally managed client functions are selected. This includes all functions in categories 1 and 2. |
| 8 | All centrally managed client functions are selected. This includes all functions in categories 4 and 5. |
| 9 | All client functions are selected. This includes all functions in categories 1, 2, 4, and 5. |
Function group ID. All functions that have this function group are selected. The special value of *NONE can be specified to select functions that do not have a function group specified.
Function ID. The ID of the functions to be selected.
The following can be specified for the function ID:
| generic* | All function IDs that begin with the generic string are selected. |
| function ID | The specific function ID are selected. |
Function product ID. All functions that have this function product are selected.
| Message ID | Error Message Text |
|---|---|
| CPF2204 E | User profile &1 not found. |
| CPF229D E | Operation not allowed on user profile &1. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CD9 E | Requested function cannot be performed at this time. |
| CPF3CDA E | Registration facility repository not available for use. |
| CPF3CE2 E | Continuation handle not valid. |
| CPF3CE3 E | Continuation handle no longer valid. |
| CPF3CE4 E | Comparison operator &1 not valid for exit program selection criteria. |
| CPF3CE7 E | Number of selection criteria entries not valid. |
| CPF3CE9 E | Length of comparison data not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9810 E | Library &1 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Security APIs | APIs by category ]