CHAPTER 4 GENERAL SYSTEM DEPENDENT ROUTINES
4.1 ALLOCATE AND DEALLOCATE SUBROUTINES
These subroutines allocate and deallocate peripheral devices
under program control. They are designed for use in programs
following the Stromlo data reduction programming conventions. In
particular, they abort via the ERROR subroutine.
Call:
CALL ALLOCATE(DEVICE)
CALL DEALLOCATE(DEVICE)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
DEVICE CHAR C Device to be (de)allocated. If DEVICE is
' ' in the call to DEALLOCATE, all devices
are deallocated.
ERRORS: No errors are generated explicitly, but system generated
errors are intercepted and handled via the ERROR routine.
NOTES:
(1) The call to DEALLOCATE will not deallocate devices which have
been allocated by:
(i) ALLOC commands outside the program;
(ii) calls to SYS$ASSIGN (including plotting to graphics
terminals and Ramtek); or
(iii) explicitly or implicitly opening a file.
(2) Logical names such as 'VERSATEC', 'RAMTEK', and 'TEKTRONIX'
can be used as the device argument.
Page 2
4.2 ERROR HANDLER PROGRAM INTERFACE
INTRODUCTION
This document describes error handling routines for use by
application programs. These routines are:
(i) ERROR - error signalling routine.
(ii) STR$ESTABLISH - establishes a condition handler, with an
optional CTRL/C trap.
(iii) STR$C_HANDL,STR$NOC_HANDL - default condition handlers
supplied when the user does not specify a handler of his
own.
Page 3
4.2.1 ERROR
This subroutine prints an error message on the output
device, then takes action to alter the flow of program control
depending on the severity of the error condition.
Call:
CALL ERROR(ICOND,MESS)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
ICOND C I4 is the error/condition code.
ICOND=0 , warning.
ICOND=1 , error message only.
ICOND=2 , possible error. Handled like -1
or -3 depending on user response.
ICOND=-3 , serious error - a condition is
signalled and the condition handler unwinds
the program stack to resume execution at
some recovery point.
ICOND=-4 , fatal error - a condition is
signalled and the condition handler calls
LIB$STOP (program aborts with a traceback).
MESS CHAR C is the message to be printed.
Page 4
4.2.2 STR$ESTABLISH
This subroutime establishes a condition handler with an
optional CTRL/C trap.
Call:
CALL STR$ESTABLISH(HANDLER,LCTRLC)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
HANDLER C I4 is the address of condition handling
routine. if HANDLER=0 default Stromlo
handlers are established.
LCTRLC C LOG 4 is the logical value - .TRUE. if a CTRL/C
trap is to be enabled, .FALSE. if not.
A condition handler is established for the caller of
STR$ESTABLISH.
If HANDLER is equal to 0 on calling the routine, one of the
default handlers is established. Otherwise the routine specified
by the user is established.
If LCTRLC is .TRUE. on call, a CTRL/C trap is enabled.
Thereafter, typing a CTRL/C at the terminal will not force an
exit from the program. Instead, a condition is signalled which
should be caught and handled by the condition handler. Note that
if a user specifies his own handler and also requests that the
CTRL/C trap be enabled, the user should then ensure that his
handler will take the appropriate action when a CTRL/C is
signalled.
Page 5
4.2.3 STR$C_HANDL,STR$NOC_HANDL
These are the MIIPS default condition handlers. When
STR$ESTABLISH is called with HANDLER equal to 0, one of these
routines is estaCblished.
The following conditions are recognized by both routines:
APP$ERROR - a serious but non-fatal error has been signalled
from an application program. An error message is printed and
the stack is unwound to the caller of the establisher of the
handler.
APP$_FATAL - a fatal error has been signalled from an
application program. An error message is printed, and the
error is resignalled to be handled by the system condition
handlers.
In addition STR$C_HANDL recognizes:
SS$_CONTROLC - a CTRL/C has been typed at the terminal. The
trap set up by STR$ESTABLISH has signalled this condition.
The handler types a message and the stack is unwound to the
caller of the establisher of the handler.
STRUCTURE OF PROGRAMS USING CONDITION HANDLERS.
Once control has been passed to a condition handler (a
system error, a call to ERROR with ICOND equal to -3 or -4, or a
CTRL/C has been typed) the flow of program control may be altered
in several ways:
(i) Stop execution.
(ii) Unwind the program stack and resume execution at some
recovery point.
(iii) Detect the condition in the handler, take some action
such as printing a warning message, and resume execution at
the point where the error occurred.
If a user chooses to supply his own handler, any of these
alternatives may be chosen. The action taken by the MIIPS
default condition handlers and the program structure needed to
use these handlers are described below.
Page 6
PROGRAM STRUCTURE USING DEFAULT HANDLERS
In the first implementation of the condition handlers, a
non-fatal condition will cause control to return to the statement
following the call to the routine which established the condition
handler. For example if subroutine FRED calls STR$ESTABLISH and
an error condition occurs, the error will effectively simulate a
return from FRED.
The general program structure is:
PROGRAM MAIN
*
*
*
Initialization code
*
*
100 CALL COMPUTE
GO TO 100 _#_#_#_#
END
SUBROUTINE COMPUTE
*
*
CALL STR$ESTABLISH(HANDLER,LCTRLC)
*
*
Command handling
Calls to modules etc. etc.
*
*
RETURN
END
If a non-fatal conditon occurs control returns to ####.