Documentor Functions : Calling Conventions : Status Codes

Status Codes

Database extraction functions return only one argument—the function status code. This code reports whether the function call was successfully completed. When the function call fails, the status code indicates the problem. You can use the status code to pinpoint run-time errors in your template. For example, assume the following call appears in your template:

state_id := stm_r_st (’%’, status);

The function requires a state name for the first (input) argument. In this case, the function returns a status code of 3, stm_illegal_name, because % is not a valid element name.

The status code is an integer value. Therefore, the status argument must be a variable declared as INTEGER. The Documentor provides predefined constants for the function status codes. This enables you to use the status name attached to each status code in your template.

For example, assume that you want to print out the synonym of the state S1. If there is no synonym defined in the state’s form, print “missing synonym”. Your template should contain the following code:

VARIABLE
INTEGER status;
.
.
.
state_id := stm_r_st (’S1’, status);
synonym := stm_r_st_synonym (state_id, status);
IF status = stm_missing_synonym THEN
WRITE ( ’\n synonym: *missing synonym* ’);
ELSE
WRITE ( ’\n synonym: ’, synonym);
END IF;

Status codes have severity levels that you can check to ensure that your function call was successful. These severity levels, and a complete list of status codes are documented in Function Status Codes.