Unidata

5.28 Creating a Enum Type: nc_def_enum

Create an enum type. Provide an ncid, a name, and a base integer type.

After calling this function, fill out the type with repeated calls to nc_insert_enum (see nc_insert_enum). Call nc_insert_enum once for each value you wish to make part of the enumeration.

Usage

     int nc_def_enum(int ncid, nc_type base_typeid, const char *name,
                     nc_type *typeidp);

ncid

The groupid where this compound type will be created.

base_typeid

The base integer type for this enum. Must be one of: NC_BYTE, NC_UBYTE, NC_SHORT, NC_USHORT, NC_INT, NC_UINT, NC_INT64, NC_UINT64.

name

The name of the new enum type.

typeidp

A pointer to an nc_type. The typeid of the new type will be placed there.

Errors

NC_NOERR

No error.

NC_EBADID

Bad group id.

NC_ENAMEINUSE

That name is in use.

NC_EMAXNAME

Name exceeds max length NC_MAX_NAME.

NC_EBADNAME

Name contains illegal characters.

NC_ENOTNC4

Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag NC_NETCDF4. (see nc_open).

NC_ESTRICTNC3

This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see nc_open).

NC_EHDFERR

An error was reported by the HDF5 layer.

NC_EPERM

Attempt to write to a read-only file.

NC_ENOTINDEFINE

Not in define mode.

The following example, from libsrc4/tst_enums.c, shows the creation and use of an enum type, including the use of a fill value.

            int dimid, varid;
            size_t num_members_in;
            int class_in;
            unsigned char value_in;
     
            enum clouds {           /* a C enumeration */
                CLEAR=0,
                CUMULONIMBUS=1,
                STRATUS=2,
                STRATOCUMULUS=3,
                CUMULUS=4,
                ALTOSTRATUS=5,
                NIMBOSTRATUS=6,
                ALTOCUMULUS=7,
                CIRROSTRATUS=8,
                CIRROCUMULUS=9,
                CIRRUS=10,
                MISSING=255};
     
            struct {
                char *name;
                unsigned char value;
            } cloud_types[] = {
                {"Clear", CLEAR},
                {"Cumulonimbus", CUMULONIMBUS},
                {"Stratus", STRATUS},
                {"Stratocumulus", STRATOCUMULUS},
                {"Cumulus", CUMULUS},
                {"Altostratus", ALTOSTRATUS},
                {"Nimbostratus", NIMBOSTRATUS},
                {"Altocumulus", ALTOCUMULUS},
                {"Cirrostratus", CIRROSTRATUS},
                {"Cirrocumulus", CIRROCUMULUS},
                {"Cirrus", CIRRUS},
                {"Missing", MISSING}
            };
            int var_dims[VAR2_RANK];
            unsigned char att_val;
            unsigned char cloud_data[DIM2_LEN] = {
                CLEAR, STRATUS, CLEAR, CUMULONIMBUS, MISSING};
            unsigned char cloud_data_in[DIM2_LEN];
     
            if (nc_create(FILE_NAME, NC_CLOBBER | NC_NETCDF4, &ncid)) ERR;
     
            /* Create an enum type. */
            if (nc_def_enum(ncid, NC_UBYTE, TYPE2_NAME, &typeid)) ERR;
            num_members = (sizeof cloud_types) / (sizeof cloud_types[0]);
            for (i = 0; i < num_members; i++)
                if (nc_insert_enum(ncid, typeid, cloud_types[i].name,
                                   &cloud_types[i].value)) ERR;
     
            /* Declare a station dimension */
            if (nc_def_dim(ncid, DIM2_NAME, DIM2_LEN, &dimid)) ERR;
            /* Declare a variable of the enum type */
            var_dims[0] = dimid;
            if (nc_def_var(ncid, VAR2_NAME, typeid, VAR2_RANK, var_dims, &varid)) ERR;
            /* Create and write a variable attribute of the enum type */
            att_val = MISSING;
            if (nc_put_att(ncid, varid, ATT2_NAME, typeid, ATT2_LEN, &att_val)) ERR;
            if (nc_enddef(ncid)) ERR;
            /* Store some data of the enum type */
            if(nc_put_var(ncid, varid, cloud_data)) ERR;
            /* Write the file. */
            if (nc_close(ncid)) ERR;