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 ####.