NAME

interface routines for IRIS Explorer cxUnknown data structure

C SPECIFICATION

#ifndef __cxUnknown_API_H_
#define __cxUnknown_API_H_

#ifdef __cplusplus
 extern "C" {
#endif

#include <stdio.h>
#if defined(__sun) || defined(WIN32)
 cxUnknown* cxUnknownAlloc( signed long Count );
 cxUnknown* cxUnknownCopy( cxUnknown *src );
 signed long cxUnknownCountGet( cxUnknown *src, cxErrorCode *ec );
 void cxUnknownCountSet( cxUnknown *src, signed long val, cxErrorCode *ec );
 unsigned char* cxUnknownDataGet( cxUnknown *src, cxErrorCode *ec );
 long cxUnknownDataLen( cxUnknown *src, cxErrorCode *ec );
 void cxUnknownDataRem( cxUnknown *src, unsigned char* *val, cxErrorCode *ec );
 void cxUnknownDataSet( cxUnknown *src, unsigned char* val, cxErrorCode *ec );
 cxUnknown* cxUnknownDup( cxUnknown *src );
 cxUnknown* cxUnknownRead( FILE *fd );
 void cxUnknownWrite( FILE *fd, int mode, cxUnknown *src );

FORTRAN SPECIFICATION

#ifndef __cxUnknown_API_H_
#define __cxUnknown_API_H_

#ifdef __cplusplus
 extern "C" {
#endif

#include <stdio.h>
#if defined(__sun) || defined(WIN32)
 integer function cxUnknownAlloc( Count )
 integer function cxUnknownCopy( src )
 integer function cxUnknownCountGet( src, ec )
 subroutine cxUnknownCountSet( src, val, ec )
 integer function cxUnknownDataGet( src, ec )
 integer function cxUnknownDataLen( src, ec )
 subroutine cxUnknownDataRem( src, val, ec )
 subroutine cxUnknownDataSet( src, val, ec )
 integer function cxUnknownDup( src )
 integer function cxUnknownRead( fd )
 subroutine cxUnknownWrite( fd, mode, src )

PARAMETERS

src

In C, a pointer to the data structure to be accessed in whole or part. In Fortran, an opaque integer handle to the data structure to be accessed in whole or part.

val

The val argument (if present) is the new value to be assigned to the structure member. See the section on Set routines below for more information on the val argument.

*Ind

Arguments following src and preceding ec with variable name ending in Ind (if any) are integer array bounds. If such an argument exists, the requested member is part of an array of structures, for which the *Ind variable provides the array index.

ec

In C, a pointer to a returned error code (if present). In Fortran, an integer output error code (if present). The ec output is an enumerated integer with cx_err_none (zero) indicating success. Any other value indicates an improper src input or an out-of-bounds Ind argument.

FUNCTION RETURN VALUE

DESCRIPTION

GENERATING THE INTERFACE ROUTINES

For example, assuming that the cxUnknown.t file exists, you would take the following steps:

        echo cxUnknown > TYPES
        cxmkmf
        make

Note that this process will create several files in the local directory, so it is often helpful to use a separate directory for types, just as modules are developed in their own directories.

GET ROUTINES

C DESCRIPTION

 signed long cxUnknownCountGet( cxUnknown *src, cxErrorCode *ec );
 unsigned char* cxUnknownDataGet( cxUnknown *src, cxErrorCode *ec );

FORTRAN DESCRIPTION

 integer function cxUnknownCountGet( src, ec )
 integer function cxUnknownDataGet( src, ec )

<ans>

The returned argument represents the structure member of interest. There are two cases, with different interpretations of the returned argument. The first case, in which the return type is not a generic pointer (in C a void* pointer, in Fortran an integer), returns the member of interest, whether scalar or pointer. In the second case, in which the return type is a generic pointer (in C a void* pointer), the returned value is a pointer to storage. If the requested member is a scalar, the returned value is a reference to that scalar. If the requested member is a pointer, the returned value is actually that pointer. This case happens when several members in different cases of a switch structure are given the same label in the IRIS Explorer Typing Language file cxUnknown.t. It may be difficult to distinguish the two cases in Fortran based on the function return type (if that type is integer). In this case the user should consult the definition of cxUnknown to determine whether several members have the same label string. In Fortran, the Get routines that return a character string or array of character strings are implemented as subroutines having that string as their last argument. They are not written as character functions. Such a subroutine returning an array of character strings assumes the caller has passed in enough storage to hold all the strings; the number of elements necessary to form the array can be found by calling the related Len routine.

SET ROUTINES

C DESCRIPTION

 void cxUnknownCountSet( cxUnknown *src, signed long val, cxErrorCode *ec );
 void cxUnknownDataSet( cxUnknown *src, unsigned char* val, cxErrorCode *ec );

FORTRAN DESCRIPTION

 subroutine cxUnknownCountSet( src, val, ec )
 subroutine cxUnknownDataSet( src, val, ec )

val

The val argument (if present) is the new value to be assigned to the structure member. There are two cases, with different interpretations of val. The first case, in which the type of val is not a generic pointer (in C a void* pointer, in Fortran an integer), assigns val, whether scalar or pointer. In the second case, in which the type of val is a generic pointer (in C a void* pointer), val is a pointer to storage. If the requested member is a scalar, val is a reference to that scalar. If the requested member is a pointer, val is interpreted as actually that pointer. This case happens when several members in different cases of a switch structure are given the same label in the IRIS Explorer Typing Language file cxUnknown.t. It may be difficult to distinguish the two cases in Fortran based on the argument type (if that type is integer). In this case the user should consult the definition of cxUnknown to determine whether several members have the same label string.

TYPE ROUTINES

C DESCRIPTION

FORTRAN DESCRIPTION

LENGTH ROUTINES

C DESCRIPTION

 long cxUnknownDataLen( cxUnknown *src, cxErrorCode *ec );

FORTRAN DESCRIPTION

 integer function cxUnknownDataLen( src, ec )

<ans>

The type of the requested switch discriminator variable. In C, the return value is a cxPrimType enumerated integer. In Fortran, the return value is an integer. See the file /usr/explorer/include/cx/Typedefs.h for more information.

DIMENSION PRODUCT ROUTINES

C DESCRIPTION

FORTRAN DESCRIPTION

<ans>

The returned integer value is the length of an array dimensioned by the specified member, computed by taking the product of the member's values.

DUPLICATION ROUTINES

C DESCRIPTION

 cxUnknown* cxUnknownDup( cxUnknown *src );

FORTRAN DESCRIPTION

 integer function cxUnknownDup( src )

<ans>

The return value references the duplicated structure, or is zero if an error was encountered. In C, the return value is a pointer to the structure. In Fortran, the return value is an opaque integer handle to the duplicated data structure.

COPYING ROUTINES

C DESCRIPTION

 cxUnknown* cxUnknownCopy( cxUnknown *src );

FORTRAN DESCRIPTION

 integer function cxUnknownCopy( src )

<ans>

The return value references the copied structure, or is zero if an error was encountered. In C, the return value is a pointer to the structure. In Fortran, the return value is an opaque integer handle to the duplicated data structure.

STORAGE ALLOCATION ROUTINES

C DESCRIPTION

 cxUnknown* cxUnknownAlloc( signed long Count );

FORTRAN DESCRIPTION

 integer function cxUnknownAlloc( Count )

src

If src is an argument, then the allocation creates an array needed by the src structure. It is assumed that the src structure has been constructed to contain all the information needed to dimension the array. In C, src is a pointer to the structure. In Fortran, src is an opaque integer handle to the data structure.

<other>

The arguments other than src, if any, are dimensioning scalars, dimensioning arrays, and discriminating switches of some enumerated type. In C, the respective types of these arguments are long, long*, and enumerated types. In Fortran, their respective types are integer, integer array, and enumerated integer. These arguments are included in the argument list if they are needed to compute the size of an array or which case of a switch to take in allocating a reference-counted structure. It is possible that a structure allocation routine will not fully allocate the structure. This happens when an array or switch contains several items to also be allocated; there is no acceptable way to put all of the dimensioning information into the function call, so the array is not allocated (a null pointer is used instead) and the user is expected to use array allocation and member setting routines to complete the structure allocation. The return value references the allocated array or structure, or is zero if an error was encountered. In C, the return value is a pointer to the allocated structure. In Fortran, the return value is an opaque integer handle to the allocated data structure.

STORAGE REMOVAL ROUTINES

C DESCRIPTION

 void cxUnknownDataRem( cxUnknown *src, unsigned char* *val, cxErrorCode *ec );

src

src is the reference-counted structure containing the member to be removed. In C, src is a pointer to the structure.

val

val is the address of the member to be removed. An array is deleted, while a shared structure has its reference count decremented. In C, val is a pointer to the member.

TYPE READING ROUTINES

C DESCRIPTION

 cxUnknown* cxUnknownRead( FILE *fd );

FORTRAN DESCRIPTION

 integer function cxUnknownRead( fd )

fd

The fd argument is the file descriptor from which to read data. In C, fd is of type FILE*. In Fortran, its type is integer.

TYPE WRITING ROUTINES

C DESCRIPTION

 void cxUnknownWrite( FILE *fd, int mode, cxUnknown *src );

FORTRAN DESCRIPTION

 subroutine cxUnknownWrite( fd, mode, src )

fd

The fd argument is the file descriptor to which to write data. In C, fd is of type FILE*. In Fortran, its type is integer.

mode

The integer mode argument determines whether the output file is transcribed in ASCII (mode == 0) or binary (mode != 0) IRIS Explorer format.

DEFINITION OF cxUnknown

shared root typedef struct {
    long            count	    "Count";
    char            data[count]	    "Data";
} cxUnknown;

SEE ALSO