Learn some seldom-known yet practical techniques to utilize User Space Objects.

Before I read the post Re: *Usrspc question by Simon Coulter in 2001 in the Midrange-l mailing list, I had never known that the Display File (DSPF) command can be used to display or change the contents of a User Space (*USRSPC) object. I realized that as a special type of space object designed to be used by user programs, *USRSPC objects are treated slightly differently from other MI space objects by some OS-level utilities. In this article, I'll introduce several tips about utilizing *USRSPC objects that will probably ease your daily work quite a lot. For detailed discussion about how to use *USRSPC objects via CL commands, APIs, or MI instructions, please refer to the following resources:

• Using User Space APIs in the Information Center
• User Space APIs in the Information Center
• Space Management and Space Addressing MI instructions

Work with *USRSPC Objects via the DSPF and EDTF Commands

The Display File (DSPF) and Edit File (EDTF) commands allow users to display or change the content of either a stream file or a member of a database file. (Note that the EDTF command works only with source physical files or data physical files that are not externally described.) As mentioned, they can also be used to display or change the content of a *USRSPC object. When data stored in a *USRSPC object is in text format, it's pretty handy to be able to display or change the content of the *USRSPC via the DSPF and EDFT commands.

To edit the character content of a *USRSPC object, you can issue an EDTF command against the *USRSPC object and set the Stream file (STMF) parameter to the IFS path name of the *USRSPC—for example, EDTF STMF('/qsys.lib/lsbin.lib/spc0f.usrspc'). EDTF is an editor that is similar to the Source Entry Utility (SEU). It provides similar edit commands (line commands), such as I (Insert a line), MM (Block move), and An (After with repeat n times), and control commands, such as F (or FIND), C (or CHANGE), etc.

To browse the data content of a *USRSPC object, you can issue a DSPF command and specify the IFS path name of the *USRSPC object as the STMF parameter of the DSPF command—for example, DSPF STMF('/qsys.lib/lsbin.lib/spc0f.usrspc'). DSPF supports control commands similar to those supported by EDTF. In addition to displaying the data content in character form, DSPF can also display the data content in hexadecimal representation. You can switch to or back from hexadecimal display by pressing function key F10.

Note that if the data content of a *USRSPC object contains newline characters (*CR, *LF, *CRLF, *LFCR), DSPF or EDTF separates lines according the newline characters in the data content. If the data content of a *USRSPC object does not contain any newline characters, DSPF and EDTF will adopt an arbitrary record length of 80 and 75, respectively; in other words, DSPF/EDTF displays each 80-character/75-character as one line.

Work with *USRSPC Object from Within a Shell Environment

A *USRSPC object can be used as the source of an input redirection or the target of an output redirection. For example, the following shell command issued in a QShell or PASE shell session will redirect both the standard output and the standard error generated by the list of shell commands to *USRSPC object QGPL/SPC0A.

Note that the output redirection will create the target *USRSPC object if it doesn't already exist or cause the existing *USRSPC object to be extended or truncated to proper size. Also, the appending redirection operator >> cannot be used on a *USRSPC object.

The sort command in the following example redirects the standard input to *USRSPC object QGPL/SPC0A and sorts the names stored in QGPL/SPC0A.

Note that QShell and PASE shell use different character encoding (EBCDIC and PC character encoding, respectively), so you should not use the data content stored in a *USRSPC object by QShell as the input of a PASE shell command or program, and vice versa.

Besides input/output redirection, a *USRSPC object can also be used as the source or destination argument of the file operation command cp. For example, the following PASE shell commands copy PASE program echo into the associated space of *USRSPC QGPL/SPC0B and then copy the content of QGPL/SPC0B to a new PASE program shout.

Exchange Information with Shell Programs via *USRSPC Objects in a Native HLL Program

The QShell utilities and the PASE shell utilities are necessary for managing Integrated File System (IFS) objects. They are also helpful for developers and operators to work with /QSYS.LIB objects from the CL environment or programs written in native High Level Languages (HLL)—for example, you can use a QShell (or PASE shell) <I>find command to look up source members by name, file type, last access time, etc. However, for IBM i HLL programs, it's still inconvenient to exchange information with shell commands or programs—for example, receiving the output of a shell command. One possible solution is to store information to be shared with shell commands or programs in *USRSPC objects.

Imagine that you are expected to collect all source members with a specific library that have been modified within a week and write the source member names to a database file or a spooled file. To achieve your goal, you may follow these steps:

1. Run a QShell find command to list the source members that satisfy the search criteria (being modified within a week), and redirect the output of your find command to a *USRSPC object (say, MYGPL/ONEWEEK). The QShell find command might look like this: find /qsys.lib/mysrclib.lib -type f -ctime -7 > /qsys.lib/mygpl.lib/oneweek.usrspc.
2. Read the search result stored in MYGPL/ONEWEEK in an RPG program, parse the character lines, and write them to a database file or a spooled file.

The following example CL program spc01.clp and RPG program spc02.rpgle demonstrate the above shown steps.

SPC01

SPC02

The Retrieve Pointer to User Space (QUSPTRUS) API is used to retrieve the space pointer addressing the associated space of the target *USRSPC object, and the Retrieve User Space Attributes (QUSRUSAT) API is used to materialize the space size (the size of the associated space) of the target *USRSPC object. The Find Character Constrained (MEMCHR) system built-in is prototyped in mih-comp.rpgleinc.

Call SPC01 and specify the proper source library and result *USRSPC library parameters. The result might look like the following:

One More Thing

For your convenience, I'd like to mention something off topic. Suppose all you care about from a submitted QShell command is the return code. You can retrieve the return code of a QShell command via the Start QSH (STRQSH) command. You can receive the completion (*COMP) message (with message ID QSH0005) sent to the call message queue via STRQSH as shown here:

The QSH#### messages are defined in message file (*MSGF) QSHELL/QZSHMSGF.