This week's issue of APIs By Example will focus on the Open List of ASPs (QYASPOL) API. This API is capable of returning different types of information about ASPs, including ASP configuration, ASP attributes, and disk units. As you probably already know, ASP is an abbreviation for Auxiliary Storage Pool, which in turn is a term describing a collection of disk units on the iSeries system.

The following IBM technical document details the different types of ASPs available, as well as their usage:
http://www-912.ibm.com/s_dir/slkbase.NSF/0/802643df554de73586256d930060d7c4?OpenDocument [2]

I have written the Retrieve ASP Information (RTVASPINF) command to demonstrate the use of the QYASPOL API. The command also serves as an example of the information made accessible by this API.

The RTVASPINF command returns a number of the basic attributes included in the APIs YASP0200 format. In the next installment of APIs By Example, I will present yet another command, based on the YASP0300 format that offers information about each of a system's individual disk units.

The command prompt below displays all the ASP attributes that can be retrieved by the RTVASPINF command:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =  
                   Retrieve ASP Information (RTVASPINF)        
Type choices, press Enter.                                       
ASP number . . . . . . . . . . .   *SYSASP       2-255, *SYSASP  
CL var for RTNASP      (3 0) . .                 Number          
CL var for NBRUNIT    (10 0) . .                 Number          
CL var for CAPTOT     (10 0) . .                 Number          
CL var for CAPAVL     (10 0) . .                 Number          
CL var for CAPTOTPTC  (10 0) . .                 Number          
CL var for CAPAVLPTC  (10 0) . .                 Number          
CL var for CAPTOTUNP  (10 0) . .                 Number          
CL var for CAPAVLUNP  (10 0) . .                 Number          
CL var for SYSSTG     (10 0) . .                 Number          
CL var for OFLSTG     (10 0) . .                 Number          
CL var for THRESHOLD   (3 0) . .                 Number          
CL var for ASPTYP        (2) . .                 Character value 
CL var for BALSTS        (1) . .                 Character value 
CL var for BALTYP        (1) . .                 Character value 
CL var for BALDATTIM    (13) . .                 Character value
CL var for BALDTAMOV  (10 0) . .                 Number          
CL var for BALDTAREM  (10 0) . .                 Number          
CL var for TRCSTS        (1) . .                 Character value 
CL var for TRCDUR     (10 0) . .                 Number          
CL var for TRCDATTIM    (13) . .                 Character value
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

As always, a help panel group that explains the individual attributes in detail is included.

Below you will find an example of how the RTVASPINF command can be put to use in a CL program:

RtvAspInf  Asp( *SYSASP )              +                             
           RtnAsp( &RtnAsp)            +                             
           NbrUnit( &NbrUnit )         +                             
           CapTot( &CapTot )           +                             
           CapAvl( &CapAvl )           +                             
           Threshold( &Threshold )     +                             
           AspTyp( &AspTyp )                                         
ChgVar     &AspUsedPct  (( &CapTot - &CapAvl ) * 100 ) / &CapTot ) 
ChgVar     &StgBufPct    ( &Threshold - &AspUsedPct )              
If ( &StgBufPct <  5 )   Do                                         
ChgVar     &RtnAspC      &RtnAsp                                      
ChgVar     &StgBufPctC   &StgBufPct                                   
SndPgmMsg  MsgId( CPF9897 )                                +  
           MsgF( QCPFMSG )                                 +  
           MsgDta( 'ASP number'                      *Bcat +  
                   &RtnAspC                          *Bcat +  
                   'threshold buffer percentage is'  *Bcat +  
                   &StgBufPctC                       *Tcat +  
                   '.')                                    +  
           ToMsgQ( *SYSOPR )                                  
EndDo 

The above code is included in a sample CL program (CBX136T).

If you are interested in even more information about ASPs and disk units than the QYASPOL API can provide, it is worth taking a look at the Materialize Resource Management Data (_MATRMD) MI built-in. The documentation can be found online here:
http://publib.boulder.ibm.com/iseries/v5r1/ic2924/tstudio/tech_ref/mi/MATRMD.htm [3]

The _MATRMD MI built-in is capable of delivering many different sets of resource management data, ASP information being just one of them. You can find a description of all the different options in the header of the above documentation. To go directly to the ASP information section, use the link below:
http://publib.boulder.ibm.com/iseries/v5r1/ic2924/tstudio/tech_ref/mi/MATRMD.htm#HDRRMD12 [4]

I have included a sample program (CBX136M) showing you how to use the _MATRMD MI built-in to retrieve ASP and disk unit information. This program can also be used as a template for programs using any of the other _MATRMD options.

The RTVASPINF command can be created from the following source members:

CBX136 –- Command processing program.

CBX136X -- Command definition source member.

CBX136H -- Command help text panel group.

Compilation instructions are found in the source headers.

This article demonstrates the following APIs:

Open List of ASPs (QYASPOL) API:
http://as400bks.rochester.ibm.com/iseries/v5r2/ic2924/info/apis/qyaspol.htm [5]

Close List (QGYCLST) API:
http://as400bks.rochester.ibm.com/iseries/v5r2/ic2924/info/apis/qgyclst.htm [6]

Send Program Message (QMHSNDPM) API:
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QMHSNDPM.htm [7]

You can retrieve the source code for this API example from http://www.pentontech.com/IBMContent/Documents/article/50961_23_RtvAspInfo.zip [8].