Error Handling

Error processing within many higher-level Sage-ST ^TM packages is done by setting Sage.SageError, a global variable containing the results of the last operation from the Sage, MultSage, FX, InfoLib, and Display packages. This value should be checked if there is a potentially catastrophic situation if an error occurs or if you are trapping for a particular error (end of file or invalid password, for example). Although during development you will typically check SageError more often, there is seldom a need in finished code to check for SageError after every operation that sets it. Following are three examples of the use of Sage.SageError--two correct and one incorrect (see figure).

Figure: Sage.SageError Example

In the first example, the salary of each employee is being increased by 10 percent. SageError is checked after the ReadRecord so that when the end-of-file is reached processing will stop. It is also checked after the ReWriteRecord to be sure that all modifications were accepted.

In the second example, a report is being written listing all the employees who live in Phoenix, AZ. The programmer intended to check SageError to determine the end-of-file, but because of the placement is checking the SageError returned by a GetFieldA. The errors most likely to result from a GetFieldA are SageError 5 (requested relation not defined), 15 (requested field of the relation not defined), 16 (string to small to receive contents of field). These bugs, if they existed, would be caught in the first running of the code, not in any released application. The third example shows a correct solution.

Sage.SageError is set by any procedure that affects the following areas:

Database - opening, closing
Relation - opening, closing, GetField, PutField, clears, etc.
Field - GetField, PutField, ClearField, etc.
Form - DisplayForm, DisplayBackground, etc.

In Table 1, fatal errors are designated with an asterisk (*). Fatal errors prevent the system from being able to continue. By default, an error message and bell and possibly a constraint error (user's choice) will be invoked during program execution when one of these errors is encountered. This option may be turned on or off using Display.DisplayFatalErrors. Nonfatal errors may impact the system and may compromise the validity of any subsequent operation, but will not preclude continued operation. Any of the errors shown in the following table may be displayed by using Display.DisplayError. Table 1. Sage-ST ^TM system errors

Fatal	#	Description
*	1	Insufficient memory available for reading form
*	2	The definition file is not available
*	3	The specified file is not a definition file
*	4	Insufficient memory for system initialization
*	5	The requested record is not defined
*	6	The record definition is in error on file
*	7	Insufficient memory for requested record def.
*	8	Insufficient memory for requested record
*	9	The requested form/dialog is not defined
*	10	The form definition is in error on file
*	11	Insufficient memory for requested form def.
*	12	The system has not been initialized
	13	Entered field value is less than range minimum
	14	Entered field value is greater than range max.
*	15	Requested field of record is not defined
	16	Receiving array is too small for field
	17	Concatenated field not allowed for request
*	18	Type conflict between requested field and type
*	19	Requested file is not defined
*	20	Insufficient memory for requested file info.
	21	Incorrect year in date field
	22	Incorrect month in date field
	23	Incorrect day in date field
	24	Incorrect hour in time field
	25	Incorrect minute in time field
	26	Incorrect second in time field
	27	Requested window location will not fit
	28	Entered field value is not in the valid list
	29	Requested data file does not currently exist
	30	Record field does not pass user conditions
	31	Record size in variable field buf. too small
*	32	DFL mod/version number is too old
	33	Read permission not granted
	34	Modify permission not granted
	35	Form field outside of form's window space
	36	Overlap in form's fields
	37	Invalid read password
	38	Invalid modify password
	39	Requested qualification name not found
	40	Insufficient memory for qualification
	41	Incorrect record format
	42	The requested view is not defined
	43	Too many deleted records - Rebuild relation
	44	Incomplete or Incorrect field entry
	45	The requested graph is not defined
	46	Insufficient memory to load requested graph
	47	Unable to open the SGK graphics area
	48	The graphics area was not opened
	49	Unable to open the indicated device
	50	Handle already open, invalid operation requested
	51	Handle already closed, invalid operation requested
	61	Selected keyboard is not defined
	62	Selected color scheme is not defined
	63	Field value does not pass the mask criteria
	64	Key/character is invalid for the field
	65	Block operation requested at position 0
	66	The requested window is not defined
	67	The window definition is in error on file
	68	The requested menu is not defined
	69	The menu definition is in error on file
	70	Could not micro lock
	71	Relation Not Locked
	72	Relation Already Locked
	73	Relation Not Lockable
	74	Record Not Lockable
	75	Can not lock multiple records
	76	Could Not Unlock
	77	Record Not Write Locked
	78	Relation Is Locked
	79	Relation Read Locked
	80	Record Read Locked
	81	No Record Is Locked
	82	Relation Lock Preempted
	83	Could not add relation
	84	Could not add fields
	85	Record Lock Preempted
	86	Lock states conflict
	87	The requested menu item is not available
	88	Operation will cause variable length data loss
	89	Requested form is of the wrong type
	91	Transaction to process is not open
	92	Multple transaction processes against relation
	93	The requested object is not available
	94	The requested dialog or control ID not defined
	95	Invalid function requested for control type
	96	Invalid function requested for control command
*	101	Keyed operation requested on non-keyed field
*	102	Memory allocation failure
	103	Data base already opened
*	104	The system/database was not opened
	105	File system error
	106	The requested relation was not opened
*	107	Version conflict - Rebuild relation
*	108	Version conflict - Rebuild relation
	109	Invalid operation specified for routine called
*	110	Relation not assigned to a file set
*	111	The key list for the relation is corrupted
	112	The requested record was not located
*	113	The key index was not properly positioned
	114	Addition of duplicate primary key attempted
	115	Maximum records for relation exceeded
	116	Rewrite requested for non existent relation
*	117	Block operation on relation with no block file
	118	Block rewrite specified for null block pointer
	119	Block request exceeded block size
*	120	Requested record has been corrupted
*	121	Illegal operation from GetFieldX
*	122	Error encountered reopening relation files
	123	Relation reset requested after local changes
	124	Requested record is not available
	125	Requested record greater than relation total
	126	Log file is not available
	127	Index file key addition was not performed
	128	Data mapping error
	129	GUI library registration failure

Following are errors that appear frequently, along with an explanation of where the problem may lie.

#	Explanation
0	Operation completed without a problem
2	The DFL name in the OpenSystem statement is spelled wrong; The ".DFL" extension on the file name in the OpenSystem statement was left off; The SRC was not compiled
4	Program is getting too large to run. Go to multiple executables or overlays.
5	Relation name is misspelled--remember, relation names are case-sensitive. The SRC has not been recompiled since the relation was added. Subschemas are being used and the relation was not included in the subschema.
7, 11	Increase the buffer size in the OpenSystem statement.
9	Form name is misspelled--remember, form names are case-sensitive; The SRC has not been recompiled since the form was added. Subschemas are being used and the form was not included in the subschema.
15	Field name is misspelled--remember, field names are case-sensitive. The SRC has not been recompiled since the field was added. Subschemas are being used and the form was not included in the subschema.
43	As records are deleted, SAGE keeps track of the "empty" space so that it can be reused as other records are added. However, if more than 32,000 records are deleted, SAGE runs out of space to monitor the deletions and consequently generates SageError 43.
50	An operation has been requested that uses some type of handle. (Files, Reports, etc.) Error 50 indicates that you requested an open operation on a handle that is already open.
51	An operation has been requested that uses some type of handle. (Files, Reports, etc.) Error 51 indicates that you requested a read/write/close operation on a handle that is already closed.
70	Someone else has the requested record locked;
75	The ReWrite or Delete attempted was not successful, so the record is still locked; The system bombed out while a record was locked. Either wait for the lock to expire or delete the RLF file.
85	The attempted ReWrite or Delete will fail because the record was no longer locked.
101	There are some calls which will not function on a field that is not keyed. Some frequently used ones are ReadRecordN and GetKeyPosition.
104	OpenSystem statement is missing. Database is closed.
106	Relation wasn't opened before trying to read, modify, or delete
110	Relation has no file set attached to it via the file ID number and file set editor. A temporary file cannot be opened.
111	Memory is being overwritten somewhere; After reading a particular record in preparation for deleting it, the primary key was changed in the memory record.
112	The ReadRecord or FindRecord did not locate a record on the last search. This is normally an informative error.
114	Tried to add a record with a primary key value equal to an existing record. Once the data on a form has been added, it can only be changed by modifying that record; The commit key was held down too long
115	When the file set for the relation was added, the maximum number of records to allow was either set too low or was forgotten. If forgotten, this defaults to 1.
116	A record cannot be rewritten (modified) until it has been written (added).