Using Intrinsics to Retrieve Variables

The HPCIGETVAR intrinsic returns the current value of the specified variable from the session variable table. HPCIGETVAR requires only a variable name. The STATUS parameter is optional. If specified, the success of the intrinsic call is returned in the STATUS parameter.

Item number and item pairs identify the parameters to receive the retrieved value. The item number and item pairs that are defined for the HPCIGETVAR intrinsic are listed below:

0: Ignored by the intrinsic.
1: Indicates that the following parameter receives the integer value of the variable. If the variable is not an integer, a zero is returned.
2: Indicates that the following parameter receives the string value of the variable. If the variable is not a string, ASCII zero is returned.
3: Indicates that the following parameter receives a 1 if the value is the boolean TRUE or a 0 if the value is the boolean FALSE. If the variable is not a boolean, a 0 is returned.
10: Indicates that the following parameter contains the length of the byte array receiving the variable's string value. If a length is passed and a byte array is not, an error is returned.
11: Indicates that the following parameter receives the actual length (in bytes) of the variable's string value.
12: Indicates that the following parameter contains a nonzero value to dereference the variable recursively. A zero value in this parameter retrieves the level-1 value of the variable.
13: Indicates that the following parameter receives a 1 if the variable found is an integer, 2 if the variable found is a string, or 3 if the variable found is a boolean.

The following example retrieves the current value of the string variable ANS. The STATUS parameter returns the status of the intrinsic call. The parameter ANS_LEN returns the length of the string retrieved.

   HPCIGETVAR(ANS,STATUS,2,ANS_STRING,11,ANS_LEN);

When you are unsure of the data type of the variable to be retrieved, several parameters can be included in the intrinsic call. The value is retrieved and loaded into the appropriate parameter field based on its type. The variable type parameter (13) is also specified to identify the actual data type and, therefore, the location of the retrieved value. The following example identifies parameters for each data type and a variable type parameter to identify the data type of the retrieved value. Note that the STATUS parameter has been omitted in this intrinsic call.

HPCIGETVAR(ANS2,,1,ANS2_INTEG,2,ANS2_BYTE,3,ANS2_BOOL,10,ANS2_LEN,13,ANS2_VARTYPE);

Another method of retrieving a variable value when the data type is not known is shown in the following example. Initially, the HPCIGETVAR intrinsic call is executed to determine only the data type of the variable. The retrieved data type is then used to branch to the appropriate intrinsic statement to retrieve the variable value. In the following example, the variable type is retrieved and analyzed. If the ANS2_VARTYPE parameter contains 1, the second intrinsic call is used to retrieve the integer value.

   HPCIGETVAR(ANS2,STATUS,13,ANS2_VARTYPE);

   [vellip]

   HPCIGETVAR(ANS2,STATUS,1,ANS2_INTEG);

The following program sample retrieves the logical device number of the user's terminal.

Figure 6-2 HPCIGETVAR Intrinsic Example

Function At_Physical_Console : Boolean;

Const

  PhysicalConsoleLDev     = 20;

  KeyWord_GetIntegerValue = 1; { keyword #2 in the intrinsic manual }

  CIVarNameLen            = 9;

Type

  StatusType = Record

                 Case Boolean Of

                   True  : ( Error_Num : Integer );

                   False : ( Info,

                             SubSys : ShortInt );

               End;

  CIVarNameType  = Packed Array[ 1..CIVarNameLen ] Of Char;

  CIVarValueType = Integer;  { See constant KeyWord_GetIntegerValue }

Var

  Status              : StatusType;

  CIVarName           : CIVarNameType;

  KeyValue_CIVarValue : CIVarValueType;

  Procedure HPCIGETVAR;    INTRINSIC;

  Procedure TERMINATE;     INTRINSIC;

  Procedure Check_Status( Var Status : StatusType );

  Begin {Check_Status}

    With Status Do

      If Info <> 0 Then

         Begin

           Writeln( 'Subsystem Number: ', SubSys );

           Writeln( 'Info            : ', Info );

           TERMINATE;

         End;

  End;  {Check_Status}

Begin {At_Physical_Console}

  CIVarName  := 'HPLDEVIN ';  { Retrieve the ldev number associated }

                              { with this terminal }

  { Read the contents of HPLDEVIN variable. }

  KeyValue_CIVarValue := 0;

  HPCIGETVAR( CIVarName, Status,

              KeyWord_GetIntegerValue, KeyValue_CIVarValue );

  Check_Status( Status );

  At_Physical_Console := KeyValue_CIVarValue = PhysicalConsoleLDev;

End;  {At_Physical_Console}

Begin {Main}

  If At_Physical_Console Then

     Writeln( 'Execution of this application on the console is not allowed.' )

  Else

     Writeln( 'Not on console --run the application.' );

End.  {Main}

The FINDJCW intrinsic retrieves the value of a specified JCW variable. The GETJCW intrinsic retrieves the current value of only the predefined variable named JCW. Both of these functions can be accomplished with the HPCIGETVAR intrinsic by specifying the appropriate variable name. To ensure program readability, use the HPCIGETVAR intrinsic in all cases.

Using Intrinsics to Retrieve Variables

Technical documentation

» Table of Contents

» Index