How to Structure a Script

Before you enter a script into Source-IV or the script editor you must consider the enforced structure and the optional structure of the script. Enforced structure is the set of requirements a script must meet before it can be compiled and executed. Optional structure is the set of techniques you can use to make scripts more readable and easier to maintain.

Enforced Structure

Enforced structure includes the following requirements:

identifying the beginning of a script.
identifying the procedures and commands in a script. Data declarations, procedure names, and the .LONGVAR, .SHORTVAR, and .PREC commands must begin in the leftmost column. All other Script-IV commands must begin at least one tab stop from the left margin. Command elements must be separated by at least one space.

Scripts are divided into the Data Environment Section, which is optional, and the Procedures Section, which is required for most scripts. Only the Type 5 (copy) script, does not require a Procedures Section. The Data Environment Section and the Procedures Section are described below.

DATA ENVIRONMENT SECTION

This section is located at the beginning of the script. If you plan to use dictionary definitions, such as formats, screens, views, or links, you must declare them in this section. The type of script you plan to write and the order of the declarations of dictionary definitions help to create the data environment for a script. For more information on script types, see the section on Different Types of Scripts in this manual.

Data Declarations: Each data declaration, except for DN, consists of a data declaration command followed by the name of a dictionary definition or 4GL dataname. The command must begin in the leftmost column of the screen and the definition name must be indented at least one tab stop on the same line. For example:

VN 4SCUST, 4SSLSRP, 4SINVEN
LN 4SSALDT
SN 4STOPSC1, 4STOPSC2, 4SBOTSCR
DN INPUT-FLAG (1), VIEW -FLAG (1),
DN TEXT-FLAG (1)
DN TAX-RATE (2.0)

VN, LN, SN, and DN are data declaration commands. Each data declaration, except for the DN declarations, specifies at least one dictionary definition or 4GL dataname. More than one declaration is allowed on a line if the definition names are separated by commas or spaces.

The order of data declarations is important. When a script is compiled, the Script-IV compiler builds a data name table. Data names are placed in the table as they are encountered. In the example above, the 4SCUST view defined in the VN statement is associated with the 4SCUST format and the 4SSLSRP view is associated with the 4SSLSRP format. When a script that uses these data declarations is compiled, the data names defined in the 4SCUST format precede the data names defined in the 4SSLSRP format.

There is a possibility that duplicate data names will be placed in the table. When a script specifies a data name, the compiler searches for the first occurrence of the data name in the table. Using the example above, the 4SCUST format and the 4SSLSRP format both contain the SALES-REP-CODE data element. A script that specifies SALES-REP-CODE accesses the value defined for SALES-REP-CODE in the 4SCUST format because 4SCUST is declared before 4SSLSRP.

To access a different occurrence of the data name, the data name must be qualified by preceding it with a format name and a period. Using the example above, to access the value of the SALES-REP-CODE data element contained in the 4SSLSRP format, the script must specify the data name as 4SSLSRP.SALES-REP-CODE. However, to access the value of the SALES-REP-CODE data element contained in the 4SCUST format, the script can specify SALES-REP-CODE or 4SCUST.SALES-REP-CODE.

For more information on data declaration commands see the Script-IV Language Reference. For more information on dictionary definitions see the Dictionary-IV Reference Manual.

Compile-Time Definitions

Compile-time definitions contain data that is resolved when the script is compiled. They include the definition names specified in data declarations and script names used in INCLUDE commands:

Definition: Data Declaration Command

Data Name	DN
Format Name	FN
Link Alias	LA
Link Name	LN
Screen Name	SN
View Name	VN

Definition: Command
Script Name: INCLUDE

When specified in Script-IV commands, compile-time definitions are not enclosed by quotation marks. They cannot be used as parameters or passed to a command in a data name or variable. They must be fully specified, for example, OPEN SCREEN CUSSCRN1.

Run-Time Definitions

Run-time definitions contain data that is resolved when the script is executed. They include all program names, on-line help, message dictionary definitions, and script names except when used in the INCLUDE command:

Definition	Command
Message Dictionary	All Applicable
On-Line Help	All Applicable
Program Name	All Applicable
Script Name	All except INCLUDE

You do not have to declare these definitions before they are specified in Script-IV commands. They can be used in string constants, variables, data names, or expressions. These definitions can be soft-coded in your script, for example, OPEN MESSAGES “ARMSGS” or OPEN MESSAGES MESSAGE-LIST.

Data Names: Data names can be defined to hold string, integer, or decimal data. Additional attributes can be specified. Data names only hold a single type of data. For example, if CUS-NAME is defined, it is handled as a single element. If it needs to be handled as a first and last name, you must define it as two parts, for example, CUS-NAME-FIRST and CUS-NAME-LAST.

Data names can be used in expressions, functions, assignments, and calculations. A data name is limited to a length of 20 characters. Valid characters are uppercase and lowercase alphabetic characters, numerals, the hyphen character, and the underscore character. Data names must not contain a period or any special characters that may cause a conflict in Script-IV syntax. Data names must not conflict with any procedure names, declared format, link, screen, or view names, or keywords. If a data name has the same name as a system variable, the data name takes precedence.

Because data names are treated as single elements in scripts, substring operations cannot be performed on data names. However, the value in a data name can be moved to a variable on which string operations can be performed. Data names and variables can be used interchangeably in Script-IV syntax, except when specifically stated otherwise.

The four types of data names that can be used in Script-IV are local format data names, global format data names, link alias data names, and local variables.

Local Format Data Names

Local format data names defined in a format can be used in a script if the format has been declared by an FN command. These local format data names are dictionary-based because the format definition resides in Dictionary-IV.

When used in a script, these data names can, and in some cases must, be qualified by the format name. The name of the format must precede the data name delimited by a period, for example: ARFORMAT.CUS-NUMBER. This is necessary if your script uses data names that match in multiple formats.

For more information on local format data names see the description of the FN command in the Script-IV Language Reference.

Global Format Data Names

Global format data names are also defined in a format that resides in Dictionary-IV. The global format name always consists of a #
(pound sign) followed by three to eight characters.

The global format is not declared in the Data Environment section, but there are a number of ways to include global format data names in a script. For more information on global format data names see the section on Formats and data names in the Thoroughbred Basic Reference Manual.

The data in a global format is separate and independent from the data in a local format.

Link Alias Data Names

For each link alias declared in the script, a duplicate format with an additional set of matching data names is available to the script. To be accessed, these data names must be qualified by the link-name-alias rather than the format name. For more information on link alias data names see the description of the LA command in the Script-IV Language Reference.

Local Variables

Local variables can be defined in a script using the DN data declaration command. These local variables do not reside in the dictionary but are handled much like a local format data name. They are not qualified by a format name or other name, and therefore must be unique among any other local variables or data names used in a format. For more information on the DN data declaration command see the description of the DN command in the Script-IV Language Reference.

Physical and Logical Formats: During file maintenance, formats are used to access data in files. The format is linked to a physical data file through the link definition. This is a physical format, which describes a record and the data elements in the record along with element characteristics, defaults, valid values, and related data entry restrictions.

In scripts, a format can be used independently of a data file or link. This is a logical format, which can function like a data name or a variable. It can be assigned a value, its value can be printed or passed to another script, and it can generally be manipulated as an item of data in several commands.

The ability to manipulate a logical format provides greater freedom in script design. The following two examples each describe a different way to collect two data records and write them to two files.

Formats for Examples 1 and 2:

Format ONE(for screen ONE and LINK-ONE):

CUS-CODE
CUS-NAME
CUS-ADDRESS
SLS-CODE

Format TWO(for screen TWO and LINK-TWO):

SLS-CODE
SLS-NAME

Format ABC (for screen ABC; no link):

CUS-CODE
CUS-NAME
CUS-ADDRESS
SLS-CODE
SLS-NAME

The first example uses two independent screens and two physical formats.

Example 1:

PRINT SCREEN ONE
INPUT SCREEN ONE
ADD LINK-ONE
PRINT SCREEN TWO
INPUT SCREEN TWO
ADD LINK-TWO

Screen ONE is printed, then used to input data into format ONE. The data in format ONE is added to the data file using LINK-ONE. The same procedure is performed for screen TWO, format TWO, and LINK-TWO. In this example, the two screens can be displayed and manipulated independently of each other.

The second example accomplishes the same task as the first example using one screen with one logical format and two physical formats.

Example 2:

PRINT SCREEN ABC
INPUT SCREEN ABC
LET ONE = ABC
ADD LINK-ONE
LET TWO = ABC
ADD LINK-TWO

Screen ABC is printed then used to input data into format ABC. Format ABC contains data names from two different physical formats: ONE and TWO. Format ONE is loaded with data in a format assignment statement, and the data in format ONE is added to the data file using LINK-ONE. Format TWO is loaded with data in a format assignment statement, and the data in format TWO is added to the data file using LINK-TWO. In this example, a single screen is used to collect data.

Constants: Constants are data elements that do not change value during script execution. Constants are also called literals because values such as 1.25 or "string" are literal values. There are two types of constants: .

Numeric constants can be positive or negative numerals in integer, fixed point, or floating-point format.
String constants include ASCII characters delimited by quotes, such as “ABC”, or hexadecimal values delimited by dollar signs, such as $414243$.

For more information on constant values see the Thoroughbred Basic Reference Manual.

Elastic Variables: Elastic variables contain values that can change during execution. Elastic variables can dynamically change length. They are not declared in the data declaration area. Do not confuse local variables, which are dictionary-based data names, with the elastic variables described below.

Elastic variables are not dictionary-based. They provide another way of holding and manipulating data. Elastic variables do have the requirements of the data name definitions described above, but elastic variables do not promote data independence. They can be used to manipulate strings, to create temporary work areas, and to fulfill various formatting requirements.

Data names and elastic variable names can be used interchangeably in Script-IV syntax, except when specifically stated otherwise.

The types of elastic variables that can be used in Script-IV are elastic numeric variables and elastic string variables.

Elastic Numeric Variables

Elastic numeric variables contain numeric values. These values can be integers, fixed-point numbers, or floating point numbers. You can use the LET command to assign numeric values to the elastic numeric variables you define.

For more information on how to define elastic numeric variables see the Thoroughbred Basic Reference Manual. To establish control of naming conventions for elastic variables please refer to the descriptions of the .LONGVAR and .SHORTVAR commands in the Script-IV Language Reference. To specify how integer values are rounded please refer to the descriptions of .PREC and PRECISION in the Script-IV Language Reference.

Elastic String Variables

Elastic string variables contain string values. These values are non-numeric values that can range up to 65000 bytes long. You can use the LET command to assign string values to the elastic string variables you define.

For more information on how to define elastic string variables see the Thoroughbred Basic Reference Manual.

Restrictions on Elastic Variables

Under some circumstances you cannot define elastic variables with certain names. This restriction applies to 8INPUT Pre/Post Processing scripts and File Maintenance Pre/Post Processing scripts. For a list of restricted elastic variable names, please refer to on-line documentation.

You cannot define a Script-IV reserved word or a Thoroughbred Basic reserved word as an elastic variable name. For a list of reserved words please refer to the Script-IV Language Reference.

System Variables: System variables are numeric or string variables that Script-IV defines to help you manage certain types of tasks. In most cases, these variables interact with a Script-IV command.

Examples of Script-IV system variables include:

VARIABLE	Interacts with
COLUMN	INPUT SCREEN
ESCAPE	ESCAPE-KEY
FIELD	INPUT SCREEN
FILE-SUFFIX	OPEN
LENGTH	INPUT SCREEN
LINE	INPUT SCREEN
MENU-PARMS	Not Applicable
SYSTEM-DATE	SET
SYSTEM-TIME	SET
TERM-KEY	INPUT MESSAGE INPUT SCREEN
TERMINAL-DATE	SET
TEXT-END	READ

For more information on these system variables see the descriptions in the Script-IV Language Reference.

PROCEDURES SECTION

The procedures section consists of at least one independent procedure that contains Script-IV commands. Procedures are the main body of the script.

The first procedure in a script is the main procedure and controls all other procedures. When the main procedure is completed, the script automatically terminates. If there are no commands in the main procedure, the script will automatically terminate without processing further procedures.

Give some thought to the design and organization of script procedures. Long-term productivity can be increased by spending time in the analysis and design phases of product development. Prior planning can decrease development time, enhance script readability, and facilitate script maintenance.

A procedure consists of a procedure name followed by one or more script commands.

Procedure Names: The procedure name:

Identifies the body of commands as a unique procedure within the script.
Must be different from all other procedure names in the script or in any included script. The procedure name must not conflict with any reserved words.
Must begin in the leftmost column of the screen and must appear on a line by itself. However, comments preceded by ! (exclamation point) can follow the procedure name.
Can be from 1 through 64 characters long. It cannot contain space characters. The first 20 characters must be unique.
Must not be broken or fall onto two lines when referred to by a command.
Can consist of uppercase or lowercase characters, numerals, and the - (hyphen) character.

Script-IV Commands: Script-IV commands can be grouped into a procedure that performs a task. Since the commands tell the system what to do rather than how to do it, the procedure is self-documenting.

Commands perform operations on data elements such as constants and variables, control input and output, and specify how scripts are executed and processed. For example:

To assign a value to a variable, you can use the LET or SET command.
To specify a branch in execution, you can use the IF/THEN/ELSE/ENDIF command.
To control file access, you can use the OPEN, LOCK, UNLOCK, and CLOSE commands.
To control I/O to disk, you can use the ADD, CHANGE, DELETE, or READ command.
To use Dictionary-IV definitions, you can use the INPUT SCREEN, INPUT MESSAGE, PRINT HELP, PRINT VIEW, or CONNECT commands.

Commands must be indented at least one tab stop from the first column on the screen. Additional indention and line spacing can be used for readability.

Commands are sensitive to spaces. Use a space to separate all elements within a command such as the command, clauses, options, parameters, data names, and so on. This is required for the compiler to accept the commands and, if not used, may cause a syntax error. The only exceptions to this are the ( ) (parentheses) characters when they are used for grouping. In this case, a space precedes but does not follow a left parenthesis, and a space follows but does not precede a right parenthesis.

Optional Structure

Optional structure, or appearance, includes the following:

command indention
line spacing
punctuation

Although optional structure does not affect script compilation and execution, it can have an impact on readability and maintenance. Because optional structure provides flexibility, it is important to set standards of consistency for your scripts.

The Script-IV language is a self-documenting language designed for readability and easy maintenance. Command syntax is simple and descriptive. Software developers who prefer terse code can build readable procedures. However, script readability can be enhanced by using the following options.

Command Placement: More than one command can be placed on one line of a script, but this coding style can produce procedures that are hard to read. Starting a Script-IV command on a new line helps produce readable code.

Many Script-IV commands contain clauses. Placing each clause on a new line enhances readability.

Comments: Comment or remark lines are not compiled. Any line that contains an * (asterisk) in the leftmost column is treated as a comment line. You can use comment lines as dividers to separate procedures or segments within a procedure. For example:

*-----------------------------------------
* Customer Record Maintenance
*-----------------------------------------

Optional Syntax Elements: Optional syntax elements do not affect command function; they enhance readability. Three common optional elements are IS, ARE, and PROCESS. For example, the following two clauses perform the same function:

MISSING TOTALS-PROCEDURE

MISSING KEY PROCESS IS
   TOTALS-PROCEDURE

Optional Punctuation: The ; (semicolon) and . (period) can be used to mark the end of a command. The script compiler ignores these punctuation marks.
Optional Line Spacing: Blank lines can be used to separate logical segments of your script. You can separate procedures or groups of procedures from each other, or separate one command from another. Blank lines are not compiled. Because scripts are compressed before they are stored on disk, blank lines do not require storage space.
Optional Indention: You can indent commands and their subordinate clauses to highlight the clauses and display processing hierarchy. If you develop and follow your own standards for indenting, it can strengthen the structure of your scripts.

Example 1

You can use indention for a command that requires many clauses, and use a blank line to separate the command from the next command:

CHANGE CUSFIL USING KEY CUS-NUMBER
   BUSY PROCESS IS  BUSY-MESSAGE
   END PROCESS IS    END-OF-FILE
   PROCESSING IS  UPDATE-CUS
   TEXT "A"
      WINDOW LINE IS 15
            COLUMN IS 0
            CHARACTERS PER-LINE ARE 60
            NUMBER LINES ARE 6

IF CUS-NUMBER > "T0000" THEN
   PRINT SCREEN CUSSCRN1 CLEAR
   DO LOCAL-CUSTOMERS
ELSE
   DO COUNT-MAIL-ORDER-CUSTOMERS
   IF COUNT1 > 1000 THEN
       PRINT MESSAGE "N,150"
       IF MAIL-ORDER-FLAG = "y" THEN
           DO BULK-MAIL
       ENDIF
   ENDIF
   DO CLOSE-MAIL-ORDERS
ENDIF

Example 2

The first part of this example demonstrates lack of structure and poor readability:

IF SORT-NO = 0 THEN
   CHANGE ATAPMSTR USING KEY NEXT
   PROCESSING IS EDIT-RECORD;BUSY IS
   BUSY-RECORD;END IS END-OF-MAIN-FILE
   ELSE CHANGE ATAPMSTR USING KEY SORT
   SORT-NO NEXT
   PROCESSING IS EDIT-RECORD;BUSY IS
   BUSY-RECORD;
   END IS END-OF-MAIN-FILE
ENDIF

The second part of this example uses the same command and demonstrates how optional structuring can increase readability:

IF SORT-NO = 0 THEN
   CHANGE ATAPMSTR USING KEY NEXT
      PROCESSING IS EDIT-RECORD
      BUSY IS        BUSY-RECORD
      END IS         END-OF-MAIN-FILE

ELSE
   CHANGE ATAPMSTR USING KEY SORT SORT-NO
   NEXT
      PROCESSING IS EDIT-RECORD
      BUSY IS        BUSY-RECORD
      END IS         END-OF-MAIN-FILE
ENDIF

From the Script-IV Developer Guide, version 8.9.1. Open this page in the PDF