Retrieve User Function Information (QSYRTUFI, QsyRetrieveUserFunctionInfo) API

  Required Parameter Group for QSYRTUFI:

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(*)

  Default Public Authority: *USE

  Threadsafe: Yes

  Syntax for QsyRetrieveUserFunctionInfo:

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

  Threadsafe: Yes

The Retrieve User Function Information (OPM, QSYRTUFI; ILE, QsyRetrieveUserFunctionInfo) API retrieves usage settings for a specified user profile for one or more functions.

Authorities and Locks

API Public Authority

*USE

Authority Required (if user profile name is not *CURRENT)

*SECADM special authority or

*READ to the user profile

Function Registration and Usage Information 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 usage 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 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.

User profile name

INPUT; CHAR(10)

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.

Function selection criteria

INPUT; CHAR(*)

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.

Desired CCSID

INPUT; BINARY(4)

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.

Error code

I/O; CHAR(*)

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

UFNI0100 Format

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.

UFNI0200 Format

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.

UFNI0300 Format

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.

Field Descriptions

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:

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:

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:

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:

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:

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:

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.

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:

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.

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.

Field Descriptions

Function category. The category of the function.

The possible values are:

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:

Function product ID. All functions that have this function product are selected.

Error Messages