'C/C++' Interface Principles

The 'C/C++' subroutine names are the same as those used for the FORTRAN subroutines (but lower case). For example, d3init for D3INIT.

The 'C/C++' routine arguments are analogous to the FORTRAN arguments. One of the differences between FORTRAN and 'C/C++' is that 'C/C++' strings do not intrinsically carry their declared length when passed as arguments. The interface has been designed so that the programmer does not need to pass additional string lengths as arguments. However, the programmer is assumed to know the maximum length of each return string argument and to have declared it as such.

The programmer should refer to the d3libc.h and pdms.h header files printed above (‘C/C++’ Library). These define the format of each DARs routine call, including definitions of all returned string lengths (for example, PDMS_TEXT_LEN). The example program illustrates how the routines should be called.

All arguments are passed by address. This means that all integer and logical input arguments must be passed through a variable address (for example, &ival). This is to ease the use of these functions: the programmer doesn't have to remember which arguments are passed by address and which are passed by value.

One of the effects of 'C/C++' string behavior is that the DARs error code 5 (character string output argument too short) cannot be returned if a DARs routine is called from a 'C/C++' program. If the supplied string is too short, the returned string will overrun the declared string and may corrupt other variables (or it may have no noticeable effect).

As an example, the cd3tex argument of d3rprj is defined as PDMS_TEXT. The interface defines PDMS_TEXT_LEN as 120. The 'C/C++' program should therefore declare this argument as PDMS_TEXT cd3tex. If instead it is defined, say, as char cd3tex[2], corruption may occur. No problem would occur if the string is declared to be longer than necessary.

In the case of d3ucti and d3uctr, the two return arguments cd3bef and cd3aft must be declared at least as long as the significant length of the input argument cd3str.