HiLMAs Intro page

Introduction

"Practice is the best of all instructors."
Publilius

In this introduction, we will use some working examples to explain the features of HILMAS. There are only simple programs or fragment of code, not particularely useful, but in these examples are showed some basic elements present in almost every useful program.

Input from user's terminal.
Do you remember first programming examples in BASIC? This is a similar dumb example.
   COPY HILMAC
 PROGRAM NUMBERS,TSO 
    SAY 'Please enter a number.'
    INPUT NUMBER1
    SAY 'Now enter a number to add to the first number.'
    INPUT NUMBER2
    EDIT2NUM NUMBER1,N1
    EDIT2NUM NUMBER2,N2
    LET SUM,N1,+,N2
    SAY 'The sum of the two numbers is ',SUM,'.'
 ENDPROG 
   COPY HILVAR
NUMBER1 DS CL6
NUMBER2 DS CL6
N1      DS F
N2      DS F
SUM DS F
After you have assembled this program, if executable is in a load library visible by your TSO session, you can run it typing, in a ISPF command line:
===> TSO NUMBERS
('TSO' is needed because you are in ISPF environment) and in your screen see:
  Please enter a number. 
 23
  Now enter a number to add to the first number.
 45
  The sum of the two numbers is 68.
 ***
As you can note, INPUT and SAY instruction are the way to accept and display data from and to your terminal; its use is similar (and borrowed by !) to Basic and REXX languages.
While SAY instruction accept every variable type, INPUT instruction can parse user input only in string variables (as NUMBER1 and NUMBER2 in example), so to do numerical calculation over this input you must convert it in numerical variables with EDIT2NUM instruction.
To do some calculation use LET instruction, even if its use is not so simple as in Basic.
If you want use this program 'in batch mode', you can accept input directly from command line, in this way:
  PROGRAM NUMBERS,TSO
     PARSE $PARAM,WITH,NUMBER1,NUMBER2
     EDIT2NUM NUMBER1,N1
     EDIT2NUM NUMBER2,N2
     LET SUM,N1,+,N2
     SAY 'The sum of the two numbers is ',SUM,'.'
  ENDPROG 
You run the program writing:
===>  TSO NUMBERS 23 45
and the answer is directly on the screen, without interaction.
Every thing written near the program name at recall time (the two numbers in this case) is copied in Hilmas system variable $PARAM: then, every word is divided in a proper variable with PARSE instruction.
Note COPY instead of /INCLUDE: in this MVS environment is used another way to include the needed HILMAS deck.
Flow control.
Hilmas is a structured language, that is possible build every program without using GO TO instruction because there are flow-control instructions by which is possible to solve every procedural problem: as stated by over 20 years of programming experience, a complex program built with a structured language (and above all using only structured blocks) is more easy to plan, to code, to debug and maintain.
In Hilmas there are a plenty of control structure as in other structured language as Pascal, C or REXX.

There are looping instructions as in this example:
   FOR OUTER,1,2
      FOR INNER,1,2
         SAY 'HIP'
      NEXT
      SAY 'HURRAH'
   NEXT
The output from this example is:
   
   HIP
   HIP
   HURRAH
   HIP
   HIP
   HURRAH
OUTER and INNER variables must be integer variables (type F or H) and start and limit of the count of FOR instruction can be a numeric constant or a integer variable.

Now another example to see the use of a two branch control instruction IF/THEN/ELSE and multibranch instruction SELECT/WHEN.
* This example receives input with a person's age and sex.  In reply, 
* it displays a person's status as follows:
*      BABIES    -  under 5
*      GIRLS     -  female 5 to 12
*      BOYS      -  male 5 to 12
*      TEENAGERS -  13 through 19
*      WOMEN     -  female 20 and up
*      MEN       -  male 20 and up
******************************************************************
 PARSE $PARAM,WITH,EAGE,SEX,.
 EDIT2NUM EAGE,AGE
 SELECT
  WHEN (AGE,<,5) THEN                /* person younger than 5 */ 
    MOVE 'BABY',TO,STATUS
  WHEN (AGE,<,13) THEN               /* person between 5 and 12 */
      IF (SEX,=,'M') THEN            /* boy between 5 and 12  */
         MOVE 'BOY',TO,STATUS
      ELSE                           /* girl between 5 and 12 */    
         MOVE 'GIRL',TO,STATUS
      ENDIF 
  WHEN (AGE,<,20) THEN               /* person between 13 and 19 */
    MOVE 'TEENAGER',TO,STATUS
  OTHERW
    IF (SEX,=,'M') THEN              /* man 20 or older */
      MOVE 'MAN',TO,STATUS                                              
    ELSE                             /* woman 20 or older */
      MOVE 'WOMAN',TO,STATUS
    ENDIF                                        
 ENDSEL                                                
*                                                    
 SAY 'This person should be counted as a ',STATUS,'.'
  . . . . . 
AGE    DS  F
EAGE   DS  CL3
SEX    DS  CL1
STATUS DS  CL8
The line command input is divided in two variables: EAGE that contain the age in character (edited) format, and SEX (a variable of only one character). The EAGE is transformed in numeric variable AGE with EDIT2NUM instruction and multibranch instruction SELECT is used to determine the correct range of age. Next, in certain ranges instruction IF is used to determine if the person is a male or female.
Note the use of round parenthesis and commas to write the IF and WHEN condition; more conditions can be joined in the same IF using AND and OR operators, as in the next example, but nested conditions are not permitted.
Note the use of comments between '/*' and '*/' in a C or REXX style: indeed the style have no importance because every thing after the arguments of the instructions are considered comments; also 'THEN' word is a comment.

This program ask you the number of a month, then tell you the number of days of this month.
  SAY 'To find out the number of days in a month,'
  SAY 'Enter the month as a number from 1 to 12.'
  INPUT EMONTH
  EDIT2NUM EMONTH,MONTH
      SELECT
         WHEN (MONTH,=,9),OR,(MONTH,=,4),OR,(MONTH,=,6),OR,(MONTH,=,11) THEN
            MOVE '30',TO,DAYS
         WHEN (MONTH,=,2) THEN
            MOVE '28 or 29',TO,DAYS
         OTHERW
            MOVE '31',TO,DAYS
      ENDSEL
  SAY 'There are',DAYS,'days in Month',MONTH,'.' 
      . . . . .
EMONTH  DS   CL4
MONTH   DS   F
DAYS    DS   CL4
Note that ORed conditions in the first WHEN; in Hilmas if more conditions are present, these are evaluated from left to right: there isn't any operator precedence in Hilmas.
File access and display.
In this example we read a file, from first to last record, and print it mantaining printer control character in column 1.
 PROGRAM PRINTCC,DOS
   INPUT PCARD
   WHILE ($EOF,=,'F') DO
      SAY LINE,CC=PCODE
      INPUT PCARD
   ENDWHILE
 ENDPROG
/INCLUDE HILMAS VAR
PCARD  DS 0CL80
PCODE  DS  CL1
LINE   DS  CL79
This program is a simple loop with a exit for End-of-file condition.
$EOF is a Hilmas built-in variable that is filled by file-read instructions: its value is 'F' (False) if is not End-Of-File, otherwhise is 'T' (True).
INPUT instruction read from "standard input" (inline punched card, in batch environment), SAY, write on "standard output", that is in SYSLST in VSE or SYSPRINT in MVS. Note that input record length is 80 bytes, that is the length of variable PCARD: this variable indeed is a "Redefine" of the next PCODE and LINE.

You can read directly from a file with some little modifications:
 
 PROGRAM  READFIL,MVS
   FOPEN 1,DDNAME=MYDD,TYPE=ESDS
   FREAD 1,RECORD
   WHILE ($EOF,=,'F') DO
      SAY (RECORD,80)
      FREAD 1,RECORD
   ENDWHILE
   FCLOSE 1
 ENDPROG
/INCLUDE HILMAS VAR
RECORD DS  CL100
MYDD   DS  CL8
With FOPEN instruction a VSAM ESDS file with DDName in string variable MYDD is opened; then with FREAD instruction every record is sequentially read and displayed. The file number ('1' in this case) is simply a file identifier, and can be a number from 1 to 20; instructions relating to the same file must have the same file number.

Note that the same program without any change can be used in CICS environment: here FOPEN instruction really open file to CICS (if isn't already opened).
Test recursivity.
The first example in a programming course of recursivity is a reckon of a factorial of a (small!) integer number, so go on.
/INCLUDE HILMAS MAC
* ----------------------------------------
* FACTORIAL RECKON - TO TEST RECURSIVITY
* ----------------------------------------
PROGRAM FATTOR,CMS,LSTACK=1000      <---- NOTE! Define a stack 
   SAY 'Write a number (not over 20) to reckon Factorial N! :'
   INPUT NUMBER
   EDIT2NUM NUMBER,I
   IF ($DATAERR,<>,' ') THEN
      SAY 'Not Numerical value.'
      EXIT
   ENDIF
   IF (I,>,20),OR,(I,<,0) THEN
      SAY 'Number must be between 0 and 20'
      EXIT
   ENDIF
   GOSUB FATT
   SAY F
   EXIT
*
* ---------------
* This Subroutine is Recalled Recursively
*
SUBDEF FATT,SAVEVAR=(I)    <-- Mask input !! 
* --- I = Input, F = Output
   IF (I,>,0) THEN
      DEC I
      GOSUB FATT      Recall itself with input=input-1
      INC I
      LET F,I,*,F     Equal to FATT(I)=I*FATT(I-1)
   ELSE
      MOVE 1,TO,F
   ENDIF
   ENDSUB
*
ENDPROG
*
/INCLUDE HILMAS VAR
I DS F
F DS F
* --- INPUT PARAMETER
NUMBER DS CL8
END
Recursivity is not a default in Hilmas: it must be activated "manually" with some parameters:

With parameter LSTACK (in PROGRAM instruction) you specify the memory (in bytes) reserved for the dynamic stack used for recursivity (in this example 1000 bytes)

When you define the internal subroutine (with SUBDEF instruction) you must specify all the variables that must be saved in the stack (with SAVEVAR parameter), that is all the variables modified from the start of the subroutine to the point in which there is the self-recall (GOSUB instruction). In our example only the "I" counter is changed from the start of FATT subroutine to the GOSUB FATT.

This is a little complex procedure, but it works. See QUEENS program for another example.
And now some environment related examples: Introduction Part 2.