SETVAR is a parameter used by many output-type commands (DISPLAY, EXECUTE, PRINT, and so on) that allows you to specify the run-time values to be used by a view’s variable definition. The commands that use SETVAR can be issued at a command line, in a Sequel script, in a CL program, or used inside of other commands. 

Elements in the SETVAR list identify a variable name to be set, and its value. The value portion may be up to 1085 characters long. The basic syntax is:

SETVAR((&VARIABLE1 VALUE1) [(&VARIABLE2 VALUE2)])

The following example demonstrates a single variable for a numeric value:

SETVAR((&AMOUNT 25))

The following example shows two variables for a numeric and character value:

SETVAR((&AMOUNT 25) (&STATE 'IL')) 

The syntax for the elements inside the SETVAR will change depending on how and where SETVAR is used.


Output Commands

When you issue a command, such as EXECUTE, that uses SETVAR on a command line, you must supply the values for the variables. For example:

EXECUTE VIEW(LIB/VIEWNAME) OUTFILE(QTEMP/F1) 
        SETVAR((&NAME SEQUELEX) (&QSTRING 'IL')
               (&NUMBER 10) (&EXPR 1) (&DTE '04/20/2009'))

If a value is omitted, the variable uses the default value specified in the view’s variable definition if *NOPROMPT is also defined. If there is no default defined, the view’s run-time prompt screen displays.


Viewpoint Script

In a script, you provide the view’s variables with a value that is also a variable—a script variable. When you enter the SETVAR parameter for a given command, you use the following syntax:

EXECUTE VIEW(LIBRARY/VIEWNAME) OUTFILE(QTEMP/F1) 
        SETVAR((&NAME '&&NAME') (&QSTRING '&&QSTRING')
               (&NUMBER '&&NUMBER') (&EXPR '&&EXPR') (&DTE '&&DATE'))

As a general rule, it is best to use single quotes around your script variables to allow for spaces or special characters. When a script variable is enclosed in quotes, two ampersands (&&) are required to ensure substitution.


Run Command—RUNCMD

Run Command (RUNCMD) is a function that runs a command, or series of commands against a list of items. A Sequel statement or view is used to produce the list and the number of records returned by the Sequel query determines the number of times the command is run. This allows for repetitive processing of any command or Sequel request.

The structure of the RUNCMD command is simply:

RUNCMD CMD(command or commands to run)
       SQL(query that produces the list)

Values returned by the SQL parameter are referenced by name within the CMD parameter, e.g.

RUNCMD CMD(‘CALL PGM(INVOICE) PARM(&&CSTTE)’) 
       SQL(‘SELECT CSTTE FROM CUSTMAST WHERE REGON=40’)

The syntax for specifying variables is unique in RUNCMD. Because the command or command list is enclosed in quotes, variables must use two ampersands to ensure proper recognition. When using SETVAR with RUNCMD, the value for the variable is usually provided by the Sequel query. Just like in a script, it is good practice to enclose this in single quotes and use two ampersands. To specify a set of quotes inside an existing set of quotes, use two single quotes.

RUNCMD CMD(‘PRINT VIEW(LIB/VIEWNAME) 
       SETVAR((&&VAR1 ''&&CUSNO''))’) 
       SQL(‘SELECT CUSNO FROM SEQUELEX/CUSTMAST WERE REGON = 10’)

RUNCMD and Scripting

Most often, RUNCMD is used as part of a process—like a broadcast e-mail request—and is one of many commands in a Viewpoint script. Since RUNCMD and scripting both substitute values in place of variables, RUNCMD in a script presents a problem. We need a syntax convention that will prevent scripting from processing the variables that RUNCMD will handle internally. For variables to be ignored by the script, and to be formatted correctly by the command processor, precede all variables with an underscore ( _ ).

RUNCMD CMD(‘PRINT VIEW(LIB/VIEWNAME) 
       SETVAR((_&&VAR1 ''_&&CUSNO''))’) 
       SQL('SELECT CUSNO FROM SEQUELEX/CUSTMAST WHERE REGON = 10')

There is another complication when writing scripts with script variables mixed in with RUNCMD type variables.

Consider:

DCL VAR(&VAR1) TYPE(*CHAR) LEN(10)
CHGVAR VAR(&VAR1) VALUE('01.05.11')
RUNCMD CMD(‘PRINT VIEW(SEQUELEX/RCMDTEST)
SETVAR((_&&VCUSNO ''_&&CUSNO'')(_&&VAL ''&&VAR1''))’)
SQL(‘SELECT CUSNO FROM SEQUELEX/CUSTMAST WHERE REGON = 50’)

The purpose of the leading underscore (_) character in a variable name is to cause the script processor to ignore these variables. However, in the case of a RUNCMD statement that includes both script variables and RUNCMD list variables, we do not want the script processor to ignore everything.

In the above example, we want &vcusno to be provided by the query results from the SQL parameter, but &val is to be supplied by the script. Thus we intentionally omit the leading underscore with ’’&&var1’’.


Run Remote Command—RUNRMTCMD

The Run Remote Command (RUNRMTCMD) is an operating system function that allows System i users to run a command on a remote system. For example, the System i tells a remote server (another PC) to run a PC program, like Viewpoint. Sequel users are familiar with this command if they have configured a Viewpoint Server to enable the Sequel Web Interface to display Client Report (CRO) results in a browser. With RUNRMTCMD you can create graphs and CRO results and make them available to users that do not have Viewpoint installed. If the request involves a run-time prompted view, you use SETVAR to supply values to the view’s variables.

Since you are issuing a PC-type command, the syntax of the CMD parameter is similar to running the command at a DOS prompt. The SETVAR parameter is identified like a switch and starts with a slash (/) It identifies the name of the variable(s) in the view, without an ampersand, and the value for the variable. If run from a command line, use the following syntax:

RUNRMTCMD CMD('"\PROGRAM FILES\SEQUEL VIEWPOINT\VIEWPNT"
          /V:SYSTEMI/LIB/VIEWNAME
          /SETVAR((VAR1 10) (VAR2 IL))')

Inside a script, the second element of the SETVAR—the value—is usually a script variable. To ensure substitution, the script variable requires two ampersands:

RUNRMTCMD CMD('"\PROGRAM FILES\SEQUEL VIEWPOINT\VIEWPNT"
          /V:SYSTEMI/LIB/VIEWNAME
          /SETVAR((VAR1 ''&&NUM'') (VAR2 ''&&CHAR''))')

Note: For the RUNRMTCMD command, do not define a variable as QSTRING—as you normally would in a view for character data—define it as an expression (EXPR) type instead.


VPSHELL

The VPSHELL command specifies a character string (up to 2000 characters) that represents a command to be run by the Viewpoint client. The command must specify a file or object that is accessible to the client. In essence, VPSHELL issues a PC-type command where the syntax of the CMD parameter is similar to running the command at a DOS prompt. The SETVAR parameter is identified like a switch and starts with a slash (/). It identifies the name of the variable(s) in the view, without an ampersand, and the value for the variable. Inside a script, the second element of the SETVAR—the value—is usually a script variable. To ensure substitution, the script variable requires two ampersands:

VPSHELL CMD('"\PROGRAM FILES\SEQUEL VIEWPOINT\VIEWPNT"
        /V:SYSTEMI/LIB/VIEWNAME
        /SETVAR((VAR1 ''&&X'') (VAR2 ''&&Y''))')

Note: For the VPSHELL command, do not define a variable as QSTRING—as you normally would in a view for character data—define it as an expression (EXPR) type instead.


DOS

Entering a command at a DOS command prompt is very similar to the CMD parameter of VPSHELL and RUMRMTCMD. The SETVAR parameter is identified as a switch and starts with a slash (/). It identifies the name of the variable(s) in the view, without an ampersand, and the value for the variable.

"\PROGRAM FILES\SEQUEL VIEWPOINT\VIEWPNT"
 /V:SYSTEMI/LIB/VIEWNAME
 /SETVAR((VAR1 10) (VAR2 IL))


Drill-Down Option

Drill-down options are the link used in a Viewpoint Drill-Down Application that ties two Sequel objects together and allows you to ‘drill’ from the results of a summary view to another view that lists the supporting detail for a summary record. SETVAR is used in the option to pass data from the starting view to the target view. Both elements in the SETVAR—the variable and the value—are designated with two ampersands. To allow for blanks and special characters, enclose the value in single quotes:

DISPLAY VIEW(LIBRARY/VIEWNAME) SETVAR((&&REGON '&&REGON'))


In Summary

This following table summarizes the variations of the SETVAR syntax for the commands discussed in this document.

Command Usage and Syntax
EXECUTE Command Line:
SETVAR((&VAR1 10) (&VAR2 'IL'))
Script:
SETVAR((&VAR1 '&&NUM') (&VAR2 '&&CHAR'))
RUNCMD Command Line:
SETVAR((&&VAR1 ''&&FIELD1'') (&&VAR2 ''&&FIELD2'')) 
Script:
SETVAR((_&&VAR1 ''_&&FIELD1'') (_&&VAR2 ''_&&FIELD2''))
RUNRMTCMD Command Line:
/SETVAR((VAR1 10) (VAR2 IL)) 
Script:
/SETVAR((VAR1 ''&&NUM'') (VAR2 ''&&CHAR'')) 
(Use EXPR in place of QSTRING for character prompts)
VPSHELL Script Only:
/SETVAR((VAR1 ''&&NUM'') (VAR2 ''&&CHAR'')) 
(Use EXPR in place of QSTRING for character prompts)
DOS DOS Command Prompt:
/SETVAR((VAR1 10) (VAR2 IL))
Drill-Down Option In Option File:
SETVAR((&&VAR1 '&&FIELD1') (&&VAR2 '&&FIELD2'))

 

 

 

 

 


Still have questions? We can help. Submit a case to Technical Support.

New to Sequel? Learn more, or sign up for a free trial.

Last Modified On: October 11, 2018