TAA Tools
RTVSYSVAL4      RETRIEVE SYSTEM VALUE 4                TAAVALC

The  Retrieve System  Value  4  command  is an  alternative  method  of
accessing a  single system value.   It differs from  RTVSYSVAL2 in that
the   return  variable  allows  for  5000  bytes  instead  of  the  900
supported by RTVSYSVAL2.   The command  interface is not of  particular
value, but  the CPP  can be called  directly as an  API which  allows a
simple access to any system value from a HLL.

RTVSYSVAL4  may  be used  for  any system  value, but  is  intended for
system values that exceed 900 bytes.

A typical command would be:

        DCL          &RTNVAR *CHAR LEN(5000)
        DCL          &QMODEL *CHAR LEN(4)
         .
        RTVSYSVAL4   SYSVAL(QMODEL) RTNVAR(&RTNVAR)
        CHGVAR       &QMODEL &RTNVAR

The return  variable  must  be declared  as  5000 bytes.    The  return
variable is  completely blanked out and  then the value is  placed into
the variable beginning at position 1.

Decimal  system  values  are  always  returned  as  character  data  in
positions 1 - 9.  The length will always be 9.

To access the decimal system value QTOTJOB, you would specify:

        DCL          &RTNVAR *CHAR LEN(5000)
        DCL          &QTOTJOB *DEC LEN(9 0)
         .
        RTVSYSVAL4   SYSVAL(QTOTJOB) RTNVAR(&RTNVAR)
        CHGVAR       &QTOTJOB %SST(&RTNVAR 1 9)

There are optional  parameters for  the type of  system value  returned
(C or  D), and the  length of the  value.  For  example, to  access the
user library list you could specify:

        DCL          &RTNVAR *CHAR LEN(5000)
        DCL          &QUSRLIBL *CHAR LEN(250)
        DCL          &RTNTYP *CHAR LEN(1)
        DCL          &RTNLEN *DEC LEN(5 0)
         .
        RTVSYSVAL4   SYSVAL(QUSRLIBL) RTNVAR(&RTNVAR) +
                       RTNTYP(&RTNTYP) RTNLEN(&RTNLEN)
        CHGVAR       &QUSRLIBL %SST(&RTNVAR 1 &RTNLEN)

It  is not  necessary to  use  the RTNLEN  value when  moving  from the
&RTNVAR  parameter as the  &RTNVAR value will  have trailing blanks for
any unused data.   The RTNTYP  and RTNLEN parameter  may be helpful  in
generalized coding solutions.

RTVSYSVAL4 escape messages you can monitor for
----------------------------------------------

      TAA9892    The system value specified is locked and
                    the information is not available

      TAA9893    The system value information is not available

      TAA9894    The specified system value does not exist

Escape messages from system commands will be re-sent.

Calling the CPP directly as an API
----------------------------------

The following  RPG code  is in a  format where it  can be  copied using
the  SEU browse function  to access a  system value (QMODEL  is used as
an example)

     ISYSVDS      DS                           5000
     I                                        1  10 SYSVLC
     I                                        1   90SYSVLD
     .
     .
     C                     MOVEL'QMODEL  'SYSVAL    P      QMODEL
     C* TAA Tool RTVSYSVAL4
     C                     CALL 'TAAVALCC'                 Get sys val
     C                     PARM           SYSVAL 10        System value
     C                     PARM           SYSVDS           Sys val DS
     C                     PARM           SYSVTP  1        Sys val type
     C                     PARM           SYSVLN  50       Sys val len
     C* Move from returned value
     C                     MOVELSYSVLC    QMODEL  4        Model info

  **   The SYSVLC field will hold all character system values.

  **   The SYSVLD field will hold all of the decimal system values.

  **   The SYSVTP parameter is a  return value and will contain  either
       C or D.

  **   The SYSVLN  parameter is  a return  value and  will contain  the
       length  of  the  returned  value.    Decimal values  are  always
       returned as character data with a length of 9.

Exceptions to normal System Value data
--------------------------------------

The API QWCRSVAL  is used to  access the  system values.   Some of  the
information is  presented differently  when using  the API.   The  most
noticeable exceptions are:

   QDATE         The  date is always  returned as  a 7  character value
                 in the format CYYMMDD.

   QTIME         The  time is  always returned  as a  9 character value
                 in the format HHMMSSmmm.

RTVSYSVAL4 Command parameters                         *CMD
-----------------------------

   SYSVAL        The system value to be retrieved.

   RTNVAR        The  return variable.    A  required  return  variable
                 that  must be  declared  as *CHAR  LEN(5000).   Values
                 are  always  left justified.    Decimal  system values
                 are always presented  as character  data in  positions
                 1-9.  See the exceptions described previously.

   RTNTYP        The return type  of system value.   An optional return
                 variable  that  must  be  specified  as *CHAR  LEN(1).
                 Either  a  'C'  (character)   or  'D'  (decimal)   are
                 returned.

   RTNLEN        The return length.   An optional return  variable that
                 must  be specified as  *DEC LEN(5  0).   For character
                 type  values, this  is the  length of  the data within
                 the 5000 bytes.   For decimal type values,  the length
                 is always 9.


Restrictions
------------

Because the command  returns variables, RTVSYSVAL4 can only  be used in
a CL program.  The CPP can be called from any program.

There  are some exceptions to  how values are returned  because the API
is used rather than the  RTVSYSVAL command.  See the previous  section.

Prerequisites
-------------

The following TAA Tools must be on your system:

          SNDESCMSG      Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RTVSYSVAL4    *CMD                   TAAVALC       QATTCMD
   TAAVALCC      *PGM       CLP         TAAVALCC      QATTCL
					

Added to TAA Productivity tools April 15, 2011


Home Page Up to Top