Error Management

• overall_status

• itemstatus_array

• ver_item_statuses

Status Data Type

The data type required for use with status parameters is status_type (also described in appendix B):

status_type = record

                case boolean of

                true : (all    : integer);

                false: (status : shortint;

                        subsys : shortint);

              end;

If no error is detected, a status parameter returns a zero. If an error is detected, the status variable returns a negative value.

If errors are detected, the 32-bit value returned must be evaluated as an array of two 16-bit integers. The leftmost 16 bits (first element), evaluated as a 16-bit integer, return a status number and the rightmost 16 bits, evaluated as a 16-bit integer, return the subsystem number.

The AIF subsystem number is 516, so AIF errors are reported with a subsystem number of 516. In some cases, the AIF calls another subsystem; if that subsystem detects an error, the called subsystem's number may be returned instead.

The status number provides error information. Appendix A provides a complete list of the AIF status numbers and their meanings.

	NOTE: Status variables must be initialized to zero before calling the AIF.

Overall Status

AIFs use the parameter overall_status to indicate the status of the overall call. If an AIF call is successful, zero is returned in overall_status. If an error has occurred, a negative number is returned.

A positive number returned indicates the index of the last element in the items_array parameter that caused an error. There might be more errors, but you must check each element in itemstatus_array to locate additional errors.

	NOTE: Always initialize all elements of overall_status to zero before calling AIFs.

Item Status

The itemstatus_array parameter is an array of status_type. This array returns status information on each individual item located in the item_array parameter. There is a one-to-one correspondence between elements in itemstatus_array and elements in item_array. For example, the eighth element of itemstatus_array returns status information about the eighth element of item_array. The itemstatus_array parameter is available with all information access AIFs and some functionality access AIFs. A positive value returned in an itemstatus_array element indicates a warning condition associated with the item in the corresponding item_array element. A negative value returned in an itemstatus_array element indicates that there is an error associated with the item in the corresponding item_array element.

In addition, itemstatus_array can return a special error indicating that more elements in the array could have been accommodated.

	NOTE: Always initialize all elements of itemstatus_array to zero before calling AIFs.

Item Verification Status

There are three optional parameters available with AIFnnPUT AIFs:

These parameters are arrays used to verify that specific conditions are true before information updating proceeds. If an item value in the ver_items array does not match the corresponding item in the item_array returned by the previous AIFnnGET call, none of the AIFnnPUT operations succeed.

The ver_item_statuses is an array of status_type. This array returns status information concerning the success or failure of verification on each item specified in the ver_item_nums parameter and the data pointed to by the ver_items parameter. There is a one-to-one correspondence between elements in ver_item_statuses and elements in ver_item_nums. For example, the eighth element of ver_item_statuses returns status information about the eighth element of ver_item_nums.

Each element of this array returns a status that follows all the conventions of status_type. A status of zero indicates a successful call, a negative number indicates an error, and a positive number indicates a warning.

If verification fails, overall_status contains an error status number -24 (Verification failed). You must scan each element in the ver_item_statuses array to determine which item failed verification.

	NOTE: Always initialize all elements of ver_item_statuses to zero before calling AIFs.

Hierarchical File System

MPE/iX Release 4.5 begins implementing features of POSIX. The largest impact that POSIX has on the Architected Interface Facility is the introduction of the Hierarchical File System (HFS). POSIX supports the specification of file pathnames that can reach a maximum path length of 1024 (including the null terminator).

This makes the concept of fixed size Return Arrays impractical for returning a list of pathnames since enormous arrays would need to be defined.

For those AIFs which return a list of filenames (for example, AIFSYSWIDEGET and AIFPROCGET), the names will be returned into a user buffer (the user may chose to pass in a long pointer to a mapped file, to a buffer in the user's stack, to an AIF global area). Each name will be terminated by a null character and the next name will follow starting in the next byte.

For those AIFs which return a single pathname, the user will specify on input the maximum pathname size in the first word of the user buffer. On output, the actual length of the pathname in bytes will be returned. All returned pathnames will be terminated with a null character which will not be included in the length. Following is an example of a pathname buffer.

                1  2   3  4  5  6  7  8  9 10 11 12 13 14 15 16 17

        ----------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

        |len=16| / D  I  R  /  D   I  R  2  /  F  N  A  M  E  1 \0|

         ---------------------------------------------------------

                                                                 |

                                                                Null

                                                                terminator

If the pathname returned is too large to fit in the user buffer as specified by the length in the first word, then an error will be returned to the user application.

	NOTE: For each AIF which accepts or returns a filename, new parameters or items have been added to support HFS pathnames. Existing items which are defined as MPE names (file.group.account) will not be effected. The idea is that eventually most applications will convert over to use the new HFS items, but they will not be forced to convert over immediately.

For more general information on POSIX, refer to New Features of MPE/iX: Using the Hierarchical File System (32650-90351).