| 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 | Function selection criteria | Input | Char(*) |
| 6 | Desired CCSID | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
#include <qsyfnusg.h>
void QsyRetrieveFunctionInformation
(char Continuation_handle[20],
void *Receiver_variable,
int *Length_of_receiver_variable,
char Format_name[8],
Qsy_Selcrtr_T *Function_selection_criteria,
int *Desired_CCSID,
void *Error_code);
Service Program: QSYFNUSGThe Retrieve Function Information (OPM, QSYRTVFI; ILE, QsyRetrieveFunctionInformation) API retrieves information about 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 function 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 function information to be returned.
You must use the following format name:
| FCNI0100 | Function information |
The selection criteria to be used when selecting which functions are returned. 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. 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 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 will be converted to the default CCSID for the job. |
| CCSID | The text fields will be converted to the specified CCSID. The CCSID value must be from 1 to 65535. If 65535 is specified, then no CCSID conversion will be 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 FCNI0100 format. This format provides information about a function. 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) | Function category | ||
| CHAR(1) | Function type | ||
| 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(10) | Function-description message-file name | ||
| CHAR(10) | Function-description message-file library name | ||
| CHAR(7) | Function-description message ID | ||
| CHAR(330) | Function-description message text | ||
| CHAR(3) | Reserved | ||
| BINARY(4) | Function-description message text CCSID | ||
| CHAR(330) | Function description | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Function description CCSID | ||
| CHAR(30) | Function product ID | ||
| CHAR(30) | Function group ID | ||
| CHAR(1) | Default usage | ||
| CHAR(1) | *ALLOBJ indicator | ||
| CHAR(1) | Usage information indicator | ||
| CHAR(*) | Reserved | ||
*ALLOBJ indicator. Whether a user with *ALLOBJ special authority can use the function. If this is not an administrable function, then this field is blank.
The possible values follow:
| 0 | The user, its groups, or default must allow usage of the function. |
| 1 | A user with *ALLOBJ special authority is always allowed to use the function. |
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.
Default usage. The default usage for the function. The default usage is used if the user or one of its groups does not have a specific usage setting. If this is not an administrable function, then this field is blank.
The possible values follow:
| 1 | The default usage does not allow usage of the function. |
| 2 | The default usage allows usage of the function. |
Function category. Whether the function is a client or host function.
The possible values follow:
| 1 | The function is a locally managed client function within IBM i Navigator. |
| 2 | The function is a locally managed client function, not within IBM i Navigator. |
| 3 | The function is a host function. |
| 4 | The function is a centrally managed client function within IBM i Navigator. |
| 5 | The function is a centrally managed client function, not within IBM i Navigator. |
Function description. The text for the function description. This value is converted to the CCSID value specified in the desired CCSID parameter.
Function description CCSID. The CCSID value that is associated with the function description in the registration facility.
Function-description message-file name. The name of the message file that contains the function description. If no message file name is specified, this field contains blanks.
Function-description message-file library name. The name of the library in which the function description message file resides. If no message file name is specified, this field contains blanks.
Function-description message ID. The message identifier for the function description. If no message file name is specified, this field contains blanks.
Function-description message text. The first-level text for the function-description 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-description message-text CCSID. The CCSID value that the function-description message text is stored in.
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 function ID.
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 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.
Function type. The type of function.
The possible values follow:
| 1 | The function is a function product. |
| 2 | The function is a function group. |
| 3 | The function is an administrable function. |
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 information indicator. Whether there is usage information defined for the function. Usage information is the list of users and groups that have a specific usage setting specified for the function. Usage information is set using the Change Function Usage Information (OPM, QSYCHFUI; ILE, QsyChangeFunctionUsageInfo) API. If this is not an administrable function, then this field is blank.
The possible values follow:
| 0 | There is no usage information defined for the function. |
| 1 | There is usage information defined for the function. |
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 information.
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 |
| 2 | CHAR(1) | Function type |
| 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 name of the functions to select.
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 is selected. |
Function product ID. All functions that have this function product are selected.
Function type. The type of function.
The possible values are:
| 1 | Function products are selected. |
| 2 | Function groups are selected. |
| 3 | Administrable functions are selected. |
| Message ID | Error Message Text |
|---|---|
| CPF2225 E | Not able to allocate internal system object. |
| 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. |
| 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 ]