next up previous contents index
Next: Differences amongst FRSs Up: The Generic Frame Protocol Previous: The GFP Knowledge Model

GFP Operations

In presenting the functional interface of the Generic Frame Protocol (GFP), we first describe concepts that are common to many operations, including common arguments and standard ways to signal errors. Then we give an overview of all the GFP operations, based on the type of objects on which they operate. To facilitate the use of GFP with multiple programming languages we describe language bindings for C, Lisp, and Java. Finally, we list all the GFP operations, along with their input arguments, return values, and descriptions.

The concept of KB behaviors, common to many GFP operations, is described in detail in Chapter 4. On the first reading of this chapter, any references to KB behaviors can be safely ignored.

GFP Architecture

GFP assumes a client-server architecture for application development. The client and server can be on different machines, on the same machine but in a different address space, or on the same machine and in the same address space. When the GFP client and server are on different machines, they communicate via the GFP transport layer. The GFP transport layer can be implemented by direct procedure calls if the client and server are in the same address space, or any of the standard network protocols (e.g., CORBA or TCP/IP).

Using GFP, a client application can access any FRS that supports a GFP server. GFP enables an application to access multiple GFP servers, each of which may support multiple FRSs, which in turn may provide access to multiple KBs. For example, an application that merged multiple KBs could access a LOOM KB on one server, two Ontolingua KBs on a second server, and place the result in a Classic KB on a third server.

To access a KB, an application loads the GFP client library for the appropriate programming language. For instance, an application written in the Java programming language would be compiled with the GFP Java client library. The client library defines Java methods for all of the GFP operations. It also defines Java classes to implement all of the GFP entities, and conditions to implement all of the GFP conditions.

To access a GFP server, a client application typically undertakes the following steps. First, the application must establish a connection to a GFP server (using   establish-connectiongif). Second, the application may find out the set of FRSs that the server supports on that connection (using   get-kb-types). Third, the application can get information about the KBs of a given type that can be opened on the connection (using   openable-kbs). Finally, the application can either open a specific KB (using   open-kb) or create a new one (using   create-kb). The application may now query and manipulate the KB by executing GFP operations. For example, it can look for specific frames (using   get-frames-matching), find the root classes of the KB (using   get-kb-roots, create new frames (using   create-frame), and save changes (using   save-kb).

A back end implementor implements the GFP operations by using the FRS's native API. Whenever there is no direct mapping between a GFP operation and some operation in the native API, the back end may invoke multiple operations in the native API or perform some runtime translation between the constructs of GFP and the constructs supported by underlying FRS. For example, LOOM supports a concept definition language but no facets. It is possible to translate the LOOM\ concept definition language into GFP facets, for example, the :at-most concept constructor of LOOM is translated into the :maximum-cardinality facet.

There is considerable redundancy in GFP operations -- some operations can be implemented in terms of others. For example, consider the operations   class-p and   individual-p that check whether an entity is a class or on individual. If we define either of these two operations, it can be used to define the other, because the domain of discourse is partitioned into classes and individuals. The minimal set of GFP operations that must be implemented, also known as mandatory methods, is known as a kernel. Because of this redundancy, an implementor can choose a kernel that most closely matches the native API of an FRS.

It is possible to develop a system that implements the complete protocol using a set of kernel operations. At least two such system have been implemented. As a consequence, an FRS developer can implement a complete GFP-compliant system by implementing only the kernel operations. This may lead to some loss in efficiency because some non-kernel operations may have more efficient implementation in terms of the native API of an FRS. For example, the operation   get-kb-classes can be implemented using   get-kb-frames and   class-p operations. Systems that store an explicit list of classes can return this result more efficiently.

FRS developers can also support subsets of GFP behavior in their back ends, and then advertise this using the behaviors mechanism (see Section 4.1). For instance, a back end might only define read-only operations on a KB. This further reduces the initial effort required to implement GFP.

Notation and Naming Conventions

Many GFP operations, (for example,   slot-p) are predicates on their arguments, and the value returned by them is a boolean truth value. All of these operations are named consistently with ``-p'' as a suffix. For example,   slot-p is a predicate that is true for slots, and   class-p is a predicate that is true for classes. When we say that an operation returns a boolean result, we mean that it returns either the GFP value false, which is to be interpreted as the boolean value false, or some non-false value is returned that is interpreted as the boolean true. Although such a truth-deciding value will frequently be the GFP value true, the only guarantee is that it will not be false. In some language implementations, the GFP values true and false may not be the same as the native language values for true and false.

We use a standard format for describing the GFP operations in Section 3.7. To explain this format, we use an example description of the get-slot-values operation as shown in Figure 3.1.

   
Figure 3.1: Format for documentation of GFP operations

Name. The first element is the name of the operation.

Argument list. The arguments are specified using the Common Lisp conventions. The argument list is divided into two groups, separated by the ``&key'' indicator. Mandatory arguments precede ``&key''. These arguments must be provided in all language bindings. The keyword (named) arguments follow the ``&key'' indicator. In Section 3.6, we discuss language bindings that show how the keyword arguments should be interpreted for languages such as C that do not support keyword arguments. In some language bindings, the keyword arguments may be optional. In language bindings that support optional keyword arguments (for example, Java), default values will be supplied for the optional keyword arguments. The specification of an optional keyword argument is either (1) a list whose first element is the argument name and whose second element is the default value or (2) the argument name. Otherwise, the argument defaults to false .

For example, kb-local-only-p defaults to false , and inference-level defaults to :taxonomic.

Return values. Following `` '' are the values returned by the operation or void if no value is returned. The operations may return more than one value. For example, get-slot-values returns three values -- a list containing the requested slot values, exact-p and more-status.

Flags. Each operation has a set of descriptive flags to indicate (1) whether there is a corresponding enumerator operationgif (E), (2) whether it is mandatory, optional or neithergif in the current implementations (M or O or I), and (3) if it is read-only or writes to the KB (R or W). For example,   get-slot-values has an enumerator, is read-only, and is optional in the current implementation.

Documentation. The documentation defines the meaning of the operations. For brevity, common arguments, such as inference-level, and common return values, such as more-status, are not described in the individual operation definitions, but in Sections 3.3 and 3.5. Arguments, return values, and GFP operations are in this font.

Common Concepts

  A comprehensive list of all arguments that are common to many GFP operations, and their default and legal values, is shown in Table 3.1. Some of the common arguments are described later, when we present an overview of the GFP operations (Sections 3.5).

Controlling Inference

    In many situations, it is necessary to control the inferences that should be performed while executing GFP operations. For example, while retrieving the values of a slot, a user may wish to receive directly asserted values and perhaps inherited values as well. To provide such control, many GFP operations support an inference-level argument that can take the following three values.

A value of :direct for inference-level is guaranteed to return at least directly asserted values, because in some systems, such as, forward chaining systems -- values in addition to the directly asserted values may also be returned. Some GFP operations, for example, an operation returning superclasses of a class may eliminate redundant values from the result. To help an application determine when exactly the directly asserted values are returned, all operations taking an :inference-level argument will return a second value (the first value being the result of the operation), exact-p, which is true if it is known that exactly the :direct or :taxonomic values is returned. A GFP implementation that always returns false as the value of exact-p is compliant, but implementors are encouraged to return true whenever possible.

Returning a List of Multiple Values

  For a GFP operation that returns a list of values, it is often desirable to limit the size of the resulting list and the computation necessary to establish the elements of the list. The number-of-values argument, which is supported by many GFP operations, allows the caller to limit the number of values returned. The legal values for this argument are :all, which is always the default, or any positive integer. A GFP operation accepting the number-of-values argument returns at least three values. The first value is the result list for the request, the second is the value of exact-p (discussed in the Section 3.3.1), and the third is more-status, a value that reveals whether there are more results available.

When number-of-values is :all; the value of more-status is either false, which indicates that there are known to be no more results, or :more, which indicates that there may still theoretically be more results, but the FRS was unable to find any more. When number-of-values is :all, a more-status value of :more means that the system cannot guarantee that it can access all possible results requested by the GFP operation.

If the number-of-values argument is a positive integer, then no more results than the specified number will be returned. The more-status will be one of the following three possible values.

 

Description Argument Name Default Value Constraint on a Legal Value X
Connection connection   gfp-local-connection (  connection-p X)
KB Type kb-type KB-type object
KB reference kb (current-kb) (  kb-p X)
KB inclusion kb-local-only-p false X {true false}
Frame reference frame (  coercible-to-frame-p X)
Slot reference slot (  slot-p X)
Facet reference facet (  facet-p X)
Class reference class (  class-p X)
Value value/thing Any value corresponding to GFP data types (portable) or any value corresponding to system-defined data types
Number of values to be returned number-of-values X=:all or a positive integer
Inferences to be performed inference-level :taxonomic X {:taxonomic, :all, :direct}
Test function test (kb-test-fn) X { :eql, :equal, :equalp } or a function specifier on the two arguments to be compared, KB object and kb-local-only-p, and must return true or false
Choosing values value-selector :known-true X { :known-true, :default-only, :either}
Controls whether error should be signaled error-p true X {true false}
Enumerator enumerator An enumerator object
Table 3.1: Commonly used arguments

 

Selecting between Default and Asserted Values

  As discussed in the knowledge model, GFP provides a facility to store and retrieve default values. Therefore, while adding a value to a slot or a facet, one may specify whether the value being added is a default value. Similarly, while retrieving values from a slot (or facet) of a frame, one may choose whether default values should be returned. This control is provided by the value-selector argument. The argument value-selector may take one of the following three values.

Test Functions

Many GFP operations need to perform comparisons. For example, while removing a slot value, we need to compare the value to be removed with the existing slot values. GFP operations requiring such comparisons support a test argument whose value is one of :eql, :equal, :equalp, or a procedure that should be used in the comparisons. The test argument defaults to :equal. The functions invoked for the values :eql, :equal, and :equalp are   eql-in-kb,   equal-in-kb, and   equalp-in-kb respectively. The arguments to a test procedure are the two entities to be compared, and the KB for which the comparison should be performed, and kb-local-only-p (discussed in Section 3.5.2). The test function should return either true or false. Supplying a function in the native programming language as a value of test is not portable especially in network applications.

Handling Errors

To support the development of robust applications, some standard means   for processing error conditions are desirable. Whenever possible, GFP operations that experience erroneous conditions or arguments signal errors. GFP uses condition signals that are analogous to COMMON LISP\ conditions or Java exceptions. Condition signals are defined for commonly occurring error situations. GFP provides a user with some control over when the errors should be signaled. A comprehensive list of standard GFP errors is available in Section 3.8.

The GFP errors are said to be either continuable or not. An error is said to be continuable only if the state of the KB is not known to have been changed by the error in such a way that the behavior of subsequent GFP operations becomes undefined. Thus, although the signaling of a continuable error will interrupt any processing currently being performed, subsequent GFP calls will be unaffected. After a non-continuable error, the state of the KB and the behavior of the FRS and application are undefined. The operation   continuable-error-p returns true only for continuable error objects, and is false otherwise.

The error behavior of GFP operations is specified in one of the following four ways: ``is an error'', ``error is signaled'', ``unspecified behavior'', ``is not portable''.

Whenever we say that ``it is an error'' for some situation to occur, it means that no valid GFP program should cause that situation to occur; if it occurs, the effects and results are completely undefined. No GFP-compliant implementation is required to detect such errors, but implementors are encouraged to detect such errors when possible. In some cases we also specify the condition that should be signaled if an implementation decides to signal one and has choice over which error is signaled.

When we say that an ``error is signaled'' in a situation, any GFP-compliant implementation must signal an error of the specified type when that situation is encountered.

When we say that ``behavior is unspecified'' for a given situation, it means that a GFP-compliant system may or may not treat that situation as an error.

An example of a situation where the behavior is unspecified is the function   replace-slot-value that replaces an existing slot value with another. The definition of   replace-slot-value does not specify whether an error should be signaled when the slot value to be replaced is not a current value of the slot, or if the new value to be added is already a value of the slot. This approach simplifies the implementation and speeds performance since each underlying FRS may make different assumptions about signaling behavior.

When we say that a particular usage is not portable, we mean that an application may legally operate in this state, but even if correct behavior is observed, it is not guaranteed to be the case if the application is directed at a different knowledge base (KB) of the same FRS, or the same KB with different behavior settings, or a KB resident in a different FRS (even with the same content), or a KB connected over a network. For example, many KBs uniquely identify frames by their names. For a KB with a value true for the behavior :frame-names-required, a frame name may be used as a valid argument for any operation that accepts a frame argument. Since the :frame-names-required behavior can be false for some KBs, such usage is not portable, because a frame name will not always be a valid argument for an operation that accepts a frame argument.

The general rule is that a standard GFP error will be signaled when the documented exceptions occur. If, for example, the user attempts to retrieve slot values from a frame that does not exist, by using a call to the function   get-slot-values, the error not-coercible-to-frame is signaled. Errors can also be signaled when slot constraints are violated. When a constraint violation occurs, the FRS should signal one of the conditions defined for constraint violations.

In two situations, an application program needs explicit control of whether an error should be signaled. An example of the first situation is the function coerce-to-frame that coerces a given object to a frame. In general, coerce-to-frame signals an error if the input object cannot be coerced to a frame. But a user program may not wish an error to be signaled if it is not sure if the input object is indeed coercible to a frame. The second situation is encountered in functions such as copy-frame that perform multiple operations. For such functions, a user may wish to continue copying even if there is an error, in which case the copy-frame continues copying as much as possible.

  To provide such control, a few GFP operations accept an error-p argument. The default value for error-p is true, in which case the errors are signaled as usual. If error-p is false, the operation catches at least the documented conditions and continues execution if possible.

The GFP operations accepting the error-p argument return a second status value, in addition to the usual return value. When the second value is true, and error-p is false, it means that execution completed successfully.

Overview of GFP operations

We categorize all the GFP operations based on the type of objects in which they operate. We introduce here any new concepts that are necessary for understanding those operations, and list operations in each category. Detailed descriptions of all operations are in Section 3.7.  

Operations on Connections

  GFP has been designed to be easily used in both centralized and distributed environments. To permit this, we use an abstraction called a connection that encodes the actual location of a GFP KB and mediates communication between a GFP application and the KB. To communicate with an FRS, an application program first establishes a connection by using the establish-connection operation. With each GFP operation, we need to indicate the connection that should be used in executing it. Some GFP operations take an explicit connection argument, whereas others derive the connection from a KB argument (explained in Section 3.5.2). Thus, once a connection is established, a user need not be aware of the actual location of the KB or whether the KB is being accessed from the same address space as the application or over the network.

Depending on the nature of the communication and the security model involved, different types of connection are used to perform the mediation between a GFP client and a server. For example, if a GFP server requires user authentication, the client will have to fulfill the authentication requirement before being able to establish a connection. The GFP specification does not provide a detailed definition of connections since the specific behavior of the connections will be a function of the communication, threading, locking, and security models used by the server. A provider of a GFP server is required to make the definition of its supported connection types available to the authors of GFP client programs.

The connection operations are:   all-connections,   close-connection,   connection-p,   establish-connection,   local-connection

Operations on KBs

  Network GFP operations take a kb argument that specifies the KB to which the operation applies. Multiple KBs may be open for access simultaneously by a GFP application. Different KBs may be serviced by different FRSs. For example, a single application might simultaneously access both a LOOM and a THEO KB.

    With each KB in an FRS, we associate a GFP KB-object and a KB-locator. A KB-object uniquely identifies a KB (discussed below) in a GFP application. A KB-locator is a frame in the meta-KB and contains sufficient information to locate and open the KB. For example, for a KB residing in a file, a KB-locator may contain the name of the KB and its pathname. In effect, a kb-locator is to a KB as a filename is to a file. GFP operations requiring a kb argument must be supplied with a KB-object. The kb argument defaults to the current KB, which is queried by the GFP operation   current-kb and set by the operation   goto-kb.

  GFP defines a taxonomy of KB-object types. An FRS may have several KB-object types defined for it. For example, one can imagine a type hierarchy in which the root class is ``KB'', with a subclass ``LOOM-KB'', which in turn has subclasses ``LOOM-FILE-KB'' and ``LOOM-ORACLE-KB.'' A back end implementor may define new KB types for her purpose, for example, ``CYC-KB''. Methods defined for KB types can be used to implement the type-specific KB operations. Certain GFP operations must be performed before an application has created a KB or acquired a reference to a KB object. Such operations must be supplied a kb-type argument, which should be the type object for the KB class for which the operation is to be executed. A KB type object for a KB class can be obtained by using the GFP operation   get-kb-type.

Our model of KB access allows KBs to reside on different types of secondary storage devices, including both flat files, and database systems on remote servers. We do not assume that the KB is read into memory in its entirety when the KB is opened for access. An existing GFP KB can be opened using the GFP operation open-kb. A new GFP KB can be created using the GFP operation create-kb. An open KB may be saved using save-kb or closed using close-kb.

The GFP operation openable-kbs can determine which KBs are available on a given connection and return KB-locators for such KBs. Each such KB-locator can then be used as an argument to open-kb.

Many FRSs allow the creation of new KBs by including existing KBs. The semantics of KB inclusion vary widely amongst FRSs. It is often useful to limit the scope of an operation so that it is performed to exclude any frames belonging to KBs that were included in the current KB from some other KBs. For example, if a client application wants to display a class graph, it might want to select the roots of the graph by ignoring frames from any included KBs. To control such behavior, many GFP operations take the argument kb-local-only-p,   which when set to true ignores, if possible, any information in the KB that was included from another KB. The kb-local-only-p argument always defaults to false.

  As was mentioned in Chapter 2, the entities in the domain of discourse of interest to GFP exist within a knowledge base (KB). Because KBs themselves are of interest to us, every GFP implementation must define a special KB, called meta-KB containing frames that represent KBs themselves. Such frames representing the KB are the same as KB-locators. A meta-kb can be accessed using the GFP operation   meta-kb.

The meta-KB also contains classes corresponding to each kb-type. Each KB-locator is an instance of an appropriate kb-type in the meta-KB. For example, a KB-locator representing a LOOM KB may be an instance of loom-kb KB-type.

The meta-KB allows the use of the GFP operations to manipulate KB-locators. For example, we could view the contents of a KB-locator using the GFP operation (  print-frame kb-locator :kb (  meta-kb)). Similarly, we could use   get-class-instances to determine all the instances of the KB-type loom-kb as follows. 

    (get-class-instances (get-kb-type 'loom-kb) :kb (meta-kb)
                         :inference-level :taxonomic)

The KB operations are   close-kb,   copy-kb,   create-kb,   create-kb-locator,   current-kb,   expunge-kb,   find-kb,   find-kb-locator,   find-kb-of-type,   get-kb-direct-children,   get-kb-direct-parents,   get-kb-type,   get-kb-types,   get-kbs,   get-kbs-of-type,   goto-kb,   kb-p,   meta-kb,   open-kb,   openable-kbs,   revert-kb,   save-kb,   save-kb-as

Operations on Frames

In GFP, as many as four identifiers are associated with a frame: frame name, frame handle, frame object, and pretty-name. Many FRSs associate a name with each frame in a KB. The frame name can be of type symbol or string. When the :frame-names-required behavior is true, a frame name uniquely identifies a frame. Some FRSs do not use frame names. GFP parameterizes this behavior of an FRS by setting the :frame-names-required behavior. When the value of :frame-names-required is true, it means that each frame is required to have a name, the frame name is unique in a KB, and the frame name supplied at the time of frame creation can be used at a later time to identify the frame. When the value of the :frame-names-required behavior is false, frame names are not required, and may not be unique in a KB even if supplied; one may not be able to locate a frame by using the name that was supplied when the frame was created.

A frame handle always uniquely identifies a frame in a KB. For some FRSs, a frame handle may be the same as the frame name or the same as the frame object. Frame handles are always supported by all the GFP back ends. To ensure portability, GFP application writers are encouraged always to refer to frames by frame handles.

A frame object is a reference to the actual data structure that encodes the information about the frame in an FRS. A frame object always uniquely identifies a frame in a KB. Some FRSs may not have a single data structure representing a frame. In such cases, the frame object is not distinguishable from the frame handle, and all frame-like properties of the frame are emergent from the context of the KB. For example, if we view an object-oriented database as an FRS, then object-identifiers (OIDs) could be viewed as frame handles. The information about an object identified by an OID does not all reside in one physical data structure in the database, but the contents of that object can still be viewed using GFP.

Any GFP operation that takes a frame argument must accept either a frame handle or a frame object as a valid value. A frame name is guaranteed to be a valid value for the frame argument only if the :frame-names-required behavior is set to true.

The frame pretty-name is a name for a frame that is meant for use in a user interface that needs to display a visually appealing but terse presentation for a frame. A pretty-name need not be unique or suitable for use in a program except for display purposes.

In Table 3.2, we summarize how different frame properties differ along several dimensions. These properties might differ in a complex implementation as follows. The frame name is a symbol unique in a KB, but not across different KBs (different KBs can contain different frames that happen to have the same frame name). The frame handle is a data structure used by an FRS to represent frames conveniently and efficiently. It is guaranteed to be unique only in a KB. The frame pretty-name is a string naming the frame in a pretty manner, that happens to be retrieved from a slot of the frame.

 

Type Unique Unique Frame arg? Slot value? Pretty?
in KB? across KBs?
Name symbol/ yes no yes FRS maybe
string dependent
Handle any yes no yes yes no
Object any yes no yes yes no
Pretty-name string no no no not portably yes
Table 3.2: The differences between the GFP mechanisms for identifying individual frames. Type -- The data type of the identifier (e.g., the frame pretty-name must be a string). Unique in KB? -- Must the identifier be unique within a given KB? Unique across KBs? -- Must the identifier be unique across all KBs? Frame arg? -- Can the identifier be used as a frame argument to most GFP functions? Slot value? -- Can the identifier be a slot value that records a relationship among frames? Pretty? -- Is the name suitable for display within a user interface?

 

The frame operations are:   allocate-frame-handle,   coerce-to-frame,   coercible-to-frame-p,   copy-frame,   create-frame,   delete-frame,   frame-in-kb-p,   get-frame-details,   get-frame-handle,   get-frame-in-kb,   get-frame-name,   get-frame-pretty-name,   get-frame-type,   get-frames-matching,   get-kb-frames,   print-frame,   put-frame-details,   put-frame-name,   put-frame-pretty-name

Operations on Classes

The class operations are:   add-class-superclass,   class-p,   coerce-to-class,   create-class,   get-class-instances,   get-class-subclasses,   get-class-superclasses,   get-kb-classes,   get-kb-roots,   instance-of-p,   primitive-p,   put-class-superclasses,   remove-class-superclass,   subclass-of-p,   superclass-of-p

Operations on Instances

The instance operations are:   add-instance-type,   get-instance-types,   put-instance-types,   remove-instance-type,   type-of-p

Operations on Individuals

The operations on individuals are:   coerce-to-individual,   create-individual,   get-kb-individuals,   individual-p

Operations on Slots

The GFP knowledge model distinguishes between own slots, the slots that appear in frames, and template slots, slots that are defined in classes, but are expressed in the frames that are instances of those classes. Rather than having a different set of operations for each type of slot, GFP has a single set of operations that applies to both own and template slots. Appropriate behavior of these operations is selected by the slot-type argument that can take one of the following three values.

For an operation that does not take a slot argument, slot-type defaults to :all. For all other operations taking a slot-type argument, the default is :own.

The slot operations are:   add-slot-value,   attach-slot,   coerce-to-slot,   create-slot,   delete-slot,   detach-slot,   follow-slot-chain,   frame-has-slot-p,   get-frame-slots,   get-frames-with-slot-value,   get-kb-slots,   get-slot-type,   get-slot-value,   get-slot-values,   get-slot-values-in-detail,   member-slot-value-p,   put-slot-value,   put-slot-values,   remove-local-slot-values,   remove-slot-value,   rename-slot,   replace-slot-value,   slot-has-value-p,   slot-p

Operations on Facets

  The facet operators are:   add-facet-value,   attach-facet,   coerce-to-facet,   create-facet,   delete-facet,   detach-facet,   facet-has-value-p,   facet-p,   get-facet-value,   get-facet-values,   get-facet-values-in-detail,   get-frames-with-facet-value,   get-kb-facets,   get-slot-facets,   member-facet-value-p,   put-facet-value,   put-facet-values,   remove-facet-value,   remove-local-facet-values,   rename-facet,   replace-facet-value,   slot-has-facet-p

Enumerators

Many GFP operations that return a list of results as their first value, such as   get-kb-classes, provide an alternative method for accessing their results. The alternative is an enumerator, which can be used enumerate the results one at a time, or even fetch them in batches. Enumerators are especially important when operations return a large list of results; they can also provide a significant speedup in a networked environment when only a portion of the results are required. For certain programming languages, such as Java, enumerators are a very common programming idiom.

Each enumerated operation, such as   get-kb-classes, has a corresponding enumerator operation. The name of the enumerator operation is derived from the basic operation by removing the prefix `get-' if any and adding the prefix `enumerate'. The arguments to the enumerator operations are exactly the same as the arguments to the basic operations.

There are a small number of operations defined on enumerators to get the   next element, to determine if an enumerator   has-more elements, to   fetch a list of elements, to   prefetch a batch of elements, and to   free an enumerator. Note that in networked environments, prefetching values from the server may result in a substantial performance benefit. It is always important to   free an enumerator that is not yet exhausted but which is no longer needed.

The enumerator operations are:   enumerate-all-connections,   enumerate-ask,   enumerate-call-procedure,   enumerate-class-instances,   enumerate-class-subclasses,   enumerate-class-superclasses,   enumerate-facet-values,   enumerate-facet-values-in-detail,   enumerate-frame-slots,   enumerate-frames-matching,   enumerate-instance-types,   enumerate-kb-classes,   enumerate-kb-direct-children,   enumerate-kb-direct-parents,   enumerate-kb-facets,   enumerate-kb-frames,   enumerate-kb-individuals,   enumerate-kb-roots,   enumerate-kb-slots,   enumerate-kb-types,   enumerate-kbs,   enumerate-kbs-of-type,   enumerate-list,   enumerate-slot-facets,   enumerate-slot-values,   enumerate-slot-values-in-detail,   fetch,   free,   has-more,   next,   prefetch

Tell/Ask Interface

Using the   tell operation, a user may assert any sentence that is accepted by the   tellable operation. We expect each FRS to define the classes of sentences that are   tellable. To define the semantics of telling an arbitrary class of sentences is outside the scope of the current specification. We define the semantics of   telling a restricted set of sentences, such that the effect of   telling each sentence in this set is equivalent to executing some GFP operation. We define similar sets of sentences for the   ask and   untell operations. The current specification of GFP does not take any position on the semantics of using   tell,   ask, and   untell with sentences that are not being considered here.

While defining the semantics of   tell,   ask, and   untell, we consider the sentences that use predicate symbols of the GFP assertion language defined earlier in the knowledge model. The predicates of the GFP assertion language are class, slot and facet names in the KB, type-of, instance-of, subclass-of, primitive, template-slot-value, template-facet-value, class, individual, subclass-of, slot-of, facet-of, template-slot-of, and template-facet-of.

Semantics of tell

Table 3.3 lists the sentences, which if asserted using tell, have defined semantics according to the current GFP specification. The semantics of   telling each sentence are defined using some GFP operation. In all the GFP operations, we assume that the :inference-level is :direct, and assume the default value of other parameters unless stated otherwise. For example, kb-local-only-p is assumed false, and kb is assumed to be the value returned by the GFP operation   current-kb.

If we tell the sentence (person john), it will be equivalent to adding person as a type of frame john. If either person or john does not exist in the KB, the effect will be the same as the effect of executing   add-instance-type when either the frame or the new type being added does not exist in the KB. The semantics of   telling other sentences can be interpreted analogously.

 

Sentence Effect of Executing (tell sentence )
(slot  frame value) (  add-slot-value frame slot value :slot-type :own)
(facet  slot frame value) (  add-facet-value frame slot facet value)
(instance-of  frame class) (  add-instance-type frame class)
(type-of  class frame) (  add-instance-type frame class)
(primitive  class) Not a tellable sentence
(template-slot-value  slot class value) (  add-slot-value class slot value
:slot-type :template)
(template-facet-value  facet slot (  add-facet-value class slot facet value
class value) :slot-type :template)
(class  class) (  create-class class)
(individual  individual) (  create-individual individual)
(slot-of  slot frame) (  attach-slot frame slot :slot-type :own)
(facet-of  facet slot frame) (  attach-facet frame slot facet :slot-type :own)
(template-slot-of  slot class) (  attach-slot slot class :slot-type :template)
(template-facet-of  facet slot class) (  attach-facet class slot facet :slot-type :template)
(subclass-of  class superclass) (  add-class-superclass class superclass)
(superclass-of  superclass class) (  add-class-superclass class superclass)
Table: Semantics of tell in terms of GFP operations (assuming that the kb argument defaults to the value of (  current-kb), error-p defaults to false, and :inference-level defaults to :direct.)

 

Semantics of Untell

  Table 3.4 lists the sentences, which if retracted using untell, have defined semantics according to the current GFP specification. The semantics of   untelling each sentence are defined using some GFP operation. We assume the default value of other parameters unless stated otherwise.

If we untell the sentence (person john), it will be equivalent to removing person as a type of frame john. The semantics of   telling other sentences can be interpreted analogously.

 

Sentence Effect of Executing (untell sentence )
(class  frame) (  remove-instance-type frame class)
(slot  frame value) (  remove-slot-value frame slot value :slot-type :own)
(facet  slot frame value) (  remove-facet-value frame slot facet value)
(instance-of  frame class) (  remove-instance-type frame class)
(type-of  class frame) (  remove-instance-type frame class)
(primitive  class) Not a tellable sentence
(template-slot-value  slot (  remove-slot-value frame slot value
class value) value :slot-type :template)
(template-facet-value  facet slot class value) (  remove-facet-value frame slot
facet value :slot-type :template)
(class  class) (  delete-frame class)
(individual  individual) (  delete-frame individual)
(slot-of  slot frame) (  detach-slot frame slot :slot-type :own)
(facet-of  facet slot frame) (  detach-facet frame slot facet :slot-type :own)
(template-slot-of  slot class) (  detach-slot class slot :slot-type :template)
(template-facet-of  facet slot class) (  detach-facet class slot facet :slot-type :template)
(subclass-of  class superclass) (  remove-class-superclass class superclass)
(superclass-of  superclass class) (  remove-class-superclass class superclass)
Table: Semantics of untell operations in terms of GFP operations (assuming that the kb argument defaults to the value of (  current-kb), and error-p defaults to false.)

 

Semantics of Ask

Table 3.5 lists the queries, which if asked using ask, have defined semantics according to the current GFP specification. The semantics of   asking each query are defined using some GFP operation. In all the GFP operations, we assume that the :inference-level is :direct, and assume the default value of other parameters unless otherwise stated.

If we ask the query (person ?x), we get all the direct instances of person, that is, it is equivalent to the result of invoking the GFP operation (  get-class-instances ?x). If we ask the query (slot ?x value), we are returned all the frames that have a slot slot containing the value, that is, it is equivalent to the GFP operation (  get-frames-with-slot-value value).

 

Query Effect of Executing (ask query )
(class  ?x) (  get-class-instances class)
(slot  frame ?x) (  get-slot-values frame slot)
(slot  ?x value) (  get-frames-with-slot-value slot value)
(facet  slot frame ?x) (  get-facet-value frame slot facet)
(facet  slot ?x value) (  get-frames-with-facet-value slot facet value)
(instance-of  ?x class) (  get-class-instances class)
(instance-of  instance ?x) (  get-instance-types instance)
(type-of  ?x instance) (  get-instance-types instance)
(type-of  class ?x) (  get-class-instances class)
(primitive  ?x) (  primitive-p ?x)
(template-slot-value  slot class ?x) (  get-slot-values class slot :slot-type :template)
(template-slot-value  slot ?x value) (  get-frames-with-slot-value slot value
:slot-type :template)
(template-facet-value  facet slot class ?x) (  get-facet-values frame slot facet
:slot-type :template)
(template-facet-value  facet slot ?x value) (  get-frames-with-facet-values slot facet value
:slot-type :template)
(class  ?x) (  get-kb-classes)
(individual  ?x) (  get-kb-individuals)
(slot  ?x) (  get-kb-slots)
(facet  ?x) (  get-kb-facets)
(slot-of  ?x class) (  get-frame-slots class)
(facet-of  ?x slot frame) (  get-slot-facets frame slot)
(template-slot-of  ?x class) (  get-frame-slots class :slot-type :template)
(template-facet-of  ?x slot class) (  get-frame-facets class slot
:slot-type :template)
(subclass-of  ?x superclass) (  get-class-subclasses superclass)
(subclass-of  subclass ?x) (  get-class-superclasses subclass)
(superclass-of  ?x subclass) (  get-class-superclasses superclass)
(superclass-of  superclass ?x) (  get-class-subclasses subclass)
Table: Semantics of ask in terms of GFP operations (assuming that the kb argument defaults to the value of (  current-kb), error-p defaults to false, and inference-level defaults to :direct)

 

The tell/ask operations are:   ask,   askable,   get-frame-sentences,   tell,   tellable,   untell

Operations on Behaviors

Behaviors are discussed in Chapter 4. GFP defines the following operations on behaviors:

  get-behavior-supported-values,   get-behavior-values,   get-kb-behaviors,   member-behavior-values-p,   put-behavior-values

Operations on Procedures

The GFP procedure language is defined in Chapter 5. GFP defines the following operations on procedures:

  call-procedure,   create-procedure,   get-procedure,   register-procedure,   unregister-procedure

Miscellaneous Operations

Miscellaneous operations that do not fall under the preceding categories include:   coerce-to-kb-value,   decontextualize,   eql-in-kb,   equal-in-kb,   equalp-in-kb,   frs-independent-frame-handle,   frs-name,   implement-with-kb-io-syntax,   value-as-string

Language Bindings

 

GFP has been designed to provide access to multiple FRS on multiple servers in multiple implementation languages. The GFP operations have been specified in a way that is programming language independent. To invoke or implement these operations in a specific programming language, we must establish a binding for the programming language. Each language binding establishes language specific conventions for naming, passing arguments, returning values, data structures, and handling exceptions.

This section briefly outlines the Lisp, C, and Java bindings for GFP operations. We present enough information for a developer working in one of these languages to correctly interpret the operation definitions in Section 3.7.

Lisp Binding

The naming and argument conventions provided in the specifications will be familiar to Common Lisp programmers. They can be used directly. All GFP operations are defined in the GFP package.

C Binding

Naming

Each GFP operation name is prefixed with `gfp_', and dashes are replaced by underscores. For example, the GFP operation   get-slot-values is called gfp_get_slot_values.

Arguments

The GFP operations are defined using mandatory positional and keyword arguments. The C programming language, however, does not provide named keyword arguments. Therefore, every argument specified for a GFP operation must be provided in the order that they appear in the operation's documentation. There is no special value to indicate that the default is to be used. All values must be explicitly provided.

Keywords

All keywords that appear in the GFP specification are defined as the values of global variables prefixed by `key_'. For example, the :all keyword is the value of key_all. Because C does not allow for dynamically allocated structures to be included in compiled code or header files, the function gfp_init must be called prior to referencing any keywords at runtime.

Data Structures

Every GFP object is implemented as a Gfp_Node struct.

Return Values

Each GFP operation returns a struct gfp_node * if it is single valued, a struct values * is returned if it is multi-valued, or void * if it returns no values.

C does not support multiple return values from functions. Operations returning multiple values return a pointer to a values struct. Functions on values include nth_value, first_value, and length.

Exceptions

Every GFP operation clears an error flag before executing, and sets it if an error occurs. It is the responsibility of the application to detect and handle errors. For the specific error flags, consult the header file for the C implementation.

Language Specific

Declarations and prototypes are defined in the file gfp.h. The function gfp_init must be called prior to executing any GFP operation or referencing any keyword at runtime.

Java Binding

Naming

Each GFP operation that takes a KB argument is defined as a method of the class GfpKb. Dashes are replaced by underscores, and the name is all in lower case. For example, get-slot-values would be called kb.get_slot_values(...), where kb is an instance of the class GfpKb.

Arguments

Java allows for arguments to be defaulted from right to left. The Java binding provides default values for the rightmost arguments that have simple defaults. Check the method definitions in the GfpKb class to verify argument defaulting.

Data structures

The Node class is the root class for all GFP objects. Subclasses of Node include Symbol, Kb, etc.

All methods implementing GFP operations return either a Node or a Values object or are void methods.

Return Values

Each GFP operation returns a Node object if it is single valued, a Values object if it is multi-valued, or void if it returns no values.

Java does not support multiple return values from methods. Operations returning multiple values return a Values object, which supports the methods nthValue, firstValue, and length.

Keywords

All keywords that appear in the GFP specification are defined as public static final members on the Node class. For example, the :all keyword is the value of Node._all.

Exceptions

Java has a full exception handling facility. All GFP conditions are implemented as Java conditions. The root of the condition graph is GfpCondition. The Java condition names are the same as GFP conditions, but the first character and the character following each dash is upper case and the dashes are removed. For example, the GFP condition constraint-violation is implemented by the Java condition class ConstraintViolation.

Listing of GFP Operations

  All GFP operations are defined here, and we list them in alphabetical order.

add-class-superclass     ( class new-superclass &key kb kb-local-only-p)
Return Value(s): void
Flags: O W
Adds the new-superclass to the superclasses of class. Returns no values.

add-facet-value     ( frame slot facet value &key kb (test :equal) (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
If the specified facet does not already contain value, then value is added to the set of values of the facet. Returns no values.
add-instance-type     ( frame new-type &key kb kb-local-only-p)
Return Value(s): void
Flags: O W
Adds the new-type to the types of frame. Returns no values.
add-slot-value     ( frame slot value &key kb (test :equal) (slot-type :own) (add-before 0) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
Value is added to the set of values of slot. If the collection-type of slot is :set, then value is added only if slot does not already contain value. Add-before, if supplied, should be false or a nonnegative integer. If the collection-type of slot is :list, value is added immediately before the value whose index is add-before. For example, if add-before is 1, the new value will be added between the first and second old values. If add-before is greater than or equal to the current number of slot values, or is false, and the collection-type of slot is :list, then value is added after all other values. This operation may signal constraint violation conditions (see Section 3.8). It is an error to provide a nonpositive integer as a value for add-before. Returns no values.
all-connections     ( )
Return Value(s): list-of-connections
Flags: E I R
Returns a list of all of the known connections.
allocate-frame-handle     ( frame-name frame-type &key kb frame-handle)
Return Value(s): frame-handle
Flags: M W
Allocates a frame handle in kb. It is not anticipated that this operation will be called by GFP applications, but rather by GFP back end implementations. This operation can be used in two distinct ways:
  1. Given a frame located in an arbitrary KB, typically different from kb, passing its frame-name, frame-type, and frame-handle will return a frame handle to represent that frame if such a frame were to be created in kb. This is useful in GFP operations such as   copy-frame and   copy-kb where it is often necessary to make forward references to frame objects.
  2. Providing just a frame-name and a frame-type will return a frame handle to represent that frame if such a frame were to be created in kb. This is useful when an implementation wants to allocate a frame handle either during the frame creation process, or to create forward references to frames when faulting them in from a lazy persistent store. Frame-name may be false.
Frame-type is the type of the frame as identified by the operation   get-frame-type; that is, it must be in the set {:class, :individual, :slot, :facet}.

The rationale for the arguments to this operation is as follows:

The contract of   allocate-frame-handle does not require the callee to return the same frame handle if called multiple times with identical arguments. Note that this is particularly important in case 2, above, with frame-name being false. It is the responsibility of the caller to remember the correspondence between its frames and the frame handles allocated. A frame handle allocated using   allocate-frame-handle can be used as the value of the handle argument to   create-frame,   create-class,   create-slot,   create-facet, and   create-individual. During the execution of these operations, it is the responsibility of the kb to preserve any necessary object identity so that, for example, 
   new-handle = allocate-frame-handle(name, :class, kb, handle);
   new-frame = create-class(name, .... :handle new-handle);
   new-handle == get-frame-handle(new-frame) // this identity must hold!
ask     ( query &key kb (reply-pattern query) (inference-level :taxonomic) (number-of-values :all) (error-p true) where timeout (value-selector :either) kb-local-only-p)
Return Value(s): reply-pattern-list exact-p more-status
Flags: E O R
Asks a query of the GFP kb. Query may be any sentence in the GFP Assertion Language that is   askable. A   cannot-handle error may be signaled if it is not askable. Reply-pattern is an expression mentioning KIF variables contained in query.

Reply-pattern is any list structure mentioning the variables in the query, or just the name of a variable. For example, consider a query that is a sentence of the form, 

     (subclass-of ?x ?y)
that is, find me the things that are subclasses of other things. If there is a match in the KB for ?x = human and ?y = animal. - the class human is a subclass of the class animal - then if the reply-pattern were to be 
     (superclass-of ?y ?x)
we would be returned a list of sentences of which one would be (superclass-of animal human). The explicit use of a reply pattern in this manner allows the user to get either sentences that can be conveniently reasserted using   tell, or tuples of matches in a shape that is convenient to the application.

When error-p is true, any errors resulting from the execution of the query are signaled. When error-p is false, all possible attempts are made to continue with the query and deliver as many results as were requested.

If the resources used by ask are a concern, the time (in seconds) allowed to answer a query will be limited, if possible, as specified by timeout. If the value of timeout is false, an unlimited time is allowed for ask to complete.

The where clause can be used to specify a list of bindings to be used for any variables appearing in the query. During query evaluation, such variables are replaced by the values specified by where. A valid value of where is a list of 2-tuples, with each tuple consisting of a variable and value pair.

Ask returns three values.

  1. reply-pattern-list - In this list, each element is an instance of reply-pattern, with all variables mentioned in query substituted.
  2. exact-p - This has its normal interpretation.
  3. more-status - This has its normal interpretation, except that an additional option :timeout may be returned for the more-status value by ask if the call terminates because execution time exceeds the limit specified by the timeout argument.
When ask is given a syntactically invalid query, it signals the   syntax-error error. When ask realizes that the query cannot be handled by the FRS, it signals a   cannot-handle error.

The following query matches four channel oscilloscopes with a bandwidth greater than 80MHz. It returns a list of pairs (?osc ?bandwidth) satisfying the query. 

   (ask '(and (oscilloscope ?osc)
              (number-of-channels ?osc ?chans)
              (= ?chans 4)
              (bandwidth ?osc ?bandwidth)
              (> ?bandwidth (* 80 mega-hertz)))
         :reply-pattern '(?osc ?bandwidth)
         :number-of-values 10 :kb kb)
All KIF operators in the query are parsed in a package-insensitive manner. For example, (and A B) and (:and A B) have the same effect. Object, relation, and function constant references in query are taken as arguments to   get-frames-matching. Frame references in the query must uniquely identify frames. (See   get-frames-matching.)
askable     ( sentence &key kb (value-selector :either) kb-local-only-p)
Return Value(s): boolean
Flags: O R
The askable operation returns false if the FRS can determine that asking the sentence would result in a   cannot-handle error being signaled, and true otherwise. It may also signal the   syntax-error condition. Even if askable returns true, ask may still not be able to handle the sentence.
attach-facet     ( frame slot facet &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: M W
Explicitly associates the facet with slot on frame, in the sense of recording that values of the facet may be asserted with frame or with instances of frame if slot-type is :template. As a result, facet is returned by   get-slot-facets at the :direct inference level, and slot-has-facet-p will be true for facet in slot on frame. It is an error to attempt to attach a non-existent facet. Doing so should signal a   facet-not-found error. Returns no values.
attach-slot     ( frame slot &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: M W
Explicitly associates the slot with frame, in the sense of recording that values of slot may be asserted with frame or with instances of frame if slot-type is :template. As a result, slot is returned by   get-frame-slots at the :direct inference level, and frame-has-slot-p will be true for slot on frame. It is an error to attempt to attach a non-existent slot. Doing so should signal a   slot-not-found error. Returns no values.
call-procedure     ( procedure &key kb arguments)
Return Value(s): value
Flags: E O R
Returns the value resulting from applying procedure to arguments. See section 5 for a definition of procedures.
class-p     ( thing &key kb kb-local-only-p)
Return Value(s): boolean
Flags: M R
Returns true if thing identifies a class.
close-connection     ( connection &key force-p (error-p true))
Return Value(s): void
Flags: O R
Closes the connection. If force-p is true, the connection may be closed without waiting for any handshakes from the server. A call to close-connection on the local connection is a no-op. This allows the user to loop through   all-connections, closing them all without fear of losing connectivity to KBs that share the same address space as the application. Returns no values.
close-kb     ( &key kb save-p)
Return Value(s): void
Flags: M W
Deletes any in-core/accessible representation of kb, but does not remove it from any persistent store if the persistent version still constitutes a meaningful KB (i.e., temporary disk work files would be deleted). It is an error ever to use kb again for any purpose. If this occurs, an   object-freed error should be signaled. Implementations may free any storage allocated for KB. If save-p is true, then any unsaved changes to kb will be saved before it is closed. Note that the default value of save-p is false. Returns no values.
coerce-to-class     ( thing &key kb (error-p true) kb-local-only-p)
Return Value(s): class class-found-p
Flags: O R
Coerces thing to a class. This operation returns two values. If error-p is true and the class is not found, then a   class-not-found error is signaled.

It is an error to call   coerce-to-class with error-p being true, and with a value of thing that does not uniquely identify a class. If this happens, a   not-unique-error error should be signaled.

Note that in some FRS, false may be a valid class. No portable program may assume that a returned value of false for the first (class) returned value implies that class-found-p is false.

coerce-to-facet     ( thing &key kb (error-p true) kb-local-only-p)
Return Value(s): facet facet-found-p
Flags: O R
Coerces thing to a facet. This operation returns two values. If error-p is true and the facet is not found, then a   slot-not-found error is signaled.

It is an error to call   coerce-to-facet with error-p being true, and with a value of thing that does not uniquely identify a facet. If this happens, a   not-unique-error error should be signaled.

Note that in some FRS, false may be a valid facet. No portable program may assume that a returned value of false for the first (facet) returned value implies that facet-found-p is false.

coerce-to-frame     ( thing &key kb (error-p true) kb-local-only-p)
Return Value(s): frame frame-found-p
Flags: M R
Coerces thing to be a frame object, if such an object exists for the underlying FRS, or a frame handle otherwise. Thing can be a frame object or a frame handle. This operation may be less careful than   get-frame-in-kb about ensuring that the frame for thing is actually in kb when the supplied thing is a frame object.   Coerce-to-frame verifies that thing is the appropriate type of frame object for kb, but may not actually determine whether the frame resides in kb. Therefore, this operation may be faster than   get-frame-in-kb for some FRSs.

For user convenience, implementors are encouraged to support the coercion into a frame of any data-structure that uniquely identifies a frame in the FRS as well as frame handles and frame objects. It is not portable to provide any value for thing other than a frame object or frame handle;   get-frames-matching should be used instead.

If the :frame-names-required behavior has the value true for kb, the names of frames are always coercible to frames. If the :frame-names-required behavior is false, frame names (if defined) are not guaranteed to be coercible to frames.

This operation returns two values.

If error-p is true and the frame is not found, then a   not-coercible-to-frame error is signaled.

It is an error to call   coerce-to-frame with error-p being true, and with a value of thing that does not uniquely identify a frame. If this happens, a   not-unique-error error should be signaled.

Note that in some FRS, false may be a valid frame object. No portable program may assume that a returned value of false for the first (frame) returned value implies that frame-found-p is false.

coerce-to-individual     ( thing &key kb (error-p true) kb-local-only-p)
Return Value(s): individual individual-found-p
Flags: O R
Coerces thing to an individual. This operation returns two values. If error-p is true and the individual is not found, then a   individual-not-found error is signaled.

It is an error to call   coerce-to-individual with error-p being true, and with a value of thing that does not uniquely identify an individual. If this happens, a   not-unique-error error should be signaled.

Note that in most FRS, false is a valid individual. No portable program may assume that a returned value of false for the first (individual) returned value implies that individual-found-p is false.

coerce-to-kb-value     ( string-or-value target-context &key kb wildcards-allowed-p force-case-insensitive-p (error-p true) (frame-action :error-if-not-unique) kb-local-only-p)
Return Value(s): result-of-read success-p completions-alist
Flags: O R
This operation is called by applications that receive input, often from a user in the form of typed input, or a value.   Coerce-to-kb-value takes this input and delivers a value that is meaningful to the FRS. This allows applications to interact with users and prompt for expressions containing frame references in a manner that will work predictably across implementation languages, and in networked implementations.   Coerce-to-kb-value implements GFP's reading model just as   value-as-string implements GFP's printing model.

string-or-value may be one of the following.

Given a string-or-value and a target-context, returns three values.

  1. result-of-read - the result of reading from the string or value, interpreting objects in the target-context for the kb
  2. success-p - false if an error occurred during the coercion, and true otherwise
  3. completions-alist - an association list of possible completions
The first value returned (result-of-read) will be an entity such as a string, number, symbol, list (possibly containing other such values), or frame.

Target-context is one of {:frame, :class, :slot, :individual, :facet, :value} and identifies the way in which the value to be extracted from string-or-value is to be interpreted.

The frame-action argument controls how the reading process interprets entities that can be interpreted as frames. The result-of-read value is false if an error occurs. The third value returned (completions-alist) is false if an error occurs, or otherwise is an association list of the form 
  ((<<string1>> <<substring1>> <<frame1>> <<frame2>>... <<frameN>>)
   (<<string2>> ....) ...)
where <<stringX>> are strings found in string-or-value that match the frames <<frame1>> ... <<frameN>> (possibly by using any specified wildcards), and <<substringX>> are the corresponding longest matching initial substrings for each <<stringX>> (see the specification of   get-frames-matching). For example, if in a KB there are frames called "FRED", "FREDDY", and "FRESH" and the call 
  (coerce-to-kb-value "fr*" :frame-action :options-if-not-unique)
is made, the values returned would be
  1. false -- The coercion could not complete because of the ambiguity.
  2. true -- The operation completed without error.
  3. (("FR*" "FRE" FRED FREDDY FRESH)) -- Only one ambiguous reference was found, and for that the longest matching substring for the pattern "FR*" is "FRE", and the matching frames are {FRED, FREDDY, FRESH}.
See also   get-frames-matching, which is called to identify frames.
coerce-to-slot     ( thing &key kb (error-p true) kb-local-only-p)
Return Value(s): slot slot-found-p
Flags: O R
Coerces thing to a slot. This operation returns two values. If error-p is true and the slot is not found, then a   slot-not-found error is signaled.

It is an error to call   coerce-to-slot with error-p being true, and with a value of thing that does not uniquely identify a slot. If this happens, a   not-unique-error error should be signaled.

Note that in some FRS, false may be a valid slot. No portable program may assume that a returned value of false for the first (slot) returned value implies that slot-found-p is false.

coercible-to-frame-p     ( thing &key kb kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true when thing can be coerced to a frame by using   coerce-to-frame, and otherwise returns false.
connection-p   ( thing)
Return Value(s): boolean
Flags: R   
Is true if thing is a connection, and false otherwise.
continuable-error-p   ( thing)
Return Value(s): boolean
Flags: R   
Returns true if thing is a continuable error, and false\ otherwise. An error is said to be continuable only if the state of the KB is known not to have been damaged by the error in such a way that the behavior of subsequent GFP operations becomes undefined. Thus, although the signalling of a continuable error will interrupt any processing currently being performed, subsequent GFP calls will be well defined. After a noncontinuable error, the state of the KB and the behavior of the FRS and application are undefined.
copy-frame     ( frame new-name &key kb (to-kb (current-kb)) (error-p true) (missing-frame-action :stop) frame-handle-mapping-table kb-local-only-p)
Return Value(s): copy-of-frame allocated-frame-handle-alist
Flags: O W
Copies frame from kb to to-kb. The name of the new frame in to-kb will be new-name. Kb and to-kb may be the same KB. If the :frame-names-required behavior has the value false for kb, new-name may be false.

If error-p is false, catches errors that occur, and continues copying to the extent possible.

The frame may contain references to other frames that do not reside in to-kb - for example, its types, superclasses, or slot values. Missing-frame-action controls the behavior of   copy-frame in this case. It can take one of the following values:

:stop - Stop copying and signal a   frames-missing error, depending on the value of error-p.

:abort - Abort copying frame, leaving the state of to-kb unchanged. Any side effects of   copy-frame that have already been performed will be undone. Signals a   frames-missing error, depending on the value of error-p.

:allocate - Allocate frame handles for any frame references that do not yet exist in to-kb.

:ignore - Continue with the copying of the current frame, but ignore and remove any references to missing frames.

Frame-handle-mapping-table, if supplied, is a hash table that maps the frame handles in the kb to frame handles in to-kb, and is used during compound copy operations, such as   copy-kb. If copy-frame fails to find a referenced frame in to-kb, it looks up the reference in the Frame-handle-mapping-table before allocating a new frame handle.

It returns two values.

  1. Copy-of-frame - Identifies the newly created frame in to-kb. If copy-frame terminates because some frames were missing, and missing-frame-action was :abort, false is returned as a value of copy-of-frame.
  2. Allocated-frame-handle-alist - a list of 2-tuples
    (frame-handle-in-kb frame-handle-in-to-kb) that maps frame handles in kb to frame handles in to-kb that were allocated during the copying process. These mappings will also have been entered in frame-handle-mapping-table if it was supplied.
copy-kb     ( from-kb to-kb &key (error-p true) (missing-frame-action :stop) kb-local-only-p)
Return Value(s): void
Flags: O W
Copies the frames in from-kb into to-kb. The interpretation of Missing-frame-action is the same as for   copy-frame. If error-p is false, catches errors that occur, and attempts to continue with copying. Returns no values.

Note that the behavior are-frames might have different values for the two KBs. Thus, if slots are represented as frames in kb, but are not represented as frames in to-kb, the frames representing slots in kb will not be copied.

create-class     ( name &key kb direct-types direct-superclasses (primitive-p true) doc template-slots template-facets own-slots own-facets handle pretty-name kb-local-only-p)
Return Value(s): new-class
Flags: M W
Creates a class called name as a direct subclass of the list of classes (or class) direct-superclasses. For FRSs that support the distinction between primitive and nonprimitive concepts, primitive-p specifies the primitiveness of the created class. The parameters doc, template-slots, template-facets, own-slots, own-facets, direct-types, handle, and pretty-name have the same meaning as for   create-frame. For FRSs that support metaclasses, the direct-types argument specifies the type(s) of the class to be created (i.e., metaclasses). Returns the new-class.
create-facet     ( name &key kb frame slot (slot-type :own) direct-types doc own-slots own-facets handle pretty-name kb-local-only-p)
Return Value(s): new-facet
Flags: M W
Creates a facet called name on slot that is associated with frame. If frame is false, the facet's frame domain is unconstrained (i.e., the facet may apply to slot in any frame).

If slot is false, the slot domain of the facet is unconstrained (i.e., the facet may apply to all slots in frame, and if frame is also false, may apply to all slots in all frames.) If :facet is a member of the behavior values for the :are-frames behavior, direct-types, doc, own-slots, own-facets, handle and pretty-name have the same interpretation as for   create-frame. If either frame or slot is false, slot-type is ignored. If either of the frame or slot arguments is false, and the FRS does not support facets with unconstrained domains, a   domain-required error will be signaled. Returns the new-facet.

create-frame     ( name frame-type &key kb direct-types direct-superclasses doc template-slots template-facets own-slots own-facets (primitive-p true) handle pretty-name kb-local-only-p)
Return Value(s): new-frame
Flags: O W
Creates a new frame called name of type frame-type. Frame-type is one of {:class, :slot, :facet, :individual}. A call to create-frame is equivalent to a call to one of   create-class,   create-individual,   create-slot, or   create-facet passing through the appropriate arguments, depending on the value of frame-type. If frame-type is either :slot or :facet, the slot (or facet) created will have unconstrained domains.

If the :frame-names-required behavior has the value false for kb, new-name may be false. If the :frame-names-required behavior is true for kb, new-name must uniquely name the new frame, and a   frame-already-exists error will be signaled if new-name is coercible to an existing frame.

Direct-types is a list of classes (or class) of which this new frame is to be a direct instance. Direct-superclasses is a list of classes (or class) of which the new frame is to be a direct subclass. Doc, if specified, is a string documenting the new frame. Pretty-name is the pretty-name of the new frame. Returns new-frame, which identifies the newly created frame.

Template-slots and own-slots each take a list of slot specifications. A slot specification assigns a set of values to a slot. The syntax of a slot specification is 

	slot-spec ::= (slot slot-value-spec*)
	slot-value-spec ::= default-slot-value | slot-value
	default-slot-value ::= (:default slot-value)
where slot identifies a slot, or names a slot to be created. If slot already exists, it is simply attached to the new frame, if it does not currently exist, it is created and attached to the new frame. Each slot-value is an entity suitable as a value of the specified slot. Default slot values are identified by appearing in a list whose first element is :default. Template slots are only allowed for class frames - that is, when frame-type is :class.

Template-facets and own-facets each take a list of facet specifications, which can assign a set of facet values. A facet specification has the form: 

	facet-spec ::= (slot fspec*)
	fspec ::= (facet facet-value-spec*)
	facet-value-spec ::= default-facet-value | facet-value
	default-facet-value ::= (:default facet-value)
where slot identifies a slot, or names a slot to be created. If slot already exists, it is simply attached to the new frame, if it does not currently exist, it is created and attached to the new frame. Facet identifies a facet, or names a facet to be created. If facet already exists, it is simply attached to slot on the new frame, if it does not currently exist, it is created and attached to slot on the new frame. Each facet-value is an object suitable as a value of the specified facet. Default facet values are identified by appearing in a list whose first element is :default. Template facets are allowed only for class frames - that is, when frame-type is :class.

Primitive-p may be used only when creating a class. When primitive-p is false, the FRS will make the class nonprimitive, if possible.

Handle, if supplied, is a previously allocated frame handle for the new frame to be created. This is used by network applications, and operations such as   copy-frame and   copy-kb. (See   allocate-frame-handle.) It is an error to supply a value for the handle argument that is already coercible to a frame. If this occurs, a   frame-already-exists error should be signaled.

Note that if frame-type is either :slot or :facet, then a frame might not be created because slots (or facets) might not be represented as frames in kb. If this is the case, and slots (or facets) with unconstrained domains are not supported, a   domain-required error will be signaled.

It is an error to supply own-slots, own-facets if a frame will not be created, according to the :are-frames behavior, and a   not-a-frame-type error should be signaled.

create-individual     ( name &key kb direct-types doc own-slots own-facets handle pretty-name kb-local-only-p)
Return Value(s): new-individual
Flags: M W
Creates an individual called name. The one or more classes that are the direct types of the instance are given by direct-types. The parameters doc, own-slots, own-facets, handle, and pretty-name all have the same meaning as for   create-frame. Returns new-individual, which identifies the new frame.
create-kb     ( name &key kb-type kb-locator initargs (connection (local-connection)))
Return Value(s): new-kb
Flags: O W
Creates a new KB (see Section 2.9) called name whose implementation type is kb-type. Kb-type identifies the underlying FRS that will be used to manipulate the KB. Returns the new-kb.

Note that this operation creates a new in-memory KB; it does not necessarily create a persistent version of the knowledge base on external storage until   save-kb or   save-kb-as is called.

kb-locator, if supplied, describes the new KB. Kb-locators can be created using   create-kb-locator. If kb-locator is not supplied, a default kb-locator will be assigned by the FRS for kb-type and connection.

Initargs is a list of initializations for the new KB as required by the kb-type. The mechanism underlying the implementation of   create-kb is not specified and the user cannot, therefore, rely on any underlying native object system initialization protocol being invoked. The format and content of the initialization arguments will be documented with the kb-type. For example, if the KB being created allows the specification of parent (included) KBs, a set of initialization arguments might be as follows: 

     (list :parent-kbs (list my-kb))
Any KB created with   create-kb can be found by using either   find-kb or   find-kb-of-type, and it is included in the values returned by   get-kbs. A KB created with   create-kb is a frame object in the   meta-kb.

Implementation note: It is the responsibility of the implementations of   create-kb to register new KBs in the Meta KB (for example, by using   put-instance-types to tell the Meta KB that the new KB is an instance of kb-type.

create-kb-locator     ( thing &key kb-type)
Return Value(s): kb-locator
Flags: M R
Returns a new kb-locator associated with thing for a kb of type kb-type. If thing is a KB, the kb-locator created is associated with that KB in the   meta-kb. It is an error for thing to be an incomplete description of a kb-locator.
create-procedure     ( &key kb arguments body environment)
Return Value(s): procedure
Flags: O R
Defines a procedure called name. The arguments are defined as follows: A procedure is a legal argument to any GFP operator in a position that expects a procedure. For example, 
    (call-procedure
      #'(lambda (frame) (get-frame-pretty-name frame :kb kb))
      :kb kb :arguments (list my-frame))
and 
    (call-procedure
      (create-procedure :arguments '(frame)
                        :body '(get-frame-pretty-name frame :kb kb))
      :kb my-kb :arguments (list my-frame))
are semantically identical.

The main differences between procedures and lambda expressions in Lisp are as follows:

  1. All bindings in procedures are dynamic, not lexical.
  2. Only a restricted set of operations is available in procedures.
  3. Lambda defines a lexical closure over any free references. procedure defines a dynamic closure over its free references. The environment of the procedure is prefilled with bindings for the names of the arguments to the GFP operator in which it is being executed. In the above case, call-procedure takes arguments KB, Arguments, and Kb-local-only-p which will take on the values my-kb, (my-frame), and nil (the default), respectively.
  4. Lambda expressions are meaningful only within the Lisp system in which the GFP system is running. procedures are executable on any (possibly network-connected) GFP KB.
  5. procedures are package-insensitive in all respects other than quoted constants.

Note that persistent side effects to <<var1>> and <<var2>> cannot be made from within the procedure. The arguments and variables mentioned in the procedure exist in a different space from the variables in a user program. The only ways to establish associations between values in a user program and variables in a procedure are through the use of the environment argument to   create-procedure, or by the arguments argument to   call-procedure.

create-slot     ( name &key kb frame (slot-type :own) direct-types doc own-slots own-facets handle pretty-name kb-local-only-p)
Return Value(s): new-slot
Flags: M W
Creates a slot called name in the frame specified by frame. Returns the new-slot. If the slot to be created is to be represented as a frame (:slot is a member of the :are-frames behavior), direct-types, doc, own-slots, own-facets, handle, and pretty-name have the same interpretation as for   create-frame. If frame is false, slot-type is ignored, and the slot's domain is ignored. If the frame argument is false, and the FRS does not support slots with unconstrained domains, a   domain-required error will be signaled.
current-kb   ( )
Return Value(s): kb
Flags: R   
Returns the current KB. The current KB is set using   goto-kb.
decontextualize     ( value from-context &key kb)
Return Value(s): decontextualized-value
Flags: M R
Given a value from kb, returns a decontextualized-value, which contains no KB or FRS-specific data structures. In particular, any references to frame objects will be replaced with FRS-independent frame handles (produced using frs-independent-frame-handle), and all values outside the standard set of GFP data types that have no interpretation outside kb will be replaced with remote-value references. Any frame references that are the result of an FRS-specific mapping of a canonically named frame will be replaced with the canonical name. Thus, for example, a facet frame called cardinality-of-slot would be mapped back to a frame handle for the canonical facet-reference :cardinality.

From-context is one of {:frame, :slot, :facet, :value}. It identifies the context of the argument to be decontextualized. For example, if the decontextualization is to be applied to a slot value, then from-context should be :value. If the decontextualization is to be applied to a slot (i.e., something that would be used as a slot argument to an operation such as   get-slot-values), then from-context should be :slot.

It is not anticipated that this operation will be called by GFP applications, but rather by GFP back end implementations. It is used to ensure correct operation in networked applications and during communication between KBs of different kb-types.

delete-facet     ( facet &key kb kb-local-only-p)
Return Value(s): void
Flags: M W
Deletes the facet from all frames containing that facet, and the facet frame itself if the facet is represented as a frame. As a result of   delete-facet, facet will return false for calls to   facet-p, and facet is not returned by any of the facet-returning operations, such as   get-kb-facets and   get-slot-facets. It is no longer possible to access any values of facet. Returns no values.
delete-frame     ( frame &key kb kb-local-only-p)
Return Value(s): void
Flags: M W
Deleting a frame from a KB is difficult to specify in a portable way. After calling   delete-frame, the frame argument will no longer be a valid frame reference (frame-p will return false). As a consequence, the value of frame will not be a valid argument to any GFP operation requiring a frame reference, such as   get-frame-slots. It will no longer be possible to access any of the properties (e.g., slots, facets) of frame. Implementations will delete at least the properties documented as being returned by   get-frame-details from the kb.

Note that after a call to   delete-frame, references to frame may still remain in the KB. Returns no values.

delete-slot     ( slot &key kb kb-local-only-p)
Return Value(s): void
Flags: M W
Deletes the slot from all frames containing that slot, and the slot frame itself if the slot is represented as a frame. As a result of   delete-slot, slot will return false for calls to   slot-p, and slot is not returned by any of the slot-returning operations, such as   get-kb-slots and   get-frame-slots. It is no longer possible to access any values of slot or any facets or facet values on slot. Returns no values.
detach-facet     ( frame slot facet &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: M W
Removes any explicit association between the facet and slot on frame. As a result, facet is not returned by   get-slot-facets at inference-level :direct unless there are facet values associated with facet in slot on frame.
detach-slot     ( frame slot &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: M W
Removes any explicit association between the slot and frame. As a result, slot is not returned by   get-frame-slots at inference-level :direct unless there are slot or facet values associated with slot in frame.
enumerate-all-connections     ( )
Return Value(s): enumerator
Flags: I R
Returns an enumerator for the elements returned by   all-connections.
enumerate-ask     ( query &key kb (reply-pattern query) (inference-level :taxonomic) (number-of-values :all) (error-p true) where timeout (value-selector :either) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   ask.
enumerate-call-procedure     ( procedure &key kb arguments)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   call-procedure.
enumerate-class-instances     ( class &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-class-instances.
enumerate-class-subclasses     ( class &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-class-subclasses.
enumerate-class-superclasses     ( class &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-class-superclasses.
enumerate-facet-values     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-facet-values.
enumerate-facet-values-in-detail     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-facet-values-in-detail.
enumerate-frame-slots     ( frame &key kb (inference-level :taxonomic) (slot-type :all) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-frame-slots.
enumerate-frames-matching     ( pattern &key kb (wildcards-allowed-p true) (selector :all) force-case-insensitive-p kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-frames-matching.
enumerate-instance-types     ( frame &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-instance-types.
enumerate-kb-classes     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-classes.
enumerate-kb-direct-children     ( &key kb)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-direct-children.
enumerate-kb-direct-parents     ( &key kb)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-direct-parents.
enumerate-kb-facets     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-facets.
enumerate-kb-frames     ( &key kb kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-frames.
enumerate-kb-individuals     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-individuals.
enumerate-kb-roots     ( &key kb (selector :all) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-roots.
enumerate-kb-slots     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-slots.
enumerate-kb-types     ( &key (connection (local-connection)))
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kb-types.
enumerate-kbs     ( &key (connection (local-connection)))
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kbs.
enumerate-kbs-of-type     ( &key kb-type (connection (local-connection)))
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-kbs-of-type.
enumerate-list     ( list)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements of the list.
enumerate-slot-facets     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-slot-facets.
enumerate-slot-values     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-slot-values.
enumerate-slot-values-in-detail     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): enumerator
Flags: O R
Returns an enumerator for the elements returned by   get-slot-values-in-detail.
eql-in-kb     ( arg0 arg1 &key kb kb-local-only-p)
Return Value(s): boolean
Flags: M R
Returns true iff arg0 and arg1 identify the same frame in kb, or are the same object (==, EQLness), and otherwise returns false. Arg0 and arg1 may be any combination of objects coercible to frames.
equal-in-kb     ( arg0 arg1 &key kb kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true iff arg0 and arg1 identify the same frame in kb, or are the same object (==, EQLness), or they are strings containing the same characters (case sensitively), or both are lists with the same structure, and each of the elements recursively is true according to   equal-in-kb. Returns false\ otherwise.
equalp-in-kb     ( arg0 arg1 &key kb kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true iff arg0 and arg1 identify the same frame in kb, or are the same object (==, EQLness), or they are strings containing the same characters (case-insensitively), or both are lists with the same structure, and each of the elements recursively is true according to   equalp-in-kb. Returns false otherwise.
establish-connection     ( connection-type &key initargs)
Return Value(s): connection
Flags: O R
Establishes and returns a connection of type connection-type. Initargs are initialization arguments for the connection if one is created, are used to initialize the connection in a manner specific to the connection type, and are documented with the definition of the connection type itself. No guarantee is made that the connection will be newly created. An existing, open connection with the same initializations may be returned.

For example, to initialize some form of network connection, the value of initargs might be a property list of the form (:host "my-host" :port 1234 :username "joe").

Although the format of initargs is implementation-specific, GFP nevertheless mandates a set of standard names for commonly used initializations.

HOST
- A string naming the host on which the server is to be found
PORT
- An integer indicating a TCP/IP port on which the server is to be found
USERNAME
- A string for the login name of the user on the GFP server
PASSWORD
- The password of the user on the server

Establishing a local connection requires no initialization arguments and can be done more conveniently using   local-connection.

expunge-kb     ( &key kb (error-p true))
Return Value(s): void
Flags: M W
Given a KB, removes it and any backup copies of it from permanent storage, and then   close-kb. Returns no values. As with   close-kb, it is an error ever to use kb again, and attempted references to kb should signal an   object-freed error. If error-p is false,   expunge-kb catches errors that occur, and attempts to continue with the deletion.
facet-has-value-p     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true iff the specified facet has a value for the specified slot and frame, and otherwise returns false.
facet-p     ( thing &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): boolean
Flags: M R
Returns true iff thing is a facet, and false otherwise.
fetch     ( enumerator &key (number-of-values :all))
Return Value(s): list-of-values
Flags: O R
Returns a list-of-values of at most number-of-values values remaining in the enumerator. If the enumerator was exhausted before the call, an   enumerator-exhausted error will be signaled. Note that unlike other operations taking a number-of-values argument, this operation does not return a more-status value.
find-kb     ( name-or-kb-or-kb-locator)
Return Value(s): kb-or-false
Flags: O R
Returns the first KB that can be found matching name-or-kb-or-kb-locator. If the argument is a KB, that KB is returned. If no matching KB can be found, kb-or-false is false.
find-kb-locator     ( thing &key kb-type)
Return Value(s): kb-locator
Flags: M R
Returns the kb-locator associated with thing if such a kb-locator exists for a KB of type kb-type, and false\ otherwise.

Always returns a kb-locator if thing is a KB. Implementations are encouraged to accept other values for thing such as a pathname that identifies the location of the KB to the system. Such usage is convenient, but is not portable. It is not portable for a GFP application to use anything other than a KB descriptor, or a KB for this argument.

find-kb-of-type     ( name-or-kb &key kb-type (connection (local-connection)))
Return Value(s): kb-or-false
Flags: O R
If name-or-kb is the name of a KB of type kb-type (or a subtype of kb-type) that is currently known to the system through the connection,   find-kb-of-type returns the KB. If no such KB can be found, kb-or-false is false.
follow-slot-chain     ( frame slot-chain &key kb (union-multiple-values true) (inference-level :taxonomic) (value-selector :either) kb-local-only-p)
Return Value(s): values
Flags: O R
Allows a program to traverse a chain of slot references, gathering own slot values. For example, imagine that we wish to determine the sisters of the father of the mother of John. The following two calls accomplish this goal: 
   (follow-slot-chain 'john '(mother father sisters))
	
   (get-slot-values
      (get-slot-value
        (get-slot-value 'john 'mother)
        'father)
      'sisters)
This operation is complicated by the fact that slots can have multiple values. For example, imagine that John has two mothers--adopted and biological. If union-multiple-values is false and a slot has more than one value, a   cardinality-violation error is signaled; if true, then the slot chain becomes a tree, and the union of all values found at the leaves of the tree is returned.
frame-has-slot-p     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true iff thing is a slot in frame, otherwise returns false.
frame-in-kb-p     ( thing &key kb kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true when thing is both coercible to a frame, and that frame is known to be resident in kb, and otherwise returns false. See   get-frame-in-kb.
free     ( enumerator)
Return Value(s): void
Flags: O R
Indicates that the enumerator will no longer be used. The enumerator and any cache of unseen values may be thrown away. After calling   free, it is an error to provide enumerator as an argument to any operation, and if this is done, an   object-freed error should be signaled. It is especially important to call   free in a network setting when a program has finished with the enumerator and its values have not been exhausted, so that the server can reclaim space allocated to the enumerator. Returns no values.
frs-independent-frame-handle     ( frame &key kb kb-local-only-p)
Return Value(s): frame-handle
Flags: O R
Given a frame, returns frame-handle, which is an FRS-independent GFP frame handle object. Frame-handle may now be used in network applications to refer to frame or in communication between KBs. The correspondence between frame and frame-handle is maintained, so that subsequent calls with the same frame will return the same frame-handle.

It is not anticipated that this operation will ever be called by user applications, but must be used by back ends to implement   decontextualize.

frs-name     ( &key kb-type (connection (local-connection)))
Return Value(s): frs-name
Flags: O R
Returns the frs-name of the underlying FRS associated with the kb-type, which is accessed over connection. Frs-name is a string. For example, given loom-kb as the kb-type, it might return the string "LOOM". This operation is used by user interfaces that need to display a printed representation of the underlying FRS for a particular kb-type.
get-behavior-supported-values     ( behavior &key kb)
Return Value(s): behavior-values
Flags: M R
Returns a list of the supported values of the behavior the KB is capable of supporting. For example, the KB might support both the :immediate and :never variants of the behavior :constraint-checking-time. These two options would be returned as a list. The returned value behavior-values is always a list, even when no variants are supported - that is, it is ().
get-behavior-values     ( behavior &key kb)
Return Value(s): behavior-values
Flags: M R
Returns a list of active values of the behavior under which the KB is currently operating. For example, the KB might support both the :immediate and :never variants of the behavior :constraint-checking-time, but only one of these modes can be enabled at a given time. A list containing, for example, just :never would be returned. The returned value behavior-values is always a list, even when no variants are active - that is, it is the ().
get-class-instances     ( class &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): list-of-instances exact-p more-status
Flags: E M R
Returns a list-of-instances for class.
get-class-subclasses     ( class &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): list-of-subclasses exact-p more-status
Flags: E M R
Returns the list-of-subclasses of class.
get-class-superclasses     ( class &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): list-of-superclasses exact-p more-status
Flags: E M R
Returns the list-of-superclasses of class.
get-facet-value     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): value-or-false exact-p
Flags: O R
Returns the sole member of the set of values of the specified facet. It is most commonly used when that set is expected to have only one member. When the facet has no value, value-or-false is false. It is an error to call this operation on a non-single-valued facet; if it is called, a   cardinality-violation error should be signaled.
get-facet-values     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): values exact-p more-status
Flags: E O R
Returns the set of values of the specified facet, in no guaranteed order. It always returns a (possibly empty) list of values.
get-facet-values-in-detail     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): list-of-specs exact-p more-status default-p
Flags: E M R
Returns the list-of-specs describing the values of the facet of slot within frame, in no guaranteed order. It always returns a list of specifications as values. If the specified slot has no values, () is returned.

Each spec is a 3-tuple of the form (value direct-p default-p).

The fourth returned value (default-p) is true if the list-of-specs is (), and the fact that there are no values is itself a default.
get-frame-details     ( frame &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): details exact-p
Flags: O R
Returns a property list (list of alternating keywords and values) describing the frame. The properties of the frame are computed using the inference-level, number-of-values-p, and kb-local-only-p arguments, whenever applicable to the appropriate GFP operator used to compute any given property. The set of properties computed is at least the following:

Property Operation(s) used to compute property
:handle   get-frame-handle
:name   get-frame-name
:pretty-name   get-frame-pretty-name
:frame-type   get-frame-type
:primitive-p   primitive-p
:superclasses   get-class-superclasses
:subclasses   get-class-subclasses
:types   get-instance-types
:own-slots   get-frame-slots,   get-slot-values
:template-slots   get-frame-slots,   get-slot-values
:own-facets   get-frame-slots,   get-slot-values,   get-slot-facets,   get-facet-values
:template-facets   get-frame-slots,   get-slot-values,   get-slot-facets,   get-facet-values

The :own-slots, :own-facets, :template-slots, and :template-facets properties returned are slot and facet specifications as defined for   create-frame. This operation is most useful in low-bandwidth or high-latency applications. A single call to   get-frame-details is often sufficient to display all the interesting features of a frame.

get-frame-handle     ( frame &key kb kb-local-only-p)
Return Value(s): frame-handle
Flags: O R
Returns a frame-handle that uniquely identifies the frame argument in kb.
get-frame-in-kb     ( thing &key kb (error-p true) kb-local-only-p)
Return Value(s): frame frame-found-p
Flags: M R
Returns two values. The first value is the frame identified by thing if such a frame is found, or false. The second value (frame-found-p) is true iff thing is coercible to a frame, and that frame is resident in KB. In all cases it is verified that the frame does, in fact, reside in kb. Otherwise, the frame-found-p value is nil (unless error-p is true, in which case the operation signals a   not-coercible-to-frame error because thing is not a valid frame in kb).
get-frame-name     ( frame &key kb kb-local-only-p)
Return Value(s): frame-name
Flags: M R
Returns frame-name, an entity that is the name of the frame identified by frame, usually a symbol or string.
get-frame-pretty-name     ( frame &key kb kb-local-only-p)
Return Value(s): string
Flags: M R
Returns a string that is a pretty, printed representation for frame - that is, the name is suitable for use within a user interface for display purposes.

There is no guarantee that it will be possible to find a unique frame given only its pretty-name, but   get-frames-matching can be used to find frames matching such strings when possible.

get-frame-sentences     ( frame &key kb (number-of-values :all) (gfp-sentences-p true) (value-selector :either) kb-local-only-p)
Return Value(s): list-of-sentences exact-p more-status
Flags: M R
Returns a list of all the logical sentences associated with a frame. The sentences may have been asserted using tell, or any other GFP update operation. If gfp-sentences-p is true, then all sentences are returned, including the ones that are equivalent to basic GFP operations. The sentences equivalent to GFP operations are defined in Table 3.3. If gfp-sentences-p is false, sentences that are equivalent to GFP operations are not returned. This is very useful for user interface applications that do not want to present redundant information. If no matching sentences are found, list-of-sentences will be ().
get-frame-slots     ( frame &key kb (inference-level :taxonomic) (slot-type :all) kb-local-only-p)
Return Value(s): list-of-slots exact-p
Flags: E M R
Returns list-of-slots, a list of all the own, template, or own and template slots that are associated with frame, depending on the value of slot-type.
get-frame-type     ( thing &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): frame-type
Flags: O R
When thing identifies a frame, returns either :slot, :facet, :class, or :individual, depending on the type of the frame. When thing does not identify a frame, frame-type is false. :Slot and :facet will be returned only in those systems that support the values :slot and :facet, respectively, for the :are-frames behavior.
get-frames-matching     ( pattern &key kb (wildcards-allowed-p true) (selector :all) force-case-insensitive-p kb-local-only-p)
Return Value(s): matching-frames longest-matching-substring
Flags: E O R
Given a pattern, finds a set of matching frames. The match of a frame to a pattern could take into account the frame's name (if meaningful), printed representation, pretty-name, or any KB-specific feature such as a list of synonyms.

Returns the following two values:

  1. matching-frames - The list of matching frames (which is () if no matches are found).
  2. longest-matching-substring - The longest matching initial substring. This returned value is useful in applications that use get-frames-matching to implement a completion facility, or prompt users for frames (false if no matches are found).
Wildcards-allowed-p -- When true, the pattern may contain * (zero or more characters) and ? (exactly one character) wildcards. Wildcard characters are escaped with the backslash character. If this argument is false, the * and ? characters simply denote themselves and need not be escaped.\ Selector -- May be a procedure (see Section 5) of signature (candidate-name, kb, kb-local-only-p) that returns true if the candidate name is to be accepted and false otherwise, or one of the following keywords: Force-Case-Insensitive-P -- When true, cause the comparison is to be case-insensitive, irrespective of the IO syntax of the KB.
get-frames-with-facet-value     ( slot facet value &key kb (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): frames exact-p
Flags: O R
Returns the set of frames in which the specified facet value is accessible on the specified slot. If the system is unable to find any frame/slot/facet combinations with the specified value, () is returned. This operation allows user interfaces to take users from a value displayed as a facet value on a particular frame/slot to the place that asserted the value.
get-frames-with-slot-value     ( slot value &key kb (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): frames exact-p
Flags: O R
Returns the set of frames in which the specified slot value is accessible. If the system is unable to find any frame/slot combinations with the specified value, () is returned. This operation allows user interfaces to take users from a value displayed as a slot value on a particular frame to the place that asserted the value.
get-instance-types     ( frame &key kb (inference-level :taxonomic) (number-of-values :all) kb-local-only-p)
Return Value(s): list-of-types exact-p more-status
Flags: E M R
Returns the list-of-types of frame, that is, the list of classes of which frame is an instance.
get-kb-behaviors     ( &key (kb-type-or-kb (current-kb)) (connection (connection-arg-default kb-type-or-kb)))
Return Value(s): list-of-behaviors
Flags: M R
When kb-type-or-kb is either a KB or a kb-type, returns list-of-behaviors, which is a list of keywords naming all the behaviors recognized by this KB, or identified by the kb-type, respectively.
get-kb-classes     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): list-of-classes
Flags: E O R
Returns list-of-classes, a list of the classes in the KB. Selector can be one of the following:
get-kb-direct-children     ( &key kb)
Return Value(s): list-of-child-kbs
Flags: E O R
Returns the list-of-child-kbs - that is, the list of KBs that directly include kb. Note that certain KB implementations may allow circular inclusion dependencies in KBs. The semantics of KB inclusion are not specified by GFP, but where possible, processing can be limited to a particular KB by the use of the kb-local-only-p argument.
get-kb-direct-parents     ( &key kb)
Return Value(s): list-of-parent-kbs
Flags: E O R
Returns the list-of-parent-kbs - that is, the list of KBs directly included by kb. Note that certain KB implementations may allow circular inclusion dependencies in KBs. The semantics of KB inclusion are not specified by GFP, but where possible, processing can be limited to a particular KB by the use of the kb-local-only-p argument.
get-kb-facets     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): list-of-facets
Flags: E O R
Returns the list-of-facets in kb. Selector can be one of the following:
get-kb-frames     ( &key kb kb-local-only-p)
Return Value(s): list-of-frames
Flags: E M R
Returns the list-of-frames in the KB, including class, slot, facets and individual frames, when present.
get-kb-individuals     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): list-of-individuals
Flags: E O R
Returns list-of-individuals, a list of the individual frames in kb. Selector can be one of the following:
get-kb-roots     ( &key kb (selector :all) kb-local-only-p)
Return Value(s): list-of-roots
Flags: E O R
Every KB has one or more frames at the top (root) of the class hierarchy. A class C is a root of the KB K if there exists no class D such that D is a superclass of C and D is in the KB K, or available in K when kb-local-only-p is false. This operation identifies and returns those classes, the list-of-roots.

Some FRSs allow user-defined classes to be roots of a KB, whereas other FRSs always import certain system-defined classes (for example, thing) into each KB and force all user classes to be subclasses of thing. These system-defined classes may normally be invisible to the user in some FRSs. The selector argument controls which root classes are returned as follows:

If kb-local-only-p is true, the list returned may return only the root classes defined in kb itself; classes that were inherited from other (included) KBs may be excluded. This means that a class that has superclasses in some KB included by kb, but has no superclasses defined in kb, may be returned as a root class if kb-local-only-p is true.

get-kb-slots     ( &key kb (selector :system-default) kb-local-only-p)
Return Value(s): list-of-slots
Flags: E O R
Returns the list-of-slots that are defined in the KB. Selector can be one of the following:
get-kb-type   ( thing)
Return Value(s): kb-type
Flags: R   
Returns the kb-type object for thing, which may be a KB, a kb-locator, or a kb-type name. KB-type names are FRS-specific, and will be documented with the FRS being used. KB-type names need never be used, since a kb-type can be selected by a user or application by using the   get-kb-types and   frs-name operations. It is not portable to specify a kb-type name as a literal in a GFP program.
get-kb-types     ( &key (connection (local-connection)))
Return Value(s): list-of-kb-types
Flags: E O R
Returns a list of KB types for each of the known FRSs accessible through the connection. List-of-kb-types contains one kb-type entry for each FRS known through the connection, and possibly also kb-type objects representing supertypes of the FRSs supported.
get-kbs     ( &key (connection (local-connection)))
Return Value(s): list-of-kbs
Flags: E O R
Returns a list-of-kbs containing all the known KBs accessible through the connection, irrespective of the KB's implementation type.
get-kbs-of-type     ( &key kb-type (connection (local-connection)))
Return Value(s): list-of-kbs
Flags: E M R
Returns list-of-kbs, the list of all the known KBs whose type matches kb-type, and that are accessible through the connection.
get-procedure     ( name &key kb)
Return Value(s): procedure
Flags: O R
Returns the procedure that is the procedure association for the name, or false if there is no such procedure association. See   register-procedure,   unregister-procedure, and   call-procedure.
get-slot-facets     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) kb-local-only-p)
Return Value(s): list-of-facets exact-p
Flags: E M R
Returns the list-of-facets associated with slot in frame.
get-slot-type     ( frame slot &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): slot-type
Flags: O R
Returns one of {:own, :template, false} to identify the slot-type of the slot on question. If there are both an own and a template slot on frame identified by slot, then :own is returned. If no such slot is known, then false is returned.
get-slot-value     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): value-or-false exact-p
Flags: O R
Returns the single member of the set of values of the slot. This operation is meaningful only for single-valued slots. It is an error to call   get-slot-value on a non-single-valued slot, and implementations should signal a   cardinality-violation if this occurs. When there is no value for the slot, value-or-false is false.
get-slot-values     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): list-of-values exact-p more-status
Flags: E O R
Returns the list-of-values of slot within frame. If the :collection-type of the slot is :list, and only :direct own slots have been asserted, then order is preserved; otherwise, the values are returned in no guaranteed order.   Get-slot-values always returns a list of values. If the specified slot has no values, () is returned.
get-slot-values-in-detail     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): list-of-specs exact-p more-status default-p
Flags: E M R
Returns the list-of-specs describing the values of slot within frame. If the :collection-type of the slot is :list, and only :direct own slots have been asserted, then order is preserved; otherwise, the values are returned in no guaranteed order.   Get-slot-values-in-detail always returns a list of specifications as its list-of-specs value. If the specified slot has no values, () is returned.

Each spec is a 3-tuple of the form (value direct-p default-p).

The default-p returned value is true if the list-of-specs is (), and the fact that there are no values is itself a default.
gfp-condition-p     ( thing)
Return Value(s): boolean
Flags: O R
Returns true if thing is a GFP-defined condition object, and false otherwise.
goto-kb     ( kb)
Return Value(s): void
Flags: O W
Makes kb the current KB. After a call to   goto-kb, the value of a call to   current-kb will be kb. The newly established   current-kb will be used as the default value for the kb argument by language bindings that support argument defaulting. Returns no values.
has-more     ( enumerator)
Return Value(s): boolean
Flags: O R
Returns true if the enumerator has more values, otherwise returns false.
individual-p     ( thing &key kb kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true if thing identifies an individual entity, and returns false if thing identifies a class.
instance-of-p     ( thing class &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true if thing is an instance of class, otherwise returns false.
kb-p     ( thing)
Return Value(s): boolean
Flags: O R
Returns true if thing is a KB, otherwise returns false.
local-connection   ( )
Return Value(s): connection
Flags: R   
Returns a connection to the local GFP implementation.
member-behavior-values-p     ( behavior value &key kb)
Return Value(s): boolean
Flags: O R
Returns true when value is one of the variants of behavior that is currently active for kb, and returns false otherwise.
member-facet-value-p     ( frame slot facet value &key kb (test :equal) (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true iff value is a value in the specified facet of slot on frame, as determined by the predicate test, and returns false otherwise.
member-slot-value-p     ( frame slot value &key kb (inference-level :taxonomic) (test :equal) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true iff value is a value in slot of frame, as determined by the predicate test, and returns false otherwise.
meta-kb     ( &key (connection (local-connection)))
Return Value(s): meta-kb
Flags: O R
Returns the Meta-KB for the server accessed through the connection.
next     ( enumerator)
Return Value(s): value
Flags: O R
Return the next value for the enumerator. It is an error to call   next if   has-more would return false for the enumerator. If   next is called on an enumerator that has been exhausted, an   enumerator-exhausted error should be signaled.
open-kb     ( kb-locator &key kb-type (connection (local-connection)) (error-p true))
Return Value(s): kb
Flags: M W
Given a kb-locator, a kb-type, and a connection, returns a KB object for that KB descriptor that will behave as if all the objects in the KB are accessible (the implementation is not actually required to load the whole KB into memory).

Implementations are at liberty to accept other values in place of the kb-locator, such as a pathname that identifies the location of the KB to the system. Such usage is convenient, but is not portable. It is not portable for a GFP application to use anything other than a KB descriptor for this argument. If error-p is false, catches errors that occur, and attempts to continue with the opening/loading process. If the KB could not be successfully opened, returns false.

openable-kbs     ( &key kb-type (connection (local-connection)))
Return Value(s): list-of-kb-locators
Flags: M R
Given a kb-type and a connection, returns list-of-kb-locators, a list of frame handles to frames in the   meta-kb that are instances of the class kb-locator. Each kb-locator instance describes one openable KB, identified at the time of the call. Subsequent calls to openable-kbs will refresh the set of kb-locator instances in the meta-kb. Kb-locators refering to KBs of kb-type that are no longer openable will be removed. KBs of kb-type that have become openable since the last call will become represented in the   meta-kb.
prefetch     ( enumerator &key (number-of-values :all) increment)
Return Value(s): void
Flags: O R
The   prefetch operator is an important optimization in network settings. The client will attempt to prefetch sufficient elements in enumerator from the server so that number-of-values elements will be immediately available (cached) at the enumerator, using only a single network call rather than executing network calls for each element.

If it is discovered that there are fewer than number-of-values elements cached locally by enumerator, a minimum chunk of increment elements will be prefetched, when available. Thus, if the enumerator already holds five elements locally, and the call (prefetch enumerator 7 20) is made, the fact that seven elements are requested, but only five are available means that a request will in fact be made to the server for more elements, and at least another 20 (as opposed to 2) elements will be prefetched. When increment is false, the number of elements prefetched will be the difference between the number currently cached in the enumerator and number-of-values.

Note that unlike other operations taking a number-of-values argument, this operation does not return a more-status value. Returns no values.

primitive-p     ( class &key kb kb-local-only-p)
Return Value(s): boolean
Flags: M R
Returns true iff class is a class whose definition is primitive, and false otherwise. For FRSs that do not distinguish primitive from defined classes,   primitive-p must return true for all classes.
print-frame     ( frame &key kb (slots :filled) (facets :filled) (stream true) (inference-level :taxonomic) (number-of-values :all) (value-selector :either) kb-local-only-p)
Return Value(s): false-or-string
Flags: O R
Prints a textual representation to stream of the frame. A warning is printed when frame is not coercible to a frame. Stream objects as values to the stream argument are generally system- and implementation-specific, so stream objects will not in general be transmissible in networked implementations. Two special values for the stream argument are also supported. If stream is false, then   print-frame prints to a string stream and that string is returned as false-or-string. If stream is true,   print-frame attempts to print to the standard output stream of the server on which   print-frame runs. When kb is a network-acessed KB, this latter option is unlikely to have a useful effect. Unless stream is false, false-or-string is false.

The slots and facets arguments control which slots (facets) are to be displayed. They can each take on one of the following values:

put-behavior-values     ( behavior values &key kb)
Return Value(s): void
Flags: M R
Sets the list of active values of the behavior under which the KB is to operate. The elements in values must be a subset of the values returned by a call to   get-behavior-supported-values for the same behavior. If they are not, an   illegal-behavior-values error will be signaled. Note that for some behaviors, the order of values is significant (e.g., :collection-type). Returns no values.
put-class-superclasses     ( class new-superclasses &key kb kb-local-only-p)
Return Value(s): void
Flags: M W
Changes class to be a subclass of all the classes listed in new-superclasses. This operation may signal constraint violation conditions (see Section 3.8). Returns no values.
put-facet-value     ( frame slot facet value &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
Sets the values of the specified facet to be a singleton set consisting of a single element: value. Returns no values.
put-facet-values     ( frame slot facet values &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: M W
Sets the values of the specified facet to be values, which is assumed to be a set. The order of the elements of values will not necessarily be maintained by the FRS. This operation may signal constraint violation conditions (see Section 3.8). Returns no values.
put-frame-details     ( frame details &key kb kb-local-only-p)
Return Value(s): void
Flags: O W
Redefines frame to have the specified details. Details is a property list as specified for   get-frame-details. This operation is useful for systems that allow transaction-oriented editing of multiple aspects of a frame. The properties :handle, :frame-type, and :primitive-p are ignored, since these may not be put. Returns no values.
put-frame-name     ( frame new-name &key kb kb-local-only-p)
Return Value(s): renamed-frame
Flags: M W
Changes the name of frame to be new-name. All references to frame in kb (e.g., in slot values) will point to the frame named new-name. Returns the frame with the new name, renamed-frame. It is not necessary that the frame object identified by frame be identical (==/EQLness) to the frame object called new-name, only that the KB consistently use the new frame instead of the old one.

Implementation note: FRSs that use frame names as frame handles must replace all references to the old name of frame with new-name. This specification allows for implementations that are forced to replace the representation of the frame with a new, renamed version.

put-frame-pretty-name     ( frame name &key kb kb-local-only-p)
Return Value(s): void
Flags: M W
Stores the name, a string, as the new pretty-name of the frame. GFP mandates no constraints on the new pretty-name, but to maximize the liklihood that applications will interoperate smoothly, implementations are encouraged to make pretty-names be short, and are strongly encouraged to include no whitespace characters other than the space characters, or any display device-specific control characters. Returns no values.
put-instance-types     ( frame new-types &key kb kb-local-only-p)
Return Value(s): void
Flags: M W
Changes frame to be an instance of all the classes listed in new-types. This operation may signal constraint violation conditions (see Section 3.8). Returns no values.
put-slot-value     ( frame slot value &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
Sets the values of slot in frame to be a singleton set consisting of a single element: value. This operation may signal constraint violation conditions (see Section 3.8). Returns no values.
put-slot-values     ( frame slot values &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: M W
Sets the values of slot in frame to be values. The order of the elements of values will not necessarily be maintained by the FRS, unless the :collection-type of the slot is :list. This operation may signal constraint violation conditions (see Section 3.8). Returns no values.
register-procedure     ( name procedure &key kb)
Return Value(s): void
Flags: O W
Associates the procedure with name in kb. Subsequent calls to   call-procedure may invoke the procedure merely by using the name. If name is false, then procedure must be a named procedure, in which case the name argument will default to the name of the procedure. Returns no values.
remove-class-superclass     ( class superclass-to-remove &key kb kb-local-only-p)
Return Value(s): void
Flags: O W
Removes superclass-to-remove from the superclasses of class. Returns no values.
remove-facet-value     ( frame slot facet value &key kb (test :equal) (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
If value is currently a member of the set of direct values of the specified facet, then value is removed from the values of the facet. Returns no values.
remove-instance-type     ( frame type-to-remove &key kb kb-local-only-p)
Return Value(s): void
Flags: O W
Removes type-to-remove from the types of frame - that is, makes frame no longer be an instance of type-to-remove. Returns no values.
remove-local-facet-values     ( frame slot facet &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
Removes all direct values of facet in slot of frame. Returns no values.
remove-local-slot-values     ( frame slot &key kb (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
Removes all direct values in slot of frame. Returns no values.
remove-slot-value     ( frame slot value &key kb (test :equal) (slot-type :own) (index :all) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
If value is currently a member of the set of direct values of slot, then value is removed from the values of slot. Only values matching the test are removed. If index is :all, then all occurrences of value will be removed. Otherwise, index should be an integer index into the values list, and only the value at that position, if it matches value, will be removed (the first value of the slot has index 0). The index argument is used only by slots whose :collection-type is :list. Returns no values.
rename-facet     ( facet new-name &key kb kb-local-only-p)
Return Value(s): renamed-facet
Flags: M W
Renames the facet for all frames containing that facet. All the facet values and facet values associated with facet are preserved under the new-name. For example, for any frame in the KB, the values returned by   get-facet-values for facet before the rename are identical to the values returned for new-name after the rename. In addition, the attached-to relationship is preserved - that is, if facet is attached to a frame before the rename, new-name is attached to that frame after the rename. In some implementations, references to facet may still remain in the KB after rename-facet. Returns the renamed-facet.
rename-slot     ( slot new-name &key kb kb-local-only-p)
Return Value(s): renamed-slot
Flags: M W
Renames the slot for all frames containing that slot. All the slot values and facet values associated with slot are preserved under the new-name. For example, for any frame in the KB, the values returned by   get-slot-values for slot before the rename are identical to the values returned for new-name after the rename. In addition, the attached-to relationship is preserved - that is, if slot is attached to a frame before the rename, new-name is attached to that frame after the rename. In some implementations, references to slot may still remain in the KB after rename-slot. Returns the renamed-slot.
replace-facet-value     ( frame slot facet old-value new-value &key kb (test :equal) (slot-type :own) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
If old-value is currently a member of the set of direct values of the specified facet, then old-value is replaced by new-value in the facet. Returns no values.
replace-slot-value     ( frame slot old-value new-value &key kb (test :equal) (slot-type :own) (index :all) (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O W
If old-value is currently a member of the set of direct values of slot, then old-value is replaced by new-value in slot. If index is :all then all occurrences of old-value will be replaced. Otherwise, index should be an integer index into the values list, and only the value at that position, if it matches old-value, will be replaced (the first value of the slot has index 0). This operation may signal constraint violation conditions (see Section 3.8). The index argument is used only by slots whose :collection-type is :list. Returns no values.
revert-kb     ( &key kb (error-p true))
Return Value(s): reverted-kb
Flags: O W
This operation is called when the user wishes to discard any changes made to a KB since it was last saved, and revert to the previously saved state.

Equivalent to successive calls to   close-kb and then   open-kb. The reverted-kb returned has the same content as kb had at the time it was last saved (or empty, if the kb had never been saved). No guarantee is made that the reverted-kb will have the same identity (==, EQLness) as kb, but some implementations may choose to recycle the existing KB object. After a call to   revert-kb, portable applications must refer only to the reverted-kb object rather than kb in case it was not recycled. References to the original kb may result in an   object-freed condition being signaled. If error-p is false, tries to catch errors that occur, and attempts to continue with reverting to the extent possible.

save-kb     ( &key kb (error-p true))
Return Value(s): boolean
Flags: M W
Saves the contents of the KB to persistent storage. No commitment is made as to the location of the KB in persistent storage, other than that it will be openable given the name, kb-type and connection first used to access it. No commitment is made as to whether the save operation results in a complete dump of the KB, or whether it results only in a dump of the changes made since the KB was last saved. If error-p is false, tries to catch errors that occur, and attempts to continue with saving to the extent possible. Returns true iff the KB was saved successfully, and false\ otherwise.
save-kb-as     ( new-name-or-locator &key kb)
Return Value(s): void
Flags: M W
Saves the entire contents of the KB to persistent storage under the new-name-or-locator. New-name-or-locator is either a new name for the KB, or a new kb-locator. The in-core KB is renamed so that   find-kb-of-type will return kb when passed the new name of the KB. Returns no values.
slot-has-facet-p     ( frame slot facet &key kb (inference-level :taxonomic) (slot-type :own) kb-local-only-p)
Return Value(s): boolean
Flags: O R
Returns true iff facet is a valid facet for slot on frame, and false otherwise. What constitutes a valid facet is KB-specific, but a facet with a value locally asserted, or with a value that is accessible from a template slot will return true for this operation.
slot-has-value-p     ( frame slot &key kb (inference-level :taxonomic) (slot-type :own) (value-selector :either) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true iff slot on frame has at least one value, otherwise returns false.
slot-p     ( thing &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): boolean
Flags: M R
Returns true iff thing is a slot in frame, otherwise returns false.
subclass-of-p     ( subclass superclass &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true if class subclass is a subclass of class superclass, and returns false otherwise.
superclass-of-p     ( superclass subclass &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true if class subclass is a subclass of class superclass, and returns false otherwise.
tell     ( sentence &key kb frame (value-selector :known-true) kb-local-only-p)
Return Value(s): void
Flags: O R
The tell operation asserts the sentence to be true in the knowledge base kb. Some FRSs may allow users to attach a sentence to a specific frame in the KB. If that is possible and desired, the frame argument may be supplied. When kb-local-only-p is true, the sentence should be asserted in the kb, even if kb includes another KB containing the sentence. When the sentence argument is syntactically invalid, tell signals a   syntax-error error. An FRS may not accept all valid sentences of the GFP Assertion Language, and for such cases, tell raises the condition   cannot-handle. Returns no values.
tellable     ( sentence &key kb (value-selector :known-true) kb-local-only-p)
Return Value(s): boolean
Flags: O R
The tellable operation returns false if the FRS can determine that telling the sentence would result in a   cannot-handle error being signaled, and true otherwise. It may raise a   syntax-error error as specified with the definition of tell. Even if tellable returns true, tell may still not be able to handle the sentence.
type-of-p     ( class frame &key kb (inference-level :taxonomic) kb-local-only-p)
Return Value(s): boolean exact-p
Flags: O R
Returns true if frame is an instance of class, otherwise returns false.
unregister-procedure     ( name &key kb)
Return Value(s): void
Flags: O W
Removes any procedure association for the name in kb. Returns no values.
untell     ( sentence &key kb frame (value-selector :known-true) kb-local-only-p)
Return Value(s): boolean
Flags: O R
The untell operation can be used to remove assertions from the knowledge base. Returns true if the sentence was removed, and false otherwise.

The effect of untelling a sentence of the GFP Assertion Language is equivalent to the effect of executing an equivalent GFP operation. The GFP operations equivalent to untelling a sentence in the Assertion Language are specified in Section 3.5.7. For example, the operation 

   (Untell `(slot-name frame-name ,slot-value))
is equivalent to the GFP operation (remove-slot-value 'frame-name 'slot-name slot-value :slot-type :own).

The effect of untelling an arbitrary tellable sentence is not predictable across implementations. For a given sentence s, executing (untell s :kb kb) after executing (tell s :kb kb) should remove the sentence s from the kb. That is, a second call to untell should return nil. This does not mean that s is no longer true, as it may be implied by other assertions in the KB.

Some FRSs may allow users to attach an assertion to a frame in the KB. If the sentence was attached to a frame, the frame argument must be supplied. The default value for frame is false. When the sentence argument is syntactically invalid, it may signal the   syntax-error error.

value-as-string     ( value &key kb (purpose :user-interface) (pretty-p (eq purpose :user-interface)) kb-local-only-p)
Return Value(s): string
Flags: O R
Given some value, returns a string that is a printed representation of that value. This is useful for user interfaces that have no way in general to print the arbitrary data structures that might be returned by, for example,   get-slot-values.
Purpose - The purpose argument can be one of {:file, :user-interface}. When it is :file, it allows the KB to print data in a manner that will be readable again (e.g., for dumping to files), preserving object identity where necessary. The output will therefore typically fully escape strings, and will probably package qualify symbols. When purpose is :user-interface, the string returned will be as pretty and readable as possible for a user interface, but such output will probably not be readable by GFP.
Pretty-p - When true, GFP will attempt to print everything in as pretty a manner as possible. This includes printing frames by using their pretty-names, and by printing strings without escaping or quotes.

GFP Conditions

  Recall that whenever possible, GFP operations that experience erroneous conditions or arguments signal errors by using condition signal. GFP conditions classes are defined here, and we present them in alphabetical order. Instead of an argument list, conditions have a list of properties that will be associated with instances of the condition. For example, the class-not-found condition has a class and kb associated with it meaning that class was not found in the kb.

abstract-gfp-error   error-message continuable
Condition Type:   
The abstract GFP error condition. Error-message is a string to print out for the error. If the error is not so severe that processing with the KB will have undefined results, continuable is true. This is the abstract superclass of GFP errors. No unspecialized instances of this error type will ever be signaled.

cannot-handle   sentence
Condition Type:   abstract-gfp-error   
The condition signaled when a   tell is performed on a sentence that cannot be handled.
cardinality-violation   constraint frame slot facet kb
Condition Type:   constraint-violation   
The condition signaled when a value stored in a slot violates a cardinality constraint on that slot.
class-not-found   class kb
Condition Type:   abstract-gfp-error   
The condition signaled on reference to a class that is not defined.
constraint-violation   constraint frame slot kb
Condition Type:   abstract-gfp-error   
The condition signaled when a value stored in a slot or facet violates a constraint on that slot.
domain-required   frame slot facet kb
Condition Type:   abstract-gfp-error   
The condition signaled when an attempt is made to create a slot or facet with an unconstrained domain in an FRS that does not support unconstrained slot (or facet) domains.
enumerator-exhausted   enumerator
Condition Type:   abstract-gfp-error   
The condition signaled when an enumerator is exhausted, and an attempt is made to get a value from it.
facet-not-found   frame slot slot-type facet kb
Condition Type:   abstract-gfp-error   
The condition signaled on reference to a nonexistent facet.
frame-already-exists   frame kb
Condition Type:   abstract-gfp-error   
The condition signaled on an attempt to create a frame that already exists. This error is signaled only when the :frame-names-required behavior is active.
generic-gfp-error  
Condition Type:   abstract-gfp-error   
The generic GFP error condition. This error is signaled when no more specific and appropriate error type can be found.
illegal-behavior-values   behavior proposed-values
Condition Type:   abstract-gfp-error   
The condition signaled when an application attempts to set illegal behavior values. Proposed-values are the values that the application is attempting to set for the behavior.
kb-not-found   kb
Condition Type:   abstract-gfp-error   
The condition signaled on reference to a nonexistent kb.
kb-value-read-error   read-string kb
Condition Type:   abstract-gfp-error   
The condition signaled on read errors. Read-string is the string from which the KB value is being read. See   coerce-to-kb-value.
method-missing   gfpop kb
Condition Type:   abstract-gfp-error   
The condition signaled on reference to a nonhandled method for a GFP operation. Gfpop is the name of the operation in question. This error is signaled when a GFP back end detects either that it is not compliant, or that is has been called in a manner that is inconsistent with its advertized capabilities, according to the value of the :compliance behavior.
missing-frames   missing-frames frame kb
Condition Type:   abstract-gfp-error   
The condition signaled by   copy-frame when missing-frame-action is either :stop or :abort and error-p is true, and frames are found to be missing.   Missing-frames is the list of missing frames.
network-connection-error   host port
Condition Type:   abstract-gfp-error   
The error signaled when GFP fails to make a network connection. Host is the host to which it is trying to connect, and port is the port number.
not-a-frame-type   frame-type kb
Condition Type:   abstract-gfp-error   
The condition signaled on an attempt to create an entity supplying frame-like arguments (such as own-slots) in a FRS that does not represent entities of that frame-type as frames.
not-coercible-to-frame   frame kb
Condition Type:   abstract-gfp-error   
The condition signaled on an attempt to coerce an object to a frame that does not identify a frame.
not-unique-error   pattern matches type kb
Condition Type:   abstract-gfp-error   
The condition signaled when a match operation has nonunique results. Pattern is the pattern given to the completion operation (e.g.,   coerce-to-kb-value). Matches is the list of matches. Type is the type expected, e.g. :slot.
object-freed   object
Condition Type:   abstract-gfp-error   
The condition signaled when possible when a user accesses a freed data structure. Object is the object being accessed.
read-only-violation  
Condition Type:   abstract-gfp-error   
The condition signaled upon a read-only violation on a read-only KB.
slot-not-found   frame slot slot-type kb
Condition Type:   abstract-gfp-error   
The condition signaled on reference to a slot that is not defined in frame.
syntax-error   erring-input
Condition Type:   abstract-gfp-error   
The condition signaled when a syntax error is detected in KIF input. Erring-input is either a string containing the erring input, or a malformed KIF input.
valuetype-violation   constraint frame slot kb
Condition Type:   constraint-violation   
The condition signaled when a value being stored in a slot violates a :valuetype constraint on that slot.
next up previous contents index
Next: Differences amongst FRSs Up: The Generic Frame Protocol Previous: The GFP Knowledge Model

For questions regarding GFP