Retrieve Function Information (QSYRTVFI, QsyRetrieveFunctionInformation) API

Required Parameter Group for QSYRTVFI:

Continuation handle

Input

Char(20)

Receiver variable

Output

Char(*)

Length of receiver variable

Input

Binary(4)

Format name

Input

Char(8)

Function selection criteria

Input

Char(*)

Desired CCSID

Input

Binary(4)

Error code

I/O

Char(*)

Default Public Authority: *USE

Threadsafe: Yes

Syntax for QsyRetrieveFunctionInformation:

 #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: QSYFNUSG
  Default Public Authority: *USE

  Threadsafe: Yes

The Retrieve Function Information (OPM, QSYRTVFI; ILE, QsyRetrieveFunctionInformation) API retrieves information about one or more functions.

The QSYS2.FUNCTION_INFO view can be used as an alternative to this API. See FUNCTION_INFO view for more information.

Authorities and Locks

API Public Authority: *USE
Function Registration Lock: *SHRNUP

Required Parameter Group

Continuation handle

INPUT; CHAR(20)

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.

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the function information requested.

Length of receiver variable

INPUT; BINARY(4)

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.

Format name

INPUT; CHAR(8)

The format of the function information to be returned.

You must use the following format name:

FCNI0100

Function information

Function selection criteria

INPUT; CHAR(*)

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.

Desired CCSID

INPUT; BINARY(4)

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:

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

FCNI0100 Format

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

BINARY(4)

Bytes returned

BINARY(4)

Bytes available

CHAR(20)

Continuation handle

BINARY(4)

Offset to first function entry

BINARY(4)

Number of function entries returned

BINARY(4)

Length of function entry

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

Field Descriptions

*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:

The user, its groups, or default must allow usage of the function.

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:

The default usage does not allow usage of the function.

The default usage allows usage of the function.

Function category. Whether the function is a client or host function.

The possible values follow:

The function is a locally managed client function within IBM i Navigator.

The function is a locally managed client function, not within IBM i Navigator.

The function is a host function.

The function is a centrally managed client function within IBM i Navigator.

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.

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:

The function is a function product.

The function is a function group.

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:

There is no usage information defined for the function.

There is usage information defined for the function.

Format for Function Selection Criteria

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

Field Descriptions

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:

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.

Function Control Keys

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

CHAR(1)

Function category

CHAR(1)

Function type

CHAR(30)

Function product ID

CHAR(30)

Function group ID

CHAR(30)

Function ID

Field Descriptions

Function category. The category of the function.

The possible values are:

Locally managed client functions within IBM i Navigator are selected.

Locally managed client functions not within IBM i Navigator are selected.

Host functions are selected.

Centrally managed client functions within IBM i Navigator are selected.

Centrally managed client functions not within IBM i Navigator are selected.

All locally managed client functions are selected. This includes all functions in categories 1 and 2.

All centrally managed client functions are selected. This includes all functions in categories 4 and 5.

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:

Function products are selected.

Function groups are selected.

Administrable functions are selected.

Error Messages

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.

API introduced: V4R3

[ Back to top | Security APIs | APIs by category ]