Types of Operating System Architected Interfaces

Each purchaser of the Architected Interface Facility: Operating System product is assigned a unique user ID. Whenever you call an AIF, you should identify yourself by using your company's user ID.

Each AIF includes an optional user_id parameter. If your program is only going to make a small number of AIF calls, then you'll want to pass the user ID to each AIF as you call it; however, if your program is going to make a lot of AIF calls, there is a more efficient method to specify your user ID. If your application uses the AIFACCESSON AIF to pass your user ID, all subsequent AIF calls made by your application are assumed to belong to the same user ID. Use AIFACCESSOFF after completing the multiple AIF calls.

	NOTE: You must use the user ID installed through INSTOS in all calls to AIFs described in this manual. If you have purchased another Architected Interface Facility product (for example, measurement interface AIFs), you still need to call AIFACCESSON with the Architected Interface Facility: Operating System user ID in order to call operating system AIFs, even if you have called AIFACCESSON for the other product.

Architected Interface Facility user IDs are used by Hewlett-Packard Response Centers to ensure that AIF-based software products are properly supported. The user IDs are not intended to prevent users who have not purchased an Architected Interface Facility product from calling AIFs; instead, user IDs are intended to guarantee the best possible support.

Because AIFs are trusted procedures, their misuse can cause a number of system problems (including system failures and data corruption). If this should happen, Hewlett-Packard's Response Centers can determine the user IDs associated with any AIF calls that result in errors. In this way, identifying and fixing AIF-related system problems can be accomplished quickly.

In most cases, there are two types of AIF for each class of objects that information can be accessed, an AIFnnGET and an AIFnnPUT.

The AIFnnGET AIF returns information about a specific object identified by the input keys. All AIFnnGET AIFs attempt to return as much information as possible each time they are called, returning individual item errors whenever possible. These errors are returned in the itemstatus_array parameter for the items in error, while the rest of the item values are returned normally.

The AIFnnPUT AIFs update relevant tables to obtain a consistent, updated state of the system. Only a subset of the items provided by the AIFnnGET AIFs are available to AIFnnPUT AIFs.

Because there is no guarantee that the information that is returned from an AIFnnGET AIF is still valid when an AIFnnPUT AIF is called, each AIFnnPUT AIF allows for verification of values to take place before a system table update occurs.

A list of items and corresponding values may be specified in the verification arrays to the AIFnnPUT AIF. Each item is checked and validated before attempting to do a system table update. If any single item that is to be verified fails, the information is not placed into the system. This verification helps prevent the system from accidentally being placed into an undesirable state. If no verification items are specified, the system table update is performed unconditionally.

The system wide information AIF is

The AIFSYSWIDEGET AIF is normally the first AIF called. It returns information about a whole class of objects, instead of information about a particular object as the other AIFs do.

The AIFSYSWIDEGET AIF enables you to specify an object class as well as a list of criteria that you wish to apply to the objects in that class. It applies all of the criteria to each object located, returning only those objects that meet the criteria that you specify. The AIFSYSWIDEGET AIF returns a list of meaningful object identifiers and, optionally, a corresponding list of alternative input keys, when possible. You can use the alternative input keys with other AIFs to retrieve information faster than using the object identifiers.

The AIFSYSWIDEGET AIF may return a context key that indicates that there are a greater number of objects available than there are elements in the user-defined array passed to the AIF. Use this context key in a subsequent call to retrieve the additional objects.

The accounting information AIFs are

Accounting information AIFs return or update information associated with directory objects such as users, groups, and accounts. Accounting information AIFs use a user name, group name, or account name as input keys. The input keys default to the calling process' user name, group name, and account name.

There are two types of file information AIFs:

Job or session information AIFs are

Job or session AIFs return or update information associated with jobs and sessions. They accept job numbers or session numbers as input keys, returning or updating job or session information associated with the keys. The keys can be obtained either from AIFSYSWIDEGET or from other means (for example, from the SHOWJOB command). The input keys default to the calling process's job or session number.

Process information AIFs are

Process information AIFs accept PIDs and PINs as input keys. They return or update process-related information. The input keys can be obtained either from AIFSYSWIDEGET or from file information AIFs.

The AIFPROCGET AIF returns information about all of the files opened by the process, process-specific file numbers, and UFIDs. These three can then be used to query the file interfaces. The AIFPROCGET AIF also returns the default account and group for the process, their names, and UFIDs. This information can be used to query accounting information AIFs.

The reply information AIF requires only a reply request ID as input. It retrieves information on a specified pending reply request. In addition to providing the table information, it also formats the request message as it is displayed on the console by the RECALL command.

The reply information AIF is

There are two types of spooler information AIFs

System configuration information AIFs are

AIFSCGET and AIFSCPUT do not require any keys, because they access system-wide configuration information. AIFSCGET provides access to the configuration constants and the dynamically maintained system variables, such as upper limits, but does not provide lists of valid objects on the system. AIFSCPUT performs actions similar to the TUNE and ALLOW commands, as well as some of the startup options.

Some of the configuration constants AIFSCGET and AIFSCPUT access are the various dispatcher queue priority limits and quantums. The dynamic system information includes the next job/session number to be allocated, the CS average quantum for transactions, and the current ALLOW mask.

Device information AIFs are:

AIFDEVCLASSGET retrieves information on a specific device class. AIFDEVICEGET retrieves information on a specific device (ldev). AIFDEVICEPUT updates information on a specific device (ldev).

• User global area management

• Ports management

• Spooler management

• Magneto-Optical Disk Library System

• Miscellaneous utilities

User global area management AIFs are:

User global area management AIFs enable you to share data between multiple processes and enforce concurrence on access to this data.

Ports management AIFs are:

Ports management AIFs enable you to create and manage Architected Interface Facility user ports. User ports can be used as a fast means of interprocess communication by sending messages from one process to another. User ports do not interfere with or provide access to system ports.

Spooler management AIFs are:

Spooler management AIFs enable you to manage spool files and spooler processes. For example, you can start, stop, resume, or suspend devices. In addition, you can link files to the MPE/iX spooler facility.

Magneto-Optical Disk Library System AIFs are:

Magneto-Optical Disk Library System AIFs provide a supported external interface to optical disk library systems while extracting internal detail. These AIF's provide a layer above the existing Media Manager routines. The Media Manager is a set of operating system routines that are used to control a Magneto-Optical Disk Library System. The Media Manager functions that are provided through AIF's include: allocating and deallocating an optical media drive, mounting and dismounting optical media, and retrieving and modifying optical disk library system information.

Refer to the following manuals for more information:

Utility AIFs provide miscellaneous functionality useful to application developers.