Determine the system values defined for your system.

I recently received a note from Paul T. asking "if there is an API which will retrieve a list of system values and their current values." To this I (all too quickly) referred him to the Retrieve System Values (QWCRSVAL) API, which retrieves the value associated with a list of one or more system values. Paul then got back to me with, "I was looking for something that would return the list of system values available"—which I admit is in his original question, but was totally missed by me.

I am not aware of any IBM-provided interface (API, CL command, database, etc.) whose purpose is to tell me what system values are defined on a given system (which isn't to say there isn't; I just don't know one offhand), but I did come up with a roundabout method to obtain such a list of system values—and an approach that others might find useful with other endeavors. My method is to determine those special values that are defined for a parameter such as SYSVAL on an IBM-supplied command such as DSPSYSVAL. This is an approach that...

1. has IBM doing the work of maintaining the list of system values as long as DSPSYSVAL is supported (which should be a long, long time)
2. should work on any current or future release of the i operating system as all of the APIs used have been around since V5R1 (and several quite a bit longer than that)
3. will not require any application programming changes as IBM continues to add system values in the future (IBM will be hard-coding the system values, not our sample application)

While I don't know what use Paul T. will have with this information, I can certainly see that it would be useful in a "roll-your-own" tracking of system value configurations in a network of systems—without having to worry about what release level each system in the network is running.

To accomplish our task, we'll use the Retrieve Command Definition (QCDRCMDD) API. This API retrieves information from a CL *CMD object and returns, to either a receiver variable or a stream file, Extensible Markup Language (XML) describing the command. In today's article, we'll use the QCDRCMDD API to generate XML describing the command DSPSYSVAL and then use the RPG operation code XML-SAX (with an appropriate handler) to create a list (array) of system value names that can be used as input to the QWCRSVAL API. Next month, we'll see what's required to call the QWCRSVAL API and then display, by way of a subfile, the values associated with each system value on the system.

The program we will be using this month is shown below. Assuming that the source is stored in member LSTSYSVAL of source file QRPGLESRC, you can create the program using the command CRTBNDRPG PGM(LSTSYSVAL). You may want to specify DBGVIEW(*SOURCE) on the CRTBNDRPG command so that you can later view the QCDRCMDD-generated XML with the source debugger.

h dftactgrp(*no)                                              

dRtvCmdD         pr                 extpgm('QCDRCMDD')      

d Cmd                           20a   const                    

d LenRcvVar                     10i 0 const                    

d DestFormat                     8a   const                    

d RcvVar                     65535a                            

d RcvVarFormat                   8a   const                    

d ErrCde                             likeds(QUSEC)            

dConvertBuffer   pr                                          

dmyHandler       pr           10i 0                          

d Controls                           likeds(HandlerInfo)      

d Event                         10i 0 value                    

d StringPtr                       *   value                    

d LenString                     20i 0 value                        

d ExceptionID                   10i 0 value                      

dCmdD_Job         s         65527a                              

dMaxSysVals       c                   const(300)                  

dSysVals         s             10a   dim(MaxSysVals)            

dCmdD_RcvVar    ds                 qualified          

d Ctl                                 likeds(QCDD0100)  

d CmdD_UTF8                 65527a                  

dControls         ds                  likeds(HandlerInfo)        

dHandlerInfo     ds                 qualified based(NoPtr)      

d TopSysVal                     10i 0                            

d ParmFnd                         n                              

d KwdFnd                          n                              

d SysValFnd                       n                              

d SpcValFnd                       n                              

d ValueFnd                       n                              

d ValFnd                         n                              

/copy qsysinc/qrpglesrc,qusec            

/copy qsysinc/qrpglesrc,qcdrcmdd                                  

/free                                                            

// Get command definition as a XML document. The document will be    

// encoded in UTF8 (CCSID 1208).                                

QUSBPrv = 0;                                                    

RtvCmdD('DSPSYSVAL QSYS' :%size(CmdD_RcvVar) :'DEST0100'        

         :CmdD_RcvVar :'CMDD0100' :QUSEC);                      

// CmdD_UTF8 now contains the XML document in CCSID 1208.      

// The system values can be found in <Parm Kwd="SYSVAL" under  

// <SpcVal>. The first special value, for instance, is          

// <Value Val="QABNORMSW" MapTo="QABNORMSW"/>. The end of the  

// special values is, naturally, delimited by </SpcVal>.        

// Convert command definition to job CCSID so we can "see"    

// and process the generated XML                                            

ConvertBuffer();                                                

// CmdD_Job now contains the XML document in the job CCSID.    

// Parse the XML document for SYSVAL special values            

xml-sax %handler(myHandler :Controls) %xml(CmdD_Job);          

if Controls.TopSysVal > 0;                                        

     // If any system values found then use QWCRSVAL to access      

     // their current values (to be done next month)                

endif;                                                            

*inlr = *on;                                                      

return;                                                            

/end-free                                                          

****************************************************************  

pConvertBuffer   b                                                

dConvertBuffer   pi                                                

dIconvOpen       pr           52   extproc('QtqIconvOpen')      

d ToCode                       32   const                        

d FromCode                     32   const                      

dIconv           pr           10i 0 extproc('iconv')            

d iconv_t                       52   value                      

d InputPtr                       *                              

d BytesToCvt                   10u 0                            

d OutputPtr                      *                              

d BytesAvlForCvt               10u 0                            

dIConvClose       pr           10i 0 extproc('iconv_close')      

d iconv_t                       52   value                      

dInputPtr         s               *   inz(%addr(CmdD_RcvVar.CmdD_UTF8))      

dOutputPtr       s               *   inz(%addr(CmdD_Job))        

dBytAvl_CmdD     s             10u 0 inz(%size(CmdD_Job))        

dRtnVal           s             10i 0                            

dFromCode         ds                qualified                    

d CCSID                         10i 0 inz(1208)                    

d ConvAlt                       10i 0 inz(0)                      

d SubstAlt                     10i 0 inz(0)                      

d SSAlt                         10i 0 inz(0)                      

d InpLenOpt                     10i 0 inz(0)                      

d ErrOpt                       10i 0 inz(0)                      

d                               8   inz(*ALLx'00')                

dToCode           ds                 qualified                    

d CCSID                         10i 0 inz(0)                      

d ConvAlt                       10i 0 inz(0)                      

d SubstAlt                     10i 0 inz(0)                      

d SSAlt                         10i 0 inz(0)                      

d InpLenOpt                     10i 0 inz(0)                      

d ErrOpt                        10i 0 inz(0)                      

d                               8   inz(*ALLx'00')              

diconv_t         ds                                                

d                               10i 0 dim(13)                      

/free                                                              

iconv_t = IconvOpen(ToCode :FromCode);                            

RtnVal = Iconv(iconv_t :InputPtr :CmdD_RcvVar.Ctl.QCDBRtn01

                       :OutputPtr :BytAvl_CmdD);          

RtnVal = IconvClose(iconv_t);                                    

/end-free                                                          

pConvertBuffer   e                                                

****************************************************************  

pmyHandler       b                                                

dmyHandler       pi           10i 0                              

d Controls                           likeds(HandlerInfo)          

d Event                         10i 0 value                

d StringPtr                       *   value                

d LenString                     20i 0 value                

d ExceptionID                   10i 0 value                

dString           s         65535a   based(StringPtr)      

/free                                                      

select;                                                  

     when Event = *XML_START_DOCUMENT;                      

       Controls.TopSysVal = 0;                        

         Controls.ParmFnd = *off;                          

         Controls.KwdFnd = *off;                          

         Controls.SpcValFnd = *off;                        

         Controls.ValueFnd = *off;                        

         Controls.ValFnd = *off;                          

     when ((Event = *XML_START_ELEMENT) and                      

           (%subst(String :1 :LenString)) = 'Parm');            

         Controls.ParmFnd = *on;                                

     when ((Event = *XML_ATTR_NAME) and                          

           (Controls.ParmFnd) and                                

           (%subst(String :1 :LenString)) = 'Kwd');              

         Controls.KwdFnd = *on;                                

     when ((Event = *XML_ATTR_CHARS) and                        

           (Controls.KwdFnd));                                  

         if %subst(String :1 :LenString) = 'SYSVAL';            

             Controls.SysValFnd = *on;                          

         endif;                                                  

         Controls.KwdFnd = *off;                                

     when ((Event = *XML_START_ELEMENT) and                      

           (Controls.SysValFnd) and                              

           (%subst(String :1 :LenString)) = 'SpcVal');            

         Controls.SpcValFnd = *on;                              

     when ((Event = *XML_START_ELEMENT) and                      

           (Controls.SpcValFnd));                                

         Controls.ValueFnd =                                    

                   (%subst(String :1 :LenString) = 'Value');      

     when ((Event = *XML_ATTR_NAME) and                          

           (Controls.ValueFnd));                                  

         Controls.ValFnd =                                      

                   (%subst(String :1 :LenString) = 'Val');      

     when ((Event = *XML_ATTR_CHARS) and                        

         (Controls.ValFnd));                                  

         Controls.TopSysVal += 1;                              

         SysVals(Controls.TopSysVal) =                        

                 %subst(String :1 :LenString);                  

         Controls.ValFnd = *off;                                

     when ((Event = *XML_END_ELEMENT) and                        

           (Controls.SpcValFnd) and                              

           (%subst(String :1 :LenString) = 'Value'));            

         Controls.ValueFnd = *off;                              

     when ((Event = *XML_END_ELEMENT) and                      

           (Controls.SysValFnd) and                            

           (%subst(String :1 :LenString)) = 'SpcVal');          

         Controls.SpcValFnd = *off;                            

     when ((Event = *XML_END_ELEMENT) and                      

           (%subst(String :1 :LenString)) = 'Parm');            

         Controls.SysValFnd = *off;                            

         Controls.ParmFnd = *off;                              

     other;                                                    

         // Ignore                                            

endsl;                                                        

return 0;                                

/end-free                                  

pmyHandler       e                        

After setting the API error code Bytes Provided variable (QUSBPrv) to 0 so that API-detected errors are returned as exceptions, the program calls the Retrieve Command Definition (QCDRCMDD) API (prototyped as RtvCmdD). The QCDRCMDD API defines six parameters.

The first parameter, Qualified command name, is a standard 20-byte qualified object name with the first 10 characters identifying the name of the command to be retrieved and the second 10 characters the library. The library can be either an explicit library or one of the special values *CURLIB and *LIBL. The example program specifies the command name DSPSYSVAL and the library QSYS.

The second parameter, Destination information, is a variable-length input parameter providing information about how the generated XML is to be returned. If the third parameter (Destination format name) is DEST0100, then the second parameter is defined as a 4-byte integer defining the size of the receiver variable (the fourth parameter of the API) where the XML is to be stored. If the third parameter is DEST0200, then the second parameter is a structure defining the path name of the stream file where the XML is to be stored. The sample program uses a destination format name of DEST0100 and %size(CmdD_RcvVar) for the second parameter, where the variable CmdD_RcvVar has an allocated size of 65535 bytes (8 bytes due to the likeds(QCDD0100) from QSYSINC source member QRPGLESRC.QCDRCMDD and 65527 bytes from the definition of subfield CmdD_UTF8).

The third parameter, Destination format name, is an 8-byte format name. The value 'DEST0100' indicates that the generated XML is to be returned in the receiver variable; the value 'DEST0200' indicates that the generated XML is to be returned in a stream file. The example program uses format DEST0100.

The fourth parameter, Receiver variable, is a variable-length output parameter where the XML is returned when the destination format is DEST0100. This parameter must be passed, but is not used, when the destination format is DEST0200. The size of this receiver variable (when using destination format DEST0100) is provided by the second parameter. The example program uses the receiver variable CmdD_RcvVar.

When using DEST0100, the receiver variable is a structure defined by three variables. The first variable, Bytes returned, is a 4-byte unsigned integer that will contain the length of the XML data returned by the QCDRCMDD API. The second variable, Bytes available, is a 4-byte unsigned integer that will contain the length of the XML data that could be returned by the API if the receiver variable were large enough. The third variable, Generated CDML source, is a variable-length character string that will contain the generated XML describing the command specified by the first parameter. The API does not return partial XML data; the receiver variable must be of sufficient size to store all of the generated XML.

Note that the preceding definitions of Bytes returned and Bytes available refer to the length of the XML data and not the number of bytes returned/available for the entire structure. This is decidedly different than the use of these fields with most APIs. Related to this difference, keep in mind that if you dynamically allocate the receiver variable based on the number of Bytes available initially returned by an API (see the earlier articles "Retrieving Information, Part I" and "Retrieving Information, Part II" if you are not familiar with dynamically allocating receiver variables), then you need to add 8 to the returned Bytes available value when using the %alloc built-in in order to allocate your receiver variable. These 8 bytes are to accommodate the two subfields of data structure QCDD0100 that are not accounted for by the Bytes available field.

The fifth parameter, Receiver format name, is an 8-byte format name that defines the level of command definition information the API should return. Format 'CMDD0100' returns a level of information that is sufficient to build a valid command string. Format 'CMDD0200' returns additional information, such as prompt messaged IDs, prompt file, etc. Both formats return command parameter special values, which is what we need for today's sample program, so the program uses CMDD0100 as the lower the format number generally the better the performance.

The sixth parameter, Error code, is the standard API error code.

Having called the QCDRCMDD API with the statement…

RtvCmdD('DSPSYSVAL QSYS' :%size(CmdD_RcvVar) :'DEST0100'        

         :CmdD_RcvVar :'CMDD0100' :QUSEC);                      

…the receiver variable CmdD_RcvVar now contains the generated XML for the command QSYS/DSPSYSVAL within the subfield CmdD_UTF8. The QCDRCMDD API returns the XML encoded as UTF8 (CCSID 1208), a variable-width encoding form of Unicode that is based on ASCII. To convert the UTF8 data to the CCSID of the current job, the program calls function ConvertBuffer(). For space reasons, we will not go into the details of this function today other than to say it uses the APIs QtqIconvOpen, iconv, and iconv_close to convert the entire XML data stream from UTF8 to the current job CCSID (or the job default CCSID if the job CCSID is 65535), returning the converted XML in variable CmdD_Job. In a future article, we'll go into the details of using these APIs to perform CCSID conversions.

With CmdD_Job now containing the EBCDIC-encoded XML data, the sample program uses the RPG operation code xml-sax to parse the XML using the handler myHandler and the communication-area data structure Controls. To best understand what the handler is doing, you may want to look at the XML input found in CmdD_Job. Below is the initial screen shot, using STRDBG and eval CmdD_Job:c 10000 just prior to running the xml-sax operation.

                             Evaluate Expression                              

Previous debug expressions                                                    

> EVAL CmdD_Job:c 10000                                                      

   CMDD_JOB:C 10000 =                                                          

             ....5...10...15...20...25...30...35...40...45...50...55...60      

       1   '<QcdCLCmd DTDVersion="1.0"><Cmd CmdName="DSPSYSVAL" CmdLib="'    

       61   'QSYS" CCSID="37" Prompt="Display System Value" HlpPnlGrp="QH'    

     121   'WCCMD1" HlpPnlGrpLib="__LIBL" HlpID="DSPSYSVAL" MaxPos="2" M'    

     181   'sgF="QCPFMSG" MsgFLib="__LIBL" ExecBatch="YES" ChgCmdExit="N'    

     241   'O" RtvCmdExit="NO"><Parm Kwd="SYSVAL" PosNbr="1" KeyParm="NO'    

     301   '" Type="NAME" Min="1" Max="1" Prompt="System value" Len="10"'    

     361   ' Rstd="YES" AlwUnprt="YES" AlwVar="YES" Expr="YES" Full="NO"'    

     421   ' DspInput="YES" Choice="QABNORMSW, QACGLVL..." ><SpcVal><Val'    

    481   'ue Val="QABNORMSW" MapTo="QABNORMSW"/><Value Val="QACGLVL" M'    

     541   'apTo="QACGLVL"/><Value Val="QACTJOB" MapTo="QACTJOB"/><Value'    

     601   ' Val="QADLACTJ" MapTo="QADLACTJ"/><Value Val="QADLSPLA" MapT'    

                                                                        More...

Debug . . .                                                                  

F3=Exit   F9=Retrieve   F12=Cancel   F16=Repeat find   F19=Left   F20=Right  

F21=Command entry       F23=Display output                                    

The procedure myHandler locates the <SpcVal> special values list of parameter <Parm Kwd="SYSVAL")…> and then populates the SysVals array with the special values associated with the <Value Val=…> arguments. These special values represent the system values supported by the DSPSYSVAL command. As the DSPSYSVAL command has more than one parameter (SYSVAL and OUTPUT), and both parameters support special values, myHandler uses a variety of indicators (ParmFnd, KwdFnd, etc.) to make sure the correct special value list is used. In addition to the indicators found in the Controls data structure, the variable TopSysVal is used to indicate the number of special values that have been loaded into the SysVals array.

When the xml-sax operation has completed, the program is ready to call the Retrieve System Values (QWCRSVAL) API in order to access the current values associated with each system value defined by the DSPSYSVAL command. Next month, we will look at how to call, and process, these system values.

Before closing, I would be remiss if I didn't point out that our sample program LSTSYSVAL makes several assumptions, two of which I'll discuss here. One assumption is that the receiver variable CmdD_RcvVar is large enough to hold the generated XML. As the program is using a static receiver variable with an allocation of 65535 bytes, and the DSPSYSVAL command (even after having been around on the i for more than 20 years) is currently generating an XML data stream of less than 10000 bytes, I don't see this assumption as a problem. Other commands may be a different story, though. A second assumption is that the SysVals array dimension—300 elements—is sufficient to hold all available system values. The number of elements is based on 300 being the maximum number of special values that can be defined for a command parameter, and, as DSPSYSVAL currently defines roughly half of that number, my anticipation is that this maximum will not be approached anytime soon.

As usual, if you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.

Bruce Vining

• Email
• Site

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at bvining@brucevining.com. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale