24 User Spaces
This chapter contains these topics:
24.1 About User Spaces
User spaces are IBM Operating System objects managed by Application Program Interfaces (APIs) to store data. User Object APIs create, manipulate, and delete user spaces and indexes. An API provides you with:
-
A faster method of retrieving information
-
A means of dynamically modifying sizes
-
A means of manipulating user objects
You should place your user spaces in library QTEMP so that it is deleted automatically when the user signs off.
24.2 What Is a User Space?
A user space is an object made up of a collection of bytes that are used for storing any user defined information.
When you use a user space, there is no key to retrieve the information placed in the space. Therefore, the information in the user space is in the order that it was entered. A user space can store up to 16 megabytes of information.
Note:
To see the contents of a user space, enter the command DMPOBJ (Dump Object) from any command line after the space has been loaded.24.3 What Are the Advantages of Using a User Space?
The main advantage of using a user space is its speed. Because a user space consists of a string of bytes instead of elements like an array, you can write and retrieve records faster using a user space than an array.
In addition to speed, a user space provides you with more flexibility. A user space does not have a fixed record length. When you write a record to a user space, you define the length of that record. Therefore, each record you write to your user space can be a different size. In addition, it is possible to dynamically increase the size of your user space by calling the Enter User Space program (X00SPC) after creating the user space.
For example: @EX 999 30
The array @EX has a fixed record length of 30, therefore no record smaller or larger than 30 bytes can be written to this array.
User spaces are also used when communicating between two programs. The space can carry information loaded in one program to another program for retrieval.
For example: Program A creates the user space and loads information into a user space. Then Program A calls Program B and passes the name of the user space to it. Program B can retrieve information from the user space that was loaded by Program A.
24.4 How Does a User Space Function?
Remember that a user space is nothing more than a collection of bytes used to store information.
You write information to a user space, as well as retrieve information from it. Since there is no key associated with a user space, the information contained in a user space is in a user-defined order. The order is based on program controlled offset and length values.
24.5 Creating a User Space
-
Determine if a user space already exists by using the JD Edwards World program J98CKOBJ.
PARM (Length) Description PSOBJ (10) The name of your user space. PSLIB (10) The name of the library in which you wish to check for the existence of the user space. Generally, this is *LIBL to check all of the libraries in the library list. PSTYPE (8) The type of object you are checking for. Generally, this is *USRSPC for a user space. PSMID (10) The member ID if you are checking for a database file. Generally, this is *NONE. PSAUT (10) The authority or authorization list to be checked for the user. Generally, this is *NONE. PSERR (1) The error parameter that will indicate an error while checking your object. Generally, this is initialized with *BLANK. 0 – No authority
1 – Not found
3 – No library
4 – Member not found
5 – No authority to library
6 – Cannot assign library
-
Do one of the following:
-
If a user space does exist you should clear it and write your new information over the old.
-
If the user space does not exist and no errors occurred, you can create your user space. To create a user space, use the QUSCRTUS (Create User Space) command.
-
| PARM (Length)) | Description |
|---|---|
| #SPNAM (20) | The first 10 characters contain your user space name, and the second 10 characters contain the name of the library where your user space is located. Remember; place your user space in library QTEMP to automatically delete your space when you sign off. |
| #SPATT (10) | The extended attribute of your user space. You may use this field to classify your user space. For example, JD Edwards World uses this field to label all of the user spaces with JD Edwards World. |
| #SPSIZ (4 binary) | The initial size of your user space. Any value from 1 byte to 16 megabytes. |
| #SPVAL (1) | The initial value of all bytes in the user space. Generally, this is *BLANK. |
| #SPAUT (10) | The authority you give users to your user space. Generally, this is *ALL. |
| #SPTXT (50) | The text description of your user space. |
To dynamically increase the size of your user space when maximum allocation is reached, call the Enlarge User Space program (X00SPC).
| PARM (Length)) | Description |
|---|---|
| #XSPCN (20) | The first 10 characters contain your user space name, and the second 10 characters contain the name of the library where your user space is located. |
| #XRQSZ (15,0) | The requested size to increase your space. |
| #XERR (1) | An error flag:
1 – Space not found 2 – Not authorized 3 – Error |
24.6 Writing to a User Space
Use either the QUSCHGUS or the X98CHGUS (Change User Space) command.
| PARM (Length)) | Description |
|---|---|
| #SPNAM (20) | The first 10 characters contain your user space name, and the second 10 characters contain the name of the library where your user space is located. |
| #SPPOS
(4 binary) |
The starting position in your user space where the information will begin. It must be the first byte and must have a value greater than 0. |
| #SPLGH
(4 binary) |
The length of the information that is being written to your user space. This field is user-defined, but it must be greater than 0. |
| #SPVAL
(* user defined) |
The actual information to be written to your user space. The field must be at least as long as the length parameter. |
| #SPAUX (1) | Used to force changes made to your user space to auxiliary storage, such as a disk. The valid values are:
0 – do not force changes 1 – write changes 2 – write changes immediately |
Note:
The X98CHGUS program, JD Edwards World's version of the IBM command QUSCHGUS, will perform a transfer control to QUSCHGUS.24.6.1 Tracking Information if Writing Variable Length Records
During the process of writing information to your user space, you should keep track of a pointer. This will ensure that you will not overwrite information or retrieve incorrect information.
One way to keep track of the pointer is to initialize it to 1. After you write information to your user space, add the length of the information to your pointer. The pointer is now set at the next starting point and ready for you to enter new information.
If the information you are writing to your user space contains various lengths, you should maintain the length of each piece of information in save fields. You can use the save fields when you wish to retrieve the information from your user space.
You can also reserve the first 2 or 3 bytes of every record for the size of that record. Then you would only have to load that part of the record with its length. When you read the record from the user space, the first 2 or 3 bytes will tell you how long the record is.
24.7 Reading from a User Space
Once you have loaded information into your user space, you are ready to retrieve it. Do not forget that your pointer must be set to the proper starting position to ensure the correct information is retrieved.
Use the QUSRTVUS (Retrieve User Space) command.
| PARM (Length)) | Description |
|---|---|
| #SPNAM (20) | The first 10 characters contain your user space name, and the second 10 characters contain the name of the library where your user space is located. |
| #SPPOS
(4 binary) |
The starting position in your user space where the information will begin. It must be the first byte and must have a value greater than 0. |
| #SPLGH
(4 binary) |
The length of the information that is being retrieved to your user space. This field is user-defined, it must not be larger than the variable that will receive the information, and it must be greater than 0. |
| #SPREC
(* user defined) |
The variable that will receive the information from your user space. |