All code can generate errors. In recognition of this, the PCL functions listed in this manual make use of a straight forward mechanism that passes information about the status of a function back from the function that has been called to the calling function. This is done through the <return value> that most functions supply.

The general convention followed is that if something happens that prevents a function from successfully completing the job that it was designed to do it will return a positive non-zero integer number. If it completes its job successfully, it will return a value of 0.

This returned integer value can then be put to use. It can be used in an IF statement to control the flow
of the path of execution for your code, it can be used to trigger the a return out of the calling function, or it can be used to break out of a FOR or WHILE loop. The returned value can be used in whatever manner is appropriate for the design of the code being written. A good practice to follow is to design your code so that it marks any problem that prevents your function from completing its job by returning an error code that is returned by that status condition only. For example: the same returned status value should
not be used to indicate that a file was not found because of an invalid path and that a file was not found because of an invalid path name. Using a unique status code for the return status of a function provides information about what caused the error and where the error occurred in a manner that can greatly simplify debugging your code. A list of all of the messages in the status message database is
provided at the end of this manual as an aid in selecting return codes that are appropriate for specific status conditions.

Most of the <return values> that are returned by the functions in this manual have messages associated with them. Status messages are all kept in a status message database that can be accessed through the use of several functions: msg_get_string(), user_message(), msg_to_form(), and msg_to_text(). The msg_get_string() is used to return a message from the message database to a string. The user_message() function takes a message code and displays the corresponding message in the history window. The msg_to_form() function can be used to get a message from the message database and display it a popup form; this is the mechanism that is used to create the popup forms that are listed in the “Remarks” section of the function descriptions. The msg_to_text() function can be used to write messages from the message database to a file.

All of these functions are provided to create a rich set of tools that can be used by the code designer to be flexible in presenting error and status information as needed.