Connect Utility Functions

Connect includes several utility functions.

AgConSetTimeout()

This function allows you to change the default timeout value. The timeout value is entered in msec.

void
AgConSetTimeout (
char *context
int timeout
);
AgConGetAsync()

This function should be used when asynchronous data is expected from STK:

int
AgConGetAsync (
char *context,
AgTConReturnInfo *returnInfo
);

This function "listens" to STK and returns the first batch of asynchronous data received. The command type and identifier are placed in the returnInfo structure along with the actual data returned. For example, you can send the ASYNC2DPICK command with a ONCE option, then call AgConGetAsync() to wait for the return data. The function "listens" until the timeout period is reached. If no data is received, Connect generates an error message. AgConGetAsync() returns AgCNoError if successful and AgCError if an error occurs.

AgConSetProperties()

This function can be used to set Verbose, Acknowledge, etc. from within a program:

void
AgConSetProperties (
char *context,
unsigned props
);

The props parameter is formed by ANDing or ORing together the following bitmasks:

AgCConVerboseOn 0x0001
AgCConAckOn 0x0002
AgCConErrorOn 0x0004
AgCConAsyncOn 0x0008

For instance, to turn Verbose and Acknowledge ON and all other options OFF, make the following call:

AgConSetProperties(connection1, (AgCConVerboseOn | AgCConAckOn));
AgConShutdownConnect()

This function frees the memory allocated internally within the Connect library:

void
AgConShutdownConnect (
);

This function should be called prior to application exit after all connections have been closed. If you wish to resume Connect operations after calling this function, you must call AgConInit() again prior to opening any connection.

AgUtMsgReserveBuffer()

This function can be used to set the size of the buffer for the AgUtMsg() function:

void
AgUtMsgReserveBuffer (
int bufferLen
);

The message buffer is, by default, 2048 characters. Use this function, before the AgUtMsg() function, if you require additional length in the message buffer.

Also, see the Connect Example File.