Quick reference

"Words! Words! Words!"
Shakespeare, Hamlet, II,2

Home | Intro | Tutorial | Download | Highlights | AboutMe

General syntax rules.

Note: square brackets are for optional element.

A Hilmas instruction is compound by:

[LABEL] INSTRUCTION-CODE PARAMETERS [COMMENT]

Format is free, with these restrictions:

These are simply the rules of Assembler/370.

Program structure.

The general structure of a program is:


/INCLUDE HILMAS.DECK (environment dependent)
 PROGRAM program-name,operating-system 
   body of program
 ENDPROG
/INCLUDE HILMAS.VAR (environment dependent)
   variables definition
 END

Variables are defined exactly as an assembler program:

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.

Instructions quick reference.

Instructions are not in alphabetical order but are divided by type.
.

Environment.

PROGRAM program-name,operating-system [,VSAMERR=label,COMAREA=,SYSIN=,SYSOUT=,LSTACK=0,PSEUDO=NO]

must be the first HILMAS instruction; program name is the name of the program (8 characters max.) and operating-system can be MVS, DOS (i.e. VSE), CICS, TSO or CMS. You can pass parameter (that is some extra words) when call a HILMAS program:
these are get back in a HILMAS system variable called $PARAM. In a batch program parameters can be specified in PARM= (VSE and MVS) parameter, in PGM=programname JCL instruction. In CICS, $PARAM variable is automatically filled with input Commarea if the program is recalled by another program.
If you don't write environment dependent instructions (for example EXEC CICS), the operating-system parameter is generally the only thing you must change to port the program to another environment, even from a batch to interactive or vice versa, if you use only line mode I/O instructions.
LSTACK parameter is required only if you write a recursive program or subroutine
COMAREA and PSEUDO are environment dependent parameters that can be used by CICS programs.

ENDPROG

must be the last executable HILMAS instruction

ENVIRON [NEXTCODE,][PADCHAR=' '][,SAVEREG=NO][,PSEUDO=NO]

required only in rare cases to modify addressing mode, or environment compilation of HILMAS

Flow control.

FOR var1,var2,var3[,STEP=integer]

<statements>

NEXT

This is the loop For/Next:
the instructions between FOR and NEXT are repeated by (var3 - var2) times, and var1 is the integer variable containing the loop counter; the optional STEP= indicates the step count; the default is 1 and can be a negative constant number.

 

IF (var1,comp1,var2),op,(var3,comp2,var4)... [THEN]

<statements>

[ELSE]

<statements>

ENDIF

The parameters of IF instruction are compound by:
var : every numeric or string variable
comp: comparison operands: = (equal), <> (not equal), < (minor), > (major), <=, >=
op: AND and OR operands.
The first branch is executed if condition is True, second if condition is False.
The ELSE clause (and the second branch) is optional. THEN is a comment.
Nested conditions are not permitted; truth values are computed from left to right and there isn't any operator precedence in this computation.

 

WHILE (var1,comp1,var2),op,(var3,comp2,var4)... [DO]

<statements>

ENDWHILE

This is the loop While/Do:
the instructions between WHILE and ENDWHILE are repeated until the condition specified is True; the conditions are specified in the same manner as IF instruction. DO is a comment.

 

REPEAT

<statements>

UNTIL (var1,comp1,var2),op,(var3,comp2,var4)...

This is the loop Repeat/Until:
the instructions between REPEAT and UNTIL are repeated until the condition specified is False, i.e. the exit is when the condition is verified; the conditions are specified in the same manner as IF instruction.This loop is executed at least one time.

 

SELECT

WHEN (var1,comp1,var2),op,(var3,comp2,var4)...

<statements>

[OTHERW]

<statements>

ENDSEL

This is the multi-branch condition Select/When:
there are one or more When conditions: if the condition is True, the statements down are executed, otherwise successive When condition is tested.
OTHERW is optional: if it is specified, its statements are executed if all When conditions aren't True. The conditions are specified in the same manner as IF instruction.

 

BREAK

Used inside a Select/When condition, exit before the end of When condition

NOBREAK

Usually, when a Select/When condition is satisfied, is executed only the first satisfied condition. Used inside a Select/When condition, with NOBREAK instruction, a branch is done of the following WHEN condition and, if satisfied, is executed

ITERATEF

LEAVEF

Used inside a For/Next loop, LEAVEF exit before the end of loop and ITERATEF begin again the loop before the NEXT instruction.

ITERATEW

LEAVEW

Used inside a While/Endwhile iteration, LEAVEW exit before the end of loop and ITERATEW begin again the loop before the ENDWHILE instruction.

ITERATER

LEAVER

Used inside a Repeat/Until iteration, LEAVER exit before the end of loop and ITERATER begin again the loop before the UNTIL instruction.

CONTINUE

Dummy instruction: do nothing.

EXIT [return-code]

Terminate program immediately with the return-code specified: must be a integer variable or constant; default 0.

 

Subroutine handling.

GOSUB subroutine

recall the internal subroutine

SUBDEF subroutine[,SAVEVAR=(var1,var2,...)]

define the start of internal subroutine.
All the variables defined in main program are visible in this subroutine, so there isn't parameter passing in this type of subroutine.
SAVEVAR= is only for recursive subroutines and normally is not needed.

ENDSUB

define the end of internal subroutine.

SUBEXIT

is a exit in the body of the internal subroutine.

CALL subroutine[,(param1,param2,...)]

recall of external subroutine; that is a routine compiled separately and linkedited together.
param1, param2, etc. are HILMAS variables to pass to subroutine.

ROUTINE subroutine,sist-op[,(param1,param2,...),VSAMERR=NO,RENT=NO]

define the start of an external subroutine written in HILMAS; that is a routine compiled separately and linkedited with another program. The source of the main program can be written in any language, provided that standard conventions of calling parameters are followed
param1, param2, etc. are HILMAS variables passed to this subroutine from main.

RETURN [(param1,param2,...)]

define the end of external subroutine; param1, param2, etc. are the same parameters in input to the routine, if you want change these values in the calling program.

 

Variables assignment.

MOVE var1,INTO,var2

the value of var1 is put in var2; the type of vars must be the same
(INTO can be shorted in TO)

MOVARRAY array,(x[,y,z]),INTO,var[,D1=d1,D2=d2][,SLEN=l-str]

MOVARRAY array,(x[,y,z]),FROM,var[,D1=d1,D2=d2][,SLEN=l-str]

the value of array variable indexed by x (and y, z, if array have 2 o 3 dimensions), is put in (if there is INTO) or filled by (if there is FROM) variable var; the type of vars must be the same; D1 is the first dimension (a integer constant) and is mandatory if array has 2 or 3 dimensions; D2 is the second dimension if array has 3 dimensions.
If array is a string-array, SLEN is the mandatory length of every string element.

ADDR var,address[,MODE=EXTERN]

the address of var is put in address

PTR2VAR address,var[,length]

the value pointed by address is put in var, the length, if not specified, is the same of var

VAR2PTR var,address[,length]

the value of var is put in variable pointed by address, the length, if not specified, is the same of var

PTR2PTR address1,address2,length

the value pointed by address1 is put in variable pointed by address2; variable length is mandatory

LET var,(expression1),op,(expression2)....

arithmetic expressions are evaluated and the result is put in var. Arithmetic operator (op) permitted in expressions are:

+ add
- subtract
* multiply
/ divide

and the operands can be integer or float, variable or constants Operator precedence is NOT obeyed: evaluation follows its order, from left to right; use parentheses to change this order. Parentheses cannot be nested.

Input / Output Statements.

SAY var1,var2,(var3,length),....[,VAR=string]
[,PAGE=NEW][,CC=varchar][,ROW=][,FILE=numfile]

display var1, var2, etc. at terminal in interactive environment (CICS, TSO and CMS); print in standard output in batch (MVS or VSE); vars output can be limited with length.
With FILE= this output line can be written on file previously opened (every environment);
With VAR= this output is written in a string variable (every environment);
With ROW= this line is written on specified row number (CICS only)
With PAGE= and CC= is managed ASA control character in column 1 (batch environment)

INPUT string1,string2,string3,...[,SEP=character]

accept a line of data from user's terminal (CICS, TSO or CMS) or from standard input (MVS or VSE):
the line in input is parsed and its words are assigned to string1, string2, etc.
the separator character is blank, if it is not changed by SEP=

CLEAR

video terminal is blanked (CICS, TSO or CMS only)

FOPEN numfile[,DDNAME=,TYPE=,ACCESS=,MODE=[,RESET=]]
[,FN=,FT=,FM=,RECFM=][,LRECL=][,CMSDEV=]

open a file: numfile is a constant number from 1 to 20 that is associated to this file; other parameters are environment dependent:
DDNAME= is the logical name of the file in MVS/TSO or VSE
TYPE= is the type of file: SAM or KSDS/ESDS/RRDS in MVS/TSO or VSE
LRECL= is the record length
ACCESS= is the access mode of the file: can be DIR (direct) or SEQ (sequential)
MODE= can be INPUT or OUTPUT
FN=,FT=,FM=,RECFM= are for CMS only

FCLOSE numfile1,numfile2,numfile3,....

close files corresponding to numfile1, numfile2, etc.

FSTATE numfile[,FN=filename,FT=filetype[,FM=filemode]]

Collect some information about a opened file. Can be used with VSAM file and CMS files.

FERASE numfile,FN=filename,FT=filetype[,FM=filemode]

CMS only; delete the specified file

FREAD numfile,string[,KEY=key,KEYLEN=key-length,
RECLEN=rec-length,UPDATE=NO]

read a record from the file numfile; string contain this record and its length must be greater or equal the record length
key is the variable containing the read-key if the file is a KSDS or a RRDS
key-length is the length of this key
rec-length is the maximum record length: if a record is greater, the value in string is truncated

FSTARTBR numfile,KEY=key[,KEYLEN=key-length,MODE=/BACK/BACKLAST]

Start a browse of a file (correspond to Dynamic access in COBOL)

FENDBR numfile

End a browse of a file (CICS only).

FWRITE numfile,string[,RECLEN=rec-length][,RECNUM=rrn]

Write a record in a file.

FREWRITE numfile[,string,RECLEN=rec-length]

Rewrite (i.e. update) a previously read record of a VSAM file.

FDELETE numfile

Delete a previously read record of a VSAM file.

 

Full screen display management.

BUILDMAP OUT/OUTNEXT,map[,(field1[,row[,column[,attribute[,length]]]]), [(field2,...)][,CURSOR=YES/NO/(row,column)][,OPTION=ALARM]

With this instruction is possible construct a 3270 data stream in a map variable (a string variable about 2000 bytes long - just a full screen). The various fields specified are translated and inserted in map variable; every field variable is enclosed in parenthesis and corresponding position and attribute (protect, unprotect, etc.) is specified with it. With OUTNEXT parameter is possible to add other fields to a partially built 3270 data stream.

CONVERSE map-out,map-in[,MAP=map,MAPSET=mapset][,LEN=$MAPLEN]

After you have built a 3270 data stream in map-out variable, use this instruction to display it on the screen. If map contain digitable fields, these are written in map-in variable (also a string 2000 bytes long ), coded in 3270 inbound data stream format. Input send key is coded in Hilmas variable $AID.

BUILDMAP IN/INNEXT,map[,(field1[,row[,column[,disposition[,length]]]]), [(field2,...)][,CURSOR=(row,column)][,OPTION=UPPER]

With this instruction is possible decode a 3270 inbound data stream present in a map variable and put its fields in corresponding Hilmas variables. Specified fields are the unprotected fields of the map displayed with CONVERSE instruction and filled by terminal operator. With INNEXT parameter is possible to decode other fields after you have partially decoded a 3270 data stream.

BUILDMAP ALTER,map-out[,(field1[,row[,column[,ATTR]]])[,(field2,...)]

With this instruction is possible alter the fields attribute of a 3270 outbound data stream present in a map-out variable.

The typical order in which these instructions must be used is:

BUILDMAP OUT (and optionally BUILDMAP OUTNEXT) to construct the map,
CONVERSE to display it on the screen,
BUILDMAP IN (and optionally BUILDMAP INNEXT) to put input filelds of the map in Hilmas variables.

These instuctions are environment independent, that is, if you build a map with these instructions for TSO (or CMS) environment, without any change, this program display the same map in CICS. See MASTMIND game as example in Download page.

Finally, in CICS environment these instuctions support Pseudo Conversational mode in a transparent manner, that is without any change to program. (with PSEUDO parameter in PROGRAM instruction).

 

Miscellaneous Statements.

RANDOM integer,limit1,limit2

generate a random integer number between limit1 and limit2

RANDSEED

randomize generation of random numbers using actual time

TIMEDATE

update HILMAS variables containing time and date

CONVDATE

convert date using standard HILMAS variables

SLEEP seconds

the program waits for specified seconds

MEMALLOC address,SIZE=integer

dynamically allocate integer bytes of memory starting at address

MEMFREE address,SIZE=integer

dynamically deallocate integer bytes of memory starting at address previously allocated

String Functions.

UPPER string

Translate a string in upper case.

COPIES string,characters

fills string with characters

LTRIM string[,length]

align string at left, removing heading blanks

RTRIM string[,length]

align string at right, removing trailing blanks

TEMPLATE string-in,string-out,template[,FILL=X]

copies string-in in string-out using template, that is copying characters in position corresponding to character 'X' (a typical example: TEMPLATE DATE,PIC,'XX/XX/XX')

TRANSLAT string,table-in,table-out[,length]

characters of string found in table-in are converted to corresponding characters in table-out

OVERLAY substring,string,start[,length]

substring is superimposed to string starting by start

SUBSTR substring,string,start[,length]

a substring is extracted by string from position delimited by start and length

DELSTR string,start,length

a substring is deleted from string, from position delimited by start and length

POS p,substring,string[,start,length]

search substring inside string; if found, position is in p; if start is specified, is the starting position of search (default 1)

SEARCH p,table,string[,start]

if one of the characters in table is found in string, its position is p; (table is a string of characters).

INSERT substring,string,start[,length]

substring is inserted in string starting from start

LENGTH p,string[,PADCHAR=]

in p is put the length of string (delimited by blanks or delimited by specified PADCHAR=)

SQUEEZE string,table[,length]

from string are deleted all characters found in table

CENTER string[,length]

content of string is centered

WORD number,string,start,length

into string, word 'number' is searched and position is returned in 'start' and 'length'

PARSE string,WITH,str1,str2,str3,...[,SEP='character'][,SEPMODE=M/S]

string is divided in its words, that are put in str1, str2, etc.; separation character is blank, and can be changed using SEP=

 

Numeric Functions.

INC integer[,constant]

integer variable is incremented by 1 (or by constant)

DEC integer[,constant]

integer variable is decreased by 1 (or by constant)

ABS numeric-var

algebraic sign is removed from numeric-var

INT float

float variable is truncated to its integer part

BITAND var1,var2

bitwise AND between var1 and var2

BITOR var1,var2

bitwise OR between var1 and var2

BITXOR var1,var2

bitwise XOR (exclusive OR) between var1 and var2

 

Conversion Functions.

NUM2EDIT var,(string[,length,decimals])

convert numeric var (integer or packed) in string (if you want, specify string length and number of decimals)

EDIT2NUM string,var

convert string in numeric type of variable (type integer or packed)

VAR2HEX var,string[,length]

convert var in hexadecimal string

HEX2VAR hex-string,string[,length]

convert hexadecimal string-hex in a binary string

INT2PAC integer,packed

convert integer in packed variable

INT2ZON integer,zoned

convert integer in zoned variable

INT2FLO integer,float

convert integer in float variable

FLO2INT float,integer

convert float in integer variable

FLO2EDIT float,string

convert float in string variable

PAC2INT packed,integer

convert packed in integer variable

ZON2PAC zoned,packed

convert zoned in packed variable

ZON2INT zoned,integer

convert zoned in integer variable

INT2BYTE integer,character

convert integer in 1 byte character (follow EBCDIC)

BYTE2INT character,integer

convert 1 byte character in integer (follow EBCDIC)

HALF2INT half,integer

convert half integer (2 bytes) in fullword integer (4 bytes): in this case is the same that:
MOVE half,TO,integer

INT2HALF integer,half

convert fullword integer (4 bytes) in half (2 bytes): in this case is the same that:
MOVE integer,TO,half

VALIDPAC packed

validate a variable containing a packed numeric value

 

REXX communication (CMS and TSO only).

VAR2REXX (string,length),(rexxvar,name-length)

transform a string variable in a REXX variable.
rexxvar is a string variable containing the name of the REXX variable and name-length is its length
string is the variable containing the value to port in REXX
Obviously, the program must be called by a REXX program.

REXX2VAR (rexxvar,name-length),string

transform a REXX variable in a HILMAS string variable
rexxvar is a string variable containing the name of the REXX variable and name-length is its length
string is the variable that will contain the value
Obviously, the program must be called by a REXX program

STACK function,(string,length)

STACK statement handle the user stack, in VM/CMS or TSO environment only.
function can be:
PUSH (string is pushed on the stack)
PULL (the top of the stack is pulled in string)

See the full manual !

Home | Intro | Tutorial | Download | Highlights | AboutMe

1