Create User Space (QUSCRTUS) API


  Required Parameter Group:

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)

  Optional Parameter Group 1:

7 Replace Input Char(10)
8 Error code I/O Char(*)

  Optional Parameter Group 2:

9 Domain Input Char(10)

  Optional Parameter Group 3:

10 Transfer size request Input Binary(4)
11 Optimum space alignment Input Char(1)

  Default Public Authority: *USE

  Threadsafe: Yes

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.


Authorities and Locks

User Space Authority
*OBJMGT, *OBJEXIST, and *READ. These authorities are required only if the replace parameter is used and if there is an existing user space to replace.
User Space Library Authority
*READ and *ADD.
User Space Lock
*EXCL. This applies to both the user space being created and an existing user space being replaced.

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 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.

Extended attribute
INPUT; CHAR(10)

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.

Initial size
INPUT; BINARY(4)

The initial size of the user space being created. This value must be from 1 byte to 16, 776, 704 bytes.

Initial value
INPUT; CHAR(1)

The initial value of all bytes in the user space. You will achieve the best performance if you set this byte to X'00'.

Public authority
INPUT; CHAR(10)

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.

Text description
INPUT; CHAR(50)

This text briefly describes the user space.


Optional Parameter Group 1

Replace
INPUT; CHAR(10)

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:
  • The allow user domain (QALWUSRDMN) system value is not set to *ALL or does not contain the library QRPLOBJ.
  • The user space you are replacing is in the user domain.

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 topic collection.

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

Domain
INPUT; CHAR(10)

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.


Optional Parameter Group 3

Transfer size request
INPUT; BINARY(4)

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.

Optimum space alignment
INPUT; CHAR(1)

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:

1 Choose optimum space alignment. 1 is the default value.
0 Do not allow the machine to 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).


Error Messages

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.


API introduced: V1R3

[ Back to top | Object APIs | APIs by category ]