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
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
MC Press books written by Bruce Vining available now on the MC Press Bookstore.
 |
||
 |
|
IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale
|
More 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.
TRY 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.
Forms 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.
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:
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.
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:
LATEST COMMENTS
MC Press Online