The Create User Space using XCL (CRTUSXCL) command creates a user space.

This function is also available with command CRTUSRSPC in library VC2XCL. Any use of this alternative command name should be library qualified in case the i operating system were to use this command name in a future release.

Parameters

User space (USRSPC)

Specifies the qualified name of the user space to create.

Restrictions:

• You must have *READ and *ADD authority to the library where the user space is to be created.
• When replacing an existing user space you must have *OBJMGT, *OBJEXIST, and *REQAD authorities to the existing user space.

This is a required parameter.

Qualifier 1: User space

name

Specify the name of the user space.

Qualifier 2: Library

*CURLIB

The current library for the job is used. If no current library entry exists in the library list, QGPL is used.

name

Specify the name of the library.

Pointer (PTR)

Specifies the CL variable to receive a pointer to the first byte of the user space.

Due to CL commands not allowing CL variables of TYPE(*PTR) to be passed as a parameter the CL pointer variable must be passed indirectly by declaring the pointer variable as being defined on a character variable. The following demonstrates how to do this.

Dcl        Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl        Var(&Pointer) Type(*Ptr) Stg(*Defined) +
             DefVar(&Chr_Ptr)
CrtUSXCL   UsrSpc(QTemp/MySpace) Ptr(&Chr_Ptr)

After the CRTUSXCL command runs the pointer variable &Pointer will address the first byte of the user space.

The defined on variable (DEFVAR) must be declared with a minimum length of 16 bytes. The CL pointer variable, declared with TYPE(*PTR), must be defined on a base 1 16-byte boundary of the DEFVAR variable.

character-value

Specify the name of the CL variable to receive the pointer value.

Initial size (SIZE)

Specifies the initial size of the user space. The actual size used by the system may differ slightly from the requested size.

4096

The user space will have an initial size of 4096 bytes (4K).

integer

Specify the initial size of the user space in bytes.

Varying size (VARSIZE)

Specifies if the user space size is to automatically grow, to a maximum of 16MB, if a program attempts to access data beyond the current size of the user space.

*NO

The user space size will not be extended beyond the current size.

*YES

Program attempts to access data beyond the current size of the user space will cause the user space to be extended to the requested size.

Authority (AUT)

Specifies the authority to the user space for users who do not have private authorities to the user space. This parameter is ignored when REPLACE(*YES) is specified and the user space currently exists. All authorities are transferred from the replaced user space to the new user space.

*LIBCRTAUT

The public authority for the user space is taken from the CRTAUT value for the target library.

*CHANGE

Users can read the object description of the user space and have read, add, update, and delete data authority to the user space.

*ALL

Users can perform all operations on the user space.

*USE

Users can read the object description of the user space and have read data authority to the user space.

*EXCLUDE

Users cannot access the user space.

character-value

Specify the name of an authorization list which defines user authorities to the user space.

Replace (REPLACE)

Specifies if an existing user space should be replaced by the request for a new user space.

*YES

An existing user space of the same name and library will be replaced.

*NO

An existing user space of the same name and libray will not be replaced. An error will be returned if an existing user space is found.

Text 'description' (TEXT)

Specifies text that briefly describes the user space.

*BLANK

No description is provided.

character-value

Specify a brief description of the user space.

Examples for CRTUSXCL

Example 1: Create a User Space Into QTEMP

CrtUSXCL   UsrSpc(QTEMP/MYSPACE)

This command creates the user space MYSPACE into the QTEMP library.

Example 2: Create a User Space and Return a Pointer Addressing the First Byte of the User Space

Dcl        Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl        Var(&Pointer) Type(*Ptr) Stg(*Defined) +
             DefVar(&Chr_Ptr)
Dcl        Var(&Byte)    Type(*Char) Len(1) +
             Stg(*Based) BasPtr(&Pointer)
CrtUSXCL   UsrSpc(QTemp/MySpace) Ptr(&Chr_Ptr)
ChgVar     Var(&Byte) Value('F')

This example creates the user space MYSPACE in library QTEMP with a pointer to the first byte of MYSPACE returned to CL variable &Chr_Ptr. The first byte of MYSPACE is then changed to the value 'F'. The CHGVAR command updates MYSPACE due to CL variable &Byte being declared as based on CL pointer variable &Pointer and the &Pointer variable is declared as being defined on the &Chr_Ptr variable value previously returned by the CRTUSXCL command.

Example 3: Using the Pointer

An example of using the pointer returned by the CRTUSXCL command can be found in member USPXMP of source file VC2XCL/QCLSRC. The example program displays the names of all objects, of a given type, that are found in a library.

Error messages for CRTUSXCL

*ESCAPE Messages

XCL500D

Function did not complete. See previously listed messages related to possible user errors.

XCL9002

Function did not complete. See previously listed messages related to possible user errors.

XCL9003

Function did not complete. See previously listed messages for possible cause.

XCL9004

Function did not complete. See previously listed messages for possible cause.

XCL9005

Function did not complete. Contact your service provider.