Basic syntax rules.

Note: wherever in this manual square brackets are for optional element.

Writing rules.

A Hilmas instruction is compound by:

[LABEL] INSTRUCTION-CODE PARAMETERS [COMMENT]

Format is free, that is can be written wherever in the line (from column 2 to 71), with these restrictions:

• INSTRUCTION-CODE (i.e. IF, GOSUB, REPEAT, SAY, etc.) must NOT be in column 1
• LABEL is optional and must be in column 1 (normally, labels are never required)
• PARAMETERS depend by INSTRUCTION-CODE (for example, can be conditions to test in a IF instruction) and must be separated by commas, and must NOT contains blanks (except for literal strings delimited by single quotation marks (') )
• At least 1 blank must be used as separator between LABEL, INSTRUCTION-CODE, PARAMETERS and COMMENT
• PARAMETERS can be positional or not; positional parameters must precede not-positional parameters; parameters written in a form like PARM1= aren't positional and its positions are indifferent in respect to other not-positional parameters.
• A line cannot contain more than one instruction
• An instruction can be split in more lines, putting a character (usually an 'X' or '-') in column 72 and carrying on next line from column 16.
• A comment line must have '*' in column 1

Remember that more instructions in the same line aren't allowed.

These are simply the rules of Assembler/370, in particular INSTRUCTION-CODE is an Assembler macro name and PARAMETERS are its macro parameters.

Program structure.

The general structure of a Hilmas program is:

   COPY HILMAS  (environment dependent)
 PROGRAM program-name,operating-system 
   body of program
 ENDPROG
   COPY HILVAR (environment dependent)
   variables definition
 END

The first COPY statement includes the the huge Hilmas desk to expand every Hilmas macro written in the program; can be written in another manner if you are, for example, in ICCF, or can be entirely omitted if your assembling JCL automatically search and use Hilmas macros.

Every program must start with PROGRAM statement (written at least at column 2) with, at least two parameters:

• program name (8 character max.)
• environment name, that can be one of this five: MVS, DOS, CICS, CMS, TSO

In the following lines the program is written using the already seen rules.

Every program must end with ENDPROG statement without parameters. If a program must exit in advance (at run-time) before natural ENDPROG, use EXIT statement.

Then, the COPY HILVAR (or environment specific similar instruction) cannot be omitted, because in this position must be included the whole set of Hilmas system variables.

Then, in the next lines are defined all the variables used by the program; remember that defining of every variable is mandatory.

Finally, the END statement close the source; this is simply the END assembly directive.

 

Program input parameters.

For Input Paramaters we mean some short input data that generally are written near the program name, when we are starting the program in an interactive environment like CMS, CICS ot TSO; for example we write:

MYPROG 10 NAME1 10/03/01

Input Paramaters must be read by the program, so that can be used to do the wanted process.

In Hilmas parameter line is automatically read and its value can be found in Hilmas variable $PARAM; to divide the various words can be used PARSE statament; for this example, if we use in program MYPROG:

PARSE $PARAM,WITH,VAL1,CUSTOMER,DATE

User's parameters are written in proper variables: VAL1 will be 10, CUSTOMER will be NAME1 and DATE will be 10/03/01.

For batch environment (MVS and VSE), $PARAM is filled with the string in PARM=, an optional parameter in EXEC statement, in the JCL that start the program.

In CICS, $PARAM variable is automatically filled with input Commarea if the program is recalled by another program (and so cannot be started by the user).

Maximum length of $PARAM is 130 bytes and Hilmas variable $PARAML contain the effective length of the string written inside (for all environments).