Skip to main content

Universal Virtual Terminal Script Interpreter Scripting

Language Constructs​

The UNVVT script interpreter supports a minimal yet powerful set of language constructs. These constructs fall into three primary categories:

  1. Command Execution: Execute external system commands (i.e., CL commands) directly from the script.
  2. Variables: Store and manipulate data using simple variable assignments. Variables can hold strings or numbers and can be referenced throughout the script.
  3. Control Flow Statements: Direct the execution of scripts using conditional and branching statements such as if, goto, and return. These constructs allow for dynamic behavior based on runtime conditions.

Each of the following sections provides syntax, usage examples, and behavioral notes for these core features.

Command Execution​

The UNVVT script interpreter allows you to execute any command that can be run from the IBM i native command line directly within a script. This includes:

  • CL commands (e.g., DSPJOB, WRKACTJOB, CHGVAR)
  • Program calls (e.g., CALL PGM(MYPGM) PARM('value'))
  • System utilities available in the IBM i environment

Usage example:

DSPJOB  
CALL PGM(MYPGM) PARM('ABC' '123')

Commands are executed in the same manner as if they were entered interactively on the IBM i command line, making UNVVT scripts a powerful tool for automating operational tasks.

Variables​

Variables in UNVVT scripts allow dynamic data storage and manipulation. They can hold strings or numbers and are referenced using the & prefix (e.g., &MY_VAR).

Variables can be created and modified in three ways:

1. PGM Statement​

The PGM statement defines input variables that receive values from the UNVVT command line via the PARM option.

Syntax:

PGM PARM([&variable_name]...)

Notes:

  • Must be the first command in the script if used.
  • Values passed on the command line map in order to the variables listed.

Example:

UNVVT STMF('/home/scripts/myscript.clle') PARM('ABC' '123')

Script:

PGM PARM(&INPUT1 &INPUT2)

Result:

&INPUT1 = 'ABC'  
&INPUT2 = '123'

2. CHGVAR Statement​

The CHGVAR command sets or changes the value of a variable. If the variable does not exist, it is created automatically.

Syntax:

CHGVAR VAR(&variable_name) VALUE(value)

Example:

CHGVAR VAR(&STATUS) VALUE('COMPLETE')

Value Functions​

The value portion of the CHGVAR command supports the following functions to help modify or retrieve the desired value:

Function

Syntax

CALC - Calculate arithmetic expression

*CALC(operand1 operator operand2) [LEN(length)]

SUBST - Return substring

*SUBST(value) [POS(starting_position)] [LEN(length)]

LEN - Return length of a string

*LEN(value)

UNPAD - Remove leading and trailing blanks from a value

*UNPAD(value) [OPTION(*LEFT | *RIGHT | *BOTH)]

TOUPPER - Convert string to uppercase

*TOUPPER(value)

DTAARA - Retrieve value from data area

*DTAARA(library/name) [POS(start_position)] [LEN(length)]

ENVVAR - Retrieve environment variable

*ENVVAR(variable_name)

FILE - Read excerpt from file

*FILE(file_name_in_IFS_format) [KEY(key)]

REPLACE - Replace one character in a variable value with another.

*REPLACE(value) FROM(char) TO(char)

REMOVE - Remove a character from a variable.

*REMOVE(value) FROM(other_value)

CURJOB - Current job name

*CURJOB

CURUSER - Current username

*CURUSER

CURJOBNBR - Current job number

*CURJOBNBR

SYSNAME - Local system name from RTVNETA.

*SYSNAME

SYSVAL - Retrieve system value

*SYSVAL(system_value)

CURLIB - Current library

*CURLIB

CURASP - Current ASP group

*CURASP

CURDIR - Current directory

*CURDIR

3. SETVAR Parameter in UNVVTSND​

The SETVAR parameter extracts data from a virtual terminal screen and stores it in a variable.

Syntax:

SETVAR((variable_name output_row output_column value_length variable_type truncation_option))

Key Options:

  • variable_type: Currently supports *LCL (local).
  • truncation_option: *NONE, *LEFT, *RIGHT, *ALL.

Example:

UNVVTSND SETVAR((&CUSTNAME 5 10 *DFT *LCL *ALL))

This extracts the value starting at row 5, column 10 until the first space, trims all spaces, and stores it in &CUSTNAME.

Control Flow Statements​

Control flow statements in UNVVT scripts allow you to direct execution based on conditions, handle exceptions, and manage script termination. These constructs make scripts dynamic and adaptable.

1. IF Clause​

The IF clause processes commands based on the value of a logical expression.

Syntax:

IF COND(logical_expression) THEN(command)

info

The only command currently supported in the THEN branch is: GOTO CMDLBL(label)

Example:

IF COND(&STATUS = 'ERROR') THEN(GOTO CMDLBL(ERROR_HANDLER))
  1. MONMSG

The MONMSG command monitors for exception messages. It applies to the command on the previous line in the script.

Syntax:

target_command
MONMSG

Example:

ADDLIBLE QTEMP  
MONMSG

3. Return​

The RETURN command exits script processing.

Syntax:

RETURN [CODE(return_code)]

Notes:

  • The optional CODE parameter specifies the end severity (0-99) for the UNVVT completion message.
  • If specified, the CODE value will only elevate the current severity; it cannot lower an already higher severity.

Example:

RETURN CODE(10)