C Connector

Use the Host Integrator C connector to create C or non-COM C++ applications for Windows- or UNIX-based development platforms that integrate host data into web applications or client/server applications.

The interfaces supported in the Host Integrator COM connector are not available in the AppConn C connector. Instead, the connector implements a session interface, which includes all of the methods included in the IAppConnTable, IAppConnModel, IAppConnTerm, and IAppConnChannel interfaces. Use the CreateSession method in the AppConn C connector to create a session object.

Intended Audience

This manual is written for developers who are familiar with developing C or C++ applications on UNIX or Windows-based development platforms.

Getting Started

The C API requires inclusion of appconnapi.h*- and appconndef.h- in the source file. The file appconnapi.h- contains the AppConn API function definitions, and *appconndef.h- contains AppConn enum and constant definitions.

Accessing host data
Building a C application
Error handling

Linking C API Programs With the AppConn Shared Library

In order to link a C API program with an AppConn shared library, you must declare the library in the PATH variable. Declaring the PATH variable is handled differently on each platform.

On Windows

Programs using the AppConn C API must link to:

appconn.dll which implements the AppConn C API functions. Appconn.dll is installed in your \Winnt\system32 directory
appconn.lib which contains the linkage definitions necessary to use the AppConn C API functions in appconn.dll, is installed in your <install directory>\lib directory

On Linux

Programs on Linux that use the AppConn C API must link with the libappconn.so located where the AppConn C API functions are implemented.

When using the AppConn C API, the directory where the libappconn is located must be declared in the library variable. For example:

 LD_LIBRARY_PATH=`{/usr/local<install directory>/lib} (Linux)`
    export LD_LIBRARY_PATH  (Linux)

The library file associated with the AppConn C API is installed in your <install directory>/lib directory.

Creating C API Objects

The C API uses C mechanisms at the interface level. C API objects are created with CreateXXX functions, which return a handle to the object. The handle is used as the first parameter to functions that perform methods on the object. The objects must be destroyed with ReleaseXXX functions. For example, use the following code to create a session object to interact with the Host Integrator Server:

  SessionHandle hSess;
   hSess = CreateSession();
  ReleaseSession(hSess);
  ```

The C API functions use the following four basic types:

- **int**- is used for boolean values.
- **long**- is used for numeric values.
- **CharType**- - is used for string values and is defined as char *, but may also be defined as wchar_t in the future.
- **Handles**- are defined for each of the C API objects. The handles are all defined as void *, so a handle can be assigned to any other handle type; however, the handle will be checked for the proper type whenever it is used in a functional call.

!!! note
    CharType * and handle parameters that are not required may be 0 or null.

```javascript
  int nRet;
  nRet = ConnectToModel(hSess, "localhost", "CCSDemo",
  "bjones", "bjones", 0);
  if (nRet)
   Disconnect(hSess, 0);

Strings are returned from the C API by passing a string buffer and the buffer's length into a function. The actual length of the AppConn string is returned. The C API function will only copy into the buffer up to the length that was given. If the buffer is 0 or null then nothing will be copied. If the size of the buffer that is being returned is known, then the C API function can be called with a static or preallocated buffer. If the size of the buffer is not known, the C API function can be called with a null buffer to get the length of the string. Then, a string buffer can be allocated of that length, and the C API function can be called with that allocated buffer. For example:

    long nLen;
    char szCurrentEntity[80];
    char *pszCurrentEntity;
    nLen = GetCurrentEntity(hSess, szCurrentEntity,
    sizeof(szCurrentEntity));
    nLen = GetCurrentEntity(hSess, 0, 0);
    pszCurrentEntity = new char[nLen + 1];
    GetCurrentEntity(hSess, pszCurrentEntity, nLen);
    Delete [] pszCurrentEntity;

Handles to objects that are returned from C API functions must be released just like objects that are created explicitly. For example:

    StringMapHandle hVariables;
    hVariables = GetModelVariables(hSess);
    ReleaseStringMap(hVariables);`

Error Handling with the C Connector

Errors in function calls are indicated by the return value. If the function returns an int, 0 indicates an error. If the function returns a long, -1 indicates an error. If the function returns a handle, 0 indicates an error. When an error is detected, use GetNumMessages, GetErrorMessage, and GetLocalizedMessage to access the error messages. GetNumMessages returns the number of the error message. GetErrorMessage and GetLocalizedMessage can be used to retrieve each error message. GetLocalizedMessage will return a localized message if localization is enabled, otherwise it will return the default error message.

    long nMessageLen;
    char *strMessage;
    for (int i = 0; i < GetNumMessages(hSess); i++)
    {
       nMessageLen = GetErrorMessage(hSess, i, 0, 0);
       strMessage = malloc(nMessageLen + 1);
       GetErrorMessage(hSess, i, strMessage, nMessageLen);
       printf("Apptrieve error: %s\n", strMessage);
       free(strMessage);
    }

Fork Considerations on UNIX

There are restrictions to the use of the fork() system call when using the AppConn C for UNIX connector. The fork() system call cannot be used while any AppConn session handles are held by the user's application. The system call may be used prior to creating a session with CreateSession() or after all session handles have been released with ReleaseSession().

Example

A C sample application, based on the Consolidated Credit Services (CCSDemo) mainframe application, is included in the AppConn C API installation; however, all the principles and methodology described in the sample application are equally applicable to any other host application.

The sample application, called CCSTutor, performs the following operations:

Allows the user to connect to the server.
Allows the user to login to the host.
Provides the user with the ability to look up customers by their account number or name to review their account information.

For Windows, the complete source code of CCSTutor can be found in the <VHI install folder>\examples\C-Sample folder. For UNIX, the complete source code of CCSTutor can be found in the /usr/local/vhi/examples/C-Sample directory. Use the command line to open the project called CCSTutor.cpp.

To access data using CCSTutor, use the following search criteria:

Userid: bjones
Password: bjones
Last name: smith
First initial: c
State: ri
Account number: 167439459

Note

The data is case sensitive.

AppConn C Method Reference

Click a link below for any AppConn C method.

<a name="create-session"></a>

CreateSession

Create an AppConn session.

SessionHandle CreateSession();

Return Value

A handle to a Host Integrator session.

<a name="connect-to-model"></a>

ConnectToModel

Method used to establish a connection to a Host Integrator Server and create or allocate a host session with the specified model. The model must be specified.

int ConnectToModel (SessionHandle hSession, const CharType *strServer, const CharType *strModelName, const CharType *strUserID, const CharType *strPassword, StringMapHandle hModelVariables);

Parameters

hSession

[in] The Host Integrator session.

strServer

[in] The name of the Host Integrator Server to connect to.

strModelName

[in] The name of the Host Integrator model to use.

strUserID

[in] The user ID that Host Integrator uses to authenticate the user.

strPassword

[in] The password that Host Integrator uses to authenticate the user.

hModelVariables

[in] An optional list of variable names paired with values (handle to a StringMap Object).

Return Value

A 1 is returned if the function succeeds, and a 0 is returned if the function does not succeed.

Remarks

Reasons for failure include:

Server is not running.
Invalid server address.
Invalid model name.
Invalid user ID or password.

See the Error Handling topic for details.

The parameters user ID and password are used by Host Integrator Server if the security option is ON.

<a name="connect-model-domain"></a>

ConnectToModelViaDomain

Method used to establish a connection to a Host Integrator Server and create or allocate a host session with the specified model in the specified Host Integrator Domain via a Management server. The model must be specified.

int ConnectToModelViaDomain (SessionHandle hSession, const CharType *strDirectoryServer, const CharType *strDomainName, const CharType *strModelName, const CharType *strUserID, const CharType *strPassword, StringMapHandle hModelVariables);

Parameters

hSession

[in] The Host Integrator session.

strDirectoryServer

[in] The name of the Directory Server.

strDomainName

[in] The name of the Host Integrator Domain to use.

strModelName

[in] The name of the Host Integrator model to use.

strUserID

[in] The user ID that Host Integrator uses to authenticate the user.

strPassword

[in] The password that Host Integrator uses to authenticate the user.

hModelVariables

[in] An optional list of variable names paired with values (handle to a StringMap Object).

Return Value

A 1 is returned if the function succeeded, and 0 if the function did not succeed.

Remarks

Reasons for failure include:

Server is not running.
Invalid server address.
Invalid model name.
Invalid user ID or password.

See the Error Handling topic for details.

The parameters user ID and password are used by Host Integrator Server if the security option is ON.

ConnectToSession

Method used to establish a connection to a Host Integrator Server and create or allocate a host session with the specified session. The session must be specified.

int ConnectToSession (SessionHandle hSession, const CharType *strServer, const CharType *strSession, const CharType *strUserID, const CharType *strPassword, StringMapHandle hModelVariables);

Parameters

hSession

[in] The Host Integrator session.

strServer

[in] The name of the Host Integrator Server to connect to.

strSession

[in] The name of the Host Integrator session to use.

strUserID

[in] The user ID that Host Integrator uses to authenticate the user.

strPassword

[in] The password that Host Integrator uses to authenticate the user.

hModelVariables

[in] An optional list of variable names paired with values (handle to a StringMap Object).

Return Value

A 1 is returned if the function succeeds, and 0 is returned if the function does not succeed.

Remarks

Reasons for failure include:

Server is not running.
Invalid server address.
Invalid model name.
Invalid user ID or password.

See the Error Handling topic for details.

The parameters user ID and password are used by the Host Integrator Server if the security option is ON.

ConnectToSessionViaDomain

Method used to establish a connection to a Host Integrator Server and create or allocate a host session with the specified session in the specified Host Integrator Domain via a Management server. The session must be specified.

int ConnectToSessionViaDomain (SessionHandle hSession, const CharType *strDirectoryServer, const CharType *strDomainName, const CharType *strSession, const CharType *strUserID, const CharType *strPassword, StringMapHandle hModelVariables);

Parameters

hSession

[in] The Host Integrator session.

strDirectoryServer

[in] The name of the directory server.

strDomainName

[in] The name of the Host Integrator Domain to use.

strSession

[in] The name of the Host Integrator session to use.

strUserID

[in] The user ID that Host Integrator uses to authenticate the user.

strPassword

[in] The password that Host Integrator uses to authenticate the user.

hModelVariables

[in] An optional list of variable names paired with values (handle to a StringMap Object).

Return Value

A flag indicating whether the function succeeded or not.

Remarks

Reasons for failure include:

Server is not running.
Invalid directory server.
Invalid domain.
Invalid session name.
Invalid user ID or password.

See the Error Handling topic for details.

The parameters user ID and password are used by Host Integrator Server if the security option is ON.

Disconnect

Method used to disconnect from a Host Integrator session.

int Disconnect (SessionHandle hSession, int nReserved);

Parameters

hSession

[in] The Host Integrator session.

nReserved

[in] Reserved parameter: use 0.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

Remarks

Reasons for failure include:

Server session has not been established.

See the Error Handling topic for details.

EnableTerminalAttributes

Method used to enable terminal attributes to be returned from the server with model recordsets.

int EnableTerminalAttributes (SessionHandle hSession, int bEnable);

Parameters

hSession

[in] The Host Integrator session.

bEnable

[in] A flag.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

Remarks

Reasons for failure include:

Server session has not been established.

See the Error Handling topic for details.

ExecuteSQLStatement

Method used to execute an SQL statement on a table defined in the model.

RecordSetHandle ExecuteSQLStatement(SessionHandle hSession, const CharType *strSQLStatement);

Parameters

hSession

[in] The Host Integrator session.

strSQLStatement

[in] The SQL statement to execute.

Return Value

A recordset handle which contains the results of the executed SQL statement. If the statement fails the return value is null. The handle must be destroyed with the ReleaseRecordSet method after it is no longer in use.

Remarks

Reasons for failure include:

Server session has not been established.
Unable to fetch rows.

See the Error Handling topic for details.

ExecuteSQLStatementWithMaxrows

Method used to execute an SQL statement on a table defined in the model and specifying maximum number of rows.

RecordSetHandle ExecuteSQLStatementWithMaxrows(SessionHandle hSession, const CharType *strSQLStatement, long maxRows);

Parameters

hSession

[in] The Host Integrator session.

strSQLStatement

[in] The SQL statement to execute.

maxRows

[in] Maximum number of rows to be fetched, or zero if all rows are to be returned.

Return Value

A recordset handle which contains the results of the executed SQL statement. If the statement fails, the return value is -1.

FetchRecords

Method used to fetch up to max rows of data from the Host Integrator Server for the current recordSet of the current entity. If the number of rows to fetch is specified as 0 then the number of rows returned is not limited. If this is the first fetch following an explicit position of the current record, fetchRecords includes the current record in the returned set of records. Otherwise, the set of records returned begins with the first record following the current record. After a fetchRecords, the current record is the last record included in returned set of records. If fieldNames is null, fetchRecords returns all fields for each record.

RecordSetHandle FetchRecords(SessionHandle hSession, long nMaxRows, StringListHandle hFieldNames, const CharType *strFilterExpression);

Parameters

hSession

[in] The Host Integrator session.

nMaxRecords

[in] The maximum number of rows to return with the fetch.

hFieldNames

[in] List of the field names to fetch from the entity

strFilterExpression

[in] An expression that qualifies the records to fetch. See Using Filter Expressions.

Return Value

A recordset handle which contains the results of the fetch. If the statement fails the return value is null. The handle must be destroyed with the ReleaseRecordSet method after it is no longer in use.

Remarks

Reasons for failure include:

Server session has not been established.
Unable to fetch rows.

See the Error Handling topic for details.

GetAttributeAtCursor

Method used to get the name of the attribute at the current cursor position. This method returns the length of the attribute name string that was copied into the strAttributeName parameter. If the cursor is not at a defined attribute, the return value is 0 and thestrAttributeName parameter is set to "".

long GetAttributeAtCursor(SessionHandle hSession, CharType *strAttributeName, long nBufferLen);

*Parameters8

hSession

[in] The Host Integrator session.

strAttributeName

[out] Buffer to retrieve the attribute name.

nBufferLen [in] The length of the buffer.

*Return Value8

The length of the attribute name retrieved.

GetAttributeMetaData

Method used to get a metadata object for an attribute for an entity in the Host Integrator model.

AttributeMetaDataHandle GetAttributeMetaData(SessionHandle hSession, const CharType *strEntityName, const CharType *strAttributeName);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] Name of the entity in the Host Integrator model.

strAttributeName

[in] Name of the attribute of the entity in the Host Integrator model.

Return Value

A attribute metadata handle which contains the metadata for the given entity and attribute. If the statement fails the return value is null. The handle must be destroyed with the ReleaseMetaData method after it is no longer in use.

GetAttributes

Method used to get the attributes of the current entity. If attributeNames is null, getAttributes returns all attributes of the entity.

RecordHandle GetAttributes(SessionHandle hSession, StringListHandle hAttributeNames);

Parameters

hSession

[in] The Host Integrator session.

hAttributeNames

[in] List of attribute names to get from the entity.

Return Value

A record handle which contains the attributes on the current entity. If the attributes names parameter is non-null, then only named attributes are retrieved. If the statement fails the return value is null. The handle must be destroyed with the ReleaseRecord method after it is no longer in use.

GetColumnMetaData

Method used to get a metadata object for a column of a table in the Host Integrator model. The handle must be destroyed with the ReleaseMetaData method after it is no longer in use.

ColumnMetaDataHandle GetColumnMetaData(SessionHandle hSession, const CharType *strTableName, const CharType *strColumnName);

Parameters

hSession

[in] The Host Integrator session.

strTableName

[in] Name of the table in the Host Integrator model.

strColumnName

[in] Name of the column of the table in the Host Integrator model.

Return Value

A column metadata handle which contains the metadata for the given table and column. If the statement fails the return value is null. The handle must be destroyed with the ReleaseMetaData method after it is no longer in use.

GetConnectionTimeout

Gets how long Host Integrator continues attempting to establish a connection if for any reason the connection cannot be established on the first try (in seconds).

The default value is 30 seconds.

long GetConnectionTimeout(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

The timeout value for connections.

GetCurrentEntity

Method used to get the current entity (i.e. screen) of the legacy application.

long GetCurrentEntity(SessionHandle hSession, CharType *strEntityName, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[out] Buffer to retrieve the entity name.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the entity name retrieved. If there is an error -1 is returned.

GetCurrentRecord

Method used to get the current record in the current recordSet.

RecordHandle GetCurrentRecord(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

A record handle which contains the contents of the current record. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseRecord method after it is no longer in use.

GetCurrentRecordIndex

Method used to get the index number of the current record in the current recordSet.

long GetCurrentRecordIndex(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

The index of the current record.

GetCurrentRecordSetName

Method used to get the name of the current recordSet.

long GetCurrentRecordSetName(SessionHandle hSession, CharType *strRecordSetName, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strRecordSetName

[out] Buffer to retrieve the recordset name.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the recordset name retrieved. If there is an error -1 is returned.

GetEntityAttributes

Method used to get the attribute names of an entity in the Host Integrator model.

StringListHandle GetEntityAttributes(SessionHandle hSession, const CharType *strEntityName);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] Name of the entity in the Host Integrator model.

Return Value

A string list handle which contains the names of the entity attributes. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetEntityDescription

Method used to get the description for an entity in the Host Integrator model.

long GetEntityDescription(SessionHandle hSession, const CharType *strEntityName, CharType*strDescription, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] The display offset.

strDescription

[out] Buffer to retrieve the entity description.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the entity description retrieved. If there is an error -1 is returned.

GetEntityOperations

Method used to get the operation names of an entity in the Host Integrator model.

StringListHandle GetEntityOperations(SessionHandle hSession, const CharType *strEntityName);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] Name of the entity in the Host Integrator model.

Return Value

A string list handle which contains the names of the entity operations. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetEntityRecordSets

Method used to get the recordset names of an entity in the Host Integrator model.

StringListHandle GetEntityRecordSets(SessionHandle hSession, const CharType *strEntityName);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] Name of the entity in the Host Integrator model.

Return Value

A string list handle which contains the names of the entity recordsets. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetErrorScreen

Returns a handle to access a terminal screen dump made when an error was reported. If a non-zero handle is returned by this function, it must be released after use.

ErrorScreenHandle GetErrorScreen(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

ErrorScreenHandle. This is a non-zero value if there is an error screen available.

GetErrorScreenColumns

Returns the number of columns in an error screen.

int GetErrorScreenColumns(ErrorScreenHandle hErrorScreen);

Parameters

ErrorScreenHandle

Handle for the error screen.

Return Value

Number of columns, or zero if there is no error screen

GetErrorScreenCursorColumn

Returns the zero-based column position of the cursor of an error screen.

int GetErrorScreenCursorColumn(ErrorScreenHandle hErrorScreen);

Parameters

ErrorScreenHandle

Handle for the error screen.

Return Value

Zero-based column position, or -1 if there is no error screen.

GetErrorScreenCursorPosition

Returns the zero-based cursor offset an error screen.

int GetErrorScreenCursorPosition(ErrorScreenHandle hErrorScreen);

Parameters

ErrorScreenHandle

Handle for the error screen.

Return Value

Zero-based cursor offset, or -1 if there is no error screen.

GetErrorScreenCursorRow

Returns the zero-based row position an error screen.

int GetErrorScreenCursorRow(ErrorScreenHandle hErrorScreen);

Parameters

ErrorScreenHandle

Handle for the error screen.

Return Value

Zero-based row position, or -1 if there is no error screen.

GetErrorScreenEntityName

Returns the entity name, if there is one, for an error screen.

int GetErrorScreenEntityName(ErrorScreenHandle hErrorScreen, CharType *strEntityName, long nBufferLen);

Parameters

ErrorScreenHandle

Handle for the error screen.

StrEntityName

Buffer to receive the entity name.

nBufferLen

Maximum number of characters the buffer can accept, including the terminating NUL character.

Return Value

Number of characters in the entity name, zero if there is no entity, or -1 if there is no error screen.

GetErrorScreenRows

Returns the number of rows in an error screen.

int GetErrorScreenRows(ErrorScreenHandle hErrorScreen);

Parameters

ErrorScreenHandle

Handle for the error screen.

Return Value

Number of rows in an error screen, or zero if there is no error screen.

GetErrorScreenFullText

Returns all of the screen text from an error screen.

int GetErrorScreenFullText(ErrorScreenHandle hErrorScreen, CharType *strText, long nBufferLen);

Parameters

ErrorScreenHandle

Handle for the error screen.

strText

Buffer to receive the text.

nBufferLen

Maximum number of characters the buffer can accept, including the terminating NUL character. A good number would be rows - columns +1.

Return Value

Number of characters returned, or zero if there is no error screen.

GetErrorScreenText

Returns a selected portion of the screen text from an error screen.

int GetErrorScreenText(ErrorScreenHandle hErrorScreen,int offset, int length, CharType *strText, long nBufferLen);

Parameters

ErrorScreenHandle

Handle for the error screen.

offset

Zero-based offset within the error screen for the selected text.

length

Number of characters of text to be obtained.

strText

Buffer to receive the text.

nBufferLen

Maximum number of characters the buffer can accept, including the terminating NUL character. Ideally, this would be length + 1.

Return Value

Number of characters returned, or zero if there is no error screen.

GetErrorScreenTextRow

Returns a single row of text from an error screen.

int GetErrorScreenTextRow(ErrorScreenHandle hErrorScreen,int row, CharType *strText, long nBufferLen);

Parameters

ErrorScreenHandle

Handle for the error screen.

row

Zero-based row index for which the text is obtained.

strText

Buffer to receive the text.

nBufferLen

Maximum number of characters the buffer can accept, including the terminating NUL character. Ideally, this would be number of columns + 1.

Return Value

Number of characters returned, or zero if there is no error screen.

GetFieldMetaData

Method used to get a metadata object for a field for an entity recordset in the Host Integrator model.

FieldMetaDataHandle GetFieldMetaData(SessionHandle hSession, const CharType *strEntityName, const CharType*strRecordSetName, const CharType *strFieldName);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] Name of the entity in the Host Integrator model.

strRecordSetName

[in] Name of the recordset.

strFieldName

[in] Name of the field.

Return Value

A field metadata handle which contains the metadata for the given field on the given recordset for the given entity. If the statement fails the return value is null. The handle must be destroyed with the ReleaseMetaData method after it is no longer in use.

GetLastRequestID

Method used to get an integer identifier for the most recent transaction performed against the current Host Integrator Server Session.

long GetLastRequestID(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

A unique id for the last request performed against the server. If a request has not yet been performed in the current session, this method returns 0. If not connected, this method returns -1.

GetMethodTimeout

Method used to get the method timeout for an Host Integrator Server Session.

long GetMethodTimeout(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

The timeout value for methods.

GetModelEntities

Method used to get the entity names of the legacy application.

StringListHandle GetModelEntities(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

A string list handle which contains the names of the entities for the Host Integrator model. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetModelName

Method used to get the name of the Host Integrator model for the current session.

long GetModelName(SessionHandle hSession, CharType *strModelName, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strModelName

[out] Buffer to retrieve the model name.

nBufferLen

[in] The string length.

Method used to get an integer identifier for the current Host Integrator Server Session.

long GetSessionID(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

A unique id for the session established with the server. If a session has not yet been established, this method returns 0.

GetSessionType

Gets the terminal emulation type of the host session.

The returned value can be:

SessionType3270 (1)
SessionType5250 (2)
SessionTypeVT (3)
SessionTypeHP (4)

long GetSessionType(SessionHandle hSessionType);

Parameters

hSessionType

[in] The Host Integrator session.

Return Value

The session type. If there is an error, -1 is returned.

GetStringAtOffset

Get the string at the given offset of the given length.

long GetStringAtOffset(SessionHandle hSession, long nOffset, long nLength, CharType *strString, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

nOffset

[in] The offset on the entity (i.e. terminal screen)..

nLength

[in] The string length.

strString

[out] Buffer to retrieve the string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the string retrieved. If there is an error -1 is returned.

GetStringAtRowColumn

Method used to get a string of the given length from the current entity on the host session starting at a given row and column.

long GetStringAtRowColumn(SessionHandle hSession, long nTopRow, long nLeftColumn, long nNumRows, long nNumColumns, CharType *strString, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

nTopRow

[in] The starting row on the entity (i.e. terminal screen).

nLeftColumn

[in] The starting column on the entity (i.e. terminal screen).

nNumRows

[in] The number of rows to get relative to the starting row.

nNumColumns

[in] The number of columns to get relative to the starting column.

strString

[out] Buffer to retrieve the string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the string retrieved. If there is an error -1 is returned.

GetTableColumns

Method used to get the column names of a table.

StringListHandle GetTableColumns(SessionHandle hSession, const CharType *strTableName);

Parameters

hSession

[in] The Host Integrator session.

strTableName

[in] Name of the table in the Host Integrator model.

Return Value

A string list handle which contains the names of the columns for the given table. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetTableDescription

Method used to get the description for a table in the Host Integrator model.

long GetTableDescription(SessionHandle hSession, const CharType *strTableName, CharType*strDescription, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strTableName

[in] Name of the table in the Host Integrator model.

strDescription

[out] Buffer to retrieve the description.

nBufferLen

[in] The length of the buffer.

Return Value

Method used to insert a string into the current entity on a host session starting at an offset.

int InsertStringAtOffset(SessionHandle hSession, const CharType *strString, long nOffset);

Parameters

hSession

[in] The Host Integrator session.

strString

[in] The string.

nOffset

[in] The offset on the entity (i.e. terminal screen).

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

InsertStringAtRowColumn

Method used to insert a string into the current entity on the host session starting at the given row and column.

int InsertStringAtRowColumn(SessionHandle hSession, const CharType *strString, long nRowNum, long nColumnNum);

Parameters

hSession

[in] The Host Integrator session.

strString

[in] The string.

nRowNum

[in] The row number of the string on the entity (i.e. terminal screen).

nColumnNum

[in] The column number of the string on the entity (i.e. terminal screen).

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

IsConnected

Method used to determine if the Host Integrator Server Session is connected.

int IsConnected(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

An integer value indicating whether or not the session is connected(true = !0, false = 0).

IsSecureConnection

Method used to determine if the Host Integrator Server Session is using an encrypted connection.

int IsSecureConnection(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

An integer value indicating whether or not the connection is encrypted (true = !0, false = 0).

MoveCurrentRecordIndex

Method used to move the current record index to a new position in the current recordSet.The movementCode can be one of the following enumerated values defined in appconndef.h:

ScrollHome
ScrollEnd
ScrollLineUp
ScrollLineDown
ScrollPageUp
ScrollPageDown

int MoveCurrentRecordIndex(SessionHandle hSession, unsigned long nMovement);

Parameters

hSession

[in] The Host Integrator session.

nMovement

[in] The enumerated value for the type of movement to perform.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

NextRecord

Method used to get the next record in the current recordSet

RecordHandle NextRecord(SessionHandle hSession, const CharType *strFilterExpression);

Parameters

hSession

[in] The Host Integrator session.

strFilterExpression

[in] An expression that qualifies the conditions for the next record. See Using Filter Expressions.

Return Value

A record handle which contains the fields of the next record. If the statement fails the return value is null. The handle must be destroyed with the ReleaseRecord method after it is no longer in use.

PerformAidKey

Method used to enter an aid key (for example, a Program Function key) into the current host session. The key is one of the terminal key enumerated values defined in appconndef.h.

int PerformAidKey(SessionHandle hSession, unsigned long nKey);

Parameters

hSession

[in] The Host Integrator session.

nKey

[in] The enumerated value for the perform. aid key.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

PerformEntityOperation

Method used to perform an operation on the current entity.

int PerformEntityOperation(SessionHandle hSession, const CharType *strOperationName);

Parameters

hSession

[in] The Host Integrator session.

strOperationName

[in] The operation name.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

PerformTableProcedure

Method used to perform a procedure on a table defined in the model. hDataInputValues are required only for update and insert procedures, while hFilterValues are required for all procedures except update. If hOutputColumnNames is non-null, then the names in this supplied list determine which table columns are returned in the resulting AppConnRecordSet.If nMaxRows is zero then the number of rows returned is unlimited.

RecordSetHandle PerformTableProcedure(SessionHandle hSession, const CharType *strTableName, const CharType*strProcedureName, StringMapHandle hDataInputValues, StringMapHandle hFilterValues, int bFilterIsCaseSensitive, StringListHandle hOutputColumnNames, long nMaxRows);

Parameters

hSession

[in] The Host Integrator session.

strTableName

[in] Name of the table in the Host Integrator model.

strProcedureName

[in] Name of the table procedure to perform.

hDataInputValues

[in] Set of data input column name-value pairs to use.

hFilterValues

[in] Set of filter column name-value pairs to use.

bFilterIsCaseSensitive

[in] Integer value used to determine if comparison is case sensitive(true = !0, false = 0)..

hOutputColumnNames

[in] List of the column names of the entity to return as output.

nMaxRows

[in] The maximum number of rows to be returned.

Return Value

A recordset handle which contains the results of the procedure. If the statement fails the return value is null. The handle must be destroyed with the ReleaseRecordSet method after it is no longer in use.

RequireSecureConnection

This method is kept for backwards compatibility. Connections to a Host Integrator Server are always encrypted.

int RequireSecureConnection(SessionHandle hSession, int bRequire);

Parameters

hSession

[in] The Host Integrator session.

bRequire

[in] Integer value used require secure connection(true = !0, false = 0).

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ResumeConnection

Method used to resume the execution of a currently suspended Host Integrator server session. If the requested session is already running, this method does nothing.

int ResumeConnection(SessionHandle hSession, const CharType *strConnectionToken);

Parameters

hSession

[in] The Host Integrator session.

strConnectionToken

[in] The token received from the SuspendConnection method.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

SelectCurrentRecord

Method used to perform the selection operation for the current recordset.

int SelectCurrentRecord(SessionHandle hSession);

Method used to set the attributes of an entity. The map contains attributes (name/value pairs) that are to be set in the entity. The map does not need to contain all of the attributes for the entity, but should contain all of the required attributes for the entity. If the entity is not specified then the current entity is used.

int SetAttributesDelayed(SessionHandle hSession, StringMapHandle hAttributes, const CharType *strEntityName);

Parameters hSession [in] The Host Integrator session. hAttributes [in] A map containing attributes (name/value pairs). strEntityName [in] Name of the entity in the Host Integrator model. Return Value An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

SetConnectionTimeout

Method used to specify how long Host Integrator continues attempting to establish a connection if for any reason the connection cannot be established on the first try (in seconds).

This method is useful, for example, if the server is temporarily unable to allow any more sessions, or if the domain load has been reached. Connection attempt information, include the number of connection attempts and the time of those attempts, is written to the log.

The default value is 30 seconds.

int SetConnectionTimeout(SessionHandle hSession, long nTimeout);

Parameters

hSession

[in] The Host Integrator session.

nTimeout

Defines the current session as a "metadata-only" session. A metadata-only session does not require a host connection and allows only methods and properties that interact with metadata. You must set SetMetaDataOnlyFlag to true before you use a Connect method.

Once a connect method has been called, and before the Disconnect method has been called, any attempt to change the value of the SetMetaDataOnlyFlag property generates an error with this text: "The MetaDataOnly property cannot be changed while a connection is active."

When a client connects with SetMetaDataOnlyFlag set to true, the server does not report the connection as a session, and does not allocate a new session or a session from a pool.

Use the [GetMetaDataOnlyFlag] (need link) property to determine the current value of the metadata-only flag.

Syntax

int SetMetaDataOnlyFlag(SessionHandle hSession, int nMetaDataOnly);

Parameters

hSession

[in] The Host Integrator session.

nMetaDataOnly

[in] An integer value specifying whether or not to set the metadata-only flag (yes = !0, no = 0).

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

Example

void myTestRoutine(void){ SessionHandle hSession; int mdoflag; hSession = CreateSession(); SetMetaDataOnlyFlag(hSession, 1); // Make this a metadata-only connection mdoflag = GetMetaDataOnlyFlag( hSession ); printf("Metadata-only flag = %d\n", mdoflag); ConnectToModel( hSession, srvr, model, userid, password, 0); ... Disconnect(hSession, 0); ReleaseSession( hSession );}

SetMethodTimeout

Method used to set the method timeout for a Host Integrator Server Session.

int SetMethodTimeout(SessionHandle hSession, long nTimeout);

Parameters

hSession

[in] The Host Integrator session.

nTimeout

[in] The timeout period in milliseconds.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

SetModelVariables

Method used to set the values of variables in the Host Integrator model.

int SetModelVariables(SessionHandle hSession, StringMapHandle hVariables);

Parameters

hSession

[in] The Host Integrator session.

hVariables

[in] A collection of name/value pairs for the variables.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

SuspendConnection

Method used to suspend the execution of a currently running Host Integrator Server Persistent Session. On successful suspension, the methods returns a token to be used when resuming the session. If the current session is already suspended, this method does nothing. The suspended session automatically terminates if it is not resumed before the specified timeout period elapses.

long SuspendConnection(SessionHandle hSession, long nTimeout, CharType *strConnectionToken, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

nTimeout

[in] The timeout value to use for the suspended session in minutes.

strConnectionToken

[out] Buffer to retrieve the description.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the connection token retrieved. If there is an error -1 is returned.

UpdateCurrentRecord

Method used to change the values of the current record in the current record set.

int UpdateCurrentRecord(SessionHandle hSession, StringMapHandle hRecord);

Parameters

hSession

[in] The Host Integrator session.

hRecord

Method used to wait for the presence of the terminal cursor at a particular terminal screen offset. Exception occurs if timeout period elapses before the cursor is at the offset.

int WaitForCursor(SessionHandle hSession, long nRowNum, long nColumnNum, long nTimeout);

Parameters

hSession

[in] The Host Integrator session.

nRowNum

[in] The row on the entity (i.e. terminal screen) for the cursor.

nColumnNum

[in] The column on the entity (i.e. terminal screen) for the cursor.

nTimeout

[in] The timeout period in milliseconds.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

WaitForEntityChange

Method used to wait for the recognition of a new entity that is not 'strEntityName'. If entityName is null or empty, the method returns upon recognition of any new entity. Exception occurs if timeout period elapses before the Verastream Server recognizes a new entity.

int WaitForEntityChange(SessionHandle hSession, const CharType *strEntityName, long nTimeout);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[in] The name of the entity that cannot satisfy the entity change condition, typically the entity that was current when the method is called.

nTimeout

[in] The timeout period in milliseconds. Return Value An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

WaitForString

Method used to wait for the presence of a string starting at a particular terminal screen row and column. Exception occurs if timeout period elapses before the string appears at the row and column.

int WaitForString(SessionHandle hSession, const CharType *strString, long nRowNum, long nColumnNum, long nTimeout);

Parameters

hSession

[in] The Host Integrator session.

strString

[in] The string.

*nRowNum8

[in] The row on the entity (i.e. terminal screen) of the beginning of the string.

nColumnNum

[in] The column on the entity (i.e. terminal screen) of the beginning of the string.

nTimeout

[in] The timeout period in milliseconds.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

WaitForStringRelCursor

ethod used to wait for the presence of a string relative to the current terminal screen cursor. Exception occurs if timeout period elapses before the string appears at the offset.

int WaitForStringRelCursor(SessionHandle hSession, const CharType *strString, long nRowOffset, long nColumnOffset, long nTimeout);

Parameters

hSession

[in] The Host Integrator session.

strString

[in] The string.

nRowOffset

[in] The row offset from the cursor (i.e. terminal screen) of the beginning of the string.

nColumnNum

[in] The column offset from the cursor (i.e. terminal screen) of the beginning of the string.

nTimeout

[in] The timeout period in milliseconds.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ReleaseSession

Method used to release an AppConn session.

int ReleaseSession(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

CreateRecordSet

Create an AppConn recordset.

RecordSetHandle CreateRecordSet(void);

Return Value

A handle to a recordset.

CreateRecord

Create an AppConn record.

RecordHandle CreateRecord(void);

Return Value

A handle to a record.

GetRecordIndex

Method used to get Host Integrator recordset index of the record.

long GetRecordIndex(RecordHandle hRecord);

Parameters

hRecord

[in] AppConn record.

Return Value

Method used to get a record of the recordset.

RecordHandle GetRecord(RecordSetHandle hRecordSet, long nRecordNo);

Parameters

hRecordSet

[in] An AppConn recordset.

nRecordNo

[in] Index of the record to get.

Return Value

A record handle which contains the fields of the retrieved record. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseRecord method after it is no longer in use.

Indexing of records through the Verastream API is 0-based, so to get the first record in your recordset you do a GetRecord(myRecordSet, 0). (Contrast with [GetRecordIndex] (need link), which uses 1-based indexing.)

GetElementMetaDataByName

Method used to get the metadata for an element in the records of the recordset.

ElementMetaDataHandle GetElementMetaDataByName(RecordSetHandle hRecordSet, const CharType *strElementName);

Parameters

hRecordSet

[in] An AppConn recordset.

strElementName

[in] Name of the element to get the metadata.

Return Value

A metadata handle (column or field depending on the recordset) which contains the metadata for the given element. If the statement fails the return value is null. The handle must be destroyed with the ReleaseMetaData method after it is no longer in use.

GetElementMetaDataByIndex

Method used to get the metadata for an element in the records of the record set.

ElementMetaDataHandle GetElementMetaDataByIndex(RecordSetHandle hRecordSet, long nElementNo);

Parameters

hRecordSet

[in] An AppConn recordset.

nElementNo

[in] Index of the element to get the metadata.

Return Value

A metadata handle (column or field depending on the recordset) which contains the metadata for the given element. If the statement fails the return value is null. The handle must be destroyed with the ReleaseMetaData method after it is no longer in use.

RecordSetToXML

Method used to convert from an AppConn recordset to an XML String.

long RecordSetToXML(RecordSetHandle hRecordSet, const CharType *strDTDURL, CharType *strXMLString, long nBufferLen);

Parameters

hRecordSet

[in] An AppConn recordset.

strDTDURL

[in] The URL of the DTD to be used for the XML result.

strXMLString

[out] Buffer to retrieve the XML string. If strXMLString is passed in as NULL, RecordSetToXML returns the length of buffer necessary to accommodate the XML string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the XML string retrieved. If there is an error -1 is returned.

RecordSetFromXML

Method used to convert from an XML String to an AppConn recordset.

int RecordSetFromXML(RecordSetHandle hRecordSet, const CharType *strXMLString);

Parameters

hRecordSet

[in] An AppConn recordset.

strXMLString

[in] Buffer to retrieve the XML string.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ReleaseRecordSet

MMethod used to release an AppConn recordset. All elements of the recordset are released.

int ReleaseRecordSet(RecordSetHandle hRecordSet);

Parameters

hRecordSet

[in] AppConn recordset.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

CreateRecord

Create an AppConn record.

RecordHandle CreateRecord(void);

Return Value

A handle to a record.

GetRecordIndex

Method used to get Host Integrator recordset index of the record.

long GetRecordIndex(RecordHandle hRecord);

Parameters

hRecord

[in] AppConn record.

Return Value

The Host Integrator recordset index. If record did not come from a recordset the index is -1.

Indexing of records is based on model-runtime indexing, which starts with 1. (Contrast with GetRecord, which uses 0-based indexing). So the index of the first record in a recordset is 1.

GetModelVersionString

Method used to get version information for the current model. The string returned uniquely identifies the version of the model deployed to the Host Integrator Server.

GetModelVersionString(SessionHandle hSession, CharType * strModelVersionString, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strModelVersionString

Method used to get the elements (key/value pairs) in the record.

StringMapHandle GetElements(RecordHandle hRecord);

Parameters

hRecord

[in] AppConn record.

Return Value

A string map handle which contains the names and values for the record. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringMap method after it is no longer in use.

GetTermAttrsByIndex

Method used to get the terminal attributes of an element in the record.

TerminalAttributesHandle GetTermAttrsByIndex(RecordHandle hRecord, long nElementNo);

Parameters

hRecord

[in] AppConn record.

nElementNo

[in] Index of the element to get.

Return Value

A terminal attributes handle for the element. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseTerminalAttributes method after it is no longer in use.

GetTermAttrsByName

Method used to get the terminal attributes of an element in the record.

TerminalAttributesHandle GetTermAttrsByName(RecordHandle hRecord, const CharType *strElementName);

Parameters

hRecord

[in] AppConn record.

strElementName

[in] Name of the element to get.

Return Value

A terminal attributes handle for the element. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseTerminalAttributes method after it is no longer in use.

ProcessString

Calls the ProcessString event handler on the server.

long ProcessString(SessionHandle hSession, const CharType *strIn, const CharType *strOut, long nBufferLen);

hSession

[in] The Host Integrator session.

strIn

[in] The string to be passed to the ProcessString event handler.

strOut

[in] Buffer to retrieve the results returned by the ProcessString event handler.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the results returned from the ProcessString event handler.

RecordToXML

Method used to convert from an AppConn record to an XML String.

long RecordToXML(RecordHandle hRecord, const CharType *strDTDURL, CharType *strXMLString, long nBufferLen);

Parameters

hRecord

[in] AppConn record.

strDTDURL

[in] The URL of the DTD to be used for the XML result.

*strXMLString8

[out] Buffer to retrieve the XML string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the XML string retrieved. If there is an error -1 is returned.

RecordFromXML

Method used to convert from an XML String to an AppConn record.

int RecordFromXML(RecordHandle hRecord, const CharType *strXMLString);

Parameters

hRecord

[in] AppConn record.

strXMLString

[in] Buffer to retrieve the XML string.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ReleaseRecord

Method used to release an AppConn record. All elements of * the record are released.

int ReleaseRecordSet(RecordSetHandle hRecordSet);

Parameters

hRecord

[in] AppConn record.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

CreateStringList

Create an AppConn string list.

StringListHandle CreateStringList(void);

Return Value

A handle to a string list.

CreateStringList

Create an AppConn string list.

StringListHandle CreateStringList(void);

Return Value

A handle to a string list.

AddStringToList

Method used to add a string to the string list.

int AddStringToList(StringListHandle hStringList, const CharType *strString);

Parameters

hStringList

[in] AppConn string list.

strString

[in] String to add to the list.

*Return Value8

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0

ClearStringList

Method used to remove all the strings from the string list.

int ClearStringList(StringListHandle hStringList);

Parameters

hStringList

[in] AppConn string list.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetNumStrings

Method used to get the number of strings in the string list.

long GetNumStrings(StringListHandle hStringList);

Parameters

hStringList

[in] AppConn string list.

Return Value

The number of elements in the AppConn string list.

GetStringAt

MMethod used to get a string in the string list.

long GetStringAt(StringListHandle hStringList, long nIndex, CharType *strString, long nBufferLen);

Parameters

hStringList

[in] AppConn string list.

nIndex

[in] Index of the string to get.

strString

[out] Buffer to retrieve the string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the element retrieved. If there is an error -1 is returned.

ReplaceStringAt

Method used to replace a string in the string list.

int ReplaceStringAt(StringMapHandle hStringMap, long nIndex, const CharType *strString);

Parameters

hStringList

[in] AppConn string list.

nIndex

[in] Index of the string to get.

strString

[in] String to replace the existing entry.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

RemoveStringAt

Method used to remove a string from the string list.

int RemoveStringAt(StringListHandle hStringList, long nIndex);

Parameters

hStringList

[in] AppConn string list.

nIndex

[in] Index of the string to remove.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ReleaseErrorScreen

Release an error screen and free the resources associated with it.

int ReleaseErrorScreen(ErrorScreenHandle hErrorScreen);

Parameters

ErrorScreenHandle

Handle of error screen to be released.

Return Value

1 with success of error screen release, 0 on failure.

ReleaseStringList

Method used to release an AppConn string list. All elements of the string list are released.

int ReleaseStringList(StringListHandle hStringList);

Parameters

hStringList

[in] AppConn string list.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

CreateStringMap

Create an AppConn string map.

StringMapHandle CreateStringMap(void);

Return Value

A handle to a string map.

AddStringToMap

Method used to add a key/value pair to the string map.

int AddStringToMap(StringMapHandle hStringMap, const CharType *strKey, const CharType *strString);

Parameters

hStringMap

[in] AppConn string map.

strstrKeyString

[in] Key to add to the map.

strString

[in] String to add to the map.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ClearStringMap

Method used to remove all the strings from the string map.

int ClearStringMap(StringMapHandle hStringMap);

Parameters

hStringMap

[in] AppConn string map.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetNumStringPairs

Method used to get the number of string/value pairs in the string map.

long GetNumStringPairs(StringMapHandle hStringMap);

Parameters

hStringMap

[in] AppConn string map.

Return Value

The number of elements in the AppConn string map.

GetKey

Method used to get a key in the string map.

long GetKey(StringMapHandle hStringMap, long nIndex, CharType *strKey, long nBufferLen);

Parameters

hStringMap

[in] AppConn string map.

nIndex

[in] Index of the key to get.

strKey

[out] Buffer to retrieve the key.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the key retrieved. If there is an error -1 is returned.

GetStringByIndex

Method used to get a string in the string map.

long GetStringByIndex(StringMapHandle hStringMap, long nIndex, CharType *strString, long nBufferLen);

Parameters hStringMap [in] AppConn string map. nIndex [in] Index of the key to get. strString [out] Buffer to retrieve the string. nBufferLen [in] The length of the buffer. Return Value The length of the string retrieved. If there is an error -1 is returned.

GetStringByKey

Method used to get a string in the string map.

long GetStringByIndex(StringMapHandle hStringMap, long nIndex, CharType *strString, long nBufferLen);

Parameters

hStringMap

[in] AppConn string map.

nIndex

[in] Index of the key to get.

strString

[out] Buffer to retrieve the string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the string retrieved. If there is an error -1 is returned.

ReplaceStringByIndex

Method used to replace a string in the string map.

int ReplaceStringByIndex(StringMapHandle hStringMap, long nIndex, const CharType *strString);

Parameters

hStringMap

[in] AppConn string map.

nIndex

[in] Index of the string to get.

strString

[in] String to replace the existing entry.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ReplaceStringByKey

Method used to replace a string in the string map.

int ReplaceStringByKey(StringMapHandle hStringMap, const CharType *strKey, const CharType *strString);

Parameters

hStringMap

[in] AppConn string map.

strKey

[in] Key of the string to get.

strString

[in] String to replace the existing entry.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

RemoveStringByIndex

Method used to remove a string from the string map.

int RemoveStringByIndex(StringMapHandle hStringMap, long nIndex);

Parameters

hStringMap

[in] AppConn string map.

nIndex

[in] Index of the string to remove.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

RemoveStringByKey

Method used to remove a string from the string map.

int RemoveStringByKey(StringMapHandle hStringMap, const CharType *strKey);

Parameters

hStringMap

[in] AppConn string map.

strKey

Determines whether the current session is "metadata only." A metadata only session does not require a host connection and allows only methods and properties that interact with metadata.

Use [SetMetaDataOnlyFlag] (need link) to set the metadata-only flag.

int GetMetaDataOnlyFlag(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

An integer value indicating whether or not the metadata-only flag is set (true = !0, false = 0).

Example

void myTestRoutine(void){ SessionHandle hSession; int mdoflag; hSession = CreateSession(); SetMetaDataOnlyFlag(hSession, 1); // Make this a metadata-only connection mdoflag = GetMetaDataOnlyFlag( hSession ); printf("Metadata-only flag = %d\n", mdoflag); ConnectToModel( hSession, srvr, model, userid, password, 0); ... Disconnect(hSession, 0); ReleaseSession( hSession );}

GetMetaDataType

Method used to get the metadata type.

The returned value is one of:

AttributeMeta
OperationMeta
RecordSetMeta
FieldMeta
VariableMeta
TableMeta
ColumnMeta
ProcedureMeta

long GetMetaDataType(MetaDataHandle hMetaData);

Parameters

hMetaData

[in] AppConn metadata.

Return Value

The type of the metadata. If there is an error -1 is returned.

ReleaseMetaData

Method used to release an AppConn metadata.

int ReleaseMetaData(MetaDataHandle hMetaData);

Parameters

hStringMap

[in] AppConn string map.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

IsAttributeReadable

Method used to determine if the attribute is readable.

int IsAttributeReadable(AttributeMetaDataHandle hAttributeMetaData);

Parameters

hAttributeMetaData

[in] Attribute metadata.

Return Value

An integer value indicating whether or not the attribute is readable(true = !0, false = 0).

IsAttributeWriteable

MMethod used to determine if the attribute is writeable.

int IsAttributeWriteable(AttributeMetaDataHandle hAttributeMetaData);

Parameters

hAttributeMetaData

Method used to determine if terminal attribute are enabled on the attribute.

int TerminalAttributesEnabled(AttributeMetaDataHandle hAttributeMetaData);

Parameters

hAttributeMetaData

[in] Attribute metadata.

Return Value

An integer value indicating whether or not terminal attributes are enabled(true = !0, false = 0).

IsFieldKey

Method used to determine if the field is a key. A key value is unique for the associated field in the recordset--no other records will have the same value for that field.

int IsFieldKey(FieldMetaDataHandle hFieldMetaData);

Parameters

hFieldMetaData

[in] Field metadata.

Return Value

An integer value indicating whether or not the field is a key(true = !0, false = 0).

IsFieldReadable

Method used to determine if the field is readable--that is, whether the field can be read by a client.

int IsFieldReadable(FieldMetaDataHandle hFieldMetaData);

Parameters

hFieldMetaData

[in] Field metadata.

Return Value

An integer value indicating whether or not the field is readable(true = !0, false = 0).

IsFieldWriteable

Method used to determine if the field is writeable--that is, whether Host Integrator allows this field to have data written to it.

int IsFieldWriteable(FieldMetaDataHandle hFieldMetaData);

Parameters

hFieldMetaData

[in] Field metadata.

Return Value

An integer value indicating whether or not the field is writeable(true = !0, false = 0).

GetFieldLength

Method used to get the length of the field.

long GetFieldLength(FieldMetaDataHandle hFieldMetaData);

Parameters

hFieldMetaData

[in] Field metadata.

Return Value

The length of the attribute. A return value of -1 indicates that the field length is variable.

FieldAttributesEnabled

Method used to determine if terminal attribute are enabled for the field. The terminal attributes enabled flag indicates whether Host Integrator can return the terminal attributes of the field. Terminal attributes specify various properties the text can have, including color, whether the text is blinking, and whether the text is displayed in reverse video.

int FieldAttributesEnabled(FieldMetaDataHandle hFieldMetaData);

Parameters

hFieldMetaData

[in] Field metadata.

Return Value

An integer value indicating whether or not the field attributes are enabled(true = !0, false = 0).

GetColumnType

Method used to get the type of the column.

The returned value can be:

IntegerColumn
TextColumn
FloatColumn

long GetColumnType(ColumnMetaDataHandle hColumnMetaData);

Parameters

hColumnMetaData

[in] Column metadata.

Return Value

The type of the column. If there is an error -1 is returned.

IsColumnKey

Method used to determine if the column is a key.

int IsColumnKey(ColumnMetaDataHandle hColumnMetaData);

Parameters

hColumnMetaData

[in] Column metadata.

Return Value

An integer value indicating whether or not the column is a key(true = !0, false = 0).

GetColumnMin

Method used to get the min for the column. For integer columns the min is the minimum value that can be entered for that column. For text columns the min is the minimum length of a string that can be entered in that column.

long GetColumnMin(ColumnMetaDataHandle hColumnMetaData);

Parameters

hColumnMetaData

[in] Column metadata.

Return Value

The min of the column. If there is an error -1 is returned.

GetColumnMax

Method used to get the max for the column. For integer columns the max is the maximum value that can be entered for that column. For text columns the max is the maximum length of a string that can be entered in that column.

long GetColumnMax(ColumnMetaDataHandle hColumnMetaData);

Parameters

hColumnMetaData

[in] Column metadata.

Return Value

The max of the column. If there is an error -1 is returned.

GetAltDestinations

Method used to get a list of alternative destinations of the operation.

StringListHandle GetAltDestinations(OperationMetaDataHandle hOperationMetaData);

Parameters

hOperationMetaData

[in] Operation metadata.

Return Value

A string list handle which contains the names of the alternative destinations. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetAttributesUsed

Method used to get a list of the attributes used in the operation.

StringListHandle GetAttributesUsed(OperationMetaDataHandle hOperationMetaData);

Parameters

hOperationMetaData

[in] Operation metadata.

Return Value

A string list handle which contains the names of the attributes used in the operation. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetDestination

Method used to get the destination of the operation.

long GetDestination(OperationMetaDataHandle hOperationMetaData, CharType *strDestination, long nBufferLen);

Parameters

hOperationMetaData

[in] Operation metadata.

strDestination

[out] Buffer to retrieve the destination.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the destination retrieved. If there is an error -1 is returned.

IsDefaultOperation

Method used to determine if the operation is the default.

int IsDefaultOperation(OperationMetaDataHandle hOperationMetaData);

Parameters

hOperationMetaData

[in] Operation metadata.

Return Value

An integer value indicating whether or not the operation is the default(true = !0, false = 0).

GetVariablesUsed

Method used to get a list of the variables used in the operation.

StringListHandle GetVariablesUsed(OperationMetaDataHandle hOperationMetaData);

Parameters

hOperationMetaData

[in] Operation metadata.

Return Value

A string list handle which contains the names of the variables used by the operation. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetFilterColumns

Method used to get a list of the filter columns for the procedure.

StringListHandle GetFilterColumns(ProcedureMetaDataHandle hProcedureMetaData);

Parameters

hProcedureMetaData

[in] Procedure metadata.

Return Value

A string list handle which contains the names of the filter columns used by the procedure. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetInputColumns

Method used to get a list of the input columns for the procedure.

StringListHandle GetInputColumns(ProcedureMetaDataHandle hProcedureMetaData);

Parameters

hProcedureMetaData

[in] Procedure metadata.

Return Value

A string list handle which contains the names of the input columns used by the procedure. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetOutputColumns

Method used to get a list of the output columns for the procedure.

StringListHandle GetOutputColumns(ProcedureMetaDataHandle hProcedureMetaData);

Parameters

hProcedureMetaData

[in] Procedure metadata.

Return Value

A string list handle which contains the names of the output columns of the procedure. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetProcedureType

Method used to get the type of the procedure.

The returned value is one of:

DeleteProcedure
UpdateProcedure
SelectProcedure
InsertProcedure

long GetProcedureType(ProcedureMetaDataHandle hProcedureMetaData);

Parameters

hProcedureMetaData

[in] Procedure metadata.

Return Value

Method used to determine if the recordset supports direct inserts.

int SupportsDirectInserts(RecordSetMetaDataHandle hRecordSetMetaData);

Parameters

hRecordSetMetaData

[in] Recordset metadata.

Return Value

An integer value indicating whether or not the recordset supports direct inserts(true = !0, false = 0).

SupportsSelect

Method used to determine if the recordset supports select.

int SupportsSelect(RecordSetMetaDataHandle hRecordSetMetaData); Parameters hRecordSetMetaData [in] Recordset metadata. Return Value An integer value indicating whether or not the recordset supports select(true = !0, false = 0).

GetFieldNames

Method used to get a list of the field names for the recordset.

StringListHandle GetFieldNames(RecordSetMetaDataHandle hRecordSetMetaData);

Parameters

hRecordSetMetaData

[in] Recordset metadata.

Return Value

A string list handle which contains the names of the fields in the recordset. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringList method after it is no longer in use.

GetScrollMovements

Method used to get a list of the scroll movements implemented for the record set.

long GetScrollMovements(RecordSetMetaDataHandle hRecordSetMetaData, long *pnScrollMovements, long nBufferLen);

Parameters

hRecordSetMetaData

[in] Recordset metadata.

pnScrollMovements

[out] Buffer to retrieve the scroll movements.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the scroll movements retrieved. If there is an error -1 is returned.

GetScrollOperation

Method used to get the operation for the given scroll movement.

Scroll Movement values:

ScrollHome
ScrollEnd
ScrollLineUp
ScrollLineDown
ScrollPageUp
ScrollPageDown

long GetScrollOperation(RecordSetMetaDataHandle hRecordSetMetaData, long nScrollMovement, CharType *strScrollOperation, long nBufferLen);

Parameters

hRecordSetMetaData

[in] Recordset metadata.

nScrollMovements

[in] Buffer to retrieve the destination.

strScrollOperation

[out] Buffer to retrieve the scroll operation.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the scroll operation retrieved. If there is an error -1 is returned.

GetDefaultValue

Method used to get the default value of the variable.

long GetDefaultValue(VariableMetaDataHandle hVariableMetaData, CharType *strDefaultValue, long nBufferLen);

Parameters

hVariableMetaData

[in] Variable metadata.

strDefaultValue

[out] Buffer to retrieve the scroll value.

nBufferLen [in] The length of the buffer.

Return Value

The length of the default value retrieved. If there is an error -1 is returned.

GetInitialization

Method used to get the method of initialization for the variable.

The returned value is one of:

AtConnection
ByDefault
Uninitialized

long GetInitialization(VariableMetaDataHandle hVariableMetaData);

Parameters

hVariableMetaData

[in] Variable metadata.

Return Value

The type of initialization for the variable. If there is an error -1 is returned.

IsEncrypted

Method used to determine if the variable is encrypted.

int IsEncrypted(VariableMetaDataHandle hVariableMetaData);

Parameters

hVariableMetaData

[in] Variable metadata.

Return Value

An integer value indicating whether or not the variable is encrypted(true = !0, false = 0).

IsHidden

Method used to determine if the variable is hidden.

int IsHidden(VariableMetaDataHandle hVariableMetaData);

Parameters

hVariableMetaData

[in] Variable metadata.

Return Value

An integer value indicating whether or not the variable is hidden(true = !0, false = 0).

IsReadable

Method used to determine if the variable is readable.

int IsReadable(VariableMetaDataHandle hVariableMetaData);

Parameters

hVariableMetaData

[in] Variable metadata.

Return Value

An integer value indicating whether or not the variable is readable(true = !0, false = 0).

IsWriteable

Method used to determine if the variable is writeable.

int IsWriteable(VariableMetaDataHandle hVariableMetaData);

Parameters

hVariableMetaData

[in] Variable metadata.

Return Value

An integer value indicating whether or not the variable is writeable(true = !0, false = 0).

GetVariableType

Method used to get the type of the variable.

The returned value is one of:

SettingVariable
UserVariable

long GetVariableType(VariableMetaDataHandle hVariableMetaData);

Parameters

hVariableMetaData

[in] Variable metadata.

Return Value

The type of the variable. If there is an error -1 is returned.

IsBlinking

Method to determine it the terminal attribute is blinking.

int IsBlinking(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is blinking(true = !0, false = 0).

IsReverse

Method to determine it the terminal attribute is reverse.

int IsReverse(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is reverse(true = !0, false = 0).

IsUnderscore

Method to determine it the terminal attribute is underscore.

int IsUnderscore(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is underscore(true = !0, false = 0).

IsHalfBrite

Method to determine it the terminal attribute is half brite.

int IsHalfBrite(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is half brite(true = !0, false = 0).

IsProtected

Method to determine it the terminal attribute is protected.

int IsProtected(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is protected(true = !0, false = 0).

IsNumeric

Method to determine it the terminal attribute is numeric.

int IsNumeric(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is numeric(true = !0, false = 0).

IsNondisplay

Method to determine it the terminal attribute is nondisplay.

int IsNondisplay(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is nondisplay(true = !0, false = 0).

IsColumnSeparated

Method to determine it the terminal attribute is column separated.

int IsColumnSeparated(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is column separated(true = !0, false = 0).

IsPenDetect

Method to determine it the terminal attribute is pen detect.

int IsPenDetect(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is pen detect(true = !0, false = 0).

IsIntense

Method to determine it the terminal attribute is intense.

int IsIntense(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

An integer value indicating whether or not the terminal attribute is intense(true = !0, false = 0).

GetColor

Method used to get the terminal attribute's color value.

long GetColor(TerminalAttributesHandle hTerminalAttributes);

Parameters

hTerminalAttributes

[in] Terminal attribute.

Return Value

Method used to the locations for a given set of fields.

ElementLocationListHandle GetFieldLocations(SessionHandle hSession, StringListHandle hFieldNames);

Parameters

hSession

[in] The Host Integrator session.

hPatternNames

[in] Names of the fields to get locations.

Return Value

A element location list handle which contains the element locations for the given attributes. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseElemLocList method after it is no longer in use.

Remarks

Recordset fields are always linear regions.

This method is guaranteed to work correctly only when a record in the recordset is selected. If no record is selected:

For recordsets containing fixed records, the field locations returned are those for the first record in the recordset, based upon the information stored in the model.
For recordsets containing variable-length records, the information returned is not meaningful.

GetRecordSetLocations

Method used to the locations for a given set of recordsets.

ElementLocationListHandle GetRecordSetLocations(SessionHandle hSession, StringListHandle hRecordSetNames);

Parameters

hSession

[in] The Host Integrator session.

hPatternNames

[in] Names of the recordsets to get locations.

Return Value

A element location list handle which contains the element locations for the given attributes. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseElemLocList method after it is no longer in use.

GetHomeEntityName

Get the name of the home entity.

long GetHomeEntityName(SessionHandle hSession, CharType *strEntityName, long nBufferLen);

Parameters

hSession

[in] The Host Integrator session.

strEntityName

[out] Buffer to retrieve the entity name.

nBufferLen

[in] The length of the buffer.

Return Value

Method used to get the logging level for an Host Integrator Server Session.

The returned value is one of:

Errors
ErrorsAndWarnings
All

long GetLoggingLevel(SessionHandle hSession);

Parameters

hSession

[in] The Host Integrator session.

Return Value

The logging level value.

SetLoggingLevel

Method used to set the logging level for a Host Integrator Server Session.

The value to set is one of:

Errors
ErrorsAndWarnings
All

int SetLoggingLevel(SessionHandle hSession, long nLoggingLevel);

Parameters

hSession [in] The Host Integrator session.

nLoggingLevel

[in] The logging level.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

WaitForCondition

Method used to wait on the given conditions. Exception occurs if timeout period elapses before the conditions are met.

int WaitForCondition(SessionHandle hSession, long nTimeout, const CharType *strExpression, const CharType *strEntityName);

Parameters

hSession

[in] The Host Integrator session.

nTimeout

[in] The timeout period in milliseconds.

strExpression

[in] The condition expression.

strEntityName

[in] The entity name.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetElemLocElementName

Method used to get the name of the element location.

long GetElemLocElementName(ElementLocationHandle hElementLocation, CharType *strElementName, long nBufferLen);

Parameters

hElementLocation

[in] Element location.

strElementName

[out] Buffer to name.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the default value retrieved. If there is an error -1 is returned.

GetElemLocElementType

Method used to get the type of the element.

The returned value is one of:

Attribute
Field
Pattern
RecordSet

long GetElemLocElementType(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The type of the element location. If there is an error -1 is returned.

GetElemLocTopRow

Method used to get the top row of the location.

long GetElemLocTopRow(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The top row of the element location. If the region is linear-1 is returned.

GetElemLocLeftColumn

Method used to get the left column of the location.

long GetElemLocLeftColumn(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The left column of the element location. If the region is linear-1 is returned.

GetElemLocNumRows

Method used to get the number of rows of the location.

long GetElemLocNumRows(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The number of rows of the element location. If the region is linear-1 is returned.

GetElemLocNumColumns

Method used to get the number of columns of the location.

long GetElemLocNumColumns(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The number of columns of the element location. If the region is linear-1 is returned.

GetElemLocLength

Method used to get the offset of the location.

long GetElemLocOffset(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The offset of the element location. If the region is rectangular -1 is returned.

GetElemLocRegionType

Method used to get the type of the region.

The returned value is one of:

Linear
Rectangular

long GetElemLocRegionType(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

The type of the region. If there is an error -1 is returned.

ReleaseErrorMessageInfo

Release an ErrorInfoHandle and free resources associated with it.

int ReleaseErrorMessageInfo( ErrorInfoHandle hError );

Parameters

hErrorInfo

ErrorInfoHandle obtained by calling GetErrorMessageInfo()

Return Value

int - (succeeded = !0, failed = 0)

ReleaseElemLoc

Method used to release an Element Location.

int ReleaseElemLoc(ElementLocationHandle hElementLocation);

Parameters

hElementLocation

[in] Element location.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetNumElemLocs

Method used to get the number of element locations in the list.

long GetNumElemLocs(ElementLocationListHandle hElementLocationList);

Parameters

hElementLocationList

[in] An element location list handle.

Return Value

The number of element locations in the list.

GetElemLocAt

Method used to get an element location in the list by index.

ElementLocationHandle GetElemLocAt(ElementLocationListHandle hElementLocationList, long nIndex);

Parameters

hElementLocationList

[in] An element location list handle.

nIndex

[in] Index for an element location.

Return Value

A element location handle. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseElemLoc method after it is no longer in use.

ReleaseElemLocList

Method used to release an Element Location List.

int ReleaseElemLocList(ElementLocationListHandle hElementLocationList);

Parameters

hElementLocationList

[in] Element location list.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetTermFieldTopRow

Method used to get the top row of the terminal field.

long GetTermFieldTopRow(TerminalFieldHandle hTerminalField);

Parameters

hTerminalField

[in] Terminal field.

Return Value

The top row of the terminal field. If there is an error-1 is returned.

GetTermFieldLeftColumn

Method used to get the left column of the terminal field.

long GetTermFieldLeftColumn(TerminalFieldHandle hTerminalField);

Parameters

hTerminalField

[in] Terminal field.

Return Value

The left column of the terminal field. If there is an error-1 is returned.

GetTermFieldOffset

Method used to get the offset of the terminal field.

long GetTermFieldOffset(TerminalFieldHandle hTerminalField);

Parameters

hTerminalField

[in] Terminal field.

Return Value

The offset of the terminal field. If there is an error-1 is returned.

GetTermFieldTermAttr

Method used to the terminal attributes of the terminal field.

TerminalAttributesHandle GetTermFieldTermAttr(TerminalFieldHandle hTerminalField);

Parameters

hTerminalField

[in] Terminal field.

Return Value

A terminal attributes handle. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseTerminalAttributes method after it is no longer in use.

ReleaseTermField

Method used to release a Terminal Field

int ReleaseTermField(TerminalFieldHandle hTerminalField);

Parameters

hTerminalField

[in] Terminal field.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

CreateStringMapSet

Create an AppConn string map list.

StringMapSetHandle CreateStringMapSet(void);

Return Value

A handle to a string map list.

AddStringMapToSet

Method used to add a string map to the string map list.

int AddStringMapToSet(StringMapSetHandle hStringMapSet, const StringMapHandle hStringMap);

Parameters

hStringMapSet

[in] AppConn string map list.

hStringMap

[in] String map to add to the list.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ClearStringMapSet

Method used to remove all the strings maps from the string map list.

int ClearStringMapSet(StringMapSetHandle hStringMapSet);

Parameters

hStringMapSet

[in] AppConn string map list.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetNumStringMaps

Method used to get the number of string maps in the string map list.

long GetNumStringMaps(StringMapSetHandle hStringMapSet);

**Parameters

hStringMapSet

[in] AppConn string map list.

Return Value

The number of elements in the AppConn string map list.

GetStringMapAt

Method used to get a string in the string list.

StringMapHandle GetStringMapAt(StringMapSetHandle hStringMapSet, long nIndex);

Parameters

hStringMapSet

[in] AppConn string map list.

nIndex

[in] Index of the string to get.

Return Value

A string map handle. If the retrieval fails the return value is null. The handle must be destroyed with the ReleaseStringMap method after it is no longer in use.

ReplaceStringMapAt

Method used to replace a string map in the string map list.

int ReplaceStringMapAt(StringMapSetHandle hStringMapSet, long nIndex, const StringMapHandle hStringMap);

Parameters

hStringMapSet

[in] AppConn string map list.

nIndex

[in] Index of the string to get.

hStringMap

[in] String Map to replace the existing entry.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

RemoveStringMapAt

Method used to remove a string map from the string map list.

int RemoveStringMapAt(StringMapSetHandle hStringMapSet, long nIndex);

Parameters

hStringMapSet

[in] AppConn string map list.

nIndex

[in] Index of the string map to remove.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

ReleaseStringMapSet

Method used to release an AppConn string map list. All elements of the string map list are released.

int ReleaseStringMapSet(StringMapSetHandle hStringMapSet);

Parameters

hStringMapSet

[in] AppConn string map list.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetErrorCode

Method used to get the error code for an AppConn object.

long GetErrorCode(SessionHandle hSession);

Parameters

hSession

[in] AppConn object

Return Value

The error code for the last reported error.

GetErrorMessage

Method used to get the error message for an AppConn object.

long GetErrorMessage(SessionHandle hSession, long nIndex, CharType *strString, long nBufferLen);

Parameters

hSession

[in] AppConn object

nIndex

[in] The index of the message to select.

strString

[out] Buffer to retrieve the string.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the message retrieved.

GetErrorMessageInfo

Obtain an Error Info handle for a given error message in the last set of reported errors.

ErrorInfoHandle GetErrorMessageInfo( SessionHandle hSession, long index );

Parameters

hSession

Session handle.

Index

0-based index of the error for which information is to be obtained.

Return Value

Handle for accessing error information, or NULL if the session handle is invalid, there are no errors, or the index value is out of range.

GetErrorMessageCode

Return the error code of a given error message.

long GetErrorMessageCode( ErrorInfoHandle hErrorInfo );

Parameters

hError

ErrorInfoHandle obtained by calling GetErrorMessageInfo()

Return Value

Error code, 0 if there is no error, or -1 if hError is invalid.

GetErrorMessageCode

Return the error code of a given error message.

long GetErrorMessageCode( ErrorInfoHandle hErrorInfo );

Parameters

hError

ErrorInfoHandle obtained by calling GetErrorMessageInfo()

Return Value

Error code, 0 if there is no error, or -1 if hError is invalid.

GetErrorMessageParameterCount

Return the number of parameter strings associated with an error message.

long GetErrorMessageParameterCount( ErrorInfoHandle hErrorInfo );

Parameters

hErrorInfo

ErrorInfoHandle obtained by calling GetErrorMessageInfo()

Return Value

Number of error parameters, of -1 if hErrorInfo is invalid

GetErrorMessageParameter

Return a parameter string for an error message, given an index.

long GetErrorMessageParameter( ErrorInfoHandle hErrorInfo, long index, CharType *strString, long nBufferLen );

Parameters

hErrorInfo

ErrorInfoHandle obtained by calling GetErrorMessageInfo()

index

0-based index of the parameter to be obtained.

strString

Buffer to receive the parameter string.

nBufferLen

Maximum number of characters the buffer can accept.

Return Value

number of characters returned, or -1 if argument(s) are invalid.

ReleaseErrorMessagInfo

Release an ErrorInfoHandle and free resources associated with it.

int ReleaseErrorMessageInfo( ErrorInfoHandle hError );

Parameters

hErrorInfo

ErrorInfoHandle obtained by calling GetErrorMessageInfo()

Return Value

int - (succeeded = !0, failed = 0)

GetLocale

Method used to get the locale for an AppConn session. By default, this method returns -1 and internally posts an "Unknown Error" message. If the user has set a locale string by a prior to call to SetLocale(), that string is returned by GetLocale().

long GetLocale(SessionHandle hSession, CharType *strLocale, long nBufferLen);

Parameters

hSession

[in] AppConn object

strLocale

[out] buffer to retrieve the locale

nBufferLen

[in] The length of the buffer.

Return Value

The length of the locale retrieved.

SetLocale

Method used to set the locale for an AppConn object.

int SetLocale(SessionHandle hSession, const CharType *strLocale);

Parameters

hSession

[in] AppConn object.

strLocale

[in] the locale.

Return Value

An integer value indicating whether or not the call succeeded (succeeded = !0, failed = 0).

GetLocalizedMessage

Method used to get the localized error message for an AppConn object.

long GetLocalizedMessage(Handle hError, long nIndex, CharType *strString, long nBufferLen);

Parameters

hError Handle

[in] AppConn object.

long nIndex

The zero-based index into the message list

strString

[out] buffer to retrieve the message.

nBufferLen

[in] The length of the buffer.

Return Value

The length of the message retrieved.

GetMajorVersion

Method used to get version information for the AppConn connector.

long GetMajorVersion(void);

Return Value

The major version number.

GetMinorVersion

Method used to get version information for the AppConn connector.

long GetMinorVersion(void);

Return Value

The minor version number.

GetModelVariableNames

Method used to get the names of all variables in the Host Integrator model.

StringListHandle GetModelVariableNames(SessionHandle hSession);

Parameters

hSession SessionHandle

[in] AppConn object.

strStringMapHandle

[out] buffer to retrieve the model variables.

Return Value

The variable names.

Remarks

One potential reason for failure is that the server session has not been established.

GetNumMessages

Method used to get the number of error messages for an AppConn object.

long GetNumMessages(SessionHandle hSession);

Parameters

hSession

[in] AppConn object.

Return Value

The number of error messages.

GetOperationTimeout

Method used to get the timeout (in seconds) of the operation.

long GetOperationTimeout(OperationMetaDataHandle hOperationMetaData);

Parameters

hOperationMetaData OperationMetaDataHandle

[in] AppConn object.

Return Value

The timeout.

GetTermFieldLength

Method used to get the length of a field.

long GetTermFieldLength(TerminalFieldHandle hTerminalField);

Parameters

hTerminalField TerminalFieldHandle

[in] AppConn Terminal Field

Return Value

The length of the field.

GetVersionString

Method used to get version information for the AppConn connector.

long GetVersionString(CharType *strVersionString, long nBufferLen);

strVersionString

[in] Buffer to retrieve the version string

nBufferLen

[in] The length of the buffer.

Return Value

The length of the version string retrieved.

Example

Building a C Application on Any Development Platform