Change User Space (QUSCHGUS) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Starting position | Input | Binary(4) |
| 3 | Length of data | Input | Binary(4) |
| 4 | Input data | Input | Char(*) |
| 5 | Force changes to auxiliary storage | Input | Char(1) |
Optional Parameter Group 1:
| 6 | Error code | I/O | Char(*) |
Optional Parameter Group 2:| 7 | Returned library name | Output | Char(10) |
Default Public Authority: *USE
Threadsafe: Yes
The Change User Space (QUSCHGUS) API changes the contents of the user space (*USRSPC) object by moving a specified amount of data to the object. This API allows you to change the contents of a user space if you are using either:
- A language that does not support pointers
- System-domain user spaces
Note: To determine the starting position for the QUSCHGUS API, you must add 1 to the offset value. In contrast to the IBM® i list APIs, which use an offset value based on 0 for the starting position, the QUSCHGUS API uses a value based on 1. For the QUSCHGUS API, the first character in the user space is at position 1.
The QSYS2.CHANGE_USER_SPACE procedure can be used as an alternative to this API. See CHANGE_USER_SPACE procedure for more information.
Authorities and Locks
- Library Authority
- *EXECUTE
- User Space Authority
- *CHANGE
- User Space Lock
- *EXCLRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. The special values supported for the library name are *LIBL and *CURLIB.
- Starting position
- INPUT; BINARY(4)
The first byte of the user space that is to be changed. It must have a value greater than 0.
- Length of data
- INPUT; BINARY(4)
The length of the new data in the input data parameter. The length must be greater than 0.
- Input data
- INPUT; CHAR(*)
The new data to be placed into the user space. The field must be at least as long as the length of data parameter.
- Force changes to auxiliary storage
- INPUT; CHAR(1)
The method of forcing changes made to the user space to auxiliary storage.
The valid values are as follows:
0 Does not force changes. Normal system management writes the changes to auxiliary storage. 1 Forces changes asynchronously. This interrupts the normal system management and ensures that the user space is written to auxiliary storage. 2 Forces changes synchronously. This interrupts the normal system management and ensures that the user space is written immediately to auxiliary storage.
Optional Parameter Group 1
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Optional Parameter Group 2
- Returned library name
- OUTPUT; CHAR(10)
The name of the library that contains the changed user space object. If the contents of the user space are successfully changed, the name of the library in which the user space was found is returned.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C0F E | Value &1 for starting position parameter is not valid. |
| CPF3C04 E | User space &1 not changed. |
| CPD3C0F D | Value &1 for starting position parameter is not valid. |
| CPD3C12 D | Length of data is not valid. |
| CPD3C13 D | Value &1 for force option is not valid. |
| CPD3C14 D | Starting position &1 and length &2 cause space overflow. |
| CPD3C15 D | New value &1 is shorter than the length specified. |
| CPD3C17 D | Error occurred with input data parameter. |
| CPF3C12 E | Length of data is not valid. |
| CPF3C13 E | Value &1 for force option is not valid. |
| CPF3C14 E | Starting position &1 and length &2 cause space overflow. |
| CPF3C15 E | New value &1 is shorter than the length specified. |
| CPF3C17 E | Error occurred with input data parameter. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF4ACF E | Operation failed for object &1 in &2 type *&3 due to replication errors. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| 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. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFC901 E | Mirroring operation not completed. Replication operations currently blocked on node &5. |
|
CPFC922 E |
Object &1 type &3 in library &2 restricted from Db2 Mirror replication, reason code &7. |
API introduced: V1R3
[ Back to top | Object APIs | APIs by category ]