1 #if !defined( C2F77_INCLUDED ) /* Include this file only once */ 2 #define C2F77_INCLUDED 3 /* 4 *+ 5 * Name: 6 * c2f77.h 7 8 * Purpose: 9 * Define the interface to the c2f77 module. 10 11 * Description: 12 * This file defines language-specific functions which support the 13 * FORTRAN 77 interface to the AST library. 14 * 15 * Note that this module is not a class implementation, although it 16 * resembles one. 17 18 * Functions Defined: 19 * Public: 20 * None. 21 * 22 * Protected: 23 * astStringExport 24 * Export a C string to a FORTRAN string. 25 26 * Macros Defined: 27 * Public: 28 * None. 29 * 30 * Protected: 31 * astWatchSTATUS 32 * Execute C code while watching a FORTRAN STATUS variable. 33 34 * Copyright: 35 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 36 * Research Councils 37 38 * Licence: 39 * This program is free software: you can redistribute it and/or 40 * modify it under the terms of the GNU Lesser General Public 41 * License as published by the Free Software Foundation, either 42 * version 3 of the License, or (at your option) any later 43 * version. 44 * 45 * This program is distributed in the hope that it will be useful, 46 * but WITHOUT ANY WARRANTY; without even the implied warranty of 47 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 48 * GNU Lesser General Public License for more details. 49 * 50 * You should have received a copy of the GNU Lesser General 51 * License along with this program. If not, see 52 * <http://www.gnu.org/licenses/>. 53 54 * Authors: 55 * RFWS: R.F. Warren-Smith (Starlink) 56 * DSB: David S. Berry (Starlink) 57 58 * History: 59 * 15-NOV-1996 (RFWS): 60 * Original version. 61 * 16-JUL-1997 (RFWS): 62 * Added astWatchSTATUS. 63 * 13-JUN-2001 (DSB): 64 * Make astStringExport available to F77 interface modules as well 65 * as AST classes. 66 *- 67 */ 68 69 /* Macros. */ 70 /* ======= */ 71 /* 72 *+ 73 * Name: 74 * astWatchSTATUS 75 76 * Type: 77 * Protected macro. 78 79 * Purpose: 80 * Execute C code while watching a FORTRAN STATUS variable. 81 82 * Synopsis: 83 * #include "c2f77.h" 84 * astWatchSTATUS(code) 85 86 * Description: 87 * This macro expands to code which executes the C code supplied 88 * via the "code" argument in a new C scope (delimited by 89 * {...}). The code supplied executes while the AST error status is 90 * equated to a variable called STATUS, which is an error status 91 * argument passed from a FORTRAN routine using the macros defined 92 * in the "f77.h" include file. 93 * 94 * The effect of this is roughly as if the astWatch function had 95 * been used to locally declare the FORTRAN STATUS argument as a 96 * new AST error status variable, except that this macro also works 97 * if STATUS is not an int. 98 99 * Parameters: 100 * code 101 * The C code to be executed. 102 103 * Examples: 104 * F77_SUBROUTINE(ast_doit)( INTEGER(STATUS) ) { 105 * astWatchSTATUS( 106 * astDoit(); 107 * ) 108 * } 109 * Causes the astDoit function to be invoked as if the AST error 110 * status were equated to the STATUS argument passed from 111 * FORTRAN. Typically, if STATUS is set to an error value, 112 * astDoit would detect this by means of the astOK macro and 113 * would not then execute. If an error occurs in astDoit, 114 * causing the AST error status to be set, then that value is 115 * transferred to STATUS after the C code has executed (i.e. at 116 * the end of the astWatchSTATUS macro). 117 118 * Notes: 119 * - The FORTRAN argument must be called STATUS and must appear in 120 * the C function's parameter list as an argument of the INTEGER() 121 * macro defined in the "f77.h" include file. 122 * - The C code supplied executes in a new scope, in which 123 * automatic variables may be declared. However, such variables 124 * will not exist after the macro's expansion has been executed. 125 * - The AST error status variable and its value remain unchanged 126 * after the expansion of this macro has executed. 127 *- 128 */ 129 130 /* Define the macro. */ 131 #define astWatchSTATUS(code) \ 132 \ 133 /* Begin a new C scope. */ \ 134 { \ 135 \ 136 /* Ensure that a pointer to the STATUS argument exists. */ \ 137 GENPTR_INTEGER(STATUS) \ 138 \ 139 /* Store the STATUS value in a local int. */ \ 140 int ast_local_status = *STATUS; \ 141 int *status = &ast_local_status; \ 142 \ 143 /* Make this int the AST error status variable, saving the address of \ 144 the previous variable. */ \ 145 int *ast_previous_status = astWatch( &ast_local_status ); \ 146 \ 147 /* Execute the code supplied using the new error status variable. */ \ 148 code \ 149 \ 150 /* Restore the original error status variable. */ \ 151 (void) astWatch( ast_previous_status ); \ 152 \ 153 /* Return the final error status to STATUS. */ \ 154 *STATUS = ast_local_status; \ 155 } 156 157 /* Function prototypes. */ 158 /* ==================== */ 159 void astStringExport_( const char *, char *, int ); 160 161 /* Function interfaces. */ 162 /* ==================== */ 163 /* These wrap up the functions defined by this module to make them 164 easier to use. */ 165 #define astStringExport astStringExport_ 166 #endif 167