HiLMAs Examples page

Other Examples

"Provando e riprovando."
Dante, Paradiso, c.III, v.3

Use of Hilmas in a CICS environment.

In an environment like CICS you can use inside a Hilmas program every CICS command you need, with EXEC CICS interface. These commands must be written following assembler coding conventions (in short omitting END-EXEC word of COBOL programs) and using the common program variables as command arguments. See CICSVSAM and other CICS programs in Download page, for more complex examples.
In this example the program ask to the user a program name to run with a LINK or a XCTL command, passing it a user defined COMMAREA.
/INCLUDE HILMAS MAC
* LINKPROG HIL
* -----------------------------------------------------
* Program to recall another program passing data in COMMAREA
*------------------------------------------------------
 PROGRAM LINK,CICS
    SAY 'Type program name:'
    INPUT PROGNAME
    SAY 'Write program recall type: (LINK or XCTL):'
    INPUT LINK
    SAY 'Write "COMMAREA" to pass:'
    INPUT COMMAREA
    LENGTH LEN,COMMAREA
    UPPER PROGNAME
    UPPER LINK
    SELECT
      WHEN (LINK,=,'LINK')
        EXEC CICS LINK PROGRAM(PROGNAME) COMMAREA(COMMAREA) LENGTH(LEN)
      WHEN (LINK,=,'XCTL')
        EXEC CICS XCTL PROGRAM(PROGNAME) COMMAREA(COMMAREA) LENGTH(LEN)
    ENDSEL
    SAY 'END of Transaction ",$TRANSID,'"'
  ENDPROG
 /INCLUDE HILMAS VAR
 I DS F
 LEN DS H
 *
 PROGNAME DS CL8
 LINK     DS CL4
 COMMAREA DS CL80
 END
   
Note that APRM CICS manual tell that the LENGTH parameter must be an HalfWord integer and we have defined LEN variable as H. You must forever follow the manual for the correct format: in this case an F definition of the LEN brings erroneous results.
For every CICS program you write, you must define it to CICS in PPT table (or in CEDA environment) and, to run it from a CICS session, you must define a four character transid in PCT linked to this program. In PPT table, Hilmas programs must be defined as Assembler programs.

But there are other implications in use of EXEC CICS interface: the program become not portable. If you think to bring the program you write in other interactive environment like TSO or CMS, you must, if is possible, don't use any EXEC CICS command: Hilmas allows some degree of environment independence with these instructions:

BUILDMAP and CONVERSE for a full screen Input/Output management
FOPEN, FREAD, FWRITE, FSTARTBR etc. to open, read, write a VSAM file

Specifically, if you use BUILDMAP and CONVERSE Hilmas instructions, you don't need to design and define CICS full screen maps, because these instructions dynamically build a 3270 data stream based on fields you specify on it. In this mode, no map is defined in PPT even if the program manages full screen maps. See Master Mind game program in Download page for an example of the use of these instructions.

Interfaces with OS macros.

Hilmas don't have an instruction to write to MVS console, so you must use native macro available in batch MVS Operating System.
  COPY HILMAS
 PROGRAM WTOCONS,MVS,SYSIN=NO,SYSOUT=NO
    INPUT TEXT
    MVC WTOMSG+4(60),TEXT    <--- a native assembler instruction
    WTO MF=(E,WTOMSG)        <--- an OS macro
 ENDPROG
  COPY HILVAR
TEXT   DS   CL60
WTOMSG WTO '1234567890123456789012345678901234567890123456789012345X
            67890 ',ROUTCDE=(2,11),DESC=(7),MF=L   <--- an OS macro
A TEXT is read from "standard input" and is written to console using macro WTO. This macro is written inside the program and amongst variables, to define the necessary space for the text of the message (as explained in "Macro Reference" manual). To write inside variable WTOMSG cannot use instruction MOVE because a 4 bytes displacement is needed, so use native Assembler instruction MVC. (Numerical sequence in WTOMSG string is only to count the length of the string and is next overwritten).

Test REXX interface.

REXX interface in HILMAS is the possibility to exchange values to and from REXX variables, and use REXX stack. See EXECIOVS program in Download page, for an interesting use of this capability.
 COPY HILMAC
* TESTREXX HIL ------------------------------------
* TEST HILMAS-REXX INTERFACE READING AND WRITING A VARIABLE
* -------------------------------------------------
 PROGRAM TESTREXX,TSO
* -- Get a variable named REXXVAR from a REXX program
    MOVE 7,TO,L
    MOVE 'REXXVAR',TO,REXXVAR
    REXX2VAR (REXXVAR,L),STRING
    SAY 'Before, REXX variable ',REXXVAR,' is: '
    SAY STRING
* -- Modify it
    MOVE ' --- MODIFIED BY HILMAS --- ',TO,STRING
* -- Return this variable to REXX program
    VAR2REXX (STRING,30),(REXXVAR,L)
 ENDPROG
*
 COPY HILVAR
L DS F
REXXVAR DS CL10
STRING DS CL40
END
The program can be recalled by this REXX:

/* REXX */
REXXVAR = 'REXX VARIABLE '
'TESTREXX'
SAY 'After, REXX variable REXXVAR is:'
SAY REXXVAR
EXIT

Running this REXX program you see in the screen:

Before, REXX variable REXXVAR is:
REXX VARIABLE
After, REXX variable REXXVAR is:
--- MODIFIED BY HILMAS ---

A word about compilation.

We have already stated that Hilmas is only a collection of macros written in assembler that resembles a language: you write Hilmas instructions but really recall macro assembler.
To compile a Hilmas program you assemble it as a normal assembler program: these are the sample Jobs to compile it in MVS environment. For a CICS and/or DL1 program you see an addition of a PreCompilation step

MVS / Batch environment.


//ASMHCL   JOB (DBA,USA1),'ASMHCL',MSGLEVEL=(1,1),MSGCLASS=X,
//         NOTIFY=&SYSUID,CLASS=A
//*
//* --- Assembly of HILMAS/BATCH (or TSO) source in  MVS
//*     USE ASSEMBLER DIRECTIVE 'COPY' INSTEAD OF /INCLUDE IN SOURCE
//*     AND PUT LIBRARY WITH HILMAC AND HILVAR MACROS IN 'SYSLIB'
//*
//*ASMH   EXEC PGM=IEV90,    <--- ASSEMBLER H
//ASMH   EXEC PGM=ASMA90,    <--- HIGH LEVEL ASSEMBLER
//            PARM='NODECK,OBJECT,LIST'
//SYSIN    DD DSNAME=CRPROUA.HIL.SOURCE(xxxxxxxx),  <---- SOURCE HILMAS
//            DISP=SHR
//SYSLIB   DD DSN=CRPROUA.JOB.PROVE,DISP=SHR
//         DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=SYS1.MODGEN,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT2   DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT3   DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSN=CRPROUA.PROGRAM.OBJ,DISP=OLD   <--- to view OBJ
//*SYSLIN  DD DSNAME=&&LOADSET,     <--- to use a temporary for OBJ
//*            DISP=(MOD,PASS),UNIT=SYSDA,
//*            DCB=(BLKSIZE=2800,LRECL=80,RECFM=FB),
//*            SPACE=(TRK,(3,3))
//*
//* ---- LINKEDIT STEP
//*
//LKED   EXEC  PGM=IEWL,PARM='RENT,MAP,LIST,LET,XREF',
//             COND=(5,LT,ASMH)
//SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(1,1))
//*SYSLIN   DD  DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//SYSLIN   DD DSN=CRPROUA.PROGRAM.OBJ,DISP=OLD
//         DD  DDNAME=SYSIN
//SYSLMOD  DD  DSN=CRPROUA.BATCH.LINKLIB,DISP=SHR   <---- OUTPUT LIB.
//SYSLIB   DD  DSN=CRPROUA.BATCH.LINKLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
  NAME xxxxxxxx(R)           /* <-- CHANGE LOAD NAME  */
/*

MVS / CICS environment.


//ASMHCLCX JOB (DBA,USA1),'ASMHCLCX',MSGLEVEL=(1,1),MSGCLASS=X,
//         NOTIFY=&SYSUID,CLASS=A
//*
//* --- CICS/DLI ASSEMBLER PRECOMPILE  - COMMAND LEVEL
//*
//TRN    EXEC PGM=DFHEAP1$,PARM=(SP,CICS)   <--- add DLI parameter if required
//STEPLIB  DD DSN=SYS1.COLL.CICS410.SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DSN=CRPROUA.HILMAS.SOURCE(xxxxxxxx),  <--- SOURCE HILMAS
//            DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSPUNCH DD DSN=&&FILETMP,     <--- precompiler output
//            DISP=(,PASS),UNIT=SYSDA,
//            SPACE=(8000,(40,10))
//*
//* --- Assembly of HILMAS/CICS  source in  MVS
//*     USE ASSEMBLER DIRECTIVE 'COPY' INSTEAD OF /INCLUDE IN SOURCE
//*     AND PUT LIBRARY WITH HILMAC AND HILVAR MACROS IN 'SYSLIB'
//*
//*ASMH   EXEC PGM=IEV90,        <--- ASSEMBLER H
//ASMH   EXEC PGM=ASMA90,        <--- HIGH LEVEL ASSEMBLER
//            PARM='NODECK,OBJECT,LIST'
//SYSIN    DD DSNAME=&&FILETMP,DISP=OLD  <--- SOURCE ASSEMBLER
//SYSLIB   DD DSN=CRPROUA.JOB.PROVE,DISP=SHR
//         DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=SYS1.MODGEN,DISP=SHR
//         DD DSN=SYS1.COLL.CICS410.SDFHMAC,DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT2   DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT3   DD UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DSN=CRPROUA.PROGRAM.OBJ,DISP=OLD    <--- to view OBJ
//*SYSLIN   DD DSNAME=&&LOADSET,      <---  to use a temporary for OBJ
//*            UNIT=SYSDA,DISP=(MOD,PASS),
//*            SPACE=(TRK,(3,3)),DCB=(BLKSIZE=2800,LRECL=80,RECFM=FB)
//*
//* ---- LINKEDIT STEP
//*
//LKED   EXEC  PGM=IEWL,PARM='RENT,MAP,LIST,LET,XREF',
//             COND=(5,LT,ASMH)
//SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(1,1))
//*SYSLIN   DD  DSNAME=&&LOADSET,DISP=(OLD,DELETE)  
//SYSLIN   DD DSN=CRPROUA.PROGRAM.OBJ,DISP=OLD
//         DD DDNAME=SYSIN
//SYSLMOD  DD  DSN=PCATCRBO.CICS.LINK,DISP=SHR   <---- OUTPUT LIBRARY
//SYSLIB   DD  DSN=CRPROUA.BATCH.LINKLIB,DISP=SHR
//         DD  DSN=SYS1.COLL.CICS410.SDFHLOAD,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
  ORDER    DFHEAI
  INCLUDE  SYSLIB(DFHEAI)
  NAME xxxxxxxx(R)           /* <-- MODIFY LOAD NAME       */
/*
//* if program contain DL/1, add   INCLUDE SYSLIB(DFSLI000) 
//*                after INCLUDE SYSLIB(DFHEAI)

A final complete example: The Eight Queens Problem.

This example is downloadable together the executables in Download page, for the three interactive environments TSO, CICS and CMS.


/INCLUDE HILMAS MAC
* QUEENS HIL ---------------------------------------------
* EIGHT QUEENS SOLUTION 
* (ANOTHER RECURSIVE ROUTINE)
*
* SEE : N. WIRTH, Algorithms+Data=Programs
* --------------------------------------------------------
 PROGRAM QUEENS,CMS,LSTACK=10000  Define a Stack for recursivity
    CLEAR
    SAY 'SOLUTION OF THE "N" CHESS-QUEENS.'
    SAY 'Write the size of chessboard (from 4 to 12) :'
    INPUT NUMBER
    EDIT2NUM NUMBER,N
    IF ($DATAERR,<>,' ') THEN
       SAY 'Not numeric value.'
       EXIT
    ENDIF
    IF (N,>,12),OR,(N,<,4) THEN
       SAY 'Number must be from 4 and 12.'
       EXIT
    ENDIF
* --- INITIALIZATION of arrays: FLAG A, B, C
    FOR I,1,N
       MOVARRAY A,(I),FROM,1
    NEXT
    LET BS,N,*,2
    FOR I,2,BS
       MOVARRAY B,(I),FROM,1
    NEXT
    FOR I,1,24
       MOVARRAY C,(I),FROM,1
    NEXT
    MOVE 0,TO,NUMSOLUZ
    SAY
    SAY '----------------------------------------------------------'
    SAY ' SOLUTION        POSITIONS OF THE QUEEN FOR EVERY COLUMN  '
    SAY '----------------------------------------------------------'
* --- Recall SUBROUTINE 'TRY' with INPUT = I = 1
    MOVE 1,TO,I
    GOSUB TRY
    EXIT
*
* ---------------
* PRINT A SOLUTION
*
 SUBDEF PRINTS
    INC NUMSOLUZ
    SAY NUMSOLUZ,': ',VAR=LINE
    FOR K,1,N
    MOVARRAY X,(K),TO,XS
       NUM2EDIT XS,STRINGA
       MOVARRAY SOLUZ,(K),FROM,STRINGA,SLEN=4
    NEXT
    SAY LINE
 ENDSUB
*
* ---------------
* TRY to FIND a SOLUTION
* I = Input, arrays A, B, C, X = Output
 SUBDEF TRY,SAVEVAR=(I,J,IPJ,IMJ)  <-- Save for recursivity
*  Variables AS, BS, CS are not saved because are not used 
* after 'TRY' recall
    FOR J,1,N
       LET IPJ,I,+,J
       LET IMJ,I,-,J,+,11
       MOVARRAY A,(J),TO,AS
    MOVARRAY B,(IPJ),TO,BS
    MOVARRAY C,(IMJ),TO,CS
    IF (AS,=,1),AND,(BS,=,1),AND,(CS,=,1) THEN
       MOVARRAY X,(I),FROM,J
       MOVARRAY A,(J),FROM,0
       MOVARRAY B,(IPJ),FROM,0
       MOVARRAY C,(IMJ),FROM,0
       IF (I,<,N) THEN
          INC I
          GOSUB TRY   <--- Self recall
          DEC I
       ELSE
          GOSUB PRINTS
       ENDIF
       MOVARRAY A,(J),FROM,1
       MOVARRAY B,(IPJ),FROM,1
       MOVARRAY C,(IMJ),FROM,1
    ENDIF
    NEXT
 ENDSUB
*
 ENDPROG
*
/INCLUDE HILMAS VAR
I DS F
J DS F
K DS F
* --- TEMPORARY VARIABLES
NUMSOLUZ DS F
XS DS F
AS DS F
BS DS F
CS DS F
IPJ DS F
IMJ DS F
STRINGA DS CL4
* --- INPUT PARAMETER 
NUMBER DS CL4
N DS F
* --- OUTPUT LINE
LINE DS 0CL80
DS CL10
SOLUZ DS CL70
* --- GLOBAL ARRAYS
X DS 13F ; QUEEN'S POSITION in column i (i from 1 to N)
A DS 13F ; FLAG=1 if no queen is in row  j (from 1 to N)
B DS 32F ; FLAG=1 if no queen is in diagonal k
* DIAGONAL of DIRECTION /; k from 2 to 2*N
C DS 24F ; FLAG=1 if no queen is in diagonal k
* DIAGONAL of DIRECTION \; k from -(N-1) to N-1
* ---
*
END

This is a screen output of the program:

 SOLUTION OF THE "N" CHESS QUEENS PROBLEM.     
 Write the size of chessboard (from 4 to 12) :
6                                              
  
  --------------------------------------------------------
  SOLUTION        POSITION OF THE QUEEN FOR EVERY COLUMN  
  --------------------------------------------------------
   1       :      2   4   6   1   3   5        
   2       :      3   6   2   5   1   4        
   3       :      4   1   5   2   6   3        
   4       :      5   3   1   6   4   2        
 ***