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:
- Space size
- Initial value
- Automatic extendibility
- 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 *
/Free
RtvPtrSpc( PxUsrSpc_q: pUsrSpc: ERRC0100 );
If ERRC0100.BytAvl = *Zero;
pSysPtr = setspfp( pUsrSpc );
If pSysPtr *Null;
mats( SPC_Templ_T: pSysPtr );
EndIf;
EndIf;
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
More...
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 spaces for list APIs
Materialize Space Attributes (MATS)
Modify Space Attributes (MODS)
Set System Pointer from Pointer (SETSPFP)
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
Articles on Apis 