Change Program Data (QBNCHGPD) API
Required Parameter Group:
| 1 | Qualified object name | Input | Char(20) |
| 2 | Object type | Input | Char(10) |
| 3 | Format name | Input | Char(8) |
| 4 | Changed object information | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 6 | Qualified bound module name | Input | Char(20) |
| 7 | Qualified bound service program name | Input | Char(20) |
Default Public Authority: *USE
Threadsafe: No
The Change Program Data (QBNCHGPD) API lets you change data for module, program and service program objects. The data available to be changed includes source file information, bound module library names, bound service program library names, and export source file information.
When the source file information is changed, the location of the source for debug source views is also changed. This will allow debug views that refer to a copy of the source (such as DBGVIEW(*SOURCE)), to be able to locate the creation source files if their location has changed.
When an object has been successfully updated by the API, the change date and time stamp (date and time the object was changed) field is also updated.
Authorities and Locks
- Library Authority
- *EXECUTE
- *DLT and *ADD are also required to change ILE program and service program objects.
- Object Authority
- *OBJMGT *USE
- Object Lock
- *EXCL
Required Parameter Group
- Qualified object name
- INPUT; CHAR(20)
The object for which you want to change information and the library in which it is located. The first 10 characters contain the object name, and the second 10 characters contain the library name.
name Specify the name of the object having its attributes changed. You can use these special values for the library name:
*CURLIB The job's current library. *LIBL The job's library list.
- Object type
- INPUT; CHAR(10)
The type of object for which you want to change the information. You must use one of these special values for the object type:
*MODULE Module object *PGM Program object *SRVPGM Service program object
- Format name
- INPUT; CHAR(8)
The format of the Change records provided for the Changed object information parameter.
The possible format names are:
CHGP0100 Change program reference information.
- Changed object information
- INPUT; CHAR(*)
The information for the object that you want to change. The information must be in the following format:
Number of change records BINARY(4)
Total number of change records specified. If the value of this field is less than 0, an error message is returned. It is not an error if this field is 0. If it is 0, the API will make no changes to the object.Change records The fields of the object to change and the data used for the change. For the specific format of the change record, see Format for the Change Records.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group
The optional parameters can be used to specify the bound modules and bound service programs that are to be selected for update for ILE program and service program objects. If the optional parameters are not specified, the API behavior will be as if *ALL was specified for both the Qualified bound module name and the Qualified bound service program name.
- Qualified bound module name
- INPUT; CHAR(20)
The bound modules for which you want to change information and the library that they were in when they were bound into this program/service program. The first 10 characters contain the module name, and the second 10 characters contain the library name. If this optional parameter is not specified, the behavior will be as if *ALL was specified for both the bound module name and the bound module library name.
You can use one of the following formats for the bound module name:
name Specify the name of the bound module having its attributes changed. generic-name Specify the generic name of all bound modules having their attributes changed. All bound modules that satisfy the generic search value are selected for change. *ALL All bound modules that match the specified bound module library name are selected to be changed. *NONE No bound modules will be changed. If *NONE is specified, the bound module library name must be blank. You can use these special values for the bound module library name:
generic-name Specify the generic name of the libraries that contained the bound modules that are to have their attributes changed. *ALL All bound modules that match the specified bound module name will be changed. - Qualified bound service program name
- INPUT; CHAR(20)
The bound service programs for which you want to change information and the library that they were in when they were bound into this program/service program. The first 10 characters contain the service program name, and the second 10 characters contain the library name. If this optional parameter is not specified, the behavior will be as if *ALL was specified for both the bound service program name and the bound service program library name.
You can use one of the following formats for the bound service program name:
name Specify the name of the bound service program having its attributes changed. generic-name Specify the generic name of all bound service programs having their attributes changed. All bound service programs that satisfy the generic search value are selected for change. *ALL All bound service programs that match the specified bound service program library name are selected to be changed. *NONE No bound service programs will be changed. If *NONE is specified, the bound service program library name must be blank. You can use these special values for the bound service program library name:
generic-name Specify the generic name of the libraries that contained the bound service programs that are to have their attributes changed. *ALL All non-IBM-supplied bound service programs that match the specified bound service program name will be changed.
Format for the Change Records--Format CHGP0100
The following table defines the format of the change records for format CHGP0100. These records are used to specify the type of data to be changed, the selection values used to determine which data items are to be changed, and the new values to which the data items are to be changed.
For this format, the data items indicated by the specified key value will be selected for update if they meet the selection critera specified by the "From" values. Selected data items will be changed to the value specified by the "To" values.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Key |
| 4 | 4 | CHAR(10) | From library |
| 14 | E | CHAR(10) | From file |
| 24 | 18 | CHAR(10) | From member |
| 34 | 22 | CHAR(10) | To library |
| 44 | 2C | CHAR(10) | To file |
| 54 | 36 | CHAR(10) | To member |
It is not an error to specify more than one change record for a particular key value. If a data item is affected by more than one change record, the value assigned by the last change record is used.
Field Descriptions
From file. The source file names that will be selected for update.
You can use one of the following formats for the From file:
| name | Specify the name of the source file that is to be selected for update. |
| generic-name | Specify the generic name of the source files that are to be updated. All source files that match the generic name value are selected. |
| *ALL | All source files for the object are selected for update. |
| blank | The From file must be blank when the bound module library(key 3), bound service program library(key 4),  disallow service program library name update (key 5) or prohibit update (key 6)  is specified. |
From library. The library names that will be selected for update.
You can use one of the following formats for the From library:
| name | Specify the name of the library that is to be selected for update. |
| generic-name | Specify the generic name of the libraries to be updated. All libraries that satisfy the generic search value are selected. |
| *ALL | All library names for the object are selected for update. |
| blank |
The From library must be blank when the disallow service program library name update(key 5) or prohibit update (key 6) is specified. |
From member. The source member names that will be selected for update.
You can use one of the following formats for the From member:
| name | Specify the name of the source member that is to be selected for update. |
| generic-name | Specify the generic name for the source members being updated. All source members that satisfy the generic search value are selected. |
| *ALL | All source members for the object are selected for update. |
| blank | The From member must be blank when the bound module library(key 3), bound service program library(key 4), disallow service program library name update(key 5) or prohibit update (key 6) is specified. |
Key. Identifies the data to be changed by this change record. See Keys for the list of valid values.
To file. The name to which the source file is to be changed.
You can use one of the following formats for the To file:
| name | Specify the name to which the source file is to be changed. |
| *SAME | The file name is not changed. |
| blank | The To file must be blank when the bound module library(key 3), bound service program library(key 4), disallow service program library name update(key 5) or prohibit update (key 6) is specified. |
To library. The name to which the library is to be changed.
You can use one of the following formats for the To library:
| name | Specify the name to which the library is to be changed. |
| *SAME | The library name is not changed. |
| blank |
The To library must be blank when the disallow service program library name update(key 5) or prohibit update (key 6) is specified. |
To member. The name to which the source member is to be changed. A value other than *SAME is only valid for this field when specific name values are also provided for the From library, From file, and From member fields. If the From library, From file, or From member fields contain a generic or *ALL value, then the To member must be *SAME.
You can use one of the following formats for the To member:
| name | Specify the name to which the source member is to be changed. |
| *SAME | The source member name is not changed. |
| blank | The To member must be blank when the bound module library(key 3), bound service program library(key 4), disallow service program library name update(key 5) or prohibit update (key 6) is specified. |
Keys
The following table lists the valid values for the key field of the change records for format CHGP0100, and specifies the object types for which each key is valid.
| Key | Description | Object Type | |||
|---|---|---|---|---|---|
| *PGM(OPM) | *MODULE | *PGM(ILE) | *SRVPGM | ||
| 1 | Creation source files | X | X | X | X |
| 2 | Export source file | X | |||
| 3 | Bound module library | X | X | ||
| 4 | Bound service program library | X | X | ||
| 5 |
Disallow service program library name update | X | X |
||
 6 |
Prohibit update | X | X |
||
OPM refers to original program model, and ILE refers to Integrated Language Environment®.
For ILE program and service program objects, the creation source file fields apply to the bound modules.
Key Descriptions
Bound module library. This key is used to change the library name for bound modules. The name specified must be in a valid object name format. It is not required to be the name of an existing library on the system. An attempt to change a bound module library name is not allowed if the change results in a program or service program having duplicate qualified bound module names.
Bound service program library. This key is used to change the library name for bound service programs. The name specified must be the name of an existing library, and the corresponding service program must exist in that library.
Creation source files. This key is used to change the library, source file, and source member names for the source files that were used to create the object.
The source files that will be changed by this key are the root source file (the one that is displayed by the DSPMOD and DSPPGM comands), and if a source debug view was specified during object creation, the names of the include files that were used are stored as debug data, and will also be changed.
When changing the root source file, this API will attempt to change the "Source file change date/time" field to the current value for the source member at the newly specified location. If a source member can not be accessed at the newly specified location, the "Source file change date/time" field will be left unchanged.
Disallow service program library name update. This key is used to prohibit further change to the library name for bound service programs. The attribute "Allow bound service program library update" will be changed to *NO at the completion of the API processing. Any change records with a key value of 4 (bound service program library) on this API call will be processed before the attribute is set to *NO.
Prohibit update. This key is used to prevent further change to the program or service program via the UPDPGM and UPDSRVPGM commands. The attribute "Allow update" will be changed to *NO at the completion of the API processing. The "Allow bound service program library update" attribute is also changed to *NO as part of the processing of this key. Any change records with other key values on this API call will be processed before the attributes are set to *NO.
Export source file. This key is used to change the library, source file, and source member names for the export source file. The name specified must be the name of an existing source file.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2131 E | Key &1 not allowed with object type *&2. |
| CPF2151 E | Operation failed for &2 in &1 type *&3. |
| CPF2199 E | &2 not valid for key &1. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9821 E | Not authorized to program &1 in library &2. |
| CPF9828 E | Not authorized to module &1 in library &2. |
API introduced: V6R1
[ Back to top | Program and CL Command APIs | APIs by category ]