|
|
|
While error checking is minimized in order to increase AIF performance,
architected interfaces provide comprehensive error management.
Architected interfaces provide parameters that return information about the
success or failure of the call. Each status parameter uses the data type
status_type to return status information. Following are the types of
status parameters provided by many operating system AIFs:
- overall_status
- itemstatus_array
- ver_item_statuses
Each AIFnnGET interface checks to make sure that the specified
item exists on the system and that the caller is of sufficient privileged
level. If the caller meets the access criteria, checking will be done to
ensure that the addresses that values are being returned into are accessible
to the caller. For example, AIFs cannot be used to change the contents of
variables in another process's stack.
Each AIFnnPUT interface checks to make sure that the specified
item exists on the system and that the caller is of sufficient privileged
level. In addition, whenever possible, values are range checked prior to
insertion.
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:
- ver_item_nums
- ver_items
- ver_item_statuses
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).
|
