![C Library Reference Version 6.50 Programmer’s Guide
Table 2 Collateral Documentation (page 2 of 2)
Document Description
SPiiPlus Modbus User’s Guide Describes Modbus setup and register address.
SPiiPlus SA, SA-LT and SAR- Installation and hardware connection with the SPiiPlus SA
LT Hardware Guide SPiiPlus SA-LT, and SAR-LT Controllers
SPiiPlus 3U-LT & SPiiPlus 3U- Installation and hardware connection with the SPiiPlus 3U
HP Hardware Guide Controller.
1.4 Conventions Used in this Guide
Several text formats and fonts, illustrated in Table 3, are used in the text to convey information
about the text.
Table 3 Text Conventions
Text Description
BOLD CAPS ACSPL+ elements (commands, functions, operators,
standard variables, etc.) when mentioned in the text.
Software tool menus, menu items, dialog box names and
dialog box elements.
bold Emphasis or an introduction to a key concept.
Monospace Code examples.
Italic monospace Information in code examples that the user provides.
ALL CAPS (Keyboard) key names [example: SHIFT key].
Bold Blue Text Links within this document, to web pages, and to e-mail
addresses.
Italic Blue Text Indicates name of referenced document.
| Used in command syntax to indicate input of one
alternative or another.
Used in GUI descriptions to indicate nested menu items
and dialog box options leading to a final action. For
example, the sequence:
Debug New Watch Real-time
directs the user to open the Debug menu, choose the New
Watch command, and select the Real-time option.
Version 6.50, 31 January 2009 3 Introduction](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-17-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
When a thread activates a non-waiting call, the library passes the request to an internal thread
that sends the command to the controller and then monitors the controller responses. When the
controller responds to the command, the internal thread stores the response in the internal
buffers. The calling thread can retrieve the controller response with help of the
acsc_WaitForAsyncCall function and validate the completion result in the Ret member of the
structure.
Up to 256 non-waiting calls can be activated before any acsc_WaitForAsyncCall is called. It
is important to understand that acsc_WaitForAsyncCall must be called for every non-waiting
call. Otherwise, the response will be stored forever in the library’s internal buffers. A call,
which is called when more then 256 calls are already activated is delayed for a certain time and
waits until acsc_WaitForAsyncCall is called by one of the previous calls. If the time expires,
an ACSC_COMMANDSQUEUEFULL error is returned.
By default, this time-out is zero. This means that the call number 257 immediately returns with
the ACSC_COMMANDSQUEUEFULL error
.
Note
If you work with multiple non-waiting calls and the
ACSC_COMMANDSQUEUEFULL error pops up all the time, the
structure of your application is too demanding. This means that you are
trying to activate more than 256 calls without retrieving the results.
If the error message pops up occasionally, try increasing the timeout.
Time-out is controlled by acsc_GetQueueOverflowTimeout and
acsc_SetQueueOverflowTimeout functions.
The following example shows how to perform waiting and non-waiting calls. In this example
the acsc_WaitForAsyncCall function was used. Any function that has Wait as a parameter can
be used to perform waiting and non-waiting calls.
#include “ACSC.h”
Char* cmd = “?$r”; // get motors state
char buf[101];
int Received;
ACSC_WAITBLOCK wait;
// example of the waiting call of acsc_Transaction
if (!acsc_Transaction( Handle, // communication handle
cmd, // pointer to the buffer that
// contains command to be executed
strlen(cmd), // size of this buffer
31 January 2009 13 SPiiPlus C Library Overview](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-27-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
buf, // input buffer that receives
// controller response
100, // size of this buffer
&Received, // number of characters that were
//actually received
NULL // waiting call
{
printf(“transaction error: %dn”, acsc_GetLastError());
}
// example of non-wainig call of acsc_Transaction if
(acsc_Transaction(Handle,cmd,strlen(cmd),buf,100,&Received,&wait))
{
// something doing here
….
// retrieve controller response
if (acsc_WaitForAsyncCall(Handle, buf, &Received, &wait, 5000))
{
buf[Received] = ‘0’;
printf(“Motors state: %sn”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘0’;
printf(“error: %sn”, buf);
}
}
31 January 2009 14 SPiiPlus C Library Overview](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-28-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
• Function = PCI function of the controller card
Within these members, the SlotNumber can be used in the acsc_OpenCommPCI call to open
communication with a specific card. Other members have no use in the SPiiPlus C Library.
If no controller cards are detected, the function assigns the ObtainedCards with zero and does
not fill the Cards array. If one or more controller cards are detected, the function assigns the
ObtainedCards with a number of detected cards and places one ACSC_PCI_SLOT structure
per each detected card into the Cards array.
If the size of Cards array specified by the Count parameter is less than the number of detected
cards, the function assigns the ObtainedCards with a number of actually detected cards, but
fills only the Count elements of the Cards array.
Example
ACSC_PCI_SLOT CardsList[16];
int DetectedCardsCount;
if (acsc_GetPCICards( CardsList, // pointer to the declared
// array
// to save the detected
// cards information
16, // size of this array
&DetectedCardsCount // number of cards that were
// actually detected
))
{
printf("Found %d SB1218PCI cardsn", DetectedCardsCount);
}
else
{
printf("error while scanning PCI bus: %dn", acsc_GetLastError());
}
4.1.7 acsc_SetServer
Description
The function defines user-mode driver host IP address.
Syntax
int acsc_SetServer(char *IP)
Arguments
IP IP address of the machine that hosts the desired active user-mode driver.
It may be entered as an IP address (10.0.0.102) or as local machine name
(ACS110)
Return Value
If the function succeeds, the return value is non-zero.
31 January 2009 29 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-43-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
the Wait parameter.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Note
This function is only used for compatibility with the previous version of zero-
library. To communicate with the controller, use the acsc_Transaction or
acsc_Command functions.
Example
// example of call of acsc_Receive
char buf100];
int Received;
if (!acsc_Receive(Handle, // communication handle
buf, // input buffer that receives data
100, // size of this buffer
&Received, // number of characters that were actually
// received
NULL // waiting call
))
{
printf("No characters were receivedn");
}
4.1.13 acsc_Transaction
Description
The function executes one transaction with the controller, i.e. it sends a command and receives
a controller response.
Syntax
int acsc_Transaction (HANDLE Handle, char* OutBuf, int OutCount, char* InBuf, int
InCount, int* Received, ACSC_WAITBLOCK* Wait)
Note
Any ASCII command being sent to the controller must end with the 'r' (13)
character, otherwise it will not be recognized as valid.
Arguments
Handle Communication handle
31 January 2009 36 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-50-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
rest of the operation. The calling thread can validate if the operation finished and can retrieve
the operation result using the acsc_WaitForAsyncCall function.
Example
char* cmd = "?SNr"; // get controller serial number
char buf[100];
int Received, ret;
ACSC_WAITBLOCK wait;
// example of the waiting call of acsc_Transaction
if (!acsc_Transaction( Handle, // communication handle
cmd, // pointer to the buffer that contains
executed
// controller’s command
strlen(cmd), // size of this buffer
buf, // input buffer that receives controller response
100, // size of this buffer
&Received, // number of characters that were actually
received
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// example of non-wainig call of acsc_Transaction
if (acsc_Transaction(Handle, cmd, strlen(cmd), buf, 100, &Received, &wait))
{
// something doing here
….
// waiting for the controller’s response 5 sec
if (acsc_WaitForAsyncCall(Handle, buf, &Received, &wait, 5000))
{
buf[Received] = ‘0’;
printf(“Controller serial number: %sn”, buf);
}
4.1.14 acsc_Command
Description
The function sends a command to the controller and analyzes the controller response.
Syntax
int acsc_Command (HANDLE Handle, char* OutBuf, int OutCount,
ACSC_WAITBLOCK* Wait)
31 January 2009 38 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-52-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function waits for completion of asynchronous call, corresponds to the Wait parameter,
and retrieves controller response to the buffer pointed by Buf. The Wait and Buf must be the
same pointers passed to SPiiPlus C function when asynchronous call was initiated.
If the call of SPiiPlus C function was successful, the function retrieves controller response to
the buffer Buf. The Received parameter will contain the number of actually received
characters.
If the call of SPiiPlus C function does not return a response (for example: acsc_Enable,
acsc_Jog, etc.) Buf has to be NULL.
If the call of SPiiPlus C function returned the error, the function retrieves this error code in the
Ret member of the Wait parameter.
If the SPiiPlus C function has not been completed in Timeout milliseconds, the function aborts
specified asynchronous call and returns ACSC_TIMEOUT error.
If the call of SPiiPlus C function has been aborted by the acsc_CancelOperation function, the
function returns ACSC_OPERATIONABORTED error.
Example
char* cmd = "?VRr";// get firmware version
char buf[101];
int Received;
ACSC_WAITBLOCK wait;
if (!acsc_Transaction(Handle, cmd, strlen(cmd), buf, 100, &Received,
&wait))
{
printf("transaction error: %dn", acsc_GetLastError());
}
else
{
// call is pending
if (acsc_WaitForAsyncCall(Handle, // communication handle
31 January 2009 41 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-55-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
buf, // pointer to the same buffer, that was specified
// for acsc_Transaction
&Received, // received bytes
&wait, // pointer to the same structure, that was
// specified for acsc_Transaction
500 // 500 ms
))
{
buf[Received] = ‘0’;
printf(“Firmware version: %sn”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘0’;
printf("error: %sn", buf);
}
}
4.1.16 acsc_CancelOperation
Description
The function cancels any asynchronous (non-waiting) call or all operations with the specified
communication handle.
Syntax
int acsc_CancelOperation(HANDLE Handle, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle
Wait Pointer to the ACSC_WAITBLOCK structure that was passed to the
function that initiated the asynchronous (non-waiting) call.
Return Value
If the function succeeds, the return value is non-zero. The corresponding asynchronous call was
successfully canceled.
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
31 January 2009 42 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-56-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
SPiiPlus controllers running with FW 4.50 or below will not be found with
a mask other than ACSC_NONE.
Example
in_addr IPaddresses[100];
int Ncontrollers;
char *DotStr;
char Version[100];
int N;
HANDLE h;
int I;
if (!acsc_GetEthernetCards(IPaddresses,100, &Ncontrollers,ACSC_NONE))
{
printf("Error %dn", acsc_GetLastError());
}
for(I=0;I<Ncontrollers;I++)
{
DotStr=inet_ntoa(IPaddresses[I]);
h=acsc_OpenCommEthernet(DotStr,ACSC_SOCKET_STREAM_PORT);
if(h!=ACSC_INVALID)
{
if(acsc_GetFirmwareVersion(h,Version, 100,&N,NULL))
{
Version[N]=0;
printf("%sn",Version);
}
acsc_CloseComm(h);
}
}
4.1.18 acsc_GetConnectionsList
Description
The function retrieves all currently opened connections on the active server and their details.
Syntax
int acsc_GetConnectionsList(ACSC_CONNECTION_DESC* ConnectionsList, int
MaxNumConnections, int* NumConnections)
31 January 2009 45 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-59-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
int NConnections;
ACSC_CONNECTION_DESC Connections[100];
int I;
char app_name[]="needed_app.exe";
if (!acsc_GetConnectionsList(Connections, 100, &NConnections))
{
printf("Error %dn", acsc_GetLastError());
}
for(I=0;I<NConnections;I++)
{
if ((strcmp(Connections[I].Application, app_name)==0) &&
(OpenProcess(0,0,Connections[I].ProcessId) == NULL))
// Check if process is
//still running by OpenProcess() function,
//only if it was executed on local PC.
{
if (!acsc_TerminateConnection(&(Connections[i])))
{
printf("Error closing communication of %s application: %dn",
Connections[I].Application, acsc_GetLastError());
}
else
{
printf("Communication of %s application is successfully closed!n",
Connections[I].Application);
}
}
}
4.1.19 acsc_TerminateConnection
Description
The function terminates a given communication channel (connection) of the active server.
Syntax
int acsc_TerminateConnection(ACSC_CONNECTION_DESC* Connection)
Arguments
Connection Pointer to array of connections. Each connection is defined by the
ACSC_CONNECTION_DESC structure.
The acsc_GetConnectionsList function is responsible for
initializing this structure.
Return Value
If the function succeeds, the return value is non-zero.
31 January 2009 47 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-61-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
int NConnections;
ACSC_CONNECTION_DESC Connections[100];
int I;
char app_name[]="needed_app.exe";
acsc_SetServerExt("10.0.0.13",7777);
if (!acsc_GetConnectionsList(Connections, 100, &NConnections))
{
printf("Error %dn", acsc_GetLastError());
}
for(I=0;I<NConnections;I++)
{
if ((strcmp(Connections[I].Application, app_name)==0) &&
(OpenProcess(Connections[I].ProcessId) == NULL))
// Check if process is still
//running by OpenProcess() function, only
//if it was executed on local PC.
{
if (!acsc_TerminateConnection(&(Connections[i])))
{
printf("Error closing communication of %s application: %dn",
Connections[I].Application, acsc_GetLastError());
}
else
{
printf("Communication of %s application is successfully closed!n",
Connections[I].Application);
}
}
}
4.2 Service Communication Functions
The Service Communication functions are:
Table 6 Service Communication Functions (page 1 of 2)
Function Description
acsc_GetCommOptions Retrieves the communication options.
acsc_GetDefaultTimeout Retrieves default communication time-out.
acsc_GetErrorString Retrieves the explanation of an error code.
acsc_GetLastError Retrieves the last error code.
acsc_GetLibraryVersion Retrieves the SPiiPlus C Library version number.
acsc_GetTimeout Retrieves communication time-out.
acsc_SetIterations Sets the number of iterations of one transaction.
31 January 2009 49 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-63-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
char ErrorStr[256];
int ErrorCode, Received;
ErrorCode = acsc_GetLastError();
if (acsc_GetErrorString(Handle, // communication handle
ErrorCode, // error code
ErrorStr, // buffer for the error explanation
255, // available buffer length
&Received// number of actually received bytes
))
{
ErrorStr[Received] = ‘0’;
printf("function returned error: %d (%s)n", ErrorCode, ErrorStr);
}
4.2.4 acsc_GetLastError
Description
The function returns the calling thread’s last-error code value. The last-error code is maintained
on a per-thread basis. Multiple threads do not overwrite each other’s last-error code.
Syntax
int acsc_GetLastError()
Arguments
This function has no arguments.
Return Value
The return value is the calling thread’s last-error code value.
Comments
It is necessary to call acsc_GetLastError immediately when some functions return zero value.
This is because all of the functions rewrite the error code value when they are called.
For a complete List of Error Codes, “Error Codes” on Page 368.
Example
printf("function returned error: %dn", acsc_GetLastError());
4.2.5 acsc_GetLibraryVersion
Description
The function retrieves the SPiiPlus C Library version number.
31 January 2009 53 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-67-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_AppendBuffer
char buf[256];
strcpy(buf, "!This is a test ACSPL+ programn" );
strcat(buf, "enable Xn" );
strcat(buf, "ptp X, 1000n" );
strcat(buf, "stopn" );
if (!acsc_AppendBuffer( Handle, // communication handle
0, // ACSPL+ program buffer
// number
buf, // buffer contained ACSPL+
// program(s)
strlen(buf), // size of this buffer
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.3.2 acsc_ClearBuffer
Description
The function deletes the specified ACSPL+ program lines in the specified program buffer.
Syntax
int acsc_ClearBuffer(HANDLE Handle, int Buffer, int FromLine, int ToLine,
ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Buffer Buffer number, from 0 to 10.
FromLine, These parameters specify a range of lines to be deleted.
ToLine
FromLine starts from 1.
If ToLine is larger then the total number of lines in the specified
program buffer, the range includes the last program line.
If ToLine is ACSC_MAX_LINE, the function deletes all lines in the
specified buffer.
31 January 2009 62 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-76-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Arguments
Handle Communication handle.
Buffer Buffer number, from 0 to 10.
Use ACSC_NONE instead of the buffer number, to compile all
programs in all buffers.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the function
returns immediately. The calling thread must then call the
acsc_WaitForAsyncCall function to retrieve the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In this
case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
The function returns non-zero if it succeeded to perform the compile operation on the buffer,
such that the communication channel is OK, the specified buffer is not running and compile
operation was performed. However, it does not mean that compilation succeeded. If the return
value is zero, compile operation could not be performed by some reason.
Note
Extended error information can be obtained by calling acsc_GetLastError.
In order to get information about compilation results, use acsc_ReadInteger to read PERR [X],
which contains the last error that occurred in buffer X. If PERR [X] is zero the buffer was
compiled successfully.
Otherwise, PERR [X] tells you about the error that occurred during the compilation.
Comments
The function compiles ACSPL+ program in the specified program buffer or all programs in all
buffers if the parameter Buffer is ACSC_NONE.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the program was compiled successfully.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
31 January 2009 64 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-78-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_LoadBuffer
char buf[256];
strcpy(buf, "!This is a test ACSPL+ programn" );
strcat(buf, "enable Xn" );
strcat(buf, "ptp X, 1000n" );
strcat(buf, "stopn" );
if (!acsc_LoadBuffer( Handle, // communication handle
0, // ACSPL+ program buffer number
buf, // pointer to the buffer contained
// ACSPL+ program(s).
strlen(buf), // size of this buffer
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.3.6 acsc_LoadBufferIgnoreServiceLines
Description
The function clears the specified program buffer and then loads ACSPL+ to this buffer.
All lines that start with # are ignored.
Note
This function is obsolete and is maintained only for backwards
compatablitiy. When loading files saved from the MultiDebugger and MMI
use the acsc_LoadBuffersFromFile function.
Syntax
int acsc_LoadBufferIgnoreServiceLines(HANDLE Handle, int Buffer, char* Program,
int Count, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle
Buffer Program buffer number: 0 to 10.
Program Pointer to the buffer contained ACSPL+ program(s).
Count Number of characters in the buffer pointed by Program
31 January 2009 67 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-81-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_LoadBuffer
char buf[256];
strcpy(buf, "!This is a test ACSPL+ programn" );
strcat(buf, "#Version 3.0 n" ); //Ignored – won’t be loaded
strcat(buf, "enable Xn" );
strcat(buf, "ptp X, 1000n" );
strcat(buf, "stopn" );
if (!acsc_LoadBufferIgnoreServiceLines
(Handle // communication handle
0, // ACSPL+ program buffer number
buf, // pointer to the buffer contained
// ACSPL+ program(s).
strlen(buf), // size of this buffer
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.3.7 acsc_LoadBuffersFromFile
Description
The function opens a file that contains one or more ACSPL+ programs allocated to several
buffers and download the programs to the corresponding buffers.
Syntax
int acsc_LoadBuffersFromFile(HANDLE Handle, char *Filename,
ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle
Filename Path of the file
Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls
are supported for this function.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
31 January 2009 69 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-83-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Text, Received and Wait items until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_UploadBuffer
char buf[256];
int Received;
if (!acsc_UploadBuffer( Handle, // communication handle
0, // ACSPL+ program buffer number
0, // from the beginning of this buffer
buf, // pointer to the buffer that receives uploaded
// text
256, // size of this buffer
&Received, // number of characters that were actually
// uploaded
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.4 Read and Write Variables Functions
The Read and Write Variables functions are:
Table 8 Read and Write Variables Functions
Function Description
acsc_ReadInteger Reads value from integer variable.
acsc_WriteInteger Writes value to integer variable.
acsc_ReadReal Reads value from real variable.
acsc_WriteReal Writes value to real variable.
4.4.1 acsc_ReadInteger
Description
The function reads value(s) from integer variable.
Syntax
int acsc_ReadInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, int* Values, ACSC_WAITBLOCK* Wait)
31 January 2009 76 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-90-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE. The
function reads the requested value and assigns it to the variable pointed by Values.
If the variable is a one-dimensional array, From1, To1 must specify the index range and
From2, To2 must be ACSC_NONE. Array Values must be of size To1-From1+1 at least. The
function reads all requested values from index From1 to index To1 inclusively and stores them
in the Values array.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. Array
Values must be of size (To1-From1+1)x(To2-From2+1) values at least. The function uses the
Values array in such a way: first, the function reads To2-From2+1 values from row From1
and fills the Values array elements from 0 to To2-From2, then reads To2-From2+1 values
from raw From1+1 and fills the Values array elements from To2-From2+1 to 2*(To2-
From2)+1, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Values and Wait items until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_ReadInteger
int AnalogInputs[8];
if (!acsc_ReadInteger( Handle, // communication handle
ACSC_NONE, // standard variable
"AIN", // variable name
0, 7, // first dimension indexes
ACSC_NONE, ACSC_NONE,// no second dimension
AnalogInputs, // pointer to the buffer
// that receives requested
// values
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.4.2 acsc_WriteInteger
Description
The function writes value(s) to integer variable.
Syntax
int acsc_WriteInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, int* Values, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle
31 January 2009 78 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-92-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
least. The function writes the values to the specified variable from index From1 to index To1
inclusively.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. Array
Values must contain (To1-From1+1)x(To2-From2+1) values at least. The function uses the
Values array as follows: first, the function retrieves the Values elements from 0 to To2-From2
and writes them to row From1 of the specified controller variable, then retrieves the Values
elements from To2-From2+1 to 2*(To2-From2)+1 and writes them to row From1+1 of the
specified controller variable, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
/ example of the waiting call of acsc_WriteInteger
int AnalogOutputs[4] = { 10, 20, 30, 40 };
if (!acsc_WriteInteger(Handle, // communication handle
ACSC_NONE, // standard variable
"AOUT", // variable name
0, 3, // first dimension indexes
ACSC_NONE, ACSC_NONE, // no second dimension
AnalogOutputs, // pointer to the buffer contained values
// that must be written
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.4.3 acsc_ReadReal
Description
The function reads value(s) from a real variable.
Syntax
int acsc_ReadReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2,
int To2, double* Values, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle
NBuf Number of program buffer for local variable or ACSC_NONE for
global and standard variable.
31 January 2009 80 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-94-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. Array
Values must be of size (To1-From1+1)x(To2-From2+1) values at least. The function uses the
Values array in such a way: first, the function reads To2-From2+1 values from row From1
and fills the Values array elements from 0 to To2-From2, then reads To2-From2+1 values
from raw From1+1 and fills the Values array elements from To2-From2+1 to 2*(To2-
From2)+1, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Values and Wait items until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_ReadReal
double FPositions[8];
if (!acsc_ReadReal( Handle, // communication handle
ACSC_NONE, // standard variable
"FPOS", // variable name
0, 7, // first dimension indexes
ACSC_NONE, ACSC_NONE, // no second dimension
FPositions, // pointer to the buffer that
// receives requested values
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.4.4 acsc_WriteReal
Description
The function writes value(s) to the real variable.
Syntax
int acsc_WriteReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, double* Values, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle
NBuf Number of program buffer for local variable or ACSC_NONE for
global and standard variable.
Var Pointer to the null-terminated character string contained name of
the variable.
From1, To1 Index range (first dimension).
31 January 2009 82 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-96-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Values elements from To2-From2+1 to 2*(To2-From2)+1 and writes them to row From1+1
of the specified controller variable, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_WriteReal
double Velocity[8] = { 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000 };
if (!acsc_WriteReal( Handle, // communication handle
ACSC_NONE, // standard variable
"VEL", // variable name
0, 7, // first dimension indexes
ACSC_NONE, ACSC_NONE, // no second dimension
Velocity, // pointer to the buffer contained values
// to be written
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.5 Load/Upload Data To/From Controller
Functions
The Load/Upload Data To/From Controller functions are:
Table 9 Load File to ACSPL+ Variables Functions
Function Description
acsc_LoadDataToController Writes value(s) from text file to SPiiPlus controller
(variable or file).
acsc_UploadDataFromController Writes value(s) from the SPiiPlus controller
(variable or file) to a text file.
4.5.1 acsc_LoadDataToController
Description
The function writes value(s) from text file to SPiiPlus controller (variable or file).
Syntax
int acsc_LoadDataToController(HANDLE Handle,int Dest, char* DestName, int From1,
int To1, int From2, int To2, char* SrcFileName, int SrcNumFormat, bool bTranspose,
ACSC_WAITBLOCK* Wait)
31 January 2009 84 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-98-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
bClear If TRUE, the function clears contents of the history buffer
If FALSE, the history buffer content is not cleared.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function retrieves the communication history from the history buffer and stores it in the
buffer pointed by Buf.
The communication history includes all commands sent to the controller and all responses and
unsolicited messages received from the controller. The amount of received data does not exceed
the size of the history buffer. The history buffer works as a cyclic buffer: when the amount of
the stored data exceeds the buffer size, the newly stored data overwrites the earliest data in the
buffer.
Therefore, as a rule, the retrieved communication history includes only the recently sent
commands and receives responses and unsolicited messages. The depth of the retrieved history
depends on the history buffer size.
The history data is retrieved in historical order, i.e. the earliest message is stored at the
beginning of Buf. The first retrieved message in Buf can be incomplete, because of being
partially overwritten in the history buffer.
If the size of the Buf is less than the size of the history buffer, only the most recent part of the
stored history is retrieved.
Example
int Received;
char Buf[10000];
if (!acsc_GetHistory(Handle, // communication handle
Buf, // pointer to the buffer that receives a
// communication history
10000, // size of this buffer
&Received, // number of characters that were actually
received
TRUE // clear contents of the history buffer
))
{
printf("getting history error: %dn", acsc_GetLastError());
}
31 January 2009 94 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-108-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Comments
The function retrieves a single unsolicited message from the message buffer.
If no unsolicited message is received, the function waits until a message arrives.
If message arrives, Length will contain the received message length. If the timeout expires, the
function exits with the ACSC_TIMEOUT error.
Example
int L;
char Buf[10000];
if (!acsc_GetSingleMessage(Handle, // communication handle
Buf, // pointer to the buffer that
// receives unsolicited messages
10000 //Size of the buffer
&L, // number of characters that were actually
received
1000 // Wait for 1 second till a message arrives
))
{
printf("getting unsolicited message error: %dn",
acsc_GetLastError());
}
4.8.4 acsc_GetMessage
Description
The function retrieves unsolicited messages from the buffer. This function only works if you
setup a buffer using acsc_OpenMessageBuffer. If no message buffer is open, these messages
will be returned by acsc_Receive.
Syntax
int acsc_GetMessage(HANDLE Handle, char* Buf, int Count, int* Received, BOOL
bClear)
Arguments
Handle Communication handle
Buf Pointer to the buffer that receives unsolicited messages
Count Size of the buffer in bytes
Received Number of characters that were actually received
31 January 2009 98 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-112-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
bClear If TRUE, the function clears the contents of the unsolicited messages
buffer after retrieving the message.
If FALSE, the unsolicited messages buffer is not cleared.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function retrieves all stored unsolicited messages from the message buffer.
The function always returns immediately. If no, unsolicited message is received, the function
assigns zero to the Received variable.
Parameter Count specifies the buffer size. If a received message contains more than Count
characters, the function transfers to buffer only Count characters, assigns Received with
Count value and returns non-zero. The remaining characters of the message are removed from
the message buffer.
If the Count is equal to or more than the length of the message, the function transfers the whole
message to buffer and assigns variable Received with a number of characters that were actually
transferred.
Example
int Received;
char Buf[10000];
if (!acsc_GetMessage( Handle, // communication handle
Buf, // pointer to the buffer that
// receives unsolicited messages
10000, // size of this buffer
&Received, // number of characters that were
// actually received
TRUE // clear contents of the
// unsolicited messages buffer
))
{
printf("getting unsolicited message error: %dn",
acsc_GetLastError());
}
31 January 2009 99 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-113-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
4.9 Log File Management Functions
The Log File Management functions are:
Table 13 Log File Management Functions
Function Description
acsc_SetLogFileOptions Sets log file options.
acsc_OpenLogFile Opens a log file.
acsc_CloseLogFile Closes a log file.
acsc_WriteLogFile Writes to a log file.
acsc_FlushLogFile Flushes the User-Mode Driver (UMD) internal
binary buffer to a specified text file from the C
Library application.
4.9.1 acsc_SetLogFileOptions
Description
The function sets the log file options.
Syntax
acsc_SetLogFileOptions(HANDLE Handle,ACSC_LOG_DETALIZATION_LEVEL
Detalization, ACSC_LOG_DATA_PRESENTATION Presentation)
Arguments
Handle Communication handle
Detalization This parameter may be one of the following:
• Minimum -Value 0: Only communication traffic will be logged.
• Medium - Value 1: Communication traffic and some internal C
Lib process data will be logged.
• Maximum -Value 2: Communication traffic and all internal
process data will be logged.
Presentation This parameter may be one of the following:
• Compact -Value 0: No more than the first ten bytes of each data
string will be logged. Non-printing characters will be represented
in [Hex ASCII code].
• Formatted - Value 1: All the binary data will be logged. Non-
printing characters will be represented in [Hex ASCII code].
• Full -Value 2: All the binary data will be logged as is.
31 January 2009 100 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-114-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_EnableM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 };
if (!acsc_EnableM(Handle, // communication handle
Axes, // enable of axes XYZT
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.12.4 acsc_Disable
Description
The function shuts off a motor.
Syntax
int acsc_Disable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc.
For the full list of the axis constants, see Axis Definitions.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the
acsc_WaitForAsyncCall function returns immediately. The calling
thread must then call the acsc_WaitForAsyncCall function to retrieve
the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In this
case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
31 January 2009 143 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-157-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function shuts off several motors. After the shutting off, the motors cannot follow the
corresponding reference and remain idle.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_DisableM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 };
if (!acsc_DisableM( Handle, // communication handle
Axes, // disable of axes XYZT
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.12.8 acsc_Group
Description
The function creates a coordinate system for a multi-axis motion.
Syntax
int acsc_Group(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axes Array of axes. Each element specifies one involved axis:
ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After
the last axis, one additional element must be located that contains –1
and marks the end of the array.
For the full list of the axis constants, see “Axis Definitions” on
Page 378.
31 January 2009 148 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-162-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the function
returns immediately. The calling thread must then call the
acsc_WaitForAsyncCall function to retrieve the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In this
case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function creates a coordinate system for a multi-axis motion. The first element of the Axes
array specifies the leading axis. The motion parameters of the leading axis become the default
motion parameters for the group.
An axis can belong to only one group at a time. If the application requires restructuring the axes,
it must split the existing group and only then create the new one. To split the existing group,
use acsc_Split function. To split all existing groups, use the acsc_SplitAll function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_Group
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 };
if (!acsc_Group( Handle, // communication handle
Axes, // create group of axes XYZT
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
31 January 2009 149 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-163-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_Split
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T,
ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C,
ACSC_AXIS_D, -1 };
if (!acsc_Split( Handle, // communication handle
Axes, // split the group of axes XYZTABCD
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.12.10 acsc_SplitAll
Description
The function breaks down all axis groups created before.
Syntax
int acsc_SplitAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the
function returns immediately. The calling thread must then call the
acsc_WaitForAsyncCall function to retrieve the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In
this case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
31 January 2009 151 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-165-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the function
returns immediately. The calling thread must then call the
acsc_WaitForAsyncCall function to retrieve the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In this
case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
A motion that was planned with ACSC_AMF_WAIT flag does not start until the acsc_GoM
function is executed. After being planned, a motion waits in the appropriate motion queue.
Each axis has a separate motion queue. A single-axis motion waits in the motion queue of the
corresponding axis. A multi-axis motion waits in the motion queue of the leading axis. The
leading axis is an axis specified first in the motion command.
The acsc_GoM function initiates the motions waiting in the motion queues of the specified
axes. If no motion waits in one or more motion queues, the corresponding axes are not affected.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_GoM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 };
if (!acsc_GoM( Handle, // communication handle
Axes, // start up the motion of axes XYZT
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
31 January 2009 155 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-169-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
If the function fails, the return value is zero.
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function terminates all executed motions that involve the specified axes. The terminated
motions can be either single-axis or multi-axis. All other motions waiting in the corresponding
motion queues are discarded and will not be executed.
If no executed motion involves a specified axis, the function has no effect on the corresponding
axis.
The terminated motions finish using the full third-order deceleration profile and the motion
deceleration values.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_HaltM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 };
if (!acsc_HaltM( Handle, // communication handle
Axes, // terminate the motion of axes
//XYZTABCD
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.13.5 acsc_Kill
Description
The function terminates a motion using reduced deceleration profile.
Syntax
int acsc_Kill(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
31 January 2009 158 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-172-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function terminates all executed motions that involve the specified axes. The terminated
motions can be either single-axis or multi-axis. All other motions waiting in the corresponding
motion queues are discarded and will not be executed.
If no executed motion involves a specified axis, the function has no effect on the corresponding
axis.
The terminated motions finish with the reduced second-order deceleration profile and the kill
deceleration values.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_KillM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 };
if (!acsc_KillM( Handle, // communication handle
Axes, // terminate the motion of axes XYZT
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.13.8 acsc_KillExt
Description
The function terminates a motion using reduced deceleration profile and defines the kill reason.
Syntax
int acsc_KillExt(HANDLE Handle, int Axis, int Reason,ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y
etc. For the full list of the axis constants, see “Axis Definitions”
on Page 378.
31 January 2009 162 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-176-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
the next motion is planned, the function does not affect the axis.
When executing the break command, the controller terminates the motion immediately without
any deceleration profile. Instead, the controller builds a smooth third-order transition profile to
the next motion.
Use caution when implementing the break command with a multi-axis motion, because the
controller provides a smooth transition profile of the vector velocity. In a single-axis motion,
this ensures a smooth axis velocity, but in a multi-axis motion, an axis velocity can change
abruptly if the terminated and next motions are not tangent in the junction point. To avoid jerk,
the terminated and next motion must be tangent or nearly tangent in the junction point.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_BreakM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Points[] = { 10000, 10000 };
// start up the motion of axis XY to point (10000, 10000)
acsc_ToPointM(Handle, 0, Axes, Points, NULL);
// delay 200 ms
Sleep(200);// Windows API function
acsc_BreakM(Handle, Axes, NULL);
// change the end point to point (–10000, -10000) on the fly
Points[0] = -10000; Points[1] = -10000;
acsc_ToPointM(Handle, 0, Axes, Points, NULL);
31 January 2009 167 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-181-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_ToPointM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T,
ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C, ACSC_AXIS_D, -1 };
double Points[] = {50000, 60000, 30000, -30000, -20000, -50000, -15000,
15000};
if (!acsc_ToPointM(Handle, // communication handle
0, // start up immediately the motion
Axes, // of the axes XYZTABCD
Points, // to the absolutely target point
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.14.3 acsc_ExtToPoint
Description
The function initiates a single-axis motion to the specified point using the specified velocity or
end velocity.
Syntax
int acsc_ExtToPoint(HANDLE Handle, int Flags, int Axis, double Point, double Velocity,
double EndVelocity, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don't start it until the
function acsc_Go is executed.
• ACSC_AMF_RELATIVE: the Point value is relative to the end
point of the previous motion. If the flag is not specified, the Point
specifies an absolute coordinate.
• ACSC_AMF_VELOCITY: the motion will use velocity specified by
the Velocity argument instead of the default velocity.
• ACSC_AMF_ENDVELOCITY: the motion will come to the end
point with the velocity specified by the EndVelocity argument.
Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For
the full list of the axis constants, see “Axis Definitions” on Page 378.
31 January 2009 172 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-186-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_ExtToPointM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T,
ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C,
ACSC_AXIS_D, -1
};
double Points[] = { 50000, 60000, 30000, 20000, -20000, -50000,
-15000, 15000 };
if (!acsc_ExtToPointM( Handle, // communication handle
ACSC_AMF_VELOCITY | // start up the motion with
// specified velocity 5000
// and come to the end point
ACSC_AMF_ENDVELOCITY, // with specified velocity
// 1000
Axes, // axes XYZTABCD
Points, // target point
5000, // motion velocity
1000, // velocity in the target
// point
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.15 Track Motion Control Functions
The Track Motion Control functions are:
Table 19 Track Motion Control Functions
Function Description
acsc_Track The function initiates a single-axis track motion.
acsc_SetTargetPosition The function assigns a current value of target position.
acsc_GetTargetPosition The function receives the current value of target position.
4.15.1 acsc_Track
Description
The function initiates a single-axis track motion.
Syntax
int acsc_Track(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait)
31 January 2009 177 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-191-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use the acsc_WaitMotionEnd function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_JogM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,
ACSC_AXIS_T,
ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C,
ACSC_AXIS_D, -1 };
int Directions[] = { ACSC_POSITIVE_DIRECTION, ACSC_POSITIVE_DIRECTION,
ACSC_POSITIVE_DIRECTION,
ACSC_POSITIVE_DIRECTION,
ACSC_NEGATIVE_DIRECTION,
ACSC_NEGATIVE_DIRECTION,
ACSC_NEGATIVE_DIRECTION,
ACSC_NEGATIVE_DIRECTION
};
if (!acsc_JogM(Handle, // communication handle
0, // start up immediately the jog motion
// with the specified velocity 5000
Axes, // axes XYZTABCD
Directions, // axes XYZT in the positive direction,
// axes ABCD in the negative direction
5000, // motion velocity
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.17 Slaved Motion Functions
The Slaved Motion functions are:
Table 21 Slaved Motion Functions
Function Description
acsc_SetMaster Initiates calculation of a master value for an axis.
acsc_Slave Initiates a master-slave motion.
acsc_SlaveStalled Initiates master-slave motion with limited follow-on area.
31 January 2009 186 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-200-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_MultiPointM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
int Points[2];
if (!acsc_MultiPointM(Handle, // communication handle
0, // create the multi-point motion with
// default velocity
Axes, // of the axes XY
0, // without dwell in the points
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add some points
Points[0] = 1000; Points[1] = 1000;
acsc_AddPointM(Handle, Axes, Points, NULL);// from the point 1000, 1000
Points[0] = 2000; Points[1] = 2000;
acsc_AddPointM(Handle, Axes, Points, NULL);// to the point 2000, 2000
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion
4.19 Arbitrary Path Motion Functions
The Arbitrary Path Motion functions are:
Table 23 Arbitrary Path Motion Functions
Function Description
acsc_Spline Initiates a single-axis spline motion. The motion follows
an arbitrary path defined by a set of points.
acsc_SplineM Initiates a multi-axis spline motion. The motion follows an
arbitrary path defined by a set of points.
4.19.1 acsc_Spline
Description
The function initiates a single-axis spline motion. The motion follows an arbitrary path defined
by a set of points.
Syntax
int acsc_Spline(HANDLE Handle, int Flags, int Axis, double Period,
ACSC_WAITBLOCK* Wait)
31 January 2009 198 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-212-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
acsc_GoM function is executed.
• ACSC_AMF_RELATIVE: the coordinates of each point are
relative. The first point is relative to the instant position when the
motion starts; the second point is relative to the first, etc. If the flag
is not specified, the coordinates of each point are absolute.
• ACSC_AMF_VARTIME: the time interval between adjacent points
is non-uniform and is specified along with each added point. If the
flag is not specified, the interval is uniform and is specified in the
Period argument.
• ΑCSC_AMF_CYCLIC: the motion uses the point sequence as a
cyclic array: after the last point the motion comes to the first point
and continues.
Flags • ACSC_AMF_CUBIC: use a cubic interpolation between the
specified points (third-order spline). If the flag is not specified,
linear interpolation is used (first-order spline). [In the present
version third-order spline is not supported].
Axes Array of axes. Each element specifies one involved axis:
ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the
last axis, one additional element must be located that contains –1 and
marks the end of the array.
For the full list of the axis constants, see “Axis Definitions” on
Page 378.
Period Time interval between adjacent points. The parameter is used only if
the ACSC_AMF_VARTIME flag is not specified.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the function
returns immediately. The calling thread must then call the
acsc_WaitForAsyncCall function to retrieve the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In this
case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
31 January 2009 202 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-216-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function initiates a multi-axis spline motion. To execute a single-axis spline motion, use
acsc_Spline.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use the acsc_WaitMotionEnd function.
The motion does not use the default values of velocity, acceleration, deceleration, and jerk. The
points and the time intervals between the points define the motion profile completely.
Points for arbitrary path motion are defined by the consequent calls of the acsc_AddPointM or
acsc_ExtAddPointM functions. The acsc_EndSequenceM function terminates the point
sequence. After execution of the acsc_EndSequenceM function, no acsc_AddPointM or
acsc_ExtAddPointM functions for this motion are allowed.
The trajectory of the motion follows through the defined points. Each point presents the instant
desired position at a specific moment. Time intervals between the points are uniform, or non-
uniform as defined by the ACSC_AMF_VARTIME flag.
This motion does not use motion profile generation. Typically, the time intervals between the
points are short, so that the array of the points implicitly specifies the desired velocity in each
point.
If the time interval does not coincide with the controller cycle, the controller provides
interpolation of the points according to the ACSC_AMF_CUBIC flag.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
/ example of the waiting call of acsc_SplineM
int i;
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
int Points[2];
if (!acsc_SplineM( Handle, // communication handle
0, // create the arbitrary path motion
// with uniform interval 10 ms
31 January 2009 203 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-217-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Axes, // axes XY
10, // uniform interval 10 ms
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
{
Points[0] = i * 100; Points[1] = i * 50;
do
{
if(!acsc_AddPointM(Handle, Axes, Points, NULL))
ErrNum=acsc_GetLastError();
else
ErrNum=0;
}while(ErrNum==3065);
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL); // the end of arbitrary path motion
4.20 PVT Functions
The PVT functions are:
Table 24 PVT Functions
Function Description
acsc_AddPVPoint Adds a point to a single-axis multi-point or spline motion.
acsc_AddPVPointM Adds a point to a multi-axis multi-point or spline motion.
acsc_AddPVTPoint Adds a point to a single-axis multi-point or spline motion.
acsc_AddPVTPointM Adds a point to a multi-axis multi-point or spline motion.
4.20.1 acsc_AddPVPoint
Description
The function adds a point to a single-axis PV spline motion and specifies velocity.
Syntax
int acsc_AddPVPoint(HANDLE Handle, int Axis, double Point, double Velocity,
ACSC_WAITBLOCK* Wait)
31 January 2009 204 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-218-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
int i;
int Axis[]={ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,-1};
double Point[3];
double Velocity[3];
if (!acsc_SplineM(Handle, // communication handle
ACSC_AMF_CUBIC, // PV motion
Axis, // axis X
10, // uniform interval 10 ms
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
{
Point[0]=i*50; Point[1]=i*100; Point[2]=i*150;
Velocity[0]=i*50; Velocity [1]=i*100; Velocity [2]=i*150;
acsc_AddPVPointM(Handle,Axis,Point,Velocity,NULL);
//position,velocity and time interval for each point
}
// the end of the arbitrary path motion
acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);
4.20.3 acsc_AddPVTPoint
Description
The function adds a point to a single-axis PVT spline motion and specifies velocity and motion
time.
Syntax
int acsc_AddPVTPoint(HANDLE Handle, int Axis, double Point, double Velocity,double
TimeInterval, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axes ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.
For the full list of the axis constants, see “Axis Definitions” on
Page 378.
Point Coordinate of the added point.
Velocity Desired velocity at the point
31 January 2009 208 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-222-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
int i;
int Axis[]={ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,-1};
double Point[3];
double Velocity[3];
if (!acsc_SplineM(Handle, // communication handle
ACSC_AMF_CUBIC|ACSC_AMF_VARTIME,//PVT motion
Axis, // axis X
0, // uniform interval is not used
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
{
Point[0]=i*50; Point[1]=i*100; Point[2]=i*150;
Velocity[0]=i*50; Velocity [1]=i*100; Velocity [2]=i*150;
acsc_AddPVTPointM(Handle,Axis,Point,Velocity,100+i,NULL);
//position,velocity and time interval for each point
}
// the end of the arbitrary path motion
acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);
4.21 Segmented Motion Functions
The Segmented Motion functions are:
Table 25 Segmented Motion Functions (page 1 of 2)
Function Description
acsc_Segment Initiates a multi-axis segmented motion.
acsc_Line Adds a linear segment to a segmented motion.
acsc_ExtLine Adds a linear segment to a segmented motion and
specifies a motion velocity.
acsc_Arc1 Adds an arc segment to a segmented motion and specifies
the coordinates of center point, coordinates of the final
point, and the direction of rotation.
acsc_ExtArc1 Adds an arc segment to a segmented motion and specifies
the coordinates of center point, coordinates of the final
point, direction of rotation, and the vector velocity for the
current segment.
acsc_Arc2 Add’s an arc segment to a segmented motion and specifies
the coordinates of center point and rotation angle.
31 January 2009 212 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-226-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_Segment
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2], Center[2];
// create segmented motion, coordinates of the initial point are (1000,1000)
Point[0] = 1000; Point[1] = 1000;
if (!acsc_Segment(Handle, // communication handle
0, // create the segmented motion with default
// velocity
Axes, // axes XY
Point, // initial point
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add arc segment with center (1000, 0), final point (1000, -1000),
// clockwise rotation
Center[0] = 1000; Center[1] = 0;
Point[0] = 1000; Point[1] = -1000;
acsc_Arc1(Handle, Axes, Center, Point, ACSC_CLOCKWISE, NULL);
// add line segment with final point (-1000, -1000)
Point[0] = -1000; Point[1] = -1000;
acsc_Line(Handle, Axes, Point, NULL);
// add arc segment with center (-1000, 0) and rotation angle -
Center[0] = -1000; Center[1] = 0;
acsc_Arc2(Handle, Axes, Center, -3.141529, NULL);
// add line segment with final point (1000, 1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Line(Handle, Axes, Point, NULL);
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
4.21.2 acsc_Line
Description
The function adds a linear segment to a segmented motion.
Syntax
int acsc_Line(HANDLE Handle, int* Axes, double* Point, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
31 January 2009 216 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-230-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_Line
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[] = { 1000, 1000 };
if (!acsc_Line( Handle, // communication handle
Axes, // axes XY
Points, // final point coordinates
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.21.3 acsc_ExtLine
Description
The function adds a linear segment to a segmented motion and specifies a motion velocity.
Syntax
int acsc_ExtLine(HANDLE Handle, int* Axes, double* Point, double Velocity,
ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axes Array of axes. Each element specifies one involved axis:
ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the
last axis, one additional element must be located that contains –1 and
marks the end of the array.
For the full list of the axis constants, see “Axis Definitions” on
Page 378.
Point Array of the final point coordinates. The number and order of values
must correspond to the Axes array. The Point must specify a value for
each element of Axes except the last –1 element.
Velocity If the motion was activated by the acsc_Segment function with the
ACSC_AMF_VELOCITY flag, this parameter specifies a motion
velocity for current segment.
31 January 2009 218 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-232-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_ExtLine
// the path of the specified segmented motion is square
// for each side of the square the non-default vector velocity is used
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2];
// create segmented motion, coordinates of the initial point are
// (1000,1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, ACSC_AMF_VELOCITY, Axes, Point, NULL);
// add line segment with final point (1000, -1000), vector velocity 25000
Point[0] = 1000; Point[1] = -1000;
acsc_ExtLine( Handle, // communication handle
Axes, // axes XY
Point, // final point
25000, // vector velocity
NULL // waiting call
);
// add line segment with final point (-1000, -1000), vector velocity 15000
Point[0] = -1000; Point[1] = -1000;
acsc_ExtLine(Handle, Axes, Point, 15000, NULL);
// add line segment with final point (-1000, 1000)
// if the velocity argument is omitted, the velocity from the previous
// segment is used
Point[0] = -1000; Point[1] = 1000;
acsc_Line(Handle, Axes, Point, NULL);
// add line segment with final point (1000, 1000), vector velocity 5000
Point[0] = 1000; Point[1] = 1000;
acsc_ExtLine(Handle, Axes, Point, 5000, NULL);
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
4.21.4 acsc_Arc1
Description
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point, the coordinates of the final point and the direction of rotation.
Syntax
int acsc_Arc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int
Rotation, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
31 January 2009 220 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-234-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of the acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The parameter FinalPoint
specifies the coordinates of the final point. All coordinates are absolute in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_Arc1
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2], Center[2];
// create segmented motion, coordinates of the initial point are
// (1000,1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, 0, Axes, Point, NULL);
// describe circle with center (1000, 0), final point (1000, 1000),
// clockwise rotation
Center[0] = 1000; Center[1] = 0;
Point[0] = 1000; Point[1] = 1000;
if (!acsc_Arc1( Handle, // communication handle
Axes, // axes XY
Center, // center of the circle
Point, // final point
ACSC_CLOCKWISE, // clockwise rotation
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
4.21.5 acsc_ExtArc1
Description
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point, the coordinates of the final point, the direction of rotation, and the vector velocity
for the current segment.
31 January 2009 222 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-236-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The function adds an arc segment to the segmented motion and specifies the coordinates of the
center point, the coordinates of the final point, the direction of rotation, and the vector velocity
for the current segment. To add an arc segment with default velocity, use acsc_Arc1.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The parameter FinalPoint
specifies the coordinates of the final point. All coordinates are absolute in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_ExtArc1
// the path of the specified segmented motion is circle
// for each semicircle the different vector velocity is used
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2], Center[2];
// create segmented motion, coordinates of the initial point are
// (1000,1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, ACSC_AMF_VELOCITY, Axes, Point, NULL);
// add arc segment with center (1000, 0), final point (1000, -1000),
// clockwise rotation, vector velocity 25000
Center[0] = 1000; Center[1] = 0;
Point[0] = 1000; Point[1] = -1000;
if (!acsc_ExtArc1(Handle, // communication handle
31 January 2009 224 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-238-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Axes, // axes XY
Center, // center of the circle
Point, // final point
ACSC_CLOCKWISE, // clockwise rotation
25000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add arc segment with center (1000, 0), final point (1000, 1000),
// clockwise rotation, vector velocity 15000
Center[0] = 1000; Center[1] = 0;
Point[0] = 1000; Point[1] = 1000;
if (!acsc_ExtArc1(Handle, // communication handle
Axes, // axes XY
Center, // center of the circle
Point, // final point
ACSC_CLOCKWISE, // clockwise rotation
15000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
4.21.6 acsc_Arc2
Description
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point and the rotation angle.
Syntax
int acsc_Arc2(HANDLE Handle, int* Axes, double* Center, double Angle,
ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
31 January 2009 225 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-239-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns a non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_Arc2
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2], Center[2];
// create segmented motion, coordinates of the initial point are
// (1000,1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, 0, Axes, Point, NULL);
// describe circle with center (1000, 0), clockwise rotation
Center[0] = 1000; Center[1] = 0;
if (!acsc_Arc2(Handle, // communication handle
Axes, // axes XY
Center, // center of the circle
-2 * 3.141529,// full circle
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
4.21.7 acsc_ExtArc2
Description
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point, the rotation angle, and the vector velocity for the current segment.
Syntax
int acsc_ExtArc2(HANDLE Handle, int* Axes, double* Center, double Angle, double
Velocity, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
31 January 2009 227 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-241-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
number and order of axes of the acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The coordinates are absolute
in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns a non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
Axes, // axes XY
Center, // center of the circle
-3.141529,// semicircle
15000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
// example of the waiting call of acsc_ExtArc2
// the path of the specified segmented motion is circle
// for each semicircle the different vector velocity is used
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2], Center[2];
// create segmented motion, coordinates of the initial point are
// (1000, 1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, ACSC_AMF_VELOCITY, Axes, Point, NULL);
// add arc segment with center (1000, 0), negative rotation angle -, vector
// velocity 25000
Center[0] = 1000; Center[1] = 0;
if (!acsc_ExtArc2(Handle, // communication handle
Axes, // axes XY
Center, // center of the circle
-3.141529,// semicircle
25000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
// add arc segment with center (1000, 0), negative rotation angle -, vector
// velocity 15000
Center[0] = 1000; Center[1] = 0;
if (!acsc_ExtArc2(Handle, // communication handle
31 January 2009 229 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-243-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
The function is used to avoid velocity jump in the inflection points. If the function is specified
between two segments, the controller provides smooth deceleration to zero in the end of first
segment and smooth acceleration to specified velocity in the beginning of second segment.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_Stopper
// the example provides a rectangular path without velocity jumps
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
double Point[2];
// create segmented motion, coordinates of the initial point are
// (1000,1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, 0, Axes, Point, NULL);
// add line segment with final point (1000, -1000)
Point[0] = 1000; Point[1] = -1000;
acsc_Line(Handle, Axes, Point, NULL);
acsc_Stopper(Handle, Axes, NULL);
// add line segment with final point (-1000, -1000)
Point[0] = -1000; Point[1] = -1000;
acsc_Line(Handle, Axes, Point, NULL);
acsc_Stopper(Handle, Axes, NULL);
// add line segment with final point (-1000, 1000)
Point[0] = -1000; Point[1] = 1000;
acsc_Line(Handle, Axes, Point, NULL);
acsc_Stopper(Handle, Axes, NULL);
// add line segment with final point (1000, 1000)
Point[0] = 1000; Point[1] = 1000;
acsc_Line(Handle, Axes, Point, NULL);
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
4.21.9 acsc_Projection
Description
The function sets a projection matrix for segmented motion.
Syntax
int acsc_Projection(HANDLE Handle, int* Axes, char* Matrix, ACSC_WAITBLOCK*
Wait)
Arguments
Handle Communication handle.
31 January 2009 231 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-245-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_Projection
int Axes[4];
double Point[2], Center[2];
// prepare the projection matrix
double Matrix[3][2] = {{ 1, 0 },
{ 0, 1.41421 },
{ 0, 1.41421 } };
// declare the matrix that will contain the projection
acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, “ProjectionMatrix(3)(2)”,
NULL);
// initialize the projection matrix
acsc_WriteReal(Handle, ACSC_NONE, "ProjectionMatrix", 0, 2, 0, 1, Matrix,
NULL);
Axes[0]= ACSC_AXIS_X; Axes[1]=ACSC_AXIS_Y;
Axes[2]= ACSC_AXIS_Z; Axes[3] = -1; // create a group of the involved
// axes
acsc_Group(Handle, Axes, NULL); // create segmented motion,
// coordinates of the initial point
// are (1000,1000)
Axes[0] = ACSC_AXIS_X; Axes[1] = ACSC_AXIS_Y; Axes[2] = -1;
Point[0] = 1000; Point[1] = 1000;
acsc_Segment(Handle, 0, Axes, Point, NULL);
// incline the working plane XY by
// 45°
Axes[0] = 0; Axes[1] = 1; Axes[2] = 2; Axes[3] = -1;
acsc_Projection(Handle, Axes, “ProjectionMatrix”, NULL);
// describe circle with center (1000, 0), clockwise rotation
// although the circle was defined, really on the plane XY we will get the
// ellipse stretched along the Y axis
Axes[0] = 0; Axes[1] = 1; Axes[2] = -1;
Center[0] = 1000; Center[1] = 0;
acsc_Arc2(Handle, Axes, Center, -2 * 3.141529, NULL);
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
31 January 2009 233 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-247-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_AddPointM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
int Points[2];
int i;
acsc_MultiPointM(Handle, 0, Axes, 0, NULL)); // create multi-point motion
// add some points
for (i = 0; i < 5; i++)
{
Points[0] = 1000 * i; Points[1] = 1000 * i;
// points (1000, 1000), (2000, 2000)…
if (!acsc_AddPointM(Handle, Axes, Points, NULL))
{
printf("transaction error: %dn", acsc_GetLastError());
break;
}
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion
4.22.3 acsc_ExtAddPoint
Description
The function adds a point to a single-axis multi-point or spline motion and specifies a specific
velocity or motion time.
Syntax
int acsc_ExtAddPoint(HANDLE Handle, int Axis, double Point, double Rate,
ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.
For the full list of the axis constants, see “Axis Definitions” on
Page 378.
Point Coordinate of the added point.
Rate If the motion was activated by the acsc_MultiPoint function with
the ACSC_AMF_VELOCITY flag, this parameter defines the
motion velocity.
If the motion was activated by the acsc_Spline function with the
ACSC_AMF_VARTIME flag, this parameter defines the time
interval between the previous point and the present one.
31 January 2009 238 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-252-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_ExtAddPointM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
int Points[2];
int i;
// create multi-point motion with specific velocity
acsc_MultiPointM(Handle, ACSC_AMF_VELOCITY, Axes, 0, NULL));
// add some points
for (i = 0; i < 5; i++)
{
Points[0] = 1000 * i; Points[1] = 1000 * i;
if (!acsc_ExtAddPointM(Handle, // communication handle
Axes, // axes XY
Points, // points (1000,1000),
// (2000,2000), …
5000, // in this case Rate defines
// a motion velocity
NULL
))
{
printf("transaction error: %dn", acsc_GetLastError());
break;
}
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion
4.22.5 acsc_EndSequence
Description
The function informs the controller, that no more points will be specified for the current single-
axis motion.
Syntax
int acsc_EndSequence(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.
For the full list of the axis constants, see “Axis Definitions” on
Page 378.
31 January 2009 242 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-256-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_EndSequenceM
int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 };
int Points[2];
int i;
// create multi-point motion
acsc_MultiPointM(Handle, 0, Axes, 0, NULL);
// add some points
for (i = 0; i < 5; i++)
{
Points[0] = 1000 * i; Points[1] = 1000 * i;
// points (1000, 1000), (2000, 2000), …
acsc_AddPointM(Handle, Axes, Points, NULL);
}
// the end of the multi-point motion
if (!acsc_EndSequenceM( Handle, // communication handle
Axes, // axes XY
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.23 Data Collection Functions
The Data Collection functions are:
Table 27 Data Collection Functions
Function Description
acsc_DataCollection Initiates data collection.
acsc_StopCollect Terminates data collection.
acsc_WaitCollectEnd Wait for the end of data collection.
4.23.1 acsc_DataCollection
Description
The function initiates data collection.
Syntax
int acsc_DataCollection(HANDLE Handle, int Flags, int Axis, char* Array, int NSample,
int Period, char* Vars, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
31 January 2009 246 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-260-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_DataCollection
// matrix consisting of two rows with 1000 columns each
char* ArrayName = "DCA(2)(1000)";
// positions of axes X and Y will be collected
char Vars[] ="FPOS(0)rFPOS(1)";
acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, ArrayName, NULL);
if (!acsc_DataCollection (Handle,// communication handle
ACSC_DCF_SYNC,// system data collection
ArrayName,// name of data collection array
1000,// number of samples to be collected
1,// sampling period 1 millisecond
Vars,// variables to be collected
NULL// waiting call ))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.23.2 acsc_StopCollect
Description
The function terminates data collection.
Syntax
int acsc_StopCollect(HANDLE Handle, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is ACSC_SYNCHRONOUS, the function returns when the
controller response is received.
If Wait points to a valid ACSC_WAITBLOCK structure, the function
returns immediately. The calling thread must then call the
acsc_WaitForAsyncCall function to retrieve the operation result.
If Wait is ACSC_IGNORE, the function returns immediately. In this
case, the operation result is ignored by the library and cannot be
retrieved to the calling thread.
Return Value
If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero.
31 January 2009 249 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-263-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
The usual system data collection finishes when the required number of samples is collected or
the acsc_StopCollect function is executed. The application can wait for data collection end
with the acsc_WaitCollectEnd function.
The temporal data collection runs until the acsc_StopCollect function is executed.
The function terminates the data collection prematurely. The application can determine the
number of actually collected samples from the S_DCN variable and the actual sampling period
from the S_DCP variable.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_StopCollect
// matrix consisting of rows with 1000 columns each
char* ArrayName = “DCA(2)(1000)”;
// positions of axes X and Y will be collected
char* Vars[] = { “FPOS(0)”, “FPOS(1)” };
acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, ArrayName, NULL);
acsc_Collect(Handle, ACSC_DCF_TEMPORAL, ArrayName, 1000, 1, Vars, NULL);
// waiting for some time
Sleep(2000);
if (!acsc_StopCollect(Handle, NULL))
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.23.3 acsc_WaitCollectEnd
Description
The function waits for the end of data collection.
Syntax
int acsc_WaitCollectEnd(HANDLE Handle, int Timeout)
31 January 2009 250 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-264-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Note
Extended error information can be obtained by calling acsc_GetLastError.
Comments
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
If the reason for the fault is still active, the controller will set the fault immediately after this
command is performed. If cleared fault is Encoder Error, the feedback position is reset to zero.
Example
// example of the waiting call of acsc_FclearM
int Axes[]={ACSC_AXIS_X,ACSC_AXIS_Y,-1};
if (!acsc_FaultClearM(Handle, // communication handle
Axes,
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
31 January 2009 310 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-324-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
function returns ACSC_OPERATIONABORTED error.
Example
char* cmd = "?VRr";// get firmware version
char buf[101];
int Received;
ACSC_WAITBLOCK wait;
if (!acsc_Transaction(Handle, cmd, strlen(cmd), buf, 100, &Received,
&wait))
{
printf("transaction error: %dn", acsc_GetLastError());
}
else
{
// call is pending
if (acsc_WaitForAsyncCall(Handle, // communication handle
buf, // pointer to the same buffer, that was specified
// for acsc_Transaction
&Received, // received bytes
&wait, // pointer to the same structure, that was
// specified for acsc_Transaction
500 // 500 ms
))
{
buf[Received] = ‘0’;
printf(“Firmware version: %sn”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘0’;
printf("error: %sn", buf);
}
}
4.27.4 acsc_WaitProgramEnd
Description
The function waits for the program termination in the specified buffer.
Syntax
int acsc_WaitProgramEnd (HANDLE Handle, int Buffer, int Timeout)
Arguments
Handle Communication handle.
Buffer Buffer number, from 0 to 9.
31 January 2009 315 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-329-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_GetFirmwareVersion
char Firmware[256];
int Received;
if (!acsc_GetFirmwareVersion( Handle, // communication handle
Firmware, // buffer for the firmware
// version
255, // size of the buffer
&Received, // number of actually
// received characters
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
else
{
Firmware[Received] = ‘0’;
printf("Firmware version of the controller: %sn", Firmware);
}
4.30.2 acsc_GetSerialNumber
Description
The function retrieves the controller serial number.
Syntax
int acsc_GetSerialNumber(HANDLE Handle, char* SerialNumber, int Count, int*
Received, ACSC_WAITBLOCK* Wait)
Arguments
Handle Communication handle.
SerialNumber Pointer to the buffer that receives the serial number.
Count Size of the buffer pointed by SerialNumber.
Received Number of characters that were actually received.
31 January 2009 337 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-351-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_GetSerialNumber
char SerialNumber[256];
int Received;
if (!acsc_GetSerialNumber(Handle, // communication handle
SerialNumber, // buffer for the serial number
255, // size of the buffer
&Received, // number of actually received characters
NULL // waiting call
))
{
printf("transaction error: %dn", acsc_GetLastError());
}
else
{
SerialNumber[Received] = ‘0’;
printf("Controller serial number: %sn", SerialNumber);
}
4.31 Error Diagnosis Functions
The Error Diagnosis functions are:
Table 35 Error Diagnosis Functions
Function Description
acsc_GetMotorError Retrieves the reason why the motor was disabled.
acsc_GetMotionError Obsolete - replaced by acsc_GetMotorError.
acsc_GetProgramError Retrieves the error code of the last program error
encountered in the specified buffer.
4.31.1 acsc_GetMotorError
Description
The function retrieves the reason for motor disabling.
Syntax
int acsc_GetMotorError(HANDLE Handle, int Axis, int* Error, ACSC_WAITBLOCK*
Wait)
Arguments
Handle Communication handle.
31 January 2009 339 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-353-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_GetMotorError
int Error;
char ErrorStr[256];
int Received;
if (acsc_GetMotorError(Handle, // communication handle
ACSC_AXIS_X, // axis X
&Error, // received value
NULL // waiting call
))
{
if (Error > 0)
{
if (acsc_GetErrorString(Handle, Error, ErrorStr, 255,
&Received))
{
ErrorStr[Received] = ‘0’;
printf("Motor error: %d (%s)n", Error, ErrorStr);
}
}
}
else
{
if (Error > 0)
{
if (acsc_GetErrorString(Handle, Error, ErrorStr, 255,
&Received))
{
ErrorStr[Received] = ‘0’;
printf("Motor error: %d (%s)n", Error, ErrorStr);
}
}
}
else
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.31.2 acsc_GetMotionError
Note
This function is obsolete and will be deprecated in a future version of the C
Library. The function is supported for backward compatibility. In all cases,
use acsc_GetMotorError instead.
31 January 2009 341 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-355-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function.
Example
// example of the waiting call of acsc_GetMotionError
int Error;
char ErrorStr[256];
if (acsc_GetMotionError( Handle, // communication handle
ACSC_AXIS_X, // axis X
&Error, // received value
NULL // waiting call
))
{
if (Error > 0)
{
if (acsc_GetErrorString( Handle, Error, ErrorStr, 255,
&Received))
{
ErrorStr[Received] = ‘0’;
printf("Motion error: %d (%s)n", Error, ErrorStr);
}
}
}
else
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.31.3 acsc_GetProgramError
Description
The function retrieves the error code of the last program error encountered in the specified
buffer.
Syntax
int acsc_GetProgramError(HANDLE Handle, int Buffer, int* Error,
ACSC_WAITBLOCK* Wait)
31 January 2009 343 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-357-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
Example
// example of the waiting call of acsc_GetProgramError
int Error;
char ErrorStr[256];
if (acsc_GetProgramError(Handle, // communication handle
0, // buffer 0
&Error, // received value
NULL // waiting call
))
{
if (Error > 0)
{
if (acsc_GetErrorString( Handle, Error, ErrorStr, 255,
&Received))
{
ErrorStr[Received] = ‘0’;
printf("Program error: %d (%s)n", Error, ErrorStr);
}
}
}
else
{
printf("transaction error: %dn", acsc_GetLastError());
}
4.32 Dual Port RAM (DPRAM) Access
Functions
The Dual Port RAM Access functions are:
Table 36 Dual Port RAM (DPRAM) Access Functions
Function Description
acsc_ReadDPRAMInteger Reads 32-bit integer from DPRAM
acsc_WriteDPRAMInteger Writes 32-bit integer to DPRAM
acsc_ReadDPRAMReal Reads 64 real from DPRAM
acsc_WriteDPRAMReal Writes 64-bit real to DPRAM
4.32.1 acsc_ReadDPRAMInteger
Description
The function reads 32-bit integer from the DPRAM.
31 January 2009 345 C Library Functions](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-359-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
asynchronously to the user thread.
7.4 ACSC_CONNECTION_DESC
Description
The structure defines controller connection for an application. Used in the
acsc_GetConnectionsList and acsc_TerminateConnection functions.
Syntax
struct ACSC_CONNECTION_DESC { char Application[100]; HANDLE handle; dwor
ProcessID};
Arguments
Application Name of the application, maxium of 100 characters.
handle The channel’s Handle.
ProcessID The ID of the process.
7.5 Application Save/Load Structures
The following structures are used with the Application Save/Load functions:
7.5.1 ACSC_APPSL_STRING
Description
The structure defines a string in the application file.
Syntax
struct ACSC_APPSL_STRING { int length; char *string};
Arguments
length Length of the string
string Pointer to the start of the string
31 January 2009 400 Structures](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-414-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
9 Sample Programs
The following samples demonstrate the usage of the SPiiPlus C Library functions. The
examples show how to write the C/C++ applications that can communicate with the SPiiPlus
controller.
The samples open the communication with the controller or the simulator and perform some
simple tasks, like starting of a point-to-point motion, reading of a motor feedback position,
downloading an ACSPL+ program to the controller program buffer, etc.
After installation of the package in the SPiiPlus C Library directory, the full source code of
these samples with the projects for Visual C++ 6 and Visual Studio 2005 can be found.
9.1 Reciprocated Motion
The following two samples execute a reciprocated point-to-point motion and read a motor
feedback position. The first sample downloads the ACSPL+ program to the controller’s
program buffer and run it with help of the SPiiPlus C functions. The second sample uses the
SPiiPlus C functions to execute motion.
Both of the samples are written as Win32 console applications.
9.1.1 ACSPL+
The sample shows how to open communication with the simulator or with the controller (via
serial, ethernet or PCI Bus), how to download the ACSPL+ program to controller's buffer, and
how to execute it. The ACSPL+ program executes a reciprocated point-to-point motion.
File ACSPL.CPP:
#include <conio.h>
#include <stdio.h>
#include "windows.h"
#include "C:Program FilesACS Motion ControlSPiiPlus 6.50ACSCC_CPPacsc.h"
HANDLE hComm; // communication handle
void ErrorsHandler(const char* ErrorMessage, BOOL fCloseComm)
{
printf (ErrorMessage);
printf ("press any key to exit.n");
if (fCloseComm) acsc_CloseComm(hComm);
_getch();
};
int main(int argc, char *argv[])
{
31 January 2009 405 Sample Programs](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-419-320.jpg)
![C Library Reference Version 6.50 Programmer’s Guide
void ErrorsHandler(const char* ErrorMessage, BOOL fCloseComm)
{
printf (ErrorMessage);
printf ("press any key to exit.n");
if (fCloseComm) acsc_CloseComm(hComm);
_getch();
};
int main(int argc, char *argv[])
{
double FPOS;
int State;
printf ("ACS-Tech80 Ltd. Copyright (C) 2000. All Rights
Reserved.n");
printf ("Application executes reciprocated point-to-point motionn");
/*****************************************************************/
// Open communication with the simulator
printf ("Application opens communication with the simulator andn");
printf ("sends some commands to the simulator using SPiiPlus C Library
functionsnn");
printf ("Wait for opening of communication with the simulator...n");
hComm = acsc_OpenCommDirect();
if (hComm == ACSC_INVALID)
{
ErrorsHandler("error while opening communication.n", FALSE);
return -1;
}
printf ("Communication with the simulator was established
successfully!n");
/*****************************************************************/
/******************************************************************
// Example of opening communication with the controller via COM1
printf ("Application opens communication with the controller via
serial link andn");
printf ("sends some commands to the controller using SPiiPlus C Library
functionsnn");
printf ("Wait for opening of communication with the
controller...n");
hComm = acsc_OpenCommSerial(1, 115200);
31 January 2009 410 Sample Programs](https://image.slidesharecdn.com/spiiplusclibraryprogrammerguide-091027191220-phpapp02/85/S-Pii-Plus-C-Library-Programmer-Guide-424-320.jpg)
S Pii Plus+C+Library+Programmer+Guide
- 1. S Pi i P L US C Library Reference Programmer’s Guide Version 6.50
- 2. V e r s i o n 6 . 5 0 , 31 January 2009 COPYRIGHT Copyright ® 1999 - 2009 ACS Motion Control Ltd. Changes are periodically made to the information in this document. Changes are published as release notes and are be incorporated into future revisions of this document. No part of this document may be reproduced in any form without prior written permission from ACS Motion Control. TRADEMARKS ACS Motion Control, PEG and SPii are trademarks of ACS Motion Control Ltd. Visual Basic and Windows are trademarks of Microsoft Corporation. Any other companies and product names mentioned herein may be the trademarks of their respective owners. Web Site: www.AcsMotionControl.com Information: info@AcsMotionControl.com Tech Support: support@AcsMotionControl.com ACS Motion Control, Ltd. Ramat Gabriel Industrial Park POB 5668 Migdal HaEmek, 10500 ISRAEL Tel: (972) (4) 6546440 Fax: (972) (4) 6546443 ACS Motion Control, Inc. 6575 City West Parkway Eden Prairie, MN 55344 Tel: 800-545-2980 Tel. 763-559-7669 Fax. 763-559-0110 ACS Motion Control (Korea) Digital Empire Building D-191 980-3, Youngtong-dong, Youngtong-gu, Suwon, Geonggi-do, 443-813, Korea Tel: +82-31-202-3541 Fax: +82-31-202-3542 NOTICE The information in this document is deemed to be correct at the time of publishing. ACS Motion Control reserves the right to change specifications without notice. ACS Motion Control is not responsible for incidental, consequential, or special damages of any kind in connection with using this document. 31 January 2009 ii Programmer’s Guide
- 3. Programmer’s Guide Changes in Version 6.50 Page Change - The following C functions were added: acsc_OpenCommEthernetTCP acsc_OpenCommEthernetUDP acsc_GetConnectionsList acsc_TerminateConnection acsc_DataCollection acsc_LoadDataToController acsc_UploadDataFromController acsc_RegisterEmergencyStop acsc_UnregisterEmergencyStop acsc_AnalyzeApplication acsc_SaveApplication acsc_FreeApplication acsc_LoadApplication acsc_ControllerReboot acsc_ControllerFactoryDefault - The following C functions are obsolete: acsc_Collect acsc_CollectB acsc_LoadFileToIntegerVariable acsc_LoadFileToRealVariable acsc_OpenCommEthernet Version 6.50, 31 January 2009 iii Programmer’s Guide
- 4. C Library Reference Version 6.50 Programmer’s Guide Table of Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Organization of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Related SPiiPlus Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 SPiiPlus Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 Conventions Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.5 Statement Text and Icons Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2 SPiiPlus C Library Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1 Operation Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 Communication Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2.1 Run-Time Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2.2 Log Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3 C Library Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4 Communication Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5 Controller Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.6 Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.7 Supplied Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.8 Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.9 Use of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.10 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.11 Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.12 Hardware Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.13 Dual-Port RAM (DPRAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.14 Non-Waiting Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3 Using the SPiiPlus C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.1 Library Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.2 Building C/C++ Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.3 Redistribution of User Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.3.1 Redistributed Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.3.2 File Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3.3.3 Kernel Mode Driver Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4 C Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.1 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.1.1 acsc_OpenCommSerial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.1.2 acsc_OpenCommEthernetTCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.1.3 acsc_OpenCommEthernetUDP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.1.4 acsc_OpenCommDirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.1.5 acsc_OpenCommPCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.1.6 acsc_GetPCICards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.1.7 acsc_SetServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.1.8 acsc_SetServerExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.1.9 acsc_SetServerExtLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.1.10 acsc_CloseComm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 4.1.11 acsc_Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.1.12 acsc_Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 31 January 2009 iv Table of Contents
- 5. C Library Reference Version 6.50 Programmer’s Guide 4.1.13 acsc_Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.1.14 acsc_Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.1.15 acsc_WaitForAsyncCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.1.16 acsc_CancelOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.1.17 acsc_GetEthernetCards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.1.18 acsc_GetConnectionsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.1.19 acsc_TerminateConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.2 Service Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 4.2.1 acsc_GetCommOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 4.2.2 acsc_GetDefaultTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.2.3 acsc_GetErrorString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 4.2.4 acsc_GetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 4.2.5 acsc_GetLibraryVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 4.2.6 acsc_GetTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 4.2.7 acsc_SetIterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.2.8 acsc_SetCommOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 4.2.9 acsc_SetTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 4.2.10 acsc_SetQueueOverflowTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 4.2.11 acsc_GetQueueOverflowTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 4.3 ACSPL+ Program Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 4.3.1 acsc_AppendBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.3.2 acsc_ClearBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4.3.3 acsc_CompileBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.3.4 acsc_DownloadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 4.3.5 acsc_LoadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 4.3.6 acsc_LoadBufferIgnoreServiceLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.3.7 acsc_LoadBuffersFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 4.3.8 acsc_RunBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 4.3.9 acsc_StopBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 4.3.10 acsc_SuspendBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 4.3.11 acsc_UploadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4.4 Read and Write Variables Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.4.1 acsc_ReadInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.4.2 acsc_WriteInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 4.4.3 acsc_ReadReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 4.4.4 acsc_WriteReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 4.5 Load/Upload Data To/From Controller Functions . . . . . . . . . . . . . . . . . . . . . . . . 84 4.5.1 acsc_LoadDataToController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 4.5.2 acsc_UploadDataFromController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 4.6 Multiple Thread Synchronization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 4.6.1 acsc_CaptureComm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 4.6.2 acsc_ReleaseComm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 4.7 History Buffer Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 4.7.1 acsc_OpenHistoryBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 4.7.2 acsc_CloseHistoryBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 4.7.3 acsc_GetHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 4.8 Unsolicited Messages Buffer Management Functions . . . . . . . . . . . . . . . . . . . . . 95 4.8.1 acsc_OpenMessageBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 31 January 2009 v Table of Contents
- 6. C Library Reference Version 6.50 Programmer’s Guide 4.8.2 acsc_CloseMessageBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 4.8.3 acsc_GetSingleMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 4.8.4 acsc_GetMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 4.9 Log File Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 4.9.1 acsc_SetLogFileOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 4.9.2 acsc_OpenLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 4.9.3 acsc_CloseLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 4.9.4 acsc_WriteLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 4.9.5 acsc_FlushLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 4.10 System Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 4.10.1 acsc_SetConf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 4.10.2 acsc_GetConf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 4.11 Setting and Reading Motion Parameters Functions . . . . . . . . . . . . . . . . . . . . . . 108 4.11.1 acsc_SetVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4.11.2 acsc_GetVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 4.11.3 acsc_SetAcceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 4.11.4 acsc_GetAcceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 4.11.5 acsc_SetDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 4.11.6 acsc_GetDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 4.11.7 acsc_SetJerk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 4.11.8 acsc_GetJerk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.11.9 acsc_SetKillDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 4.11.10 acsc_GetKillDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 4.11.11 acsc_SetVelocityImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 4.11.12 acsc_SetAccelerationImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 4.11.13 acsc_SetDecelerationImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 4.11.14 acsc_SetJerkImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 4.11.15 acsc_SetKillDecelerationImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 4.11.16 acsc_SetFPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 4.11.17 acsc_GetFPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 4.11.18 acsc_SetRPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 4.11.19 acsc_GetRPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 4.11.20 acsc_GetFVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 4.11.21 acsc_GetRVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 4.12 Axis/Motor Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 4.12.1 acsc_Commut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 4.12.2 acsc_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 4.12.3 acsc_EnableM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 4.12.4 acsc_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 4.12.5 acsc_DisableAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 4.12.6 acsc_DisableExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 4.12.7 acsc_DisableM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 4.12.8 acsc_Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 4.12.9 acsc_Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 4.12.10 acsc_SplitAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 4.13 Motion Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 4.13.1 acsc_Go . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 4.13.2 acsc_GoM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 31 January 2009 vi Table of Contents
- 7. C Library Reference Version 6.50 Programmer’s Guide 4.13.3 acsc_Halt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 4.13.4 acsc_HaltM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 4.13.5 acsc_Kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 4.13.6 acsc_KillAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 4.13.7 acsc_KillM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 4.13.8 acsc_KillExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 4.13.9 acsc_Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 4.13.10 acsc_BreakM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 4.14 Point-to-Point Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 4.14.1 acsc_ToPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 4.14.2 acsc_ToPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 4.14.3 acsc_ExtToPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 4.14.4 acsc_ExtToPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 4.15 Track Motion Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 4.15.1 acsc_Track . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 4.15.2 acsc_SetTargetPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 4.15.3 acsc_GetTargetPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 4.16 Jog Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 4.16.1 acsc_Jog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 4.16.2 acsc_JogM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 4.17 Slaved Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 4.17.1 acsc_SetMaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 4.17.2 acsc_Slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 4.17.3 acsc_SlaveStalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 4.18 Multi-Point Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 4.18.1 acsc_MultiPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 4.18.2 acsc_MultiPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 4.19 Arbitrary Path Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 4.19.1 acsc_Spline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 4.19.2 acsc_SplineM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 4.20 PVT Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 4.20.1 acsc_AddPVPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 4.20.2 acsc_AddPVPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 4.20.3 acsc_AddPVTPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 4.20.4 acsc_AddPVTPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 4.21 Segmented Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 4.21.1 acsc_Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 4.21.2 acsc_Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 4.21.3 acsc_ExtLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 4.21.4 acsc_Arc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 4.21.5 acsc_ExtArc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 4.21.6 acsc_Arc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 4.21.7 acsc_ExtArc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 4.21.8 acsc_Stopper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 4.21.9 acsc_Projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 4.22 Points and Segments Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 4.22.1 acsc_AddPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 4.22.2 acsc_AddPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 31 January 2009 vii Table of Contents
- 8. C Library Reference Version 6.50 Programmer’s Guide 4.22.3 acsc_ExtAddPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 4.22.4 acsc_ExtAddPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 4.22.5 acsc_EndSequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 4.22.6 acsc_EndSequenceM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 4.23 Data Collection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 4.23.1 acsc_DataCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 4.23.2 acsc_StopCollect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 4.23.3 acsc_WaitCollectEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 4.24 Status Report Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 4.24.1 acsc_GetMotorState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 4.24.2 acsc_GetAxisState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 4.24.3 acsc_GetIndexState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 4.24.4 acsc_ResetIndexState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 4.24.5 acsc_GetProgramState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 4.25 Input/Output Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 4.25.1 acsc_GetInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 4.25.2 acsc_GetInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 4.25.3 acsc_GetOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 4.25.4 acsc_GetOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 4.25.5 acsc_SetOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 4.25.6 acsc_SetOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 4.25.7 acsc_GetAnalogInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 4.25.8 acsc_GetAnalogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 4.25.9 acsc_SetAnalogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 4.25.10 acsc_GetExtInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 4.25.11 acsc_GetExtInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 4.25.12 acsc_GetExtOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 4.25.13 acsc_GetExtOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 4.25.14 acsc_SetExtOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 4.25.15 acsc_SetExtOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 4.26 Safety Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 4.26.1 acsc_GetFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 4.26.2 acsc_SetFaultMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 4.26.3 acsc_GetFaultMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 4.26.4 acsc_EnableFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 4.26.5 acsc_DisableFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 4.26.6 acsc_SetResponseMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 4.26.7 acsc_GetResponseMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 4.26.8 acsc_EnableResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 4.26.9 acsc_DisableResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 4.26.10 acsc_GetSafetyInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 4.26.11 acsc_GetSafetyInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 4.26.12 acsc_GetSafetyInputPortInv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 4.26.13 acsc_SetSafetyInputPortInv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 4.26.14 acsc_FaultClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 4.26.15 acsc_FaultClearM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 4.27 Wait-for-Condition Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 4.27.1 acsc_WaitMotionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 31 January 2009 viii Table of Contents
- 9. C Library Reference Version 6.50 Programmer’s Guide 4.27.2 acsc_WaitLogicalMotionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 4.27.3 acsc_WaitForAsyncCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 4.27.4 acsc_WaitProgramEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 4.27.5 acsc_WaitMotorEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 4.27.6 acsc_WaitInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 4.27.7 acsc_WaitUserCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 4.27.8 acsc_WaitMotorCommutated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 4.28 Callback Registration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 4.28.1 acsc_SetCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 4.28.2 acsc_SetCallbackExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 4.28.3 acsc_SetInterruptMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 4.28.4 acsc_GetInterruptMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 4.28.5 acsc_SetCallbackPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 4.29 Variables Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 4.29.1 acsc_DeclareVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 4.29.2 acsc_ClearVariables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 4.30 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 4.30.1 acsc_GetFirmwareVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 4.30.2 acsc_GetSerialNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 4.31 Error Diagnosis Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 4.31.1 acsc_GetMotorError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 4.31.2 acsc_GetMotionError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 4.31.3 acsc_GetProgramError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 4.32 Dual Port RAM (DPRAM) Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 4.32.1 acsc_ReadDPRAMInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 4.32.2 acsc_WriteDPRAMInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 4.32.3 acsc_ReadDPRAMReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 4.32.4 acsc_WriteDPRAMReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 4.33 Position Event Generation (PEG) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 4.33.1 acsc_PegInc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 4.33.2 acsc_PegRandom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 4.33.3 acsc_AssignPins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 4.33.4 acsc_StopPeg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 4.34 Emergency Stop Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 4.34.1 acsc_RegisterEmergencyStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 4.34.2 acsc_UnregisterEmergencyStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 4.35 Application Save/Load Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 4.35.1 acsc_AnalyzeApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 4.35.2 acsc_LoadApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 4.35.3 acsc_SaveApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 4.35.4 acsc_FreeApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 4.36 Reboot Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 4.36.1 acsc_ControllerReboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 4.36.2 acsc_ControllerFactoryDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 5 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 6 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 31 January 2009 ix Table of Contents
- 10. C Library Reference Version 6.50 Programmer’s Guide 6.1.1 ACSC_SYNCHRONOUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6.1.2 ACSC_INVALID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6.1.3 ACSC_NONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6.1.4 ACSC_IGNORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6.1.5 ACSC_INT_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6.1.6 ACSC_REAL_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6.1.7 ACSC_MAX_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6.1.8 ACSC_COUNTERCLOCKWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6.1.9 ACSC_CLOCKWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6.1.10 ACSC_POSITIVE_DIRECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6.1.11 ACSC_NEGATIVE_DIRECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 6.2 General Communication Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 6.2.1 ACSC_COMM_USECHECKSUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 6.2.2 ASCS_COMM_AUTORECOVER_HW_ERROR . . . . . . . . . . . . . . . . . . . . . 377 6.3 Ethernet Communication Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 6.3.1 ACSC_SOCKET_DGRAM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 6.3.2 ACSC_SOCKET_STREAM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6.4 Axis Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6.4.1 ACSC_AXIS_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6.4.2 ACSC_AXIS_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6.4.3 ACSC_AXIS_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6.4.4 ACSC_AXIS_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6.4.5 ACSC_AXIS_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6.4.6 ACSC_AXIS_B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6.4.7 ACSC_AXIS_C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6.4.8 ACSC_AXIS_D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6.5 Motion Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6.5.1 ACSC_AMF_WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6.5.2 ACSC_AMF_RELATIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6.5.3 ACSC_AMF_VELOCITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6.5.4 ACSC_AMF_ENDVELOCITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6.5.5 ACSC_AMF_POSITIONLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6.5.6 ACSC_AMF_VELOCITYLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6.5.7 ACSC_AMF_CYCLIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6.5.8 ACSC_AMF_VARTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 6.5.9 ACSC_AMF_CUBIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 6.5.10 ACSC_AMF_EXTRAPOLATED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 6.5.11 ACSC_AMF_STALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 6.5.12 ACSC_AMF_MAXIMUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6.5.13 ACSC_AMF_SYNCHRONOUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6.6 Data Collection Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6.6.1 ACSC_DCF_TEMPORAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6.6.2 ACSC_DCF_CYCLIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6.6.3 ACSC_DCF_SYNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 6.6.4 ACSC_DCF_WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 6.7 Motor State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 6.7.1 ACSC_MST_ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 6.7.2 ACSC_MST_INPOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 31 January 2009 x Table of Contents
- 11. C Library Reference Version 6.50 Programmer’s Guide 6.7.3 ACSC_MST_MOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 6.7.4 ACSC_MST_ACC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6.8 Axis State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6.8.1 ACSC_AST_LEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6.8.2 ACSC_AST_DC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6.8.3 ACSC_AST_PEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6.8.4 ACSC_AST_MOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6.8.5 ACSC_AST_ACC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6.8.6 ACSC_AST_SEGMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6.8.7 ACSC_AST_VELLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6.8.8 ACSC_AST_POSLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6.9 Index and Mark State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6.9.1 ACSC_IST_IND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6.9.2 ACSC_IST_IND2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6.9.3 ACSC_IST_MARK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6.9.4 ACSC_IST_MARK2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6.10 Program State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6.10.1 ACSC_PST_COMPILED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6.10.2 ACSC_PST_RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6.10.3 ACSC_PST_SUSPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 6.10.4 ACSC_PST_DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 6.10.5 ACSC_PST_AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 6.11 Safety Control Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 6.11.1 ACSC_SAFETY_RL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 6.11.2 ACSC_SAFETY_LL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 6.11.3 ACSC_SAFETY_RL2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6.11.4 ACSC_SAFETY_LL2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6.11.5 ACSC_SAFETY_HOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6.11.6 ACSC_SAFETY_SRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6.11.7 ACSC_SAFETY_SLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6.11.8 ACSC_SAFETY_ENCNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6.11.9 ACSC_SAFETY_ENC2NC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 6.11.10 ACSC_SAFETY_DRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 6.11.11 ACSC_SAFETY_ENC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 6.11.12 ACSC_SAFETY_ENC2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 6.11.13 ACSC_SAFETY_PE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 6.11.14 ACSC_SAFETY_CPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 6.11.15 ACSC_SAFETY_VL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 6.11.16 ACSC_SAFETY_AL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 6.11.17 ACSC_SAFETY_CL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 6.11.18 ACSC_SAFETY_SP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 6.11.19 ACSC_SAFETY_PROG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 6.11.20 ACSC_SAFETY_MEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 6.11.21 ACSC_SAFETY_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 6.11.22 ACSC_SAFETY_ES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 6.11.23 ACSC_SAFETY_INT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 6.11.24 ACSC_SAFETY_INTGR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 6.12 Callback Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 31 January 2009 xi Table of Contents
- 12. C Library Reference Version 6.50 Programmer’s Guide 6.12.1 Hardware Callback Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 6.12.1.1 ACSC_INTR_PEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 6.12.1.2 ACSC_INTR_MARK1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 6.12.1.3 ACSC_INTR_MARK2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 6.12.1.4 ACSC_INTR_EMERGENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 6.12.2 Software Callback Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 6.12.2.1 ACSC_INTR_PHYSICAL_MOTION_END . . . . . . . . . . . . . . . . . . . . . . . 393 6.12.2.2 ACSC_INTR_LOGICAL_MOTION_END . . . . . . . . . . . . . . . . . . . . . . . . 393 6.12.2.3 ACSC_INTR_MOTION_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 6.12.2.4 ACSC_INTR_MOTOR_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 6.12.2.5 ACSC_INTR_PROGRAM_END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 6.12.2.6 ACSC_INTR_COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 6.12.2.7 ACSC_INTR_ACSPL_PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 6.12.2.8 ACSC_INTR_INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 6.12.2.9 ACSC_INTR_MOTION_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 6.12.2.10 ACSC_INTR_MOTION_PHASE_CHANGE . . . . . . . . . . . . . . . . . . . . . . . 394 6.12.2.11 ACSC_INTR_TRIGGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 6.12.2.12 ACSC_INTR_MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 6.13 Callback Interrupt Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 6.14 Configuration Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 7 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 7.1 ACSC_WAITBLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 7.2 ACSC_PCI_SLOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 7.3 ACSC_HISTORYBUFFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 7.4 ACSC_CONNECTION_DESC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 7.5 Application Save/Load Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 7.5.1 ACSC_APPSL_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 7.5.2 ACSC_APPSL_SECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 7.5.3 ACSC_APPSL_ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 7.5.4 ACSC_APPSL_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 8 Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 8.1 ACSC_LOG_DETALIZATION_LEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 8.2 ACSC_LOG_DATA_PRESENTATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 8.3 ACSC_APPSL_FILETYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 9 Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 9.1 Reciprocated Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 9.1.1 ACSPL+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 9.1.2 Immediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 9.2 Communication Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 31 January 2009 xii Table of Contents
- 13. C Library Reference Version 6.50 Programmer’s Guide List of Figures Figure 1 C Library Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Figure 2 Emergency Stop Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 31 January 2009 xiii List of Figures
- 14. C Library Reference Version 6.50 Programmer’s Guide List of Tables Table 1 Related SPiiPlus Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Table 2 Collateral Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Table 3 Text Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Table 4 Hardware Interrupt Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Table 5 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Table 6 Service Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Table 7 ASSPL+ Program Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Table 8 Read and Write Variables Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Table 9 Load File to ACSPL+ Variables Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Table 10 Multiple Thread Synchronization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Table 11 History Buffer Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Table 12 Unsolicited Messages Buffer Management Functions. . . . . . . . . . . . . . . . . . . . . . . . . . 95 Table 13 Log File Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Table 14 System Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Table 15 Setting and Reading Motion Parameters Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Table 16 Axis/Motor Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Table 17 Motion Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Table 18 Point-to-Point Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Table 19 Track Motion Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Table 20 Jog Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Table 21 Slaved Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Table 22 Multi-point Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Table 23 Arbitrary Path Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Table 24 PVT Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Table 25 Segmented Motion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Table 26 Points and Segments Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Table 27 Data Collection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Table 28 Status Report Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Table 29 Input/Output Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Table 30 Safety Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Table 31 Wait-for-Condition Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Table 32 Callback Registration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Table 33 Variables Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Table 34 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Table 35 Error Diagnosis Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Table 36 Dual Port RAM (DPRAM) Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Table 37 Position Event Generation (PEG) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Table 38 Emergency Stop Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Table 39 Application Save/Load Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Table 40 Reboot Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Table 41 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Table 42 Callback Interrupt Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Table 43 Configuration Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 31 January 2009 xiv List of Tables
- 15. C Library Reference Version 6.50 Programmer’s Guide 1 Introduction The SPiiPlus C Library supports the creation of a user application that operates on a PC host computer and communicates with SPiiPlus motion controllers. The SPiiPlus C Library implements a rich set of controller operations and conceals from the application the complexity of low-level communication and synchronization with the controller. 1.1 Organization of this Guide This guide is organized as follows: • Chapter 2 "SPiiPlus C Library Overview" • Chapter 3 "Using the SPiiPlus C Library" • Chapter 4 "C Library Functions" • Chapter 5 "Error Codes" • Chapter 6 "Constants" • Chapter 7 "Structures" • Chapter 8 "Enums" • Chapter 9 "Sample Programs" 1.2 Related SPiiPlus Tools Table 1 Related SPiiPlus Tools Tool Description SPiiPlus MMI A multipurpose user interface with the controller including: Program management, Motion management, Communication terminal, Four channel digital oscilloscope, Safety and I/O signals monitor, Signal tuning and adjustment, and a fully interactive simulator. Program and SPii debugging tools and FRF are also included. SPiiPlus Utilities The SPiiPlus Upgrader allows upgrading or downgrading of the controller firmware. The SPiiPlus Emergency Wizard allows firmware recovery in case of damage or loss of communication to the controller. Version 6.50, 31 January 2009 1 Introduction
- 16. C Library Reference Version 6.50 Programmer’s Guide Table 1 Related SPiiPlus Tools Tool Description SPiiPlus C Library A DLL (Dynamic Link Library) that supports host application programming in a variety of languages including C/C++. The library introduces a new level of application support with a built-in controller simulator and it also provides outstanding debugging capabilities. All tools are provided with a full simulator of the controller. SPiiPlus COM Library A DLL (Dynamic Link Library) that supports host application programming in a variety of languages including C#, Visual Basic, LabView, and more. The library introduces a new level of application support with a built-in controller simulator and it also provides outstanding debugging capabilities. All tools are provided with a full simulator of the controller. 1.3 SPiiPlus Documentation Table 2 Collateral Documentation (page 1 of 2) Document Description SPiiPlus PCI Series Hardware Installation and hardware connection with the SPiiPlus PCI 4 Guide or 8 axes SPiiPlus CM Hardware Guide Installation and hardware connection with the SPiiPlus Control Module HSSI Expansion Modules High-Speed Synchronous Serial Interface (HSSI) for Guide expanded I/O, distributed axes, and nonstandard devices. SPiiPlus Setup Guide Communication, configuration and adjustment procedures for SPiiPlus motion control products. SPiiPlus ACSPL+ Command set and high level language for programming Programmer's Guide SPiiPlus controllers. SPiiPlus Utilities User’s Guide Firmware upgrade and recovery procedures. SPiiPlus Command & Variable Complete description of all variables and commands in the Reference Guide ACSPL+ programming language. SPiiPlus C Library Reference C++ and Visual Basic® libraries for host PC applications. This guide is applicable for all the SPiiPlus motion control products SPiiPlus COM Library COM Methods, Properties, and Events for Communication Reference Guide with the Controller SPiiPlus FRF Analyzer User’s The SPiiPlus FRF (Frequency Response Function) Analyzer? Guide is a powerful servo analysis GUI for ACS Motion Control SPiiPlus motion controllers. Version 6.50, 31 January 2009 2 Introduction
- 17. C Library Reference Version 6.50 Programmer’s Guide Table 2 Collateral Documentation (page 2 of 2) Document Description SPiiPlus Modbus User’s Guide Describes Modbus setup and register address. SPiiPlus SA, SA-LT and SAR- Installation and hardware connection with the SPiiPlus SA LT Hardware Guide SPiiPlus SA-LT, and SAR-LT Controllers SPiiPlus 3U-LT & SPiiPlus 3U- Installation and hardware connection with the SPiiPlus 3U HP Hardware Guide Controller. 1.4 Conventions Used in this Guide Several text formats and fonts, illustrated in Table 3, are used in the text to convey information about the text. Table 3 Text Conventions Text Description BOLD CAPS ACSPL+ elements (commands, functions, operators, standard variables, etc.) when mentioned in the text. Software tool menus, menu items, dialog box names and dialog box elements. bold Emphasis or an introduction to a key concept. Monospace Code examples. Italic monospace Information in code examples that the user provides. ALL CAPS (Keyboard) key names [example: SHIFT key]. Bold Blue Text Links within this document, to web pages, and to e-mail addresses. Italic Blue Text Indicates name of referenced document. | Used in command syntax to indicate input of one alternative or another. Used in GUI descriptions to indicate nested menu items and dialog box options leading to a final action. For example, the sequence: Debug New Watch Real-time directs the user to open the Debug menu, choose the New Watch command, and select the Real-time option. Version 6.50, 31 January 2009 3 Introduction
- 18. C Library Reference Version 6.50 Programmer’s Guide 1.5 Statement Text and Icons Used in this Guide Note Notes include helpful information or tips. Caution A Caution describes a condition that may result in damage to equipment. Warning A Warning describes a condition that may result in serious bodily injury or death. Advanced Indicates a topic for advanced users. Model Highlights a specification, procedure, condition, or statement that depends on the product model. Version 6.50, 31 January 2009 4 Introduction
- 19. C Library Reference Version 6.50 Programmer’s Guide 2 SPiiPlus C Library Overview 2.1 Operation Environment The SPiiPlus C Library supports Microsoft® Windows® 2000, XP (32-bit and 64-bit), and Vista (32-bit and 64-bit). The previous version (v.4.50) of the C Library does not support remote access under Windows XP with Service Pack 2. The reason is that Service Pack 2 prevents unauthorized remote access. To provide authorized remote access in all supported versions of Windows, C Library v.5.0 and above supports the NTLM authentication protocol that performs security handshaking between the server and client. The protocol determines if the client have appropriate access rights to the machine that runs the C Library User-Mode Driver (UMD). Authorized remote access is supported in Windows 2000, Windows XP (Service Pack 1, Service Pack 2 and Service Pack 3), and Vista. 2.2 Communication Log 2.2.1 Run-Time Logging The UMD logs constantly at run-time. The data is stored in binary format in an internal cyclic buffer and is translated to text just before it is written to file. 2.2.2 Log Types The user may choose one of two mutually exclusive log types: • Dump on Request – all the binary data that is stored in the internal binary buffer and is flushed by explicit request to the file, see acsc_FlushLogFile. • Continuous – there is a background thread that takes care of periodic file update. It reads the binary buffer and performs text formatting to the file. 2.3 C Library Concept The C Library is a software package that allows Host-based applications to communicate with the SPiiPlus controller in order to program, send commands, and query controller status. The C Library includes user-mode and kernel-mode drivers that perform various communication tasks. 31 January 2009 5 SPiiPlus C Library Overview
- 20. C Library Reference Version 6.50 Programmer’s Guide The host application is provided with a robust C Function API to make calls the C Library which in turn communicates with the SPiiPlus Controller through the controller drivers. The controller then returns the reply to the to the caller application. The host application may contact C Library from remote location by setting its IP address or the machine name. Set the IP address with the acsc_SetServer function. Up to four host applications may communicate with the controller simultaneously via a single physical connection. Host Computer Remote Computer Host Application 1 Host Application 2 Remote C Library Application SPiiPlus SPiiPlus SPiiPlus SPiiPlus Figure 1 C Library Concept 2.4 Communication Channels The SPiiPlus C Library supports all communication channels provided by SPiiPlus motion controllers: • Serial (RS-232) • Ethernet (point-to-point and Network) • PCI Bus 2.5 Controller Simulation The SPiiPlus C Library includes the controller simulator operating on the same PC as the user application. The simulator provides execution of the user application without the physical controller for debugging and demonstration purposes. 31 January 2009 6 SPiiPlus C Library Overview
- 21. C Library Reference Version 6.50 Programmer’s Guide 2.6 Programming Languages The library directly supports development of C/C++ applications. Visual Basic®, C# or other languages can also be used with a little additional effort. For languages other than C/C++, the SPiiPlus COM library is recommended. 2.7 Supplied Components The library includes a DLL, a device driver, an import library, and a header file for C/C++ compilers. 2.8 Highlights • Unified support of all communication channels (Serial, Ethernet, PCI Bus) All functions except acsc_OpenComm*** functions are identical for all communication channels. The user application remains substantially the same and works through any of the available communication channels. • Controller simulator as an additional communication channels All library functions can work with the Simulator exactly as with the actual controller. The user application activates the simulator by opening a special communication channel. The user is not required to change his application in order to communicate with the Simulator. • Support of multi-threaded user application The user application can consist of several threads. Each thread can call SPiiPlus C Library functions simultaneously. The library also provides special functions for the synchronization SPiiPlus C functions called from concurrent threads. • Automatic synchronization and mutual exclusion of concurrent threads Both waiting and non-waiting calls of SPiiPlus C functions can be used from different threads without any blocking or affect one to another. The library provides automatic synchronization and mutual exclusion of concurrent threads so the threads are not delayed one by another. Each thread operates with its maximum available rate. • Concurrent support of up to 10 communication channels in one application One application can open up to 10 communication channels simultaneously. Different communication channels are usually connected to different controllers. However, two or more communication channels can be connected to one controller. For example, one application can communicate with one controller through both Ethernet and serial links. • Acknowledgement for each controller command The library automatically checks the status of each command sent by the user application to the controller. The user application can check the status to confirm that the command was received successfully. This applies for both waiting and non-waiting calls. 31 January 2009 7 SPiiPlus C Library Overview
- 22. C Library Reference Version 6.50 Programmer’s Guide • Communication history The library supports the storage of all messages sent to and received from the controller in a memory buffer. The application can retrieve the full or partial contents of the buffer and can clear the history buffer. • Separate processing of unsolicited messages Most messages sent from the controller to the host are responses to the host commands. However, the controller can send unsolicited messages, for example, because of executing the disp command. The library separates the unsolicited messages from the overall message flow and provides special function for handling unsolicited messages. • Rich set of functions for setting and reading parameters, motion, program management, I/O ports, safety controls, and other. • Two calling modes Most library functions can be called in either waiting or non-waiting mode. In waiting mode, the calling thread does not continue until the controller acknowledges the command execution. In non-waiting mode, a function returns immediately and the actual work of sending the command and receiving acknowledgement is performed by the internal thread of the library. • Debug Tools The library provides different tools that facilitate debugging of the user application. The simulator and the communication history mentioned above are the primary debugging tools. The user can also open a log file that stores all communications between the application and the controller. • Setting user callback functions for predefined events The possibility exists to set a callback function that will be called when a specified event occurs in the controller. This lets you define a constant reaction by the user host application to events inside the controller without polling the controller status (see Section 2.10 Callbacks). • Wait-for-Condition Functions To facilitate user programming, the library includes functions that delay the calling thread until a specific condition is satisfied. Some of the functions periodically pole the relevant controller status until the condition is true, or the time out expired. Some of these functions are based on the callback mechanism, see Section 2.10 Callbacks. The functions with this option are: • acsc_WaitMotionEnd • acsc_WaitLogicalMotionEnd • acsc_WaitProgramEnd • acsc_WaitInput These functions will use the callback mechanism if the callback to the relevant event is set, otherwise polling is used. 31 January 2009 8 SPiiPlus C Library Overview
- 23. C Library Reference Version 6.50 Programmer’s Guide • Support for Windows 2000/XP (32-bit and 64-bit)/Vista (32-bit and 64-bit) The user application that communicates through the library takes no notice of the operational environment. The library itself chooses the proper device driver and conceals all differences between the operating systems from the user application. 2.9 Use of Functions Each library function performs a specific controller operation. To perform its task, the function sends one or more commands to the controller and validates the controller responses. Because the SPiiPlus C functions follow the C syntax and have self-explaining names, the application developer is not required to be an expert in ACSPL+ language. However, the most time-critical part of an application often needs to be executed in the controller and not in the host. This part still requires ACSPL+ programming. To use the SPiiPlus C Library functions from C/C++ environment, it is necessary to include the header file ACSC.h and the import library file ACSC_x86.lib or ACSC_x64.lib, whichever is appropriate, to the project. An example of a function is the following that implements a motion to the specified point: int acsc_ToPoint(HANDLE Handle, int Flags, int Axis, double Point, ACSC_WAITBLOCK* Wait) Where: • Handle is a communication handle returned by one of the acsc_OpenComm*** functions. • Flags are a bit-mapped parameter that can include one or more motion flags. For example: ACSC_AMF_WAIT Plan the motion, but don’t start until the acsc_Go function is called ACSC_AMF_RELATIVE The Point value is relative to the end-point of the previous motion. If the flag is not specified, the Point specifies an absolute coordinate. • Axis is an axis of the motion where ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y, and so on. • Point is a coordinate of the target point. • Wait is used for non-waiting calls. Non-waiting calls are discussed in the next section. 31 January 2009 9 SPiiPlus C Library Overview
- 24. C Library Reference Version 6.50 Programmer’s Guide 2.10 Callbacks There is an option to define an automatic response in the user application to several events inside the controller. The user specifies a function that will be called when certain event occurs. This approach helps user application to avoid polling of the controller status and only to execute the defined reaction when it is needed. The library may set several callbacks in the same time. Every one of them runs in its own thread and doesn’t delay the others. Callbacks are supported in all communication channels. The library hides the difference from the application, so that the application handles the callbacks in all channels in the same way. The events that may have a callback functions are: • Hardware detected events • PEG • MARK1 and MARK2 • Emergency Stop • Software detected events • Physical motion end • Logical motion end • Motion failure • Motor failure • ACSPL+ program end • ACSPL+ line execution • ACSPL + “interrupt” command execution • Digital input goes high • Motion start • Motion profile phase change • Trigger function detects true trigger condition • Controller sent complete message on a communication channel 2.11 Timing When working with PCI bus, the callbacks are initiated through physical interrupts generated by the controller. In the Simulator, the interrupt mechanism is emulated with OS mechanisms. In all other kinds of communication, the controller sends an alert message over the communication channel in order to inform the host about the event. Although the implementation is transparent, the timing is different varies for each communication channel as follows: • In PCI communication, the callbacks are based upon PCI interrupts and response is very fast (sub-millisecond level). 31 January 2009 10 SPiiPlus C Library Overview
- 25. C Library Reference Version 6.50 Programmer’s Guide • In all other channels, callback operation includes sending/receiving a message that requires much more time. Specific figures depend on the communication channel rate. From the viewpoint of the Callback Mechanism, all communication channels are functionally equivalent, but differ in timing. 2.12 Hardware Interrupts Hardware events (Emergency Stop, PEG and MARK) are detected by the controllers HW and an interrupt on PCI bus is generated automatically, while on other communication channels those events are recognized by the Firmware and only then an alert message may be sent. That is why there is a difference in the definition of the Event condition for different communication channels. Table 4 Hardware Interrupt Generation Callback Condition of PCI Condition of Alert Message (all Interrupt channels except PCI) Emergency stop The interrupt is The message is sent when the S_FAULT.#ES generated on positive or bit changes from zero to one. negative edge of the The message is disabled if S_FMASK.#ES is input ES signal.The edge zero. is selected by S_SAFINI.#ES bit. Mark 1 and Mark The interrupt is The message is sent when the corresponding 2 generated on positive IST.#MARK or IST.#MARK2 bit changes edge of the from zero to one. corresponding Mark signal. PEG The interrupt is The message is sent when corresponding generated on negative AST.#PEG bit changes from one to zero. edge of PEG pulse. 2.13 Dual-Port RAM (DPRAM) The DPRAM is a memory block that is accessible from the host and from the controller. This feature provides fast data exchange between the host and the controller. The SPiiPlus controller provides 1024 bytes of dual-port ram memory (DPRAM). Relative address range of DPRAM is from byte 0 to byte 0x3FF. The first 128 bytes (relative addresses from 0 to 0x080) are reserved for system use. The rest of the memory is free for the user needs. The DPRAM functions are available with any communication channel, however it is important to remember that only PCI bus communication provide real physical access to controllers DPRAM and works very fast (sub-millisecond level). 31 January 2009 11 SPiiPlus C Library Overview
- 26. C Library Reference Version 6.50 Programmer’s Guide In all other channels, the DPRAM operation is simulated. Each operation includes communication with the controller. Specific figures depend on the communication channel rate. Using DPRAM communication in a non-PCI communication channel is recommended if an application is primarily intended for PCI channel, but requires full compatibility with other communication channels. 2.14 Non-Waiting Calls There are three possible approaches regarding when a library function returns control to the calling thread: • Waiting call The function waits for the controller response and then returns. For many commands, the controller response does not signal the completion of the operation. The controller response only acknowledges that the controller accepted the command and started the process of its execution. For example, the controller responds to a motion command when it has planned the motion, but has not executed yet. • Non-waiting call The library function initiates transmission of the command to the controller and returns immediately without waiting for the controller response. An internal library thread sends the command to the controller and retrieves the result. To get the result of operation the application calls the acsc_WaitForAsyncCall function. • Non-waiting call with neglect of operation results The same as the previous call, only the library does not retrieve the controller response. This mode can be useful when the application ignores the controller responses. Most library functions can be called in either waiting or non-waiting mode. The pointer Wait to the ACSC_WAITBLOCK structure provides the selection between waiting and non- waiting modes as follows: • Zero Wait (NULL character) defines a waiting call. The function does not return until the controller response is received. Note Do not use ‘0’ as the Null character. • If Wait is a valid pointer, the call is non-waiting and the function returns immediately. • If Wait is ACSC_IGNORE, the call is non-waiting and will neglect of the operation result. ACSC_WAITBLOCK is defined as follows: Structure: ACSC_WAITBLOCK { HANDLE Event; int Ret; }; 31 January 2009 12 SPiiPlus C Library Overview
- 27. C Library Reference Version 6.50 Programmer’s Guide When a thread activates a non-waiting call, the library passes the request to an internal thread that sends the command to the controller and then monitors the controller responses. When the controller responds to the command, the internal thread stores the response in the internal buffers. The calling thread can retrieve the controller response with help of the acsc_WaitForAsyncCall function and validate the completion result in the Ret member of the structure. Up to 256 non-waiting calls can be activated before any acsc_WaitForAsyncCall is called. It is important to understand that acsc_WaitForAsyncCall must be called for every non-waiting call. Otherwise, the response will be stored forever in the library’s internal buffers. A call, which is called when more then 256 calls are already activated is delayed for a certain time and waits until acsc_WaitForAsyncCall is called by one of the previous calls. If the time expires, an ACSC_COMMANDSQUEUEFULL error is returned. By default, this time-out is zero. This means that the call number 257 immediately returns with the ACSC_COMMANDSQUEUEFULL error . Note If you work with multiple non-waiting calls and the ACSC_COMMANDSQUEUEFULL error pops up all the time, the structure of your application is too demanding. This means that you are trying to activate more than 256 calls without retrieving the results. If the error message pops up occasionally, try increasing the timeout. Time-out is controlled by acsc_GetQueueOverflowTimeout and acsc_SetQueueOverflowTimeout functions. The following example shows how to perform waiting and non-waiting calls. In this example the acsc_WaitForAsyncCall function was used. Any function that has Wait as a parameter can be used to perform waiting and non-waiting calls. #include “ACSC.h” Char* cmd = “?$r”; // get motors state char buf[101]; int Received; ACSC_WAITBLOCK wait; // example of the waiting call of acsc_Transaction if (!acsc_Transaction( Handle, // communication handle cmd, // pointer to the buffer that // contains command to be executed strlen(cmd), // size of this buffer 31 January 2009 13 SPiiPlus C Library Overview
- 28. C Library Reference Version 6.50 Programmer’s Guide buf, // input buffer that receives // controller response 100, // size of this buffer &Received, // number of characters that were //actually received NULL // waiting call { printf(“transaction error: %dn”, acsc_GetLastError()); } // example of non-wainig call of acsc_Transaction if (acsc_Transaction(Handle,cmd,strlen(cmd),buf,100,&Received,&wait)) { // something doing here …. // retrieve controller response if (acsc_WaitForAsyncCall(Handle, buf, &Received, &wait, 5000)) { buf[Received] = ‘0’; printf(“Motors state: %sn”, buf); } else { acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received); buf[Received] = ‘0’; printf(“error: %sn”, buf); } } 31 January 2009 14 SPiiPlus C Library Overview
- 29. C Library Reference Version 6.50 Programmer’s Guide else { printf(“transaction error: %dn”, acsc_GetLastError()); } // Example of non-waiting call of acsc_Transaction with neglect of the // operation result. Function does not wait for the controller response. // The call of acsc_WaitForAsyncCall has no sense because it does not // return the controller response for this calling mode. If (acsc_Transaction( Handle,cmd,strlen(cmd),buf, 100, &Received, ACSC_IGNORE)) { printf(“transaction error: %dn”, acsc_GetLastError()); } 31 January 2009 15 SPiiPlus C Library Overview
- 30. C Library Reference Version 6.50 Programmer’s Guide 3 Using the SPiiPlus C Library 3.1 Library Structure The C Library is built from several levels, from Kernel-mode drivers on one end, to high level C function APIs on the other, and include: • ACSPCI32.SYS (for 32-bit), ACSPCI64.SYS (for 64-bit), WINDRVR6.SYS – Kernel- mode drivers for low-level communication support. These drivers are automatically installed and registered when the user installs the SPiiPlus software package. These drivers are required for communication with the controller through the PCI bus. • ACSCSRV.EXE – User-mode driver for high-level communication support. When this driver is active, there is an icon in the notification area at the bottom-right corner of the screen. This driver is necessary for all communication channels. The driver is automatically installed and registered when the user installs the SPiiPlus software package. • ACSCL_X86.DLL – Dynamic Link Library that contains the API functions. The DLL is installed in the SYSTEM32 directory, so it is accessible to all host applications. It is designed to operate in a 32-bit environment. • ACSCL_X64.DLL – Dynamic Link Library that contains the API functions. The DLL is installed in the SYSTEM32 directory, so it is accessible to all host applications. It is designed to operate in a 64-bit environment. • ACSCL_X86.LIB – Static LIB file required for a C/C++ project to access the DLL functions. It is designed to operate in a 32-bit environment. • ACSCL_X64.LIB – Static LIB file required for a C/C++ project to access the DLL functions. It is designed to operate in a 64-bit environment. Note A 32-bit software development should link against ACSCL_X86.LIB. A 64-bit software development should link against ACSCL_X64.LIB. • ACSC.H – C header file with API functions and Constant declarations. 3.2 Building C/C++ Applications To facilitate using the C Library in user applications, the installation includes the ACSC.H, and ACSC_x86.LIB or ACSC_x64.LIB files. The files are not required for running the C Library, and are only used for building user applications. In order to use the C Library functions in your application, proceed as follows: 1. Copy files from Program FilesACS Motion ControlSPiiPlus …ACSC to the project directory. Include file ACSCL_X86.LIB, or ACSCL_X86.LIB (as appropriate), in your C/C++ project. 31 January 2009 16 Using the SPiiPlus C Library
- 31. C Library Reference Version 6.50 Programmer’s Guide 2. Include file ACSC.H in each project file where the functions must be called. Use the statement #include “ACSC.H” (see the example program in Section 2.14). 3. Once the application that includes ACSCL_X86.LIB (or ACSCL_X64.LIB) file is activated, it locates file ACSCL_X86.DLL (or ACSCL_X64.DLL), so the appropriate .DLL file must be accessible to the application. The library installation puts the file in the SYSTEM32 directory, where it can be found by any application. 3.3 Redistribution of User Application A user application that calls C Library functions can be immediately executed on a computer where the SPiiPlus software package was previously installed. Note If the application is executed on a computer without the SPiiPlus software package installation, the user must install several library and support files. This process is called “redistribution”. 3.3.1 Redistributed Files The files for redistribution are found in “Program FilesACS Motion ControlSPiiPlus …Redist,” and include: • ACSCL_X86.DLL – C Library API for 32-bit environment • ACSCL_X64.DLL – C Library API for 64-bit environment • MFC80.DLL, MSVCR80.DLL, Microsoft.VC80.CRT.manifest, Microsoft.VC80.MFC.manifest – Microsoft® C Runtime Libraries • WINDRVR6.SYS – Jungo© WinDriver Kernel Mode Device Driver • WDAPI1000.DLL – Jungo© WinDriver Library used by ACSCSRV.EXE • ACSPCI32.SYS – Kernel-mode PCI Device Driver (for 32-bit environment) • ACSPCI64.SYS – Kernel-mode PCI Device Driver (for 64-bit environment) • ACS.ESTOP.EXE – ACS Motion Control© SPiiPlus Emergency Stop • ACSCSRV.EXE – SPiiPlus user-mode driver • ACS.AUTOINSTALLER.EXE – ACS Motion Control© SPiiPlus PCI Driver AutoInstaller 31 January 2009 17 Using the SPiiPlus C Library
- 32. C Library Reference Version 6.50 Programmer’s Guide 3.3.2 File Destinations The files should be copied to various places, depends on the Operating System. These files are common to all Microsoft Windows versions. Place these files in the relevant Windows system directory: • ACSCL_X86.DLL, or • ACSCL_X64.DLL The following files differ with each Windows version: Place the following files in the SYSTEM32DRIVERS: • ACSPCI32.SYS, or • ACSPCI64.SYS In order to provide WinDriver information for Windows "Plug and Play," redistribute INF files as follows: • ACSPCI.INF • WINDRVR6.INF Note The INF files are required only for registration process; they should be placed in well-known destinations. Copy ACSCSRV.EXE, ACS.EStop.exe, WDAPI1000.DLL, MFC80.DLL, MSVCR80.DLL, Microsoft.VC80.CRT.manifest, and Microsoft.VC80.MFC.manifest to target machine. The exact place is not important; however, it is convenient to put it in the application directory. The main thing is to configure Windows to launch ACSCSRV.EXE on start-up. The preferred way to do so is to make an addition to the registry key as follows: HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionRun a new string value named “ACSCSRV” The string should contain the full path to the location of ACSCSRV.EXE. On start-up Windows will start the user-mode driver on the current machine for each user that logs in. 3.3.3 Kernel Mode Driver Registration The easiest way to perform Kernel Mode driver installation and removal is to use the WDREG utility. • 32-bit Systems If you want to install or remove drivers on a 32-bit system, use files from the "x86" folder. First, you have to remove old drivers from the registry. Execute the following commands on the target machine and reboot it: 31 January 2009 18 Using the SPiiPlus C Library
- 33. C Library Reference Version 6.50 Programmer’s Guide Windows 2000XP (32-bit): • wdreg.exe -name "Spii" -file Spii stop • wdreg.exe -name "Spii" -file Spii DELETE • wdreg.exe -name WinDriver stop • wdreg.exe -name WinDriver DELETE Delete these files from the following directories on the target machine: Windows 2000: WINDRVR.SYS, SPII.SYS from C:WINNTSYSTEM32DRIVERS. Windows XP x86 (32-bit): WINDRVR.SYS, SPII.SYS from C:WINDOWSSYSTEM32DRIVERS. Place these files in the following directories on the target machine: • Windows 2000: ACSPCI32.SYS to C:WINNTSYSTEM32DRIVERS. • Windows XP or Vista: ACSPCI32.SYS to C:WINDOWSSYSTEM32DRIVERS. Put wdreg.exe, difxapi.dll, windrvr6.inf, windrvr6.sys, wd1000.cat, acspci.inf, ACSPCI32.sys, acsx86.cat in a folder on the target machine. To install drivers to the registry execute the following commands: • wdreg.exe -inf acspci.inf disable • wdreg.exe -inf windrvr6.inf disable • wdreg.exe -inf windrvr6.inf install • wdreg.exe -name ACSPCI32 install • wdreg.exe -inf acspci.inf install • wdreg.exe -inf windrvr6.inf enable • wdreg.exe -inf acspci.inf enable To remove drivers from the registry execute the following commands: • wdreg.exe -inf acspci.inf disable • wdreg.exe -inf windrvr6.inf disable • wdreg.exe -name ACSPCI32 uninstall • wdreg.exe -inf acspci.inf uninstall • wdreg.exe -inf windrvr6.inf uninstall • 64-bit Systems If you want to install or remove drivers on a 64-bit system, use files from "x64" folder. Place these files to the following directories on the target machine: • Windows XP or Vista: ACSPCI64.SYS to C:WINDOWSSYSTEM32DRIVERS. 31 January 2009 19 Using the SPiiPlus C Library
- 34. C Library Reference Version 6.50 Programmer’s Guide Put wdreg.exe, difxapi.dll, windrvr6.inf, windrvr6.sys, wd1000.cat, acspci.inf, ACSPCI64.sys, acsamd64.cat in a folder on the target machine. To install drivers to the registry execute the following commands: • wdreg.exe -inf acspci.inf disable • wdreg.exe -inf windrvr6.inf disable • wdreg.exe -inf windrvr6.inf install • wdreg.exe -name ACSPCI64 install • wdreg.exe -inf acspci.inf install • wdreg.exe -inf windrvr6.inf enable • wdreg.exe -inf acspci.inf enable To remove drivers from the registry execute the following commands on the target machine: • wdreg.exe -inf acspci.inf disable • wdreg.exe -inf windrvr6.inf disable • wdreg.exe -name ACSPCI64 uninstall • wdreg.exe -inf acspci.inf uninstall • wdreg.exe -inf windrvr6.inf uninstall 31 January 2009 20 Using the SPiiPlus C Library
- 35. C Library Reference Version 6.50 Programmer’s Guide 4 C Library Functions This chapter describes each of the functions available in the SPiiPlus C Library. The functions are arranged in functional groups. For each function there is a: • Description - A short description of the use of the function • Syntax - The calling syntax • Arguments - List and definition of function arguments • Return value - A description of the value, if any, that the fuction returns • Comments - Where relevant, additional information on the function • Example - Short code example in C language The functions are grouped in the following categories: • Communication Functions • Service Communication Functions • ACSPL+ Program Management Functions • Read and Write Variables Functions • Load/Upload Data To/From Controller Functions • Multiple Thread Synchronization Functions • History Buffer Management Functions • Unsolicited Messages Buffer Management Functions • Log File Management Functions • System Configuration Functions • Setting and Reading Motion Parameters Functions • Axis/Motor Management Functions • Motion Management Functions • Point-to-Point Motion Functions • Track Motion Control Functions • Jog Functions • Slaved Motion Functions • Multi-Point Motion Functions • Arbitrary Path Motion Functions • PVT Functions • Segmented Motion Functions • Points and Segments Manipulation Functions • Data Collection Functions • Status Report Functions • Input/Output Access Functions • Safety Control Functions • Wait-for-Condition Functions 31 January 2009 21 C Library Functions
- 36. C Library Reference Version 6.50 Programmer’s Guide • Callback Registration Functions • Variables Management Functions • Service Functions • Error Diagnosis Functions • Dual Port RAM (DPRAM) Access Functions • Position Event Generation (PEG) Functions • Emergency Stop Functions • Application Save/Load Functions • Reboot Functions 4.1 Communication Functions The C Library Communication Functions are: Table 5 Communication Functions (page 1 of 2) Function Description acsc_OpenCommSerial Opens communication via serial port. acsc_OpenCommEthernetTCP Opens communication with the controller via Ethernet using TCP protocol. acsc_OpenCommEthernetUDP Opens communication with the controller via Ethernet using the UDP protocol. acsc_OpenCommDirect Starts up the Simulator and opens communication with it. acsc_OpenCommPCI Opens communication with the SPiiPlus PCI via PCI Bus. acsc_GetPCICards Retrieves information about the installed SPiiPlus PCI card’s. acsc_SetServer The function defines user-mode driver host IP address acsc_CloseComm Closes communication (for all kinds of communication). acsc_Send Sends a message. acsc_Receive Receives a message. acsc_Transaction Executes one transaction with the controller, i.e., sends the request and receives the controller response. acsc_Command Sends a command to the controller and analyzes the controller response. acsc_WaitForAsyncCall Waits for completion of asynchronous call and retrieves a data. acsc_CancelOperation Cancels any asynchronous (non-waiting) call or all operations with the specified communication handle. 31 January 2009 22 C Library Functions
- 37. C Library Reference Version 6.50 Programmer’s Guide Table 5 Communication Functions (page 2 of 2) Function Description acsc_GetEthernetCards Detects available controllers through a standard Etherneet connection. acsc_SetServerExt Behaves as acsc_SetServer but explicitly specifies the IP port number for a remote connection. acsc_SetServerExtLogin Same as acsc_SetServerExt but provides additional data. acsc_GetConnectionsList Retrieves all currently opened connections on the active server and their details. acsc_TerminateConnection Terminates a given communication channel (connection) of the active server. 4.1.1 acsc_OpenCommSerial Description The function opens communication with the controller via a serial port. Syntax HANDLE acsc_OpenCommSerial(int Channel, int Rate) Arguments Channel Communication channel: 1 corresponds to COM1, 2 – to COM2, etc. Rate Communication rate in bits per second (baud). This parameter must be equal to the controller variable IOBAUD for the successful link with the controller. If ACSC_AUTO constant is passed, the function will automatically determine the baud rate. Return Value If the function succeeds, the return value is a valid communication handle. The handle must be used in all subsequent function calls that refer to the open communication channel. If the function fails, the return value is ACSC_INVALID (-1). Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 23 C Library Functions
- 38. C Library Reference Version 6.50 Programmer’s Guide Comments After a channel is open, any SPiiPlus C function works with the channel irrespective of the physical nature of the channel. Example HANDLE Handle = OpenCommSerial(1, // Communication port COM1 115200 // Baud rate 115200 ); if (Handle == ACSC_INVALID) { printf("error opening communication: %dn", acsc_GetLastError()); } 4.1.2 acsc_OpenCommEthernetTCP Description The function opens communication with the controller via Ethernet using TCP protocol. Syntax int acsc_OpenCommEthernetTCP(char* Address, int Port); Arguments Address Pointer to a null-terminated character string that contains the network address of the controller in symbolic or TCP/IP dotted form. Port Service port. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments None. 31 January 2009 24 C Library Functions
- 39. C Library Reference Version 6.50 Programmer’s Guide Example HANDLE hComm=(HANDLE)-1; int Port = 703; hComm = acsc_OpenCommEthernetTCP("10.0.0.1",Port); if (hComm == ACSC_INVALID) { printf("Error while opening communication: %dn", acsc_GetLastError()); return -1; } 4.1.3 acsc_OpenCommEthernetUDP Description The function opens communication with the controller via Ethernet using the UDP protocol. Syntax int acsc_OpenCommEthernetUPD(char* Address, int Port); Arguments Address Pointer to a null-terminated character string that contains the network address of the controller in symbolic or TCP/IP dotted form. Port Service port. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments None. 31 January 2009 25 C Library Functions
- 40. C Library Reference Version 6.50 Programmer’s Guide Example HANDLE hComm=(HANDLE)-1; int Port = 704; hComm = acsc_OpenCommEthernetUDP("10.0.0.1",Port); if (hComm == ACSC_INVALID) { printf("Error while opening communication: %dn", acsc_GetLastError()); return -1; } 4.1.4 acsc_OpenCommDirect Description The function starts up the Simulator and opens communication with the Simulator. Syntax HANDLE acsc_OpenCommDirect() Return Value If the function succeeds, the return value is a valid communication handle. The handle must be used in all subsequent function calls that refer to the open communication channel. If the function fails, the return value is ACSC_INVALID (-1). Note Extended error information can be obtained by calling acsc_GetLastError. Comments The Simulator is a part of the SPiiPlus C Library. When the application calls acsc_OpenCommDirect, the library starts up the Simulator as a separate process on the same PC and opens a simulator communication channel for communication with the simulator. After a channel is open, any SPiiPlus C function works with the Simulator exactly as with a physical controller. Note For the simulator to be to be found by acsc_OpenCommDirect, a copy of the simulator executable file, sb4.exe (located in the SPiiPlus BIN folder), must be in the same folder as the application executable file. 31 January 2009 26 C Library Functions
- 41. C Library Reference Version 6.50 Programmer’s Guide Example HANDLE Handle = acsc_OpenCommDirect(); if (Handle == ACSC_INVALID) { printf("error opening communication: %dn", acsc_GetLastError()); } 4.1.5 acsc_OpenCommPCI Description The function opens a communication channel with the controller via PCI Bus. Up to 4-communication channels can be open simultaneously with the same SPiiPlus card through the PCI Bus. Syntax HANDLE acsc_OpenCommPCI(int SlotNumber) Arguments SlotNumber Number of the slot of the controller card. If SlotNumber is ACSC_NONE, the function opens communication with the first found controller card. Return Value If the function succeeds, the return value is a valid communication handle. The handle must be used in all subsequent function calls that refer to the open communication channel. If the function fails, the return value is ACSC_INVALID (-1). Note Extended error information can be obtained by calling acsc_GetLastError. Comments To open PCI communication the host PC, one or more controller cards must be inserted into the computer PCI Bus. After a channel is open, any SPiiPlus C function works with the channel irrespective of the physical nature of the channel. 31 January 2009 27 C Library Functions
- 42. C Library Reference Version 6.50 Programmer’s Guide Example // open communication with the first found controller card HANDLE Handle = acsc_OpenCommPCI(ACSC_NONE); if (Handle == ACSC_INVALID) { printf("error opening communication: %dn", acsc_GetLastError()); } 4.1.6 acsc_GetPCICards Description The function retrieves information about the controller cards inserted in the computer PCI Bus. Syntax int acsc_GetPCICards(ACSC_PCI_SLOT* Cards, int Count, int* ObtainedCards) Arguments Cards Pointer to the array of the ACSC_PCI_SLOT elements. Count Number of elements in the array pointed to by Cards. ObtainedCards Number of cards that were actually detected. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function scans the PCI Bus for the inserted controller cards and fills the Cards array with information about the detected cards. Structure ACSC_PCI_SLOT is defined as follows: Structure: ACSC_PCI_SLOT {int BusNumber; int SlotNumber; int Function;}; Where: • BusNumber = bus number • SlotNumber = slot number of the controller card 31 January 2009 28 C Library Functions
- 43. C Library Reference Version 6.50 Programmer’s Guide • Function = PCI function of the controller card Within these members, the SlotNumber can be used in the acsc_OpenCommPCI call to open communication with a specific card. Other members have no use in the SPiiPlus C Library. If no controller cards are detected, the function assigns the ObtainedCards with zero and does not fill the Cards array. If one or more controller cards are detected, the function assigns the ObtainedCards with a number of detected cards and places one ACSC_PCI_SLOT structure per each detected card into the Cards array. If the size of Cards array specified by the Count parameter is less than the number of detected cards, the function assigns the ObtainedCards with a number of actually detected cards, but fills only the Count elements of the Cards array. Example ACSC_PCI_SLOT CardsList[16]; int DetectedCardsCount; if (acsc_GetPCICards( CardsList, // pointer to the declared // array // to save the detected // cards information 16, // size of this array &DetectedCardsCount // number of cards that were // actually detected )) { printf("Found %d SB1218PCI cardsn", DetectedCardsCount); } else { printf("error while scanning PCI bus: %dn", acsc_GetLastError()); } 4.1.7 acsc_SetServer Description The function defines user-mode driver host IP address. Syntax int acsc_SetServer(char *IP) Arguments IP IP address of the machine that hosts the desired active user-mode driver. It may be entered as an IP address (10.0.0.102) or as local machine name (ACS110) Return Value If the function succeeds, the return value is non-zero. 31 January 2009 29 C Library Functions
- 44. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the IP address of the User-Mode Driver (UMD) host. Once the function is called all acsc_OpenCommxxx calls will attempt to establish communication via the user-mode driver that was specified in recent acsc_SetServer call. In order to establish communication via different user-mode driver host acsc_SetServer should be called again. Use the function only if the application needs to establish communication with a controller through the remote computer. If the function is not called, by default all connections are established through the local computer. Only a controller connected to the local computer by a serial cable, PCI bus or Ethernet can be accessed. Once the function is called, it defines the remote computer to be used as a communication server. Any subsequent acsc_OpenCommxxx call will attempt to establish communication with a controller connected to that remote computer. Application can simultaneously communicate through several communication servers. Use the following pattern to open communication channels through several servers: Handle01= acsc_OpenComxxx(…); // Open all channels with controllers // connected to the local computer Handle02= ascs_OpenComxxx(…) SetServer(Server1); // Set Server1 Handle11=acsc_OpenComxxx(…); // Open all channels with controllers // connected to Server1 Handle12= acsc_OpenComxxx(…) SetServer(Server2); // Set Server2 Handle21= acsc_OpenComxxx(…); // Open all channels with controllers // connected to Server2 Handle22= acsc_OpenComxxx(…) Note When the application calls SetServer(Server2), all handles related to the local computer or to Server1 remain valid. Then the application can use all handles to provide simultaneous communication with many controllers through different servers. 31 January 2009 30 C Library Functions
- 45. C Library Reference Version 6.50 Programmer’s Guide Example acsc_SetServer(“10.0.0.134”);// defines remote server if(!acsc_OpenCommPCI(-1)) // attempts to open communication with PCI card // via remote server at 10.0.0.134 { printf("transaction error: %dn", acsc_GetLastError()); } 4.1.8 acsc_SetServerExt Description The function behaves as acsc_SetServer but explicitly specifies the IP port number for a remote connection, where acsc_SetServer uses only the default port. Syntax int acsc_SetServerExt(char*IP,intPort) Arguments IP IP address where to look for server. Port Port number for connection Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments This function is used for access over varying IP ports. 31 January 2009 31 C Library Functions
- 46. C Library Reference Version 6.50 Programmer’s Guide Example acsc_SetServerExt(“10.0.0.134”,7777); Handle=acsc_OpenCommPCI(-1) //Will attempt to find active UMD running on //host “10.0.0.13” and listening on Port 7777 //and open communication with PCI card on that //host 4.1.9 acsc_SetServerExtLogin Description The function behaves as acsc_SetServerExt and, in addition, passes login data. Syntax int acsc_SetServerExtLogin(char *IP, int Port, char *Username, char *Password, char *Domain) Arguments IP IP address where to look for server Port Port number to connect over Username Null terminated valid username Password Null terminated valid password Domain Null terminated domain or workgroup Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 32 C Library Functions
- 47. C Library Reference Version 6.50 Programmer’s Guide Example acsc_SetServerExtLogin("10.0.0.13",7777,"Mickey","viva11","ACS-Tech80") Handle=acsc_OpenCommPCI(-1)//Will attempt to find active UMD running on host //"10.0.0.13" and listenning on Port 7777 //on the host attempting to login as "Mickey" //and open communication with PCI card at that host 4.1.10 acsc_CloseComm Description The function closes communication via the specified communication channel. Syntax int acsc_CloseComm(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function closes the communication channel and releases all system resources related to the channel. If the function closes communication with the Simulator, the function also terminates the Simulator. Each acsc_OpenComm*** call in the application must have the corresponding acsc_CloseComm call in order to return the resources to the system. Example if (!acsc_CloseComm(Handle)) { printf("error closing communication: %dn", acsc_GetLastError()); } 31 January 2009 33 C Library Functions
- 48. C Library Reference Version 6.50 Programmer’s Guide 4.1.11 acsc_Send Description The function sends a message to the controller. Syntax int acsc_Send(HANDLE Handle, char* Buf, int Count, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Buf Buffer that contains the command to be sent Count Number of characters in the command Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sends a specified number of characters to the controller. The function does not receive a controller response. The function can be useful for applications like communication terminal to send any commands to the controller. All background communication can be received with help of the acsc_GetHistory function, which retrieves communication history. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 34 C Library Functions
- 49. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Send char* cmd = "enable Xr"; if (!acsc_Send(Handle, // communication handle cmd, // pointer to the buffer that contains // executed controller’s command strlen(cmd), // size of this buffer NULL // waiting call )) { printf("sending failed: %dn", acsc_GetLastError()); } 4.1.12 acsc_Receive Description The function receives a message from the controller. Syntax int acsc_Receive(HANDLE Handle, char* Buf, int Count, int* Received, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Buf Buffer that receives a controller response Count Size of the buffer Received Number of characters that were actually received Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function retrieves at least one character, the return value is non-zero. If no characters were received, the function returns zero. Comments The function retrieves currently stored data from an input internal library buffer. If the number of bytes in the input library buffer is longer than Count, the function retrieves and stores only Count characters in the buffer pointed by Buf. The Received parameter will contain the exact number of the characters stored in InBuf. The function returns immediately after storing data in the user buffer irrespective of value of 31 January 2009 35 C Library Functions
- 50. C Library Reference Version 6.50 Programmer’s Guide the Wait parameter. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Note This function is only used for compatibility with the previous version of zero- library. To communicate with the controller, use the acsc_Transaction or acsc_Command functions. Example // example of call of acsc_Receive char buf100]; int Received; if (!acsc_Receive(Handle, // communication handle buf, // input buffer that receives data 100, // size of this buffer &Received, // number of characters that were actually // received NULL // waiting call )) { printf("No characters were receivedn"); } 4.1.13 acsc_Transaction Description The function executes one transaction with the controller, i.e. it sends a command and receives a controller response. Syntax int acsc_Transaction (HANDLE Handle, char* OutBuf, int OutCount, char* InBuf, int InCount, int* Received, ACSC_WAITBLOCK* Wait) Note Any ASCII command being sent to the controller must end with the 'r' (13) character, otherwise it will not be recognized as valid. Arguments Handle Communication handle 31 January 2009 36 C Library Functions
- 51. C Library Reference Version 6.50 Programmer’s Guide OutBuf Output buffer that contains the command to be sent OutCount Number of characters in the command InBuf Input buffer that receives controller response InCount Size of the input buffer Received Number of characters that were actually received Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The full operation of transaction includes the following steps: 1. Send OutCount characters from OutBuf to the controller. 2. Waits until the controller response is received or the timeout occurs. In the case of timeout, set Received to zero, store error value and return. 3. Store the controller response in InBuf. If the controller response is longer than InCount, store only InCount characters. 4. Writes to Received the exact number of the characters stored in InBuf. 5. Analyzes the controller response, and set the error value if the response indicates an error. If the Wait argument is NULL, the call is waiting and the function does not return until the full operation is finished. If the Wait argument points to a valid ACSC_WAITBLOCK structure, the call is non-waiting and the function returns immediately after the first step. An internal library thread executes the 31 January 2009 37 C Library Functions
- 52. C Library Reference Version 6.50 Programmer’s Guide rest of the operation. The calling thread can validate if the operation finished and can retrieve the operation result using the acsc_WaitForAsyncCall function. Example char* cmd = "?SNr"; // get controller serial number char buf[100]; int Received, ret; ACSC_WAITBLOCK wait; // example of the waiting call of acsc_Transaction if (!acsc_Transaction( Handle, // communication handle cmd, // pointer to the buffer that contains executed // controller’s command strlen(cmd), // size of this buffer buf, // input buffer that receives controller response 100, // size of this buffer &Received, // number of characters that were actually received NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // example of non-wainig call of acsc_Transaction if (acsc_Transaction(Handle, cmd, strlen(cmd), buf, 100, &Received, &wait)) { // something doing here …. // waiting for the controller’s response 5 sec if (acsc_WaitForAsyncCall(Handle, buf, &Received, &wait, 5000)) { buf[Received] = ‘0’; printf(“Controller serial number: %sn”, buf); } 4.1.14 acsc_Command Description The function sends a command to the controller and analyzes the controller response. Syntax int acsc_Command (HANDLE Handle, char* OutBuf, int OutCount, ACSC_WAITBLOCK* Wait) 31 January 2009 38 C Library Functions
- 53. C Library Reference Version 6.50 Programmer’s Guide Note Any ASCII command being sent to the controller must end with 'r' (13) character, otherwise it will not be recognized as valid. Arguments Handle Communication handle OutBuf Output buffer that contains the request to be sent OutCount Number of characters in the request Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function acsc_WaitForAsyncCall returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function is similar to acsc_Transaction except that the controller response is not transferred to the calling thread. The function is used mainly for the commands that the controller responds to with a prompt. In this case, the exact characters that constitute the prompt are irrelevant for the calling thread. The function provides analysis of the prompt, and if the operation fails, the calling thread can obtain the error code. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 39 C Library Functions
- 54. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Command char* cmd = "enable Xr"; if (!acsc_Command( Handle, // communication handle cmd, // pointer to the buffer that contains // executed controller’s command strlen(cmd), // size of this buffer NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.1.15 acsc_WaitForAsyncCall Description The function waits for completion of asynchronous call and retrieves a data. Syntax int acsc_WaitForAsyncCall(HANDLE Handle, void* Buf, int* Received, ACSC_WAITBLOCK* Wait, int Timeout) Arguments Handle Communication handle. Buf Pointer to the buffer that receives controller response. This parameter must be the same pointer that was specified for asynchronous call of SPiiPlus C function. If the SPiiPlus C function does not accept a buffer as a parameter, Buf has to be NULL pointer. Received Number of characters that were actually received. Wait Pointer to the same ACSC_WAITBLOCK structure that was specified for asynchronous call of SPiiPlus C function. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. The Ret field of Wait contains the error code that the non-waiting call caused. If Wait.Ret is zero, the call succeeded: no errors occurred. 31 January 2009 40 C Library Functions
- 55. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function waits for completion of asynchronous call, corresponds to the Wait parameter, and retrieves controller response to the buffer pointed by Buf. The Wait and Buf must be the same pointers passed to SPiiPlus C function when asynchronous call was initiated. If the call of SPiiPlus C function was successful, the function retrieves controller response to the buffer Buf. The Received parameter will contain the number of actually received characters. If the call of SPiiPlus C function does not return a response (for example: acsc_Enable, acsc_Jog, etc.) Buf has to be NULL. If the call of SPiiPlus C function returned the error, the function retrieves this error code in the Ret member of the Wait parameter. If the SPiiPlus C function has not been completed in Timeout milliseconds, the function aborts specified asynchronous call and returns ACSC_TIMEOUT error. If the call of SPiiPlus C function has been aborted by the acsc_CancelOperation function, the function returns ACSC_OPERATIONABORTED error. Example char* cmd = "?VRr";// get firmware version char buf[101]; int Received; ACSC_WAITBLOCK wait; if (!acsc_Transaction(Handle, cmd, strlen(cmd), buf, 100, &Received, &wait)) { printf("transaction error: %dn", acsc_GetLastError()); } else { // call is pending if (acsc_WaitForAsyncCall(Handle, // communication handle 31 January 2009 41 C Library Functions
- 56. C Library Reference Version 6.50 Programmer’s Guide buf, // pointer to the same buffer, that was specified // for acsc_Transaction &Received, // received bytes &wait, // pointer to the same structure, that was // specified for acsc_Transaction 500 // 500 ms )) { buf[Received] = ‘0’; printf(“Firmware version: %sn”, buf); } else { acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received); buf[Received] = ‘0’; printf("error: %sn", buf); } } 4.1.16 acsc_CancelOperation Description The function cancels any asynchronous (non-waiting) call or all operations with the specified communication handle. Syntax int acsc_CancelOperation(HANDLE Handle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Wait Pointer to the ACSC_WAITBLOCK structure that was passed to the function that initiated the asynchronous (non-waiting) call. Return Value If the function succeeds, the return value is non-zero. The corresponding asynchronous call was successfully canceled. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 42 C Library Functions
- 57. C Library Reference Version 6.50 Programmer’s Guide Comments If Wait points to a valid ACSC_WAITBLOCK structure, the function cancels the corresponding call with the error ACSC_OPERATIONABORTED. If the corresponding call was not found the error ACSC_CANCELOPERATIONERROR will be returned by acsc_GetLastError function. If Wait is NULL, the function cancels all of the waiting and non-waiting calls for the specified communication handle. Example // cancels all of the waiting and non-waiting calls if (!acsc_CancelOperation(Handle, NULL)) { printf("Cancel operation error: %dn", acsc_GetLastError()); } 4.1.17 acsc_GetEthernetCards Description The function detects available controllers through a standard Etherneet connection. By default, the function searches the local network segment. The default setting can be changed, as described below. Syntax int acsc_GetEthernetCards(in_addr*IPaddresses,int Max, int*Ncontrollers,unsigned long BroadcastAddress) Arguments IPadresses Buffer for IP addresses of detected controllers Max Size of IPaddresses array NControllers The number of actually detected controllers BroadcastAddress IP address for broadcasting. Normally has to be ACSC_NONE Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 43 C Library Functions
- 58. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments Function Execution The function executes as follows: 1. Broadcasts a message to the network 2. Collects all received replies 3. Filters out all replies sent by nodes other than the SPiiPlus controller 4. The function then stores controller's IP addresses in the IPaddresses array, assigns Ncontrollers with the number of detected controllers and returns. If the size of the IPaddresses array appears too small for all detected controllers (Ncontrollers > Max), only Max addresses are stored in the array. In order to convert the in_addr structure to a dot-delineated string, use the inet_ntoa() Microsoft Windows function. Broadcasting Considerations If BroadcastAddress needs to be specified as other than ACSC_NONE, use the inet_addr Microsoft Windows function to convert the dot-delineated string to an integer parameter. The function uses the following broadcasting message: "ACS-TECH80r" The target port for broadcasting is 700. A node that doesn't support port 700 simply does not see the broadcasting message. If a node other than the controller supports port 700, the node receives the message. However, since the message format is meaningful only for SPiiPlus controllers, any other node that receives the message either ignores it or responds with an error message that is filtered out by the function. Normally, the user specifies ACSC_NONE in the BroadcastAddress parameter. In this case, the function uses broadcast address 255.255.255.255. The address causes broadcasting in a local segment of the network. If the host computer is connected to several local segments (multi-home node), the broadcasting message is sent to all connected segments. The user may wish to specify explicit broadcasting addresses in the following cases: • To reduce the broadcasting area. In a multi-home node, the specific address can restrict broadcasting to one of the connected segments. • To extend the broadcasting area. If a wide area network (WAN) is supported, a proper broadcasting address can broadcast to the entire WAN, or part of the WAN. For information about how to use broadcasting addresses, refer to the network documentation. 31 January 2009 44 C Library Functions
- 59. C Library Reference Version 6.50 Programmer’s Guide Note SPiiPlus controllers running with FW 4.50 or below will not be found with a mask other than ACSC_NONE. Example in_addr IPaddresses[100]; int Ncontrollers; char *DotStr; char Version[100]; int N; HANDLE h; int I; if (!acsc_GetEthernetCards(IPaddresses,100, &Ncontrollers,ACSC_NONE)) { printf("Error %dn", acsc_GetLastError()); } for(I=0;I<Ncontrollers;I++) { DotStr=inet_ntoa(IPaddresses[I]); h=acsc_OpenCommEthernet(DotStr,ACSC_SOCKET_STREAM_PORT); if(h!=ACSC_INVALID) { if(acsc_GetFirmwareVersion(h,Version, 100,&N,NULL)) { Version[N]=0; printf("%sn",Version); } acsc_CloseComm(h); } } 4.1.18 acsc_GetConnectionsList Description The function retrieves all currently opened connections on the active server and their details. Syntax int acsc_GetConnectionsList(ACSC_CONNECTION_DESC* ConnectionsList, int MaxNumConnections, int* NumConnections) 31 January 2009 45 C Library Functions
- 60. C Library Reference Version 6.50 Programmer’s Guide Arguments ConnectionsList Pointer to array of connections. Each connection is defined by the ACSC_CONNECTION_DESC structure. The user application is responsible for allocating memory for this array. MaxNumConnections Number of ConnectionsList array elements. NumConnections Actual number of retrieved connections. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments If the size of the ConnectionsList array appears too small for all detected connections (Connections > MaxNumConnections), only MaxNumConnections connections are stored in the array. This function can be used to check if there are some unused connections that remain from an application that did not close the communication channel or were not gracefully closed (terminated or killed). Each connection from returned list can be terminated only by the acsc_TerminateConnection function. Note Using any function of the acsc_SetServer family makes a previously returned connections list irrelevant because it changes the active server. 31 January 2009 46 C Library Functions
- 61. C Library Reference Version 6.50 Programmer’s Guide Example int NConnections; ACSC_CONNECTION_DESC Connections[100]; int I; char app_name[]="needed_app.exe"; if (!acsc_GetConnectionsList(Connections, 100, &NConnections)) { printf("Error %dn", acsc_GetLastError()); } for(I=0;I<NConnections;I++) { if ((strcmp(Connections[I].Application, app_name)==0) && (OpenProcess(0,0,Connections[I].ProcessId) == NULL)) // Check if process is //still running by OpenProcess() function, //only if it was executed on local PC. { if (!acsc_TerminateConnection(&(Connections[i]))) { printf("Error closing communication of %s application: %dn", Connections[I].Application, acsc_GetLastError()); } else { printf("Communication of %s application is successfully closed!n", Connections[I].Application); } } } 4.1.19 acsc_TerminateConnection Description The function terminates a given communication channel (connection) of the active server. Syntax int acsc_TerminateConnection(ACSC_CONNECTION_DESC* Connection) Arguments Connection Pointer to array of connections. Each connection is defined by the ACSC_CONNECTION_DESC structure. The acsc_GetConnectionsList function is responsible for initializing this structure. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 47 C Library Functions
- 62. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments This function can be used to terminate an unused connection that remains from an application that did not close the communication channel or was not gracefully closed (terminated or killed). The Connection parameter should be passed as it was retrieved by acsc_GetConnectionsList function. Note Using any function of the acsc_SetServer family makes a previously returned connections list irrelevant because it changes the active server. 31 January 2009 48 C Library Functions
- 63. C Library Reference Version 6.50 Programmer’s Guide Example int NConnections; ACSC_CONNECTION_DESC Connections[100]; int I; char app_name[]="needed_app.exe"; acsc_SetServerExt("10.0.0.13",7777); if (!acsc_GetConnectionsList(Connections, 100, &NConnections)) { printf("Error %dn", acsc_GetLastError()); } for(I=0;I<NConnections;I++) { if ((strcmp(Connections[I].Application, app_name)==0) && (OpenProcess(Connections[I].ProcessId) == NULL)) // Check if process is still //running by OpenProcess() function, only //if it was executed on local PC. { if (!acsc_TerminateConnection(&(Connections[i]))) { printf("Error closing communication of %s application: %dn", Connections[I].Application, acsc_GetLastError()); } else { printf("Communication of %s application is successfully closed!n", Connections[I].Application); } } } 4.2 Service Communication Functions The Service Communication functions are: Table 6 Service Communication Functions (page 1 of 2) Function Description acsc_GetCommOptions Retrieves the communication options. acsc_GetDefaultTimeout Retrieves default communication time-out. acsc_GetErrorString Retrieves the explanation of an error code. acsc_GetLastError Retrieves the last error code. acsc_GetLibraryVersion Retrieves the SPiiPlus C Library version number. acsc_GetTimeout Retrieves communication time-out. acsc_SetIterations Sets the number of iterations of one transaction. 31 January 2009 49 C Library Functions
- 64. C Library Reference Version 6.50 Programmer’s Guide Table 6 Service Communication Functions (page 2 of 2) Function Description acsc_SetCommOptions Sets the communication options. acsc_SetTimeout Sets communication time-out. acsc_SetQueueOverflowTimeout Sets the Queue Overflow Time-out. acsc_GetQueueOverflowTimeout Retrieves the Queue Overflow Time-out. 4.2.1 acsc_GetCommOptions Description The function retrieves the communication options. Syntax int acsc_GetCommOptions(HANDLE Handle, unsigned int* Options) Arguments Handle Communication handle Options Current communication options Bit-mapped parameter that can include the following flag: ACSC_COMM_USE_CHECKSUM. The communication mode when each command sends to the controller with checksum and the controller responds with checksum. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current communication options. To set the communication option call acsc_SetCommOptions. 31 January 2009 50 C Library Functions
- 65. C Library Reference Version 6.50 Programmer’s Guide Example // the example of using acsc_GetCommOptions unsigned int Options; if (!acsc_GetCommOptions(Handle, &Options)) { printf("transaction error: %dn", acsc_GetLastError()); } 4.2.2 acsc_GetDefaultTimeout Description The function retrieves default communication timeout. Syntax int acsc_GetDefaultTimeout(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is the default time-out value in milliseconds. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The value of the default time-out depends on the type of established communication channel. Time-out also depends on the baud rate value for serial communication. Example int DefTimeout = acsc_GetDefaultTimeout(Handle); if (DefTimeout == 0) { printf("default timeout receipt error: %dn", acsc_GetLastError()); } 31 January 2009 51 C Library Functions
- 66. C Library Reference Version 6.50 Programmer’s Guide 4.2.3 acsc_GetErrorString Description The function retrieves the explanation of an error code. Syntax int acsc_GetErrorString(HANDLE Handle, int ErrorCode, char* ErrorStr, int Count, int* Received) Arguments Handle Communication handle ErrorCode Error code. ErrorStr Pointer to the buffer that receives the text explanation of ErrorCode. Count Size of the buffer pointed by ErrorStr Received Number of characters that were actually received Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the string that contains the text explanation of the error code returned by the acsc_GetLastError, acsc_GetMotorError, acsc_GetMotionError, and acsc_GetProgramError functions. The function will not copy more than Count characters to the ErrorStr buffer. If the buffer is too small, the error explanation can be truncated. For the SPiiPlus C Library error codes, the function returns immediately with the text explanation. For the controller’s error codes, the function refers to the controller to get the text explanation. 31 January 2009 52 C Library Functions
- 67. C Library Reference Version 6.50 Programmer’s Guide Example char ErrorStr[256]; int ErrorCode, Received; ErrorCode = acsc_GetLastError(); if (acsc_GetErrorString(Handle, // communication handle ErrorCode, // error code ErrorStr, // buffer for the error explanation 255, // available buffer length &Received// number of actually received bytes )) { ErrorStr[Received] = ‘0’; printf("function returned error: %d (%s)n", ErrorCode, ErrorStr); } 4.2.4 acsc_GetLastError Description The function returns the calling thread’s last-error code value. The last-error code is maintained on a per-thread basis. Multiple threads do not overwrite each other’s last-error code. Syntax int acsc_GetLastError() Arguments This function has no arguments. Return Value The return value is the calling thread’s last-error code value. Comments It is necessary to call acsc_GetLastError immediately when some functions return zero value. This is because all of the functions rewrite the error code value when they are called. For a complete List of Error Codes, “Error Codes” on Page 368. Example printf("function returned error: %dn", acsc_GetLastError()); 4.2.5 acsc_GetLibraryVersion Description The function retrieves the SPiiPlus C Library version number. 31 January 2009 53 C Library Functions
- 68. C Library Reference Version 6.50 Programmer’s Guide Syntax unsigned int acsc_GetLibraryVersion() Arguments This function has no arguments. Return Value The return value is the 32-bit unsigned integer value, which specifies binary version number. Comments The SPiiPlus C Library version consists of four (or less) numbers separated by points: #.#.#.#. The binary version number is represented by 32-bit unsigned integer value. Each byte of this value specifies one number in the following order: high byte of high word – first number, low byte of high word – second number, high byte of low word – third number and low byte of low word – forth number. For example version “2.10” has the following binary representation (hexadecimal format): 0x020A0000. First two numbers in the string form are obligatory. Any release version of the library consists of two numbers. The third and fourth numbers specify an alpha or beta version, special or private build, etc. Example unsigned int Ver = acsc_GetLibraryVersion(); printf("SPiiPlus C Library version is %d.%d.%d.%dn", HIBYTE(HIWORD(Ver)), LOBYTE(HIWORD(Ver)), HIBYTE(LOWORD(Ver)), LOBYTE(LOWORD(Ver))); 4.2.6 acsc_GetTimeout Description The function retrieves communication timeout. Syntax int acsc_GetTimeout(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is the current timeout value in milliseconds. If the function fails, the return value is zero. 31 January 2009 54 C Library Functions
- 69. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Example int Timeout = acsc_GetTimeout(Handle); if (Timeout == 0) { printf("timeout receipt error: %dn", acsc_GetLastError()); } 4.2.7 acsc_SetIterations Description The function sets the number of iterations in one transaction. Syntax int acsc_SetIterations(HANDLE Handle, int Iterations) Arguments Handle Communication handle Iterations Number of iterations Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments If, after the transmission of command to the controller, the controller response is not received during the predefined time, the library repeats the transmission of command. The number of those iterations is defined by the Iterations parameter for each communication channel independently. Most of the SPiiPlus C functions perform communication with the controller by transactions 31 January 2009 55 C Library Functions
- 70. C Library Reference Version 6.50 Programmer’s Guide (i.e., they send commands and wait for responses) that are based on the acsc_Transaction function. Therefore, the changing of number of iterations can have an influence on the behavior of the user application. The default the number of iterations for all communication channels is 2. Example if (!acsc_SetIterations(Handle, 2)) { printf("number of iterations setting error: %dn", acsc_GetLastError()); } 4.2.8 acsc_SetCommOptions Description The function sets the communication options. Syntax int acsc_SetCommOptions(HANDLE Handle, unsigned int Options) Arguments Handle Communication handle Options Communication options to be set Bit-mapped parameter that can include one of the following flags: ACSC_COMM_USE_CHECKSUM: the communication mode used when each command is sent to the controller with checksum and the controller also responds with checksum. ACSC_COMM_AUTORECOVER_HW_ERROR: When a hardware error is detected in the communication channel and this bit is set, the library automatically repeats the transaction, without counting iterations. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 56 C Library Functions
- 71. C Library Reference Version 6.50 Programmer’s Guide Comments The function sets the communication options. To get current communication option, call acsc_GetCommOptions. To add some communication options to the current configuration, modify an Option parameter that has been filled in by a call to acsc_GetCommOptions. This ensures that the other communication options will have same values. Example // the example sets the mode with checksum unsigned int Options; acsc_GetCommOptions(Handle, &Options); Options = Options | ACSC_COMM_USE_CHECKSUM; acsc_SetCommOptions(Handle, Options); 4.2.9 acsc_SetTimeout Description The function sets the communication timeout. Syntax int acsc_SetTimeout(HANDLE Handle, int Timeout) Arguments Handle Communication handle Timeout Maximum waiting time in milliseconds. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the communication timeout. All of the subsequent waiting calls of the functions will wait for the controller response Timeout in milliseconds. If the controller does not respond to the sent command during this time, SPiiPlus C functions return with zero value. In this case, the call of acsc_GetLastError 31 January 2009 57 C Library Functions
- 72. C Library Reference Version 6.50 Programmer’s Guide will return the ACSC_TIMEOUT error. Example if (!acsc_SetTimeout(Handle, 5000)) { printf("timeout set error: %dn", acsc_GetLastError()); } 4.2.10 acsc_SetQueueOverflowTimeout Description The function sets the Queue Overflow Timeout. Syntax int acsc_SetQueueOverflowTimeout (HANDLE Handle, int Delay) Arguments Handle Communication handle. Timeout Timeout value in milliseconds Return Value If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets Queue Overflow Timeout value in milliseconds. See also “Non-Waiting Calls” on Page 12. Example if (!acsc_ SetQueueOverflowTimeout(Handle,100)) { printf("Queue Overflow Timeout setting error: %dn", acsc_GetLastError()); } 31 January 2009 58 C Library Functions
- 73. C Library Reference Version 6.50 Programmer’s Guide 4.2.11 acsc_GetQueueOverflowTimeout Description The function retrieves the Queue Overflow Timeout. Syntax int acsc_GetQueueOverflowTimeout(HANDLE Handle) Arguments Handle Communication handle. Return Value If the function succeeds, the return value is the current Queue Overflow Timeout value in milliseconds. If the function fails, the return value is ACSC_NONE. Note Extended error information can be obtained by calling acsc_GetLastError. Comments See Non-Waiting Calls for an explanation about Queue Overflow Timeout. Example int QueueTimeout = acsc_GetQueueOverflowTimeout(Handle); if (QueueTimeout == ACSC_NONE) { printf("Queue Overflow Timeout receipt error: %dn", acsc_GetLastError()); }x 4.3 ACSPL+ Program Management Functions The Program Management functions are: Table 7 ASSPL+ Program Management Functions (page 1 of 2) Function Description acsc_AppendBuffer Appends one or more ACSPL+ lines to the program in the specified program buffer. acsc_ClearBuffer Deletes the specified ACSPL+ program lines in the specified program buffer. 31 January 2009 59 C Library Functions
- 74. C Library Reference Version 6.50 Programmer’s Guide Table 7 ASSPL+ Program Management Functions (page 2 of 2) Function Description acsc_CompileBuffer Compiles ACSPL+ program in the specified program buffer(s). acsc_DownloadBuffer The function has been renamed to acsc_AppendBuffer. acsc_LoadBuffer Clears the specified program buffer and then loads ACSPL+ program to this buffer. acsc_LoadBufferIgnoreServiceLines Clears the specified program buffer and then loads ACSPL+ program to this buffer. acsc_LoadBuffersFromFile Opens a file that contains one or more ACSPL+ programs allocated to several buffers and download the programs to the corresponding buffers. acsc_RunBuffer Starts up ACSPL+ program in the specified program buffer. acsc_StopBuffer Stops ACSPL+ program in the specified program buffer(s). acsc_SuspendBuffer Suspends ACSPL+ program in the specified program buffer(s). acsc_UploadBuffer Uploads ACSPL+ program from the specified program buffer. 4.3.1 acsc_AppendBuffer Description The function appends one or more ACSPL+ lines to the program in the specified buffer. Syntax int acsc_AppendBuffer(HANDLE Handle, int Buffer, char* Program, int Count, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Buffer Buffer number, from 0 to 10. Program Pointer to the buffer contained ACSPL+ program(s). Count Number of characters in the buffer pointed by Program 31 January 2009 60 C Library Functions
- 75. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function appends one or more ACSPL+ lines to the program in the specified buffer. If the buffer already contains any program, the new text is appended to the end of the existing program. No compilation or syntax check is provided during downloading. In fact, any text, not only a correct program, can be inserted into a buffer. In order to compile the program and check its accuracy, the compile command must be executed after downloading. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 61 C Library Functions
- 76. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_AppendBuffer char buf[256]; strcpy(buf, "!This is a test ACSPL+ programn" ); strcat(buf, "enable Xn" ); strcat(buf, "ptp X, 1000n" ); strcat(buf, "stopn" ); if (!acsc_AppendBuffer( Handle, // communication handle 0, // ACSPL+ program buffer // number buf, // buffer contained ACSPL+ // program(s) strlen(buf), // size of this buffer NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.2 acsc_ClearBuffer Description The function deletes the specified ACSPL+ program lines in the specified program buffer. Syntax int acsc_ClearBuffer(HANDLE Handle, int Buffer, int FromLine, int ToLine, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Buffer Buffer number, from 0 to 10. FromLine, These parameters specify a range of lines to be deleted. ToLine FromLine starts from 1. If ToLine is larger then the total number of lines in the specified program buffer, the range includes the last program line. If ToLine is ACSC_MAX_LINE, the function deletes all lines in the specified buffer. 31 January 2009 62 C Library Functions
- 77. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function deletes the specified ACSPL+ program lines in the specified program buffer. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_ClearBuffer if (!acsc_ClearBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number 1, ACSC_MAX_LINE, // delete all lines in the buffer NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.3 acsc_CompileBuffer Description The function compiles ACSPL+ program in the specified program buffer(s). Syntax int acsc_CompileBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait) 31 January 2009 63 C Library Functions
- 78. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Buffer Buffer number, from 0 to 10. Use ACSC_NONE instead of the buffer number, to compile all programs in all buffers. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value The function returns non-zero if it succeeded to perform the compile operation on the buffer, such that the communication channel is OK, the specified buffer is not running and compile operation was performed. However, it does not mean that compilation succeeded. If the return value is zero, compile operation could not be performed by some reason. Note Extended error information can be obtained by calling acsc_GetLastError. In order to get information about compilation results, use acsc_ReadInteger to read PERR [X], which contains the last error that occurred in buffer X. If PERR [X] is zero the buffer was compiled successfully. Otherwise, PERR [X] tells you about the error that occurred during the compilation. Comments The function compiles ACSPL+ program in the specified program buffer or all programs in all buffers if the parameter Buffer is ACSC_NONE. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the program was compiled successfully. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 64 C Library Functions
- 79. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_CompileBuffer if (!acsc_CompileBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number NULL // waiting call )) { printf("compilation error: %dn", acsc_GetLastError()); } 4.3.4 acsc_DownloadBuffer Description The function has been renamed to acsc_AppendBuffer. Previously written applications can use this function as before. 4.3.5 acsc_LoadBuffer Description The function clears the specified program buffer and then loads ACSPL+ program to this buffer. Syntax int acsc_LoadBuffer(HANDLE Handle, int Buffer, char* Program, int Count, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Buffer Buffer number, from 0 to 10. Program Pointer to the buffer contained ACSPL+ program(s). Count Number of characters in the buffer pointed by Program 31 January 2009 65 C Library Functions
- 80. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function clears the specified program buffer and then loads ACSPL+ program to this buffer. No compilation or syntax check is provided during downloading. Any text, not only a correct program, can be inserted into a buffer. In order to compile the program and check its accuracy, the compile command must be executed after downloading. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 66 C Library Functions
- 81. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_LoadBuffer char buf[256]; strcpy(buf, "!This is a test ACSPL+ programn" ); strcat(buf, "enable Xn" ); strcat(buf, "ptp X, 1000n" ); strcat(buf, "stopn" ); if (!acsc_LoadBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number buf, // pointer to the buffer contained // ACSPL+ program(s). strlen(buf), // size of this buffer NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.6 acsc_LoadBufferIgnoreServiceLines Description The function clears the specified program buffer and then loads ACSPL+ to this buffer. All lines that start with # are ignored. Note This function is obsolete and is maintained only for backwards compatablitiy. When loading files saved from the MultiDebugger and MMI use the acsc_LoadBuffersFromFile function. Syntax int acsc_LoadBufferIgnoreServiceLines(HANDLE Handle, int Buffer, char* Program, int Count, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Buffer Program buffer number: 0 to 10. Program Pointer to the buffer contained ACSPL+ program(s). Count Number of characters in the buffer pointed by Program 31 January 2009 67 C Library Functions
- 82. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function clears the specified program buffer and then loads ACSPL+ program to this buffer. No compilation or syntax check is provided during downloading. Any text, not only a correct program, can be inserted into a buffer. In order to compile the program and check its accuracy, the compile command must be executed after downloading. Note You can use this function in order to load program from file created by SPiiPlus MMI or SPiiPlus MD only if it contains a program from one buffer only. Otherwise, programs from several buffers will stick together, because the separators are ignored. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 68 C Library Functions
- 83. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_LoadBuffer char buf[256]; strcpy(buf, "!This is a test ACSPL+ programn" ); strcat(buf, "#Version 3.0 n" ); //Ignored – won’t be loaded strcat(buf, "enable Xn" ); strcat(buf, "ptp X, 1000n" ); strcat(buf, "stopn" ); if (!acsc_LoadBufferIgnoreServiceLines (Handle // communication handle 0, // ACSPL+ program buffer number buf, // pointer to the buffer contained // ACSPL+ program(s). strlen(buf), // size of this buffer NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.7 acsc_LoadBuffersFromFile Description The function opens a file that contains one or more ACSPL+ programs allocated to several buffers and download the programs to the corresponding buffers. Syntax int acsc_LoadBuffersFromFile(HANDLE Handle, char *Filename, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Filename Path of the file Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 69 C Library Functions
- 84. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function analyzes the file, determines which program buffers should be loaded, clears them and then loads ACSPL+ programs to those buffers. SPiiPlus software tools save ACSPL+ programs in the following format: # Header: Date, Firmware version etc. #Buf1 (buffer number) ACSPL+ program of Buf1 #Buf2 (buffer number) ACSPL+ program of Buf2 #Buf3 (buffer number) ACSPL+ program of Buf3 etc. The number of buffers in a file may change from 1 to 10, without any default order. No compilation or syntax check is provided during downloading. Any text, not only a correct program, can be inserted into a buffer. In order to compile the program and check its accuracy, the compile command must be executed after downloading. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_LoadBuffersFromFile if (!acsc_LoadBuffersFromFile(Handle, // communication //handle “C:MMIProgram.prg”, //full path NULL // waiting call )) { printf("acsc_LoadBuffersFromFile: %dn", acsc_GetLastError()); } 4.3.8 acsc_RunBuffer Description The function starts up ACSPL+ program in the specified buffer. Syntax int acsc_RunBuffer(HANDLE Handle, int Buffer, char* Label, ACSC_WAITBLOCK* Wait) 31 January 2009 70 C Library Functions
- 85. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Buffer Buffer number, from 0 to 9. Label Label in the program that the execution starts from. If NULL is specified instead of a pointer, the execution starts from the first line. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function starts up ACSPL+ program in the specified buffer. The execution starts from the specified label, or from the first line if the label is not specified. If the program was not compiled before, the function first compiles the program and then starts it. If an error was encountered during compilation, the program does not start. If the program was suspended by the acsc_SuspendBuffer function, the function resumes the program execution from the point where the program was suspended. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the program in the specified buffer was started successfully. The function does not wait for the program end. To wait for the program end, use the acsc_WaitProgramEnd function. 31 January 2009 71 C Library Functions
- 86. C Library Reference Version 6.50 Programmer’s Guide If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_RunBuffer if (!acsc_RunBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number NULL, // from the beginning of this buffer NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.9 acsc_StopBuffer Description The function stops the execution of ACSPL+ program in the specified buffer(s). Syntax int acsc_StopBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Buffer Buffer number, from 0 to 10. Use ACSC_NONE instead of the buffer number, to stop the execution of all programs in all buffers. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 72 C Library Functions
- 87. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function stops ACSPL+ program execution in the specified buffer or in all buffers if the parameter Buffer is ACSC_NONE. The function has no effect if the program in the specified buffer is not running. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example / example of the waiting call of acsc_StopBuffer if (!acsc_StopBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.10 acsc_SuspendBuffer Description The function suspends the execution of ACSPL+ program in the specified program buffer(s). Syntax int acsc_SuspendBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Buffer Buffer number, from 0 to 10. Use ACSC_NONE instead of the buffer number, to suspend the execution of all programs in all buffers. 31 January 2009 73 C Library Functions
- 88. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function suspends ACSPL+ program execution in the specified buffer or in all buffers if the parameter Buffer is ACSC_NONE. The function has no effect if the program in the specified buffer is not running. To resume execution of the program in the specified buffer, call the acsc_RunBuffer function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SuspendBuffer if (!acsc_SuspendBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.3.11 acsc_UploadBuffer Description The function uploads ACSPL+ program from the specified program buffer. 31 January 2009 74 C Library Functions
- 89. C Library Reference Version 6.50 Programmer’s Guide Syntax int acsc_UploadBuffer(HANDLE Handle, int Buffer, int Offset, char* Program, int Count, int* Received, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Buffer Program buffer number, from 0 to 10. Offset Binary offset in the buffer that defines start point of uploading. Program Pointer to the buffer that receives uploaded text Count Size of the receiving buffer pointed by Program Received Number of characters that were actually uploaded. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function uploads ACSPL+ program from the specified program buffer. Uploading starts from the specified offset. The first uploaded character is character number Offset in the program text. Uploading lasts until Count characters are uploaded or the end of the program is achieved. The function assigns variable Received with a number of characters that were actually uploaded. The value can be less than Count if the function failed or the end of the program is achieved. 31 January 2009 75 C Library Functions
- 90. C Library Reference Version 6.50 Programmer’s Guide If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Text, Received and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_UploadBuffer char buf[256]; int Received; if (!acsc_UploadBuffer( Handle, // communication handle 0, // ACSPL+ program buffer number 0, // from the beginning of this buffer buf, // pointer to the buffer that receives uploaded // text 256, // size of this buffer &Received, // number of characters that were actually // uploaded NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.4 Read and Write Variables Functions The Read and Write Variables functions are: Table 8 Read and Write Variables Functions Function Description acsc_ReadInteger Reads value from integer variable. acsc_WriteInteger Writes value to integer variable. acsc_ReadReal Reads value from real variable. acsc_WriteReal Writes value to real variable. 4.4.1 acsc_ReadInteger Description The function reads value(s) from integer variable. Syntax int acsc_ReadInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2, int To2, int* Values, ACSC_WAITBLOCK* Wait) 31 January 2009 76 C Library Functions
- 91. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle NBuf Number of program buffer for local variable or ACSC_NONE for global and standard variable. Var Pointer to a null-terminated character string that contains a name of the variable. From1, To1 Index range (first dimension). From2, To2 Index range (second dimension). Values Pointer to the buffer that receives requested values. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function reads specified integer variable or array. The variable can be a standard controller variable, a user global variable, or a user local variable. Standard and user global variables have global scope. Therefore, parameter Nbuf must be ACSC_NONE (-1) for these classes of variables. User local variable exists only within a buffer. The buffer number must be specified for user local variable. 31 January 2009 77 C Library Functions
- 92. C Library Reference Version 6.50 Programmer’s Guide If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE. The function reads the requested value and assigns it to the variable pointed by Values. If the variable is a one-dimensional array, From1, To1 must specify the index range and From2, To2 must be ACSC_NONE. Array Values must be of size To1-From1+1 at least. The function reads all requested values from index From1 to index To1 inclusively and stores them in the Values array. If the variable is a two-dimensional array, From1, To1 must specify the index range of the first dimension and From2, To2 must specify the index range of the second dimension. Array Values must be of size (To1-From1+1)x(To2-From2+1) values at least. The function uses the Values array in such a way: first, the function reads To2-From2+1 values from row From1 and fills the Values array elements from 0 to To2-From2, then reads To2-From2+1 values from raw From1+1 and fills the Values array elements from To2-From2+1 to 2*(To2- From2)+1, etc. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Values and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_ReadInteger int AnalogInputs[8]; if (!acsc_ReadInteger( Handle, // communication handle ACSC_NONE, // standard variable "AIN", // variable name 0, 7, // first dimension indexes ACSC_NONE, ACSC_NONE,// no second dimension AnalogInputs, // pointer to the buffer // that receives requested // values NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.4.2 acsc_WriteInteger Description The function writes value(s) to integer variable. Syntax int acsc_WriteInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2, int To2, int* Values, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle 31 January 2009 78 C Library Functions
- 93. C Library Reference Version 6.50 Programmer’s Guide NBuf Number of program buffer for local variable or ACSC_NONE for global and standard variable. Var Pointer to the null-terminated character string contained name of the variable. From1, To1 Index range (first dimension). From2, To2 Index range (second dimension). Values Pointer to the buffer contained values that must be written. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes to a specified integer variable or array. The variable can be a standard controller variable, user global or user local. Standard and user global variables have global scope. Therefore, parameter Nbuf must be ACSC_NONE (-1) for these classes of variables. User local variable exists only within a buffer. The buffer number must be specified for user local variable. If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE (-1). The function writes the value pointed by Values to the specified variable. If the variable is a one-dimensional array, From1, To1 must specify the index range and From2, To2 must be ACSC_NONE (-1). Array Values must contain To1-From1+1 values at 31 January 2009 79 C Library Functions
- 94. C Library Reference Version 6.50 Programmer’s Guide least. The function writes the values to the specified variable from index From1 to index To1 inclusively. If the variable is a two-dimensional array, From1, To1 must specify the index range of the first dimension and From2, To2 must specify the index range of the second dimension. Array Values must contain (To1-From1+1)x(To2-From2+1) values at least. The function uses the Values array as follows: first, the function retrieves the Values elements from 0 to To2-From2 and writes them to row From1 of the specified controller variable, then retrieves the Values elements from To2-From2+1 to 2*(To2-From2)+1 and writes them to row From1+1 of the specified controller variable, etc. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example / example of the waiting call of acsc_WriteInteger int AnalogOutputs[4] = { 10, 20, 30, 40 }; if (!acsc_WriteInteger(Handle, // communication handle ACSC_NONE, // standard variable "AOUT", // variable name 0, 3, // first dimension indexes ACSC_NONE, ACSC_NONE, // no second dimension AnalogOutputs, // pointer to the buffer contained values // that must be written NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.4.3 acsc_ReadReal Description The function reads value(s) from a real variable. Syntax int acsc_ReadReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2, int To2, double* Values, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle NBuf Number of program buffer for local variable or ACSC_NONE for global and standard variable. 31 January 2009 80 C Library Functions
- 95. C Library Reference Version 6.50 Programmer’s Guide Var Pointer to the null-terminated character string contained name of the variable. From1, To1 Index range (first dimension). From2, To2 Index range (second dimension). Values Pointer to the buffer that receives requested values. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function reads specified real variable or array. The variable can be a standard controller variable, user global variable, or user local variable. Standard and user global variables have global scope. Therefore, parameter Nbuf must be ACSC_NONE (-1) for these classes of variables. User local variable exists only within a buffer. The buffer number must be specified for user local variable. If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE. The function reads the requested value and assigns it to the variable pointed by Values. If the variable is a one-dimensional array, From1, To1 must specify the index range and From2, To2 must be ACSC_NONE. Array Values must be of size To1-From1+1 at least. The function reads all requested values from index From1 to index To1 inclusively and stores them in the Values array. 31 January 2009 81 C Library Functions
- 96. C Library Reference Version 6.50 Programmer’s Guide If the variable is a two-dimensional array, From1, To1 must specify the index range of the first dimension and From2, To2 must specify the index range of the second dimension. Array Values must be of size (To1-From1+1)x(To2-From2+1) values at least. The function uses the Values array in such a way: first, the function reads To2-From2+1 values from row From1 and fills the Values array elements from 0 to To2-From2, then reads To2-From2+1 values from raw From1+1 and fills the Values array elements from To2-From2+1 to 2*(To2- From2)+1, etc. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Values and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_ReadReal double FPositions[8]; if (!acsc_ReadReal( Handle, // communication handle ACSC_NONE, // standard variable "FPOS", // variable name 0, 7, // first dimension indexes ACSC_NONE, ACSC_NONE, // no second dimension FPositions, // pointer to the buffer that // receives requested values NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.4.4 acsc_WriteReal Description The function writes value(s) to the real variable. Syntax int acsc_WriteReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2, int To2, double* Values, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle NBuf Number of program buffer for local variable or ACSC_NONE for global and standard variable. Var Pointer to the null-terminated character string contained name of the variable. From1, To1 Index range (first dimension). 31 January 2009 82 C Library Functions
- 97. C Library Reference Version 6.50 Programmer’s Guide From2, To2 Index range (second dimension). Values Pointer to the buffer contained values that must be written. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes to the specified real variable or array. The variable can be a standard controller variable, user global or user local. Standard and user global variables have global scope. Therefore, parameter Nbuf must be ACSC_NONE (-1) for these classes of variables. User local variable exists only within a buffer. The buffer number must be specified for user local variable. If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE (-1). The function writes the value pointed by Values to the specified variable. If the variable is a one-dimensional array, From1, To1 must specify the index range and From2, To2 must be ACSC_NONE (-1). Array Values must contain To1-From1+1 values at least. The function writes the values to the specified variable from index From1 to index To1 inclusively. If the variable is a two-dimensional array, From1, To1 must specify the index range of the first dimension and From2, To2 must specify the index range of the second dimension. Array Values must contain (To1-From1+1)x(To2-From2+1) values at least. The function uses the Values array in such a way: first, the function retrieves the Values elements from 0 to To2- From2 and writes them to row From1 of the specified controller variable, then retrieves the 31 January 2009 83 C Library Functions
- 98. C Library Reference Version 6.50 Programmer’s Guide Values elements from To2-From2+1 to 2*(To2-From2)+1 and writes them to row From1+1 of the specified controller variable, etc. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_WriteReal double Velocity[8] = { 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000 }; if (!acsc_WriteReal( Handle, // communication handle ACSC_NONE, // standard variable "VEL", // variable name 0, 7, // first dimension indexes ACSC_NONE, ACSC_NONE, // no second dimension Velocity, // pointer to the buffer contained values // to be written NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.5 Load/Upload Data To/From Controller Functions The Load/Upload Data To/From Controller functions are: Table 9 Load File to ACSPL+ Variables Functions Function Description acsc_LoadDataToController Writes value(s) from text file to SPiiPlus controller (variable or file). acsc_UploadDataFromController Writes value(s) from the SPiiPlus controller (variable or file) to a text file. 4.5.1 acsc_LoadDataToController Description The function writes value(s) from text file to SPiiPlus controller (variable or file). Syntax int acsc_LoadDataToController(HANDLE Handle,int Dest, char* DestName, int From1, int To1, int From2, int To2, char* SrcFileName, int SrcNumFormat, bool bTranspose, ACSC_WAITBLOCK* Wait) 31 January 2009 84 C Library Functions
- 99. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Dest Number of program buffer for local variable, ACSC_NONE for global and standard variable. ACSC_FILE for loading directly to file on flash memory (only arrays can be written directly into controller files). DestName Pointer to the null-terminated character string that contains name of the variable or file. From1, To1 Index range (first dimension). From2, To2 Index range (second dimension). SrcFileName Filename (including path) of the source text data file. SrcNumFormat Format of number(s) in source file. Use ACSC_INT_TYPE and ACSC_REAL_TYPE for integer and real numbers, respectively. bTranspose If TRUE, then the array will be transposed before being loaded; otherwise, this parameter has no affect. Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes to a specified variable (scalar/array) or directly to a binary file on the controller's flash memory. The variable can be an ACSPL+ variable, user global or user local. ACSPL+ and user global variables have global scope. Therefore, Dest must be ACSC_NONE (-1) for these classes of variables. User local variable exists only within a buffer. The buffer number must be specified for user local variable. If Dest is ACSC_NONE (-1) and there is no global variable with the name specified by DestName, it would be defined. Arrays will be defined with dimensions (To1+1, To2+1). 31 January 2009 85 C Library Functions
- 100. C Library Reference Version 6.50 Programmer’s Guide If performing loading directly to a file, From1, To1, From2 and To2 are meaningless. If the variable is scalar, the From1, To1, From2, and To2 arguments must be ACSC_NONE (-1). The function writes the value from the file specified by SrcFileName to the variable specified by Name. If the variable is a one-dimensional array, From1, To1 must specify the index range and the From2, To2 must be ACSC_NONE (-1). The text file, pointed to by the SrcFileName argument, must contain To1 to From1+1 values, at least. The function writes the values to the specified variable from the From1 index tothe To1 index inclusively. If the variable is a two-dimensional array, From1, To1 must specify the index range of the first dimension and From2, To2 must specify the index range of the second dimension. The text file, pointed to by the SrcFileName argument, must contain ((To1-From1+1) x (To2-From2+1)) values, at least; otherwise, an error will occur. The function uses the text file as follows: 1. The function retrieves the To2-From2+1 values and writes them to row From1 of the specified controller variable 2. Then retrieves next To2-From2+1 values and writes them to row From1+1 of the specified controller variable, etc. Note If bTranspose is TRUE, the function actions are inverted. It takes To1- From1+1 values and writes them to column From2 of the specified controller variable, then retrieves next To1-From1+1 values and writes them to column From2+1 of the specified controller variable, etc. The text file is processed line-by-line; any characters except numbers, dots, commas and exponent 'e' are translated as separators between the numbers. A line that starts with no digits is considered as comment and ignored. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function has been made. 31 January 2009 86 C Library Functions
- 101. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_LoadDataToController if (!acsc_LoadDataToController(Handle, // communication handle ACSC_NONE, // standard variable "UserArray", // variable name 0, 99, // first dimension indexes -1,-1, // no second dimension "UserArr.TXT", // Text file name contained values // that must be written ACSC_INT_TYPE, //decimal integers FALSE, //no Transpose required NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } UserArr.TXT has this structure: 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 …………… 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 …………… 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 …………… 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 …………… … … 4.5.2 acsc_UploadDataFromController Description This function writes value(s) from the SPiiPlus controller (variable or file) to a text file. Syntax int acsc_UploadDataFromController(HANDLE Handle, int Src, char * SrcName, int SrcNumFormat, int From1, int To1, int From2, int To2, char* DestFileName, char* DestNumFormat, bool bTranspose, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Src Number of the program buffer for local variable, ACSC_NONE for global and ASCPL+ variables, and ACSC_FILE for downloading directly from file on flash memory. SrcName Pointer to the null-terminated character string that contains name of the Variable or File. 31 January 2009 87 C Library Functions
- 102. C Library Reference Version 6.50 Programmer’s Guide SrcNumFormat Format of number(s) in the controller. Use ACSC_INT_BINARY for integer or ACSC_REAL_BINARY for real. From1, To1 Index range (first dimension). From2, To2 Index range (second dimension). DestFileName Filename (including ful path) of the destination text file. DestNumFormat Pointer to the null-terminated character string that contains the formatting string that will be used for printing into file, for example, 1:%dn. Use the string with %d for integers, and %lf for reals. bTranspose If TRUE, then the array is transposed before being downloaded; otherwise, this parameter has no effect. Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes data to the specified file from a specified variable (scalar/array) or directly from a binary file in the controller's flash memory. The variable can be a standard ASCPL+ variable, user global or user local. The ASCPL+ and user global variables have global scope. In this case, the Src argument has to be ACSC_NONE (-1) for these classes of variables. User local variable exists only within a buffer. The buffer number has to be specified for user local variable. If the variable (or file) with the name specified by SrcName does not exist, an error occurs. If loading directly from the file, From1, To1, From2 and To2 are meaningless. If the variable is a scalar, all From1, To1, From2 and To2 values must be ACSC_NONE (-1). The function writes the value from variable specified by SrcName to the file specified by DestFileName. If the variable is a one-dimensional array, From1, To1 must specify the index range, and From2, To2 must be ACSC_NONE (-1). The function writes the values from the specified 31 January 2009 88 C Library Functions
- 103. C Library Reference Version 6.50 Programmer’s Guide variable from the From1 value to the To1 value, inclusively, to the file specified by DestFileName. If the variable is a two-dimensional array, From1, To1 must specify the index range of the first dimension, and From2, To2 must specify the index range of the second dimension. The function uses the variable as follows: first, the function retrieves the To2-From2+1 values from the row specified in From1 and writes them to the file specified by DestFileName. It then retrieves To2-From2+1 values from the From1+1 row and writes them, and so forth. If bTranspose is TRUE, the function actions are inverted. It takes To1-From1+1 values from the row specified by From2 and writes them to first column of the destination file. Then retrieves the next To1-From1 values from row From2+1 and writes them to the next column of the file. The destination file’s format can be determined by string specified by DestNumFormat. This string will be used as argument in *printf function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_DownloadDataFromController if (!acsc_UploadDataFromController(Handle, // communication handle ACSC_NONE, // standard variable "UserArray", // variable name ACSC_INT_BINARY, //from binary integers 0, 99, // first dimension indexes -1,-1, // no second dimension "UserArr.TXT", // Text file name of destination file // that must be written "%d",//Format of written file FALSE, //no Transpose required NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.6 Multiple Thread Synchronization Functions The Multiple Thread Synchronization functions are: Table 10 Multiple Thread Synchronization Functions Function Description acsc_CaptureComm Captures a communication channel. acsc_ReleaseComm Releases a communication channel. 31 January 2009 89 C Library Functions
- 104. C Library Reference Version 6.50 Programmer’s Guide 4.6.1 acsc_CaptureComm Description The function captures a communication channel. Syntax int acsc_CaptureComm(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function captures the communication handle for the calling thread and prevents access to this communication handle from other threads. If one thread captures the communication handle and another thread calls one of SPiiPlus C Library functions using the same handle, the second thread will be delayed until the first thread executes acsc_ReleaseComm. The function provides ability to execute a sequence of functions without risk of intervention from other threads. Example if (!acsc_CaptureComm(Handle)) { printf("capture communication error: %dn", acsc_GetLastError()); } 4.6.2 acsc_ReleaseComm Description The function releases a communication channel. 31 January 2009 90 C Library Functions
- 105. C Library Reference Version 6.50 Programmer’s Guide Syntax int acsc_ReleaseComm(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function releases the communication handle captured by acsc_CaptureComm and allows other threads to communicate through the channel. Example if (!acsc_ReleaseComm(Handle)) { printf("release communication error: %dn", acsc_GetLastError()); } 4.7 History Buffer Management Functions The History Buffer Management functions are: Table 11 History Buffer Management Functions Function Description acsc_OpenHistoryBuffer Opens a history buffer. acsc_CloseHistoryBuffer Closes a history buffer. acsc_GetHistory Retrieves the contents of the history buffer. 4.7.1 acsc_OpenHistoryBuffer Description The function opens a history buffer. 31 January 2009 91 C Library Functions
- 106. C Library Reference Version 6.50 Programmer’s Guide Syntax LP_ACSC_HISTORYBUFFER acsc_OpenHistoryBuffer(HANDLE Handle, int Size) Arguments Handle Communication handle Size Required size of the buffer in bytes Return Value The function returns pointer to ACSC_HISTORYBUFFER structure. If the buffer cannot be allocated, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function allocates a history buffer that stores all commands sent to the controller and all responses and unsolicited messages received from the controller. Only one history buffer can be open for each communication handle. The buffer works as a cyclic buffer. When the amount of the stored data exceeds the buffer size, the newly stored data overwrites the earliest data in the buffer. Example LP_ACSC_HISTORYBUFFER lpHistoryBuf = acsc_OpenHistoryBuffer( Handle, // communication handle 10000 // size of the buffer ); if (!lpHistoryBuf) { printf("opening history buffer error: %dn", acsc_GetLastError()); } 4.7.2 acsc_CloseHistoryBuffer Description The function closes the history buffer and discards all stored history. Syntax int acsc_CloseHistoryBuffer(HANDLE Handle) 31 January 2009 92 C Library Functions
- 107. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function closes the history buffer and releases the used memory. All information stored in the buffer is discarded. Example if (!acsc_CloseHistoryBuffer(Handle)) { printf("closing history buffer error: %dn", acsc_GetLastError()); } 4.7.3 acsc_GetHistory Description The function retrieves the contents of the history buffer. Syntax int acsc_GetHistory(HANDLE Handle, char* Buf, int Count, int* Received, BOOL bClear) Arguments Handle Communication handle Buf Pointer to the buffer that receives the communication history Count Size of the buffer in bytes Received Number of characters that were actually received 31 January 2009 93 C Library Functions
- 108. C Library Reference Version 6.50 Programmer’s Guide bClear If TRUE, the function clears contents of the history buffer If FALSE, the history buffer content is not cleared. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the communication history from the history buffer and stores it in the buffer pointed by Buf. The communication history includes all commands sent to the controller and all responses and unsolicited messages received from the controller. The amount of received data does not exceed the size of the history buffer. The history buffer works as a cyclic buffer: when the amount of the stored data exceeds the buffer size, the newly stored data overwrites the earliest data in the buffer. Therefore, as a rule, the retrieved communication history includes only the recently sent commands and receives responses and unsolicited messages. The depth of the retrieved history depends on the history buffer size. The history data is retrieved in historical order, i.e. the earliest message is stored at the beginning of Buf. The first retrieved message in Buf can be incomplete, because of being partially overwritten in the history buffer. If the size of the Buf is less than the size of the history buffer, only the most recent part of the stored history is retrieved. Example int Received; char Buf[10000]; if (!acsc_GetHistory(Handle, // communication handle Buf, // pointer to the buffer that receives a // communication history 10000, // size of this buffer &Received, // number of characters that were actually received TRUE // clear contents of the history buffer )) { printf("getting history error: %dn", acsc_GetLastError()); } 31 January 2009 94 C Library Functions
- 109. C Library Reference Version 6.50 Programmer’s Guide 4.8 Unsolicited Messages Buffer Management Functions The Unsolicited Messages Buffer Management functions are: Table 12 Unsolicited Messages Buffer Management Functions Function Description acsc_OpenMessageBuffer Opens an unsolicited messages buffer. acsc_CloseMessageBuffer Closes an unsolicited messages buffer. acsc_GetSingleMessage Retrieves single message or exits by time-out acsc_GetMessage Retrieves unsolicited messages from the buffer. 4.8.1 acsc_OpenMessageBuffer Description The function opens an unsolicited messages buffer. Syntax LP_ACSC_HISTORYBUFFER acsc_OpenMessageBuffer(HANDLE Handle, int Size) Arguments Handle Communication handle Size Required size of the buffer in bytes Return Value The function returns pointer to ACSC_HISTORYBUFFER structure. If the buffer cannot be allocated, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function allocates a buffer that stores unsolicited messages from the controller. Unsolicited messages are messages that the controller sends on its own initiative and not as a response to command. For example, the disp command in an ACSPL+ program forces the controller to send an unsolicited message. 31 January 2009 95 C Library Functions
- 110. C Library Reference Version 6.50 Programmer’s Guide Only one message buffer can be open for each communication handle. If the message buffer has been open, the library separates unsolicited messages from the controller responses and stores them in the message buffer. In this case, the acsc_Receive function retrieves only the controller replies, and the acsc_GetMessage function retrieves unsolicited messages. If the message buffer is not open, acsc_Receive retrieves both replies and unsolicited messages. If the user application does not call acsc_Receive or acsc_GetMessage and uses only acsc_Transaction and acsc_Command, the unsolicited messages are discarded. The message buffer works as a FIFO buffer: acsc_GetMessage extracts the earliest message stored in the buffer. If acsc_GetMessage extracts the messages slower than the controller produces them, buffer overflow can occur, and some messages will be lost. Generally, the greater the buffer, the less likely is buffer overflow to occur. Example LP_ACSC_HISTORYBUFFER lpMessageBuf = acsc_OpenMessageBuffer( Handle, // communication handle 10000 // size of the buffer ); if (!lpMessageBuf) { printf("opening unsolicited messages buffer error: %dn", acsc_GetLastError()); } 4.8.2 acsc_CloseMessageBuffer Description The function closes the messages buffer and discards all stored unsolicited messages. Syntax int acsc_CloseMessageBuffer(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 96 C Library Functions
- 111. C Library Reference Version 6.50 Programmer’s Guide Comments The function closes the message buffer and releases the used memory. All unsolicited messages stored in the buffer are discarded. Example if (!acsc_CloseMessageBuffer(Handle)) { printf("closing unsolicited messages buffer error: %dn", acsc_GetLastError()); } 4.8.3 acsc_GetSingleMessage Description The function retrieves single unsolicited message from the buffer. This function only works if you setup a buffer using acsc_OpenMessageBuffer. If there is no message in the buffer the function waits till the message arrives or time out expires. Syntax int acsc_GetSingleMessage (HANDLE Handle, char *Message,int Count,int *Length,int Timeout) Arguments Handle Communication handle Message Pointer to the buffer that receives unsolicited messages, it should be at least 1K. Count Size of the buffer to which the Message argument points. Length The actual length of the message Timeout Timeout in milliseconds Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 97 C Library Functions
- 112. C Library Reference Version 6.50 Programmer’s Guide Comments The function retrieves a single unsolicited message from the message buffer. If no unsolicited message is received, the function waits until a message arrives. If message arrives, Length will contain the received message length. If the timeout expires, the function exits with the ACSC_TIMEOUT error. Example int L; char Buf[10000]; if (!acsc_GetSingleMessage(Handle, // communication handle Buf, // pointer to the buffer that // receives unsolicited messages 10000 //Size of the buffer &L, // number of characters that were actually received 1000 // Wait for 1 second till a message arrives )) { printf("getting unsolicited message error: %dn", acsc_GetLastError()); } 4.8.4 acsc_GetMessage Description The function retrieves unsolicited messages from the buffer. This function only works if you setup a buffer using acsc_OpenMessageBuffer. If no message buffer is open, these messages will be returned by acsc_Receive. Syntax int acsc_GetMessage(HANDLE Handle, char* Buf, int Count, int* Received, BOOL bClear) Arguments Handle Communication handle Buf Pointer to the buffer that receives unsolicited messages Count Size of the buffer in bytes Received Number of characters that were actually received 31 January 2009 98 C Library Functions
- 113. C Library Reference Version 6.50 Programmer’s Guide bClear If TRUE, the function clears the contents of the unsolicited messages buffer after retrieving the message. If FALSE, the unsolicited messages buffer is not cleared. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves all stored unsolicited messages from the message buffer. The function always returns immediately. If no, unsolicited message is received, the function assigns zero to the Received variable. Parameter Count specifies the buffer size. If a received message contains more than Count characters, the function transfers to buffer only Count characters, assigns Received with Count value and returns non-zero. The remaining characters of the message are removed from the message buffer. If the Count is equal to or more than the length of the message, the function transfers the whole message to buffer and assigns variable Received with a number of characters that were actually transferred. Example int Received; char Buf[10000]; if (!acsc_GetMessage( Handle, // communication handle Buf, // pointer to the buffer that // receives unsolicited messages 10000, // size of this buffer &Received, // number of characters that were // actually received TRUE // clear contents of the // unsolicited messages buffer )) { printf("getting unsolicited message error: %dn", acsc_GetLastError()); } 31 January 2009 99 C Library Functions
- 114. C Library Reference Version 6.50 Programmer’s Guide 4.9 Log File Management Functions The Log File Management functions are: Table 13 Log File Management Functions Function Description acsc_SetLogFileOptions Sets log file options. acsc_OpenLogFile Opens a log file. acsc_CloseLogFile Closes a log file. acsc_WriteLogFile Writes to a log file. acsc_FlushLogFile Flushes the User-Mode Driver (UMD) internal binary buffer to a specified text file from the C Library application. 4.9.1 acsc_SetLogFileOptions Description The function sets the log file options. Syntax acsc_SetLogFileOptions(HANDLE Handle,ACSC_LOG_DETALIZATION_LEVEL Detalization, ACSC_LOG_DATA_PRESENTATION Presentation) Arguments Handle Communication handle Detalization This parameter may be one of the following: • Minimum -Value 0: Only communication traffic will be logged. • Medium - Value 1: Communication traffic and some internal C Lib process data will be logged. • Maximum -Value 2: Communication traffic and all internal process data will be logged. Presentation This parameter may be one of the following: • Compact -Value 0: No more than the first ten bytes of each data string will be logged. Non-printing characters will be represented in [Hex ASCII code]. • Formatted - Value 1: All the binary data will be logged. Non- printing characters will be represented in [Hex ASCII code]. • Full -Value 2: All the binary data will be logged as is. 31 January 2009 100 C Library Functions
- 115. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function configures the log file options. The function may be called before or after the log file is opened. Example //Example of function acsc_SetLogFileOptions acsc_SetLogFileOptions(Handle,Maximum,Formatted); 4.9.2 acsc_OpenLogFile Description The function opens log file. Syntax int acsc_OpenLogFile(HANDLE Handle, char* FileName) Arguments Handle Communication handle FileName Pointer to the null-terminated string contained name or path of the log file. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 101 C Library Functions
- 116. C Library Reference Version 6.50 Programmer’s Guide Comments The function opens a binary file that stores all communication history. Only one log file can be open for each communication handle. If the log file has been open, the library writes all incoming and outgoing messages to the specified file. The messages are written to the file in binary format, i.e., exactly as they are received and sent, including all service bytes. Unlike the history buffer, the log file cannot be read within the library. The main usage of the log file is for debug purposes. Example if (!acsc_OpenLogFile(Handle, "acs_comm.log")) { printf("opening log file error: %dn", acsc_GetLastError()); } 4.9.3 acsc_CloseLogFile Description The function closes the log file. Syntax int acsc_CloseLogFile(HANDLE Handle) Arguments Handle Communication handle Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments An application must always call the acsc_CloseLogFile before it exits. Otherwise, the data written to the file might be lost. 31 January 2009 102 C Library Functions
- 117. C Library Reference Version 6.50 Programmer’s Guide Example if (!acsc_CloseLogFile(Handle)) { printf("closing log file error: %dn", acsc_GetLastError()); } 4.9.4 acsc_WriteLogFile Description The function writes to log file. Syntax int acsc_WriteLogFile(HANDLE Handle, char* Buf, int Count) Arguments Handle Communication handle Buf Pointer to the buffer that contains the string to be written to log file. Count Number of characters in the buffer Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes data from a buffer to log file. Note The log file has to have been opened previously using: acsc_OpenLogFile 31 January 2009 103 C Library Functions
- 118. C Library Reference Version 6.50 Programmer’s Guide Example char* str = “Test string”; if (!acsc_WriteLogFile(Handle, // communication handle str, // string to be written strlen(str) // length of this string )) { printf("error while writing to log file: %dn", acsc_GetLastError()); } 4.9.5 acsc_FlushLogFile Description This function allows flushing the User-Mode Driver (UMD) internal binary buffer to a specified text file from the C Library application. Syntax acsc_FlushLogFile(char*filename) Arguments filename String that specifies the file name. Note Extended error information can be obtained by calling acsc_GetLastError. Comments If Continuous Log is active, the function will fail. if (!acscFlushLogFile( filename)) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 104 C Library Functions
- 119. C Library Reference Version 6.50 Programmer’s Guide 4.10 System Configuration Functions System Configuration functions are: Table 14 System Configuration Functions Function Description acsc_SetConf The function writes system configuration data. acsc_GetConf The function reads system configuration data. 4.10.1 acsc_SetConf Description The function writes system configuration data. Syntax int acsc_SetConf(HANDLE Handle, int Key, int Index, double Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Key Configuration key, see Configuration Keys, that specifies the configured feature. Assigns value of key argument in ACSPL+ SetConf function. Index Specifies corresponding axis or buffer number. Assigns value of index argument in ACSPL+ SetConf function. Value Value to write to specified key. Assigns value of value argument in ACSPL+ SetConf function. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 105 C Library Functions
- 120. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes system configuration data. The Key parameter specifies the feature number and the Index parameter defines axis or buffer to which it should be applied. Use ACSC_CONF_XXX constants in the value field. For complete details of system configuration see the description of the SetConf function in the SPiiPlus ACSPL+ Programmer’s Guide. Example // example of the waiting call of acsc_Track if (!acsc_SetConf(Handle, // communication handle ACSC_CONF_DIGITAL_SOURCE_KEY,// 205 ACSC_AXIS_X, // of the axis X 0, NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.10.2 acsc_GetConf Description The function reads system configuration data. Syntax int acsc_GetConf(HANDLE Handle, int Key, int Index, double *Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Key Configuration Key, see Configuration Keys, specifies the configured feature. Assigns value of key argument in ACSPL+ GetConf function. Index Specifies corresponding axis or buffer number. Assigns value of index argument in ACSPL+ GetConf function. Value Receives the configuration data 31 January 2009 106 C Library Functions
- 121. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function reads system configuration data. The Key parameter specifies the feature number and the Index parameter defines axis or buffer to which it should be applied. For detailed description of system configuration see “SPiiPlus ACSPL+ Programmer’s Guide” GetConf definition. Example // example of the waiting call of acsc_Track if (!acsc_GetConf(Handle, // communication handle ACSC_CONF_DIGITAL_SOURCE_KEY, // 205 ACSC_AXIS_X, // of the axis X &Value, NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 107 C Library Functions
- 122. C Library Reference Version 6.50 Programmer’s Guide 4.11 Setting and Reading Motion Parameters Functions The Setting and Reading Motion Parameters functions are: Table 15 Setting and Reading Motion Parameters Functions Function Description acsc_SetVelocity Defines a value of motion velocity. acsc_GetVelocity Retrieves a value of motion velocity. acsc_SetAcceleration Defines a value of motion acceleration. acsc_GetAcceleration Retrieves a value of motion acceleration. acsc_SetDeceleration Defines a value of motion deceleration. acsc_GetDeceleration Retrieves a value of motion deceleration. acsc_SetJerk Defines a value of motion jerk. acsc_GetJerk Retrieves a value of motion jerk. acsc_SetKillDeceleration Defines a value of kill deceleration. acsc_GetKillDeceleration Retrieves a value of kill deceleration. acsc_SetVelocityImm Defines a value of motion velocity. Unlike acsc_SetVelocity, the function has immediate effect on any executed and planned motion. acsc_SetAccelerationImm Defines a value of motion acceleration. Unlike acsc_SetAcceleration, the function has immediate effect on any executed and planned motion. acsc_SetDecelerationImm Defines a value of motion deceleration. Unlike acsc_SetDeceleration, the function has immediate effect on any executed and planned motion. acsc_SetJerkImm Defines a value of motion jerk. Unlike acsc_SetJerk, the function has an immediate effect on any executed and planned motion. acsc_SetKillDecelerationImm Defines a value of kill deceleration. Unlike acsc_SetKillDeceleration, the function has immediate effect on any executed and planned motion. acsc_SetFPosition Assigns a current value of feedback position. acsc_GetFPosition Retrieves a current value of motor feedback position. acsc_SetRPosition Assigns a current value of reference position. acsc_GetRPosition Retrieves a current value of reference position. acsc_GetFVelocity Retrieves a current value of motor feedback velocity. acsc_GetRVelocity Retrieves a current value of reference velocity. 31 January 2009 108 C Library Functions
- 123. C Library Reference Version 6.50 Programmer’s Guide 4.11.1 acsc_SetVelocity Description The function defines a value of motion velocity. Syntax int acsc_SetVelocity(HANDLE Handle, int Axis, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see Axis Definitions. Velocity The value specifies required motion velocity. The value will be used in the subsequent motions except for the master-slave motions and the motions activated with the ACSC_AMF_VELOCITY flag. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the 31 January 2009 109 C Library Functions
- 124. C Library Reference Version 6.50 Programmer’s Guide value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects the motions initiated after the function call. The function has no effect on any motion that was started or planned before the function call. To change velocity of an executed or planned motion, use the acsc_SetVelocityImm function. The function has no effect on the master-slave motions and the motions activated with the ACSC_AMF_VELOCITY flag. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetVelocity if (!acsc_SetVelocity( Handle, // communication handle ACSC_AXIS_X, // axis X 10000, // velocity value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.2 acsc_GetVelocity Description The function retrieves a value of motion velocity. Syntax int acsc_GetVelocity(HANDLE Handle, int Axis, double* Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see Axis Definitions. Velocity Pointer to the variable that receives the value of motion velocity. 31 January 2009 110 C Library Functions
- 125. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the value of the motion velocity. The retrieved value is a value defined by a previous call of the acsc_SetVelocity function, or the default value if the function was not called before. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Velocity and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetVelocity double Velocity; if (!acsc_GetVelocity(Handle, // communication handle ACSC_AXIS_X, // axis X &Velocity, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.3 acsc_SetAcceleration Description The function defines a value of motion acceleration. 31 January 2009 111 C Library Functions
- 126. C Library Reference Version 6.50 Programmer’s Guide Syntax int acsc_SetAcceleration(HANDLE Handle, int Axis, double Acceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y corresponds to Y, etc. For the full list of the axis constants, see Axis Definitions. Acceleration The value specifies required motion acceleration. The value will be used in the subsequent motions except the master-slave motions. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects the motions initiated after the function call. The function has no effect on any motion that was started or planned before the function call. To change acceleration of an executed or planned motion, use the acsc_SetAccelerationImm function. 31 January 2009 112 C Library Functions
- 127. C Library Reference Version 6.50 Programmer’s Guide The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetAcceleration if (!acsc_SetAcceleration(Handle, // communication handle ACSC_AXIS_X, // axis X 100000, // acceleration value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.4 acsc_GetAcceleration Description The function retrieves a value of motion acceleration. Syntax int acsc_GetAcceleration(HANDLE Handle, int Axis, double* Acceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, “Axis Definitions” on Page 378. Acceleration Pointer to the variable that receives the value of motion acceleration. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 113 C Library Functions
- 128. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the value of the motion acceleration. The retrieved value is a value defined by a previous call of the acsc_SetAcceleration function, or the default value if the function was not called before. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Acceleration and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetAcceleration double Acceleration; if (!acsc_GetAcceleration( Handle, // communication handle ACSC_AXIS_X, // axis X &Acceleration, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.5 acsc_SetDeceleration Description The function defines a value of motion deceleration. Syntax int acsc_SetDeceleration(HANDLE Handle, int Axis, double Deceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 114 C Library Functions
- 129. C Library Reference Version 6.50 Programmer’s Guide Deceleration The value specifies a required motion deceleration. The value will be used in the subsequent motions except the master-slave motions. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects the motions initiated after the function call. The function has no effect on any motion that was started or planned before the function call. To change deceleration of an executed or planned motion, use the acsc_SetDecelerationImm function. The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 115 C Library Functions
- 130. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_SetDeceleration if (!acsc_SetDeceleration( Handle, // communication handle ACSC_AXIS_X, // axis X 100000, // deceleration value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.6 acsc_GetDeceleration Description The function retrieves a value of motion deceleration. Syntax int acsc_GetDeceleration(HANDLE Handle, int Axis, double* Deceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378 Deceleration Pointer to the variable that receives the value of motion deceleration. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 116 C Library Functions
- 131. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the value of the motion deceleration. The retrieved value is a value defined by a previous call of the acsc_SetDeceleration function, or the default value if the function was not previously called. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Deceleration and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetDeceleration double Deceleration; if (!acsc_GetDeceleration( Handle, // communication handle ACSC_AXIS_X, // axis X &Deceleration, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.7 acsc_SetJerk Description The function defines a value of motion jerk. Syntax int acsc_SetJerk(HANDLE Handle, int Axis, double Jerk, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Jerk The value specifies a required motion jerk. The value will be used in the subsequent motions except for the master-slave motions. 31 January 2009 117 C Library Functions
- 132. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects the motions initiated after the function call. The function has no effect on any motion that was started or planned before the function call. To change the jerk of an executed or planned motion, use the acsc_SetJerkImm function. The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetJerk if (!acsc_SetJerk( Handle, // communication handle ACSC_AXIS_X, // axis X 1000000, // jerk value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 118 C Library Functions
- 133. C Library Reference Version 6.50 Programmer’s Guide 4.11.8 acsc_GetJerk Description The function retrieves a value of motion jerk. Syntax int acsc_GetJerk(HANDLE Handle, int Axis, double* Jerk, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Jerk Pointer to the variable that receives the value of motion jerk. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the value of the motion jerk. The retrieved value is a value defined by a previous call of the acsc_SetJerk function, or the default value if the function was not called before. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Jerk and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 119 C Library Functions
- 134. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetJerk double Jerk; if (!acsc_GetJerk( Handle, // communication handle ACSC_AXIS_X, // axis X &Jerk, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.9 acsc_SetKillDeceleration Description The function defines a value of motion kill deceleration. Syntax int acsc_SetKillDeceleration(HANDLE Handle, int Axis, double KillDeceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. KillDeceleration The value specifies a required motion kill deceleration. The value will be used in the subsequent motions. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 120 C Library Functions
- 135. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects the motions initiated after the function call. The function has no effect on any motion that was started or planned before the function call. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetKillDeceleration double KillDeceleration; if (!acsc_SetKillDeceleration( Handle, // communication handle ACSC_AXIS_X, // axis X 100000, // kill deceleration value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.10 acsc_GetKillDeceleration Description The function retrieves a value of motion kill deceleration. Syntax int acsc_GetKillDeceleration(HANDLE Handle, int Axis, double* KillDeceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 121 C Library Functions
- 136. C Library Reference Version 6.50 Programmer’s Guide Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. KillDeceleration Pointer to the variable that receives the value of motion kill deceleration. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the value of the motion kill deceleration. The retrieved value is a value defined by a previous call of the acsc_SetKillDeceleration function, or the default value if the function was not called before. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the KillDeceleration and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 122 C Library Functions
- 137. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetKillDeceleration double KillDeceleration; if (!acsc_GetKillDeceleration(Handle, // communication handle ACSC_AXIS_X, // axis X &KillDeceleration, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.11 acsc_SetVelocityImm Description The function defines a value of motion velocity. Unlike acsc_SetVelocity, the function has immediate effect on any executed or planned motion. Syntax int acsc_SetVelocityImm(HANDLE Handle, int Axis, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Velocity The value specifies required motion velocity. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 123 C Library Functions
- 138. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects: • The currently executed motion. The controller provides a smooth transition from the instant current velocity to the specified new value. • The waiting motions that were planned before the function call. • The motions that will be commanded after the function call. The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetVelocityImm if (!acsc_SetVelocityImm(Handle, // communication handle ACSC_AXIS_X, // axis X 10000, // velocity value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.12 acsc_SetAccelerationImm Description The function defines a value of motion acceleration. Unlike acsc_SetAcceleration, the function has immediate effect on any executed and planned motion. Syntax int acsc_SetAccelerationImm(HANDLE Handle, int Axis, double Acceleration, ACSC_WAITBLOCK* Wait) 31 January 2009 124 C Library Functions
- 139. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see Axis Definitions. Acceleration The value specifies required motion acceleration. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects: • The currently executed motion. • The waiting motions that were planned before the function call. • The motions that will be commanded after the function call. The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 125 C Library Functions
- 140. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_SetAccelerationImm if (!acsc_SetAccelerationImm(Handle, // communication handle ACSC_AXIS_X, // axis X 100000, // acceleration value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.13 acsc_SetDecelerationImm Description The function defines a value of motion deceleration. Unlike acsc_SetDeceleration, the function has immediate effect on any executed and planned motion. Syntax int acsc_SetDecelerationImm(HANDLE Handle, int Axis, double Deceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Deceleration The value specifies required motion deceleration. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 126 C Library Functions
- 141. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects: • The currently executed motion. • The waiting motions that were planned before the function call. • The motions that will be commanded after the function call. The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetDecelerationImm if (!acsc_SetDecelerationImm(Handle, // communication handle ACSC_AXIS_X, // axis X 100000, // deceleration value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.14 acsc_SetJerkImm Description The function defines a value of motion jerk. Unlike acsc_SetJerk, the function has immediate effect on any executed and planned motion. Syntax int acsc_SetJerkImm(HANDLE Handle, int Axis, double Jerk, ACSC_WAITBLOCK* Wait) 31 January 2009 127 C Library Functions
- 142. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Jerk The value specifies required motion jerk. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects: • The currently executed motion. • The waiting motions that were planned before the function call. • The motions that will be commanded after the function call. The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 128 C Library Functions
- 143. C Library Reference Version 6.50 Programmer’s Guide Example / example of the waiting call of acsc_SetJerkImm if (!acsc_SetJerkImm( Handle, // communication handle ACSC_AXIS_X, // axis X 1000000, // jerk value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.15 acsc_SetKillDecelerationImm Description The function defines a value of motion kill deceleration. Unlike acsc_SetKillDeceleration, the function has an immediate effect on any executed and planned motion. Syntax int acsc_SetKillDecelerationImm(HANDLE Handle, int Axis, double Deceleration, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. KillDeceleration The value specifies the required motion deceleration. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 129 C Library Functions
- 144. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the specified value to the controller. One value can be specified for each axis. A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the value of the leading axis. The leading axis is an axis specified first in the motion command. The function affects: • The currently executed motion • The waiting motions that were planned before the function call • The motions that will be commanded after the function call The function has no effect on the master-slave motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetKillDecelerationImm if (!acsc_SetKillDecelerationImm(Handle, // communication handle ACSC_AXIS_X, // axis X 100000, // kill deceleration value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.16 acsc_SetFPosition Description The function assigns a current value of feedback position. Syntax int acsc_SetFPosition(HANDLE Handle, int Axis, double FPosition, ACSC_WAITBLOCK* Wait) 31 January 2009 130 C Library Functions
- 145. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. FPosition The value specifies the current value of feedback position. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function assigns a current value to the feedback position. No physical motion occurs. The motor remains in the same position; only the internal controller offsets are adjusted so that the periodic calculation of the feedback position will provide the required results. For more information see the explanation of the SET command in the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 131 C Library Functions
- 146. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_SetFPosition if (!acsc_SetFPosition( Handle, // communication handle ACSC_AXIS_X, // axis X 0, // required feedback position NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.17 acsc_GetFPosition Description The function retrieves an instant value of the motor feedback position. Syntax int acsc_GetFPosition(HANDLE Handle, int Axis, double* FPosition, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. FPosition Pointer to a variable that receives the instant value of the motor feedback position. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 132 C Library Functions
- 147. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves an instant value of the motor feedback position. The feedback position is a measured position of the motor transferred to user units. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the FPosition and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetFPosition double FPosition; if (!acsc_GetFPosition( Handle, // communication handle ACSC_AXIS_X, // axis X &FPosition, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.18 acsc_SetRPosition Description The function assigns a current value of reference position. Syntax int acsc_SetRPosition(HANDLE Handle, int Axis, double RPosition, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Rposition The value specifies the current value of reference position. 31 January 2009 133 C Library Functions
- 148. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function assigns a current value to the reference position. No physical motion occurs. The motor remains in the same position; only the internal controller offsets are adjusted so that the periodic calculation of the reference position will provide the required results. For more information see explanation of the SET command in the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetRPosition if (!acsc_SetRPosition( Handle, // communication handle ACSC_AXIS_X, // axis X 0, // required reference position NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); 31 January 2009 134 C Library Functions
- 149. C Library Reference Version 6.50 Programmer’s Guide 4.11.19 acsc_GetRPosition Description The function retrieves an instant value of the motor reference position. Syntax int acsc_GetRPosition(HANDLE Handle, int Axis, double* RPosition, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Rposition Pointer to a variable that receives the instant value of the motor reference position. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves an instant value of the motor reference position. The reference position is a value calculated by the controller as a reference for the motor. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the RPosition and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 135 C Library Functions
- 150. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetRPosition double RPosition; if (!acsc_GetRPosition( Handle, // communication handle ACSC_AXIS_X, // axis X &RPosition, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.20 acsc_GetFVelocity Description The function retrieves an instant value of the motor feedback velocity. Unlike acsc_GetVelocity, the function retrieves the actually measured velocity and not the required value. Syntax int acsc_GetFVelocity(HANDLE Handle, int Axis, double* FVelocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. FVelocity Pointer to a variable that receives the instant value of the motor feedback velocity. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 136 C Library Functions
- 151. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves an instant value of the motor feedback velocity. The feedback velocity is a measured velocity of the motor transferred to user units. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the FVelocity and Wait items until a call to the acsc_WaitForAsyncCall function. Example / example of the waiting call of acsc_GetFVelocity double FVelocity; if (!acsc_GetFVelocity( Handle, // communication handle ACSC_AXIS_X, // axis X &FVelocity, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.11.21 acsc_GetRVelocity Description The function retrieves an instant value of the motor reference velocity. Syntax int acsc_GetRVelocity(HANDLE Handle, int Axis, double* RVelocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 137 C Library Functions
- 152. C Library Reference Version 6.50 Programmer’s Guide RVelocity Pointer to a variable that receives the instant value of the motor reference velocity. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves an instant value of the motor reference velocity. The reference velocity is a value calculated by the controller in the process of motion generation. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the RVelocity and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetRVelocity double RVelocity; if (!acsc_GetRVelocity( Handle, // communication handle ACSC_AXIS_X, // axis X &RVelocity, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 138 C Library Functions
- 153. C Library Reference Version 6.50 Programmer’s Guide 4.12 Axis/Motor Management Functions The Axis/Motor Management functions are: Table 16 Axis/Motor Management Functions Function Description acsc_Commut Initiates a motor commutation. acsc_Enable Activates a motor. acsc_EnableM Activates several motors. acsc_Disable Shuts off a motor. acsc_DisableAll Shuts off all motors. acsc_DisableExt Shuts off a motor and defines the disable reason. acsc_DisableM Shuts off several motors. acsc_Group Creates a coordinate system for a multi-axis motion. acsc_Split Breaks down an axis group created before. acsc_SplitAll Breaks down all axis groups created before. 4.12.1 acsc_Commut Description This function initiates a motor commutation. Syntax int acsc_Commut(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Axes Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y - to Y, etc. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 139 C Library Functions
- 154. C Library Reference Version 6.50 Programmer’s Guide Return Values If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Extended error information can be obtained by calling acsc_GetLastError. Comments The function activates a motor. After the activation, the motor begins to follow the reference and physical motion is available. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Commut if (!acsc_Commut(Handle, // communication handle ACSC_AXIS_X,// commute of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.2 acsc_Enable Description The function activates a motor. Syntax int acsc_Enable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see Axis Definitions. 31 January 2009 140 C Library Functions
- 155. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function activates a motor. After the activation, the motor begins to follow the reference and physical motion is available. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Enable if (!acsc_Enable( Handle, // communication handle ACSC_AXIS_X, // enable of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.3 acsc_EnableM Description The function activates several motors. 31 January 2009 141 C Library Functions
- 156. C Library Reference Version 6.50 Programmer’s Guide Syntax int acsc_EnableM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see Axis Definitions. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function activates several motors. After the activation, the motors begin to follow the corresponding reference and physical motions for the specified motors are available. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 142 C Library Functions
- 157. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_EnableM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 }; if (!acsc_EnableM(Handle, // communication handle Axes, // enable of axes XYZT NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.4 acsc_Disable Description The function shuts off a motor. Syntax int acsc_Disable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see Axis Definitions. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the acsc_WaitForAsyncCall function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 143 C Library Functions
- 158. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function shuts off a motor. After shutting off the motor cannot follow the reference and remains at idle. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Disable if (!acsc_Disable( Handle, // communication handle ACSC_AXIS_X, // disable of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.5 acsc_DisableAll Description The function shuts off all motors. Syntax int acsc_DisableAll(HANDLE Handle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 144 C Library Functions
- 159. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function shuts off all motors. After the shutting off none of motors can follow the corresponding, reference and all motors remain idle. If no motors are currently enabled, the function has no effect. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_DisableAll if (!acsc_DisableAll(Handle, NULL)) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.6 acsc_DisableExt Description The function shuts off a motor and defines the disable reason. Syntax int acsc_DisableExt(HANDLE Handle, int Axis,int Reason, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 145 C Library Functions
- 160. C Library Reference Version 6.50 Programmer’s Guide Reason Integer number that defines the reason of disable. The specified value is stored in the MERR variable in the controller and so modifies the state of the disabled motor. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function shuts off a motor. After shutting off the motor cannot follow the reference and remains at idle. If Reason specifies one of the available motor termination codes, the state of the disabled motor will be identical to the state of the motor disabled for the corresponding fault. This provides an enhanced implementation of user-defined fault response. If the second parameter specifies an arbitrary number, the motor state will be displayed as “Kill/disable reason: <number> - customer code. This provides ability to separate different DISABLE commands in the application. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 146 C Library Functions
- 161. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_DisableExt #define MY_MOTOR_FAULT 10 if (!acsc_DisableExt(Handle, // communication handle ACSC_AXIS_X, // disable of axis X MY_MOTOR_FAULT, // internal customer code NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.7 acsc_DisableM Description The function shuts off several specified motors. Syntax int acsc_DisableM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 147 C Library Functions
- 162. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function shuts off several motors. After the shutting off, the motors cannot follow the corresponding reference and remain idle. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_DisableM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 }; if (!acsc_DisableM( Handle, // communication handle Axes, // disable of axes XYZT NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.8 acsc_Group Description The function creates a coordinate system for a multi-axis motion. Syntax int acsc_Group(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 148 C Library Functions
- 163. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function creates a coordinate system for a multi-axis motion. The first element of the Axes array specifies the leading axis. The motion parameters of the leading axis become the default motion parameters for the group. An axis can belong to only one group at a time. If the application requires restructuring the axes, it must split the existing group and only then create the new one. To split the existing group, use acsc_Split function. To split all existing groups, use the acsc_SplitAll function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Group int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 }; if (!acsc_Group( Handle, // communication handle Axes, // create group of axes XYZT NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 149 C Library Functions
- 164. C Library Reference Version 6.50 Programmer’s Guide 4.12.9 acsc_Split Description The function breaks down an axis group created before. Syntax int acsc_Split(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function breaks down an axis group created before by the acsc_Group function. The Axes parameter must specify the same axes as for the acsc_Group function that created the group. After the splitting up the group no longer exists. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or 31 January 2009 150 C Library Functions
- 165. C Library Reference Version 6.50 Programmer’s Guide delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Split int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C, ACSC_AXIS_D, -1 }; if (!acsc_Split( Handle, // communication handle Axes, // split the group of axes XYZTABCD NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.12.10 acsc_SplitAll Description The function breaks down all axis groups created before. Syntax int acsc_SplitAll(HANDLE Handle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 151 C Library Functions
- 166. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function breaks down all axis groups created before by the acsc_Group function. The application may call this function to ensure that no axes are grouped. If no groups are currently existed, the function has no effect. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SplitAll if (!acsc_SplitAll(Handle, NULL)) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13 Motion Management Functions The Motion Management functions are: Table 17 Motion Management Functions (page 1 of 2) Function Description acsc_Go Starts up a motion that is waiting in the specified motion queue. acsc_GoM Synchronously starts up several motions that are waiting in the specified motion queues. acsc_Halt Terminates a motion using the full deceleration profile. acsc_HaltM Terminates several motions using the full deceleration profile. acsc_Kill Terminates a motion using the reduced deceleration profile. acsc_KillAll Terminates all currently executed motions. acsc_KillM Terminates several motions using the reduced deceleration profile. acsc_KillExt Terminates a motion using reduced deceleration profile and defines the kill reason. 31 January 2009 152 C Library Functions
- 167. C Library Reference Version 6.50 Programmer’s Guide Table 17 Motion Management Functions (page 2 of 2) Function Description acsc_Break Terminates a motion immediately and provides a smooth transition to the next motion. acsc_BreakM Terminates several motions immediately and provides a smooth transition to the next motions. 4.13.1 acsc_Go Description The function starts up a motion waiting in the specified motion queue. Syntax int acsc_Go(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 153 C Library Functions
- 168. C Library Reference Version 6.50 Programmer’s Guide Comments A motion that was planned with ACSC_AMF_WAIT flag does not start until the acsc_Go function is executed. Being planned, a motion waits in the appropriate motion queue. Each axis has a separate motion queue. A single-axis motion waits in the motion queue of the corresponding axis. A multi-axis motion waits in the motion queue of the leading axis. The leading axis is an axis specified first in the motion command. The acsc_Go function initiates the motion waiting in the motion queue of the specified axis. If no motion waits in the motion queue, the function has no effect. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Go if (!acsc_Go(Handle, // communication handle ACSC_AXIS_X, // start up the motion of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13.2 acsc_GoM Description The function synchronously starts up several motions that are waiting in the specified motion queues. Syntax int acsc_GoM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 154 C Library Functions
- 169. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments A motion that was planned with ACSC_AMF_WAIT flag does not start until the acsc_GoM function is executed. After being planned, a motion waits in the appropriate motion queue. Each axis has a separate motion queue. A single-axis motion waits in the motion queue of the corresponding axis. A multi-axis motion waits in the motion queue of the leading axis. The leading axis is an axis specified first in the motion command. The acsc_GoM function initiates the motions waiting in the motion queues of the specified axes. If no motion waits in one or more motion queues, the corresponding axes are not affected. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GoM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 }; if (!acsc_GoM( Handle, // communication handle Axes, // start up the motion of axes XYZT NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 155 C Library Functions
- 170. C Library Reference Version 6.50 Programmer’s Guide 4.13.3 acsc_Halt Description The function terminates a motion using the full deceleration profile. Syntax int acsc_Halt(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates the executed motion that involves the specified axis. The terminated motion can be either single-axis or multi-axis. Any other motion waiting in the corresponding motion queue is discarded and will not be executed. If no executed motion involves the specified axis, the function has no effect. The terminated motion finishes using the full third-order deceleration profile and the motion deceleration value. 31 January 2009 156 C Library Functions
- 171. C Library Reference Version 6.50 Programmer’s Guide If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Halt if (!acsc_Halt(Handle, // communication handle ACSC_AXIS_X, // terminate the motion of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13.4 acsc_HaltM Description The function terminates several motions using the full deceleration profile. Syntax int acsc_HaltM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 157 C Library Functions
- 172. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates all executed motions that involve the specified axes. The terminated motions can be either single-axis or multi-axis. All other motions waiting in the corresponding motion queues are discarded and will not be executed. If no executed motion involves a specified axis, the function has no effect on the corresponding axis. The terminated motions finish using the full third-order deceleration profile and the motion deceleration values. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_HaltM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 }; if (!acsc_HaltM( Handle, // communication handle Axes, // terminate the motion of axes //XYZTABCD NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13.5 acsc_Kill Description The function terminates a motion using reduced deceleration profile. Syntax int acsc_Kill(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 158 C Library Functions
- 173. C Library Reference Version 6.50 Programmer’s Guide Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates the executed motion that involves the specified axis. The terminated motion can be either single-axis or multi-axis. Any other motion waiting in the corresponding motion queue is discarded and will not be executed. If no executed motion involves the specified axis, the function has no effect. The terminated motion finishes with the reduced second-order deceleration profile and the kill deceleration value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Kill if (!acsc_Kill(Handle, // communication handle ACSC_AXIS_X, // terminate the motion of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 159 C Library Functions
- 174. C Library Reference Version 6.50 Programmer’s Guide 4.13.6 acsc_KillAll Description The function terminates all currently executed motions. Syntax int acsc_KillAll(HANDLE Handle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates all currently executed motions. Any other motion waiting in any motion queue is discarded and will not be executed. If no motion is currently executed, the function has no effect. The terminated motions finish with the reduced second-order deceleration profile and the kill deceleration values. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 160 C Library Functions
- 175. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_KillAll if (!acsc_KillAll(Handle, NULL)) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13.7 acsc_KillM Description The function terminates several motions using reduced deceleration profile. Syntax int acsc_KillM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 161 C Library Functions
- 176. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates all executed motions that involve the specified axes. The terminated motions can be either single-axis or multi-axis. All other motions waiting in the corresponding motion queues are discarded and will not be executed. If no executed motion involves a specified axis, the function has no effect on the corresponding axis. The terminated motions finish with the reduced second-order deceleration profile and the kill deceleration values. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_KillM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, -1 }; if (!acsc_KillM( Handle, // communication handle Axes, // terminate the motion of axes XYZT NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13.8 acsc_KillExt Description The function terminates a motion using reduced deceleration profile and defines the kill reason. Syntax int acsc_KillExt(HANDLE Handle, int Axis, int Reason,ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 162 C Library Functions
- 177. C Library Reference Version 6.50 Programmer’s Guide Reason Integer number that defines the reason of kill. The specified value is stored in the MERR variable in the controller and so modifies the state of the killed motor. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates the executed motion that involves the specified axis. The terminated motion can be either single-axis or multi-axis. Any other motion waiting in the corresponding motion queue is discarded and will not be executed. If no executed motion involves the specified axis, the function has no effect. The terminated motion finishes with the reduced second-order deceleration profile and the kill deceleration value. If Reason specifies one of the available motor termination codes, the state of the killed motor will be identical to the state of the motor killed for the corresponding fault. This provides an enhanced implementation of user-defined fault response. If the second parameter specifies an arbitrary number, the motor state will be displayed as “Kill/disable reason: <number> - customer code. This provides ability to separate different KILL commands in the application. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the KillDeceleration and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 163 C Library Functions
- 178. C Library Reference Version 6.50 Programmer’s Guide Example / example of the waiting call of acsc_KillExt #define MY_MOTOR_FAULT 10 if (!acsc_KillExt( Handle, // communication handle ACSC_AXIS_X, // terminate the motion of // axis X MY_MOTOR_FAULT, // internal customer code NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.13.9 acsc_Break Description The function terminates a motion immediately and provides a smooth transition to the next motion. Syntax int acsc_Break(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function acsc_WaitForAsyncCall returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 164 C Library Functions
- 179. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates the executed motion that involves the specified axis only if the next motion is waiting in the corresponding motion queue. The terminated motion can be either single-axis or multi-axis. If the motion queue contains no waiting motion, the break command is not executed immediately. The current motion continues instead until the next motion is planned to the same motion queue. Only then is the break command executed. If no executed motion involves the specified axis, or the motion finishes before the next motion is planned, the function has no effect. When executing the break command, the controller terminates the motion immediately without any deceleration profile. The controller builds instead a smooth third-order transition profile to the next motion. Use caution when implementing the break command with a multi-axis motion, because the controller provides a smooth transition profile of the vector velocity. In a single-axis motion, this ensures a smooth axis velocity. However, in a multi-axis motion an axis velocity can change abruptly if the terminated and next motions are not tangent to the junction point. To avoid jerk, the terminated and next motion must be tangent or nearly tangent in the junction point. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the using of acsc_Break // start up the motion of axis X to point 10000 acsc_ToPoint(Handle, 0, ACSC_AXIS_X, 10000, NULL); // delay 200 ms Sleep(200); // Windows API function acsc_Break(Handle, ACSC_AXIS_X, NULL); // change the end point to point –20000 on the fly acsc_ToPoint(Handle, 0, ACSC_AXIS_X, -20000, NULL); 4.13.10 acsc_BreakM Description The function terminates several motions immediately and provides a smooth transition to the next motions. 31 January 2009 165 C Library Functions
- 180. C Library Reference Version 6.50 Programmer’s Guide Syntax int acsc_BreakM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function acsc_WaitForAsyncCall returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function terminates the executed motions that involve the specified axes. Only those motions are terminated that have the next motion waiting in the corresponding motion queue. The terminated motions can be either single-axis or multi-axis. If a motion queue contains no waiting motion, the break command does not immediately affect the corresponding axis. The current motion continues instead until the next motion is planned to the same motion queue. Only then, the break command is executed. If no executed motion involves the specified axis, or the corresponding motion finishes before 31 January 2009 166 C Library Functions
- 181. C Library Reference Version 6.50 Programmer’s Guide the next motion is planned, the function does not affect the axis. When executing the break command, the controller terminates the motion immediately without any deceleration profile. Instead, the controller builds a smooth third-order transition profile to the next motion. Use caution when implementing the break command with a multi-axis motion, because the controller provides a smooth transition profile of the vector velocity. In a single-axis motion, this ensures a smooth axis velocity, but in a multi-axis motion, an axis velocity can change abruptly if the terminated and next motions are not tangent in the junction point. To avoid jerk, the terminated and next motion must be tangent or nearly tangent in the junction point. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_BreakM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Points[] = { 10000, 10000 }; // start up the motion of axis XY to point (10000, 10000) acsc_ToPointM(Handle, 0, Axes, Points, NULL); // delay 200 ms Sleep(200);// Windows API function acsc_BreakM(Handle, Axes, NULL); // change the end point to point (–10000, -10000) on the fly Points[0] = -10000; Points[1] = -10000; acsc_ToPointM(Handle, 0, Axes, Points, NULL); 31 January 2009 167 C Library Functions
- 182. C Library Reference Version 6.50 Programmer’s Guide 4.14 Point-to-Point Motion Functions The Point-to-Point Motion functions are: Table 18 Point-to-Point Motion Functions Function Description acsc_ToPoint Initiates a single-axis motion to the specified point. acsc_ToPointM Initiates a multi-axis motion to the specified point. acsc_ExtToPoint Initiates a single-axis motion to the specified point using the specified velocity or end velocity. acsc_ExtToPointM Initiates a multi-axis motion to the specified point using the specified velocity or end velocity. 4.14.1 acsc_ToPoint Description The function initiates a single-axis motion to the specified point. Syntax int acsc_ToPoint(HANDLE Handle, int Flags, int Axis, double Point, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_Go is executed. ACSC_AMF_RELATIVE: the Point value is relative to the end point of the previous motion. If the flag is not specified, the Point specifies an absolute coordinate. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Coordinate of the target point. 31 January 2009 168 C Library Functions
- 183. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a single-axis point-to-point motion. The motion is executed using the required motion velocity and finishes with zero end velocity. The required motion velocity is the velocity specified by the previous call of the acsc_SetVelocity function or the default velocity if the function was not called. To execute multi-axis point-to-point motion, use acsc_ToPointM. To execute motion with other motion velocity or non-zero end velocity, use acsc_ToPoint or acsc_ExtToPointM. The controller response indicates that the command was accepted and the motion was planned successfully. The function does not wait for the motion end. To wait for the motion end, use acsc_WaitMotionEnd function. The motion builds the velocity profile using the required values of velocity, acceleration, deceleration, and jerk of the specified axis. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 169 C Library Functions
- 184. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ToPoint if (!acsc_ToPoint(Handle, // communication handle 0, // start up immediately the motion ACSC_AXIS_X, // of the axis X 10000, // to the absolute target point 10000 NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.14.2 acsc_ToPointM Description The function initiates a multi-axis motion to the specified point. Syntax int acsc_ToPointM(HANDLE Handle, int Flags, int* Axes, double* Point, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_GoM is executed. ACSC_AMF_RELATIVE: the Point values are relative to the end point of the previous motion. If the flag is not specified, the Point specifies absolute coordinates. ACSC_AMF_MAXIMUM: not to use the motion parameters from the leading axis but to calculate the maximum allowed motion velocity, acceleration, deceleration, and jerk of the involved axes. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 170 C Library Functions
- 185. C Library Reference Version 6.50 Programmer’s Guide Point Array of the target coordinates. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a multi-axis point-to-point motion. The motion is executed using the required motion velocity and finishes with zero end velocity. The required motion velocity is the velocity specified by the previous call of the acsc_SetVelocity function, or the default velocity if the function was not called. To execute single-axis point-to-point motion, use acsc_ToPoint.To execute motion with other motion velocity or non-zero end velocity, use acsc_ExtToPoint or acsc_ExtToPointM. The controller response indicates that the command was accepted and the motion was planned successfully. The function does not wait for the motion end. To wait for the motion end, use acsc_WaitMotionEnd function. The motion builds the velocity profile using the required values of velocity, acceleration, deceleration, and jerk of the leading axis. The leading axis is the first axis in the Axes array. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 171 C Library Functions
- 186. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ToPointM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C, ACSC_AXIS_D, -1 }; double Points[] = {50000, 60000, 30000, -30000, -20000, -50000, -15000, 15000}; if (!acsc_ToPointM(Handle, // communication handle 0, // start up immediately the motion Axes, // of the axes XYZTABCD Points, // to the absolutely target point NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.14.3 acsc_ExtToPoint Description The function initiates a single-axis motion to the specified point using the specified velocity or end velocity. Syntax int acsc_ExtToPoint(HANDLE Handle, int Flags, int Axis, double Point, double Velocity, double EndVelocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don't start it until the function acsc_Go is executed. • ACSC_AMF_RELATIVE: the Point value is relative to the end point of the previous motion. If the flag is not specified, the Point specifies an absolute coordinate. • ACSC_AMF_VELOCITY: the motion will use velocity specified by the Velocity argument instead of the default velocity. • ACSC_AMF_ENDVELOCITY: the motion will come to the end point with the velocity specified by the EndVelocity argument. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 172 C Library Functions
- 187. C Library Reference Version 6.50 Programmer’s Guide Point Coordinate of the target point. Velocity Motion velocity. The argument is used only if the ACSC_AMF_VELOCITY flag is specified. EndVelocity Velocity in the target point. The argument is used only if the ACSC_AMF_ENDVELOCITY flag is specified. Otherwise, the motion finishes with zero velocity. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a single-axis point-to-point motion. If the ACSC_AMF_VELOCITY flag is specified, the motion is executed using the velocity specified by the Velocity argument. Otherwise, the required motion velocity is used. The required motion velocity is the velocity specified by the previous call of the acsc_SetVelocity function, or the default velocity if the function was not called. If the ACSC_AMF_ENDVELOCITY flag is specified, the motion velocity at the final point is specified by the EndVelocity argument. Otherwise, the motion velocity at the final point is zero. To execute a multi-axis point-to-point motion with the specified velocity or end velocity, use acsc_ExtToPointM. To execute motion with default motion velocity and zero end velocity, use acsc_ExtToPoint or acsc_ToPointM. The controller response indicates that the command was accepted and the motion was planned successfully. The function does not wait for the motion end. To wait for the motion end, use 31 January 2009 173 C Library Functions
- 188. C Library Reference Version 6.50 Programmer’s Guide acsc_WaitMotionEnd function. The motion builds the velocity profile using the required values of acceleration, deceleration and jerk of the specified axis. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_ExtToPoint if (!acsc_ExtToPoint(Handle, // communication handle ACSC_AMF_VELOCITY | // start up the motion with // specified velocity 5000 ACSC_AMF_ENDVELOCITY, // come to the end point with // specified velocity 1000 ACSC_AXIS_X, // axis X 10000, // target point 5000, // motion velocity 1000, // velocity in the target // point NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.14.4 acsc_ExtToPointM Description The function initiates a multi-axis motion to the specified point using the specified velocity or end velocity. Syntax int acsc_ExtToPointM(HANDLE Handle, int Flags, int* Axes, double* Point, double Velocity, double EndVelocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 174 C Library Functions
- 189. C Library Reference Version 6.50 Programmer’s Guide Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don't start it until the function acsc_Go is executed. • ACSC_AMF_RELATIVE: the Point values are relative to the end of the previous motion. If the flag is not specified, the Point specifies absolute coordinates. • ACSC_AMF_VELOCITY: the motion will use velocity specified by the Velocity argument instead of the default velocity. • ACSC_AMF_ENDVELOCITY: the motion will come to the end with the velocity specified by the EndVelocity argument. • ACSC_AMF_MAXIMUM: not to use the motion parameters from the leading axis but to calculate the maximum allowed motion velocity, acceleration, deceleration and jerk of the involved axes. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378 Point Array of the target coordinates. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Velocity Motion vector velocity. The argument is used only if the ACSC_AMF_VELOCITY flag is specified. EndVelocity Vector velocity in the target point. The argument is used only if the ACSC_AMF_ENDVELOCITY is specified. Otherwise, the motion finishes with zero velocity. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 175 C Library Functions
- 190. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a multi-axis point-to-point motion. If the ACSC_AMF_VELOCITY flag is specified, the motion is executed using the velocity specified by the Velocity argument. Otherwise, the required motion velocity is used. The required motion velocity is the velocity specified by the previous call of the acsc_SetVelocity function, or the default velocity if the function was not called. If the ACSC_AMF_ENDVELOCITY flag is specified, the motion velocity at the final point is specified by the EndVelocity argument. Otherwise, the motion velocity at the final point is zero. To execute a single-axis point-to-point motion with the specified velocity or end velocity, use acsc_ExtToPoint. To execute a motion with default motion velocity and zero end velocity, use acsc_ToPoint or acsc_ToPointM. The controller response indicates that the command was accepted and the motion was planned successfully. The function does not wait for the motion end. To wait for the motion end, use acsc_WaitMotionEnd function. The motion builds the velocity profile using the required values of acceleration, deceleration and jerk of the leading axis. The leading axis is the first axis in the Axes array. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 176 C Library Functions
- 191. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ExtToPointM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C, ACSC_AXIS_D, -1 }; double Points[] = { 50000, 60000, 30000, 20000, -20000, -50000, -15000, 15000 }; if (!acsc_ExtToPointM( Handle, // communication handle ACSC_AMF_VELOCITY | // start up the motion with // specified velocity 5000 // and come to the end point ACSC_AMF_ENDVELOCITY, // with specified velocity // 1000 Axes, // axes XYZTABCD Points, // target point 5000, // motion velocity 1000, // velocity in the target // point NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.15 Track Motion Control Functions The Track Motion Control functions are: Table 19 Track Motion Control Functions Function Description acsc_Track The function initiates a single-axis track motion. acsc_SetTargetPosition The function assigns a current value of target position. acsc_GetTargetPosition The function receives the current value of target position. 4.15.1 acsc_Track Description The function initiates a single-axis track motion. Syntax int acsc_Track(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait) 31 January 2009 177 C Library Functions
- 192. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Flags Bit-mapped parameter that can include the following flag: ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_Go is executed. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a single-axis track motion. After the motion is initialized, ptp motion will be generated with every change in TPOS value. The controller response indicates that the command was accepted and the motion was planned successfully. 31 January 2009 178 C Library Functions
- 193. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Track if (!acsc_Track(Handle, // communication handle 0, // start up immediately the motion ACSC_AXIS_X, // of the axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.15.2 acsc_SetTargetPosition Description The function assigns a current value of track position. Syntax int acsc_SetTargetPosition(HANDLE Handle, int Axis, double TargetPosition, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. TargetPosition The value specifies the current value of track position. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 179 C Library Functions
- 194. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function assigns a current value to the Track position. If the corresponding axis is initialized with track motion, the change of TPOS will cause generation of ptp motion to that new value. For more information see the explanation of the track command in the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetFPosition if (!acsc_SetTargetPosition(Handle,// communication handle ACSC_AXIS_X, // axis X 0, // required target position NULL // waiting call )) { printf("acsc_SetTargetPosition error: %dn", acsc_GetLastError()); } 4.15.3 acsc_GetTargetPosition Description The function retrieves the instant value of track position. Syntax int acsc_GetTargetPosition(HANDLE Handle, int Axis, double *TargetPosition, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see Axis Definitions. TargetPosition The pointer to variable that receives the instant value of the target position. 31 January 2009 180 C Library Functions
- 195. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function reads a current value of the corresponding TPOS variable. If the corresponding axis is initialized with track motion, TPOS controls the motion of the axis. For more information see the explanation of the track command in the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetFPosition double TPOS; if (!acsc_SetTargetPosition( Handle, // communication handle ACSC_AXIS_X, // axis X &TPOS // target position NULL // waiting call )) { printf("acsc_GetTargetPosition error: %dn", acsc_GetLastError()); } 31 January 2009 181 C Library Functions
- 196. C Library Reference Version 6.50 Programmer’s Guide 4.16 Jog Functions The Jog functions are: Table 20 Jog Functions Function Description acsc_Jog Initiates a single-axis jog motion. acsc_JogM Initiates a multi-axis jog motion. 4.16.1 acsc_Jog Description The function initiates a single-axis jog motion. Syntax int acsc_Jog(HANDLE Handle, int Flags, int Axis, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_Go is executed. • ACSC_AMF_VELOCITY: the motion will use the velocity specified by the Velocity argument instead of the default velocity. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Velocity If the ACSC_AMF_VELOCITY flag is specified, the velocity profile is built using the value of Velocity. The sign of Velocity defines the direction of the motion. If the ACSC_AMF_VELOCITY flag is not specified, only the sign of Velocity is used in order to specify the direction of motion. In this case, the constants ACSC_POSITIVE_DIRECTION or ACSC_NEGATIVE_DIRECTION can be used. 31 January 2009 182 C Library Functions
- 197. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a single-axis jog. To execute multi-axis jog, use acsc_JogM. The jog motion is a motion with constant velocity and no defined ending point. The jog motion continues until the next motion is planned, or the motion is killed for any reason. The motion builds the velocity profile using the default values of acceleration, deceleration and jerk of the specified axis. If the ACSC_AMF_VELOCITY flag is not specified, the default value of velocity is used as well. In this case, only the sign of Velocity is used in order to specify the direction of motion. The positive velocity defines a positive direction, the negative velocity – negative direction. If the ACSC_AMF_VELOCITY flag is specified, the value of Velocity is used instead of the default velocity. The sign of Velocity defines the direction of the motion. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. No waiting for the motion end is provided. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 183 C Library Functions
- 198. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Jog if (!acsc_Jog(Handle, // communication handle 0, // start up immediately the jog // motion // with default velocity ACSC_AXIS_X, // axis X ACSC_NEGATIVE_DIRECTION, // to the negative direction NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.16.2 acsc_JogM Description The function initiates a multi-axis jog motion. Syntax int acsc_JogM(HANDLE Handle, int Flags, int* Axes, int* Direction, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_Go is executed. • ACSC_AMF_VELOCITY: the motion will use the velocity specified by the Velocity argument instead of the default velocity. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 184 C Library Functions
- 199. C Library Reference Version 6.50 Programmer’s Guide Direction Array of directions—The number and order of values must correspond to the Axes array. The Direction array must specify direction for each element of Axes except the last –1 element. The constant ACSC_POSITIVE_DIRECTION in the Direction array specifies the correspondent axis to move in positive direction, the constant ACSC_NEGATIVE_DIRECTION specifies the correspondent axis to move in the negative direction. Velocity If the ACSC_AMF_VELOCITY flag is specified, the velocity profile is built using the value of Velocity. If the ACSC_AMF_VELOCITY flag is not specified, Velocity is not used. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a multi-axis jog motion. To execute single-axis jog motion, use acsc_Jog. The jog motion is a motion with constant velocity and no defined ending point. The jog motion continues until the next motion is planned, or the motion is killed for any reason. The motion builds the vector velocity profile using the default values of velocity, acceleration, deceleration and jerk of the axis group. If the ACSC_AMF_VELOCITY flag is not specified, the default value of velocity is used as well. If the ACSC_AMF_VELOCITY flag is specified, the value of Velocity is used instead of the default velocity. The function can wait for the controller response or can return immediately as specified by the Wait argument. 31 January 2009 185 C Library Functions
- 200. C Library Reference Version 6.50 Programmer’s Guide The controller response indicates that the command was accepted and the motion was planned successfully. The function cannot wait or validate the end of the motion. To wait for the motion end, use the acsc_WaitMotionEnd function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_JogM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z, ACSC_AXIS_T, ACSC_AXIS_A, ACSC_AXIS_B, ACSC_AXIS_C, ACSC_AXIS_D, -1 }; int Directions[] = { ACSC_POSITIVE_DIRECTION, ACSC_POSITIVE_DIRECTION, ACSC_POSITIVE_DIRECTION, ACSC_POSITIVE_DIRECTION, ACSC_NEGATIVE_DIRECTION, ACSC_NEGATIVE_DIRECTION, ACSC_NEGATIVE_DIRECTION, ACSC_NEGATIVE_DIRECTION }; if (!acsc_JogM(Handle, // communication handle 0, // start up immediately the jog motion // with the specified velocity 5000 Axes, // axes XYZTABCD Directions, // axes XYZT in the positive direction, // axes ABCD in the negative direction 5000, // motion velocity NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.17 Slaved Motion Functions The Slaved Motion functions are: Table 21 Slaved Motion Functions Function Description acsc_SetMaster Initiates calculation of a master value for an axis. acsc_Slave Initiates a master-slave motion. acsc_SlaveStalled Initiates master-slave motion with limited follow-on area. 31 January 2009 186 C Library Functions
- 201. C Library Reference Version 6.50 Programmer’s Guide 4.17.1 acsc_SetMaster Description The function initiates calculating of master value for an axis. Syntax int acsc_SetMaster(HANDLE Handle, int Axis, char* Formula, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Formula ASCII string that specifies a rule for calculating master value. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates calculating of master value for an axis. The master value for each axis is presented in the controller as one element of the MPOS array. Once the acsc_SetMaster function is called, the controller is calculates the master value for the specified axis each controller cycle. 31 January 2009 187 C Library Functions
- 202. C Library Reference Version 6.50 Programmer’s Guide The acsc_SetMaster function can be called again for the same axis at any time. At that moment, the controller discards the previous formula and accepts the newly specified formula for the master calculation. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the controller starts calculating the master value according to the formula. The Formula string can specify any valid ACSPL+ expression that uses any standard or user global variables as its operands. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetMaster char* szFormula = "2 * Y_FPOS"; // master value is calculated as // feedback position of the axis Y // with scale factor equal 2 if (!acsc_SetMaster( Handle, // communication handle ACSC_AXIS_X, // set master value for the axis X szFormula, // ASCII string that specifies a rule for // calculating master value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.17.2 acsc_Slave Description The function initiates a master-slave motion. Syntax int acsc_Slave(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 188 C Library Functions
- 203. C Library Reference Version 6.50 Programmer’s Guide Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_Go is executed. • ACSC_AMF_POSITIONLOCK: the motion will use position lock. If the flag is not specified, velocity lock is used (see “Comments” on Page 189). Axis Slaved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a single-axis master-slave motion with an unlimited area of following. If the area of following must be limited, use acsc_SlaveStalled. The master-slave motion continues until the motion is killed or the motion fails for any reason. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The master value for the specified axis must be defined before by the call to acsc_SetMaster function. The acsc_SetMaster function can be called again in order to change the formula of 31 January 2009 189 C Library Functions
- 204. C Library Reference Version 6.50 Programmer’s Guide master calculation. If at this moment the master-slave motion is in progress, the slave can come out from synchronism. The controller then regains synchronism, probably with a different value of offset between the master and slave. If the ACSC_AMF_POSITIONLOCK flag is not specified, the function activates a velocity- lock mode of slaved motion. When synchronized, the APOS axis reference follows the MPOS with a constant offset: APOS = MPOS + C The value of C is latched at the moment when the motion comes to synchronism, and then remains unchanged as long as the motion is synchronous. If at the moment of motion start the master velocity is zero, the motion starts synchronously and C is equal to the difference between initial values of APOS and MPOS. If the ACSC_AMF_POSITIONLOCK flag is specified, the function activates a position-lock mode of slaved motion. When synchronized, the APOS axis reference strictly follows the MPOS: APOS = MPOS If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Slave char* szFormula = "2 * Y_FPOS"; // master value is calculated as feedback // position of the axis Y with scale // factor equal 2 acsc_SetMaster(Handle, ACSC_AXIS_X, szFormula, NULL)); if (!acsc_Slave( Handle, // communication handle 0, // velocity lock is used as default ACSC_AXIS_X, // axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 190 C Library Functions
- 205. C Library Reference Version 6.50 Programmer’s Guide 4.17.3 acsc_SlaveStalled Description The function initiates master-slave motion within predefined limits. Syntax int acsc_SlaveStalled(HANDLE Handle, int Flags, int Axis, double Left, double Right, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the acsc_Go function is executed. • ACSC_AMF_POSITIONLOCK: the motion will use position lock. If the flag is not specified, velocity lock is used (see “Comments” on Page 192). Axis Slaved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Left Left (negative) limit of the following area. Right Right (positive) limit of the following area. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 191 C Library Functions
- 206. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates single-axis master-slave motion within predefiend limits. Use acsc_Slave to initiate unlimited motion. For sophisticated forms of master-slave motion, use slaved variants of segmented and spline motions. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The master-slave motion continues until the kill command is executed, or the motion fails for any reason. The master value for the specified axis must be defined before by the call to acsc_SetMaster function. The acsc_SetMaster function can be called again in order to change the formula of master calculation. If at this moment the master-slave motion is in progress, the slave can come out from synchronism. The controller then regains synchronism, probably with a different value of offset between the master and slave. If the ACSC_AMF_POSITIONLOCK flag is not specified, the function activates a velocity- lock mode of slaved motion. When synchronized, the APOS axis reference follows the MPOS with a constant offset: APOS = MPOS + C The value of C is latched at the moment when the motion comes to synchronism, and then remains unchanged as long as the motion is synchronous. If at the moment of motion start the master velocity is zero, the motion starts synchronously and C is equal to the difference between initial values of APOS and MPOS. If the ACSC_AMF_POSITIONLOCK flag is specified, the function activates a position-lock mode of slaved motion. When synchronized, the APOS axis reference strictly follows the MPOS: APOS = MPOS The Left and Right values define the allowed area of changing the APOS value. The MPOS value is not limited and can exceed the limits. In this case, the motion comes out from synchronism, and the APOS value remains (stalls) in one of the limits until the change of 31 January 2009 192 C Library Functions
- 207. C Library Reference Version 6.50 Programmer’s Guide MPOS allows following again. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SlaveStalled char* szFormula = "2 * Y_FPOS"; // master value is calculated as // feedback position of the axis Y with // scale factor equal 2 acsc_SetMaster(Handle, ACSC_AXIS_X, szFormula, NULL)); if (!acsc_SlaveStalled(Handle, // communication handle 0, // velocity lock is used as default ACSC_AXIS_X, // axis X -100000, // left (negative) limit of the // following area 100000, // right (positive) limit of the // following area NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.18 Multi-Point Motion Functions The Multi-Point Motion functions are: Table 22 Multi-point Motion Functions Function Description acsc_MultiPoint Initiates a single-axis multi-point motion. acsc_MultiPointM Initiates a multi-axis multi-point motion. 4.18.1 acsc_MultiPoint Description The function initiates a single-axis multi-point motion. Syntax int acsc_MultiPoint(HANDLE Handle, int Flags, int Axis, double Dwell, ACSC_WAITBLOCK* Wait) 31 January 2009 193 C Library Functions
- 208. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_Go is executed. • ACSC_AMF_RELATIVE: the coordinates of each point are relative. The first point is relative to the instant position when the motion starts; the second point is relative to the first, etc. If the flag is not specified, the coordinates of each point are absolute. • ACSC_AMF_VELOCITY: the motion uses the velocity specified with each point instead of the default velocity. • ACSC_AMF_CYCLIC: the motion uses the point sequence as a cyclic array. After positioning to the last point it does positioning to the first point and continues. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Dwell Dwell in each point in milliseconds. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 194 C Library Functions
- 209. C Library Reference Version 6.50 Programmer’s Guide Comments The function initiates a single-axis multi-point motion. To execute multi-axis multi-point motion, use acsc_MultiPointM. The motion executes sequential positioning to each of the specified points, optionally with dwell in each point. The function itself does not specify any point, so that the created motion starts only after the first point is specified. The points of motion are specified by using the acsc_AddPoint or acsc_ExtAddPoint functions that follow this function. The motion finishes when the acsc_EndSequence function is executed. If the call of acsc_EndSequence is omitted, the motion will stop at the last point of the sequence and wait for the next point. No transition to the next motion in the motion queue will occur until the function acsc_EndSequence executes. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The function cannot wait or validate the end of the motion. To wait for the motion end, use the acsc_WaitMotionEnd function. During positioning to each point, a velocity profile is built using the default values of acceleration, deceleration, and jerk of the specified axis. If the ACSC_AMF_VELOCITY flag is not specified, the default value of velocity is used as well. If the ACSC_AMF_VELOCITY flag is specified, the value of velocity specified in subsequent acsc_ExtAddPoint functions is used. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_MultiPoint if (!acsc_MultiPoint( Handle, // communication handle 0, // create the multi-point motion // with default velocity ACSC_AXIS_X, // axis X 1, // with dwell 1 ms NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points acsc_AddPoint(Handle, ACSC_AXIS_X, 1000, NULL);// from the point 1000 acsc_AddPoint(Handle, ACSC_AXIS_X, 2000, NULL);// to the point 2000 // finish the motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);// end of multi-point motion 31 January 2009 195 C Library Functions
- 210. C Library Reference Version 6.50 Programmer’s Guide 4.18.2 acsc_MultiPointM Description The function initiates a multi-axis multi-point motion. Syntax int acsc_MultiPointM(HANDLE Handle, int Flags, int* Axes, double Dwell, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_GoM is executed. • ACSC_AMF_RELATIVE: the coordinates of each point are relative. The first point is relative to the instant position when the motion starts; the second point is relative to the first, etc. If the flag is not specified, the coordinates of each point are absolute. • ACSC_AMF_VELOCITY: the motion will use the velocity specified with each point instead of the default velocity. • ACSC_AMF_CYCLIC: the motion uses the point sequence as a cyclic array: after positioning to the last point does positioning to the first point and continues. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Dwell Dwell in each point in milliseconds. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 196 C Library Functions
- 211. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a multi-axis multi-point motion. To execute single-axis multi-point motion, use acsc_MultiPoint. The motion executes sequential positioning to each of the specified points, optionally with dwell in each point. The function itself does not specify any point, so the created motion starts only after the first point is specified. The points of motion are specified by using acsc_AddPointM or acsc_ExtAddPointM, functions that follow this function. The motion finishes when the acsc_EndSequenceM function is executed. If the call of acsc_EndSequenceM is omitted, the motion will stop at the last point of the sequence and wait for the next point. No transition to the next motion in the motion queue will occur until the function acsc_EndSequenceM executes. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The function cannot wait or validate the end of the motion. To wait for the motion end, use acsc_WaitMotionEnd function. During positioning to each point, a vector velocity profile is built using the default values of velocity, acceleration, deceleration, and jerk of the axis group. If the AFM_VELOCITY flag is not specified, the default value of velocity is used as well. If the AFM_VELOCITY flag is specified, the value of velocity specified in subsequent acsc_ExtAddPointM functions is used. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 197 C Library Functions
- 212. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_MultiPointM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; int Points[2]; if (!acsc_MultiPointM(Handle, // communication handle 0, // create the multi-point motion with // default velocity Axes, // of the axes XY 0, // without dwell in the points NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points Points[0] = 1000; Points[1] = 1000; acsc_AddPointM(Handle, Axes, Points, NULL);// from the point 1000, 1000 Points[0] = 2000; Points[1] = 2000; acsc_AddPointM(Handle, Axes, Points, NULL);// to the point 2000, 2000 // finish the motion acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion 4.19 Arbitrary Path Motion Functions The Arbitrary Path Motion functions are: Table 23 Arbitrary Path Motion Functions Function Description acsc_Spline Initiates a single-axis spline motion. The motion follows an arbitrary path defined by a set of points. acsc_SplineM Initiates a multi-axis spline motion. The motion follows an arbitrary path defined by a set of points. 4.19.1 acsc_Spline Description The function initiates a single-axis spline motion. The motion follows an arbitrary path defined by a set of points. Syntax int acsc_Spline(HANDLE Handle, int Flags, int Axis, double Period, ACSC_WAITBLOCK* Wait) 31 January 2009 198 C Library Functions
- 213. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the acsc_Go function is executed. • ACSC_AMF_RELATIVE: use the coordinates of each point as relative. The first point is relative to the instant position when the motion starts; the second point is relative to the first, etc. If the flag is not specified, the coordinates of each point are absolute. • ACSC_AMF_VARTIME: the time interval between adjacent points is non-uniform and is specified along with each added point. If the flag is not specified, the interval is uniform and is specified in the Period argument. Flags • ACSC_AMF_CYCLIC: use the point sequence as a cyclic array: after the last point come to the first point and continue. • ACSC_AMF_CUBIC: use a cubic interpolation between the specified points (third-order spline). • If the flag is not specified, linear interpolation is used (first-order spline). • If the flag is specified and the ACSC_AMF_VARTIME is not specified, the controller builds PV spline motion. • If the flag is specified and the ACSC_AMF_VARTIME is specified, the controller builds PVT spline motion. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Period Time interval between adjacent points. The parameter is used only if the ACSC_AMF_VARTIME flag is not specified. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 199 C Library Functions
- 214. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a single-axis spline motion. To execute multi-axis spline motion, use acsc_SplineM. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The function cannot wait or validate the end of the motion. To wait for the motion end, use the acsc_WaitMotionEnd function. The motion does not use the default values of velocity, acceleration, deceleration, and jerk. The points and the time intervals between the points completely define the motion profile. Points for arbitrary path motion are defined by the consequent calls of acsc_AddPoint or acsc_ExtAddPoint functions. The acsc_EndSequence function terminates the point sequence. After execution of the acsc_EndSequence function, no acsc_AddPoint or acsc_ExtAddPoint functions for this motion are allowed. The trajectory of the motion follows through the defined points. Each point presents the instant desired position at a specific moment. Time intervals between the points are uniform, or non- uniform as defined by the ACSC_AMF_VARTIME flag. This motion does not use a motion profile generation. The time intervals between the points are typically short, so that the array of the points implicitly specifies the desired velocity in each point. If the time interval does not coincide with the controller cycle, the controller provides interpolation of the points according to the ACSC_AMF_CUBIC flag. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 200 C Library Functions
- 215. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Spline int i; if (!acsc_Spline( Handle, // communication handle 0, // create the arbitrary path motion // with uniform interval 10 ms ACSC_AXIS_X , 10, // uniform interval 10 ms NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points for (i = 0; i <100; i++) { do { if(!acsc_AddPoint (Handle, ACSC_AXIS_X, i*100, NULL)) ErrNum=acsc_GetLastError(); else ErrNum=0; }while(ErrNum==3065); } // finish the motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL); // the end of arbitrary path 4.19.2 acsc_SplineM Description The function initiates a multi-axis spline motion. The motion follows an arbitrary path defined by a set of points. Syntax int acsc_SplineM(HANDLE Handle, int Flags, int* Axes, double Period, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 201 C Library Functions
- 216. C Library Reference Version 6.50 Programmer’s Guide Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the acsc_GoM function is executed. • ACSC_AMF_RELATIVE: the coordinates of each point are relative. The first point is relative to the instant position when the motion starts; the second point is relative to the first, etc. If the flag is not specified, the coordinates of each point are absolute. • ACSC_AMF_VARTIME: the time interval between adjacent points is non-uniform and is specified along with each added point. If the flag is not specified, the interval is uniform and is specified in the Period argument. • ΑCSC_AMF_CYCLIC: the motion uses the point sequence as a cyclic array: after the last point the motion comes to the first point and continues. Flags • ACSC_AMF_CUBIC: use a cubic interpolation between the specified points (third-order spline). If the flag is not specified, linear interpolation is used (first-order spline). [In the present version third-order spline is not supported]. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Period Time interval between adjacent points. The parameter is used only if the ACSC_AMF_VARTIME flag is not specified. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 202 C Library Functions
- 217. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a multi-axis spline motion. To execute a single-axis spline motion, use acsc_Spline. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The function cannot wait or validate the end of the motion. To wait for the motion end, use the acsc_WaitMotionEnd function. The motion does not use the default values of velocity, acceleration, deceleration, and jerk. The points and the time intervals between the points define the motion profile completely. Points for arbitrary path motion are defined by the consequent calls of the acsc_AddPointM or acsc_ExtAddPointM functions. The acsc_EndSequenceM function terminates the point sequence. After execution of the acsc_EndSequenceM function, no acsc_AddPointM or acsc_ExtAddPointM functions for this motion are allowed. The trajectory of the motion follows through the defined points. Each point presents the instant desired position at a specific moment. Time intervals between the points are uniform, or non- uniform as defined by the ACSC_AMF_VARTIME flag. This motion does not use motion profile generation. Typically, the time intervals between the points are short, so that the array of the points implicitly specifies the desired velocity in each point. If the time interval does not coincide with the controller cycle, the controller provides interpolation of the points according to the ACSC_AMF_CUBIC flag. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example / example of the waiting call of acsc_SplineM int i; int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; int Points[2]; if (!acsc_SplineM( Handle, // communication handle 0, // create the arbitrary path motion // with uniform interval 10 ms 31 January 2009 203 C Library Functions
- 218. C Library Reference Version 6.50 Programmer’s Guide Axes, // axes XY 10, // uniform interval 10 ms NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points for (i = 0; i <100; i++) { Points[0] = i * 100; Points[1] = i * 50; do { if(!acsc_AddPointM(Handle, Axes, Points, NULL)) ErrNum=acsc_GetLastError(); else ErrNum=0; }while(ErrNum==3065); } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); // the end of arbitrary path motion 4.20 PVT Functions The PVT functions are: Table 24 PVT Functions Function Description acsc_AddPVPoint Adds a point to a single-axis multi-point or spline motion. acsc_AddPVPointM Adds a point to a multi-axis multi-point or spline motion. acsc_AddPVTPoint Adds a point to a single-axis multi-point or spline motion. acsc_AddPVTPointM Adds a point to a multi-axis multi-point or spline motion. 4.20.1 acsc_AddPVPoint Description The function adds a point to a single-axis PV spline motion and specifies velocity. Syntax int acsc_AddPVPoint(HANDLE Handle, int Axis, double Point, double Velocity, ACSC_WAITBLOCK* Wait) 31 January 2009 204 C Library Functions
- 219. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Axes ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Coordinate of the added point. Velocity Desired velocity at the point Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Before this function can be used, PV spline motion must be initiated by calling acsc_Spline with the appropriate flags. The function adds a point to a single-axis PV spline motion with a uniform time and specified velocity at that point To add a point to a multi-axis PV motion, use acsc_AddPVPointM. To add a point to a PVT motion with non-uniform time interval, use the acsc_AddPVTPoint and acsc_AddPVTPointM functions. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call 31 January 2009 205 C Library Functions
- 220. C Library Reference Version 6.50 Programmer’s Guide this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example int i; if (!acsc_Spline(Handle, // communication handle ACSC_AMF_CUBIC, //PV motion uniform time inteval ACSC_AXIS_X, // axis X 10, // uniform interval 10 ms NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points for (i = 0; i <100; i++) acsc_AddPVPoint(Handle,ACSC_AXIS_X,i*100,i*100,NULL); //position,velocity and time interval for each point // the end of the arbitrary path motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL); 4.20.2 acsc_AddPVPointM Description The function adds a point to a multiple-axis PV spline motion and specifies velocity. Syntax int acsc_AddPVPointM(HANDLE Handle, int *Axis, double *Point, double *Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see Axis Definitions. Point Array of the coordinates of added point. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. 31 January 2009 206 C Library Functions
- 221. C Library Reference Version 6.50 Programmer’s Guide Velocity Array of the velocities of added point. The number and order of values must correspond to the Axes array. The Velocity must specify a value for each element of Axes except the last –1 element. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Before this function can be used, PVT spline motion must be initiated by calling acsc_SplineM with the appropriate flags. The function adds a point to a multiple-axis PV spline motion with a uniform time and specified velocity at that point. To add a point to a single-axis PV motion, use acsc_AddPVPoint. To add a point to a PVT motion with non-uniform time interval, use the acsc_AddPVTPoint and acsc_AddPVTPointM functions. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. All axes specified in the Axes array must be specified before the call of the acsc_MultiPointM or acsc_SplineM function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of acsc_MultiPointM or acsc_SplineM functions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 207 C Library Functions
- 222. C Library Reference Version 6.50 Programmer’s Guide Example int i; int Axis[]={ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,-1}; double Point[3]; double Velocity[3]; if (!acsc_SplineM(Handle, // communication handle ACSC_AMF_CUBIC, // PV motion Axis, // axis X 10, // uniform interval 10 ms NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points for (i = 0; i <100; i++) { Point[0]=i*50; Point[1]=i*100; Point[2]=i*150; Velocity[0]=i*50; Velocity [1]=i*100; Velocity [2]=i*150; acsc_AddPVPointM(Handle,Axis,Point,Velocity,NULL); //position,velocity and time interval for each point } // the end of the arbitrary path motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL); 4.20.3 acsc_AddPVTPoint Description The function adds a point to a single-axis PVT spline motion and specifies velocity and motion time. Syntax int acsc_AddPVTPoint(HANDLE Handle, int Axis, double Point, double Velocity,double TimeInterval, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Coordinate of the added point. Velocity Desired velocity at the point 31 January 2009 208 C Library Functions
- 223. C Library Reference Version 6.50 Programmer’s Guide TimeInterval If the motion was activated by the acsc_Spline function with the ACSC_AMF_VARTIME flag, this parameter defines the time interval between the previous point and the present one. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Before this function can be used, PV spline motion must be initiated by calling acsc_Spline with the appropriate flags. The function adds a point to a single-axis PVT spline motion with a non-uniform time and specified velocity at that point. To add a point to a multi-axis PVT motion, use acsc_AddPVTPointM. To add a point to a PV motion with uniform time interval, use the acsc_AddPVPoint and acsc_AddPVPointM functions. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 209 C Library Functions
- 224. C Library Reference Version 6.50 Programmer’s Guide Example int i; if (!acsc_Spline(Handle, // communication handle ACSC_AMF_CUBIC|ACSC_AMF_VARTIME,//PVT motion ACSC_AXIS_X, // axis X 0, // uniform interval is not used NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points for (i = 0; i <100; i++) acsc_AddPVTPoint(Handle,ACSC_AXIS_X,i*100,i*100,100+i,NULL); //position,velocity and time interval for each point // the end of the arbitrary path motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL); 4.20.4 acsc_AddPVTPointM Description The function adds a point to a multiple-axis PVT spline motion and specifies velocity and motion time. Syntax int acsc_AddPVTPointM(HANDLE Handle, int *Axis, double *Point, double *Velocity,double TimeInterval, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Array of the coordinates of added point. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Velocity Array of the velocities of added point. The number and order of values must correspond to the Axes array. The Velocity must specify a value for each element of Axes except the last –1 element. 31 January 2009 210 C Library Functions
- 225. C Library Reference Version 6.50 Programmer’s Guide TimeInterval If the motion was activated by the acsc_SplineM function with the ACSC_AMF_VARTIME flag, this parameter defines the time interval between the previous point and the present one. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Before this function can be used, PVT spline motion must be initiated by calling acsc_SplineM with the appropriate flags. The function adds a point to a multiple-axis PVT spline motion with a non-uniform time and specified velocity at that point. To add a point to a single-axis PVT motion, use acsc_AddPVTPoint. To add a point to a PV motion with uniform time interval, use the acsc_AddPVPoint and acsc_AddPointM functions. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 211 C Library Functions
- 226. C Library Reference Version 6.50 Programmer’s Guide Example int i; int Axis[]={ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,-1}; double Point[3]; double Velocity[3]; if (!acsc_SplineM(Handle, // communication handle ACSC_AMF_CUBIC|ACSC_AMF_VARTIME,//PVT motion Axis, // axis X 0, // uniform interval is not used NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add some points for (i = 0; i <100; i++) { Point[0]=i*50; Point[1]=i*100; Point[2]=i*150; Velocity[0]=i*50; Velocity [1]=i*100; Velocity [2]=i*150; acsc_AddPVTPointM(Handle,Axis,Point,Velocity,100+i,NULL); //position,velocity and time interval for each point } // the end of the arbitrary path motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL); 4.21 Segmented Motion Functions The Segmented Motion functions are: Table 25 Segmented Motion Functions (page 1 of 2) Function Description acsc_Segment Initiates a multi-axis segmented motion. acsc_Line Adds a linear segment to a segmented motion. acsc_ExtLine Adds a linear segment to a segmented motion and specifies a motion velocity. acsc_Arc1 Adds an arc segment to a segmented motion and specifies the coordinates of center point, coordinates of the final point, and the direction of rotation. acsc_ExtArc1 Adds an arc segment to a segmented motion and specifies the coordinates of center point, coordinates of the final point, direction of rotation, and the vector velocity for the current segment. acsc_Arc2 Add’s an arc segment to a segmented motion and specifies the coordinates of center point and rotation angle. 31 January 2009 212 C Library Functions
- 227. C Library Reference Version 6.50 Programmer’s Guide Table 25 Segmented Motion Functions (page 2 of 2) Function Description acsc_ExtArc2 Adds an arc segment to a segmented motion and specifies the coordinates of center point, rotation angle, and the vector velocity for the current segment. acsc_Stopper Provides a smooth transition between two segments of segmented motion. acsc_Projection Sets a projection matrix for a segmented motion. 4.21.1 acsc_Segment Description The function initiates a multi-axis segmented motion. Syntax int acsc_Segment(HANDLE Handle, int Flags, int* Axes, double* Point, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_AMF_WAIT: plan the motion but don’t start it until the function acsc_GoM is executed. • ACSC_AMF_VELOCITY: the motion will use velocity specified for each segment instead of the default velocity. • ACSC_AMF_CYCLIC: the motion uses the segment sequence as a cyclic array: after the last segment, move along the first segment etc. • ACSC_AMF_VELOCITYLOCK: slaved motion: the motion advances in accordance to the master value of the leading axis. • ACSC_AMF_POSITIONLOCK: slaved motion, strictly conformed to master. • ACSC_AMF_EXTRAPOLATED: if a master value travels beyond the specified path, the last or the first segment is extrapolated. • ACSC_AMF_STALLED: if a master value travels beyond the specified path, the motion stalls at the last or first point. 31 January 2009 213 C Library Functions
- 228. C Library Reference Version 6.50 Programmer’s Guide Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Array of the coordinates of the initial point on the plane. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates a multi-axis segmented motion. Segmented motion moves axes along a continuous path. The path is defined as a sequence of linear and arc segments on the plane. Although segmented motion follows a flat path, it can involve any number of axes, because the motion plane can be connected to the axes at any projection transformation. To use such transformation, use the acsc_Projection function. The function itself does not specify any segment, so the created motion starts only after the first segment is specified. The segments of motion are specified by the using acsc_Line, acsc_Arc1, acsc_Arc2, acsc_ExtLine, acsc_ExtArc1, or acsc_ExtArc2 functions that follow this function. The motion finishes when the acsc_EndSequenceM function is executed. If the call of acsc_EndSequenceM is omitted, the motion will stop at the last segment of the sequence and 31 January 2009 214 C Library Functions
- 229. C Library Reference Version 6.50 Programmer’s Guide wait for the next segment. No transition to the next motion in the motion queue will occur until the function acsc_EndSequenceM is executed. During positioning to each point, a vector velocity profile is built using the default values of velocity, acceleration, deceleration, and jerk of the axis group. If the AFM_VELOCITY flag is not specified, the default value of velocity is used as well. If the AFM_VELOCITY flag is specified, the value of velocity specified in subsequent acsc_ExtLine, acsc_ExtArc1, or acsc_ExtArc2 functions is used. The flags ACSC_AMF_EXTRAPOLATED and ACSC_AMF_STALLED are relevant only for slaved motion and must be used with ACSC_AMF_VELOCITYLOCK or ACSC_AMF_POSITIONLOCK flags. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the motion was planned successfully. The function does not wait and does not validate the end of the motion. To wait for the motion end, use the acsc_WaitMotionEnd function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 215 C Library Functions
- 230. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Segment int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2], Center[2]; // create segmented motion, coordinates of the initial point are (1000,1000) Point[0] = 1000; Point[1] = 1000; if (!acsc_Segment(Handle, // communication handle 0, // create the segmented motion with default // velocity Axes, // axes XY Point, // initial point NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add arc segment with center (1000, 0), final point (1000, -1000), // clockwise rotation Center[0] = 1000; Center[1] = 0; Point[0] = 1000; Point[1] = -1000; acsc_Arc1(Handle, Axes, Center, Point, ACSC_CLOCKWISE, NULL); // add line segment with final point (-1000, -1000) Point[0] = -1000; Point[1] = -1000; acsc_Line(Handle, Axes, Point, NULL); // add arc segment with center (-1000, 0) and rotation angle - Center[0] = -1000; Center[1] = 0; acsc_Arc2(Handle, Axes, Center, -3.141529, NULL); // add line segment with final point (1000, 1000) Point[0] = 1000; Point[1] = 1000; acsc_Line(Handle, Axes, Point, NULL); // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 4.21.2 acsc_Line Description The function adds a linear segment to a segmented motion. Syntax int acsc_Line(HANDLE Handle, int* Axes, double* Point, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 216 C Library Functions
- 231. C Library Reference Version 6.50 Programmer’s Guide Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Array of the final point coordinates. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds a linear segment to the segmented motion. To add a linear segment with a specified non-default velocity, use acsc_ExtLine. All axes specified in the Axes array must be specified before the call of the acsc_Segment function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of acsc_Segment function. The parameter Point specifies the coordinates of the final point. The coordinates are absolute in the plane. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the segment is added to 31 January 2009 217 C Library Functions
- 232. C Library Reference Version 6.50 Programmer’s Guide the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Line int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[] = { 1000, 1000 }; if (!acsc_Line( Handle, // communication handle Axes, // axes XY Points, // final point coordinates NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.21.3 acsc_ExtLine Description The function adds a linear segment to a segmented motion and specifies a motion velocity. Syntax int acsc_ExtLine(HANDLE Handle, int* Axes, double* Point, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Array of the final point coordinates. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Velocity If the motion was activated by the acsc_Segment function with the ACSC_AMF_VELOCITY flag, this parameter specifies a motion velocity for current segment. 31 January 2009 218 C Library Functions
- 233. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds a linear segment to the segmented motion and specifies a motion velocity for the current segment. To add a linear segment with default velocity, use acsc_Line. All axes specified in the Axes array must be specified before the call of the acsc_Segment function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of the acsc_Segment function. The parameter Point specifies the coordinates of the final point. The coordinates are absolute in the plane. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the segment is added to the motion buffer. The segment can be rejected if the motion buffer is full. In that case, you can call this function periodically until the function returns a non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 219 C Library Functions
- 234. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ExtLine // the path of the specified segmented motion is square // for each side of the square the non-default vector velocity is used int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2]; // create segmented motion, coordinates of the initial point are // (1000,1000) Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, ACSC_AMF_VELOCITY, Axes, Point, NULL); // add line segment with final point (1000, -1000), vector velocity 25000 Point[0] = 1000; Point[1] = -1000; acsc_ExtLine( Handle, // communication handle Axes, // axes XY Point, // final point 25000, // vector velocity NULL // waiting call ); // add line segment with final point (-1000, -1000), vector velocity 15000 Point[0] = -1000; Point[1] = -1000; acsc_ExtLine(Handle, Axes, Point, 15000, NULL); // add line segment with final point (-1000, 1000) // if the velocity argument is omitted, the velocity from the previous // segment is used Point[0] = -1000; Point[1] = 1000; acsc_Line(Handle, Axes, Point, NULL); // add line segment with final point (1000, 1000), vector velocity 5000 Point[0] = 1000; Point[1] = 1000; acsc_ExtLine(Handle, Axes, Point, 5000, NULL); // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 4.21.4 acsc_Arc1 Description The function adds an arc segment to a segmented motion and specifies the coordinates of the center point, the coordinates of the final point and the direction of rotation. Syntax int acsc_Arc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int Rotation, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 220 C Library Functions
- 235. C Library Reference Version 6.50 Programmer’s Guide Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Center Array of the center coordinates. The number and order of values must correspond to the Axes array. The Center must specify a value for each element of the Axes except the last–1 element. FinalPoint Array of the final point coordinates. The number and order of values must correspond to the Axes array. The FinalPoint must specify a value for each element of Axes except the last –1 element. Rotation This parameter defines the direction of rotation. If Rotation is set to ACSC_COUNTERCLOCKWISE, then the rotation is counterclockwise. If Rotation is set to ACSC_CLOCKWISE, then rotation is clockwise. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds an arc segment to the segmented motion and specifies the coordinates of the center point, the coordinates of the final point and the direction of rotation. To add an arc segment with a specified non-default velocity, use acsc_ExtArc1. 31 January 2009 221 C Library Functions
- 236. C Library Reference Version 6.50 Programmer’s Guide All axes specified in the Axes array must be specified before the call of the acsc_Segment function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of the acsc_Segment function. The parameter Center specifies the coordinates of the arc center. The parameter FinalPoint specifies the coordinates of the final point. All coordinates are absolute in the plane. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the segment is added to the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Arc1 int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2], Center[2]; // create segmented motion, coordinates of the initial point are // (1000,1000) Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, 0, Axes, Point, NULL); // describe circle with center (1000, 0), final point (1000, 1000), // clockwise rotation Center[0] = 1000; Center[1] = 0; Point[0] = 1000; Point[1] = 1000; if (!acsc_Arc1( Handle, // communication handle Axes, // axes XY Center, // center of the circle Point, // final point ACSC_CLOCKWISE, // clockwise rotation NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 4.21.5 acsc_ExtArc1 Description The function adds an arc segment to a segmented motion and specifies the coordinates of the center point, the coordinates of the final point, the direction of rotation, and the vector velocity for the current segment. 31 January 2009 222 C Library Functions
- 237. C Library Reference Version 6.50 Programmer’s Guide Syntax int acsc_ExtArc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int Rotation, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Center Array of the center coordinates. The number and order of values must correspond to the Axes array. The Center must specify a value for each element of Axes except the last –1 element. FinalPoint Array of the final point coordinates. The number and order of values must correspond to the Axes array. The FinalPoint must specify a value for each element of Axes except the last –1 element. Rotation This parameter defines the direction of rotation. If Rotation is set to ACSC_COUNTERCLOCKWISE, then the rotation is counterclockwise; if Rotation is set to ACSC_CLOCKWISE, then rotation is clockwise. Velocity If the motion was activated by the acsc_Segment function with the ACSC_AMF_VELOCITY flag, this parameter specifies a motion velocity for current segment. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread can then validate the operation result using the members of ACSC_WAITBLOCK structure. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 223 C Library Functions
- 238. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds an arc segment to the segmented motion and specifies the coordinates of the center point, the coordinates of the final point, the direction of rotation, and the vector velocity for the current segment. To add an arc segment with default velocity, use acsc_Arc1. All axes specified in the Axes array must be specified before the call of the acsc_Segment function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of acsc_Segment function. The parameter Center specifies the coordinates of the arc center. The parameter FinalPoint specifies the coordinates of the final point. All coordinates are absolute in the plane. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the segment is added to the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_ExtArc1 // the path of the specified segmented motion is circle // for each semicircle the different vector velocity is used int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2], Center[2]; // create segmented motion, coordinates of the initial point are // (1000,1000) Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, ACSC_AMF_VELOCITY, Axes, Point, NULL); // add arc segment with center (1000, 0), final point (1000, -1000), // clockwise rotation, vector velocity 25000 Center[0] = 1000; Center[1] = 0; Point[0] = 1000; Point[1] = -1000; if (!acsc_ExtArc1(Handle, // communication handle 31 January 2009 224 C Library Functions
- 239. C Library Reference Version 6.50 Programmer’s Guide Axes, // axes XY Center, // center of the circle Point, // final point ACSC_CLOCKWISE, // clockwise rotation 25000, // vector velocity NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add arc segment with center (1000, 0), final point (1000, 1000), // clockwise rotation, vector velocity 15000 Center[0] = 1000; Center[1] = 0; Point[0] = 1000; Point[1] = 1000; if (!acsc_ExtArc1(Handle, // communication handle Axes, // axes XY Center, // center of the circle Point, // final point ACSC_CLOCKWISE, // clockwise rotation 15000, // vector velocity NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 4.21.6 acsc_Arc2 Description The function adds an arc segment to a segmented motion and specifies the coordinates of the center point and the rotation angle. Syntax int acsc_Arc2(HANDLE Handle, int* Axes, double* Center, double Angle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 225 C Library Functions
- 240. C Library Reference Version 6.50 Programmer’s Guide Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Center Array of the center coordinates. The number and order of values must correspond to the Axes array. The Center must specify a value for each element of Axes except the last –1 element. Angle Rotation angle in radians. Positive angle for counterclockwise rotation, negative for clockwise rotation. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds an arc segment to the segmented motion and specifies the coordinates of the center point and the rotation angle. To add an arc segment with a specified non-default velocity, use acsc_ExtArc2. All axes specified in the Axes array must be specified before the call of the acsc_Segment function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of the acsc_Segment function. The parameter Center specifies the coordinates of the arc center. The coordinates are absolute in the plane. 31 January 2009 226 C Library Functions
- 241. C Library Reference Version 6.50 Programmer’s Guide The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the segment is added to the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns a non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Arc2 int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2], Center[2]; // create segmented motion, coordinates of the initial point are // (1000,1000) Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, 0, Axes, Point, NULL); // describe circle with center (1000, 0), clockwise rotation Center[0] = 1000; Center[1] = 0; if (!acsc_Arc2(Handle, // communication handle Axes, // axes XY Center, // center of the circle -2 * 3.141529,// full circle NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 4.21.7 acsc_ExtArc2 Description The function adds an arc segment to a segmented motion and specifies the coordinates of the center point, the rotation angle, and the vector velocity for the current segment. Syntax int acsc_ExtArc2(HANDLE Handle, int* Axes, double* Center, double Angle, double Velocity, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 227 C Library Functions
- 242. C Library Reference Version 6.50 Programmer’s Guide Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Center Array of the center coordinates. The number and order of values must correspond to the Axes array. The Center must specify a value for each element of Axes except the last –1 element. Angle Rotation angle in radians. Positive angle for counterclockwise rotation, negative for clockwise rotation. Velocity If the motion was activated by the acsc_Segment function with the ACSC_AMF_VELOCITY flag, this parameter specifies a motion velocity for current segment. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds an arc segment to the segmented motion and specifies the coordinates of the center point, the rotation angle, and the vector velocity for the current segment. To add an arc segment with default velocity, use acsc_Arc2. All axes specified in the Axes array must be specified before the call of the acsc_Segment function. The number and order of the axes in the Axes array must correspond exactly to the 31 January 2009 228 C Library Functions
- 243. C Library Reference Version 6.50 Programmer’s Guide number and order of axes of the acsc_Segment function. The parameter Center specifies the coordinates of the arc center. The coordinates are absolute in the plane. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the segment is added to the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns a non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example Axes, // axes XY Center, // center of the circle -3.141529,// semicircle 15000, // vector velocity NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); // example of the waiting call of acsc_ExtArc2 // the path of the specified segmented motion is circle // for each semicircle the different vector velocity is used int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2], Center[2]; // create segmented motion, coordinates of the initial point are // (1000, 1000) Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, ACSC_AMF_VELOCITY, Axes, Point, NULL); // add arc segment with center (1000, 0), negative rotation angle -, vector // velocity 25000 Center[0] = 1000; Center[1] = 0; if (!acsc_ExtArc2(Handle, // communication handle Axes, // axes XY Center, // center of the circle -3.141529,// semicircle 25000, // vector velocity NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } // add arc segment with center (1000, 0), negative rotation angle -, vector // velocity 15000 Center[0] = 1000; Center[1] = 0; if (!acsc_ExtArc2(Handle, // communication handle 31 January 2009 229 C Library Functions
- 244. C Library Reference Version 6.50 Programmer’s Guide 4.21.8 acsc_Stopper Description The function provides a smooth transition between two segments of segmented motion. Syntax int acsc_Stopper(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The controller builds the motion so that the vector velocity follows the smooth velocity diagram. The segments define the projection of the vector velocity to axis velocities. If all segments are connected smoothly, axis velocity is also smooth. However, if the user defined a path with an inflection point, axis velocity has a jump in this point. The jump can cause a motion failure due to the acceleration limit. 31 January 2009 230 C Library Functions
- 245. C Library Reference Version 6.50 Programmer’s Guide The function is used to avoid velocity jump in the inflection points. If the function is specified between two segments, the controller provides smooth deceleration to zero in the end of first segment and smooth acceleration to specified velocity in the beginning of second segment. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_Stopper // the example provides a rectangular path without velocity jumps int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; double Point[2]; // create segmented motion, coordinates of the initial point are // (1000,1000) Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, 0, Axes, Point, NULL); // add line segment with final point (1000, -1000) Point[0] = 1000; Point[1] = -1000; acsc_Line(Handle, Axes, Point, NULL); acsc_Stopper(Handle, Axes, NULL); // add line segment with final point (-1000, -1000) Point[0] = -1000; Point[1] = -1000; acsc_Line(Handle, Axes, Point, NULL); acsc_Stopper(Handle, Axes, NULL); // add line segment with final point (-1000, 1000) Point[0] = -1000; Point[1] = 1000; acsc_Line(Handle, Axes, Point, NULL); acsc_Stopper(Handle, Axes, NULL); // add line segment with final point (1000, 1000) Point[0] = 1000; Point[1] = 1000; acsc_Line(Handle, Axes, Point, NULL); // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 4.21.9 acsc_Projection Description The function sets a projection matrix for segmented motion. Syntax int acsc_Projection(HANDLE Handle, int* Axes, char* Matrix, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 231 C Library Functions
- 246. C Library Reference Version 6.50 Programmer’s Guide Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Matrix Pointer to the null-terminated string containing the name of the matrix that provides the specified projection. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets a projection matrix for segmented motion. The projection matrix connects the plane coordinates and the axis values in the axis group. The projection can provide any transformation as rotation or scaling. The number of the matrix rows must be equal to the number of the specified axes. The number of the matrix columns must equal two. The matrix must be declared before as a global variable by an ACSPL+ program or by the acsc_DeclareVariable function and must be initialized by an ACSPL+ program or by the acsc_WriteReal function. For more information about projection, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 232 C Library Functions
- 247. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Projection int Axes[4]; double Point[2], Center[2]; // prepare the projection matrix double Matrix[3][2] = {{ 1, 0 }, { 0, 1.41421 }, { 0, 1.41421 } }; // declare the matrix that will contain the projection acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, “ProjectionMatrix(3)(2)”, NULL); // initialize the projection matrix acsc_WriteReal(Handle, ACSC_NONE, "ProjectionMatrix", 0, 2, 0, 1, Matrix, NULL); Axes[0]= ACSC_AXIS_X; Axes[1]=ACSC_AXIS_Y; Axes[2]= ACSC_AXIS_Z; Axes[3] = -1; // create a group of the involved // axes acsc_Group(Handle, Axes, NULL); // create segmented motion, // coordinates of the initial point // are (1000,1000) Axes[0] = ACSC_AXIS_X; Axes[1] = ACSC_AXIS_Y; Axes[2] = -1; Point[0] = 1000; Point[1] = 1000; acsc_Segment(Handle, 0, Axes, Point, NULL); // incline the working plane XY by // 45° Axes[0] = 0; Axes[1] = 1; Axes[2] = 2; Axes[3] = -1; acsc_Projection(Handle, Axes, “ProjectionMatrix”, NULL); // describe circle with center (1000, 0), clockwise rotation // although the circle was defined, really on the plane XY we will get the // ellipse stretched along the Y axis Axes[0] = 0; Axes[1] = 1; Axes[2] = -1; Center[0] = 1000; Center[1] = 0; acsc_Arc2(Handle, Axes, Center, -2 * 3.141529, NULL); // finish the motion acsc_EndSequenceM(Handle, Axes, NULL); 31 January 2009 233 C Library Functions
- 248. C Library Reference Version 6.50 Programmer’s Guide 4.22 Points and Segments Manipulation Functions The Points and Segments Manipulation functions are: Table 26 Points and Segments Manipulation Functions Function Description acsc_AddPoint Adds a point to a single-axis multi-point or spline motion. acsc_AddPointM Adds a point to a multi-axis multi-point or spline motion. acsc_ExtAddPoint Adds a point to a single-axis multi-point or spline motion and specifies a specific velocity or motion time. acsc_ExtAddPointM Adds a point to a multi-axis multi-point or spline motion and specifies a specific velocity or motion time. acsc_EndSequence Informs the controller that no more points will be specified for the current single-axis motion. acsc_EndSequenceM Informs the controller that no more points or segments will be specified for the current multi-axis motion. 4.22.1 acsc_AddPoint Description The function adds a point to a single-axis multi-point or spline motion. Syntax int acsc_AddPoint(HANDLE Handle, int Axis, double Point, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Coordinate of the added point. 31 January 2009 234 C Library Functions
- 249. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds a point to a single-axis multi-point or spline motion. To add a point to a multi- axis motion, use acsc_AddPVPointM. To add a point with a specified non-default velocity or time interval use acsc_AddPVPoint or acsc_AddPVPointM. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 235 C Library Functions
- 250. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_AddPoint int i; acsc_MultiPoint(Handle, 0, 0, 1, NULL));// create multi-point motion // add some points for (i = 0; i < 5; i++) { if (!acsc_AddPoint(Handle, // communication handle ACSC_AXIS_X, // axis X 1000 * i, // points 1000, 2000, 3000, … NULL // waiting call )) { printf("transaction error: %dn",acsc_GetLastError()); break; } } // finish the motion acsc_EndSequence(Handle, 0, NULL); // end of the multi-point motion 4.22.2 acsc_AddPointM Description The function adds a point to a multi-axis multi-point or spline motion. Syntax int acsc_AddPointM(HANDLE Handle, int* Axes, double* Point, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of involved axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 236 C Library Functions
- 251. C Library Reference Version 6.50 Programmer’s Guide Point Array of the coordinates of added point. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds a point to a multi-axis multi-point or spline motion. To add a point to a single- axis motion, use acsc_AddPoint. To add a point with a specified non-default velocity or time interval use acsc_ExtAddPoint or acsc_ExtAddPointM. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. All axes specified in the Axes array must be specified before the call of the acsc_MultiPointM or acsc_SplineM function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of acsc_MultiPointM or acsc_SplineM functions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 237 C Library Functions
- 252. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_AddPointM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; int Points[2]; int i; acsc_MultiPointM(Handle, 0, Axes, 0, NULL)); // create multi-point motion // add some points for (i = 0; i < 5; i++) { Points[0] = 1000 * i; Points[1] = 1000 * i; // points (1000, 1000), (2000, 2000)… if (!acsc_AddPointM(Handle, Axes, Points, NULL)) { printf("transaction error: %dn", acsc_GetLastError()); break; } } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion 4.22.3 acsc_ExtAddPoint Description The function adds a point to a single-axis multi-point or spline motion and specifies a specific velocity or motion time. Syntax int acsc_ExtAddPoint(HANDLE Handle, int Axis, double Point, double Rate, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Coordinate of the added point. Rate If the motion was activated by the acsc_MultiPoint function with the ACSC_AMF_VELOCITY flag, this parameter defines the motion velocity. If the motion was activated by the acsc_Spline function with the ACSC_AMF_VARTIME flag, this parameter defines the time interval between the previous point and the present one. 31 January 2009 238 C Library Functions
- 253. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds a point to a single-axis multi-point motion with specific velocity or to single- axis spline motion with a non-uniform time. To add a point to a multi-axis motion, use acsc_ExtAddPointM. To add a point to a motion with default velocity or uniform time interval, the acsc_AddPoint and acsc_AddPointM functions are more convenient. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns a non-zero value. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 239 C Library Functions
- 254. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ExtAddPoint int i; // create multi-point motion with the specific velocity acsc_MultiPoint(Handle, ACSC_AMF_VELOCITY, ACSC_AXIS_X, 1, NULL); // add some points for (i = 0; i < 5; i++) { if (!acsc_ExtAddPoint( Handle, // communication handle ACSC_AXIS_X, // axis X 1000 * i, // points 1000, 2000, 3000, … 5000, // in this case Rate defines // a motion velocity NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); break; } } // finish the motion acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);// end of multi-point motion 4.22.4 acsc_ExtAddPointM Description The function adds a point to a multi-axis multi-point or spline motion and specifies a specific velocity or motion time. Syntax int acsc_ExtAddPointM(HANDLE Handle, int* Axes, double* Point, double Rate, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Point Array of the coordinates of added point. The number and order of values must correspond to the Axes array. The Point must specify a value for each element of Axes except the last –1 element. 31 January 2009 240 C Library Functions
- 255. C Library Reference Version 6.50 Programmer’s Guide Rate If the motion was activated by the acsc_MultiPoint function with the ACSC_AMF_VELOCITY flag, this parameter defines as motion velocity. If the motion was activated by the acsc_Spline function with the ACSC_AMF_VARTIME flag, this parameter defines as time interval between the previous point and the present one. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function adds a point to a multi-axis multi-point or spline motion. To add a point to a single- axis motion, use acsc_ExtAddPoint. To add a point to a motion with a default velocity or a uniform time interval, the acsc_ExtAddPointM function is more convenient. The function can wait for the controller response or can return immediately as specified by the Wait argument. The controller response indicates that the command was accepted and the point is added to the motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call this function periodically until the function returns non-zero value. All axes specified in the Axes array must be specified before the call of the acsc_MultiPointM or acsc_SplineM function. The number and order of the axes in the Axes array must correspond exactly to the number and order of the axes of acsc_MultiPointM or acsc_SplineM functions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 241 C Library Functions
- 256. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ExtAddPointM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; int Points[2]; int i; // create multi-point motion with specific velocity acsc_MultiPointM(Handle, ACSC_AMF_VELOCITY, Axes, 0, NULL)); // add some points for (i = 0; i < 5; i++) { Points[0] = 1000 * i; Points[1] = 1000 * i; if (!acsc_ExtAddPointM(Handle, // communication handle Axes, // axes XY Points, // points (1000,1000), // (2000,2000), … 5000, // in this case Rate defines // a motion velocity NULL )) { printf("transaction error: %dn", acsc_GetLastError()); break; } } // finish the motion acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion 4.22.5 acsc_EndSequence Description The function informs the controller, that no more points will be specified for the current single- axis motion. Syntax int acsc_EndSequence(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 242 C Library Functions
- 257. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The motion finishes when the acsc_EndSequence function is executed. If the call of acsc_EndSequence is omitted, the motion will stop at the last point of the sequence and wait for the next point. No transition to the next motion in the motion queue will occur until the acsc_EndSequence function executes. The function can wait for the controller response or can return immediately as specified by the Wait argument. This function applies to the single-axis multi-point or spline (arbitrary path) motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 243 C Library Functions
- 258. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_EndSequence int i; // create multi-point motion acsc_MultiPoint(Handle, 0, ACSC_AXIS_X, 1, NULL); // add some points for (i = 0; i < 5; i++) { acsc_AddPoint(Handle, ACSC_AXIS_X, 1000 * i, NULL); } // end of the multi-point motion if (!acsc_EndSequence( Handle, // communication handle ACSC_AXIS_X, // axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.22.6 acsc_EndSequenceM Description The function informs the controller, that no more points or segments will be specified for the current multi-axis motion. Syntax int acsc_EndSequence(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 244 C Library Functions
- 259. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The motion finishes when the acsc_EndSequenceM function is executed. If the call of acsc_EndSequenceM is omitted, the motion will stop at the last point or segment of the sequence and wait for the next point. No transition to the next motion in the motion queue will occur until the acsc_EndSequenceM function executes. The function can wait for the controller response or can return immediately as specified by the Wait argument. This function applies to the multi-axis multi-point, spline (arbitrary path) and segmented motions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 245 C Library Functions
- 260. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_EndSequenceM int Axes[] = { ACSC_AXIS_X, ACSC_AXIS_Y, -1 }; int Points[2]; int i; // create multi-point motion acsc_MultiPointM(Handle, 0, Axes, 0, NULL); // add some points for (i = 0; i < 5; i++) { Points[0] = 1000 * i; Points[1] = 1000 * i; // points (1000, 1000), (2000, 2000), … acsc_AddPointM(Handle, Axes, Points, NULL); } // the end of the multi-point motion if (!acsc_EndSequenceM( Handle, // communication handle Axes, // axes XY NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.23 Data Collection Functions The Data Collection functions are: Table 27 Data Collection Functions Function Description acsc_DataCollection Initiates data collection. acsc_StopCollect Terminates data collection. acsc_WaitCollectEnd Wait for the end of data collection. 4.23.1 acsc_DataCollection Description The function initiates data collection. Syntax int acsc_DataCollection(HANDLE Handle, int Flags, int Axis, char* Array, int NSample, int Period, char* Vars, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 246 C Library Functions
- 261. C Library Reference Version 6.50 Programmer’s Guide Flags Bit-mapped parameter that can include one or more of the following flags: • ACSC_DCF_SYNC: Start data collection synchronously to a motion. • ACSC_DCF_WAIT: Create the synchronous data collection, but do not start until the acsc_Go function is called. This flag can only be used with the ACSC_DCF_SYNC flag. • ACSC_DCF_TEMPORAL: Temporal data collection, the sampling period is calculated automatically according to the collection time. • ACSC_DCF_CYCLIC: Cyclic data collection uses the collection array as a cyclic buffer and continues indefinitely. When the array is full, each new sample overwrites the oldest sample in the array. Axis Axis to which the data collection must be synchronized. The parameter is required only for axis data collection (ACSC_DCF_SYNC flag). For a complete description of axis definitions see “Axis Definitions” on Page 378 Array Pointer to the null-terminated string contained the name of the array that stores the collected samples. The array must be declared as a global variable by an ACSPL+ program or by the acsc_DeclareVariable function. NSample Number of samples to be collected. Period Sampling period in milliseconds. If the ACSC_DCF_TEMPORAL flag is specified, this argument defines a minimal period. Vars Variable list - Pointer to null terminated string. The string contains chained names of the variables, separated by 'r'(13) character. The values of these variables will be collected in the Array. If variable name specifies an array, the name must be supplemented with indexes in order to specify one element of the array. 31 January 2009 247 C Library Functions
- 262. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Data collection started by this function without the ACSC_DCF_SYNC flag is called system data collection. Data collection started with the ACSC_DCF_SYNC flag is called axis data collection. Data collection started with the ACSC_DCF_CYCLIC flag is called cyclic data collection. Unlike the standard data collection that finishes when the collection array is full, cyclic data collection does not self-terminate. Cyclic data collection uses the collection array as a cyclic buffer and can continue to collect data indefinitely. When the array is full, each new sample overwrites the oldest sample in the array. Cyclic data collection can only be terminated by calling acsc_StopCollect function. The array that stores the samples can be one or two-dimensional. A one-dimensional array is allowed only if the variable list contains one variable name. The number of the array rows must be equal to or more than the number of variables in the variable list. The number of the array columns must be equal to or more than the number of samples specified by the NSample argument. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 248 C Library Functions
- 263. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_DataCollection // matrix consisting of two rows with 1000 columns each char* ArrayName = "DCA(2)(1000)"; // positions of axes X and Y will be collected char Vars[] ="FPOS(0)rFPOS(1)"; acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, ArrayName, NULL); if (!acsc_DataCollection (Handle,// communication handle ACSC_DCF_SYNC,// system data collection ArrayName,// name of data collection array 1000,// number of samples to be collected 1,// sampling period 1 millisecond Vars,// variables to be collected NULL// waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.23.2 acsc_StopCollect Description The function terminates data collection. Syntax int acsc_StopCollect(HANDLE Handle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 249 C Library Functions
- 264. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The usual system data collection finishes when the required number of samples is collected or the acsc_StopCollect function is executed. The application can wait for data collection end with the acsc_WaitCollectEnd function. The temporal data collection runs until the acsc_StopCollect function is executed. The function terminates the data collection prematurely. The application can determine the number of actually collected samples from the S_DCN variable and the actual sampling period from the S_DCP variable. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_StopCollect // matrix consisting of rows with 1000 columns each char* ArrayName = “DCA(2)(1000)”; // positions of axes X and Y will be collected char* Vars[] = { “FPOS(0)”, “FPOS(1)” }; acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, ArrayName, NULL); acsc_Collect(Handle, ACSC_DCF_TEMPORAL, ArrayName, 1000, 1, Vars, NULL); // waiting for some time Sleep(2000); if (!acsc_StopCollect(Handle, NULL)) { printf("transaction error: %dn", acsc_GetLastError()); } 4.23.3 acsc_WaitCollectEnd Description The function waits for the end of data collection. Syntax int acsc_WaitCollectEnd(HANDLE Handle, int Timeout) 31 January 2009 250 C Library Functions
- 265. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function does not return while the system data collection is in progress and the specified time-out interval has not elapsed. The function verifies the S_ST.#DC system flag. Example if (!acsc_WaitCollectEnd(Handle, // communication handle 30000 // during 30 sec )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.24 Status Report Functions The Status Report functions are: Table 28 Status Report Functions Function Description acsc_GetMotorState Retrieves the current motor state. acsc_GetAxisState Retrieves the current axis state. acsc_GetIndexState Retrieves the current state of the index and mark variables. acsc_ResetIndexState Resets the specified bit of the index/mark state. acsc_GetProgramState Retrieves the current state of the program buffer. 31 January 2009 251 C Library Functions
- 266. C Library Reference Version 6.50 Programmer’s Guide 4.24.1 acsc_GetMotorState Description The function retrieves the current motor state. Syntax int acsc_GetMotorState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. State Pointer to a variable that receives the current motor state. The parameter can include one or more of the following flags: • ACSC_MST_ENABLE — a motor is enabled • ACSC_MST_INPOS — a motor has reached a target position • ACSC_MST_MOVE — a motor is moving • ACSC_MST_ACC — a motor is accelerating Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 252 C Library Functions
- 267. C Library Reference Version 6.50 Programmer’s Guide Comments The function retrieves the current motor state. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the State and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetMotorState int State; if (!acsc_GetMotorState( Handle, // communication handle ACSC_AXIS_X, // axis X &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.24.2 acsc_GetAxisState Description The function retrieves the current axis state. Syntax int acsc_GetAxisState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see Axis Definitions. 31 January 2009 253 C Library Functions
- 268. C Library Reference Version 6.50 Programmer’s Guide State Pointer to a variable that receives the current axis state. The parameter can include one or more of the following flags: • ACSC_AST_LEAD – an axis is leading in a group • ACSC_AST_DC – an axis data collection is in progress • ACSC_AST_PEG – a PEG for the specified axis is in progress • ACSC_AST_MOVE – an axis is moving • ACSC_AST_ACC – an axis is accelerating • ACSC_AST_SEGMENT – a construction of segmented motion for the specified axis is in progress • ACSC_AST_VELLOCK – a slave motion for the specified axis is synchronized to master in velocity lock mode • ACSC_AST_POSLOCK - a slave motion for the specified axis is synchronized to master in position lock mode Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current axis state. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the State and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 254 C Library Functions
- 269. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetAxisState int State; if (!acsc_GetAxisState( Handle, // communication handle ACSC_AXIS_X, // axis X &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.24.3 acsc_GetIndexState Description The function retrieves the current set of bits that indicate the index and mark state. Syntax int acsc_GetIndexState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see Axis Definitions. State Pointer to a variable that receives the current set of bits that indicate the index and mark state. The parameter can include one or more of the following flags: • ACSC_IST_IND – a primary encoder index of the specified axis is latched • ACSC_IST_IND2 – a secondary encoder index of the specified axis is latched • ACSC_IST_MARK – a MARK1 signal has been generated and position of the specified axis was latched • ACSC_IST_MARK2 – a MARK2 signal has been generated and position of the specified axis was latched 31 January 2009 255 C Library Functions
- 270. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current set of bits that indicate the index and mark state. The controller processes index/mark signals as follows: When an index/mark signal is encountered for the first time, the controller latches feedback positions and raises the corresponding bit. As long as a bit is raised, the controller does not latch feedback position even if the signal occurs again. To resume latching logic, the application must call the acsc_ResetIndexState function to explicitly reset the corresponding bit. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the State and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetIndexState int State; if (!acsc_GetIndexState( Handle, // communication handle ACSC_AXIS_X, // axis X &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 256 C Library Functions
- 271. C Library Reference Version 6.50 Programmer’s Guide 4.24.4 acsc_ResetIndexState Description The function resets the specified bit of the index/mark state. Syntax int acsc_ResetIndexState(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see Axis Definitions. Mask The parameter contains bit to be cleared. Only one of the following flags can be specified: • ACSC_IST_IND – a primary encoder index of the specified axis is latched • ACSC_IST_IND2 – a secondary encoder index of the specified axis is latched Mask • ACSC_IST_MARK – a MARK1 signal has been generated and position of the specified axis was latched • ACSC_IST_MARK2 – a MARK2 signal has been generated and position of the specified axis was latched Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 257 C Library Functions
- 272. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function resets the specified bit of the index/mark state. The parameter Mask contains a bit, which must be cleared, i.e. the function resets only that bit of the index/mark state, which corresponds to non-zero bit of the parameter Mask. To get the current index/mark state, use acsc_GetIndexState function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_ResetIndexState if (!acsc_ResetIndexState(Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_IST_IND, // mentioned bit will be cleared NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); 4.24.5 acsc_GetProgramState Description The function retrieves the current state of the program buffer. Syntax int acsc_GetProgramState(HANDLE Handle, int Buffer, int* State, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Buffer Number of the buffer. 31 January 2009 258 C Library Functions
- 273. C Library Reference Version 6.50 Programmer’s Guide State Pointer to a variable that receives the current state of the program buffer. The parameter can include one or more of the following flags: • ACSC_PST_COMPILED – a program in the specified buffer is compiled • ACSC_PST_RUN – a program in the specified buffer is running • ACSC_PST_AUTO – an auto routine in the specified buffer is running • ACSC_PST_DEBUG – a program in the specified buffer is executed in debug mode, i.e. breakpoints are active • ACSC_PST_SUSPEND – a program in the specified buffer is suspended after the step execution or due to breakpoint in debug mode Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the program buffer. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the State and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 259 C Library Functions
- 274. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetProgramState int State; if (!acsc_GetProgramState( Handle, // communication handle 0, // buffer 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25 Input/Output Access Functions The Input/Output Access functions are: Table 29 Input/Output Access Functions (page 1 of 2) Function Description acsc_GetInput Retrieves the current state of the specified digital input. acsc_GetInputPort Retrieves the current state of the specified digital input port. acsc_GetInputPort Retrieves the current state of the specified digital input port. acsc_GetOutput Retrieves the current state of the specified digital output. acsc_GetOutputPort Retrieves the current state of the specified digital output port. acsc_SetOutput Sets the specified digital output to the specified value. acsc_SetOutputPort Sets the specified digital output port to the specified value. acsc_GetAnalogInput Retrieves the current numerical value of the specified analog inputs. acsc_GetAnalogOutput Retrieves the current numerical value of the specified analog outputs. acsc_SetAnalogOutput Writes the current numerical value to the specified analog outputs. acsc_GetExtInput Retrieves the current state of the specified extended input. acsc_GetExtInputPort Retrieves the current state of the specified extended input port. acsc_GetExtOutput Retrieves the current state of the specified extended output. acsc_GetExtOutputPort Retrieves the current state of the specified extended output port. 31 January 2009 260 C Library Functions
- 275. C Library Reference Version 6.50 Programmer’s Guide Table 29 Input/Output Access Functions (page 2 of 2) Function Description acsc_SetExtOutput Sets the specified extended output to the specified value. acsc_SetExtOutputPort Sets the specified extended output port to the specified value. 4.25.1 acsc_GetInput Description The function retrieves the current state of the specified digital input. Syntax int acsc_GetInput(HANDLE Handle, int Port, int Bit, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the input port. Bit Number of the specific bit. Value Pointer to a variable that receives the current state of the specific input. The value will be populated by 0 or 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 261 C Library Functions
- 276. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified digital input. To get values of all inputs of the specific port, use the acsc_GetInputPort function. Digital inputs are represented in the controller variable IN. For more information about digital inputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetInput // the function reads input 0 of port 0 ( IN(0).0 ) int State; if (!acsc_GetInput( Handle, // communication handle 0, // port 0 0, // bit 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.2 acsc_GetInputPort Description The function retrieves the current state of the specified digital input port. Syntax int acsc_GetInputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the input port. 31 January 2009 262 C Library Functions
- 277. C Library Reference Version 6.50 Programmer’s Guide Value Pointer to a variable that receives the current state of the specific input port. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified digital input port. To get the value of the specific input of the specific port, use the acsc_GetInput function. Digital inputs are represented in the controller variable IN. For more information about digital inputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetInputPort // the function reads input port 0 ( IN(0) ) int State; if (!acsc_GetInputPort( Handle, // communication handle 0, // port 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 263 C Library Functions
- 278. C Library Reference Version 6.50 Programmer’s Guide 4.25.3 acsc_GetOutput Description The function retrieves the current state of the specified digital output. Syntax int acsc_GetOutput(HANDLE Handle, int Port, int Bit, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the output port. Bit Number of the specific bit. Value Pointer to a variable that receives the current state of the specific output. The value will be populated by 0 or 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified digital output. To get values of all outputs of the specific port, use the acsc_GetOutputPort function. Digital outputs are represented in the controller variable OUT. For more information about digital outputs, see the SPiiPlus ACSPL+ Programmer’s Guide. 31 January 2009 264 C Library Functions
- 279. C Library Reference Version 6.50 Programmer’s Guide If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetOutput // the function reads output 0 of port 0 ( OUT(0).0 ) int State; if (!acsc_GetOutput( Handle, // communication handle 0, // port 0 0, // bit 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.4 acsc_GetOutputPort Description The function retrieves the current state of the specified digital output port. Syntax int acsc_GetOutputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the output port. Value Pointer to a variable that receives the current state of the specific output. The value will be populated by 0 or 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 265 C Library Functions
- 280. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified digital output port. To get the value of the specific output of the specific port, use the acsc_GetOutput function. Digital outputs are represented in the controller variable OUT. For more information about digital outputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetOutputPort // the function reads output port 0 ( OUT(0) ) int State; if (!acsc_GetOutputPort( Handle, // communication handle 0, // port 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.5 acsc_SetOutput Description The function sets the specified digital output to the specified value. Syntax int acsc_SetOutput(HANDLE Handle, int Port, int Bit, int Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 266 C Library Functions
- 281. C Library Reference Version 6.50 Programmer’s Guide Port Number of the output port. Bit Number of the specific bit. Value The value to be written to the specified output. Any non-zero value is interpreted as 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the specified digital output to the specified value. To set values of all outputs of a specific port, use the acsc_SetExtOutputPort function. Digital outputs are represented in the controller variable OUT. For more information about digital outputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 267 C Library Functions
- 282. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_SetOutput // the function sets output 0 of port 0 to 1 // ( ACSPL+ equivalent: OUT(0).0 = 1 ) if (!acsc_SetOutput( Handle, // communication handle 0, // port 0 0, // bit 0 1, // value to be set NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.6 acsc_SetOutputPort Description The function sets the specified digital output port to the specified value. Syntax int acsc_SetOutputPort(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the output port. Value The value to be written to the specified output port. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 268 C Library Functions
- 283. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the specified digital output port to the specified value. To set the value of the specific output of the specific port, use the acsc_SetOutput function. Digital outputs are represented in the controller variable OUT. For more information about digital outputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetOutputPort // the function sets first 4 outputs of port 0 to 1 // ( ACSPL+ equivalent: OUT(0) = 0x000F ) if (!acsc_SetOutputPort(Handle, // communication handle 0, // port 0 0x000F, // value to be set NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.7 acsc_GetAnalogInput Description The function retrieves the current numerical value of the specified analog inputs. Syntax int acsc_GetAnalogInput(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the analog inputs port. Value Pointer to a variable that receives the current value of the specific analog inputs. 31 January 2009 269 C Library Functions
- 284. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current numerical value of the specified analog inputs. Analog inputs are represented in the controller variable AIN. For more information about analog inputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetAnalogInput // the function reads analog inputs of port 0 ( AIN(0) ) int State; if (!acsc_GetAnalogInput(Handle, // communication handle 0, // port 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 270 C Library Functions
- 285. C Library Reference Version 6.50 Programmer’s Guide 4.25.8 acsc_GetAnalogOutput Description The function retrieves the current numerical value of the specified analog outputs. Syntax int acsc_GetAnalogOutput(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the output port. Value Pointer to a variable that receives the current numerical value of the specific analog outputs. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current numerical value of the specified analog outputs. To write a value to the specific analog outputs, use the acsc_SetAnalogOutput function. Analog outputs are represented in the controller variable AOUT. For more information about analog outputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or 31 January 2009 271 C Library Functions
- 286. C Library Reference Version 6.50 Programmer’s Guide delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetAnalogOutput // the function reads analog outputs of port 0 (AOUT(0) ) int State; if (!acsc_GetAnalogOutput(Handle, // communication handle 0, // port 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.9 acsc_SetAnalogOutput Description The function writes the current numerical value to the specified analog outputs. Syntax int acsc_SetAnalogOutput(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the output port. Value The value to be writes to the specific analog outputs. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 272 C Library Functions
- 287. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function writes the current numerical value to the specified analog outputs. To get a value of the specific analog outputs, use the acsc_GetAnalogOutput function. Analog outputs are represented in the controller variable AOUT. For more information about analog outputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetAnalogOutput // the function writes the value 100 to the analog outputs of port 0 // ( ACSPL+ equivalent: AOUT(0) = 100 ) if (!acsc_SetAnalogOutput( Handle, // communication handle 0, // port 0 100, // value to be written NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); 4.25.10 acsc_GetExtInput Description The function retrieves the current state of the specified extended input. Syntax int acsc_GetExtInput(HANDLE Handle, int Port, int Bit, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the extended input port. Bit Number of the specific bit. 31 January 2009 273 C Library Functions
- 288. C Library Reference Version 6.50 Programmer’s Guide Value Pointer to a variable that receives the current state of the specific input. The value will be populated by 0 or 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified extended input. To get values of all inputs of the specific extended port, use the acsc_GetExtInputPort function. Extended inputs are represented in the controller variable EXTIN. For more information about extended inputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetExtInput // the function reads extended input 0 of port 0 ( EXTIN(0).0 ) int State; if (!acsc_GetExtInput(Handle, // communication handle 0, // port 0 0, // bit 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 274 C Library Functions
- 289. C Library Reference Version 6.50 Programmer’s Guide 4.25.11 acsc_GetExtInputPort Description The function retrieves the current state of the specified extended input port. Syntax int acsc_GetExtInputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the extended input port. Value Pointer to a variable that receives the current state of the specific input port. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified extended input port. To get the value of the specific input of the specific extended port, use the acsc_GetExtInput function. Extended inputs are represented in the controller variable EXTIN. For more information about extended inputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or 31 January 2009 275 C Library Functions
- 290. C Library Reference Version 6.50 Programmer’s Guide delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetExtInputPort // the function reads extended input port 0 ( EXTIN(0) ) int State; if (!acsc_GetExtInputPort(Handle, // communication handle 0, // port 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.12 acsc_GetExtOutput Description The function retrieves the current state of the specified extended output. Syntax int acsc_GetExtOutput(HANDLE Handle, int Port, int Bit, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the extended output port. Bit Number of the specific bit. Value Pointer to a variable that receives the current state of the specific output. The value will be populated by 0 or 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 276 C Library Functions
- 291. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified extended output. To get values of all outputs of the specific extended port, use the acsc_GetExtOutputPort function. Extended outputs are represented in the controller variable EXTOUT. For more information about extended outputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetExtOutput // the function reads extended output 0 of port 0 ( EXTOUT(0).0 ) int State; if (!acsc_GetExtOutput( Handle, // communication handle 0, // port 0 0, // bit 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.13 acsc_GetExtOutputPort Description The function retrieves the current state of the specified extended output port. Syntax int acsc_GetExtOutputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK* Wait) 31 January 2009 277 C Library Functions
- 292. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Port Number of the extended output port. Value Pointer to a variable that receives the current state of the specific output. The value will be populated by 0 or 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified extended output port. To get the value of the specific output of the specific extended port, use the acsc_GetExtOutputPort function. Extended outputs are represented in the controller variable EXTOUT. For more information about extended outputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 278 C Library Functions
- 293. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetExtOutputPort // the function reads extended output port 0 ( EXTOUT(0) ) int State; if (!acsc_GetExtOutputPort( Handle, // communication handle 0, // port 0 &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.14 acsc_SetExtOutput Description The function sets the specified extended output to the specified value. Syntax int acsc_SetExtOutput(HANDLE Handle, int Port, int Bit, int Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Port Number of the extended output port. Bit Number of the specific bit. Value The value to be written to the specified output. Any non-zero value is interpreted as 1. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. 31 January 2009 279 C Library Functions
- 294. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the specified extended output to the specified value. To set values of all outputs of the specific extended port, use the acsc_SetExtOutputPort function. Extended outputs are represented in the controller EXTOUT variable. For more information about extended outputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetExtOutput // the function sets output 0 of extended port 0 to 1 // ( ACSPL+ equivalent: EXTOUT(0).0 = 1 ) if (!acsc_SetExtOutput(Handle, // communication handle 0, // port 0 0, // bit 0 1, // value to be set NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.25.15 acsc_SetExtOutputPort Description The function sets the specified extended output port to the specified value. Syntax int acsc_SetExtOutputPort(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK* Wait) 31 January 2009 280 C Library Functions
- 295. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Port Number of the extended output port. Value The value written to the specified output port. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the specified extended output port to the specified value. To set the value of the specific output of the specific extended port, use the acsc_SetExtOutput function. Extended outputs are represented in the controller variable EXTOUT. For more information about extended outputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 281 C Library Functions
- 296. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_SetExtOutputPort // the function sets first 4 outputs of extended port 0 to 1 // ( ACSPL+ equivalent: EXTOUT(0) = 0x000F ) if (!acsc_SetExtOutputPort(Handle, // communication handle 0, // port 0 0x000F, // value to be set NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26 Safety Control Functions The Safety Control functions are: Table 30 Safety Control Functions (page 1 of 2) Function Description acsc_GetFault Retrieves the set of bits that indicate the motor or system faults. acsc_SetFaultMask Sets the mask, that enables/disables the examination and processing of the controller faults. acsc_GetFaultMask Retrieves the mask that defines which controller faults are examined and processed. acsc_EnableFault Enables the specified motor or system fault. acsc_DisableFault Disables the specified motor or system fault. acsc_SetResponseMask Sets the mask that defines for which motor or system faults the controller provides default response. acsc_GetResponseMask Retrieves the mask that defines for which motor or system faults the controller provides default response. acsc_EnableResponse Enables the default response to the specified motor or system fault. acsc_DisableResponse Disables the default response to the specified motor or system fault. acsc_GetSafetyInput Retrieves the current state of the specified safety input. acsc_GetSafetyInputPort Retrieves the current state of the specified safety input port. acsc_GetSafetyInputPortInv Retrieves the set of bits that define inversion for the specified safety input port. acsc_SetSafetyInputPortInv Sets the set of bits that define inversion for the specified safety input port. 31 January 2009 282 C Library Functions
- 297. C Library Reference Version 6.50 Programmer’s Guide Table 30 Safety Control Functions (page 2 of 2) Function Description acsc_FaultClear The function clears the current faults and results of previous faults stored in the MERR variable. acsc_FaultClearM The function clears the current faults and results of previous faults stored in the MERR variable for multiple axis. 4.26.1 acsc_GetFault Description The function retrieves the set of bits that indicate the motor or system faults. Syntax int acsc_GetFault(HANDLE Handle, int Axis, int* Fault, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to receive the motor faults or ACSC_NONE to receive the system faults. For the full list of the axis constants, see Axis Definitions. Fault Pointer to the variable that receives the current set of fault bits. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 283 C Library Functions
- 298. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the set of bits that indicate motor or system faults. Motor faults are related to a specific motor, the power amplifier, and the Servo processor. For example: Position Error, Encoder Error, or Driver Alarm. System faults are not related to any specific motor. For example: Emergency Stop or Memory Fault. The parameter Fault receives the set of bits that indicates the controller faults. To recognize the specific fault, constants ACSC_SAFETY_*** can be used. See Safety Control Masks for a detailed description of these constants. For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Fault and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetFault int Fault; if (!acsc_GetFault( Handle, // communication handle ACSC_AXIS_X, // axis X &Fault, // received set of faults NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } if (Fault & ACSC_SAFETY_RL)printf("Right Limit faultn”); if (Fault & ACSC_SAFETY_LL)printf("Left Limit faultn”); 4.26.2 acsc_SetFaultMask Description The function sets the mask that enables or disables the examination and processing of controller faults. Syntax int acsc_SetFaultMask(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK* Wait) 31 January 2009 284 C Library Functions
- 299. C Library Reference Version 6.50 Programmer’s Guide Warning Certain controller faults provide protection against potential serious bodily injury and damage to the equipment. Be aware of the implications before disabling any alarm, limit, or error. Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to mask the motor faults, or ACSC_NONE to mask the system faults. For the full list of the axis constants, see Axis Definitions. Mask The mask to be set: If a bit of the Mask is zero, the corresponding fault is disabled. To set/reset a specified bit, use ACSC_SAFETY_*** constants. See Safety Control Masks for a detailed description of these constants. If the Mask is ACSC_NONE, then all the faults for the specified axis are enabled. If the Mask is zero, then all the faults for the specified axis are disabled. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 285 C Library Functions
- 300. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the mask that enables/disables the examination and processing of the controller faults. The two types of controller faults are motor faults and system faults. The motor faults are related to a specific motor, the power amplifier or the Servo processor. For example: Position Error, Encoder Error or Driver Alarm. The system faults are not related to any specific motor. For example: Emergency Stop or Memory Fault. For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetFaultMask if (!acsc_SetFaultMask( Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_NONE, // enable all faults NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.3 acsc_GetFaultMask Description The function retrieves the mask that defines which controller faults are examined and processed. Syntax int acsc_GetFaultMask(HANDLE Handle, int Axis, int* Mask, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle 31 January 2009 286 C Library Functions
- 301. C Library Reference Version 6.50 Programmer’s Guide Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to get the motor faults mask, or ACSC_NONE to get the system faults mask. For the full list of the axis constants, see Axis Definitions. Mask The current faults mask. If a bit of Mask is zero, the corresponding fault is disabled. Use the ACSC_SAFETY_*** constants to examine the specified bit. See Safety Control Masks for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the mask, defining which controller faults are examined and processed. If a bit of the parameter Mask is zero, the corresponding fault is disabled. The controller faults are of two types: motor faults and system faults. The motor faults are related to a specific motor, the power amplifier or the Servo processor. For example: Position Error, Encoder Error or Driver Alarm. The system faults are not related to any specific motor, for example: Emergency Stop or Memory Fault. For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or 31 January 2009 287 C Library Functions
- 302. C Library Reference Version 6.50 Programmer’s Guide delete the Mask and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetFaultMask int Mask; if (!acsc_GetFaultMask( Handle, // communication handle ACSC_AXIS_X, // axis X &Mask, // current mask NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.4 acsc_EnableFault Description The function enables the specified motor or system fault. Syntax int acsc_EnableFault(HANDLE Handle, int Axis, int Fault, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to enable the motor fault or ACSC_NONE to enable the system fault. For the full list of the axis constants, see Axis Definitions. Fault The fault to be enabled. Only one fault can be enabled at a time. To specify the fault, one of the constants ACSC_SAFETY_*** can be used. See Safety Control Masks for a detailed description of these constants. 31 January 2009 288 C Library Functions
- 303. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the acsc_WaitForAsyncCall function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function enables the examination and processing of the specified motor or system fault by setting the specified bit of the fault mask to one. The motor faults are related to a specific motor, the power amplifier, and the Servo processor. For example: Position Error, Encoder Error, and Driver Alarm. The system faults are not related to any specific motor. For example: Emergency Stop, Memory Fault. For more information about the controller faults, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 289 C Library Functions
- 304. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_EnableFault if (!acsc_EnableFault( Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_SAFETY_PE, // enable fault Position // Error NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.5 acsc_DisableFault Description The function disables the specified motor or system fault. Syntax int acsc_DisableFault(HANDLE Handle, int Axis, int Fault, ACSC_WAITBLOCK* Wait) Warning Certain controller faults provide protection against potential serious bodily injury and damage to the equipment. Be aware of the implications before disabling any alarm, limit, or error. Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to disable the motor faults or ACSC_NONE to disable the system faults. For the full list of the axis constants, see Axis Definitions. Fault The fault to be disabled. Only one fault can be disabled at a time. To specify the fault, one of the constants ACSC_SAFETY_*** can be used. See Safety Control Masks for a detailed description of these constants. 31 January 2009 290 C Library Functions
- 305. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function disables the examination and processing of the specified motor or system fault by setting the specified bit of the fault mask to zero. The motor faults are related to a specific motor, the power amplifier, and the Servo processor. For example: Position Error, Encoder Error, and Driver Alarm. The system faults are not related to any specific motor, for example: Emergency Stop, Memory Fault. For more information about the controller faults, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_DisableFault if (!acsc_DisableFault( Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_SAFETY_VL, // disable fault Velocity // Limit NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 291 C Library Functions
- 306. C Library Reference Version 6.50 Programmer’s Guide 4.26.6 acsc_SetResponseMask Description The function retrieves the mask that defines the motor or the system faults for which the controller provides the default response. Syntax int acsc_SetResponseMask(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK* Wait) Warning Certain controller faults provide protection against potential serious bodily injury and damage to the equipment. Be aware of the implications before disabling any alarm, limit, or error. Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to set the mask of responses to the motor faults, or ACSC_NONE to set the mask of responses to the system faults. For the full list of the axis constants, see Axis Definitions. Mask The mask to be set. If a bit of Mask is zero, the corresponding default response is disabled. Use the ACSC_SAFETY_*** constants to set/reset a specified bit. See Safety Control Masks for a detailed description of these constants. If Mask is ACSC_NONE, all default responses for the specified axis are enabled. If Mask is zero, all default responses for the specified axis are disabled. 31 January 2009 292 C Library Functions
- 307. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the mask that defines the motor or the system faults for which the controller provides the default response. The default response is a controller-predefined action for the corresponding fault. For more information about the controller faults and default responses, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_SetResponseMask if (!acsc_SetResponseMask( Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_NONE, // enable all default responses NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 293 C Library Functions
- 308. C Library Reference Version 6.50 Programmer’s Guide 4.26.7 acsc_GetResponseMask Description The function retrieves the mask that defines the motor or the system faults for which the controller provides the default response. Syntax int acsc_GetResponseMask(HANDLE Handle, int Axis, int* Mask, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to get the mask of responses to the motor faults, or ACSC_NONE to get the mask of responses to the system faults. For the full list of the axis constants, see Axis Definitions. Mask The current mask of default responses. If a bit of Mask is zero, the corresponding default response is disabled. Use the ACSC_SAFETY_*** constants to examine the specified bit. See Safety Control Masks for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 294 C Library Functions
- 309. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the mask that defines the motor or the system faults for which the controller provides the default response. If a bit of the parameter Mask is zero, the controller does not provide a default response to the corresponding fault. The default response is a controller-predefined action for the corresponding fault. For more information about the controller faults and default, responses see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Mask and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetResponseMask int Mask; if (!acsc_GetResponseMask( Handle, // communication handle ACSC_AXIS_X, // axis X &Mask, // current responses mask NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.8 acsc_EnableResponse Description The function enables the response to the specified motor or system fault. Syntax int acsc_EnableResponse(HANDLE Handle, int Axis, int Response, ACSC_WAITBLOCK* Wait) 31 January 2009 295 C Library Functions
- 310. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to enable the response to the specified motor fault, or ACSC_NONE to enable the response to the specified system fault. For the full list of the axis constants, see Axis Definitions. Response The default response to be enabled. Only one default response can be enabled at a time. To specify the default response, one of the constants ACSC_SAFETY_*** can be used. See Safety Control Masks for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function enables the default response to the specified motor or system fault by setting the specified bit of the response mask to one. The default response is a controller-predefined action for the corresponding fault. For more information about the controller faults and default responses, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or 31 January 2009 296 C Library Functions
- 311. C Library Reference Version 6.50 Programmer’s Guide delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_EnableResponse if (!acsc_EnableResponse(Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_SAFETY_PE, // enable the default // response to the Position // Error fault NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.9 acsc_DisableResponse Description The function disables the default response to the specified motor or system fault. Syntax int acsc_DisableResponse(HANDLE Handle, int Axis, int Response, ACSC_WAITBLOCK* Wait) Warning Certain controller faults provide protection against potential serious bodily injury and damage to the equipment. Be aware of the implications before disabling any alarm, limit, or error. Arguments Handle Communication handle Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to disable the default response to the specified motor fault, or ACSC_NONE to disable response to the specified system fault. For the full list of the axis constants, see Axis Definitions. 31 January 2009 297 C Library Functions
- 312. C Library Reference Version 6.50 Programmer’s Guide Response The response to be disabled. Only one default response can be disabled at a time. To specify the fault, one of the constants ACSC_SAFETY_*** can be used. See Safety Control Masks for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function disables the default response to the specified motor or system fault by setting the specified bit of the response mask to zero. The default response is a controller-predefined action for the corresponding fault. For more information about the controller faults and default responses, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 298 C Library Functions
- 313. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_DisableResponse if (!acsc_DisableResponse( Handle, // communication handle ACSC_AXIS_X, // axis X ACSC_SAFETY_VL, // disable the default // response to the // Velocity Limit fault NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.10 acsc_GetSafetyInput Description The function retrieves the current state of the specified safety input. Syntax int acsc_GetSafetyInput(HANDLE Handle, int Axis, int Input, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to get the specified safety motor input, or ACSC_NONE to get the specified system safety input. For the full list of the axis constants, see “Axis Definitions” on Page 378. Input The specific safety input. To specify a desired motor safety input OR combination of any of the following constants can be used: • ACSC_SAFETY_RL • ACSC_SAFETY_LL • ACSC_SAFETY_RL2 • ACSC_SAFETY_LL2 • ACSC_SAFETY_HOT • ACSC_SAFETY_DRIVE • ACSC_SAFETY_ES See Safety Control Masks for a detailed description of these constants. 31 January 2009 299 C Library Functions
- 314. C Library Reference Version 6.50 Programmer’s Guide Value Pointer to a variable that receives the current state of the specified inputs. The value will be populated by 0 or 1. The value will receive 1 if any of the specified safety inputs in the Input field is on. Otherwise, it receives 0. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified safety input. To get values of all safety inputs of the specific axis, use the acsc_GetSafetyInput function. Safety inputs are represented in the controller variables SAFIN and S_SAFIN. For more information about safety inputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Note Some safety inputs can be unavailable in a specific controller model. For example, SPiiPlus SA controller does not provide Motor Overheat, Preliminary Left Limit, and Preliminary Right Limit safety inputs. See specific model documentation for details. 31 January 2009 300 C Library Functions
- 315. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetSafetyInput // the function reads Emergency Stop system safety input int State; if (!acsc_GetSafetyInput( Handle, // communication handle ACSC_NONE, // system safety input // port ACSC_SAFETY_ES, // Emergency Stop safety // input &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.11 acsc_GetSafetyInputPort Description The function retrieves the current state of the specified safety input port. Syntax int acsc_GetSafetyInputPort(HANDLE Handle, int Axis, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to get the specified safety motor inputs port, or ACSC_NONE to get the specified safety system inputs port. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 301 C Library Functions
- 316. C Library Reference Version 6.50 Programmer’s Guide Value Pointer to a variable that receives the current state of the specific safety input port. To recognize a specific motor safety input, only one of the following constants can be used: • ΑCSC_SAFETY_RL • ACSC_SAFETY_LL • ACSC_SAFETY_RL2 • ACSC_SAFETY_LL2 • ACSC_SAFETY_HOT • ACSC_SAFETY_DRIVE To recognize a specific system safety input, only ACSC_SAFETY_ES constant can be used. See Safety Control Masks for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the current state of the specified safety input port. To get the state of the specific safety input of a specific axis, use the acsc_GetSafetyInput function. Safety inputs are represented in the controller variables SAFIN and S_SAFIN. For more information about safety inputs, see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 302 C Library Functions
- 317. C Library Reference Version 6.50 Programmer’s Guide Note Some safety inputs can be unavailable in a specific controller model. For example, SPiiPlus SA controller does not provide Motor Overheat, Preliminary Left Limit, and Preliminary Right Limit safety inputs. See specific model documentation for details. Example // example of the waiting call of acsc_GetSafetyInputPort // the function reads safety input port of the axis X int State; if (!acsc_GetSafetyInputPort( Handle, // communication handle ACSC_AXIS_X, // axis X &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.26.12 acsc_GetSafetyInputPortInv Description The function retrieves the set of bits that define inversion for the specified safety input port. Syntax int acsc_GetSafetyInputPortInv(HANDLE Handle, int Axis, int* Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to get the inversion for the specified safety motor inputs port, or ACSC_NONE to get the inversion for the specified safety system inputs port. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 303 C Library Functions
- 318. C Library Reference Version 6.50 Programmer’s Guide Value Pointer to a variable that receives the set of bits that define inversion for the specific safety input port. To recognize a specific bit, use the following constants: • ACSC_SAFETY_RL • ACSC_SAFETY_LL • ACSC_SAFETY_RL2 • ACSC_SAFETY_LL2 • ACSC_SAFETY_HOT • ACSC_SAFETY_DRIVE Use the ACSC_SAFETY_ES constant to recognize an inversion for the specific system safety input port,. See “Safety Control Masks” on Page 387 for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the set of bits that define inversion for the specified safety input port. To set the specific inversion for the specific safety input port, use the acsc_GetSafetyInputPortInv function. If a bit of the retrieved set is zero, the corresponding signal is not inverted and therefore high voltage is considered an active state. If a bit is raised, the signal is inverted and low voltage is considered an active state. 31 January 2009 304 C Library Functions
- 319. C Library Reference Version 6.50 Programmer’s Guide The inversions of safety inputs are represented in the controller variables SAFINI and S_SAFINI. For more information about safety inputs, see the SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function. Note Some safety inputs can be unavailable in a specific controller model. For example, SPiiPlus SA controller does not provide Motor Overheat, Preliminary Left Limit, and Preliminary Right Limit safety inputs. See specific model documentation for details. Example // example of the waiting call of acsc_GetSafetyInputPortInv // the function reads an inversion of safety input port of the axis X int State; if (!acsc_GetSafetyInputPortInv(Handle, // communication handle ACSC_AXIS_X, // axis X &State, // received value NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 305 C Library Functions
- 320. C Library Reference Version 6.50 Programmer’s Guide 4.26.13 acsc_SetSafetyInputPortInv Description The function sets the set of bits that define inversion for the specified safety input port. Syntax int acsc_SetSafetyInputPortInv(HANDLE Handle, int Axis, int Value, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis The parameter specifies the axis (ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc.) to set the specified safety motor inputs port, or ACSC_NONE to set the specified safety system inputs port. For the full list of the axis constants, see “Axis Definitions” on Page 378. Value The specific inversion. To set a specific bit, use the following constants: ACSC_SAFETY_RL, ACSC_SAFETY_LL, ACSC_SAFETY_RL2, ACSC_SAFETY_LL2, ACSC_SAFETY_HOT, ACSC_SAFETY_DRIVE. To set an inversion for the specific system safety input port, use only the ACSC_SAFETY_ES constant. See Safety Control Masks for a detailed description of these constants. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 306 C Library Functions
- 321. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the bits that define inversion for the specified safety input port. To retrieve an inversion for the specific safety input port, use the acsc_GetSafetyInputPortInv function. If a bit of the set is zero, the corresponding signal will not be inverted and therefore high voltage is considered an active state. If a bit is raised, the signal will be inverted and low voltage is considered an active state. The inversions of safety inputs are represented in the controller variables SAFINI and S_SAFINI. For more information about safety, inputs see SPiiPlus ACSPL+ Programmer’s Guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Note Some safety inputs can be unavailable in a specific controller model. For example, SPiiPlus SA controller does not provide Motor Overheat, Preliminary Left Limit, and Preliminary Right Limit safety inputs. See specific model documentation for details. Example // example of the waiting call of acsc_SetSafetyInputPortInv // the function sets the inversion for safety input port of the axis X int State; if (!acsc_SetSafetyInputPortInv(Handle, // communication handle ACSC_AXIS_X, // axis X State, // inversion that will be set NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 307 C Library Functions
- 322. C Library Reference Version 6.50 Programmer’s Guide 4.26.14 acsc_FaultClear Description The function clears the current faults and the result of the previous fault stored in the MERR variable. Syntax int acsc_FaultClear(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function clears the current faults of the specified axis and the result of the previous fault stored in the MERR variable. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 308 C Library Functions
- 323. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_Disable if (!acsc_FaultClear (Handle, // communication handle ACSC_AXIS_X, // disable of axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); 4.26.15 acsc_FaultClearM Description The function clears the current faults and results of previous faults stored in the MERR variable for multiple axes. Syntax int acsc_FaultClearM(HANDLE Handle, int *Axes, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axes Array of axes. Each element specifies one involved axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. After the last axis, one additional element must be located that contains –1 and marks the end of the array. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 309 C Library Functions
- 324. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. If the reason for the fault is still active, the controller will set the fault immediately after this command is performed. If cleared fault is Encoder Error, the feedback position is reset to zero. Example // example of the waiting call of acsc_FclearM int Axes[]={ACSC_AXIS_X,ACSC_AXIS_Y,-1}; if (!acsc_FaultClearM(Handle, // communication handle Axes, NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 310 C Library Functions
- 325. C Library Reference Version 6.50 Programmer’s Guide 4.27 Wait-for-Condition Functions The Wait-for-Condition functions are: Table 31 Wait-for-Condition Functions Function Description acsc_WaitMotionEnd Waits for the end of a motion. acsc_WaitLogicalMotionEnd Waits for the logical end of a motion. acsc_WaitForAsyncCall Waits for the end of data collection. acsc_WaitProgramEnd Waits for the program termination in the specified buffer. acsc_WaitMotorEnabled Waits for the specified state of the specified motor. acsc_WaitInput Waits for the specified state of the specified digital input. acsc_WaitUserCondition Waits for user-defined condition. acsc_WaitMotorCommutated Waits for the specified motor to be commutated. 4.27.1 acsc_WaitMotionEnd Description The function waits for the end of a motion. Syntax int acsc_WaitMotionEnd (HANDLE Handle, int Axis, int Timeout) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 311 C Library Functions
- 326. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function does not return while the specified axis is involved in a motion, the motor has not settled in the final position and the specified time-out interval has not elapsed. The function differs from the acsc_WaitLogicalMotionEnd function. Examining the same motion, the acsc_WaitMotionEnd function will return latter. The acsc_WaitLogicalMotionEnd function returns when the generation of the motion finishes. On the other hand, the acsc_WaitMotionEnd function returns when the generation of the motion finishes and the motor has settled in the final position. Example if (!acsc_WaitMotionEnd(Handle, // communication handle ACSC_AXIS_X, // wait for the end of motion of axis X 30000 // during 30 sec )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.27.2 acsc_WaitLogicalMotionEnd Description The function waits for the logical end of a motion. Syntax int acsc_WaitLogicalMotionEnd (HANDLE Handle, int Axis, int Timeout) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. The axis must be either a single axis not included in any group or a leading axis of a group. 31 January 2009 312 C Library Functions
- 327. C Library Reference Version 6.50 Programmer’s Guide Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function does not return while the specified axis is involved in a motion and the specified time-out interval has not elapsed. The function differs from the acsc_WaitMotionEnd function. Examining the same motion, the acsc_WaitMotionEnd function will return later. The acsc_WaitLogicalMotionEnd function returns when the generation of the motion finishes. On the other hand, the acsc_WaitMotionEnd function returns when the generation of the motion finishes and the motor has settled in the final position. Example if (!acsc_WaitLogicalMotionEnd(Handle, // communication handle ACSC_AXIS_X, // wait for the logical end of motion of axis X 30000 // during 30 sec )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.27.3 acsc_WaitForAsyncCall Description The function waits for completion of asynchronous call and retrieves a data. Syntax int acsc_WaitForAsyncCall(HANDLE Handle, void* Buf, int* Received, ACSC_WAITBLOCK* Wait, int Timeout) 31 January 2009 313 C Library Functions
- 328. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Buf Pointer to the buffer that receives controller response. This parameter must be the same pointer that was specified for asynchronous call of SPiiPlus C function. If the SPiiPlus C function does not accept a buffer as a parameter, Buf has to be NULL pointer. Received Number of characters that were actually received. Wait Pointer to the same ACSC_WAITBLOCK structure that was specified for asynchronous call of SPiiPlus C function. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. The Ret field of Wait contains the error code that the non-waiting call caused. If Wait.Ret is zero, the call succeeded: no errors occurred. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function waits for completion of asynchronous call, corresponds to the Wait parameter, and retrieves controller response to the buffer pointed by Buf. The Wait and Buf must be the same pointers passed to SPiiPlus C function when asynchronous call was initiated. If the call of SPiiPlus C function was successful, the function retrieves controller response to the buffer Buf. The Received parameter will contain the number of actually received characters. If the call of SPiiPlus C function does not return a response (for example: acsc_Enable, acsc_Jog, etc.) Buf has to be NULL. If the call of SPiiPlus C function returned the error, the function retrieves this error code in the Ret member of the Wait parameter. If the SPiiPlus C function has not been completed in Timeout milliseconds, the function aborts specified asynchronous call and returns ACSC_TIMEOUT error. If the call of SPiiPlus C function has been aborted by the acsc_CancelOperation function, the 31 January 2009 314 C Library Functions
- 329. C Library Reference Version 6.50 Programmer’s Guide function returns ACSC_OPERATIONABORTED error. Example char* cmd = "?VRr";// get firmware version char buf[101]; int Received; ACSC_WAITBLOCK wait; if (!acsc_Transaction(Handle, cmd, strlen(cmd), buf, 100, &Received, &wait)) { printf("transaction error: %dn", acsc_GetLastError()); } else { // call is pending if (acsc_WaitForAsyncCall(Handle, // communication handle buf, // pointer to the same buffer, that was specified // for acsc_Transaction &Received, // received bytes &wait, // pointer to the same structure, that was // specified for acsc_Transaction 500 // 500 ms )) { buf[Received] = ‘0’; printf(“Firmware version: %sn”, buf); } else { acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received); buf[Received] = ‘0’; printf("error: %sn", buf); } } 4.27.4 acsc_WaitProgramEnd Description The function waits for the program termination in the specified buffer. Syntax int acsc_WaitProgramEnd (HANDLE Handle, int Buffer, int Timeout) Arguments Handle Communication handle. Buffer Buffer number, from 0 to 9. 31 January 2009 315 C Library Functions
- 330. C Library Reference Version 6.50 Programmer’s Guide Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function does not return while the ACSPL+ program in the specified buffer is in progress and the specified time-out interval has not elapsed. Example if (!acsc_WaitProgramEnd(Handle, // communication handle 0, // buffer 0 30000 // during 30 sec )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.27.5 acsc_WaitMotorEnabled Description The function waits for the specified state of the specified motor. Syntax int acsc_WaitMotorEnabled (HANDLE Handle, int Axis, int State, int Timeout) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. 31 January 2009 316 C Library Functions
- 331. C Library Reference Version 6.50 Programmer’s Guide State 1 – the function wait for the motor enabled, 0 – the function wait for the motor disabled. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function does not return while the specified motor is not in the desired state and the specified time-out interval has not elapsed. The function examines the MST.#ENABLED motor flag. Example If( !acsc_WaitMotorEnabled(Handle, //communication handle ACSC_AXIS_X, //axis X 1, //wait untill the motor is enabled 30000 // during 30 sec )) { printf("WaitMotorEnabled error: %dn", acsc_GetLastError() ); } 4.27.6 acsc_WaitInput Description The function waits for the specified state of digital input. Syntax int acsc_WaitInput (HANDLE Handle, int Port, int Bit, int State, int Timeout) Arguments Handle Communication handle. 31 January 2009 317 C Library Functions
- 332. C Library Reference Version 6.50 Programmer’s Guide Port Number of input port: 0 corresponds to IN0, 1 – to IN1, etc. Bit Selects one bit from the port, from 0 to 31. State Specifies a desired state of the input, 0 or 1. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The basic configuration of the SPiiPlus PCI model provides only 16 inputs. Therefore, the Port must be 0, and the Bit can be specified from 0 to 15. Example if (!acsc_WaitInput(Handle, // communication handle 0, // IN0 0, // IN0.0 1, // wait for IN0.0 = 1 30000 // during 30 sec )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.27.7 acsc_WaitUserCondition Description The function waits for the user-defined condition. Syntax int acsc_WaitUserCondition(HANDLE Handle, ACSC_USER_CONDITION_FUNC UserCondition, int Timeout) 31 January 2009 318 C Library Functions
- 333. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. UserCondition A pointer to a user-defined function that accepts an argument of HANDLE type and returns the result of integer type. Its prototype is: int WINAPI UserCondition (HANDLE Handle); Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function calls the UserCondition function in order to determine the termination moment. While the UserCondition function returns zero and the specified time-out interval has not elapsed, the acsc_WaitUserCondition function calls UserCondition periodically. Once the UserCondition function returns non-zero results, the acsc_WaitUserCondition function also returns. The UserCondition function accepts as argument the Handle parameter, passed to the function acsc_WaitUserCondition. If the condition is satisfied, the UserCondition function returns 1, if it is not satisfied – 0. In case of an error the UserCondition function returns –1. 31 January 2009 319 C Library Functions
- 334. C Library Reference Version 6.50 Programmer’s Guide Example // In the example the UserCondition function checks when the feedback // position of the motor X will reach 100000. int WINAPI UserCondition(HANDLE Handle) { double FPos; if (acsc_ReadReal(Handle, ACSC_NONE, "FPOS", 0, 0, ACSC_NONE, ACSC_NONE, &FPos, NULL)) { if (FPos > 100000) return 1; } else return –1; // error is occurred return 0; // continue waiting } ….. // wait while FPOS arrives at point 100000 if (!acsc_WaitUserCondition(Handle, // communication handle UserCondition, // pointer to the user-defined function 30000 // during 30 sec { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 320 C Library Functions
- 335. C Library Reference Version 6.50 Programmer’s Guide 4.27.8 acsc_WaitMotorCommutated Description The function waits for the specified motor to be commutated. Syntax int acsc_WaitMotorCommutated (HANDLE Handle, int Axis, int State, int Timeout) Arguments Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. State 1 - The function waits for the motor to be commutated. Timeout Maximum waiting time in milliseconds. If Timeout is INFINITE, the function's time-out interval never elapses. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Extended error information can be obtained by calling acsc_GetLastError. Comments The function does not return while the specified motor is not in the desired state and the specified time-out interval has not elapsed. The function examines the MFLAGS.#BRUSHOK flag. Example if (!acsc_WaitMotorCommutated( Handle, // communication handle ACSC_AXIS_X,// buffer 0 TRUE, // wait until motor is commutated 30000 // during 30 sec )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 321 C Library Functions
- 336. C Library Reference Version 6.50 Programmer’s Guide 4.28 Callback Registration Functions The Callback Registration functions are: Table 32 Callback Registration Functions Function Description acsc_SetCallback Installs a user-defined callback function for the specified interrupt condition. acsc_SetCallbackExt Installs a user-defined callback function for the specified interrupt condition with user-defined parameter. acsc_SetCallbackExt Sets the mask for the specified interrupt. acsc_SetCallbackExt Retrieves the mask for the specified interrupt. acsc_SetCallbackPriority Sets the priority for all callback threads. 4.28.1 acsc_SetCallback Description The function installs a user-defined callback function for the specified interrupt condition. Syntax int acsc_SetCallback(HANDLE Handle, ACSC_INTR_CALLBACK_FUNC Callback, int Interrupt) Arguments Handle Communication handle. Callback A pointer to a user-defined function that accepts an argument of integer type and returns the result of integer type. Its prototype is: int WINAPI Callback(int Param); If Callback is NULL, the function resets previous installed callback for the corresponding Interrupt. If Callback has no functionality and is set only for the corresponding acsc_Waitxxx function, this parameter may be set as acsc_dummy_callback. Interrupt See Callback Interrupts. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 322 C Library Functions
- 337. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function installs a user-defined callback function Callback for the specified interrupt condition Interrupt. The library calls the Callback function when the specified interrupt occurs. The bit-mapped parameter Param of the function Callback identifies which axis/buffer/input the interrupt was generated for. See Callback Interrupt Masks for a detailed description of the parameter Param for each interrupt. One callback can be installed for each interrupt. The library creates a separate thread for each interrupt. Therefore, each callback function is called in a separate thread so that the callbacks do not delay one another. To uninstall a specific callback, call the function acsc_SetCallbackwith the parameter Callback equal to NULL and the parameter Interrupt equal to the specified interrupt type. Note Before the PEG interrupts can be detected, the acsc_AssignPins function must be called. 31 January 2009 323 C Library Functions
- 338. C Library Reference Version 6.50 Programmer’s Guide Example int WINAPI CallbackInput (int Param);// will be defined later …. // set callback function to monitor digital inputs if (!acsc_SetCallback(Handle, // communication handle CallbackInput, // pointer to the user callback function ACSC_INTR_INPUT // Type of callback )) { printf("callback registration error: %dn", acsc_GetLastError()); } …. // If callback was installed successfully, the CallbackInput function will // be called each time the any digital input has changed from 0 to 1. // CallbackInput function checks the digital inputs 0 and 1 int WINAPI CallbackInput (int Param) { if (Param & ACSC_MASK_INPUT_0) { // input 0 has changed from 0 to 1 // doing something here … } if (Param & ACSC_MASK_INPUT_1) { // input 1 has changed from 0 to 1 // doing something here … } return 0; } 31 January 2009 324 C Library Functions
- 339. C Library Reference Version 6.50 Programmer’s Guide 4.28.2 acsc_SetCallbackExt Description The function installs a user-defined callback function for the specified interrupt condition with user-defined parameter. Syntax int acsc_SetCallbackExt(HANDLE Handle, ACSC_INTR_CALLBACK_FUNC_EXT Callback,void* UserParameter,int Interrupt) Arguments Handle Communication handle. Callback A pointer to a user-defined function that accepts an argument of integer type and returns the result of integer type. Its prototype is: int WINAPI Callback(int Param); If Callback is NULL, the function resets previous installed callback for the corresponding Interrupt. If Callback should have no functionality and is set only for corresponding acsc_Waitxxx function, this parameter may be set as acsc_dummy_callback_ext. UserParameter Additional parameter that will be passed to the callback function Interrupt See Callback Interrupts. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function installs a user-defined callback function Callback for the specified interrupts condition Interrupt. The library calls the Callback function when the specified interrupt occurs. The bit-mapped parameter Param of the function Callback identifies for which axis/buffer/input the interrupt was generated. See Callback Interrupt Masks for a detailed description of the parameter Param for each interrupt. 31 January 2009 325 C Library Functions
- 340. C Library Reference Version 6.50 Programmer’s Guide One callback can be installed for each interrupt, for same communication channel. The library creates a separate thread for each interrupt. Therefore, each callback function is called in a separate thread so that the callbacks do not delay one another. User on Callback registration defines the parameter UserParameter. It is especially useful when several SPiiPlus cards are used. That allows setting the same function as a Callback on certain interrupt, for all the cards. Inside that function user can see by the UserParameter, which card caused the interrupt. To uninstall a specific callback, call the function acsc_SetCallback with the parameter Callback equals to NULL and the parameter Interrupt equals the specified interrupt type. This action will uninstall the callback for specified communication channel. Note Before the PEG interrupts can be detected, the acsc_AssignPins function must be called. 31 January 2009 326 C Library Functions
- 341. C Library Reference Version 6.50 Programmer’s Guide Example int WINAPI CallbackInput (int Param,void* UserParameter); // will be defined later … int CardIndex;//Some external variable, which contains card index // set callback function to monitor digital inputs if (!acsc_SetCallbackExt(Handle, // communication handle CallbackInput,// pointer to the user callback function &CardIndex, // pointer to the index ACSC_INTR_INPUT // Type of callback )) { printf("callback registration error: %dn", acsc_GetLastError()); } … // If callback was installed successfully, the CallbackInput function will // be called each time the any digital input has changed from 0 to 1. // CallbackInput function checks the digital inputs 0 and 1 int WINAPI CallbackInput (int Param,void* UserParameter) {if (Param & ACSC_MASK_INPUT_0 && *UserParameter == 0) //Treat input 0 only for card with index 0 { // input 0 has changed from 0 to 1 // doing something here } if (Param & ACSC_MASK_INPUT_1 && *UserParameter == 1) //Treat input 1 only for card with index 1 { // input 1 has changed from 0 to 1 // doing something here } return 0; } 4.28.3 acsc_SetInterruptMask Description The function sets the mask for specified interrupt. Note The function can be used only with the PCI communication channel. Syntax int acsc_SetInterruptMask(HANDLE Handle, int Interrupt, int Mask) 31 January 2009 327 C Library Functions
- 342. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle Interrupt See Callback Interrupts Mask The mask to be set. If some bit equals to 0 then interrupt for corresponding axis/buffer/input does not occur – interrupt is disabled. Use ACSC_MASK_*** constants to set/reset a specified bit. See Callback Interrupt Masks for a detailed description of these constants. If Mask is ACSC_NONE, the interrupts for all axes/buffers/inputs are enabled. If Mask is 0, the interrupts for all axes/buffers/inputs are disabled. As default all bits for each interrupts are set to one. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function sets the bit mask for specified interrupt. To get current mask for specified interrupt, call acsc_GetInterruptMask. Using a mask, you can reduce the number of calls of your callback function. The callback will be called only if the interrupt is caused by an axis/buffer/input that corresponds to non-zero bit in the related mask. 31 January 2009 328 C Library Functions
- 343. C Library Reference Version 6.50 Programmer’s Guide Example // the example shows how to configure the interrupt mask to monitor only // specific axis if (!acsc_SetInterruptMask(Handle, // communication handle ACSC_INTR_PHYSICAL_MOTION_END, // specified interrupt ACSC_MASK_AXIS_X // enable interrupt // only for the axis X )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.28.4 acsc_GetInterruptMask Description The function retrieves the mask for specified interrupt. Syntax int acsc_GetInterruptMask(HANDLE Handle, int Interrupt, int* Mask) Arguments Handle Communication handle Interrupt See Callback Interrupts. Mask The current mask. If a bit equals 0, an interrupt for corresponding axis/buffer/input does not occur; the interrupt is disabled. Use the ACSC_MASK_*** constants to analyze a value of the specific bit. See Callback Interrupt Masks for a detailed description of these constants. As default all bits for each interrupts are set to one. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 329 C Library Functions
- 344. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the bit mask for specified interrupt. To set the mask for specified interrupt, use acsc_SetInterruptMask. Example // the example shows how to get the mask for specific interrupt int Mask; if (!acsc_GetInterruptMask( Handle, // communication handle ACSC_INTR_PHYSICAL_MOTION_END, // specified interrupt &Mask // received value )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.28.5 acsc_SetCallbackPriority Description The function sets the priority for all callback threads. Note The function can be used only with the PCI communication channel. Syntax int acsc_SetCallbackPriority(HANDLE Handle, int Priority) Arguments Handle Communication handle. 31 January 2009 330 C Library Functions
- 345. C Library Reference Version 6.50 Programmer’s Guide Priority Specifies the priority value for the callback thread. This parameter can be one of the operating system defined priority levels. For example Win32 API defines the following priorities: THREAD_PRIORITY_ABOVE_NORMAL THREAD_PRIORITY_BELOW_NORMAL THREAD_PRIORITY_HIGHEST THREAD_PRIORITY_IDLE THREAD_PRIORITY_LOWEST THREAD_PRIORITY_NORMAL THREAD_PRIORITY_TIME_CRITICAL As default, all callback threads have a normal priority. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The operating system uses the priority level of all executable threads to determine which thread gets the next slice of CPU time. Basically, threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level does scheduling of threads at a lower level take place. When manipulating priorities, be very careful to ensure that a high-priority thread does not consume all of the available CPU time. See the relevant operating system guides for details. Example // the example sets the new priority for all callbacks if (!acsc_SetCallbackPriority(Handle, THREAD_PRIORITY_ABOVE_NORMAL)) { printf("set of callback priority error: %dn", acsc_GetLastError()); } 31 January 2009 331 C Library Functions
- 346. C Library Reference Version 6.50 Programmer’s Guide 4.29 Variables Management Functions The Variables Management functions are: Table 33 Variables Management Functions Function Description acsc_DeclareVariable Creates the persistent global variable. acsc_ClearVariables Deletes all persistent global variables. 4.29.1 acsc_DeclareVariable Description The function creates the persistent global variable. Syntax int acsc_DeclareVariable (HANDLE Handle, int Type, char* Name, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Type Type of the variable. For the integer variable the parameter must be ACSC_INT_TYPE. For the real variable, the parameter must be ACSC_REAL_TYPE. Name Pointer to the null-terminated ASCII string contained name of the variable. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function acsc_WaitForAsyncCall returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 332 C Library Functions
- 347. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function creates the persistent global variable specified by the parameter Name of type specified by the parameter Type. The variable can be used as any other standard or global variable. If it is necessary to declare one or two-dimensional array, the parameter Name should also contains the dimensional size in brackets. The lifetime of a persistent global variable is not connected with any program buffer. The persistent variable survives any change in the program buffers and can be erased only by the acsc_ClearVariables function. The function can wait for the controller response or can return immediately as specified by the Wait argument. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of the declaration of scalar variable acsc_DeclareVariable(Handle, // communication handle ACSC_INT_TYPE, // integer type “MyVar”, // name of the variable NULL // waiting call )); // example of the declaration of one-dimensional array acsc_DeclareVariable(Handle, // communication handle ACSC_INT_TYPE, // integer type “MyArr(10)”, // name of the one-dimensional // array of 10 elements NULL // waiting call )); // example of the declaration of matrix acsc_DeclareVariable(Handle, // communication handle ACSC_REAL_TYPE, // real type “MyMatrix(10)(5)”, // name of the matrix of 10 rows // and 5 columns NULL // waiting call )); 31 January 2009 333 C Library Functions
- 348. C Library Reference Version 6.50 Programmer’s Guide 4.29.2 acsc_ClearVariables Description The function deletes all persistent global variables. Syntax int acsc_ClearVariables (HANDLE Handle, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function deletes all persistent global variables created by the acsc_DeclareVariable function. The function can wait for the controller response or can return immediately as specified by the Wait argument. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 334 C Library Functions
- 349. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_ClearVariables if (!acsc_ClearVariables(Handle, // communication handle NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.30 Service Functions The Service functions are: Table 34 Service Functions Function Description acsc_GetFirmwareVersion Retrieves the firmware version of the controller. acsc_GetSerialNumber Retrieves the controller serial number. 4.30.1 acsc_GetFirmwareVersion Description The function retrieves the firmware version of the controller. Syntax int acsc_GetFirmwareVersion(HANDLE Handle, char* Version, int Count, int* Received, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Version Pointer to the buffer that receives the firmware version. Count Size of the buffer pointed by Version. Received Number of characters that were actually received. 31 January 2009 335 C Library Functions
- 350. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the character string that contains the firmware version of the controller. The function will not copy more than Count characters to the Version buffer. If the buffer is too small, the firmware version can be truncated. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Version, Received, and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 336 C Library Functions
- 351. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetFirmwareVersion char Firmware[256]; int Received; if (!acsc_GetFirmwareVersion( Handle, // communication handle Firmware, // buffer for the firmware // version 255, // size of the buffer &Received, // number of actually // received characters NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } else { Firmware[Received] = ‘0’; printf("Firmware version of the controller: %sn", Firmware); } 4.30.2 acsc_GetSerialNumber Description The function retrieves the controller serial number. Syntax int acsc_GetSerialNumber(HANDLE Handle, char* SerialNumber, int Count, int* Received, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. SerialNumber Pointer to the buffer that receives the serial number. Count Size of the buffer pointed by SerialNumber. Received Number of characters that were actually received. 31 January 2009 337 C Library Functions
- 352. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the character string that contains the controller serial number. The function will not copy more than Count characters to the SerialNumber buffer. If the buffer is too small, the serial number can be truncated. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the SerialNumber, Received and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 338 C Library Functions
- 353. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetSerialNumber char SerialNumber[256]; int Received; if (!acsc_GetSerialNumber(Handle, // communication handle SerialNumber, // buffer for the serial number 255, // size of the buffer &Received, // number of actually received characters NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } else { SerialNumber[Received] = ‘0’; printf("Controller serial number: %sn", SerialNumber); } 4.31 Error Diagnosis Functions The Error Diagnosis functions are: Table 35 Error Diagnosis Functions Function Description acsc_GetMotorError Retrieves the reason why the motor was disabled. acsc_GetMotionError Obsolete - replaced by acsc_GetMotorError. acsc_GetProgramError Retrieves the error code of the last program error encountered in the specified buffer. 4.31.1 acsc_GetMotorError Description The function retrieves the reason for motor disabling. Syntax int acsc_GetMotorError(HANDLE Handle, int Axis, int* Error, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. 31 January 2009 339 C Library Functions
- 354. C Library Reference Version 6.50 Programmer’s Guide Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see Axis Definitions. Error Pointer to a variable that receives the reason why the motor was disabled. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the reason for motor disabling. If the motor is enabled the parameter, Error is zero. If the motor was disabled, the parameter Error contains the reason for motor disabling. Note To get the error explanation, use the acsc_GetErrorString function. See “SPiiPlus ACSPL+ Programmer’s Guide” for all available motor error code descriptions. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 340 C Library Functions
- 355. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetMotorError int Error; char ErrorStr[256]; int Received; if (acsc_GetMotorError(Handle, // communication handle ACSC_AXIS_X, // axis X &Error, // received value NULL // waiting call )) { if (Error > 0) { if (acsc_GetErrorString(Handle, Error, ErrorStr, 255, &Received)) { ErrorStr[Received] = ‘0’; printf("Motor error: %d (%s)n", Error, ErrorStr); } } } else { if (Error > 0) { if (acsc_GetErrorString(Handle, Error, ErrorStr, 255, &Received)) { ErrorStr[Received] = ‘0’; printf("Motor error: %d (%s)n", Error, ErrorStr); } } } else { printf("transaction error: %dn", acsc_GetLastError()); } 4.31.2 acsc_GetMotionError Note This function is obsolete and will be deprecated in a future version of the C Library. The function is supported for backward compatibility. In all cases, use acsc_GetMotorError instead. 31 January 2009 341 C Library Functions
- 356. C Library Reference Version 6.50 Programmer’s Guide Description The function retrieves the termination code of the last executed motion of the specified axis. Syntax int acsc_GetMotionError(HANDLE Handle, int Axis, int* Error, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis Axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. For a multi-axis motion this parameter must correspond to a leading axis of a group Error Pointer to a variable that receives the termination code of the last executed motion. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Get extended error information by call acsc_GetLastError. Comments The function retrieves the termination code of the last executed motion of the specified axis. If the motion is in progress, the parameter Error is zero. If the motion terminates for any reason, the parameter Error contains the termination code. To get the error explanation, use the function acsc_GetErrorString. See the SPiiPlus ACSPL+ Programmer’s Guide for all available motion termination codes description. 31 January 2009 342 C Library Functions
- 357. C Library Reference Version 6.50 Programmer’s Guide If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function. Example // example of the waiting call of acsc_GetMotionError int Error; char ErrorStr[256]; if (acsc_GetMotionError( Handle, // communication handle ACSC_AXIS_X, // axis X &Error, // received value NULL // waiting call )) { if (Error > 0) { if (acsc_GetErrorString( Handle, Error, ErrorStr, 255, &Received)) { ErrorStr[Received] = ‘0’; printf("Motion error: %d (%s)n", Error, ErrorStr); } } } else { printf("transaction error: %dn", acsc_GetLastError()); } 4.31.3 acsc_GetProgramError Description The function retrieves the error code of the last program error encountered in the specified buffer. Syntax int acsc_GetProgramError(HANDLE Handle, int Buffer, int* Error, ACSC_WAITBLOCK* Wait) 31 January 2009 343 C Library Functions
- 358. C Library Reference Version 6.50 Programmer’s Guide Arguments Handle Communication handle. Buffer Number of the program buffer. Error Pointer to a variable that receives the error code. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function retrieves the error code of the last program error encountered in the specified buffer. If the program is running, the parameter Error is zero. If the program terminates for any reason, the parameter Error contains the termination code. Note To get the error explanation, use the acsc_GetErrorString function. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function. 31 January 2009 344 C Library Functions
- 359. C Library Reference Version 6.50 Programmer’s Guide Example // example of the waiting call of acsc_GetProgramError int Error; char ErrorStr[256]; if (acsc_GetProgramError(Handle, // communication handle 0, // buffer 0 &Error, // received value NULL // waiting call )) { if (Error > 0) { if (acsc_GetErrorString( Handle, Error, ErrorStr, 255, &Received)) { ErrorStr[Received] = ‘0’; printf("Program error: %d (%s)n", Error, ErrorStr); } } } else { printf("transaction error: %dn", acsc_GetLastError()); } 4.32 Dual Port RAM (DPRAM) Access Functions The Dual Port RAM Access functions are: Table 36 Dual Port RAM (DPRAM) Access Functions Function Description acsc_ReadDPRAMInteger Reads 32-bit integer from DPRAM acsc_WriteDPRAMInteger Writes 32-bit integer to DPRAM acsc_ReadDPRAMReal Reads 64 real from DPRAM acsc_WriteDPRAMReal Writes 64-bit real to DPRAM 4.32.1 acsc_ReadDPRAMInteger Description The function reads 32-bit integer from the DPRAM. 31 January 2009 345 C Library Functions
- 360. C Library Reference Version 6.50 Programmer’s Guide Note The function can be used only with the PCI and Simulator communication channels Syntax acsc_ReadDPRAMInteger(HANDLE Handle, int address,int *Value) Arguments Handle Communication handle Address Address has to be even number from 128 to 508 Value Value that was read from DPRAM Return Value The function returns non-zero on success. If the value cannot be read, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Address has to be even number in the range of 128 to 508, because we use 16-bit alignment when working with DPRAM. Addresses less than 128 are used for internal purposes. Example acsc_ReadDPRAMInteger( Handle, // communication handle 0xA0, // DPRAM address &Value //Value that receives the result ) 31 January 2009 346 C Library Functions
- 361. C Library Reference Version 6.50 Programmer’s Guide 4.32.2 acsc_WriteDPRAMInteger Description The function writes 32-bit integer to the DPRAM. Note The function can be used only with the PCI and Simulator communication channels Syntax acsc_WriteDPRAMInteger(HANDLE Handle, int address,int Value) Arguments Handle Communication handle Address Address has to be even number from 128 to 508 Value Value to be written Return Value The function returns non-zero on success. If the value cannot be written, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Address has to be even number in the range of 128 to 508, because we use 16-bit alignment when working with DPRAM. Addresses less than 128 are used for internal purposes. Example acsc_WriteDPRAMInteger(Handle, // communication handle 0xA0, // DPRAM address 0 //Value to write ) 31 January 2009 347 C Library Functions
- 362. C Library Reference Version 6.50 Programmer’s Guide 4.32.3 acsc_ReadDPRAMReal Description The function reads 64-bit Real from the DPRAM. Note The function can be used only with the PCI and Simulator communication channels Syntax acsc_ReadDPRAMReal(HANDLE Handle, int address, double *Value) Arguments Handle Communication handle Address Address has to be even number from 128 to 508 Value Value that was read from DPRAM Return Value The function returns non-zero on success. If the value cannot be read, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Address has to be even number in the range of 128 to 504, because we use 16-bit alignment when working with DPRAM. Addresses less than 128 are used for internal purposes. Example acsc_ReadDPRAMReal( Handle, // communication handle 0xA0, // DPRAM address &Value //Value that receives the result ) 31 January 2009 348 C Library Functions
- 363. C Library Reference Version 6.50 Programmer’s Guide 4.32.4 acsc_WriteDPRAMReal Description The function writes 64-bit Real to the DPRAM. Note The function can be used only with the PCI and Simulator communication channels Syntax acsc_WriteDPRAMReal(HANDLE Handle, int address, double Value) Arguments Handle Communication handle Address Address has to be even number from 128 to 508 Value Value to be written Return Value The function returns non-zero on success. If the value cannot be written, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Address has to be even number in the range of 128 to 504, because we use 16-bit alignment when working with DPRAM. Addresses less than 128 are used for internal purposes. Example acsc_WriteDPRAMReal(Handle, // communication handle 0xA0, // DPRAM address 0 //Value to write ) 31 January 2009 349 C Library Functions
- 364. C Library Reference Version 6.50 Programmer’s Guide 4.33 Position Event Generation (PEG) Functions The Position Event Generation functions are: Table 37 Position Event Generation (PEG) Functions Function Description acsc_PegInc Sets incremental PEG acsc_PegRandom Sets random PEG acsc_AssignPins Defines whether a digital output is allocated to the corresponding bit of the OUT array (for general purpose use) or allocated for PEG function use. acsc_StopPeg Stops PEG 4.33.1 acsc_PegInc Description The function initiates incremental PEG. Incremental PEG function is defined by first point, last point and the interval. Syntax int acsc_PegInc(HANDLE Handle, int Flags, int Axis, double Width, double FirstPoint, double Interval, double LastPoint, int TbNumber, double TbPeriod, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis PEG axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Flags Bit-mapped parameter that can include following flag: ACSC_AMF_SYNCHRONOUS - PEG starts synchronously with the motion sequence. Width Width of desired pulse in milliseconds. FirstPoint Position where the first pulse is generated. 31 January 2009 350 C Library Functions
- 365. C Library Reference Version 6.50 Programmer’s Guide Interval Distance between the pulse-generating points. LastPoint Position where the last pulse is generated. TbNumber Number of time-based pulses generated after each encoder-based pulse, the range is from 0 to 511. If time-based pulses aren’t desired, assign ACSC_NONE in this parameter. TbPeriod Period of time-based pulses, period from 0.000025 to 0.012775msec. If time-based pulses aren’t desired, assign ACSC_NONE in this parameter. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates incremental PEG generation. See details in ACSPL+ programmers guide. The time-based pulse generation is optional, if it is not used, TbPeriod and TbNumber should be ACSC_NONE. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. 31 January 2009 351 C Library Functions
- 366. C Library Reference Version 6.50 Programmer’s Guide Example // example of incremental PEG initialization if (!acsc_PegInc( Handle,// communication handle ACSC_AMF_SYNCRONOUS,// synchronous PEG ACSC_AXIS_X,// axis X 0.01, // 10 microseconds pulse width 1000.0,// start from 1000 100.0, // generate pulse every 100 units 10000.0,// stop generating at 10000 ACSC_NONE,// no time-based pulse generation ACSC_NONE, NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.33.2 acsc_PegRandom Description The function initiates random PEG. Random PEG function specifies an array of points where position-based events should be generated. Syntax int acsc_PegRandom(HANDLE Handle,int Flags,int Axis,double Width,char* PointArray,char* StateArray,int TbNumber, double TbPeriod, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Flags Bit-mapped parameter that can include following flag: ACSC_AMF_SYNCHRONOUS - PEG starts synchronously with the motion sequence. Axis PEG axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Width Width of desired pulse in milliseconds. 31 January 2009 352 C Library Functions
- 367. C Library Reference Version 6.50 Programmer’s Guide PointArray Null-terminated string contained the name of the real array that stores positions at which PEG pulse should be generated The array must be declared as a global variable by an ACSPL+ program or by the acsc_DeclareVariable function. StateArray Null-terminated string contained the name of the integer array that stores desired output state at each position. The array must be declared as a global variable by an ACSPL+ program or by the acsc_DeclareVariable function. If output state change is not desired, this parameter should be NULL. TbNumber Number of time-based pulses generated after each encoder-based pulse, the range is from 0 to 511. If time-based pulses are not desired, assign ACSC_NONE in this parameter. TbPeriod Period of time-based pulses, period from 0.000025 to 0.012775 (Milliseconds). If time-based pulses aren’t desired, assign ACSC_NONE in this parameter. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function initiates random PEG generation (see SPiiPlus ACSPL+ Programmer’s Guide). 31 January 2009 353 C Library Functions
- 368. C Library Reference Version 6.50 Programmer’s Guide StateArray should be NULL if output state won’t change because of PEG. The time-based pulse generation is optional, if it is not used, TbPeriod and TbNumber should be ACSC_NONE. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of incremental PEG initialization if (!acsc_PegRandom( Handle,// communication handle 0, // non-synchronous PEG ACSC_AXIS_X,// axis X 0.01, // 10 microseconds pulse width “PointArr”,// name of array inside the controller NULL, // state array is not used ACSC_NONE,// no time-based pulse generation ACSC_NONE, NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 4.33.3 acsc_AssignPins Description The function defines whether a digital output is allocated to the corresponding bit of the OUT array (for general purpose use) or allocated for PEG function use. Syntax int acsc_AssignPins(HANDLE Handle,int Axis,unsigned short Mask, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis PEG axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Mask 16-bit mask defines pins state. 31 January 2009 354 C Library Functions
- 369. C Library Reference Version 6.50 Programmer’s Guide Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the acsc_WaitForAsyncCall function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The function calls the ACSPL command SetConf (205, axis, Mask), where Mask is the output mask. For a description of the output mask, see the description of SetConf in the SPiiPlus ACSPL+ programmers guide. If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of incremental PEG initialization if (!acsc_AssignPins( Handle, // communication handle ACSC_AXIS_X, // axis X 0b100000000, // bit 8 is 1 means OUT3 is assigned // to the pulse output of the X PEG NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 355 C Library Functions
- 370. C Library Reference Version 6.50 Programmer’s Guide 4.33.4 acsc_StopPeg Description The function stops PEG. Syntax int acsc_StopPeg(HANDLE Handle,int Axis, ACSC_WAITBLOCK* Wait) Arguments Handle Communication handle. Axis PEG axis: ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y to Y, etc. For the full list of the axis constants, see “Axis Definitions” on Page 378. Wait Pointer to ACSC_WAITBLOCK structure. If Wait is ACSC_SYNCHRONOUS, the function returns when the controller response is received. If Wait points to a valid ACSC_WAITBLOCK structure, the function returns immediately. The calling thread must then call the acsc_WaitForAsyncCall function to retrieve the operation result. If Wait is ACSC_IGNORE, the function returns immediately. In this case, the operation result is ignored by the library and cannot be retrieved to the calling thread. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Get extended error information by call acsc_GetLastError. Comments If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or delete the Wait item until a call to the acsc_WaitForAsyncCall function. Example // example of incremental PEG initialization if (!acsc_StopPeg(Handle, // communication handle ACSC_AXIS_X, // axis X NULL // waiting call )) { printf("transaction error: %dn", acsc_GetLastError()); } 31 January 2009 356 C Library Functions
- 371. C Library Reference Version 6.50 Programmer’s Guide 4.34 Emergency Stop Functions The Emergency Stop functions are: Table 38 Emergency Stop Functions Function Description acsc_RegisterEmergencyStop Initiates Emergency Stop functionality. acsc_UnregisterEmergencyStop Deactivates Emergency Stop functionality. 4.34.1 acsc_RegisterEmergencyStop Description The function initiates the Emergency Stop functionality for calling application. Syntax int acsc_RegisterEmergencyStop(); Arguments None Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments SPiiPlus UMD and Library provide the user application with the ability to open/close the Emergency Stop button (shown in Figure 2). Clicking the Emergency Stop button sends a stop to all motions and motors command to all channels, which used in calling application, thereby stopping all motions and disabling all motors. Figure 2 Emergency Stop Button 31 January 2009 357 C Library Functions
- 372. C Library Reference Version 6.50 Programmer’s Guide In the UMD when it has been selected, the Emergency Stop button stops all motions and disables all motors. Previously only SPiiPlus MMI provided such functionality. Now such functionality is also available for user applications. Calling acsc_RegisterEmergencyStop will cause an Emergency Stop button to appear in the right bottom corner of the UMD screen. If this button is already displayed, that is, activated by another application, a new button does not appear, but all functionality is available for the new application. Clicking the Emergency Stop button causes the stopping of all motions and motors command to all channels that are used in the calling application. Calling acsc_RegisterEmergencyStop requires having the local host SPiiPlus UMD running, even if it is used through a remote connection, because the Emergency Stop button is part of the local SPiiPlus UMD. If the local SPiiPlus UMD is not running, the function fails. Only a single call is required per application. It can be placed anywhere in code, even before the opening of communication with controllers. An application can remove the Emergency Stop button by calling acsc_UnregisterEmergencyStop. The Emergency Stop button disappears if there are no additional registered applications using it. Terminatation of SPiiPlus UMD also removes the Emergency Stop button, so restarting the SPiiPlus UMD requires calling acsc_RegisterEmergencyStop() again. Registering the Emergency Stop button more than once per application is meaningless, but the function succeeds anyway. In order to ensure that the Emergency Stop button is active, it is recommended to place a call to acsc_RegisterEmergencyStop after each call to any of OpenComm***() functions. Example int OpenCommunication() { HANDLE Handle = OpenCommEthernet( // It can be any kind of OpenComm*** "10.0.0.100", // TCP-IP address of the controller ACSC_SOCKET_DGRAM_PORT// point-to-point communication ); if (Handle == ACSC_INVALID) { printf("error opening communication: %dn", acsc_GetLastError()); return 0; } if (!acsc_RegisterEmergencyStop()) { printf("Registration of EStop is failed. Error is: %dn", acsc_GetLastError()); return 0; } return 1; } 31 January 2009 358 C Library Functions
- 373. C Library Reference Version 6.50 Programmer’s Guide 4.34.2 acsc_UnregisterEmergencyStop Description The function terminates the Emergency Stop functionality for the calling application. Syntax int acsc_UnregisterEmergencyStop(); Arguments None Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments The SPiiPlus User Mode Driver (UMD) and C Library provide user applications with the ability to activate or deactivate the Emergency Stop button displayed in the UMD. Calling acsc_UnregisterEmergencyStop will cause application not to respond to the user clicking the Emergency Stop button displayed in the UMD. If there are no other applications that have registered the Emergency Stop functionality (through the acsc_RegisterEmergencyStopfunction), the button will disappear. Unregistering Emergency Stop more than once per application is meaningless, but the function will succeed anyway. Example int CloseCommunication() { if (!acsc_UnregisterEmergencyStop()) { printf("Unregistration of EStop is failed. Error is: %dn", acsc_GetLastError()); return 0; } if (!acsc_CloseComm(Handle)) { printf("Error closing communication: %dn", acsc_GetLastError()); } return 1; } 31 January 2009 359 C Library Functions
- 374. C Library Reference Version 6.50 Programmer’s Guide 4.35 Application Save/Load Functions The Application Save/Load functions are: Table 39 Application Save/Load Functions Function Description acsc_AnalyzeApplication Analyzes application file and returns information about the file components. acsc_LoadApplication Loads selected components of user application from a file on the host PC and saves it in the controller’s flash memory. acsc_SaveApplication Saves selected components of user application from the controller’s flash memory to a file on the host PC. acsc_FreeApplication Frees memory previously allocated by the acsc_AnalyzeApplication function. 4.35.1 acsc_AnalyzeApplication Description The function analyzes an application file and returns information about the file’s components, such as, saved ACSPL+ programs, configuration parameters, user files, etc. Syntax int acsc_AnalyzeApplication(HANDLE Handle, char* fileName, ACSC_APPSL_INFO** info (, ACSC_WAITBLOCK* Wait)) Arguments Handle Communication handle. fileName Filename (with included path) of the Application file. Info Pointer to the Application information descriptor, defined by the ACSC_APPSL_INFO structure. The acsc_AnalyzeApplication function is solely responsible for initializing this structure. Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 360 C Library Functions
- 375. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments If fileName is NULL, the current Controller Application will be analyzed; otherwise, the file specified by fileName, from from the local hard disk, will be analyzed. Example ACSC_APPSL_INFO* ainfo = NULL; if (!acsc_AnalyzeApplication(hComm,"C:needed_application_file.spi", &ainfo)) printf("AnalyzeApplication error: %dn", acsc_GetLastError()); 4.35.2 acsc_LoadApplication Description The function loads a section of data from the host PC disk and saves it in the controller’s files. Syntax int acsc_LoadApplication(HANDLE Handle const char * fileName, ACSC_APPLSL_INFO* info (, ACSC_WAITBLOCK* Wait)) Arguments Handle Communication handle. fileName Filename (with included path) of the Application file. Info Pointer to the Application information descriptor, defined by the ACSC_APPSL_INFO structure. The acsc_AnalyzeApplication function is solely responsible for initializing this structure. Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. Return Value If the function succeeds, the return value is non-zero. 31 January 2009 361 C Library Functions
- 376. C Library Reference Version 6.50 Programmer’s Guide If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments None. Example ACSC_APPSL_INFO* ainfo = NULL; if (!acsc_AnalyzeApplication(hComm,"C:needed_application_file.spi", &ainfo,NULL)) printf("AnalyzeApplication error: %dn", acsc_GetLastError()); if (!acsc_LoadApplication(hComm,"C:needed_application_file.spi", ainfo,NULL)) printf("LoadApplication error: %dn", acsc_GetLastError()); 4.35.3 acsc_SaveApplication Description The function saves a user application from the controller to a file on the host PC. Syntax int acsc_SaveApplication(HANDLE Handle, const char * fileName, ACSC_APPLSL_INFO* info (, ACSC_WAITBLOCK* Wait)) Arguments Handle Communication handle. fileName Filename (with included path) of the Application file. Info Pointer to the Application information descriptor, defined by the ACSC_APPSL_INFO structure. The acsc_AnalyzeApplication function is solely responsible for initializing this structure. Wait Wait has to be ACSC_SYNCHRONOUS, since only synchronous calls are supported for this function. 31 January 2009 362 C Library Functions
- 377. C Library Reference Version 6.50 Programmer’s Guide Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments None. Example ACSC_APPSL_INFO* ainfo = NULL; if (!acsc_AnalyzeApplication(hComm,"C:needed_application_file.spi", &ainfo,NULL)) printf("AnalyzeApplication error: %dn", acsc_GetLastError()); if (!acsc_SaveApplication(hComm,"C:needed_application_file.spi", ainfo,NULL)) printf("SaveApplication error: %dn", acsc_GetLastError()); 4.35.4 acsc_FreeApplication Description The function frees memory previously allocated by the acsc_AnalyzeApplication function. Syntax int acsc_FreeApplication(ACSC_APPLSL_INFO* Info) Arguments Info Pointer to the Application information descriptor, defined by the ACSC_APPSL_INFO structure. The acsc_AnalyzeApplication function is solely responsible for initializing this structure. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. 31 January 2009 363 C Library Functions
- 378. C Library Reference Version 6.50 Programmer’s Guide Note Extended error information can be obtained by calling acsc_GetLastError. Comments None. Example ACSC_APPSL_INFO* ainfo = NULL; if (!acsc_AnalyzeApplication(hComm,"C:needed_application_file.spi", &ainfo,NULL)) printf("AnalyzeApplication error: %dn", acsc_GetLastError()); ... if (!acsc_FreeApplication(ainfo,NULL)) printf("FreeApplication error: %dn", acsc_GetLastError()); 4.36 Reboot Functions The Reboot functions are: Table 40 Reboot Functions Function Description acsc_ControllerReboot Reboots controller and waits for process completion. acsc_ControllerFactoryDefault Reboots controller, restores factory default settings and waits for process completion. 4.36.1 acsc_ControllerReboot Description The function reboots controller and waits for process completion. Syntax int acsc_ControllerReboot(HANDLE Handle, int Timeout) Arguments Handle Communication handle. 31 January 2009 364 C Library Functions
- 379. C Library Reference Version 6.50 Programmer’s Guide Timeout Maximum waiting time in milliseconds. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. Comments Example hComm = acsc_OpenComm… ; if (hComm == ACSC_INVALID) { printf("Error while opening communication: %dn", acsc_GetLastError()); return -1; } printf ("Communication with the controller was established successfully!n"); if (!acsc_ControllerReboot(hComm,30000)){ printf("ControllerReboot error: %dn", acsc_GetLastError()); return -1; } printf ("Controller rebooted successfully, closing communicationn"); acsc_CloseComm(hComm); hComm = acsc_OpenComm… ; //reopen communication if (hComm == ACSC_INVALID) { printf("Error while reopening communication after reboot: %dn", acsc_GetLastError()); return -1; } printf ("Communication with the controller after reboot, was established successfully!n"); 31 January 2009 365 C Library Functions
- 380. C Library Reference Version 6.50 Programmer’s Guide 4.36.2 acsc_ControllerFactoryDefault Description The function reboots controller, restores factory default settings and waits for process completion. Syntax int acsc_ControllerFactoryDefault(HANDLE Handle, int Timeout) Arguments Handle Communication handle. Timeout Maximum waiting time in milliseconds. Return Value If the function succeeds, the return value is non-zero. If the function fails, the return value is zero. Note Extended error information can be obtained by calling acsc_GetLastError. 31 January 2009 366 C Library Functions
- 381. C Library Reference Version 6.50 Programmer’s Guide Comments Example hComm = acsc_OpenComm… ; if (hComm == ACSC_INVALID) { printf("Error while opening communication: %dn", acsc_GetLastError()); return -1; } printf ("Communication with the controller was established successfully!n"); if (!acsc_ControllerFactoryDefault(hComm,30000)){ printf("ControllerFactoryDefault error: %dn", acsc_GetLastError()); return -1; } printf ("Controller restarted successfully, closing communicationn"); acsc_CloseComm(hComm); hComm = acsc_OpenComm… ; //reopen communication if (hComm == ACSC_INVALID) { printf("Error while reopening communication after restart: %dn", acsc_GetLastError()); return -1; } printf ("Communication with the controller after reboot, was established successfully!n"); 31 January 2009 367 C Library Functions
- 382. C Library Reference Version 6.50 Programmer’s Guide 5 Error Codes Note Any error code greater than 1000 is a controller error defined in the SPiiPlus ACSPL+ Programmer’s Guide. Table 41 Error Codes (page 1 of 7) Format Error Description ACSC_ONLYSYNCHRONOUS 101 Asynchronous call is not supported. ACSC_ENOENTLOGFILE 102 No such file or directory. This error is returned by the acsc_OpenLogFile function if a component of a path does not specify an existing directory. ACS_OLD_FW 103 The FW version does not support the current C Library version. This error is returned by one of the acsc_OpenComm functions, such as, acsc_OpenCommSerial . Upgrde the FW of the controller. ACSC_MEMORY_OVERFLOW 104 Controllers reply is too long. ACSC_EBADFLOGFILE 109 Internal library error: Invalid file handle. ACSC_EACCESLOGFILE 113 File permission denied. This error is returned by the acsc_OpenLogFile function if attempt was made to open a read-only file, or file’s sharing mode does not allow a write operation. ACSC_EINVALLOGFILE 122 Internal library error: Cannot open Log file. ACSC_EMFILELOGFILE 124 Too many open files. This error is returned by the acsc_OpenLogFile function if no more file handles available. ACSC_ENOSPCLOGFILE 128 No space left on device. This error is returned by the acsc_WriteLogFile function if no more space for writing is available on the device (for example, when the disk is full). 31 January 2009 368 Error Codes
- 383. C Library Reference Version 6.50 Programmer’s Guide Table 41 Error Codes (page 2 of 7) Format Error Description ACSC_TIMEOUT 130 The controller stopped responding. This error indicates that during specified time-out the controller did not respond or response was invalid. ACSC_INITFAILURE 132 Communication initialization failure. Returned by one of the acsc_OpenComm functions, such as, acsc_OpenCommSerial , in the following cases: • The specified communication parameters are invalid • The corresponding physical connection is not established • The controller does not respond for specified communication channel. ACSC_CREATECOMMFAILURE 133 Internal library error: Creating communication object failure. ACSC_INVALIDHANDLE 134 Invalid communication handle. Specified communication handle must be a handle returned by one of the acsc_Open*** functions, such as, acsc_OpenCommSerial. ACSC_ALLCHANNELSBUSY 135 All channels are busy. The maximum number of the concurrently opened communication channels is 10. ACSC_INVALIDLOGFILENAME 136 Invalid name of Log file. This error is returned by the acsc_OpenLogFile function if the specified log file name is invalid or more than 256 characters. ACSC_RECEIVEDTOOLONG 137 Received message is too long (more than size of user buffer). This error cannot be returned and is present for compatibility with previous versions of the library. ACSC_INVALIDBUFSIZE 138 The program string is long. This error is returned by one of the acsc_DownloadBuffer, acsc_AppendBuffer or acsc_LoadBuffer function if ACSPL+ program contains a string longer than 2032 bytes. 31 January 2009 369 Error Codes
- 384. C Library Reference Version 6.50 Programmer’s Guide Table 41 Error Codes (page 3 of 7) Format Error Description ACSC_INVALIDPARAMETERS 139 Function parameters are invalid. ACSC_CLOSEDHISTORYBUF 140 History buffer is closed. ACSC_EMPTYNAMEVAR 141 Name of variable must be specified. ACSC_INPUTPAR 142 Error in index specification. This error is returned by the acsc_ReadInteger, acsc_ReadReal, acsc_WriteInteger, or acsc_WriteReal functions if the parameters From1, To1, From2, To2 were specified incorrectly. ACSC_RECEIVEDTOOSMALL 143 Controller reply contains less values than expected. This error is returned by the acsc_ReadInteger or acsc_ReadReal functions. ACSC_FUNCTIONNOTSUPPORTED 145 Function is not supported in current version. ACSC_INITHISTORYBUFFAILED 147 Internal error: Error of the history buffer initialization. ACSC_CLOSEDMESSAGEBUF 150 Unsolicited messages buffer is closed. ACSC_SETCALLBACKERROR 151 Callback registration error. This error is returned by the acsc_SetCallback function for any of the communication channels. In the present version of library, only PCI Bus communication supports user callbacks. ACSC_CALLBACKALREADYSET 152 Callback function has been already installed. This error is returned by the acsc_SetCallback function if the application tries to install another callback function for the same interrupt that was already used. Only one callback can be installed for each interrupt. ACSC_CHECKSUMERROR 153 Checksum of the controller response is incorrect. ACSC_REPLIESSEQUENCEERROR 154 Internal library error: The controller replies sequence is invalid. ACSC_WAITFAILED 155 Internal library error: WaitForSingleObject function returns error. ACSC_INITMESSAGEBUFFAILED 157 Internal library error: Error of the unsolicited messages buffer initialization. 31 January 2009 370 Error Codes
- 385. C Library Reference Version 6.50 Programmer’s Guide Table 41 Error Codes (page 4 of 7) Format Error Description ACSC_OPERATIONABORTED 158 Non-waiting call has been aborted. This error occurs in the following cases: acsc_CancelOperation function returns this error if the corresponding call has been aborted by user request. acsc_WaitForAsyncCall function returns this error if the parameter Wait contains invalid pointer. ACSC_CANCELOPERATIONERROR 159 Error of the non-waiting call cancellation. This error is returned by the acsc_CancelOperation function if the parameter Wait contains invalid pointer. ACSC_COMMANDSQUEUEFULL 160 Queue of transmitted commands is full. The maximum number of the concurrently transmitted commands is 256. Check how many waiting calls were initiated and how many non-waiting (asynchronous) calls are in progress so far. ACSC_SENDINGFAILED 162 The library cannot send to the specified communication channel. Check physical connection with the controller (or settings) and try to reconnect. ACSC_RECEIVINGFAILED 163 The library cannot receive from the specified communication channel. Check physical connection with the controller (or settings) and try to reconnect. ACSC_CHAINSENDINGFAILED 164 Internal library error: Sending of the chain is failed. ACSC_DUPLICATED_IP 165 Specified IP address is duplicated. ACSC_APPLICATION_NOT_FOUND 166 There is no Application with such Handle. ACSC_ARRAY_EXPECTED 167 Array name was expected. ACSC_INVALID_FILETYPE 168 File is not Data File. ACSC_APPSL_CRC 171 Application Saver Loader CRC error. ACSC_APPSL_HEADERCRC 172 Application Saver Loader Header CRC error. ACSC_APPSL_FILESIZE 173 Application Saver Loader File Size error. ACSC_APPSL_FILEOPEN 174 Application Saver Loader File Open error. 31 January 2009 371 Error Codes
- 386. C Library Reference Version 6.50 Programmer’s Guide Table 41 Error Codes (page 5 of 7) Format Error Description ACSC_APPSL_UNKNOWNFILE 175 Application Saver Loader Unknown File error. ACSC_APPSL_VERERROR 176 Application Saver Loader Format Version error. ACSC_APPSL_SECTION_SIZE 177 Application Saver Loader Section Size is Zero. ACSC_TLSERROR 179 Internal library error: Thread local storage error. ACSC_INITDRIVERFAILED 180 Error of the PCI driver initialization. Returned by the acsc_GetPCICards function in the following cases: SPiiPlus PCI driver is not installed correctly or the version of the SPiiPlus PCI Bus driver is incorrect In this case, it is necessary to reinstall the SPiiPlus PCI driver (WINDRIVER) and the library. ACSC_INVALIDPOINTER 185 Pointer to the buffer is invalid. Returned by the acsc_WaitForAsyncCall function if the parameter Buf is not the same pointer that was specified for SPiiPlus C function call. ACSC_SETPRIORITYERROR 189 Specified priority for the callback thread cannot be set. Returned by the acsc_SetCallbackPriority function in the following cases: Specified priority value is not supported by the operating system or cannot be set by the function or the function was called by any of the communication channels. In the present version of library, only PCI Bus communication supports user callbacks. ACSC_DIRECTDPRAMACCESS 190 Cannot access DPRAM directly through any channel but PCI and Direct. Returned by DPRAM access functions, when attempting to call them with Serial or Ethernet channels. ACSC_INVALID_DPRAM_ADDR 192 Invalid DPRAM address was specified Returned by DPRAM access functions, when attempting to access illegal address 31 January 2009 372 Error Codes
- 387. C Library Reference Version 6.50 Programmer’s Guide Table 41 Error Codes (page 6 of 7) Format Error Description ACSC_OLD_SIMULATOR 193 This version of simulator does not support work with DPRAM. Returned by DPRAM access functions, when attempting to access old version Simulator that does not support DPRAM. ACSC_FILE_NOT_FOUND 195 Returned by functions that work with host file system when a specified filename is not found. Check the path and filename. ACSC_NOT_ENOUGH_DATA 196 Returned by functions that analyze SPiiPlus application files when application file format is incorrect. Check application file and replace with a valid file. ACSC_SERVER 197 The application cannot establish communication with the SPiiPlus UMD. Returned by one of the acsc_OpenComm functions. Check the following: SPiiPlus UMD is loaded (whether the UMD icon appears in the Task tray). SPiiPlus UMD shows an error message. In case of remote connection, access from a remote application is enabled. 31 January 2009 373 Error Codes
- 388. C Library Reference Version 6.50 Programmer’s Guide Table 41 Error Codes (page 7 of 7) Format Error Description ACSC_STOPPED_RESPONDING 198 The controller does not reply for more than 20 seconds. Returned by any function that exchanges data with the controller. Check the following: Controller is powered on (MPU LED is green) Controller connected properly to host Controller executes a time consuming command like compilation of a large program, save to flash, load to flash, etc. ACSC_DLL_UMD_VERSION 199 The DLL and the UMD versions are not compatible. Returned by one of the acsc_OpenComm functions, such as, acsc_OpenCommSerial. Verify that the files ACSCL.DLL and ACSCSRV.EXE are of the same version. 31 January 2009 374 Error Codes
- 389. C Library Reference Version 6.50 Programmer’s Guide 6 Constants This chapter presents the constants that are incorporated in the SPiiPlus C Library. 6.1 General 6.1.1 ACSC_SYNCHRONOUS Description Indicates a synchronous call. Value 0 6.1.2 ACSC_INVALID Description Invalid communication handle. Value -1 6.1.3 ACSC_NONE Description Placeholder for redundant values, like the second index in a one-dimensional array. Value -1 6.1.4 ACSC_IGNORE Description Used for non-waiting calls with neglect of operation results. Value 0xFFFFFFFF 6.1.5 ACSC_INT_TYPE Description Integer type of the variable. 31 January 2009 375 Constants
- 390. C Library Reference Version 6.50 Programmer’s Guide Value 1 6.1.6 ACSC_REAL_TYPE Description Real type of the variable. Value 2 6.1.7 ACSC_MAX_LINE Description Maximum number of lines in the program buffer. Value 100000 6.1.8 ACSC_COUNTERCLOCKWISE Description Counterclockwise rotation. Value 1 6.1.9 ACSC_CLOCKWISE Description Clockwise rotation. Value -1 6.1.10 ACSC_POSITIVE_DIRECTION Description A move in positive direction. Value 1 31 January 2009 376 Constants
- 391. C Library Reference Version 6.50 Programmer’s Guide 6.1.11 ACSC_NEGATIVE_DIRECTION Description A move in negative direction. Value -1 6.2 General Communication Options 6.2.1 ACSC_COMM_USECHECKSUM Description The communication mode when each command is sent to the controller with checksum and the controller also responds with checksum Value 0x000000001 6.2.2 ASCS_COMM_AUTORECOVER_HW_ERROR Description When a hardware error is detected in the communication channel and this bit is set, the library automatically repeats the transaction without counting iterations. By default, this flag is not set. Value 0x000000002 6.3 Ethernet Communication Options 6.3.1 ACSC_SOCKET_DGRAM_PORT Description The library opens Ethernet communication using the connection-less socket and UDP communication protocol. Value 700 31 January 2009 377 Constants
- 392. C Library Reference Version 6.50 Programmer’s Guide 6.3.2 ACSC_SOCKET_STREAM_PORT Description The library opens Ethernet communication using the connection-oriented socket and TCP communication protocol. Value 701 6.4 Axis Definitions 6.4.1 ACSC_AXIS_X Description Axis X Value 0 6.4.2 ACSC_AXIS_Y Description Axis Y Value 1 6.4.3 ACSC_AXIS_Z Description Axis Z Value 2 6.4.4 ACSC_AXIS_T Description Axis T Value 3 31 January 2009 378 Constants
- 393. C Library Reference Version 6.50 Programmer’s Guide 6.4.5 ACSC_AXIS_A Description Axis A Value 4 6.4.6 ACSC_AXIS_B Description Axis B Value 5 6.4.7 ACSC_AXIS_C Description Axis C Value 6 6.4.8 ACSC_AXIS_D Description Axis D Value 7 6.5 Motion Flags 6.5.1 ACSC_AMF_WAIT Description The controller plans the motion but doesn’t start it until the acsc_Go function is executed. Value 0x00000001 31 January 2009 379 Constants
- 394. C Library Reference Version 6.50 Programmer’s Guide 6.5.2 ACSC_AMF_RELATIVE Description The value of the point coordinate is relative to the end point coordinate of the previous motion. Value 0x00000002 6.5.3 ACSC_AMF_VELOCITY Description The motion uses the specified velocity instead of the default velocity. Value 0x00000004 6.5.4 ACSC_AMF_ENDVELOCITY Description The motion comes to the end point with the specified velocity Value 0x00000008 6.5.5 ACSC_AMF_POSITIONLOCK Description The slaved motion uses position lock. If the flag is not specified, velocity lock is used. Value 0x00000010 6.5.6 ACSC_AMF_VELOCITYLOCK Description The slaved motion uses velocity lock. Value 0x00000020 6.5.7 ACSC_AMF_CYCLIC Description The motion uses the point sequence as a cyclic array: after positioning to the last point it does 31 January 2009 380 Constants
- 395. C Library Reference Version 6.50 Programmer’s Guide positioning to the first point and continues. Value 0x00000100 6.5.8 ACSC_AMF_VARTIME Description The time interval between adjacent points of the spline (arbitrary path) motion is non-uniform and is specified along with an each added point. If the flag is not specified, the interval is uniform. Value 0x00000200 6.5.9 ACSC_AMF_CUBIC Description Use a cubic interpolation between the specified points (third-order spline) for the spline (arbitrary path) motion. If the flag is not specified, linear interpolation is used (first-order spline). Note Currently third-order spline is not supported Value 0x00000400 6.5.10 ACSC_AMF_EXTRAPOLATED Description Segmented slaved motion: if a master value travels beyond the specified path, the last or the first segment is extrapolated. Value 0x00001000 6.5.11 ACSC_AMF_STALLED Description Segmented slaved motion: if a master value travels beyond the specified path, the motion stalls 31 January 2009 381 Constants
- 396. C Library Reference Version 6.50 Programmer’s Guide at the last or first point. Value 0x00002000 6.5.12 ACSC_AMF_MAXIMUM Description Multi-axis motion does not use the motion parameters from the leading axis but calculates the maximum allowed motion velocity, acceleration, deceleration and jerk of the involved axes. Value 0x00004000 6.5.13 ACSC_AMF_SYNCHRONOUS Description Position Event Generation (PEG): Start PEG synchronously with the motion sequence. Value 0x00008000 6.6 Data Collection Flags 6.6.1 ACSC_DCF_TEMPORAL Description Temporal data collection. The sampling period is calculated automatically according to the collection time. Value 0x00000001 6.6.2 ACSC_DCF_CYCLIC Description Cyclic data collection uses the collection array as a cyclic buffer and continues infinitely. When the array is full, each new sample overwrites the oldest sample in the array. Value 0x00000002 31 January 2009 382 Constants
- 397. C Library Reference Version 6.50 Programmer’s Guide 6.6.3 ACSC_DCF_SYNC Description Starts data collection synchronously to a motion. Data collection started with the ACSC_DCF_SYNC flag is called axis data collection. Value 0x00000004 6.6.4 ACSC_DCF_WAIT Description Creates synchronous data collection, but does not start until the acsc_Go function is called. This flag can only be used with the ACSC_DCF_SYNC flag. Value 0x00000008 6.7 Motor State Flags 6.7.1 ACSC_MST_ENABLE Description Motor is enabled Value 0x00000001 6.7.2 ACSC_MST_INPOS Description Motor has reached a target position. Value 0x00000010 6.7.3 ACSC_MST_MOVE Description Motor is moving. Value 0x00000020 31 January 2009 383 Constants
- 398. C Library Reference Version 6.50 Programmer’s Guide 6.7.4 ACSC_MST_ACC Description Motor is accelerating. Value 0x00000040 6.8 Axis State Flags 6.8.1 ACSC_AST_LEAD Description Axis is leading in a group. Value 0x00000001 6.8.2 ACSC_AST_DC Description Axis data collection is in progress. Value 0x00000002 6.8.3 ACSC_AST_PEG Description PEG for the specified axis is in progress. Value 0x00000004 6.8.4 ACSC_AST_MOVE Description Axis is moving. Value 0x00000020 31 January 2009 384 Constants
- 399. C Library Reference Version 6.50 Programmer’s Guide 6.8.5 ACSC_AST_ACC Description Axis is accelerating. Value 0x00000040 6.8.6 ACSC_AST_SEGMENT Description Construction of segmented motion for the specified axis is in progress. Value 0x00000080 6.8.7 ACSC_AST_VELLOCK Description Slave motion for the specified axis is synchronized to master in velocity lock mode. Value 0x00000100 6.8.8 ACSC_AST_POSLOCK Description Slave motion for the specified axis is synchronized to master in position lock mode. Value 0x00000200 6.9 Index and Mark State Flags 6.9.1 ACSC_IST_IND Description Primary encoder index of the specified axis is latched. Value 0x00000001 31 January 2009 385 Constants
- 400. C Library Reference Version 6.50 Programmer’s Guide 6.9.2 ACSC_IST_IND2 Description Secondary encoder index of the specified axis is latched. Value 0x00000002 6.9.3 ACSC_IST_MARK Description MARK1 signal has been generated and position of the specified axis was latched. Value 0x00000004 6.9.4 ACSC_IST_MARK2 Description MARK2 signal has been generated and position of the specified axis was latched. Value 0x00000008 6.10 Program State Flags 6.10.1 ACSC_PST_COMPILED Description Program in the specified buffer is compiled. Value 0x00000001 6.10.2 ACSC_PST_RUN Description Program in the specified buffer is running. Value 0x00000002 31 January 2009 386 Constants
- 401. C Library Reference Version 6.50 Programmer’s Guide 6.10.3 ACSC_PST_SUSPEND Description Program in the specified buffer is suspended after the step execution or due to breakpoint in debug mode. Value 0x00000004 6.10.4 ACSC_PST_DEBUG Description Program in the specified buffer is executed in debug mode, i.e. breakpoints are active. Value 0x00000020 6.10.5 ACSC_PST_AUTO Description Auto routine in the specified buffer is running. Value 0x00000080 6.11 Safety Control Masks 6.11.1 ACSC_SAFETY_RL Description Motor fault - Right Limit Value 0x00000001 6.11.2 ACSC_SAFETY_LL Description Motor fault - Left Limit Value 0x00000002 31 January 2009 387 Constants
- 402. C Library Reference Version 6.50 Programmer’s Guide 6.11.3 ACSC_SAFETY_RL2 Description Motor fault - Preliminary Right Limit Value 0x00000004 6.11.4 ACSC_SAFETY_LL2 Description Motor fault - Preliminary Left Limit Value 0x00000008 6.11.5 ACSC_SAFETY_HOT Description Motor fault - Motor Overheat Value 0x00000010 6.11.6 ACSC_SAFETY_SRL Description Motor fault - Software Right Limit Value 0x00000020 6.11.7 ACSC_SAFETY_SLL Description Motor fault - Software Left Limit Value 0x00000040 6.11.8 ACSC_SAFETY_ENCNC Description Motor fault - Primary Encoder Not Connected 31 January 2009 388 Constants
- 403. C Library Reference Version 6.50 Programmer’s Guide Value 0x00000080 6.11.9 ACSC_SAFETY_ENC2NC Description Motor fault - Secondary Encoder Not Connected Value 0x00000100 6.11.10 ACSC_SAFETY_DRIVE Description Motor fault - Driver Alarm Value 0x00000200 6.11.11 ACSC_SAFETY_ENC Description Motor fault - Primary Encoder Error Value 0x00000400 6.11.12 ACSC_SAFETY_ENC2 Description Motor fault - Secondary Encoder Error Value 0x00000800 6.11.13 ACSC_SAFETY_PE Description Motor fault - Position Error Value 0x00001000 31 January 2009 389 Constants
- 404. C Library Reference Version 6.50 Programmer’s Guide 6.11.14 ACSC_SAFETY_CPE Description Motor fault - Critical Position Error Value 0x00002000 6.11.15 ACSC_SAFETY_VL Description Motor fault - Velocity Limit Value 0x00004000 6.11.16 ACSC_SAFETY_AL Description Motor fault - Acceleration Limit Value 0x00008000 6.11.17 ACSC_SAFETY_CL Description Motor fault - Current Limit Value 0x00010000 6.11.18 ACSC_SAFETY_SP Description Motor fault - Servo Processor Alarm Value 0x00020000 6.11.19 ACSC_SAFETY_PROG Description System fault - Program Error 31 January 2009 390 Constants
- 405. C Library Reference Version 6.50 Programmer’s Guide Value 0x02000000 6.11.20 ACSC_SAFETY_MEM Description System fault - Memory Overuse Value 0x04000000 6.11.21 ACSC_SAFETY_TIME Description System fault - Time Overuse Value 0x08000000 6.11.22 ACSC_SAFETY_ES Description System fault - Emergency Stop Value 0x10000000 6.11.23 ACSC_SAFETY_INT Description System fault - Servo Interrupt Value 0x20000000 6.11.24 ACSC_SAFETY_INTGR Description System fault - Integrity Violation Value 0x40000000 31 January 2009 391 Constants
- 406. C Library Reference Version 6.50 Programmer’s Guide Note See the SPiiPlus ACSPL+ Programmer’s Guide for detailed explanations of faults. 6.12 Callback Interrupts There are two types of Callback Interrupts: • Hardware Callback Interrupts • Software Callback Interrupts 6.12.1 Hardware Callback Interrupts 6.12.1.1 ACSC_INTR_PEG Description Position event signal (PEG) has been generated. Value 3 6.12.1.2 ACSC_INTR_MARK1 Description MARK1 signal has been generated. Value 7 6.12.1.3 ACSC_INTR_MARK2 Description MARK2 signal has been generated. Value 8 6.12.1.4 ACSC_INTR_EMERGENCY Description EMERGENCY STOP signal has been generated. 31 January 2009 392 Constants
- 407. C Library Reference Version 6.50 Programmer’s Guide Value 15 6.12.2 Software Callback Interrupts 6.12.2.1 ACSC_INTR_PHYSICAL_MOTION_END Description Physical motion has finished. Value 16 6.12.2.2 ACSC_INTR_LOGICAL_MOTION_END Description Logical motion has finished. Value 17 6.12.2.3 ACSC_INTR_MOTION_FAILURE Description Motion has been interrupted due to a fault. Value 18 6.12.2.4 ACSC_INTR_MOTOR_FAILURE Description Motor has been disabled due to a fault. Value 19 6.12.2.5 ACSC_INTR_PROGRAM_END Description ACSPL+ program has finished. Value 20 31 January 2009 393 Constants
- 408. C Library Reference Version 6.50 Programmer’s Guide 6.12.2.6 ACSC_INTR_COMMAND Description A line of ACSPL+ commands has been executed in a dynamic buffer. Value 21 6.12.2.7 ACSC_INTR_ACSPL_PROGRAM Description ACSPL+ program has generated the interrupt by INTERRUPT command. Value 22 6.12.2.8 ACSC_INTR_INPUT Description Digital input has changed from 0 to 1. Value 23 6.12.2.9 ACSC_INTR_MOTION_START Description Motion Starts Value 24 6.12.2.10 ACSC_INTR_MOTION_PHASE_CHANGE Description Motion Profile Phase changes Value 25 6.12.2.11 ACSC_INTR_TRIGGER Description AST.#TRIGGER bit goes high 31 January 2009 394 Constants
- 409. C Library Reference Version 6.50 Programmer’s Guide Value 26 6.12.2.12 ACSC_INTR_MESSAGE Description Communication interrupt (the controller raises this interrupt after sending a complete message to the host) Value 31 6.13 Callback Interrupt Masks Table 42 Callback Interrupt Masks (page 1 of 2) Bit Name Bit Desc. Interrupt ACSC_MASK_AXIS_X 0 Axis X ACSC_INTR_PEG, ACSC_MASK_AXIS_Y 1 Axis Y ACSC_INTR_MARK1, ACSC_MASK_AXIS_Z 2 Axis Z ACSC_INTR_MARK2, ACSC_MASK_AXIS_T 3 Axis T ACSC_INTR_PHYSICAL_MOTION_END, ACSC_MASK_AXIS_A 4 Axis A ACSC_INTR_LOGICAL_MOTION_END, ACSC_MASK_AXIS_B 5 Axis B ACSC_MASK_AXIS_C 6 Axis C ACSC_INTR_MOTION_FAILURE, ACSC_MASK_AXIS_D 7 Axis D ACSC_INTR_MOTOR_FAILURE, ACSC_INTR_MOTION_START, ACSC_INTR_MOTION_PHASE_CHANGE , ACSC_INTR_TRIGGER 31 January 2009 395 Constants
- 410. C Library Reference Version 6.50 Programmer’s Guide Table 42 Callback Interrupt Masks (page 2 of 2) Bit Name Bit Desc. Interrupt ACSC_MASK_BUFFER_0 0 Buffer 0 ACSC_INTR_PROGRAM_END, ACSC_MASK_BUFFER_1 1 Buffer 1 ACSC_INTR_COMMAND, ACSC_MASK_BUFFER_2 2 Buffer 2 ACSC_INTR_ACSPL_PROGRAM ACSC_MASK_BUFFER_3 3 Buffer 3 ACSC_MASK_BUFFER_4 4 Buffer 4 ACSC_MASK_BUFFER_5 5 Buffer 5 ACSC_MASK_BUFFER_6 6 Buffer 6 ACSC_MASK_BUFFER_7 7 Buffer 7 ACSC_MASK_BUFFER_8 8 Buffer 8 ACSC_MASK_BUFFER_9 9 Buffer 9 ACSC_MASK_INPUT_0 0.31 Inputs ACSC_INTR_INPUT … IN(0).0 ACSC_MASK_INPUT_31 … IN(0).31 6.14 Configuration Keys Table 43 Configuration Keys Key Name Key Description ACSC_CONF _WORD1_KEY 1 Bit 6 defines HSSI route, bit 7 defines source for interrupt generation. ACSC_CONF _INT_EDGE_KEY 3 Sets the interrupt edge to be positive or negative. ACSC_CONF _ENCODER_KEY 4 Sets encoder type: A&B or analog. ACSC_CONF_OUT_KEY 29 Sets the specified output pin to be one of the following: OUT0 PEG Brake ACSC_CONF _MFLAGS9_KEY 204 Controls value of MFLAGS.9 ACSC_CONF_DIGITAL_SOURCE_K 205 Assigns use of OUT0 signal: general EY purpose output or PEG output. ACSC_CONF_SP_OUT_PINS_KEY 206 Reads SP output pins. ACSC_CONF_BRAKE_OUT_KEY 229 Controls brake function. 31 January 2009 396 Constants
- 411. C Library Reference Version 6.50 Programmer’s Guide 31 January 2009 397 Constants
- 412. C Library Reference Version 6.50 Programmer’s Guide 7 Structures This chapter details the structures that are available for SPiiPlus C programming. 7.1 ACSC_WAITBLOCK Description The structure is used for non-waiting calls of the SPiiPlus C functions. Syntax struct ACSC_WAITBLOCK { HANDLE Event; int Ret; } Arguments Event Not used Ret The completion of a task Comments To initiate a non-waiting call the user thread declares the ACSC_WAITBLOCK structure and passes the pointer to this structure to SPiiPlus C function as parameter. When a thread activates a non-waiting call, the library passes the request to an internal thread that sends the command to the controller and then monitors the controller responses. When the controller responds to the command, the internal thread stores the response in the internal buffer. The calling thread can retrieve the response with help of the acsc_WaitForAsyncCall function and validate the Ret. Note The error codes stored in Ret are the same that the acsc_GetLastError function returns. 7.2 ACSC_PCI_SLOT Description The structure defines a physical location of PCI card. This structure is used in the acsc_GetPCICards function and contains the information about detected PCI card. Syntax struct ACSC_PCI_SLOT { unsigned int BusNumber; unsigned int SlotNumber; unsigned int Function; }; 31 January 2009 398 Structures
- 413. C Library Reference Version 6.50 Programmer’s Guide Arguments BusNumber The Bus number SlotNumber Slot number of the controller card Function PCI function of the controller card Comments The SlotNumber can be used in the acsc_OpenCommPCI call in order to open communication with a specific card. Other members have no use in SPiiPlus C Library. 7.3 ACSC_HISTORYBUFFER Description The structure defines a state of the history and message buffers. This structure is used by the acsc_OpenHistoryBuffer and acsc_OpenMessageBuffer functions. Syntax struct ACSC_HISTORYBUFFER { int Max; int Cur; int Ring; char* Buf}; Arguments Max Buffer size Cur Number of bytes currently stored in the buffer Ring Circular index in the buffer Buf Pointer to the buffer Comments Max is equal to the requested Size and never changes its value. Cur is a number of bytes currently stored in the buffer. From the beginning, Cur is zero, then grows up to Max, and then remains unchanged. Ring is a circular index in the buffer: if the buffer is full, the most recent byte is stored in position Ring-1, the earliest byte is stored in position Ring. The user program must never change the members in the structure or write to the history buffer. However, the user program can read the structure and the buffer directly. If doing so, the user should be aware that the library includes a separate thread that watches the replies from the controller. For this reason the contents of the buffer and structure members can change 31 January 2009 399 Structures
- 414. C Library Reference Version 6.50 Programmer’s Guide asynchronously to the user thread. 7.4 ACSC_CONNECTION_DESC Description The structure defines controller connection for an application. Used in the acsc_GetConnectionsList and acsc_TerminateConnection functions. Syntax struct ACSC_CONNECTION_DESC { char Application[100]; HANDLE handle; dwor ProcessID}; Arguments Application Name of the application, maxium of 100 characters. handle The channel’s Handle. ProcessID The ID of the process. 7.5 Application Save/Load Structures The following structures are used with the Application Save/Load functions: 7.5.1 ACSC_APPSL_STRING Description The structure defines a string in the application file. Syntax struct ACSC_APPSL_STRING { int length; char *string}; Arguments length Length of the string string Pointer to the start of the string 31 January 2009 400 Structures
- 415. C Library Reference Version 6.50 Programmer’s Guide 7.5.2 ACSC_APPSL_SECTION Description The structure defines the application section to be loaded or saved. Syntax struct ACSC_APPSL_SECTION { ACSC_APPSL_FILETYPE type; ACSC_APPSL_STRING filename; ACSC_APPSL_STRING description; int size; int offset; int CRC; int inuse; int error; char *data}; Arguments type Section type (see ACSC_APPSL_FILETYPE for a description). filename Section filename. description Section description. size Size, in bytes, of the data. offset Offset in the data section. CRC Data CRC. inuse 0 - Not in use. 1 - In use. error Associated error code. data Pointer to the start of the data. 7.5.3 ACSC_APPSL_ATTRIBUTE Description The structure defines an attribute key-value pair. Syntax struct ACSC_APPSL_ATTRIBUTE { ACSC_APPSL_STRING key; ACSC_APPSL_STRING value}; 31 January 2009 401 Structures
- 416. C Library Reference Version 6.50 Programmer’s Guide Arguments key Attribute’s key. value The value of the key. 7.5.4 ACSC_APPSL_INFO Description The structure defines an application file structure, including the header, attributes and file sections. Syntax struct ACSC_APPSL_INFO {ACSC_APPSL_STRING filename; ACSC_APPSL_STRING description; int isNewFile; int ErrCode; int attributes_num; ACSC_APPSL_ATTRIBUTE *attributes; int sections_num; ACSC_APPSL_SECTION *sections;}; Arguments filename Name of the file. description File description. isNewFile 1 - File is new. 0 - File exists and has been modified. ErrCode Error code from the controller. attributes_num Number of file attributes. attributes Pointer to file attributes. sections_num Number of file sections. sections Pointer to start of file sections. 31 January 2009 402 Structures
- 417. C Library Reference Version 6.50 Programmer’s Guide 8 Enums This chapter details the enums that are available for SPiiPlus C programming. 8.1 ACSC_LOG_DETALIZATION_LEVEL Description This enum is used for setting log file parameters in the acsc_SetLogFileOptions function. Syntax typedef enum ACSC_LOG_DETALIZATION_LEVEL{Minimum,Medium,Maximum}; Arguments Minimum Value 0: Minumum information Medium Value 1: Medium information Maximum Value 2: Maximum information 8.2 ACSC_LOG_DATA_PRESENTATION Description This enum is used for setting log file parameters in the acsc_SetLogFileOptions function. Syntax typedef enum ACSC_LOG_DATA_PRESENTATION {Compact,Formatted,Full}; Arguments Compact Value 0: No more than the first ten bytes of the data strings will be logged. Non-printing characters will be represented in Hex ASCII code. Formatted Value 1: All the binary data will be logged. Non-printing characters will be represented in Hex ASCII code. Full Value 2: All the binary data will be logged as is. 31 January 2009 403 Enums
- 418. C Library Reference Version 6.50 Programmer’s Guide 8.3 ACSC_APPSL_FILETYPE Description This enum is used by Application Load/Save functions for defining the application file type. Syntax typedef enum ACSC_APPSL_FILETYPE{ACSC_ADJ, ACSC_SP, ACSC_ACSPL, ACSC_PAR, ACSC_USER}; Arguments ACSC_ADJ Value 0: File type is an Adjuster. ACSC_SP Value 1: File type is an SP application. ACSC_ACSPL Value 2: File type is a Program Buffer. ACSC_PAR Value 3: File type is a Parameters file. ACSC_USER Value 4: File type is a User file 31 January 2009 404 Enums
- 419. C Library Reference Version 6.50 Programmer’s Guide 9 Sample Programs The following samples demonstrate the usage of the SPiiPlus C Library functions. The examples show how to write the C/C++ applications that can communicate with the SPiiPlus controller. The samples open the communication with the controller or the simulator and perform some simple tasks, like starting of a point-to-point motion, reading of a motor feedback position, downloading an ACSPL+ program to the controller program buffer, etc. After installation of the package in the SPiiPlus C Library directory, the full source code of these samples with the projects for Visual C++ 6 and Visual Studio 2005 can be found. 9.1 Reciprocated Motion The following two samples execute a reciprocated point-to-point motion and read a motor feedback position. The first sample downloads the ACSPL+ program to the controller’s program buffer and run it with help of the SPiiPlus C functions. The second sample uses the SPiiPlus C functions to execute motion. Both of the samples are written as Win32 console applications. 9.1.1 ACSPL+ The sample shows how to open communication with the simulator or with the controller (via serial, ethernet or PCI Bus), how to download the ACSPL+ program to controller's buffer, and how to execute it. The ACSPL+ program executes a reciprocated point-to-point motion. File ACSPL.CPP: #include <conio.h> #include <stdio.h> #include "windows.h" #include "C:Program FilesACS Motion ControlSPiiPlus 6.50ACSCC_CPPacsc.h" HANDLE hComm; // communication handle void ErrorsHandler(const char* ErrorMessage, BOOL fCloseComm) { printf (ErrorMessage); printf ("press any key to exit.n"); if (fCloseComm) acsc_CloseComm(hComm); _getch(); }; int main(int argc, char *argv[]) { 31 January 2009 405 Sample Programs
- 420. C Library Reference Version 6.50 Programmer’s Guide double FPOS; // ACSPL+ program which we download to controller's buffer // The program performs a reciprocated motion from position 0 to 4000 // and then back char* prog = " enable X rn St: rn ptp X, 4000 rn ptp X, 0 rn goto St rn stop rn "; printf ("ACS-Tech80 Ltd. Copyright (C) 2000. All Rights Reserved.n"); printf ("Application executes reciprocated point-to-point motionn"); /*****************************************************************/ // Open communication with simulator printf ("Application opens communication with the simulator, downloadsn"); printf ("program to controller's and executes it using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the simulator...n"); hComm = acsc_OpenCommDirect(); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the simulator was established successfully!n"); /*****************************************************************/ /******************************************************************** // Example of opening communication with the controller via COM1 printf ("Application opens communication with the controller via COM1, downloadsn"); printf ("program to the controller and executes it using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the controller...n"); 31 January 2009 406 Sample Programs
- 421. C Library Reference Version 6.50 Programmer’s Guide hComm = acsc_OpenCommSerial(1, 115200); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the controller was established successfully!n"); /*******************************************************************/ /******************************************************************** // Example of opening communication with controller via Ethernet printf ("Application opens communication with the controller via Ethernet, downloadsn"); printf ("program to the controller and executes it using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the controller...n"); // 10.0.0.100 - default IP address of the controller // for the point-to-point connection to the controller hComm = acsc_OpenCommEthernet("10.0.0.100", ACSC_SOCKET_DGRAM_PORT); // for the connection to the controller via local network or Internet // hComm = acsc_OpenCommEthernet("10.0.0.100", ACSC_SOCKET_STREAM_PORT); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the controller was established successfully!n"); /*******************************************************************/ /******************************************************************** // Open communication with the controller via PCI bus // (for the SPiiPlus PCI-8 series only) printf ("Application opens communication with the controller andn"); printf ("sends some commands to the controller using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the 31 January 2009 407 Sample Programs
- 422. C Library Reference Version 6.50 Programmer’s Guide controller...n"); hComm = acsc_OpenCommPCI(ACSC_NONE); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the controller was established successfully!n"); /*****************************************************************/ printf ("Press any key to run motion.n"); printf ("Then press any key to exit.n"); _getch(); // Stop a program in the buffer 0 if (!acsc_StopBuffer(hComm, 0, NULL)) { ErrorsHandler("stop program error.n", TRUE); return -1; } // Download the new program to the controller's buffer if (!acsc_LoadBuffer(hComm, 0, prog, strlen(prog), NULL)) { ErrorsHandler("downloading program error.n", TRUE); return -1; } printf ("Program downloadedn"); // Execute the program in the buffer 0 if (!acsc_RunBuffer(hComm, 0, NULL, NULL)) { ErrorsHandler("run program error.n", TRUE); return -1; } 31 January 2009 408 Sample Programs
- 423. C Library Reference Version 6.50 Programmer’s Guide printf ("Motion is in progress...n"); printf ("Feedback position:n"); while (!_kbhit()) { // read the feedback position of axis X if (acsc_GetFPosition(hComm, ACSC_AXIS_X, &FPOS, NULL)) { printf ("%fr", FPOS); } Sleep(500); } // Stop the program in the buffer 0 if (!acsc_StopBuffer(hComm, 0, NULL)) { ErrorsHandler("stop program error.n", TRUE); return -1; } // Close the communication acsc_CloseComm(hComm); return 0; } 9.1.2 Immediate The sample shows how to open communication with the simulator or with the controller (via serial, ethernet or PCI Bus) and how to execute a reciprocated point-to-point motion only by calling appropriate SPiiPlus C functions without any ACSPL+ program. File IMMEDIATE.CPP: #include <conio.h> #include <stdio.h> #include "windows.h" #include "C:Program FilesACS Motion ControlSPiiPlus 6.50ACSCC_CPPacsc.h" HANDLE hComm; // communication handle 31 January 2009 409 Sample Programs
- 424. C Library Reference Version 6.50 Programmer’s Guide void ErrorsHandler(const char* ErrorMessage, BOOL fCloseComm) { printf (ErrorMessage); printf ("press any key to exit.n"); if (fCloseComm) acsc_CloseComm(hComm); _getch(); }; int main(int argc, char *argv[]) { double FPOS; int State; printf ("ACS-Tech80 Ltd. Copyright (C) 2000. All Rights Reserved.n"); printf ("Application executes reciprocated point-to-point motionn"); /*****************************************************************/ // Open communication with the simulator printf ("Application opens communication with the simulator andn"); printf ("sends some commands to the simulator using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the simulator...n"); hComm = acsc_OpenCommDirect(); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the simulator was established successfully!n"); /*****************************************************************/ /****************************************************************** // Example of opening communication with the controller via COM1 printf ("Application opens communication with the controller via serial link andn"); printf ("sends some commands to the controller using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the controller...n"); hComm = acsc_OpenCommSerial(1, 115200); 31 January 2009 410 Sample Programs
- 425. C Library Reference Version 6.50 Programmer’s Guide if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the controller was established successfully!n"); /*****************************************************************/ /****************************************************************** // Example of opening communication with the controller via Ethernet printf ("Application opens communication with the controller via ethernet andn"); printf ("sends some commands to the controller using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the controller...n"); // 10.0.0.100 - default IP address of the controller // for the point to point connection to the controller hComm = acsc_OpenCommEthernet("10.0.0.100", ACSC_SOCKET_DGRAM_PORT); // for the connection to the controller via local network or Internet // hComm = acsc_OpenCommEthernet("10.0.0.100", ACSC_SOCKET_STREAM_PORT); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the controller was established successfully!n"); /*******************************************************************/ /******************************************************************** // Open communication with the controller via PCI bus // (for the SPiiPlus PCI-8 series only) printf ("Application opens communication with the controller andn"); printf ("sends some commands to the controller using SPiiPlus C Library functionsnn"); printf ("Wait for opening of communication with the controller...n"); 31 January 2009 411 Sample Programs
- 426. C Library Reference Version 6.50 Programmer’s Guide hComm = acsc_OpenCommPCI(ACSC_NONE); if (hComm == ACSC_INVALID) { ErrorsHandler("error while opening communication.n", FALSE); return -1; } printf ("Communication with the controller was established successfully!n"); /*****************************************************************/ printf ("Press any key to run motion.n"); printf ("Then press any key to exit.n"); _getch(); // Enable the motor X if (!acsc_Enable(hComm, ACSC_AXIS_X, NULL)) { ErrorsHandler("transaction error.n", TRUE); return -1; } printf ("Motor enabledn"); while (!_kbhit()) { // execute point-to-point motion to position 4000 if (!acsc_ToPoint(hComm, 0, ACSC_AXIS_X, 4000, NULL)) { ErrorsHandler("PTP motion error.n", TRUE); return -1; } printf ("Moving to the position 4000...n"); // execute backward point-to-point motion to position 0 if (!acsc_ToPoint(hComm, 0, ACSC_AXIS_X, 0, NULL)) { ErrorsHandler("PTP motion error.n", TRUE); return -1; } printf ("Moving back to the position 0...n"); // Check if both of motions finished 31 January 2009 412 Sample Programs
- 427. C Library Reference Version 6.50 Programmer’s Guide do { if (acsc_GetFPosition(hComm, ACSC_AXIS_X, &FPOS, NULL)) { printf ("%fr", FPOS); } // Read the motor X state. Fifth bit shows motion // process if (!acsc_GetMotorState(hComm, ACSC_AXIS_X, &State,NULL)) { ErrorsHandler("get motor state error.n", TRUE); return -1; } Sleep(500); } while (State & ACSC_MST_MOVE); } acsc_CloseComm(hComm); return 0; } 9.2 Communication Terminal One more sample of the SPiiPlus C Library is the simple communication terminal that allows communication with the SPiiPlus controller via any communication channel like a serial link (RS-232), Ethernet network, PCI Bus, and with the simulator. The sample can be useful for different user applications. The sample is written in Visual C++ and use’s the MFC library classes. The full source code with comments can be found in the SPiiPlus C Library directory. 31 January 2009 413 Sample Programs