| 1 | Qualified user space name | Input | Char(20) |
| 2 | Extended attribute | Input | Char(10) |
| 3 | Initial size | Input | Binary(4) |
| 4 | Initial value | Input | Char(1) |
| 5 | Public authority | Input | Char(10) |
| 6 | Text description | Input | Char(50) |
| 7 | Replace | Input | Char(10) |
| 8 | Error code | I/O | Char(*) |
| 9 | Domain | Input | Char(10) |
| 10 | Transfer size request | Input | Binary(4) |
| 11 | Optimum space alignment | Input | Char(1) |
The Create User Space (QUSCRTUS) API creates a user space in either the user domain or the system domain. A system-domain user space cannot be saved to a release prior to Version 2 Release 3 Modification 0. A user-domain user space can be directly manipulated with machine interface (MI) instructions or can be accessed using system APIs. On systems with a QSECURITY system value of 40 or greater, applications can only access system-domain user spaces using APIs. The user space objects you create are larger than or equal to the size specified. They have a fixed length and can be extended or truncated using the Change User Space Attributes (QUSCUSAT) API or the Modify Space (MODS) MI instruction (for user-domain user spaces). (The MODS instruction will not work on system-domain user spaces if the security level of the system is 40 or greater.)
Note: For performance reasons, the *USRSPC object is
created before checking to see if it exists in the library specified for the
qualified user space name. If you have an application using this API
repeatedly, even if you are using *NO for the replace parameter, permanent
system addresses will be used. 
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 only special value supported for the library name is *CURLIB.
User spaces created in the QTEMP and QRPLOBJ libraries are not forced to permanent storage; they are deleted when those libraries are cleared at sign-off and system IPL, respectively.
The extended attribute of the user space. For example, an object type of
*FILE has an extended attribute of PF (physical file), LF (logical file), DSPF
(display file), SAVF (save file), and so on. A *USRSPC might have user defined extended attributes such as LOG, TRACE, and CONTROL.
The extended attribute must be a valid *NAME. You can enter this parameter in uppercase, lowercase, or mixed case. The API converts it to uppercase.
The initial size of the user space being created. This value must be from 1 byte to 16, 776, 704 bytes.
The initial value of all bytes in the user space. You will achieve the best performance if you set this byte to X'00'.
The authority you give users who do not have specific private or group authority to the user space. Once the user space has been created, its public authority stays the same when it is moved to another library or restored from backup media.
If the replace parameter is used and a user space exists to be replaced, this parameter is ignored. All authorities are transferred from the replaced user space to the new one.
The valid values for this parameter are:
| *ALL | The user can perform all authorized operations on the object. |
| Authorization list name | The user space is secured by the specified authorization list, and its public authority is set to *AUTL. The specified authorization list must exist on the system when this API is called. If it does not exist, the create process fails, and an error is returned to the application. |
| *CHANGE | The user can read the object description and has read, add, update, and delete authority to the object. |
| *EXCLUDE | The user cannot access the object in any way. |
| *LIBCRTAUT | The public authority for the user space is taken from the CRTAUT value for the target library when the object is created. If the CRTAUT value for the library changes later, that change does not affect user spaces already created. If the CRTAUT value contains an authorization list name and that authorization list secures an object, do not delete the list. If you do, the next time you call this API with the *LIBCRTAUT parameter, it will fail. |
| *USE | The user can read the object and its description but cannot change them. |
This text briefly describes the user space.
Whether you want to replace an existing user space.
Valid values for this parameter are:
| *NO | Do not replace an existing user space of the same name and library. *NO is the default value. |
| *YES | Replace an existing user space of the same name and library. |
If the user space already exists, it is replaced
by a new user space of the same name and library, and is subject to the same
authorities. The user space being replaced is destroyed if both:
|
If the user space is in the system domain, it is moved to QRPLOBJ. If QALWUSRDMN is set to *ALL or if it contains QRPLOBJ, the replaced user space is moved to QRPLOBJ, which is cleared at system IPL. For details about authorities, ownership, and renaming, see the discussion of the REPLACE parameter in the Control Language (CL) information in the iSeries Information Center.
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.
The domain into which the user space is created. If this parameter is not specified, the value of *DEFAULT is assumed by the API.
Valid values for this parameter are:
| *DEFAULT | Allows the system to decide into which domain the object should be created. |
| *SYSTEM | Creates the user space object into the system domain. The API can always create a user space into the system domain regardless of the security level in effect. However, you must use APIs to access system-domain user spaces if you are running at security level 40 or greater. |
| *USER | Attempts to create the user space object into the user domain. This is not always possible. If the library you are creating the user space into does not appear in the QALWUSRDMN system value, the API cannot create the user space into the user domain. An error will be returned. |
The API uses the following values to determine into which domain to create the user space. The destination library is the library you specified in the qualified user space name parameter. The optional domain parameter is the information specified in the domain parameter.
| QALWUSRDMN System Value | Destination Library | Optional Domain Parameter | Domain of Created Object |
|---|---|---|---|
| *ALL | Any | *DEFAULT | User domain |
| *ALL | Any | *SYSTEM | System domain |
| *ALL | Any | *USER | User domain |
| QTEMP | QTEMP | *DEFAULT | User domain |
| QTEMP | QTEMP | *SYSTEM | System domain |
| QTEMP | QTEMP | *USER | User domain |
| Does not contain library name | Library name | *DEFAULT | System domain |
| Does not contain library name | Library name | *SYSTEM | System domain |
| Does not contain library name | Library name | *USER | None; error is returned |
| Note: The QALWUSRDMN system value lists the libraries into which user domain objects can be created. The libraries can be the special value *ALL or a list of one or more library names. | |||
You must use APIs to access data or information in system-domain user spaces on systems with a QSECURITY level of 40 or greater. You cannot use MI instructions to directly access system-domain user objects.
The Retrieve Object Description (QUSROBJD) or List Objects (QUSLOBJ) API can be used to determine into which domain the user-space object was created.
The number of pages to be transferred between main storage and auxiliary storage This is only a request, as the machine may use a value of its choice in some circumstances. Allowable values range between 0 and 32 pages. A value of 0 is an indication that the machine should use the default transfer size for the user space. If this parameter is not specified, the default is 0. A larger transfer size may allow for better performance of applications processing the user space.
Allows the machine to choose optimum alignment for the user space. Choosing optimum alignment is highly recommended. Applications that manipulate optimally aligned user spaces may perform significantly better.
Allowable values are:
| 0 |
Do not allow the machine to choose optimum space alignment. 0 is the
default value. |
| 1 | Choose optimum space alignment. |
Note: If not using the optimum space alignment, the user space has a maximum size of 16MB minus 512 bytes (16,776,704 bytes). If optimum alignment is specified, the maximum size of the user space is 16MB minus one disk page (current page size is 4096 bytes, giving a maximum space size of 16,773,120 bytes).
| Message ID | Error Message Text |
|---|---|
| CPF2143 E | Cannot allocate object &1 in &2 type *&3. |
| CPF2144 E | Not authorized to &1 in &2 type *&3. |
| CPF2283 E | Authorization list &1 does not exist. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C01 E | User space &2 in library &1 not created. |
| CPD3C01 D | Object name &1 is not valid. |
| CPD3C03 D | Extended attribute &1 is not valid. |
| CPD3C04 D | Value &1 for size parameter is not valid. |
| CPD3C05 D | Value &1 for authority parameter is not valid. |
| CPF3C2B E | Extended attribute &1 is not valid. |
| CPF3C2C E | Value &1 for size parameter is not valid. |
| CPF3C2D E | Value &1 for authority parameter is not valid. |
| CPF3C29 E | Object name &1 is not valid. |
| CPF3C34 E | Value &1 for replace option is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C45 E | Value &1 not valid for domain parameter. |
| CPF3C49 E | Request for user domain object cannot be granted. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3C91 E | Value &1 not valid for transfer size request parameter. |
| CPF3C92 | Value &1 not valid for optimum space alignment parameter. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9870 E | Object &2 type *&5 already exists in library &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| Top | Object API categories | API by category |