Z305 IBM VM/CMS System Interface

OBSOLETE

Please note that this routine has been obsoleted in CNL 219. Users are advised not to use it any longer and to replace it in older programs. No maintenance for it will take place and it will eventually disappear.
Suggested replacement: None

VMPACK is a package of Fortran--callable subprograms providing an interface to the VM/CMS operating system.

Structure:

SUBROUTINE subprograms
User Entry Names: VMBEEP, VMCMS, VMREXX, VMRTRM, VMSATN, VMTATN
Files Referenced: Virtual console

Usage:

Subroutine VMBEEP:

    CALL VMBEEP

    CALL VMCMS(COMAND,IRC)

COMAND

( CHARACTER) A command.

IRC

( INTEGER) Contains, on exit, the return code from the command.

Examples:

    CALL VMCMS('FILEDEF 27 TERMINAL',IRC)
    MSG='EXEC TELL JIM THE FILEDEF HAS BEEN ISSUED'
    CALL VMCMS(MSG,IRC)

Restrictions:

It is not permitted to issue a CMS command which runs in the user area, nor a command which invokes another program, as this will overwrite the program which is executing. The commonly used commands which run in the user area are:

ASSEMBLE,	COPYFILE,	EXECUPDT,	FORMAT,	LISTDS,	LKED,	LOADLIB, MACLIB,	MACLIST,
MODMAP,	MOVEFILE,	OSRUN,	SORT,	TAPEMAC,	TAPPDS,	TXTLIB,	UPDATE.

Subroutine VMREXX:
This subroutine can be called from a program which has been invoked from a REXX exec to set, inspect or drop any of the exec's variables.

    CALL VMREXX(CODE,NAME,VALUE,IRC)

CODE

( CHARACTER*1) Indicates the function to be performed:

A

Move REXX stem variables to Fortran array. See Examples.

B

Move Fortran array to REX stem variables. See Examples.

D

Drop the variable. If the name given is a stem, all variables with that stem are dropped.

F

Fetch the value of the variable.

S

Set the value of the variable.

N

Fetch the next variable. This function code be used to search through all the variables of the exec file.

P

Fetch 'private' information. When this function code is used the variable name refers to certain fixed information:

ARG

Fetch the primary argument list.

SOURCE

Fetch the source string as provided by the REXX PARSE SOURCE instruction.

VERSION

Fetch the version string as provided by the REXX PARSE VERSION instruction.

NAME

( CHARACTER) Name of the REXX variable as a constant or variable (in UPPER case).

VALUE

( CHARACTER) Value of the REXX variable as a constant or variable.

IRC

( INTEGER) Return code. Contains, on exit, one of the following values to indicate the result of the operation:

0

Execution was successful.

1

The variable did not exist.

2

Last variable transferred for function code 'N'.

4

Truncation occurred during fetch.

8

Invalid variable name.

16

Invalid integer in stem.0 for function codes 'A' and 'B'.

128

Invalid function code.

Examples:

    CALL VMREXX('P','ARG',CHARS,IRC)

Fetching and Setting Stem variables: Function codes 'A' and 'B' allow transfer of data between Fortran arrays and REXX stem variables. The REXX variable stem.0 must contain the number of elements to be transferred. Then 'A' moves data from REXX to Fortran, 'B' from Fortran to REXX:

    /**/
    line.0 = 5
    line.1 = 'Hello'
    line.2 = 33
    line.3 = 'alpha'
    line.4 = 'Beta'
    line.5 = 8567
    'LOAD TEST(START'
    Do l = 1 To 5
    Say mine.l
    End
 
    PROGRAM TEST
    CHARACTER*5 GET(MAX),SET(MAX)
    DATA SET/'DUMMY','LINES',' TO  ','GIVE ','REXX '/
    CALL VMREXX('A','LINE.',GET,IRC)
    WRITE (6,'(1X,A10)') GET
    CALL VMREXX('S','MINE.0','5',IRC)
    CALL VMREXX('B','MINE.',SET,IRC)
    END

Restrictions:

Note that the REXX variables within an Exec which calls a second Exec are not visible within the second Exec. This means that, for example, VMREXX has no knowledge of the variables within an Exec which invokes program execution by using the GO option of the VFORT exec.

The maximum number of elements that can be transferred with codes 'A' and 'B' is 999,999,999.
Subroutine VMRTRM:
This subroutine will read a line from the console stack or, if the stack is empty, directly from the console (i.e. the user must type in a line):

    CALL VMRTRM(LINE,LENGTH)

LINE

( CHARACTER) Contains, on exit, the line read from the console.

LENGTH

( INTEGER) Number of characters placed in LINE.

Subroutines VMSATN and VMTATN:
These subroutines can be used by interactive programs to process attention interrupts from the virtual console. An attention interrupt occurs when the user enters a string of characters on the command line and presses the enter (or return) key at a time when the program has not issued a read to the console, i.e. the user wishes to bring something to the attention of the program even though the program has not requested any input. This mechanism may be used, for example, to temporarily halt a long-running program in order to query its status.

VMSATN is used to establish the attention interrupt mechanism and must be called before any attention interrupts can be detected:

    CALL VMSATN(IRC)

IRC

( INTEGER) Contains, on exit, the value zero if the attention mechanism has been established, and a non-zero value otherwise.

    CALL VMTATN(IRC)

IRC

( INTEGER) Contains, on exit, a non-zero value if an interrupt has occured, and the value zero otherwise.

Examples:

The following example shows a program which establishes the attention mechanism and then performs an iterative process.

VMTATN is called at the beginning of each iteration to determine whether an attention interrupt has occurred:

*...  ESTABLISH THE ATTENTION MECHANISM
      CALL VMSATN(IRC)
      IF(IRC .NE. 0) THEN
        process the error
      ENDIF
*...  PERFORM ITERATIVE PROCESSING
    1 CALL VMTATN(IRC)
      IF(IRC .NE. 0) THEN
        READ '(A)',LINE
        process the attention interrupt
      ELSE
        perform normal processing
      ENDIF
      GOTO 1
      END

Restrictions:

CMS support for immediate commands (e.g. HX) requires that CMS handles attention interrupts from the virtual console. Immediate commands will therefore not be recognized by CMS when VMSATN and VMTATN are used to handle attention interrupts. The PA1 key may, however, be used to interrupt execution of the virtual machine and put the virtual console into 'CP READ' status.
$•$

Z306