DASD management is an inevitable chore that falls on someone’s shoulders in every shop. The falling price of even AS/400 drives has reduced the intensity of need to economize on disk space, but, like a basement, all drives gradually fill up with useless clutter. Whether one-time queries or obsolete data files, all objects need to be categorized and archived to be thrown in the bit bucket, and third-party tools seem to provide the most comprehensive toolset for organizing and reporting objects on a system.

IBM provides a variety of tools to help with this object management. You can, for instance, use PDM menus to view objects library by library and filter down to view just, say, physical files.

The Display Object Description (DSPOBJD) command is also a powerful tool. Many people have dumped the results of DSPOBJD into an outfile and massaged the data in Query/400 to satisfy a current need.

The Work with Objects by Owner (WRKOBJOWN) command shows objects owned by a particular user. Wily DASD management police can “encourage” users to manage their own mess (sorry, not “mess” but “mission-critical queries”) with WRKOBJOWN, and the command allows basic users to view all the objects they own and take matters into their own hands. Still, in my opinion, WRKOBJOWN should show the amount of space users occupy and the size of each object.

The Display Objects by Owner (DSPOBJOWN) command addresses this shortcoming and can be enhanced to address others. (The source code for this article is available for download from the Midrange Computing Web site at www.midrangecomputing.com/mc.) As shown in Figure 1, several objects make up DSPOBJOWN. The first part of the utility is the command entry. DSPOBJOWN, like WRKOBJOWN, has only the parameter User, whose default is *CURRENT. The RPG IV and CL source members should be created as modules and then bound together with the Create Program (CRTPGM) command. As shown in Figure 2, several APIs are used to retrieve and handle the object information displayed.

Retrieve Object Information Step-by-step

The RPG IV module drives the DSPOBJOWN utility, and the structures needed for the APIs are in the D-specs. (I did not include all the structures, only the information you need.

Review the manuals cited in the References and Related Materials section of this article to see what other information is available for future changes to the utility.) The retrieved object information is of two different types: standard AS/400 objects (such as *PGM, *FILE, and *OUTQ) and AS/400 Integrated File System (AS/400 IFS) objects (such as *DIR and *STMF). The need for this distinction will be made clear.

To begin, a user space is created in QTEMP and filled with a list of objects owned by the selected user. Before this information can be retrieved, the incoming parameter must be checked. If *CURRENT is chosen as the user, the name of the current user profile is retrieved from the program status data structure (PSDS). To retrieve a list of objects, the QSYSLOBJA (List Objects User Is Authorized to, Owns, or Is Primary Group of) API is used with the “object returned” option (field OBJ_Returned) of *OBJOWN. This security API can retrieve a variety of different object categories, but you are looking only for a list of objects associated with the specified user profile. DSPOBJOWN calls QSYSLOBJA twice. On the first call, you retrieve a list of AS/400 IFS objects, and, on the second call, you retrieve standard AS/400 objects. I use user spaces to store and retrieve this information.

A Step-by-step Review

To retrieve AS/400 IFS objects, the QSYSLOBJA call uses the unique format OBJA0310 (set by the OBJ_Format field), which varies in length because of the directory storage nature of the AS/400 IFS. The common Library/Object designation gives way to a UNIX branch file structure, and the two common AS/400 IFS objects are directories (*DIR) and stream files (*STMF). The QSYSLOBJA API places all this information in the user space created earlier in the program.

Retrieving information starts with the header structure, US_Header. The Retrieve AS/400 IFS Object (RTVIFSOBJ) subroutine has the main logic you should review. Since AS/400 IFS file names vary in length, some substring manipulation is needed to parse names properly. Once the file name has been extracted, notice that the desired information is stripped out and placed in the OBJA_Fields array.

The QSYSLOBJA API does not retrieve the objects in ascending order. To display the objects in any sorted order, you have to fill an array (OBJA_Fields) and sort it. The sorted array is written into the subfile. I have in the array two fields used for the AS/400 IFS file name. One of the fields (OBJA_IfsLoc) contains the full name and location of the AS/400 IFS directory or stream file; the other field (OBJA_DspLoc) displays this information on the screen. If the length of the location is greater than the space allocated in the subfile, the OBJA_DspLoc field is appended with a “>.” A longer version of the name can also be displayed by using function key F24.

As each AS/400 IFS object is retrieved from the user space, you have to call an AS/400 IFS API to retrieve the size of the object. The stat API retrieves a variety of information on AS/400 IFS files or directories, including their size in bytes. Notice the prototype structure created in the D-specs for the use of stat. Stat cannot be used with a call; it must be used with a function that has the proper prototype in place. Now your array has all the AS/400 IFS objects for the specified user.

Standard AS/400 objects are much easier to retrieve from the user space. For this information, object format OBJA0300 is used with the QSYSLOBJA API. The user space is not cleared or deleted; existing object information is overlaid. The header information tells how many objects are listed in the user space. The structure used to view object information is made of the easily recognizable 10-byte field that holds the library, type, and attribute of each object. As with AS/400 IFS objects, an additional API is needed to retrieve the size of the object. The Retrieve Object Description (QUSROBJD) API retrieves more than you would ever want to know about an object, even though you need only two pieces of information: the object size in bytes and the multiplier. The multiplier is usually 1, but I

go ahead and multiply the number of object bytes by the multiplier to produce the object size.

As stated earlier, all this useful information has been stored in an array sorted in descending order by library, object, and type. The program then counts down from the number of rows originally placed in the array to fill the subfile. The array is designed to hold 10,000 objects, and, depending on your uses, this number may need to be increased. Still, most users do not own 10,000 objects. As shown in Figure 3, the subfile is loaded, and the results are displayed. You now have a list of objects, with the size of each object displayed. Also displayed at the top of the screen is the total number of objects and total size of those objects.

CL Does the Work

DSPOBJOWN lets you perform the same object management tasks as WRKOBJOWN. Users can delete their own files, copy them to an archive library, change object ownership, and display various attributes. All these options are executed in the CLLE program DSPOBJOWNC, and a series of parameters is passed to indicate what function to execute and what object to be affected.

The DPSOBJOWNC program has marked each object in the subfile as either “400” or “IFS.” AS/400 IFS object management commands are different from standard OS/400 object commands. To display an AS/400 IFS object’s authority, use the Display Authority (DSPAUT) command. For a standard AS/400 object, use Display Object Authority (DSPOBJAUT). Figure 4 lists the functions DSPOBJOWN provides and divides them into AS/400 IFS object commands and standard AS/400 object commands. By flagging each type of object as you retrieve it, you control execution of the proper CL command.

In addition, a Monitor Message (MONMSG) command is used in module DSPOBJOWNC to trap any command failures. In the event of an error, an error flag is set, and the Move Program Messages (QMHMOVPM) API is executed. This messaging- handling API retrieves the last error message for display in the controlling program DSPOBJOWN. DSPOBJOWN also sees that an error has occurred and can display a message of your choice in addition to the system message.

Room to Grow

The modular format of DPSOBJOWN makes it relatively simple to add object manipulation functionality to it in the future, in case you want to tailor the functions that certain users can use. By giving individual users the power to police their own DASD, you can distribute the burden of the job. There are many occasions in which individuals have honestly forgotten how much clutter their libraries have accumulated. Using a tool like this as a standard practice will keep your system cleaner.

REFERENCES AND RELATED MATERIALS

• OS/400 Message Handling APIs V4R4 (SC41-5862-03, CD-ROM QB3AMN03)
• OS/400 Object APIs V4R4 (SC41-5865-03, CD-ROM QB3AMQ03)
• OS/400 Security APIs V4R4 (SC41-5872-03, CD-ROM QB3AMX03)

Name Object Type Source Type Description

DSPOBJOWN Command CMD Command interface DSPOBJOWN Program Created from two modules DSPOBJOWN Module RPGLE Manages object APIs and builds subfiles of object information
DSPOBJOWNC Module CLLE Performs CL functions on objects selected in

DSPOBJOWN DSPOBJOWND File DSPF Display file DOOMSGF MSGF Stores program error messages

Figure 1: The DSPOBJOWN utility consists of these objects.

API Description

QUSRTVUS Retrieves user space QUSROBJD Retrieves object description QUSCRTUS Creates user space QSYSLOBJA Retrieves objects owned by particular user
QUSDLTUS Deletes user space QMHRMVPM Clears program message queue QMSNDPM Sends message to program message queue
stat Retrieves AS/400 IFS file information

Figure 2: DSPOBJOWN uses these APIs.

Figure 3: DSPOBJOWN displays object information in the traditional “work with” format.

Function AS/400 IFS Object Command Standard Object Command

Displays different

DSPAUT DSPOBJAUT groups authorized
to object
Creates duplicate of file CPYFRMSTMF CRTDUPOBJ Deletes file RMLNK
Deletes directory RMDIR
Deletes various object DLTxxxx

DSPOBJD *FULL

types (e.g., *FILE, *PGM,
and *LIB)

Displays object’s full attributes
Displays object’s service DSPOBJD *SERVICE attributes
Changes object’s ownership CHGOWN CHGOBJOWN

Figure 4: DSPOBJOWN offers these functions.

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?