Details of Function Calls

This section describes each function call available in the libiclinklibs.a library. The descriptions include available arguments, and the results returned, including error codes.

For an example of each function call, see the IC-CAP IPC Link example program ($ICCAP_ROOT/src/ipcexample.c). This example program takes control of IC-CAP. It then sends PEL commands to access variables and datasets in an npn model, performs a time-consuming task, and sends a pin mapping to IC-CAP and then accesses it.

launch_iccap

 int launch_iccap(const char *appName,
                  const char *host,
                  const char *iccapRoot,
                  const char *altPath)

launch_iccap invokes IC-CAP with the IPC link in place.

appName declares the name of the invoking program. This name cannot contain any spaces. This name will appear in the interactive dialog selector in IC-CAP as well as within a menu. If appName is NULL or the null string, the default link name will be Unnamed_Link.

host specifies the host's name on which to run. If this string is not NULL, and if gethostent matches this host with gethostbyname(), then no remsh or rsh is used. If host is not NULL (or null string), and it returns a hostent with gethostbyname, then remsh or rsh will be used to invoke IC-CAP.

iccapRoot is the path to where IC-CAP has been installed on the machine on which it is to run. If iccapRoot is NULL, it is assumed that ICCAP_ROOT is or will be set in the environment and that $ICCAP_ROOT/bin is already in the path.

altPath identifies a different path. Ordinarily, $ICCAP_ROOT/bin/iccap is used to invoke IC-CAP. Users often place a wrapper around this script to set up ICCAP_ROOT and LM_LICENSE_FILE. If this is the case, the alternate script can be named in this argument.

Returns

launch_iccap returns 0 if successful, or the following error codes:

-1 - Unable to determine current host.

-2 - Unable to fork.

initialize_session()

 int initialize_session()

initialize_session attempts to gain control of the current IC-CAP session. Once initialized, PEL calls can be sent. IC-CAP is placed in a special mode on success of this call which will not raise any error dialogs. It also actively listens for calls from the link.

Returns

initialize_session() returns 0 if successful, or one of the following error codes:

-1 - IC-CAP is being used interactively. Message should be presented to user in this case telling them to set IC-CAP for Linked Mode.

-2 - General Communications Failure. IC-CAP is not responding as expected. The link has been broken.

-3 - The session is already running, and waiting for a PEL response from a prior send_PEL with wait==0. get_PEL_response must be called.

terminate_session()

 int terminate_session()

terminate_session relinquishes control of IC-CAP. This enables you to interactively use IC-CAP.

Returns

terminate_session() returns 0 if successful, or one of the following error codes:

-1 - Indicates that IC-CAP is in interactive mode.

-2 - Indicates a communications failure. When -2 is returned, the link is broken.

-3 - The session can't be terminated. Waiting for a PEL response from a prior send_PEL with wait==0. get_PEL_response must be called.

send_PEL

 int send_PEL(const char *PELText, int wait, char **errMsg, 
         LinkReturnFuncT retfunc)

send_PEL sends PELText across the link to be executed within IC-CAP. initialize_session() must have been called successfully prior to this working. The text can be multiline or a single line of code. Each call to send_PEL essentially begins a new macro, so temporary variables within text will not persist between send_PEL calls. However, temporary variables can be used within multiline PELText. PELText should be null terminated.

wait specifies if send_PEL should wait for the PEL to finish before returning. If wait is nonzero, send_PEL will wait. If wait is 0, send_PEL will return immediately upon sending the PEL text to IC-CAP. The caller must then, at a later time, call get_PEL_response() to wait for the call to complete and collect the return status. See get_PEL_response.

If errMsg is not NULL and a PEL error occurs (noted by return of -3), it will be set to point to an error message returned from IC-CAP. The message will be a null terminated string and must be freed with free(). No memory is allocated if NULL is passed to send_PEL, or if no error occurs. errMsg is only meaningful when -3 is returned.

retfunc points to a function of type LinkReturnFuncT. This function will be invoked whenever IC-CAP calls one of the functions ICMSchar, ICMSint, ICMSreal, ICMSstr, or ICMSarray. The one argument to this function is a pointer to a LinkReturnS structure as shown in the following statement:

 typedef int (*LinkReturnFuncT)(struct LinkReturnS *);

For details about the structure, see Details of the LinkReturnS Structure.

Returns

send_PEL() returns 0 if successful, or one of the following error codes:

-1 - Indicates that IC-CAP is in interactive mode.

-2 - Indicates a communications failure. When -2 is returned, the link is broken.

-3 - PEL was executed, but an IC-CAP error occurred. Check errMsg for details.

-4 - PEL could not be sent, because there is a pending response caused by a prior send_PEL with wait==0.

get_PEL_response

 int get_PEL_response(char **errMsg, LinkReturnFuncT retfunc)

get_PEL_response waits PEL from a prior send_PEL (with wait==0) to complete.

If errMsg is not NULL and a PEL error occurred (error code -3), it will be set to point to an error message returned from IC-CAP. The message will be a null terminated string and must be freed with free(). No memory will be allocated if NULL is passed to send_PEL, or if no error occurs. errMsg is only meaningful when -3 is returned.

retfunc points to a function of type LinkReturnFuncT. This function is invoked when IC-CAP calls one of the functions ICMSchar, ICMSint, ICMSreal, ICMSstr, or ICMSarray. The one argument to this function is a pointer to a LinkReturnS structure as shown in the following statement:

 typedef int (*LinkReturnFuncT)(struct LinkReturnS *);

For details about the structure, see Details of the LinkReturnS Structure.

Returns

get_PEL_response() returns 0 if successful, or one of the following error codes:

-1 - Indicates that IC-CAP is in interactive mode.

-2 - Indicates a communications failure. When -2 is returned, the link is broken.

-3 - PEL was executed, but an IC-CAP error occurred. Check errMsg for details.

-4 - There were no prior send_PEL calls with wait==0 to wait for.

send_map

 int send_map(int *pinMap, int numPins)

send_map sends a new pin matrix mapping to IC-CAP for use with ICMSpin() or SPECSpin(). The indices of the pinMap array correspond to the actual pins in the hardware. The values of pinMap correspond to the logical pad numbers associated with the pins. For example, if pinMap[5]=12, a call to SPECSpin(5) would return 12. If hardware contains no 0 pin, load pinMap[0] with -1.

Returns

send_map() returns 0 if successful, or one of the following error codes:

-1 - indicates that IC-CAP is in interactive mode.

-2 - indicates a communications failure. When -2 is returned, the link is broken.

-3 - Map cannot be sent. Waiting for a PEL response from a prior send_PEL with wait==0. get_PEL_response must be called.