Functional List of LSAPI Functions

Main entry points to set up Prolog environment

  • lsInit
  • lsInit2
  • lsInitLSX
  • lsAddLSX
  • lsAddPred
  • lsInitPreds
  • lsLoad
  • lsMain
  • lsReset
  • lsClose
  • Parameter manipulating functions for building extended predicates

  • lsGetParm
  • lsGetParmType
  • lsStrParmLen
  • lsUnifyParm
  • Calling Prolog from the host language

  • lsExec
  • lsExecStr
  • lsCall
  • lsCallStr
  • lsRedo
  • lsClearCall
  • Dynamic database asserting and retracting

  • lsAsserta
  • lsAssertaStr
  • lsAssertz
  • lsAssertzStr
  • lsRetract
  • lsRetractStr
  • String/Term conversion functions

  • lsTermToStr
  • lsTermToStrQ
  • lsStrToTerm
  • Making Prolog types

  • lsMakeAddr
  • lsMakeAtom
  • lsMakeFloat
  • lsMakeInt
  • lsMakeStr
  • Getting C values from Prolog terms

  • lsGetTerm
  • lsGetTermType
  • lsStrTermLen
  • Structure manipulation functions

  • lsGetFA
  • lsMakeFA
  • lsUnifyArg
  • lsGetArg
  • lsGetArgType
  • lsStrArgLen
  • lsUnify
  • List manipulation functions

  • lsMakeList
  • lsPopList
  • lsPushList
  • lsGetHead
  • lsGetTail
  • Stream I/O functions

  • lsSetInput
  • lsSetOutput
  • lsSetIOArg
  • lsSetStream
  • lsGetStream
  • Miscellaneous functions

  • lsGetVersion
  • lsSetCommandArgs
  • Error handling

  • lsErrRaise
  • lsGetExceptType
  • lsGetExceptRC
  • lsGetExceptMsg
  • lsGetExceptCallStack
  • lsGetExceptReadBuffer
  • lsGetExceptReadFileName
  • lsGetExceptReadLineno
  • LSAPI Data Types

    API functions that initiate Prolog execution or unification return TF, a Prolog true/false. Most other functions return RC, an error checkable function return.

    TF
    can be TRUE (1), FALSE (0) or some other number which indicates a Prolog error.
    RC
    can be OK (0), or some other number which indicates a Prolog error.

    Many API functions require you to specify the type of the Prolog term, pTYPE. pTYPE is an enumerated constant with these values.

    pATOM
    an atom
    pINT
    an integer
    pSTR
    a string (delimited by $'s)
    pFLOAT
    a double precision floating point number
    pSTRUCT
    a structure
    pLIST
    a list
    pTERM
    a term
    pADDR
    the address of a Prolog value
    pVAR
    a Prolog variable
    pWSTR
    a Unicode string
    pWATOM
    a Unicode atom

    Other API functions require you to specify the type of the host language variable, cTYPE. cTYPE is an enumerated constant with these values.

    cAATOM
    an atom (used to indicate a host string will become an atom) (see cATOM below)
    cASTR
    an ANSI character string (see cSTR below)
    cINT
    an integer
    cLONG
    a long
    cSHORT
    a short
    cFLOAT
    a single precision floating point number
    cDOUBLE
    a double precision floating point number
    cADDR
    the address of a value
    cTERM
    a term
    cWSTR
    a Unicode string
    cWATOM
    a Unicode atom
    cSTR
    a cover type mapped to cASTR or cWSTR depending on whether _UNICODE is specified or not
    cATOM
    a cover type mapped to cAATOM or cWATOM depending on whether _UNICODE is specified or not

    Other defined types are

    STRptr
    a pointer to a string, Unicode or ASCII depending upon the interface
    VOIDptr
    a pointer to anything
    intC
    an integer the size of a Prolog cell (usually 32 bits)
    uintC
    an unsigned intC
    intCH
    an integer half the size of a Prolog cell (usually 16 bits)
    uintCH
    an unsigned intCH
    CELL
    a Prolog cell
    TERM
    a Prolog term (a pointer to a CELL)
    PATOM
    a Prolog atom (same as intCH)
    PATOMptr
    a pointer to PATOM
    ARITY
    a Prolog arity (uintCH)
    ENGid
    ID value for a Logic Server engine
    ExtPred
    a function pointer for an extended predicate

    A few API functions manipulate Prolog I/O streams. They use the enumerated constant STREAM to identify the streams. Values of STREAM are

    CUR_IN
    CUR_OUT
    CUR_ERR
    USER_IN
    USER_OUT
    USER_ERR

    The exectipn types, ExType, are:

    See amzi.h for the exact implementations of all data types.

    LSAPI Function Descriptions

    lsAddLSX

    Description:

    void AddLSX(STRptr lsxname, VOIDptr vp);
    RC lsAddLSX(ENGid cureng, STRptr lsxname, VOIDptr vp);

    cureng
    Current engine identifier
    lsxname
    Name of the LSX file to load
    vp
    Pointer, can be used to identify calling application.

    Remarks:

    Causes the Logic Server to load the specified LSX file. Like other API functions that initialize extended predicates, lsAddLSX() must come after a call to lsInit() and before a call to lsLoad().

    See Extended Predicate Libraries (LSXs) and Writing Extended Predicates

    Return Value:

    OK if everything worked

    Example:

    lsAddPred

    Description:

    void AddPred(STRptr functor, ARITY arity, ExtPred fp, VOIDptr vp);
    RC lsAddPred(ENGid cureng, STRptr functor, ARITY arity, ExtPred fp, VOIDptr vp)

    cureng
    Current engine identifier
    functor
    Functor of the extended predicate
    arity
    Arity of the extended predicate
    fp
    Function pointer to host language implementation
    vp
    Pointer to anything to be passed to the extended predicate

    Remarks:

    Adds the predicate functor/arity to the extended predicate table, mapping it to the function pointed to by fp. Like lsInitPreds(), lsAddPred() must be called between the calls to lsInit() and lsLoad().

    The fourth argument is used in the callback. This argument is passed as the first argument to the extended predicate. This feature allows you to implement call backs to member functions of class. The extended predicate becomes a dispatch function, that uses the argument as a pointer to an object that is used to implement the extended predicate. See the C++ PetsCB and Rubik's cube samples for an example of this technique.

    NOTE that when lsInitPreds is called, this fourth argument is automatically generated to be the engine ID, so call back functions get the engine ID passed as a parameter.

    See Extended Predicate Libraries (LSXs) and Writing Extended Predicates

    Return Value:

    Returns OK if it worked.

    Example:

    This code adds an extended predicate called msgbox that takes one argument.

    lsAsserta

    Description:

    void Asserta(TERM term);
    RC lsAsserta(ENGid cureng, TERM term);

    cureng
    Current engine identifier
    term
    Term to be asserted

    Remarks:

    Asserts the term to the dynamic database as the first clause under the key which is the term's functor. Same as Prolog asserta/1 and assert/1.

    See Asserting and Retracting to and from the Prolog Database

    Return Value:

    Returns OK if it worked, NOTOK if some indeterminate error happened, and an atom (small positive integer) if the term redefined a protected predicate.

    lsAssertaStr

    Description:

    void AssertaStr(STRptr str);
    RC lsAssertaStr(ENGid cureng, STRptr str);

    cureng
    Current engine identifier
    str
    String representation of term to be asserted

    Remarks:

    A convenient form of lsAsserta() that uses a string instead of a term. Asserts the term to the dynamic database as the first clause under the key which is the term's functor. Same as Prolog asserta/1 and assert/1.

    See Asserting and Retracting to and from the Prolog Database

    Return Value:

    Returns OK if it worked, NOTOK if some indeterminate error happened, and an atom (small positive integer) if the term redefined a protected predicate.

    Example:

    lsAssertz

    Description:

    void Assertz(TERM term);
    RC lsAssertz(ENGid cureng, TERM term);

    cureng
    Current engine identifier
    term
    Term to be asserted

    Remarks:

    Asserts the term to the dynamic database as the last clause under the key which is the term's functor. Same as Prolog assertz/1.

    See Asserting and Retracting to and from the Prolog Database

    Return Value:

    Returns OK if it worked, NOTOK if some indeterminate error happened, and an atom (small positive integer) if the term redefined a protected predicate.

    Example:

    lsAssertzStr

    Description:

    void AssertzStr(STRptr str);
    RC lsAssertzStr(ENGid cureng, STRptr str);

    cureng
    Current engine identifier
    str
    String representation of term to be asserted

    Remarks:

    A convenient form of lsAssertz() that uses a string instead of a term. Asserts the term to the dynamic database as the last clause under the key which is the term's functor. Same as Prolog assertz/1.

    See Asserting and Retracting to and from the Prolog Database

    Return Value:

    Returns OK if it worked, NOTOK if some indeterminate error happened, and an atom (small positive integer) if the term redefined a protected predicate.

    Example:

    lsCall

    Description:

    TF Call(TERMptr termp);
    TF lsCall(ENGid cureng, TERMptr termp);

    cureng
    Current engine identifier
    termp
    Pointer to term to be called

    Remarks:

    Once a term has been created it can be passed to the Amzi! interpreter with lsCall(). This is equivalent to the Prolog statement call(X) where X is a Prolog term.

    See Calling Terms

    Return Value:

    Returns TRUE/FALSE

    Example:

    lsCallStr

    Description:

    TF CallStr(TERMptr termp, STRptr str);
    TF lsCallStr(ENGid cureng, TERMptr termp, STRptr str);

    cureng
    Current engine identifier
    termp
    Returns the term corresponding to string
    str
    The string representation of a term to call

    Remarks:

    lsCallStr() is a more convenient form of lsCall() that lets you use the string representation of a Prolog term or query.

    See String Passing Interface

    Return Value:

    Returns TRUE/FALSE

    Example:

    lsClearCall

    Description:

    RC ClearCall();
    RC lsClearCall(ENGid cureng)

    cureng
    Current engine indentifier

    Remarks:

    A call to lsCall() or lsCallStr() causes the Prolog engine to build a backtracking choice point on the Prolog control stack. Successive calls to lsRedo() will cause the choice point to be removed when there are no more choices.

    If you do not exhaust all the choices with lsRedo() calls, then a call to lsClearCall() can be made to remove the choice point from the stack. It is not in general necessary, but is good form and might be required if the lsCall() is in a tight loop, thus using up the control stack.

    lsCall() and lsCallStr() should not be used when the call is intended to be executed only once. For those situations lsExec() and lsExecStr() should be used, which do not add a choice point to the Prolog control stack.

    See Scope of Logic Server Terms

    Return Value:

    OK

    lsClose

    Description:

    void Close();
    RC lsClose(ENGid cureng);

    cureng
    Current engine identifier

    Remarks:

    Closes down the Prolog environment, closing Prolog streams and freeing all memory allocated by Prolog.

    See Main Entry Points

    Return Value:

    OK

    Example:

    lsErrRaise

    Description:

    void ErrRaise(STRptr msg);
    RC lsErrRaise(ENGid cureng, STRptr msg)

    cureng
    Current engine identifier
    msg
    The string to use in the error message

    Remarks:

    Causes an Exec type Prolog error to be raised with the specified error message.

    See Error Handling

    lsExec

    Description:

    TF Exec(TERMptr termp);
    TF lsExec(ENGid cureng, TERMptr termp);

    cureng
    Current engine identifier
    termp
    Term to execute

    Remarks:

    lsExec() and lsExecStr() are similar to lsCall() and lsCallStr(). The only difference is the Exec functions are intended to be called only once and not backtracked into. That is, you cannot call lsRedo() after lsExec(), but you can after lsCall().

    The advantage of lsExec() calls over lsCall() calls is they do not add anything to the Prolog execution stack, so they can be called with no overhead. The disadvantage, of course, is you can't backtrack through them.

    See Calling Terms

    Return Value:

    Returns TRUE/FALSE

    lsExecStr

    Description:

    TF ExecStr(TERMptr termp, STRptr str);
    TF lsExecStr(ENGid cureng, TERMptr termp, STRptr str);

    cureng
    Current engine identifier
    termp
    Returns the term corresponding to string
    str
    The string representation of a term to call

    Remarks:

    lsExecStr() is a more convenient form of lsExec() that lets you use the string representation of a Prolog term or query.

    See String Passing Interface

    Return Value:

    Returns TRUE/FALSE

    Example:

    lsGetArg

    Description:

    void GetArg(TERM term, int iarg, cTYPE ctype, VOIDptr valp);
    RC lsGetArg(ENGid cureng, TERM term, int iarg, cTYPE ctype, VOIDptr valp);

    cureng
    Current engine identifier
    term
    The term whose argument is being retrieved
    iarg
    The argument number, starting at 1
    ctype
    The type of variable being set
    valp
    Pointer to where to put the value

    Remarks:

    Used to extract arguments from complex structures.

    Visual Basic Note: When retrieving strings from VB, you must specify 'ByVal' for the VOIDptr val argument.

    See Mapping Prolog Arguments to Host Variables

    Return Value:

    OK if it worked, NOTOK if it didn't.

    Example:

    lsGetArgType

    Description:

    pTYPE GetArgType(TERM term, int iarg);
    pTYPE lsGetArgType(ENGid cureng, TERM term, int iarg);

    cureng
    Current engine identifier
    term
    Term to examine
    iarg
    Which argument of the term to test

    Remarks:

    Gets the type of the iargth argument of term, assuming term is a structure.

    See Mapping Prolog Arguments to Host Variables

    Return Value:

    pTYPE, see the Data Types section for possible values.

    lsGetExceptCallStack

    Description:

    void CLSException::GetCallStack(STRptr str, int len);
    RC lsGetExceptCallStack(ENGid cureng, STRptr str, int len)

    cureng
    Current engine identifier
    str
    String buffer big enough to hold the call stack
    len
    Length of str

    Remarks:

    Gets the call stack when the current exception occurred.

    See Error Handling

    Return Value:

    OK

    lsGetExceptMsg

    Description:

    void CLSException::GetMsg(STRptr str, int len);
    RC lsGetExceptMsg(ENGid cureng, STRptr str, int len);

    cureng
    Current engine identifier
    str
    String buffer to hold error message
    len
    Length of str

    Remarks:

    Gets the message for the current error.

    See Error Handling

    Return Value:

    OK

    Example:

    rc = lsLoad(CurEng, xplname);
    if (rc != 0)
    {
       lsGetExceptMsg(CurEng, errmsg, 1024);
       printf("Fatal Error #%d loading Amzi! Logic Server .xpl file:\n%s", rc, errmsg);
    }
    

    lsGetExceptReadBuffer

    Description:

    void CLSException::GetReadBuffer(STRptr str, int len);
    RC lsGetExceptReadBuffer(ENGid cureng, STRptr str, int len)

    cureng
    Current engine identifier
    str
    String buffer big enough to hold the current read buffer
    len
    Length of str

    Remarks:

    Gets the current read buffer which includes the words "<-Near Here->" to indicate the location of the read error, or at least where the Prolog reader realized it was in trouble.

    See Error Handling

    Return Value:

    OK

    lsGetExceptReadFileName

    Description:

    void CLSException::GetReadFileName(STRptr str, int len);
    RC lsGetExceptReadBuffer(ENGid cureng, STRptr str, int len)

    cureng
    Current engine identifier
    str
    String buffer big enough to hold a file name and path
    len
    Length of str

    Remarks:

    Gets the name of the file, if any, that was open when a read error occurred. The name is an empty string if the read error occurred during string I/O or console I/O.

    See Error Handling

    Return Value:

    OK

    lsGetExceptReadLineno

    Description:

    int CLSException::GetReadLineno();
    int lsGetExceptReadLineno(ENGid cureng)

    cureng
    Current engine identifier

    Remarks:

    If the read error occurred during file I/O, this function returns a line number in the file close to where the error occurred.

    See Error Handling

    Return Value:

    OK

    lsGetExceptType

    Description:

    ExType CLSException::GetType();
    ExType lsGetExceptType(ENGid cureng)

    cureng
    Current engine identifier

    Remarks:

    Returns the type of the current exception. See the section on Data Types for the values of ExType.

    See Error Handling

    Return Value:

    The exception type.

    lsGetExceptRC

    Description:

    RC CLSException::GetRC();
    RC lsGetExceptRC(ENGid cureng)

    cureng
    Current engine identifier

    Remarks:

    Returns the return code of the current exception.

    See Error Handling

    Return Value:

    The return code

    lsGetFA

    Description:

    void GetFA(TERM term, STRptr functor, ARITYptr, arityp);
    RC lsGetFA(ENGid cureng, TERM term, STRptr functor, ARITYptr arityp);

    cureng
    Current engine identifier
    term
    Term to be dissected
    functor
    String which will contain the functor
    arityp
    Pointer to an integer of type ARITY that will have the arity

    Remarks:

    This function lets you determine the functor and arity of a term. If the term is an atom, then the arity will be 0. If the term is a list then the functor will be "." and the arity 2.

    See Manipulating Structures

    Return Value:

    Returns OK for the three types of terms described above, returns NOTOK if the term is not a legal atom, structure or list.

    Example:

    lsGetHead

    Description:

    void GetHead(TERM term, cTYPE ctype, VOIDptr valp);
    RC lsGetHead(ENGid cureng, TERM term, cTYPE ctype, VOIDptr valp)

    cureng
    Current engine identifier
    term
    Term representing a list
    ctype
    Type of variable to be filled
    valp
    Address of the variable

    Remarks:

    The term representing the head of the list is stored in valp. See the Data Types section for legal values of cTYPE.

    See Manipulating Lists

    Return Value:

    OK if everything worked, NOTOK if it failed. Note that it will fail if term does not represent a list or if term represents the empty list.

    lsGetParm

    Description:

    void GetParm(int iparm, cTYPE ctype, VOIDptr valp);
    RC lsGetParm(ENGid cureng, int iparm, cTYPE ctype, VOIDptr valp);

    cureng
    Current engine identifier
    iparm
    Number of the parameter to get
    ctype
    C/C++ type to retrieve a value into
    valp
    Pointer to the C/C++ variable to hold the value

    Remarks:

    When implementing extended predicates, lsGetParm() gets the C/C++ value of the iparmth parameter, where 1 is the first parameter. See the Data Types section for legal values of cTYPE.

    See Writing Extended Predicates

    Return Value:

    OK if successful.

    Example:

    lsGetParmType

    Description:

    pTYPE GetParmType(int iparm);
    pTYPE lsGetParmType(ENGid cureng, int iparm);

    cureng
    Current engine identifier
    iparm
    Number of the parameter whose type is returned

    Remarks:

    When implementing extended predicates lsGetParmType() gets the parameter type of the iparmth parameter.

    See Writing Extended Predicates

    Return Value:

    pTYPE, see the Data Types section for legal values of pTYPE.

    Examples:

    lsGetStream

    Description:

    int GetStream(STREAM stream);
    int lsGetStream(ENGid cureng, STREAM stream);

    cureng
    Current engine identifier
    stream
    Stream identifier

    Remarks:

    Gets the current integer handle of the stream specified by stream. See the section on Data Types for the legal values of STREAM.

    See Capturing Prolog I/O

    Return Value:

    The integer handle of the stream.

    lsGetTail

    Description:

    TERM GetTail(TERM term);
    TERM lsGetTail(ENGid cureng, TERM term)

    cureng
    Current engine identifier
    term
    Term representing a list

    Remarks:

    The term representing the tail of the list is returned.

    Return Value:

    The term representing the tail. Returns 0 if term does not represent a list or if term represents the empty list.

    See Manipulating Lists

    lsGetTerm

    Description:

    void GetTerm(TERM term, cTYPE ctype, VOIDptr valp);
    RC lsGetTerm(ENGid cureng, TERM term, cTYPE ctype, VOIDptr valp);
    cureng
    Current engine identifier
    term
    Term from which value is to be taken
    ctype
    C type to receive the value
    valp
    Pointer to the C/C++ variable

    Remarks:

    Copies the value of the term into the variable of type ctype pointed to by valp. See the Data Types section for legal values of cTYPE.

    See Handling Varying Prolog Types

    Return Value:

    OK if it worked.

    lsGetTermType

    Description:

    pTYPE GetTermType(TERM term);
    pTYPE lsGetTermType(ENGid cureng, TERM term);

    cureng
    Current engine identifier
    term
    Term

    Remarks:

    Get the type of the term.

    Return Value:

    Returns the Prolog type of the term. See the Data Types section for legal values of pTYPE.

    See Handling Varying Prolog Types

    Example:

    lsGetVersion

    Description:

    void GetVersion(STRptr str);
    RC lsGetVersion(ENGid cureng, STRptr str);

    cureng
    Current engine identifier
    str
    String to hold version

    Remarks:

    Copies the current version information into the string s.

    See Miscellaneous API Functions

    Return Value:

    OK

    lsInit

    Description:

    void Init(STRptr ininame);
    RC lsInit(ENGid *cureng, STRptr ininame);

    cureng
    Pointer to the new engine identifier
    ininame
    Name of .cfg file used for stacks etc.

    Remarks:

    Initializes the Prolog environment, using <filename>.cfg if present. If it's not present, then it uses amzi.cfg and system defaults. It can be called with an empty string, "", if you don't care to look for an application specific .cfg file. Must be called once, and before lsLoad() is called.

    See Main Entry Points

    Return Value:

    OK if everything worked.

    Example:

    lsInit2

    Description:

    void Init2(STRptr iniparams);
    RC lsInit2(ENGid *cureng, STRptr iniparams);

    cureng
    Pointer to the new engine identifier
    iniparams
    INI parameters used for stacks etc.

    Remarks:

    Initializes the Prolog environment, using the .cfg parameters specified in the iniparams string. The string is of the format "parm1=val1, parm2=val2..". The .cfg parameters can be specified using their full name or with their abbreviation. See the section on INI parameters for a list.

    Either lsInit() or lsInit2 must be called once, and before lsLoad() is called.

    See Main Entry Points

    Return Value:

    OK if everything worked.

    Example:

    lsInitLSX

    Description

    void InitLSX(VOIDptr p);
    RC lsInitLSX(ENGid cureng, VOIDptr p);

    cureng
    Current engine identifier
    p
    Pointer, can be used to identify calling application.

    Remarks:

    Causes the Logic Server to look for the 'loadlsx' .cfg file parameter, and load any .lsx files listed there.

    See Extended Predicate Libraries (LSXs) and Writing Extended Predicates

    Return Value:

    OK if everything worked

    lsInitPreds

    Description:

    void InitPreds(PRED_INITptr predtabp);
    RC lsInitPreds(ENGid cureng, PRED_INITptr predtabp);
    cureng
    Current engine identifier
    predtabp
    Predicate table pointer

    Remarks:

    Initializes the predicate table pointed to by predtabp. An application can initialize any number of predicate tables. This should be called after the call to lsInit() and before calling any Prolog functions.

    See Extended Predicate Libraries (LSXs) and Writing Extended Predicates

    Return Value:

    OK if everything worked.

    Example:

    lsLoad

    Description:

    void Load(STRptr xplname);
    RC lsLoad(ENGid cureng, STRptr xplname);

    cureng
    Current engine identifier
    xplname
    Name of the .xpl file

    Remarks:

    Loads the compiled and linked Prolog program, xplname. You must call lsLoad() at least once after calling lsInit(). If you want to load multiple compiled Prolog files, the rest need to be loaded as .plm files using lsExecStr() to call the load predicate with the name of the .plm file to load.

    See Main Entry Points

    Return Value:

    OK if it worked.

    Example:

    lsMain

    Description:

    TF Main();
    TF lsMain(ENGid cureng);

    cureng
    Current engine identifier

    Remarks:

    Calls main/0 of the loaded Prolog .xpl file.

    See Main Entry Points

    Return Value:

    Prolog TRUE/FALSE depending on success or failure.

    Example:

    lsMakeAddr

    Description:

    void MakeAddr(TERMptr termp, VOIDptr valp);
    RC lsMakeAddr(ENGid cureng, TERMptr termp, VOIDptr valp);

    cureng
    Current engine identifier
    termp
    Pointer to a term
    valp
    An address

    Remarks:

    Creates a term of type pADDR from the pointer valp.

    See Making Simple Terms

    Return Value:

    OK if it worked.

    lsMakeAtom

    Description:

    void MakeAtom(TERMptr termp, STRptr str);
    RC lsMakeAtom(ENGid cureng, TERMptr termp, STRptr str);

    cureng
    Current engine identifier
    termp
    Pointer to a term
    str
    String representing a Prolog atom

    Remarks:

    Creates a term of type pATOM from the string str.

    See Making Simple Terms

    Return Value:

    OK if it worked.

    lsMakeFA

    Description:

    void MakeFA(TERMptr termp, STRptr functor, ARITY arity);
    RC lsMakeFA(ENGid cureng, TERMptr termp, STRptr functor, ARITY arity);

    cureng
    Current engine identifier
    termp
    Pointer to a term
    functor
    String representing the functor
    arity
    Arity of the term

    Remarks:

    Creates a term with the specified functor and arity. The arguments are all unbound variables which may be left as is or set to specific values using lsUnifyArg().

    See Manipulating Structures

    Return Value:

    OK if it worked.

    Example:

    lsMakeFloat

    Description:

    void MakeFloat(TERMptr termp, double f);
    RC lsMakeFloat(ENGid cureng, TERMptr termp, double f);

    cureng
    Current engine identifier
    termp
    Pointer to a term
    f
    Double precision floating point number

    Remarks:

    Creates a term of type pFLOAT from the double float f.

    See Making Simple Terms

    Return Value:

    OK if it worked.

    lsMakeInt

    Description:

    void MakeInt(TERMptr termp, intC i);
    RC lsMakeInt(ENGid cureng, TERMptr termp, intC i);

    cureng
    Current engine identifier
    termp
    Pointer to a term
    i
    Integer

    Remarks:

    Creates a term of type pINT from the integer i.

    See Making Simple Terms

    Return Value:

    OK if it worked.

    lsMakeList

    Description:

    void MakeList(TERMptr termp);
    RC lsMakeList(ENGid cureng, TERMptr termp);

    cureng
    Current engine identifier
    termp
    Pointer to term that will point to new list

    Remarks:

    Creates an empty list pointed to by tp.

    See Making Simple Terms

    Return Value:

    OK if it worked.

    lsMakeStr

    Description:

    void MakeStr(TERMptr termp, STRptr str);
    RC lsMakeStr(ENGid cureng, TERMptr termp, STRptr str);

    cureng
    Current engine identifier
    termp
    Pointer to a term
    str
    String

    Remarks:

    Creates a term of type pSTR from the string str.

    See Making Simple Terms

    Return Value:

    OK if it worked.

    lsPopList

    Description:

    void PopList(TERMptr listp, cTYPE ctype, VOIDptr valp);
    RC lsPopList(ENGid cureng, TERMptr listp, cTYPE ctype, VOIDptr valp);

    cureng
    Current engine identifier
    listp
    Term pointing to a list or empty list
    ctype
    Type of the term to be popped
    valp
    The location to store the popped term

    Remarks:

    Pops the term of type ctype from the head of the list and save it in valp. See the Data Types section for possible values of cTYPE.

    See Manipulating Lists

    Return Value:

    OK if everything worked, NOTOK if it failed. Failure will occur if tp does not point to a list.

    lsPushList

    Description:

    void PushList(TERMptr listp, TERM term);
    RC lsPushList(ENGid cureng, TERMptr listp, TERM term)

    cureng
    Current engine identifier
    listp
    Term pointing to a list or empty list
    term
    Term to be pushed on the list

    Remarks:

    The term is pushed on the head of the list and listp points to this new head of list.

    Return Value:

    OK if everything worked, NOTOK if it failed. Failure will occur if tp does not point to a list.

    See Manipulating Lists

    lsRedo

    Description:

    TF Redo();
    TF lsRedo(ENGid cureng);

    cureng
    Current engine identifier

    Remarks:

    Causes Prolog to backtrack and retry the last lsCall(), lsvCallStr(), or lsRedo(). The term used in the initiating lsCall() or lsvCallStr() is unified with a new value if the redo is successful. lsRedo can be used in a while loop to get all the solutions to a Prolog query.

    Return Value:

    TRUE/FALSE. A loop that has the TF return code as its condition will loop until there are no more solutions.

    See String Passing Interface and Scope of Logic Server Terms

    Example:

    lsReset

    Description:

    void Reset();
    RC lsReset(ENGid cureng);

    cureng
    Current engine identifier

    Remarks:

    Resets the Prolog stacks and runtime environment. Leaves the dynamic database unchanged, so all load programs and assert terms are still present.

    See Error Handling

    Return Value:

    OK if successful.

    lsRetract

    Description:

    TF Retract(TERM term);
    TF lsRetract(ENGid cureng, TERM term);

    cureng
    Current engine identifier
    term
    Term to retract

    Remarks:

    Retracts the first term in the database that unifies with the specified term; term has the unified value, so lsRetract() can be used to retrieve and process terms as they're being retracted.

    See Asserting and Retracting to and from the Prolog Database

    Return Value:

    TRUE/FALSE

    Example:

    lsRetractStr

    Description:

    TF RetractStr(STRptr str);
    TF lsRetractStr(ENGid cureng, STRptr str);

    cureng
    Current engine identifier
    str
    String representation of term

    Remarks:

    Retracts the first term in the database that unifies with the term represented by the string str.

    See Asserting and Retracting to and from the Prolog Database

    Return Value:

    TRUE/FALSE

    Example:

    lsSetCommandArgs

    Description:

    void SetCommandArgs(int argc, char** argv);
    RC lsSetCommandArgs(ENGid cureng, int argc, char** argv);

    cureng
    Current engine identifier
    argc
    Count of arguments
    argv
    Array of arguments

    Remarks:

    Passes the values of argc and argv to the Prolog engine so it can process command line arguments if desired. It is necessary to do this if the Prolog code uses the predicate 'command_line/1'.

    See Miscellaneous API Functions

    Return Value:

    OK

    Example:

    lsSetInput

    Description:

    void SetInput(int (* mygetc)(VOIDptr vp), void(*myungetc)(VOIDptr vp, int c));
    RC lsSetInput(ENGid cureng, int (* mygetc)(VOIDptr vp), void(*myungetc)(VOIDptr vp, int c));

    cureng
    Current engine identifier
    mygetc
    A function that gets a character
    myungetc
    A function that ungets the last character

    Remarks:

    When any input stream is set to 3, Amzi! Prolog uses these functions for reading user input from that stream.

    See Capturing Prolog I/O

    Return Value:

    OK if it worked.

    lsSetIOArg

    Description:

    void SetIOArg(VOIDptr vp);
    RC lsSetIOArg(ENGid cureng, VOIDptr vp);

    cureng
    Current engine identifier
    vp
    The argument to include in I/O calls

    Remarks:

    When any input stream is set to 3, the vp argument is included in the calls to the getc, ungetc, putc and puts functions defined by lsSetInput() and lsSetOutput().

    See Capturing Prolog I/O

    Return Value:

    OK if it worked.

    lsSetOutput

    Description:

    void SetOutput(void (*myputc)(VOIDptr vp, int c), void (*myputs)(VOIDptr vp, STRptr s));
    RC lsSetOutput(ENGid cureng, void (*myputc)(VOIDptr vp, int c), void (*myputs)(VOIDptr vp, STRptr s));

    cureng
    Current engine identifier
    myputc
    A function that puts a character
    myputs
    A function that puts a string

    Remarks:

    When any output stream is set to 3, Amzi! Prolog uses these functions for writing to the stream.

    See Capturing Prolog I/O

    Return Value:

    OK if it worked.

    lsSetStream

    Description:

    SetStream(STREAM stream, int handle);
    RC lsSetStream(ENGid cureng, STREAM stream, int handle);

    cureng
    Current engine identifier
    stream
    The stream to set
    handle
    The handle to set it to

    Remarks:

    Sets the stream to the integer handle. Typically this will be used to set the stream to 3, reserved for user-defined function I/O. It might also be used to reset the stream to its old value, obtained from a prior call to lsGetStream(). See the section on Data Types for the legal values of STREAM.

    See Capturing Prolog I/O

    Return Value:

    OK if it worked.

    lsStrArgLen

    Description:

    int StrArgLen(TERM term, int iarg);
    int lsStrArgLen(ENGid cureng, TERM term, int iarg);

    cureng
    Current engine identifier
    term
    Term defining a structure
    iarg
    Number of the structure argument

    Remarks:

    Used to determine the length of string to be returned from a lsGetArg() where the argument is either a string or an atom.

    See Mapping Prolog Arguments to Host Variables

    Return Value:

    The length of the string/atom at the iargth parameter, or NOTOK (-1) if term is not a string.

    lsStrParmLen

    Description:

    int StrParmLen(int iparm);
    int lsStrParmLen(ENGid cureng, int iparm);

    cureng
    Current engine identifier
    iparm
    Number of the parameter

    Remarks:

    Used to determine the length of string to be returned from a lsGetParm() where the parameter is either a string or an atom.

    See Writing Extended Predicates

    Return Value:

    The length of the string/atom at the iparmth parameter, or NOTOK (-1) if term is not a string.

    lsStrTermLen

    Description:

    int StrTermLen(TERM term);
    int lsStrTermLen(ENGid cureng, TERM term);

    cureng
    Current engine identifier
    term
    Term representing a string

    Remarks:

    Used to determine the length of string to be returned from a lsGetTerm() or lsGetHead() where the parameter is either a string or an atom.

    See String Passing Interface

    Return Value:

    The length of the string/atom at the iparmth parameter, or NOTOK (-1) if term is not a string.

    lsStrToTerm

    Description:

    void StrToTerm(TERMptr termp, STRptr str);
    RC lsStrToTerm(ENGid cureng, TERMptr termp, STRptr str);

    cureng
    Current engine identifier
    termp
    Pointer to term created from string
    str
    String to be used to generate a term

    Remarks:

    Reads the string and creates a term from it.

    See Calling Terms

    Return Value:

    OK if it worked.

    Example:

    lsTermToStr

    Description:

    void TermToStr(TERM term, STRptr str, int len);
    RC lsTermToStr(ENGid cureng, TERM term, STRptr str, int len);

    cureng
    Current engine identifier
    term
    Term to translate to a string
    str
    Pointer to string buffer to hold value
    len
    Length of string buffer, used to prevent overflows

    Remarks:

    Writes the term to the string which is len bytes long.

    See String Passing Interface

    Return Value:

    OK if it worked.

    Example:

    lsTermToStrQ

    Description:

    void TermToStrQ(TERM term, STRptr, str, int len);
    RC lsTermToStrQ(ENGid cureng, TERM term, STRptr str, int len);

    cureng
    Current engine identifier
    term
    Term to translate to a string
    str
    Pointer to string buffer to hold value
    len
    Length of string buffer, used to prevent overflows

    Remarks:

    This function is the same as lsTermToStr(), except the string is created with quoted atoms where necessary. This makes it possible to feed the same string back to Prolog.

    See String Passing Interface

    Return Value:

    OK if it worked.

    lsUnify

    Description:

    TF Unify(TERM term1, TERM term2);
    TF lsUnify(ENGid cureng, TERM term1, TERM term2);

    cureng
    Current engine identifier
    term1
    Term to unify
    term2
    Term to unify

    Remarks:

    Unifies the two terms. lsUnify() does a full Prolog unification between the two terms. Unlike other functions which return TF, lsUnify() does not set and reset Prolog break and error handling.

    See Manipulating Structures

    Return Value:

    TRUE/FALSE depending on whether the unification succeeded or failed.

    lsUnifyArg

    Description:

    TF UnifyArg(TERMptr termp, int iarg, cTYPE ctype, VOIDptr valp);
    TF lsUnifyArg(ENGid cureng, TERMptr termp, int iarg, cTYPE ctype, VOIDptr valp);

    cureng
    Current engine identifier
    termp
    Pointer to the structure term whose argument is to be set
    iarg
    The number of the argument, starting at 1
    ctype
    The type of the variable
    valp
    Pointer to the variable

    Remarks:

    Used to build complex terms, lsUnifyArg() lets you individually set the arguments of term. Used in conjunction with lsMakeFA(), as well as Prolog terms picked up from calls to Prolog.

    See Manipulating Structures

    Return Value:

    TRUE/FALSE depending on whether the unification succeeded or failed.

    Example:

    lsUnifyParm

    Description:

    TF UnifyPartm(int iparm, cTYPE ctype, VOIDptr valp);
    TF lsUnifyParm(ENGid cureng, int iparm, cTYPE ctype, VOIDptr valp);

    cureng
    Current engine identifier
    iparm
    The number of the parameter to set, starting at 1
    ctype
    The type of the variable
    valp
    A pointer to the variable

    Remarks:

    Unify the iparmth parameter of an extended predicate with the 'variable. Note that there are two types for representing strings, cATOM and cSTR. While they are both strings, they unify as either a Prolog atom or a Prolog string depending on which is used.

    See Writing Extended Predicates

    Return Value:

    TRUE/FALSE depending on whether the unification succeeded or failed.

    Example:

    Copyright ©1987-2000 Amzi! inc. All Rights Reserved.