Variables.

In HILMAS declaring variables is mandatory: every used variable must be defined after last executable line of code (that may be a ENDPROG or a RETURN if it is a Subroutine), after the assembler directive 'COPY HILVAR' and before the last line of source code, that is END.

Every declared variable is visible (that is, usable) from any point of the source code, even from internal subroutines, if there are. Is not possible to change the 'scope' of a variable: all are in COMMON with every routine of the source file where are defined. If you want 'mask' the name and the usability of variables used by a routine, you must define this routine (and its variables) in a divided source file defined as a 'External Subroutine'.

Variables are basically of two types: numeric and string; numeric variables are compound by some sub-types: integer (short and long, that is, in Assembler terms, Half and Full), float (with floating decimal point), packed and zoned.

Defining variables is the only thing of HILMAS that must be defined in native Assembler: that is every variable must be written as though it were a true Assembler program.
Therefore variables must follow these rules:

• variable-name written from column 1 (mandatory)
  
• name-length of 8 characters maximum (or more, if use HLASM as Assembler compiler)
  
• 'DS' or 'DC' after variable name: 'DS' is Define Space (i.e. the variable is not initialized) and 'DC' is Define Constant (the variable is initialized with a value, but can be changed by program)
  
• type of variable (with length, if variable is a string)
• initializing value between quotes (') if is a 'DC' definition
  

The general outline is:
<var-name> DS <type>[Lnn]
<var-name> DC <type>[Lnn]'value'
L is followed by a number 'nn' that is the length in bytes

Types of variables are:

F	integer (Full, 4 bytes)
H	integer (Half, 2 bytes)
Z	zoned, that is a integer number with sign, whose length (mandatory) is equal to number of digits
P	packed, that is a integer number with sign, whose length (mandatory) is equal to half the number of digits
D	float, that is a fractional number with sign (8 bytes)
C	character, that is a string with a mandatory length from 1 to 255 bytes
A	address, that is a 4 bytes pointer to memory position (to a variable, to a program, etc.)

 

Some examples:

NUM1	DS	F	an integer not initialized
ITERAT	DC	H'1'	a short integer initialized to 1
LINE	DS	CL80	a string 80 characters long not initialized
TITLE	DC	CL10' Title '	a string initialized
ADR1	DS	A	a pointer variable

In general, in this manual:

For "integer" is meant type "F" or "H" indifferently.
For "string" is meant type "C" with length from 1 to 255 characters; length greater than 255 can be used for string arrays or for particular uses.
"var" is for a variable or constant; the type of "var" is explained in every instruction.
Constants are values enclosed in single quotes ( ' ) if type required is string, or a numerical constant if type is numerical.
Hilmas has some own variables whose name starts with a '$' that are filled by some specific instructions: for example $DATAERR variable is blank if a data error conversion don't occurs with EDIT2NUM instruction. These variable are freely usable as every other variables in Hilmas programs. A detailed list of these system variabiles are in Appendix.
So don't use varable names starting with '$' for your variables!

You have seen that an Hilmas managed string must have a length less then 256 characters; this don't mean that more long string definitions are forbidden: it means only that a string with length less than 256 can be used in Hilmas string handling statements like SUBSTR, PARSE, etc. Strings greater than 255 are commonly used for example to define space for an array or for building a screen map with BUILDMAP.
But with a such long string, you can use only MOVARRAY (or instructions that use pointers) to handle it; to use Hilmas string handling instructions you must first move a portion of a string in a second string with length less than 256.

In this release of Hilmas E type (that is, short floating point numbers, 4 bytes), cannot be directly managed.

Who cares of variable type?

In Hilmas is important, more that in native Assembler, to use the correct type for every variable: every Hilmas statement can process only a certain type of variable and some controls are done (at compile time) to verify this. If a variable isn't of the correct type a fatal error occurs, that is a MNOTE with seriuosness 16, that usually stops compilation. In Language Reference you can find, for every statement, what type of variables are accepted as instruction parameter.

Use of string variables.

In Hilmas the use of string variables is not so intuitive as in other languages, because strings are for its nature of variable length; when a string variable is defined in Hilmas (as a CLnn storage area), the length in byte is only the maximum length of the string; when the string is filled with words, the length of the string is the position of the last character before trailing blanks. The empty string in Hilmas is a string filled with spaces. In this way LENGTH instruction works, and the other string functions (as DELSTR or LTRIM) always fill the string with spaces on the right. On the other hand, string concatenation done with SAY instruction don't care of this internal length: all the strings are added with maximum length, unless length modifier is used for every string added.

Use of group variables.

With "group variables" we mean variables that are compound by more elementary variables or more elementary group of variables. This is achieved in COBOL with level number that show hierarchical level of variables: top level of a compound variable is 01 and the higher the level number of a following variable, the lower the item is in the hierarchy.
In Assembler (that is in Hilmas) this is achieved with a different technique: every group variable must have a 0 (zero) quantifier before: this is because a group variable don't use itself storage, memory is used only by the elementary variables by which is compound.

In the following example we compare such tecnique with a well-known COBOL equivalent structure.

ASSEMBLER						COBOL
STUDENT	DS		0	CL45	01			STUDENT.
ID	DS			ZL7		03		ID	PIC  9(7).
NAME	DS		0	CL26		03		NAME.
FIRST	DS			CL10			05	FIRST	PIC  X(10).
MIDINIT	DS			CL1			05	MIDINIT	PIC  X.
SURNAME	DS			CL15			05	SURNAME	PIC  X(15).
BIRTH	DS		0	CL8		03		BIRTH.
DAY	DS			ZL2			05	DAY	PIC  99.
MONTH	DS			ZL2			05	MONTH	PIC  99.
YEAR	DS			ZL4			05	YEAR	PIC  9(4).
COURSEID	DS			CL4		03		COURSEID	PIC  X(4).

In the same way zero quantifier before variable type can be used like a COBOL REDEFINE to change also the type of a variable; for example an integer can be redefined as a four characters string:

NUMBER  DS 0F
FOURCH  DS  CL4

Use of constant values.

Constants that is possible to use in Hilmas statements are of two types:

• strings, that must be enclosed with single quotes ('); a single quote inside the string can be written as a repeated single quote (' ')
• numbers, that are written without quotes

See Language Reference to find, for every statement, if an instruction parameter accept constants or not.

 

Variables initialization.

A starting value can be given to a variable in two ways:

• using DC (define constant) instead of DS in variable definition, specifying the initializing value enclosed in quote near the type, as you can see in preceding examples
• using MOVE statement and assigning a costant value to a variable in run time

Note that in CICS environment only the second method (the MOVE) is usable: this is because storage used by program is acquired and assigned by CICS only at run-time, when the program is loaded in main storage (all programs are reentrant in CICS), so a variable initialization cannot occur in compile time and even a DC variable are unassigned.

 

Hilmas System Variables.

Finally, there are some variables automatically defined in Hilmas, variables that are included with COPY HILVAR: these are used by some instructions and can be freely used by the program. All these variables start with a '$' in the name, to avoid conflicts with user variables.

Mostly, are used for error handling, as $DATAERR, that signals an error in conversion statement like EDIT2NUM, or $RCFILE that contain return code of some file handling statements, or $EOF that signals an End Of File.

Some of these variables are automatically filled when program starts, like batch COMMAREA in DOS/VSE, or like $TERMID, $TRANSID and $COMMLEN in CICS environment. Others are used for date conversion (CONVDATE) or to collect infomations about file (FSTATE).

A more detailed overview is in Appendix, whereas in Language Reference statements that use system variables are shown.

 

Arrays.

An array is a collection of variables all of the same type and length, arranged in a tabular form; in Hilmas up to three dimensions can be used for such tables; if only one dimension is used, array is a vector, otherwise is a table or a cube.

To define an array variable must be followed only these two basic rules:

• must be defined a variable with length equal (or greater) then the total amount of storage required by the array
• variable type must be of the same type of the elements stored inside

So a previous count of the storage to use must be done: if for example we must define a table of 10 x 15 strings with length of 8 characters we must allocate 10 x 15 x 8 = 1200 bytes:

STRARRAY   DS   CL1200

If type of the array element has a predefined fixed length (such integer, F or H) a multiplicator equal to the total number of elements can be used; for example to define a 3 dimension array of integers 8 x 20 x 2:

FARRAY   DS   320F

The preceding string array should also be defined as:

STRARRAY   DS   150CL8

Using the grouping tecnique previously seen, an array can be subdefined with variables redefining a new array:

STRARRAY   DS  0CL1200
STRINTGR   DS   300F

In this example if we use array STRARRAY we have string elements of 8 bytes each; using array STRINTGR we can view the same array, but compound by integer numbers.

In these variable definitions we see that number and amount of dimensions is lose (are not written in array definition); indeed these are used only when an element is stored or fetched by MOVARRAY instruction, so the same array can be "redimensioned" using a different MOVARRAY instruction: the limit is that total size and type must be the same. For example a string array of 50 elements of 10 bytes each, can be used as a string array of 100 elements of 5 bytes each or a table of 5 x 5 elements compound by strings of 20 bytes each.