SPI Programming Manual (G06.24+, H06.03+, J06.03+)

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-53
Pass-Through Error Lists
Fill in only the Z-TOKENCODE field to describe a missing required token. If more
than one field is involved in the error (as in the case of a field that conflicts with the
value of another field), repeat the ZSPI-TKN-PARM-ERR token for each field
involved. In addition, if the subsystem ID qualifying the token is not the default
subsystem ID, include the ZSPI-TKN-SSID-ERR token to identify that SSID.
These guidelines apply to error lists at every level. That is, when C creates an error list
to pass back to B, the point of view shifts—because C is creating an error list, it takes
the role of B in the above guidelines and the guidelines all apply to C. The principle
applies similarly for any depth of subordinate servers.
Errors from SPI procedures (assuming the program does not recover from them) are
reported according to guideline 8. For guidelines for constructing error lists to report
such errors, see the
Guardian Procedure Errors and Messages Manual .
When relaying pass-through error information from multiple subsystems, you can use
the SSMOVE procedure to move an entire error list from one SPI buffer to another.
Guideline 8 refers to token definitions and directions for their use that are provided by
procedures and other services that do not have SPI interfaces. If you wish to provide
such tokens and directions, you must decide what items of information are useful to
report in a description of an error from your service and define how each is to be
included in the error list. The names of the tokens and other definitions must follow the
same guidelines as the definitions for a complete SPI interface, but only those few
declarations needed to build the error lists need be supplied. The declarations are
packaged the same way as for a complete SPI interface.
When defining guidelines for handling error lists to report errors from servers with non-
SPI interfaces, consider:
•
Certainly the error number is of interest; your subsystem should place it in the
ZSPI-TKN-ERROR token unless there is good reason to put some other value
there.
•
For procedures, your server should examine each argument to the procedure. You
should define tokens for those arguments that would be useful in an error message
or for other analysis of the error. If an argument is a structure, it might be
appropriate to define tokens for just some of the fields of the structure, or it might
be appropriate to include the whole structure in a token. Decide that on a case-by-
case basis.
•
In some cases, there might be important information that is not among the
parameters. Define tokens for such information and explain how to obtain the
information to put in those tokens if it is not obvious.
•
In some cases, the primary information might not be in a form usable by another
process. A file number in a file-system WRITE call is a good example. In these
cases, give directions telling how to transform what is available into what is useful
and define a token for the result of the transformation, not for the starting values.
•
Be sure to tell what to do for a token corresponding to an optional argument to the
procedure in the case that argument is not used in the call that encountered the