Tue, May
0 New Articles

The API Corner: In Search of System Values

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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                                  




// 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                                            




// 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)                




*inlr = *on;                                                      





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)                      




iconv_t = IconvOpen(ToCode :FromCode);                            

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

                       :OutputPtr :BytAvl_CmdD);          

RtnVal = IconvClose(iconv_t);                                    




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)      





     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                        



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

             Controls.SysValFnd = *on;                          


         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.ValueFnd =                                    

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


     when ((Event = *XML_ATTR_NAME) and                          



         Controls.ValFnd =                                      

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


     when ((Event = *XML_ATTR_CHARS) and                        



         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;                              



         // Ignore                                            



return 0;                                




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 =                                                          


       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'    


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

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 This email address is being protected from spambots. You need JavaScript enabled to view it.. 

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

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

Now On Sale



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: