Wed, Jun
4 New Articles

The API Corner: Accessing System Values

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

Use the Retrieve System Values API.


Last month's article demonstrated how the Retrieve Command Definition (QCDRCMDD) API could be used to access the list of SYSVAL special values associated with the DSPSYSVAL command, thereby removing the need to know in advance what system values are valid for the system the program is running on. The sample program then loaded these special value names into the array SysVals. This month, we'll look at how the Retrieve System Values (QWCRSVAL) API can be used to access the values associated with each system value name found in SysVals. For demonstration purposes, we'll display the various system values using a subfile.

But before looking at the subfile we'll be using today, I need to point out an API change that has occurred since last month's article. Last month, in our discussion of the Bytes returned and Bytes available fields returned by the QCDRCMDD API when using format DEST0100, I mentioned that the value returned for the Bytes available field did not account for the 8 bytes needed to hold Bytes returned and Bytes available. The week following publication of the article, IBM provided PTFs for QCDRCMDD so that the Bytes available value returned does reflect the 8 bytes for Bytes available and Bytes returned. The PTFs are SI47772 for V5R4, SI47773 for 6.1, and SI47774 for 7.1. So my note concerning the need to add 8 to Bytes available, when dynamically allocating a receiver variable, no longer applies (assuming you have the PTFs installed, that is). If you have existing programs that currently add 8, then you'll be allocating 8 bytes more than is strictly necessary, but I wouldn't worry about it as 8 bytes are hardly something you would notice! With the previously mentioned PTFs applied, the definition for Bytes returned remains as being the length of the returned XML data. As QCDRCMDD has been available since V5R1, and changing this definition to account for the 8 bytes returned for Bytes available and Bytes returned could impact current use of this value in operations such as %subst and CCSID conversions, compatibility concerns dictated that this value be left as is.

Returning to our current task of displaying the system values, the subfile we will be using is shown below. Assuming that the source is stored in member LSTSVDSPF of source file QDDSSRC, you can create the display file using the command CRTDSPF FILE(LSTSVDSPF) SRCFILE(QDDSSRC).

A                                      CA03(03 'Exit')          

A         R SV_SFL                   SFL                      

A           SYSVALNAME   10A O 5 2                        

A           SVVALUE       60A O 5 15                        

A         R SV_CTL                    SFLCTL(SV_SFL)          

A                                     OVERLAY                  

A                                     SFLPAG(18)              

A                                     SFLSIZ(19)              

A 31                                  SFLDSP SFLEND            

A N32                                 SFLDSPCTL                

A 32                                 SFLCLR                  

A                                 1 2SYSNAME                  

A                                      COLOR(WHT)              

A                                 1 65DATE(*YY) EDTCDE(Y)      

A                                     COLOR(WHT)              

A                                 2 30'System Value Display'  

A                                     COLOR(WHT)              

A                                 4 2'Name     '            

A                                     DSPATR(UL)              

A                                 4 15'Value               -  

A                                                         -  

A                                                         '  

A                                     DSPATR(UL)              

A         R SV_KEYS                                            

A                                 24 2'F3=Exit'              

A                                     COLOR(BLU)              

The program we will be using this month is shown below with the changes from last month shown in bold. Assuming that the source is stored in member LSTSYSVAL of source file QRPGLESRC, you can create the program using the command CRTBNDRPG PGM(LSTSYSVAL).

h dftactgrp(*no)                                                  


fLstSVDspf cf   e             workstn sfile(SV_Sfl :RRNS1)        


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                    


dGetSysVals       pr                 extpgm('QWCRSVAL')      

d RcvVar                     65535a                            

d LenRcvVar                     10i 0 const                    

d NbrSysVals                   10i 0 const                    

d SysVals                       10a   dim(MaxSysVals)            

d ErrCde                             likeds(QUSEC)            


dCmdD_Job         s         65527a                            

dRRNS1           s             4s 0                          


dMaxSysVals       c                   const(300)              

dSysVals         s             10a   dim(MaxSysVals)          


dCmdD_RcvVar     ds                 qualified                    

d Ctl                                 likeds(QCDD0100)            

d CmdD_UTF8                  65527a                                


dSysVal_RcvVar   ds         65535                                

d NbrSysValsRtn                 10i 0                            


dSysValOfsPtr     s               *                                

dSysValOfs       s             10i 0 based(SysValOfsPtr)          


dSVPtr           s               *                                

dSV               ds                 qualified                    

d                                     based(SVPtr)                

d Ctl                                likeds(QWCRSVT)              

d CData                     10000a                                

d BData                         10i 0 overlay(CData :1)            


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                              

/copy qsysinc/qrpglesrc,qwcrsval                              




// Get command definition as a XML document. The document is    

// 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 you can "see"      

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


     GetSysVals(SysVal_RcvVar :%size(SysVal_RcvVar)                

               :Controls.TopSysVal :SysVals :QUSEC);              


     *in32 = *on;                                                  

     write SV_Ctl;                                                

     *in32 = *off;                                                


     SysValOfsPtr = %addr(SysVal_RcvVar) + %size(NbrSysValsRtn);    

     for RRNS1 = 1 to NbrSysValsRtn;                                

         SVPtr = %addr(SysVal_RcvVar) + SysValOfs;                    

         SysValName = SV.Ctl.QWCSV;                                  


           when SV.Ctl.QWCIS02 = 'L';                              

                 SVValue = '*LOCKED';                                


           when SysValName = 'QLOCALE';                            

                 SVValue = 'Not displayed';                          


           when SV.Ctl.QWCTD00 = 'C';                              

                 if SV.Ctl.QWCLD00 <= %size(SVValue);                

                   SVValue = %subst(SV.CData :1 :SV.Ctl.QWCLD00);  


                   SVValue = %subst(SV.CData :1 :%size(SVValue));  



           when SV.Ctl.QWCTD00 = 'B';                  

                 SVValue = %editc(SV.BData :'X');        



                 SVValue = '** PROBLEM **';              



         write SV_Sfl;                                  

        SysValOfsPtr += 4;                              




*in31 = (RRNS1 > 0);                                    

write SV_Keys;                                        

dow (not *in03);                                      

     exfmt SV_Ctl;                                      



*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                              

Last month's version of LSTSYSVAL had the following code to support the "processing" of system values.

if Controls.TopSysVal > 0;                                        

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

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



The changes for this month can be found primarily within this IF processing (with the other changes being related to data definitions, API prototypes, etc.).

The first change is the calling of the QWCRSVAL API, prototyped as GetSysVal. The QWCRSVAL API defines five parameters.

The first parameter, Receiver variable, is a variable-length output parameter where the API will return information related to the system values retrieved. The sample program uses the data structure SysVal_RcvVar, which is defined with a size of 65535 bytes, for the receiver variable. We'll look at the format of this receiver variable in more detail shortly.

The second parameter, Length of receiver variable, is a 4-byte integer input value defining the size of the Receiver variable. The sample program uses the value %size(SysVal_RcvVar).

The third parameter, Number of system values to retrieve, is a 4-byte integer input value defining the number of system values that are to be returned by the API. The sample program uses the variable Controls.TopSysVal. This variable was previously set by the xml-sax handler to the number of system value special values found in the XML generated by the QCDRCMDD API.

The fourth parameter, System value names, is a variable-length array of 10-byte character values. The character values represent the system value names that are to be retrieved. The number of system value names to process is provided by the third parameter, Number of system values to retrieve. The sample program uses the array SpcVals, which was previously loaded by the xml-sax handler.

The fifth parameter, Error code, is the standard API error code. The error code parameter was previously set to return API-encountered errors as exceptions.

Having called the QWCRSVAL API with the statement…

     GetSysVals(SysVal_RcvVar :%size(SysVal_RcvVar)                

               :Controls.TopSysVal :SysVals :QUSEC);              

…the receiver variable SysVal_RcvVar now contains the data associated with the returned system values and is ready for further processing. This processing, in the case of managing the system value configurations of remote systems, might be the sending of the receiver variable "as is" to a central site or, in the case of the sample program, locally processing the system values and presenting an interactive display of the current system values.

The receiver variable returned by the QWCRSVAL API is formatted as…

  • a 4-byte integer representing the number of system values returned
  • a variable-length array of 4-byte integer values providing base-0 offsets to the system value information. Each offset directs the program to the information associated with one returned system value (where the information provides what system value is being defined). The dimension of the array is provided by the previous number of system values returned.
  • the system value information associated with each system value returned. This information might be located anywhere within the receiver variable and must be accessed using the previously referenced array of offset values.

Each occurrence of system value information accessed by offset is formatted as…

  • a 10-byte character field containing the name of the system value being returned (QABNORMSW, QACGLVL, etc.)
  • a 1-byte character field describing the type of data being returned for the named system value. A value of 'B' indicates that the data is returned as a binary/integer value, a value of 'C' that the data is returned in character form, and a value of ' ' (blank) that the data associated with the system value is not available.
  • a 1-byte character field providing status information associated with the system value. A value of 'L' indicates that the data was not available due to the system value being locked, a value of ' ' (blank) that the data is available.
  • a 4-byte integer value providing the length of the value returned for the system value
  • a variable-length field where the value of the system value can be found

As mentioned earlier, the LSTSYSVAL sample program uses the data structure SysVal_RcvVar as the receiver variable. The data structure is defined with a length of 65535 bytes and one subfield: NbrSysValsRtn. The field NbrSysValsRtn is where we can determine the number of system values returned by the API.

SysVal_RcvVar could also have defined an array (with dim(MaxSysVals)) but doesn't. I chose instead to use the based variable SysValOfs and the basing pointer SysValOfsPtr to access the returned offset values. Either of these approaches, and several others, will work. Using an array definition may, however, cause someone taking a quick look at the program to think that an array of 300 elements is really being returned. In reality, the number of elements in the array is determined by NbrSysValsRtn.

The sample program also uses the based data structure SV (and associated basing pointer SVPtr) to access the system value information associated with each returned system value. The program could, as an alternative, use a substring approach to access the system value information, but I just hate coding a bunch of substring operations.

In terms of processing, the returned system value information LSTSYSVAL, after clearing the subfile and setting the pointer variable SysValsOfsPtr, enters a FOR loop conditioned by the number of system values returned by the API. Within the FOR loop, each system value information entry is accessed by setting the pointer SVPtr to the starting address of the receiver variable and adding the appropriate offset. After extracting the system value name (SV.Ctl.QWCSV), a select group is entered in order to process the value of the system value.

The only system-value-related special handling within this select group is for the system value QLOCALE. While this system value is returned as having a data type of 'C' (character), it is actually a data structure consisting of both binary and character data. Next month, as part of discussing the CCSID conversion APIs QtqIconvOpen, iconv, and iconv_close (a discussion that was deferred in last month's article), we'll look at how to display this particular system value. Attempting to display the value of QLOCALE, as it is returned from the QWCRSVAL API, in our subfile would most likely result in a 5250 data stream error. Rather than attempting to show the current value of QLOCALE, and receiving a 5250 data stream error, LSTSYSVAL simply displays the text "Not displayed."

After loading the subfile, LSTSYSVAL then displays the subfile entries until command Attention key 3 is pressed. At that point, the program ends.

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: