Register Function (QSYRGFN, QsyRegisterFunction) API

  Required Parameter Group for QSYRGFN:

1	Function ID	Input	Char(30)
2	Function controls	Input	Char(*)
3	Error Code	I/O	Char(*)

  Default Public Authority: *USE

  Threadsafe: Yes

  Syntax for QsyRegisterFunction:

 #include <qsyrgfn1.h>

 void QsyRegisterFunction
        (char                  Function_ID[30],
         Qsy_Func_Controls_T  *Function_controls,
         void                 *Error_code);

  Service Program: QSYRGFN1
  Default Public Authority: *USE

  Threadsafe: Yes

The Register Function (OPM, QSYRGFN; ILE, QsyRegisterFunction) API registers a function with the registration facility. The function controls provide information to help manage and control the use of the function.

You can update a function entry by reregistering the function (using the replace control key) with new values for the function control keys. The registration facility will update the control keys and maintain the current list of usage settings that are associated with the function. The following conditions apply to updating the function control keys:

• Function category: This control key is set the first time the function is registered and cannot be changed.
• Function type: This control key is set the first time the function is registered and cannot be changed.

When a function is registered, the registration information is stored using the Exit Point Registration Facility. Each function is registered as an exit program within an exit point. The exit point that the function is registered in depends on the category of the function:

• Locally managed client functions within iSeries Navigator are registered in the QIBM_QSY_OPNAVCLIENT exit point.
  
  
• Locally managed client functions that are not within iSeries Navigator are registered in the QIBM_QSY_OTHERCLIENT exit point.
  
  
• Host functions are registered in the QIBM_QSY_HOSTFUNC exit point.
  
  
• Centrally managed client functions within iSeries Navigator are registered in the QIBM_QSY_OPNAVCENTRL exit point.
  
  
• Centrally managed client functions that are not within iSeries Navigator are registered in the QIBM_QSY_OTHERCENTRL exit point.

The Exit Point Registration Facility is used only for storing the function registration information. The exit programs within these exit points are never called, so the formats associated with these exit points (FCNR0100 and FCNR0200) are never used or documented.

Note: You must use this API and the Deregister Function (QSYDRGFN, QsyDeregisterFunction) API to manage the function registration entries. If the Exit Point Registration Facility APIs are used, the results will be unpredictable.

Authorities and Locks

API Public Authority

*USE

Authority Required

*SECADM special authority

Function Registration Lock

*EXCL

Required Parameter Group

Function ID

INPUT; CHAR(30)

The function ID to register. IBM functions are named QIBM_Qccc_name, where _Qccc is the componenet qualifier and ccc is the component identifier, or are named QIBM_wccc_name, where _wccc is the component qualifier, w is a character A through I, and ccc is the component identifier. The component qualifier is included in IBM function IDs if the function is associated with a specific component. Otherwise, IBM function IDs will not contain the component qualifier. User-supplied function IDs should not preface their function ID with QIBM. User-supplied function IDs should start with the company name to eliminate most problems that involve unique names.

The first character of the function ID must be one of the following:

A-Z	Uppercase A-Z

The remaining characters in the function ID must be made up of the following characters:

A-Z	Uppercase A-Z
0-9	Digits 0-9
.	Period
_	Underscore

Function controls

INPUT; CHAR(*)

The function control fields for managing the function. Any field not specified will be given the default value. Refer to Function Control Keys for more information.

The information must be in the following format:

Number of variable length records	BINARY(4) The total number of all of the variable length records.
Variable length records	The fields of the function controls to set. Refer to Format for Variable Length Record for more information.

Error code

I/O; CHAR(*)

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

Format for Variable Length Record

The following table shows the layout of the variable length record. For a detailed description of each field, see Field Descriptions.

If the length of the data is longer than the key field's data length, the data is truncated at the right. No message is issued.

If the length of the data is shorter than the key field's data length and the key contains binary data, an error message is issued. If the key does not contain binary data, the field is padded with blanks.

It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.

Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.

Field Descriptions

Data. The value to which a specific function control is to be set.

Function control key. The function control to be set. Refer to Function Control Keys for more information.

Length of data. The length of the function control value.

Length of variable length record. The length of the record including this field.

Function Control Keys

The following table shows the valid function control keys for the key field area of the variable length record. For a detailed description of each field, see Field Descriptions.

Field Descriptions

Whether a user with *ALLOBJ special authority can use the function. The default value is 1. This key can be specified only if the function type control key is set to 3 (administrable function).

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. This key can be specified only if the function type control key is set to 3 (administrable function). The default value is 2.

Function category. The category of the function. This control is set when the function is registered and cannot be changed. The default value is 3.

Only client based applications should use category 1, 2, 4, or 5. See Application Administration Concepts in the iSeries Navigator topic for more information on the difference between locally managed and centrally managed client functions.

Function description. The text for the function description. The default value is blanks.

Function description CCSID. The CCSID value associated with the function description. The default value is 0.

Function group ID. The ID of the function group with which this function will be grouped. The function group must exist, have a function type of function group (2), and have the same category as the function being registered. If a value of *NONE is specified, then the function is not grouped under a function group. The default value is *NONE. This key cannot be specified if the function type control key is set to 1 (function product).

Function name. The text name for the function ID. The function name will be used to identify the function when using the iSeries Navigator Application Administration support. If this control is not specified, the function ID will be used to identify the function.

Function name CCSID. The CCSID value associated with the function name. The default value is 0.

Function product ID. The ID of the product for which the function is being registered. This key cannot be specified if the function type control key is set to 1 (function product). This key must be specified if the function type control key is set to 2 (function group) or 3 (administrable function).

Function type. The type of function. This control is set when the function is registered and cannot be changed. The default value is 3.

Qualified message file name and message identifier for function description. A message file and message identifier that contains the function description. The message file and message identifier do not have to exist at the time of registration. The default value is blanks. Refer to Qualified Message File Format for the format of this field.

Qualified message file name and message identifier for function name. A message file and message identifier that contains the function name. The message file and message identifier do not have to exist at the time of registration. The default value is blanks. Refer to Qualified Message File Format for the format of this field.

Replace. Whether to replace an existing registered function. The default value is 0.

Qualified Message File Format

The following table shows the layout of the qualified message file name and message identifier for the function name and function description fields. For a detailed description of each field, see Field Descriptions.

Field Descriptions

The library name in which the message file resides. No special values are supported.

Message file name. The name of the message file that contains the function name or function description.

Message identifier. The message identifier for the function name or function description.

Error Messages