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.
The source file can be changed to a database file (using the CHGP0100 format) only if the object being changed already has its source file originating from a database file. Similarly, the source file can be changed to a stream file (using the CHGP0200 format) only if the object being changed already has its source file originating from a stream file. There is no mechanism to change the source file from a database file to a stream file or vice versa.
Although format CHGP0200 (used to change source stream files) can be used on modules/programs created for a release prior to 7.4, the format has no effect.
Note: For compatibility, the display module/program commands and the retrieve module/program information APIs will present both the stream file name and the equivalent database file name if the stream file is in the QSYS file system. However, if an object was built from a stream file in the QSYS file system, the source is considered to be originating from a stream file, not a database file. In that case, only format CHGP0200 can be used if the source file requires changing.
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 database file program reference information.CHGP0200 Change stream file 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. The layout of each change record depends upon the format name parameter. If the format is CHGP0100, see Format for the Change Records - format CHGP0100. If the format is CHGP0200, see Format for the Change Records - format CHGP0200.
- 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.
Format for the Change Records--Format CHGP0200
The following table defines the format of the change records for format CHGP0200. 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 criteria 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) | Record length |
| 4 | 4 | BINARY(4) | Key |
| 8 | 8 | BINARY(4) | CCSID of the from path |
| 12 | C | BINARY(4) | Length of the from path |
| 16 | 10 | BINARY(4) | Offset to the from path |
| 20 | 14 | BINARY(4) | CCSID of the to path |
| 24 | 18 | BINARY(4) | Length of the to path |
| 28 | 1C | BINARY(4) | Offset to the to path |
| Variable portion of record | |||
| 32 | 20 | CHAR(*) | From path |
| CHAR(*) | To path | ||
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 resulting value will be the value after all change records have been applied, in order. For example, if the starting path is /abc/def/x.c, and the change records are as follows:
- Record 1:
- From = "/abc"
To = "/xyz" - Record 2:
- From = "/x"
To = "/xyz"
The resulting path will be /xyzyz/def/x.c. Record 1 changes the original path to /xyz/def/x.c and record 2 changes the intermediate path to /xyzyz/def/x.c.
Field Descriptions
CCSID of the from path. The coded character set identifier (CCSID) of the From path. When searching for selected stream file paths for update, paths will be converted to a common CCSID prior to performing any comparisons. If this field is 0, then the From path is assumed to be in the current job's CCSID.
CCSID of the to path. The coded character set identifier (CCSID) of the To path. When searching for selected stream file paths for update, paths will be converted to a common CCSID prior to performing any comparisons. If this field is 0, then the To path is assumed to be in the current job's CCSID.
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. |
From path. The stream file path that will be selected for update. The From Path specifies the portion of the stream file path to be updated. If it is found at the beginning of the current source stream file path, it will be updated with the path specified in the To Path. See the table in the To path description for examples. Note that the path specified in the From Path will be compared starting at the beginning of the stream file path. If the string is contained in the middle or end of the stream file path, it will not match and will not be updated. Wild cards are not allowed in the From path.
Key. Identifies the data to be changed by this change record. See Keys for the list of valid values.
Length of the from path. The length, in bytes, of the From path. The From path must specify a value; therefore, this field cannot be zero.
Length of the to path. The length, in bytes, of the To Path. The To Path must specify a value; therefore, this field cannot be zero.
Offset to the from path. Offset from the beginning of the current record to the From Path.
Offset to the to path. Offset from the beginning of the current record to the To Path.
Record length. The length of the given change record, including the variable portion of the record. This field can be used to reach the next change record if one is present.
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. |
To path. The path to which the matching portion of the stream file is to be changed. If a From path is found at the beginning of a stream file path, that text will be replaced with the To Path. Some examples follow:
| Current Source Path | From Path | To Path | Modified Path | Description |
|---|---|---|---|---|
| /home/bill/abc.C | /home/bill | /ibm/idwb | /ibm/idwb/abc.C | The From Path is found at the beginning of the current source path; therefore, that portion of the From Path is changed to the To Path. |
| /home/bill/abc.C | /bill | /idwb | no change | The From Path is not found at the beginning of the current source path. |
| /home/bill/abc.C | /ibm/idwb/ | /home/joe/abc.C | no change | The From Path is not found at the beginning of the current source path. |
Keys
The following table lists the valid values for the key field of the change records, the format allowed, and the object types for which each key is valid.
| Key | Description | Format Allowed |
Object Type | |||
|---|---|---|---|---|---|---|
| *PGM(OPM) | *MODULE | *PGM(ILE) | *SRVPGM | |||
| 1 | Creation source files | CHGP0100, CHGP0200 |
X1 |
X | X | X |
| 2 | Export source file | CHGP0100 |
X | |||
| 3 | Bound module library2 |
CHGP0100 |
X | X | ||
| 4 | Bound service program library2 |
CHGP0100 |
X | X | ||
| 5 | Disallow service program library name update2 |
CHGP0100 |
X | X | ||
| 6 | Prohibit update2 |
CHGP0100 |
X | X | ||
1For key=1, OPM programs can only be changed with format CHGP0100.
2This function requires that the object contain creation data.
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 database file names (library, file, member) or the stream file names of 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 stored as debug data.
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 file at the newly specified location. If a source file 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 |
|---|---|
| CPF0542 E |
Program &1 in library &2 not changed. |
| CPF0544 E |
Programs in libraries QSYS and QGDDM cannot be changed. |
| 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. |
| CPF3C36 E |
Number of parameters, &1, entered for this API was not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF5CA8 E |
Invalid value for parameter number &1. |
| CPF5CA9 E |
Change record number &1 is invalid. |
| CPF5CAB E |
Unexpected error occurred. |
| CPF5CEB E |
Service program &1 in library &2 not found. |
| CPF5CEE E |
Service programs in libraries QSYS and QGDDM cannot be changed. |
| CPF5CF3 E |
Service program &1 in library &2 not changed. |
| CPF5CFA E |
Modules in library QSYS cannot be changed. |
| CPF5D04 E |
Not authorized to service program &1 in library &2. |
| CPF5D0D E |
Service program &1 not found in library &2. |
| CPF9390 E |
Unable to normalize the "To path" and the "From path". |
| CPF9391 E |
Updating a path will cause its length to be greater than 5000 bytes. |
| CPF9392 E |
An unexpected conversion error occurred. |
| CPF9393 E |
Change record number &1 is invalid. |
| CPF9394 E |
Unable to change source file name. |
| 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. |
| CPF9804 E |
Object &2 in library &3 damaged. |
| CPF9806 E |
Cannot perform function for 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 ]