CRTUSRSPC (Create User Space)

The CRTUSRSPC command greatly simplifies creating objects of type *USRSPC. User Space objects are used with many IBM i APIs. The COZTOOLS also includes a RTVUSRSPC CL Command that allows user space objects to be used in a way similar to Data Areas but without the size limitation of Data Areas.

Parameters

USRSPC - The qualified user space name being created.

SIZE - The initial size (in bytes) of the User Space. Several special size values may be used to simplify entering the initial size:

• 1k = 1024
• 1M or 1MB = 1048576
• *MAX = 1675566

OBJATR - The extended object attribute assigned to the user space. This can be helpful to identify what is stored in the user space. For example, a user space created within COZTOOLS might include an OBJATR(COZTOOLS). Up to 10 characters may be specified or the special value *BLANK may be used to assign no extended object attribute.

AUTOEXT - The auto-extend attribute allows the user space to automatically grow if necessary. This is triggered when data is written beyond the current length of the user space. For example, if the current length is 1000 bytes and the user attempts to store information in position 128 of the user space, user space management automatically extends the user space's size to at least 128 bytes. When AUTOEXT(*NO) is specified, length of the user space is fixed as the value specified on the SIZE parameter. In this situation, an error will be generated if the end-user attempts to write or read beyond the current length of the user space.

INZ - This character value is used to initialize the user space when it is created or extended. By default the internal IBM i API default to X'40' (blanks) for the initialization character; this is very inefficient. It is recommended that user space objects use the X'00' character for their initialization character. To specify that X'00' is used, specify INZ(*NULL) for this parameter. Any other character or hexadecimal value may be specified. 

AUT - The public authority to the user space. This is the same parameter on all CRTxxx object commands and supports the same values.

REPLACE - If the user space exists, specify REPLACE(*YES) to have it replaced, otherwise use the default REPLACE(*NO) value.

TEXT - Specify up to 50 characters of the user space object's text description.

DOMAIN - This optional parameter may be used to create the user space object in the User Domain or System Domain. Typically this parameter is not used, and its default DOMAIN(*USER) is specified.

Example: Create a User Space in QGPL named OBJLIST

CRTUSRSPC USRSPC(QGPL/OBJLIST) SIZE(1MB) OBJATR(BOB) TEXT('Used to receive object list for QUSLOBJ API')

The CRTUSRSPC command is part of the COZTOOLS software package available beginning May 1, 2012 from www.cozTools.com

Components:

• CRTUSRSPC Command Definition
• CRTUSRSPC RPG IV Program

Requirements:

• IBM i v5.4 or later
• COZTOOLS