Create User Space (QUSCRTUS) API


  Required Parameter Group:


  Optional Parameter Group 1:


  Optional Parameter Group 2:


  Optional Parameter Group 3:


  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:


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:


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:


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.


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:


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



API introduced: V1R3

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