2.1 General VICAR conventions

• Portability. All VICAR software runs on all platforms that MIPL supports.
• Separate FORTRAN and C Interfaces . All subroutines have separate FORTRAN and C calling sequences, with different names. Subroutines call only the appropriate language interface.
• Status return. The status code is the function return. If automatic error checking is on (via x/zveaction or one of the “*_ACT” key words), then status return may be ignored.
• Pass by value. All input values to the RTL are passed by value as in standard C, rather than by reference. Output variables or arrays are passed by reference. Check to remove “ & “'s before input arguments.
• Data Formats and I/O .
  • Applications read files written in any host representation. See 1.3.1 VICAR File Representations.
  • Applications write files in the native host representations of the machine on which they are currently running. See 1.3.1 VICAR File Representations.
  • Programs reading binary labels read any host format, and convert to native format before using. See 1.3 Data Types and Host Representations and 1.7 Using Binary Labels.

• Data Format Translation. Do not write your own pixel data type or host representation conversion routines. The routine x/zvtrans is the standard way to translate data between different host representations and pixel data types in VICAR. See VICAR File Representations (page 9).
• Do not use EQUIVALENCE for data type conversion in FORTRAN. Use the INT2BYTE or BYTE2INT routines. See 2.7.2 No EQUIVALENCE for Type Conversion (page 37).
• Pixel Sizes. Do not assume the size in bytes of a pixel or other data; it may be different on other machines. Use one of the x/zvpixsize routines, or size of in C, to determine the size of a data element. See 1.5 Pixel Type Declarations.
• Name Registries. Every property name or BLTYPE name used is entered into the appropriate name registry. See 4.1.2.1 Using Property Labels and 1.7.2 Programming and Binary Labels.
• Operating System Calls. All OS-specific code is eliminated or isolated, and should be written in C if possible. See 2.7.6 VMS-Specific Code.
• Conditional Compilation. Conditional compilation statements to handle machine dependencies use names of specific features that are defined in standard include files based on the machine type. Feature dependencies are defined only in x/zvmaininc.h or vmachdep.h. Symbols VMS_OS and UNIX_OS distinguish between VMS and UNIX operating systems.
• No Terminal I/O. VICAR applications may not write directly to the terminal (e. g. stdout). Use x/zvmessage instead.
• ANSI C. Function prototype include files use #ifndef wrappers, _NO_PROTO, and extern “C” declarations. FORTRAN bridge routines do not use prototypes or the prototype form of declaration.
• FORTRAN 77 standard. All FORTRAN code conforms to the ANSI FORTRAN -77 standard, with the exception of the allowed extensions listed in the reference. See 2.7.5 VMS FORTRAN Extensions.
• FORTRAN Strings. All FORTRAN-callable subroutines written in C use the RTL string conversion routines ( sfor2c et al ) to handle CHARACTER*n arguments. See 2.6.4 Passing Strings.
• vimake. VICAR applications use imakefiles compatible with vimake to create their build files.
• vpack. VICAR applications are packed into a COM file using the vpack command.
• Optional Arguments

There are two types of RTL routines: those that take a constant number of arguments, and those that take optional arguments of the form “key word”, ”value”, “key word”,” value”, etc.
All routines that accept keyword-value pairs, whether or not the pairs are used in any particular call, must have an argument list terminator. The terminator is a language-dependent argument at the end of the argument list, where the next key word would be if it existed.
In FORTRAN, the terminator is a single blank in quotes at the end of the argument list:

call xvopen(unit, status, 'op', 'write','open_act','sa',' ') 
call xvread(unit, buffer, status, 'line', 1, ' ') 
call xvclose(unit, status, '')

In C, the terminator is a 0 or NULL argument ( not a blank):

status = zvopen(unit, “op”, “write”, “open_act”, “sa”, 0); 
status = zvread(unit, buffer, “line”, 1, 0); 
status = zvclose(unit, 0);

Certain RTL routines used to take pure optional arguments (not keyword/value), but that practice is not portable and is now obsolete.