About Items

Items are system-maintained handles for shared resources. Each item contains a globally unique identification number and a pointer to the resource. Items can refer to any one of many different system components such as data structures, I/O devices, folios, tasks, and so on. You need to understand and use the item function calls in order to use these various system components.

The procedure for working with an item is the same, regardless of the item type. The procedure is as follows:

  1. Define the necessary parameters (tag arguments) for the item you want.
  2. Create or open the item using the tag arguments.
  3. Use the item.
  4. Delete or close the item when you're finished with it.
Portfolio provides a set of kernel calls that manage items while they're in use. These calls allow a task to check for the existence of an item, find the item number of a named object, get a pointer to an item, lock and unlock an item, and change the item's priority and owner.

To create items for you application, you need to include the following header files:

These header files declare structures, types, parameters, routine definitions, and other definitions needed for items. You also need the include file for some items that are associated with that folio. For example, to create an item used by the Audio folio, you'll have to include the audio.h file.

The kernel creates and keeps track of items in system memory. When the kernel creates an item, it creates a node for that item using the ItemNode data structure:

typedef struct ItemNode
{
    struct ItemNode *n_Next; /*pointer to next itemnode in */

                                /* list */
    struct ItemNode *n_Prev; /*pointer to previous itemnode in 

                                /* list */
    uint8 n_SubsysType;    /* what folio manages this node */
    uint8 n_Type;        /* what type of node for the folio */
    uint8 n_Priority;    /* queueing priority */
    uint8 n_Flags;        /* misc flags, see below */
    int32 n_Size;        /* total size of node including hdr */
    char *n_Name;        /* ptr to null terminated string or NULL*/
    uint8 n_Version;    /* version of of this itemnode */
    uint8 n_Revision;    /* revision of this itemnode */
    uint8 n_FolioFlags;    /* flags for this item's folio */
    uint8 n_ItemFlags;    /* additional system item flags */
    Item  n_Item;        /* ItemNumber for this data structure */
    Item  n_Owner;        /* creator, present owner, disposer */
    void *n_ReservedP;    /* Reserved pointer */
} ItemNode, *ItemNodeP;
The fields in this data structure define the status of the item and give information about the item. User tasks can't change their values, but they can look at them for information such as the version and revision numbers of an item (useful for items such as folios or devices). LookupItem(), described later, returns a pointer to the ItemNode structure for a specific item.

Creating or Opening an Item

To use most items such as message ports and semaphores, a task must first create them. The system, however, supplies some items premade on disk: folios, devices, and drivers. To use a folio or a device, a task opens it instead of creating it from scratch.

The difference between item creation and item opening is important: a created item is owned by the creating task, which can delete the item at any time. A created item is automatically deleted if the owning task quits without deleting it. On the other hand, an opened item is owned by the original creator and is shared among tasks. When a task opens the item, the item is loaded into memory and the kernel registers the opening task as a user. When another task opens the same item, the kernel registers that task as well.