APIs by Example: User Space APIs

Anyone who has been programming APIs for some time will probably be familiar with user space objects. The original list APIs, such as the List Objects (QUSLOBJ) or the List Job (QUSLJOB) API, almost all return the requested information to a user space. A user space basically is a chunk of storage of up to 16MB that can be used for any purpose requiring you to store or share data. User spaces can be changed to automatically extend its size if needed, and a user space can be backed-up. As any other object on the System i, it will also record access and supports object security and auditing.

To enable programmers to take efficiently advantage of user spaces, IBM has added support for pointer access to user spaces in the programming languages capable of defining and manipulating space pointers. To manage and work with user space objects there are a number of APIs available, but only one CL command – the Delete User Space (DLTUSRSPC) command.

To stick to the truth, as rarely as such an ambition may seem these days, there are also two CL commands available to display and edit files in the Integrated File System (IFS) – the Display File (DSPF) and Edit File (EDTF) commands, respectively – that can be employed to perform their powers against user spaces. To further expand on the toolset available to create and manage user spaces IBM also added a number of user space APIs to create user spaces, change and retrieve user space content, as well as change user space attributes, respectively.

In today’s APIs by Example article I offer CL command interfaces to the user space APIs mentioned, and to tie everything nicely together, also include a new Work with User Spaces (WRKUSRSPC) command. To complete the full circle, I plan to show an example in an upcoming article of how to employ a user space to keep track of journal entry processing, using the Receive Journal Entry (RCVJRNE) command and an associated journal entry exit program.

The Create User Space (CRTUSRSPC), Change User Space (CHGUSRSPC) and Retrieve User Space (RTVUSRSPC) CL commands are all very simple command front-ends for the respective user space API. Each user space API is specified directly as the associated command’s command processing program (CPP). I have previously discussed this technique in the article APIs by Example: APIs and CL Command Interfaces, to which you will find a link in the “More information” section at the end of this article.

The Change User Space Attributes (CHGUSRSPCA) command did however require a bit more work to complete. For obvious reasons I wanted the CHGUSRSPCA command to retrieve and display the current attribute values, when the command is prompted. The Change User Space Attributes (QUSCUSAT) API enables you to change the following four attributes:

  1. Space size
  2. Initial value
  3. Automatic extendibility
  4. Transfer size request

The Retrieve User Space Attributes (QUSRUSAT) API however, only allows you to retrieve three of those attributes, as the Transfer size request is not included. Luckily, the API documentation does mention the Materialize Space (MATS) machine interface (MI) function as an alternative source of space attribute information, so I simply resorted to that option in my command prompt override program.

The transfer size request attribute would continue to challenge me however, as I went on to code the command processing program actually performing the update of the user space attributes. It turned out that the QUSCUSAT API willingly would change the space size, initial value and the automatic extendibility attributes, but not under any circumstances would it change the transfer size request. The QUSCUSAT API call would run successfully, but upon the next command prompt the specified user space’s transfer size request would appear unchanged.

I have not yet had time to investigate this issue further or to open an APAR with IBM, so to circumvent the problem for now, I decided to go further down the MI road, and simply employ the Modify Space Attributes (MODS) MI function. This approach worked brilliantly without further complications, and thereby also incidentally serves as an example of how to call the MODS MI function.

Another takeaway from the MATS and MODS approach is a demonstration of how to get a system pointer to an object using a space pointer, rather than a call to one of the Resolve System Pointer (RSLVSP) MI functions. The advantage being that the Retrieve Pointer to User Space (QUSPTRUS) API, which returns a space pointer to a user space, will communicate any errors encountered in the common API error data structure, as opposed to the brutal and sometimes cryptic exception messages returned by the RSLVSP MI functions.

The MATS and MODS MI functions identify the user space to access by means of a system pointer to the user object in question, rather than a qualified object name as regular APIs do. Here’s a code snippet showing how to employ the Set System Pointer from Pointer (setspfp) MI function to obtain a system pointer from a space pointer, which then in turn is used by the Materialize Space Attributes (mats) MI function to retrieve the user space attributes:

**-- Retrieve pointer to user space:                                    
D RtvPtrSpc       Pr                  ExtPgm( 'QUSPTRUS' )              
D  SpcNam_q                     20a   Const                             
D  Pointer                        *                                     
D  Error                     32767a         Options( *NoPass: *VarSize )
D mats            Pr                  ExtProc( 'mats' )                 
D  Template                           Const  Like( SPC_Templ_T )        
D  SpcPtr                         *   Value  ProcPtr                    
D setspfp         Pr              *   ProcPtr  ExtProc( 'setspfp' )     
D  SpcPtr                         *   Value                             
**-- Local declarations:                      
D pSysPtr         s               *   ProcPtr 
D pUsrSpc         s               *           
   RtvPtrSpc( PxUsrSpc_q: pUsrSpc: ERRC0100 );                          
   If  ERRC0100.BytAvl = *Zero;              
     pSysPtr = setspfp( pUsrSpc ); 
     If  pSysPtr  *Null;      
       mats( SPC_Templ_T: pSysPtr );    

If you’d rather use one of the RSLVSP MI functions, you can find an example in the code accompanying the following previously published article:
APIs by Example: User Queues Part 2

You will find the RSLVSP MI function code example in the subprocedure named GetSysPtr() in the source member for the service program CBX115S.

The Work with User Spaces (WRKUSRSPC) command has the following appearance when prompted:

                        Work with User Spaces (WRKUSRSPC)                    
 Type choices, press Enter.                                                  
 User space . . . . . . . . . . .                 Name, generic*, *ALL       
   Library  . . . . . . . . . . .     *LIBL       Name, *LIBL, *CURLIB...    
 Space attribute  . . . . . . . .   *ALL          Name, generic*, *ALL       
 Sort order . . . . . . . . . . .   *USRSPC       *USRSPC, *LIB   

The WRKUSRSPC command allows you to specify either object name or library as primary and secondary sort order for the command’s user space list output, respectively, and has the following work-with panel :

                            Work with User Spaces                      APIMYMY
                                                       16-10-18  13:28:12 CEST
Type options, press Enter.                                                    
  1=Change   2=Edit        3=Copy   4=Delete     5=Display   7=Move/Rename    
  8=Display object descr   9=Change attributes   13=Change object desc        
Opt  User space  Library     Attribute   Extend        Size  Text             
     QTOUTELNET  QUSRSYS     CONTROL      *NO         16384  TCP/IP Configurat
     QTOUTFTP    QUSRSYS     CONTROL      *NO         16384  TCP/IP Configurat
     QTOUVPN     QUSRSYS     CONTROL      *NO         16384  TCP/IP Configurat
     QUSY2ASP    QUSRSYS                  *NO          7680                   
     QYPSOBJFAC  QUSRSYS     USRSPC       *YES         3584                   
     QZDATRC     QUSRSYS                  *NO         36352  User space create
     QZDFSTRCC   QUSRSYS                  *NO          4096  Datalinks File Sy
     QZHQTRC     QUSRSYS                  *NO         36352  User space create
     QZRCTRC     QUSRSYS                  *NO         36352  User space create
     QZSCTRC     QUSRSYS                  *NO         36352  User space create
     QZSOTRC     QUSRSYS                  *NO         36352  User space create
Parameters or command                                                         
F3=Exit   F4=Prompt     F5=Refresh   F6=Create user space   F9=Retrieve       
F11=Display full text   F12=Cancel   F17=Top   F18=Bottom   F21=Command menu  

The panel options expose all the user space commands discussed earlier as well as a few other commands, that are useful to keep handy when working with user spaces. Here’s a brief explanation of the options available above:

1=Change User Space (CHGUSRSPC) 
2=Edit File (EDTF)
3=Create Duplicate Object (CRTDUPOBJ)
4=Delete User Space (DLTUSRSPC)
5=Display File (DSPF)
7=Move and Rename Object (MOVRNMOBJ)
8=Display Object Description (DSPOBJD)
9=Change User Space Attributes (CHGUSRSPCA)
13=Change Object Description (CHGOBJD)  

In addition to the above list of user space related commands, the list panel also supports command key F6 which will run the Create User Space (CRTUSRSPC) command.

The following source members are included in the zip-file containing all the user space CL commands mentioned in this article:

CBX310M  CLP     User Space Commands - Build commands  
CBX310U  UIM     User Space Commands Menu              

CBX310H  PNLGRP  Create User Space                     
CBX310X  CMD     Create User Space                     

CBX311H  PNLGRP  Change User Space                     
CBX311X  CMD     Change User Space                     

CBX312H  PNLGRP  Retrieve User Space                   
CBX312X  CMD     Retrieve User Space              

CBX313   RPGLE   Change User Space Attributes – CPP
CBX313H  PNLGRP  Change User Space Attributes - Help
CBX313O  RPGLE   Change User Space Attributes - POP 
CBX313V  RPGLE   Change User Space Attributes - VCP 
CBX313X  CMD     Change User Space Attributes

CBX314   RPGLE   Work with User Spaces - CCP               
CBX314E  RPGLE   Work with User Spaces - UIM Exit Program  
CBX314H  PNLGRP  Work with User Spaces - Help              
CBX314P  PNLGRP  Work with User Spaces - Panel Group       
CBX314V  RPGLE   Work with User Spaces - VCP               
CBX314X  CMD     Work with User Spaces    
CBX314M  CLP     Work with User Spaces - Build Command     

The Rename/Move option on the Work with User Spaces list panel is dependent on the Move and Rename Object (MOVRNMOBJ) command made available here.

To create all above CL commands download all source members into the respective source files on your System i. Compile and run the CBX310M and CBX314M CL programs, they will take care of running all the necessary create-commands. Both programs expect a single 10-byte character parameter, specifying the library containing the aforementioned source files. All command objects created will also be placed in this library.

You’ll also find compilation instructions in the respective source headers of the individual sources.

Download the UsrSpcCmd zip file containing the source code.

More information
You can find more information on the user space topic following the links below:

IBM APIs – User Space APIs

IBM APIs – User spaces

IBM APIs – User spaces for list APIs

Materialize Space Attributes (MATS)

Modify Space Attributes (MODS)

Set System Pointer from Pointer (SETSPFP)

Set Access State (SETACST)

Change Object Description (QLICOBJD) API

IBM Knowledge Center – Manipulating a user space with pointers

IBM Object operations and auditing – Operations for User Space (*USRSPC)

TechTip: User Space Tricks That You Might Have Never Thought Of

IBM Systems Mag – User Spaces and List APIs

The CL Corner: Incrementing a Numeric Value Across Jobs

APIs by Example: Locking Parts of a User Space

APIs by Example: APIs and CL Command Interfaces

User Space Objects QP0Z* in QUSRSYS


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s