Register Exit Point (QUSRGPT, QusRegisterExitPoint) API

Required Parameter Group:

1	Exit point name	Input	Char(20)
2	Exit point format name	Input	Char(8)
3	Exit point controls	Input	Char(*)
4	Error code	I/O	Char(*)

  Service Program Name: QUSRGFA1

  Default Public Authority: *EXCLUDE

  Threadsafe: Yes

The Register Exit Point (OPM, QUSRGPT; ILE, QusRegisterExitPoint) API registers an exit point with the registration facility. Each exit point can have a single exit program or multiple exit programs associated with it. Each exit point can be registered multiple times with a unique format name. The format name is defined by the exit point provider. The format name can be used to define the structural layout of the exit program data, the number and type of parameters to be passed, and so on. The exit point controls provide information to help manage and control the use of the exit point. The user profile calling the Register Exit Point API does not need to be authorized to the preprocessing exit programs.

Updating of an exit point is performed by reregistering the exit point with new values for the exit point control keys. The registration facility will update the control keys and maintain the current list of exit programs that are associated with the exit point. The following conditions apply to updating the exit point control keys:

Allow deregister: This control key is set the first time the exit point is registered and cannot be changed.
Allow change of exit point controls: When this control key is set to 0 (cannot be changed), none of the control keys are eligible to be updated.
Maximum number of exit programs: Updating this control key to a value less than the number of exit programs currently under the exit point results in an error. The update is not performed.
Preprocessing exit program information for add function: If the new preprocessing exit program value is not *NONE and the Preprocessing Exit Program for Retrieve is *NONE, the Preprocessing Exit Program for Add is called for each exit program associated with the exit point. If the preprocessing exit program returns to the API the return code to not add an exit program, an error occurs. No update is performed.
If updating the preprocessing exit program to *NONE and the preprocessing exit program information for retrieve function field is also *NONE, the API updates the control key. If the preprocessing exit program information for retrieve function field is not *NONE, an error is returned and no update is performed.
Preprocessing exit program information for remove function: If updating the preprocessing exit program to *NONE and the preprocessing exit program information for retrieve function field is also *NONE, the API updates the control key. If the preprocessing exit program for retrieve is not set to *NONE, an error is returned and no update is performed.
Preprocessing exit program information for retrieve function: When the new value for the preprocessing exit program is not *NONE, preprocessing exit programs for add and remove must be either currently specified for the exit point or must be specified on the registration call. The registration facility calls the Preprocessing Exit Program for Add for each of the exit programs associated with the exit point. The facility then removes these exit programs (without calling the Preprocessing Exit Program for Remove) from the registration facility repository and updates the exit point. If the preprocessing exit program returns to the API the return code to not add an exit program, an error occurs and no update is performed.
When the new value for the preprocessing exit program is *NONE, the API will change the value. Exit point providers are responsible for moving the exit program information that they stored to the registration facility by using the Add Exit Program API.
Qualified message file and message identifier for exit point description: The registration facility updates this control key with the new value. When this control key is specified for an update, the text for exit point description control key must not be specified.
Exit point text description: The registration facility updates this control key with the new value. When this control key is specified for an update, the qualified message file and message identifier for exit point description control key must not be specified.

Unregistered Exit Points

The registration facility creates an exit point when an exit program is requested to be added to an exit point that does not exist. The facility uses the default values for the exit point control keys. This exit point is considered unregistered until it is explicitly registered with this API.

An unregistered exit point that was created by the Add Exit Program API can be registered using the Register Exit Point API. Unregistered exit points and related information can be displayed using the Work with Registration Information (WRKREGINF) command or retrieved using the Retrieve Exit Information API.

The Add Exit Program, Remove Exit Program, Retrieve Exit Information, and Deregister Exit Point APIs can be run against an unregistered exit point. The ability to deregister an unregistered exit point enables the removal of exit points created by the Add Exit Program API in error. For example, if the exit point name specified on the call to the Add Exit Program API were misspelled, the exit point can be deregistered.

When registering an unregistered exit point, the exit point control keys are reset to what is specified on the call to the Register Exit Point API. The following conditions prevent the registration of an unregistered exit point:

A preprocessing exit program is specified for add. The registration facility calls the Preprocessing Exit Program for Add for each exit program that was added to the unregistered exit point. If an exit program currently listed under the unregistered exit point cannot be added, the preprocessing exit program then notifies the registration facility. When this occurs, the exit point provider must remove the exit program from the unregistered exit point (using the Remove Exit Program API) and must register the exit point again.
The current number of exit programs associated with the unregistered exit point exceeds the maximum number of exit programs specified when the exit point is registered. When this occurs, the exit point provider should do either of the following:
- Remove the appropriate number of exit programs from the unregistered exit point (using the Remove Exit Program API)
- Change the maximum number of exit programs field to a higher value

Authorities and Locks

API Public Authority: *EXCLUDE
Exit Registration Lock: *EXCL

Required Parameter Group

Exit point name

INPUT; CHAR(20)

The exit point name to register. IBM^® i exit points are named QIBM_Qccc_name, where ccc is the component identifier. All other IBM exit points are named QIBM_wccc_name, where w is a character A through I and ccc is the component identifier. User-supplied exit point names should not preface their exit point names with QIBM. User-supplied exit point names should start with the company name to eliminate most problems involving name uniqueness. An exit point name must be a valid *NAME (basic name) and all uppercase. See ELEM (Element) Statement in the Control language topic collection for more information about *NAME.

Exit point format name

INPUT; CHAR(8)

The format defined by the exit point provider. The format specifies the layout of the exit program data or the parameters to be passed, or both. The exit point format name must be a valid *NAME (basic name) and all uppercase characters.

Exit point controls

INPUT; CHAR(*)

The exit point control fields for managing the exit point. Any field not specified will be given the default value. Refer to Exit Point 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 exit point 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.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Length of variable length record
4	4	BINARY(4)	Exit point control key
8	8	BINARY(4)	Length of data
12	C	CHAR(*)	Data

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 exit point control is to be set.

Exit point control key. The exit point control to be set. Refer to Exit Point Control Keys for more information.

Length of data. The length of the exit point control value.

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

Exit Point Control Keys

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

Key	Type	Field
1	CHAR(1)	Allow deregistration
2	CHAR(1)	Allow change of exit point controls
3	BINARY(4)	Maximum number of exit programs
4	CHAR(28)	Preprocessing exit program information for add function
5	CHAR(28)	Preprocessing exit program information for remove function
6	CHAR(28)	Preprocessing exit program information for retrieve function
7	CHAR(27)	Qualified message file name and message identifier for exit point description
8	CHAR(50)	Exit point text description

Field Descriptions

Allow change of exit point controls. Whether the exit point controls can be changed. When 0 (no change) is specified, the only means of changing the exit point controls is to:

Deregister the exit point (if allow deregister is set to 1)
Reregister the exit point
Add the exit programs again

The default value is 1.

0	The exit point controls cannot be changed.
1	The exit point controls can be changed.

Allow deregistration. Whether the exit point can be deregistered (removed from the registration facility repository). When 0 is specified, the exit point can never be removed from the registration facility repository. This control is set when the exit point is registered and cannot be changed. The default value is 1.

0	The exit point cannot be deregistered.
1	The exit point can be deregistered.

Exit point text description. The text for the exit point description. When this key is specified, the qualified message file name and message identifier for exit point description key must not be specified. The default value is blanks.

Maximum number of exit programs. The number of exit programs that this exit point can have. The minimum number of exit programs is 1. The default value is -1.

-1	No maximum.
>0	The maximum number of exit programs.

Preprocessing exit program information for add function. The format and the exit program that the registration facility calls when the Add Exit Program API is called for the exit point. This program performs any function that is needed by the exit point when an exit program is added to it. The exit program must exist when the exit point is registered. Refer to Preprocessing Exit Program Format for the format of this field.

Preprocessing exit program information for remove function. The format and the exit program that the registration facility calls when the Remove Exit Program API is called for the exit point. This program performs any function that is needed by the exit point when an exit program is removed from it. The exit program must exist when the exit point is registered. Refer to Preprocessing Exit Program Format for the format of this field.

Preprocessing exit program information for retrieve function. The format and the exit program that the registration facility calls when the Retrieve Exit Information API is called for the exit point. This exit program cannot be specified without specifying preprocessing exit programs for add and remove. When this exit program is specified, the exit point provider will store all the exit program information instead of the registration facility. The exit program must exist when the exit point is registered. Refer to Preprocessing Exit Program Format for the format of this field.

Qualified message file name and message identifier for exit point description. A message file and message identifier that contains the exit point description. When this key is specified, the exit point text description control key must not be specified. 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 Format

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

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(10)	Message file name
10	A	CHAR(10)	Message file library name
20	14	CHAR(7)	Message identifier

Field Descriptions

Message file library name. The library name in which the message file resides. The special value *CURLIB is not supported. The possible values are:

*LIBL	Search the library list for the message file. This value uses the first message file in the library list that contains the message identifier.
library name	The name of the message library the message file resides in.

Message file name. The name of the message file that contains the exit point description.

Message identifier. The message identifier for the description.

Preprocessing Exit Program Format

The following table shows the layout of the preprocessing exit program information fields. For a detailed description of each field, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(10)	Preprocessing exit program name
10	A	CHAR(10)	Preprocessing exit program library name
20	14	CHAR(8)	Preprocessing exit program format name

Field Descriptions

Preprocessing exit program format name. The format name for the preprocessing exit program. If *NONE is specified for the preprocessing exit program name, this field must be blank. The possible values for the format names follow:

ADDP0100	The required parameter group for the Preprocessing Exit Program for Add.
RMVP0100	The required parameter group for the Preprocessing Exit Program for Remove.
RTVI0100	The required parameter group for the Preprocessing Exit Program for Retrieve.

Refer to Registration Facility Preprocessing Exit Programs for information about the required parameter group of each preprocessing exit program.

Preprocessing exit program library name. The library name in which the preprocessing exit program resides. If *NONE is specified for the preprocessing exit program name, this field must be blank. The special values *LIBL and *CURLIB are not supported.

Preprocessing exit program name. The name of the preprocessing exit program that is called by the registration facility when the corresponding function is requested for the exit point. The default value is *NONE. The possible values are:

*NONE	No exit program is supplied.
exit program name	The exit program name.

If *NONE is specified for the preprocessing exit program name, the library name and format name must be blank.

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
CPF3C1E E	Required parameter &1 omitted.
CPF3C36 E	Number of parameters, &1, entered for this API was not valid.
CPF3C4D E	Length &1 for key &2 not valid.
CPF3C81 E	Value for key &1 not valid.
CPF3C82 E	Key &1 not valid for API &2.
CPF3C84 E	Key &1 required with value specified for key &2.
CPF3C85 E	Value for key &1 not allowed with value for key &2.
CPF3C90 E	Literal value cannot be changed.
CPF3CD1 E	Exit point &1 with format &2 already registered.
CPF3CD2 E	Exit point name &1 not valid.
CPF3CD3 E	Exit point format name &1 not valid.
CPF3CD4 E	Maximum number of exit programs reached for exit point &1 with format &2.
CPF3CD5 E	Exit point control &1 cannot be changed.
CPF3CD7 E	Preprocessing exit program &1 library &2 with format &3 not valid.
CPF3CD8 E	Registration of exit point &1 with format &2 not performed.
CPF3CD9 E	Requested function cannot be performed at this time.
CPF3CDA E	Registration facility repository not available for use.
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.
CPF9802 E	Not authorized to object &2 in &3.
CPF9810 E	Library &1 not found.
CPF9811 E	Program &1 in library &2 not found.
CPF9820 E	Not authorized to use library &1.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3

API introduced: V3R1

[ Back to top | Registration Facility APIs | APIs by category ]