Thursday, August 7, 2014

User Spaces introduction continued

user space, quscusat

After publishing yesterday's post User Spaces introduction Sam posted a comment:

It seems you forgot one important thing: Change User Space Attribute API
Automatic extendibility. Whether or not the user space is automatically extended by the system when the end of the space is encountered.
0 The user space is not automatically extendible.
1 The user space is automatically extendible.

While I write each post I test the code I give as examples. I did not encounter an error while testing that the User Space was full. But that could be that I did not fill the 128k size I made the User Space in my example.

Perhaps I needed to use a file with more fields? Or what would happen if I created the User Space with a size of 1 byte?

First let me start with the Change User Space Attribute, QUSCUSAT, API. I am just going to include it in the example I gave in the User Spaces introduction example.

QUSCUSAT API has four parameters:

  1. Returned library name, 10 character. If the change is successful this will contain the name of the library that the User Space is in.
  2. Qualified user space name, 20 character, User Space name 1-10 and library 11-20.
  3. Attribute, 64 character. To change the User Space to automatically extend this needs to be '1'.
  4. Error code, 32767 character. I will use the QUSEC data area.

Below is the prototype for this API in both free format and fixed format RPG.

  dcl-pr ChgUserSpace extpgm('QUSCUSAT') ; 
    *n char(10) const ;  // Returned library name
    *n char(20) const ;  // Name 
    *n char(64) const ;  // Attribute to change
    *n char(32767) options(*varsize:*nopass) ;  // Error feedback
  end-pr ; 

  D ChgUserSpace    PR                  extpgm('QUSCUSAT')
   * Returned library name 
  D                               10A   const
   * Name 
  D                               20A   const 
   * Attribute to change 
  D                               64A   const 
   * Error feedback 
  D                            32767A   options(*varsize:*nopass)

I also need to add a field to contain the returned library name:

  dcl-s ReturnedLib char(10) ;

  D ReturnedLib     S             10  

I would insert the call to this API just after where I call the CrtUserSpace in my previous example, at line 38.5 .

  ChgUserSpace(ReturnedLib:'@USRSPACE QTEMP':'1':QUSEC) ;

Now my User Space is automatically extending.

I went on to test did I really need to do this as was I correct in thinking that the User Space the way I defined it in my previous post would extended automatically. Rather than test the two scenarios I mentioned above individually I decided to do them both at the same time.

Using my original example, without QUSCUSAT, I created my User Space with an initial size of 1 byte, and used a file with 240 fields.

I would change the third parameter in the CrtUserSpace, Initial user space size, to 1. This must be the smallest size you can create a User Space.

  CrtUserSpace('@USRSPACE QTEMP':'':1:x'00':                      
               '*ALL':'List of fields':'*YES':QUSEC) ;

I changed the call to ListFields from my TESTFILE to the file with the 240 fields.

When I run my modified example program it displays all 240 fields.

It would appear that the User Space is being automatically extended as I cannot imagine that the data for the 240 fields would fit in 1 character.

I do want to thank Sam for his comment as while the User Space does appear to automatically extend in IBM i version 7.1 it may not in other releases. Or perhaps the data for the 240 fields does somehow fit in 1 character. Whichever is true this is another useful User Space API to be aware of.


More information about these keywords can be found on the IBM website about QUSCUSAT here.


This article was written for IBM i 7.1, and it should work with earlier releases too.


  1. Also be aware of another gotcha when using user spaces between v5r4 and v6r1. IBM decided to change the default value of the optional parameter optimum space alignment from 0 to 1. This results in your space being smaller than it was pre v6r1 so if you are detecting the end of the space using non optimum space alignment with the default you may now get a mch3601 space pointer not set for location reference when you run off the end of the shorter space. Naughty IBM!

  2. Userspaces are allocated in increments of 4K pages. So you can't really have a user space of size= 1 byte. I suspect your file is small enough that you didn't 'run off the end' of the allocated storage. You may get more bytes than you ask for, but you won't get less (unless you get an error!) I think the alignment option set to 0 may give you a partial 4K page at the start of your allocation.


To prevent "comment spam" all comments are moderated.
Learn about this website's comments policy here.

Some people have reported that they cannot post a comment using certain computers and browsers. If this is you feel free to use the Contact Form to send me the comment and I will post it for you, please include the title of the post so I know which one to post the comment to.