The API Corner: Accessing System Values

APIs
Typography
  • 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                              

                                                              

/free                                                        

                                                              

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

                                                                  

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                                      

                                                                  

     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;                                  

         select;                                                    

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

                 else;                                              

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

                 endif;                                              

                                                        

           when SV.Ctl.QWCTD00 = 'B';                  

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

                                                        

           other;                                      

                 SVValue = '** PROBLEM **';              

         endsl;                                          

                                                        

         write SV_Sfl;                                  

        SysValOfsPtr += 4;                              

     endfor;                                            

endif;                                                

                                                        

*in31 = (RRNS1 > 0);                                    

write SV_Keys;                                        

dow (not *in03);                                      

     exfmt SV_Ctl;                                      

enddo;                                                          

                                                                  

*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                              

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)                

                                                                    

endif;                                                            

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.

BLOG COMMENTS POWERED BY DISQUS