Using Dataport Functions : Calling Conventions : Special Cases of Return Values

Special Cases of Return Values

The following are special cases of return values:

Return values of filename

A number of Dataport functions store extracted information in files, such as a function that retrieves an element’s long description. This function returns the name of the file that contains the requested information. The filename returned is of type stm_filename. This data-type is declared as char * in the library definition file.
Note:
The returned string is defined as static in the functions. Copy the string if it is required for later use.
Return values of enumerated types

There are several functions that return a finite number of discrete values. These values are not necessarily integers, and no particular order is assumed for these values.

For example, the function stm_r_st_type extracts the state type for the state specified in the function call. The possible state types are:

stm_st_diagram

stm_st_and

stm_st_or

stm_st_instance

stm_st_reference

stm_st_basic


    Your program can contain statements such as:
     if (stm_r_st_type (st_id, &status) == stm_st_basic)

For such return values, there are special enumerated data-types declared in the definition file. For example, the previous state types belong to the enumerated type stm_state_type. Refer to for the list of enumerated data-types. Refer to Single-Element Functions, Query Functions, and Utility Functions for the possible values and the corresponding data-types that particular functions return.

Return values of pointers to records

There are several functions that return a pointer to records with the textual and graphical information of an element.
Note:
The records are defined as static in the functions; You should copy the records if they are needed for later use.
Return values when the function call fails

When a function call fails, the function status code reflects the failure by returning the following values:
 

By testing the value returned by the function, you can pinpoint function call failures. To determine what went wrong, use the function status code.