Using Intrinsics to Set Variables

Any user-defined variable can be set from within an application program using the HPCIPUTVAR intrinsic. Variables set in this way are available to any process within the specified session. The variable name specified in the intrinsic must be a valid variable name. An optional STATUS parameter can be specified to receive status information on the success of the intrinsic call.

Item number and item pairs identify the type of data that is to be stored in the variable. The item number and item pairs that are defined for the HPCIPUTVAR intrinsic are listed below:

It is possible to set variables on both a process local and a job or session global basis. For a list of variables whose modifications exist only for the locality of the process see Appendix A of the MPE/iX Commands Reference Manual 32650-90003.

If you wish to modify session or job level variables then the HPCIGETVAR and HPCISETVAR intrinsics should be called rather than calling the COMMAND intrinsic to execute the SETVAR and SHOWVAR commands. The COMMAND intrinsic SETVAR will not set a session level variable.

The following example uses the HPCIPUTVAR intrinsic to set a variable named ANS. It also loads it with numeric data (1) contained in the parameter ANS_INPUT. Status on the success of the HPCIPUTVAR intrinsic call is returned in the parameter named STATUS.

   HPCIPUTVAR(ANS,STATUS,1,ANS_INPUT)

The next example specifies that the variable named ANS2 is loaded with data from ANS_INPUT. The length of the string is specified in ANS_LEN. Note that the STATUS parameter has been omitted, signified by the two commas after the variable name.

   HPCIPUTVAR(ANS2,,2,ANS2_INPUT,11,ANS2_LEN,14,ANS2_INT)

The data type of the variable in this example depends on the contents of the ANS2_INT parameter. If this field contains a nonzero character, the data is considered string character data. If the ANS2_INT field contains a zero, the input, ANS_INPUT, is interpreted to determine whether the variable contains numeric or boolean data.

The following sample program creates a variable named MYVAR using the HPCIPUTVAR intrinsic.

Procedure Create_CI_Variable;

Const

  KeyWord_StringValue  = 2;   { keyword #2 in the intrinsic manual }

  KeyWord_StringLength = 11;  { Keyword #11 in the intrinsic manual }

  StringLength         = 34;

  CIVarNameLen         = 6;   { Length of variable name to be created }

Type

  StatusType = Record

                  Case Boolean Of

                    True  : ( Error_Num : Integer );

                    False : ( Info,

                              SubSys : ShortInt );

                End;

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

  ToBeWrittenType = Packed Array[ 1..StringLength ] Of Char;

  CIVarValueType  = ToBeWrittenType;

Var

  Status       : StatusType;

  CIVarName    : CIVarNameType;

  KeyValue_ActualStringContents  : CIVarValueType;

  KeyValue_ActualStringLength    : Integer;

  Procedure HPCIPUTVAR;    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 {Create_CI_Variable}

  CIVarName  := 'MyVar ';    { Name of the variable to be created }

  KeyValue_ActualStringContents := 'Programmatically Created Variable';

  KeyValue_ActualStringLength   := StringLength;

  { Create MyVar variable. }

  HPCIPUTVAR( CIVarName, Status,

              KeyWord_StringValue, KeyValue_ActualStringContents,

              KeyWord_StringLength, KeyValue_ActualStringLength );

  Check_Status( Status );

End;  {Create_CI_Variable}

Begin {Main}

  Create_CI_Variable;

End.  {Main}

The HPCIPUTVAR intrinsic can also be used to modify the value of a predefined variable. The predefined variable to be modified is identified by specifying the variable name in the intrinsic call. Its value is determined by item number and item pairs specifying the data type and the value to be inserted. Note that some predefined variables cannot be modified. (Refer to the MPE/iX Commands Reference Manual (32650-90003) for a list of predefined variables that can be modified.)

The HPCIDELETEVAR intrinsic deletes any user-defined variables within the appropriate session. The variable to be deleted is specified by its variable name. Wildcard characters can be used to delete multiple variables. The STATUS parameter returns the status of the intrinsic call to the calling program. Note that no predefined variables can be deleted. The following example deletes the variable named ANS.

   HPCIDELETEVAR(ANS,STATUS)

The PUTJCW intrinsic sets and loads a job control word (JCW), a 16-bit unsigned integer variable. The SETJCW intrinsic sets only the predefined variable named JCW. Both of these functions can be accomplished with the HPCIPUTVAR intrinsic by specifying the appropriate variable name and loading a numeric value within the range of 0 to 65,535. To ensure program readability, use the HPCIPUTVAR intrinsic in all cases.