0% found this document useful (0 votes)
67 views418 pages

SPiiPlus C Library (V5-20)

Uploaded by

Nikita Stenin
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
67 views418 pages

SPiiPlus C Library (V5-20)

Uploaded by

Nikita Stenin
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 418

S Pi i P L US

C Library

Programmers’ Guide
Version 5.20
V e r s i o n 5 . 2 0 , October 30, 2006
COPYRIGHT
Copyright ® 1999 - 2005 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.

Website: http://www.AcsMotionControl.com
Information: [email protected]
Tech Support: [email protected]

ACS Motion Control, Inc.


14700 28th Ave North - Suite 25
Plymouth, MN 55447
Tel: 800-545-2980
Tel. 763-559-7669
Fax. 763-559-0110
ACS Motion Control, Ltd.
Ramat Gabriel Industrial Park
POB 5668
Migdal HaEmek, 10500
ISRAEL
Tel: (972) (4) 6546440
Fax: (972) (4) 6546443
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.

October 30, 2006 ii Programmer’s Guide


Programmer’s Guide

Changes in Version 4.5

Page Change
16 Section 3.3.1, Redistributed Files - updated lists
16 Section 3.3.2, File Destinations - updated lists
99 Section 5.40.3, information in paragraph updated
128 Section 5.54, acsc_GetConf Spelling correction in function name; int * Value
changed to double * Value
193 Section 5.94, acsc_GetSingleMessage - new function
272 Section 5.140, acsc_SetCallback - interrupt parameters updated, updated
information in the Note
274 Section 5.141, acsc_SetCallbackExt - interrupt parameters updated, updated
information in the Note
280 Section 5.144, acsc_SetConf - key parameters updated
291 Section 5.151, acsc_SetInterruptMask - parameters updated
313 Section 5.165, acsc_SetServer - new function added
388 Section 7.12, Callback Interrupts Types - this section is rearranged into
Table 52, Callback Interrupts Types - Hardware and Table 53, Callback
Interrupts Types - Software
390 Section 7.13, Callback Interrupts Masks - new masks added

Changes in Version 5.20

Page Change
5 Section 2.1, Operation Environment - Support for Microsoft Windows
authentication as required by Windows XP Service Pack 2.
5 Section 2.2, Communication Log - Description of the implementation of the User-
Mode Driver communication log.
31 Table 37, Error Diagnosis - acsc_GetMotionError removed from table
119 acsc_FlushLogFile - New function
132 acsc_GetEthernetCards - New function
165 acsc_GetMotionError - Obsolete function, note added
315 acsc_SetServerExt - New function
316 acsc_SetServerLoginExt - New function

369 Section 5.197, acsc_WriteLogFile - function behavior changed, a log file no


longer needs to be explicitly opened.

Version 5.20, October 30, 2006 iii Programmer’s Guide


C Library Reference Version 5.20 Programmer’s Guide

Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Organization of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Related SPiiPlus Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 The SPiiPlus Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.4 Conventions Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.5 Statement Text and Icons Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Operation Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Communication Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1 Library Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Building C/C++ Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 Redistribution of User Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 List of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.1 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.2 Service Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3 ACSPL+ Program Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.4 Read and Write Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5 Load File to ACSPL+ Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.6 Multiple Thread Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.7 History Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.8 Unsolicited Messages Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.9 Log File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.10 System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.11 Setting and Reading the Motion Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.12 Axis/Motor Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.13 Motion Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.14 Point-to-Point Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.15 Track Motion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.16 Jogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.17 Slaved Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.18 Multi-Point Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

October 30, 2006 iv Table of Contents


C Library Reference Version 5.20 Programmer’s Guide

4.19 Arbitrary Path Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26


4.20 PVT Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.21 Segmented Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.22 Points and Segments Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.23 Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.24 Status Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.25 Input/Output Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.26 Safety Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.27 Wait-for-Condition Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.28 Callback Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.29 Variables Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.30 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.31 Error Diagnosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.32 Dual Port RAM (DPRAM) Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.33 Position Event Generation (PEG) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5 Detailed Function Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.1 acsc_AddPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.2 acsc_AddPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.3 acsc_AddPVPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.4 acsc_AddPVPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.5 acsc_AddPVTPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.6 acsc_AddPVTPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.7 acsc_AppendBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.8 acsc_Arc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.9 acsc_Arc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.10 acsc_AssignPins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.11 acsc_Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.12 acsc_BreakM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.13 acsc_CancelOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.14 acsc_CaptureComm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.15 acsc_ClearBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.16 acsc_ClearVariables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.17 acsc_CloseComm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.18 acsc_CloseHistoryBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.19 acsc_CloseLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.20 acsc_CloseMessageBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.21 acsc_Collect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.22 acsc_CollectB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.23 acsc_Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.24 acsc_CompileBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.25 acsc_DeclareVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.26 acsc_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5.27 acsc_DisableAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.28 acsc_DisableExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.29 acsc_DisableFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.30 acsc_DisableM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
5.31 acsc_DisableResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

October 30, 2006 v Table of Contents


C Library Reference Version 5.20 Programmer’s Guide

5.32 acsc_DownloadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.33 acsc_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.34 acsc_EnableFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.35 acsc_EnableM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
5.36 acsc_EnableResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
5.37 acsc_EndSequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
5.38 acsc_EndSequenceM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
5.39 acsc_ExtAddPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
5.40 acsc_ExtAddPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
5.41 acsc_ExtArc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5.42 acsc_ExtArc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.43 acsc_ExtLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
5.44 acsc_ExtToPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
5.45 acsc_ExtToPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.46 acsc_FaultClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.47 acsc_FaultClearM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.48 acsc_FlushLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.49 acsc_GetAcceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.50 acsc_GetAnalogInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.51 acsc_GetAnalogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.52 acsc_GetAxisState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.53 acsc_GetCommOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.54 acsc_GetConf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.55 acsc_GetDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.56 acsc_GetDefaultTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
5.57 acsc_GetEthernetCards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
5.58 acsc_GetErrorString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
5.59 acsc_GetExtInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
5.60 acsc_GetExtInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.61 acsc_GetExtOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.62 acsc_GetExtOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
5.63 acsc_GetFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.64 acsc_GetFaultMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.65 acsc_GetFirmwareVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
5.66 acsc_GetFPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.67 acsc_GetFVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.68 acsc_GetHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.69 acsc_GetIndexState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
5.70 acsc_GetInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.71 acsc_GetInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
5.72 acsc_GetInterruptMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.73 acsc_GetJerk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.74 acsc_GetKillDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.75 acsc_GetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
5.76 acsc_GetLibraryVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.77 acsc_GetMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.78 acsc_GetMotionError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
5.79 acsc_GetMotorError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

October 30, 2006 vi Table of Contents


C Library Reference Version 5.20 Programmer’s Guide

5.80 acsc_GetMotorState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169


5.81 acsc_GetOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
5.82 acsc_GetOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
5.83 acsc_GetPCICards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
5.84 acsc_GetProgramError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.85 acsc_GetProgramState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.86 acsc_GetQueueOverflowTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
5.87 acsc_GetResponseMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
5.88 acsc_GetRPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
5.89 acsc_GetRVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
5.90 acsc_GetSafetyInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
5.91 acsc_GetSafetyInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.92 acsc_GetSafetyInputPortInv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.93 acsc_GetSerialNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
5.94 acsc_GetSingleMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
5.95 acsc_GetTargetPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
5.96 acsc_GetTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
5.97 acsc_GetVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
5.98 acsc_Go . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
5.99 acsc_GoM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.100 acsc_Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
5.101 acsc_Halt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
5.102 acsc_HaltM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
5.103 acsc_Jog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
5.104 acsc_JogM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
5.105 acsc_Kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
5.106 acsc_KillAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
5.107 acsc_KillExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
5.108 acsc_KillM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
5.109 acsc_Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
5.110 acsc_LoadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
5.111 acsc_LoadBufferIgnoreServiceLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
5.112 acsc_LoadBuffersFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
5.113 acsc_LoadFileToIntegerVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
5.114 acsc_LoadFileToRealVariable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
5.115 acsc_MultiPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
5.116 acsc_MultiPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
5.117 acsc_OpenCommDirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
5.118 acsc_OpenCommEthernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
5.119 acsc_OpenCommPCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
5.120 acsc_OpenCommSerial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
5.121 acsc_OpenHistoryBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
5.122 acsc_OpenLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
5.123 acsc_OpenMessageBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
5.124 acsc_PegI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
5.125 acsc_PegR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
5.126 acsc_Projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
5.127 acsc_ReadDPRAMInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

October 30, 2006 vii Table of Contents


C Library Reference Version 5.20 Programmer’s Guide

5.128 acsc_ReadDPRAMReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251


5.129 acsc_ReadInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
5.130 acsc_ReadReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
5.131 acsc_Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
5.132 acsc_ReleaseComm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
5.133 acsc_ResetIndexState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
5.134 acsc_RunBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
5.135 acsc_Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
5.136 acsc_Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
5.137 acsc_SetAcceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
5.138 acsc_SetAccelerationImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
5.139 acsc_SetAnalogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
5.140 acsc_SetCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
5.141 acsc_SetCallbackExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
5.142 acsc_SetCallbackPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
5.143 acsc_SetCommOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
5.144 acsc_SetConf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
5.145 acsc_SetDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
5.146 acsc_SetDecelerationImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
5.147 acsc_SetExtOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
5.148 acsc_SetExtOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
5.149 acsc_SetFaultMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
5.150 acsc_SetFPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
5.151 acsc_SetInterruptMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
5.152 acsc_SetIterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
5.153 acsc_SetJerk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
5.154 acsc_SetJerkImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
5.155 acsc_SetKillDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
5.156 acsc_SetKillDecelerationImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
5.157 acsc_SetLogFileOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
5.158 acsc_SetMaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
5.159 acsc_SetOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
5.160 acsc_SetOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.161 acsc_SetQueueOverflowTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
5.162 acsc_SetResponseMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.163 acsc_SetRPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
5.164 acsc_SetSafetyInputPortInv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
5.165 acsc_SetServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
5.166 acsc_SetServerExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
5.167 acsc_SetServerLoginExt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
5.168 acsc_SetTargetPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
5.169 acsc_SetTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
5.170 acsc_SetVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
5.171 acsc_SetVelocityImm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
5.172 acsc_Slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
5.173 acsc_SlaveStalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
5.174 acsc_Spline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
5.175 acsc_SplineM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

October 30, 2006 viii Table of Contents


C Library Reference Version 5.20 Programmer’s Guide

5.176 acsc_Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334


5.177 acsc_SplitAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
5.178 acsc_StopBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
5.179 acsc_StopCollect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
5.180 acsc_StopPeg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
5.181 acsc_Stopper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
5.182 acsc_SuspendBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
5.183 acsc_Track . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
5.184 acsc_ToPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
5.185 acsc_ToPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
5.186 acsc_Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
5.187 acsc_UploadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
5.188 acsc_WaitCollectEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
5.189 acsc_WaitForAsyncCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
5.190 acsc_WaitInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
5.191 acsc_WaitLogicalMotionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
5.192 acsc_WaitMotionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
5.193 acsc_WaitMotorEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
5.194 acsc_WaitProgramEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
5.195 acsc_WaitUserCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
5.196 acsc_WriteInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
5.197 acsc_WriteLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
5.198 acsc_WriteReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
5.199 acsc_WriteDPRAMInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
5.200 acsc_WriteDPRAMReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
6 List of Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
7 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
7.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
7.2 General Communication Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
7.3 Ethernet Communication Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
7.4 Axis Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
7.5 Motion Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
7.6 Data Collection Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
7.7 Motor State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
7.8 Axis State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
7.9 Index and Mark State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
7.10 Program State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
7.11 Safety Control Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
7.12 Callback Interrupts Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
7.13 Callback Interrupts Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
7.14 Configuration Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
8 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
8.1 ACSC_WAITBLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
8.2 ACSC_PCI_SLOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
8.3 ACSC_HISTORYBUFFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
9 Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

October 30, 2006 ix Table of Contents


C Library Reference Version 5.20 Programmer’s Guide

9.1 ACSC_LOG_DETALIZATION_LEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395


9.2 ACSC_LOG_DATA_PRESENTATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
10 Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
10.1 Reciprocated Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
10.2 Communication Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

October 30, 2006 x Table of Contents


C Library Reference Version 5.20 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 Registry Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 6 Registry Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 7 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 8 Service Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 9 ASSPL+ Program Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Table 10 Read and Write Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 11 Load File to ACSPL+ Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 12 Multiple Thread Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 13 History Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 14 Unsolicited Messages Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 15 Log File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 16 System Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 17 Setting and Reading Motion Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 18 Axis/Motor Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 19 Motion Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 20 Point-to-Point Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 21 Track Motion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 22 Jogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 23 Slaved Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 24 Multi-point Motion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 25 Arbitrary Path Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 26 PVT Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 27 Segmented Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 28 Points and Segments Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 29 Data Collection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 30 Status Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 31 Input/Output Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 32 Safety Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 33 Wait-for-Condition Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 34 Callback Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 35 Variables Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 36 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 37 Error Diagnosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 38 Dual Port RAM (DPRAM) Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 39 Position Event Generation (PEG) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 40 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Table 41 General Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Table 42 General Communication Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Table 43 Ethernet Communication Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Table 44 Axis Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Table 45 Motion Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Table 46 Data Collection Flags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Table 47 Data Collection Flags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Table 48 Axis State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Table 49 Index and Mark State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Table 50 Program State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

October 30, 2006 xi List of Tables


C Library Reference Version 5.20 Programmer’s Guide

Table 51 Safety Control Masks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387


Table 52 Callback Interrupts Types - Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Table 53 Callback Interrupts Types - Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Table 54 Callback Interrupts Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Table 55 Configuration Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Table 56 Structure Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Table 57 ACSC PCI Slot Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Table 58 ACSC History Buffer Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Table 59 ACSC Log Detalization Level Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Table 60 ACSC Log Detalization Level Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

October 30, 2006 xii List of Tables


C Library Reference Version 5.20 Programmer’s Guide

List of Figures
Figure 1 C Library Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

October 30, 2006 xiii List of Figures


C Library Reference Version 5.20 Programmer’s Guide

1 Introduction
The SPiiPlus C Library supports the creation of a user application that operates in 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


• “General Information” on Page 5
• “Using the SPiiPlus C Library” on Page 15
• “List of Functions” on Page 19
• “Detailed Function Descriptions” on Page 32

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.
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 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.

Version 5.20, October 30, 2006 1 Introduction


C Library Reference Version 5.20 Programmer’s Guide

1.3 The SPiiPlus Documentation

Table 2 Collateral Documentation


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 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)
Guide Analyzer™ is a powerful servo analysis GUI for ACS Motion
Control SPiiPlus motion controllers.
SPiiPlus Modbus User’s Guide Describes Modbus setup and register address.
SPiiPlus SA and SA-LT Installation and hardware connection with the SPiiPlus SA
Hardware Guide and SPiiPlus SA-LT Controllers
SPiiPlus 3U Hardware Guide Installation and hardware connection with the SPiiPlus 3U
Controller.

Version 5.20, October 30, 2006 2 Introduction


C Library Reference Version 5.20 Programmer’s Guide

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.
| When used in command syntax, indicates input from one
alternative or another.
When used in GUI descriptions, indicates 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.

1.5 Statement Text and Icons Used in this


Guide

Note
Highlights an essential operating or maintenance procedure,
condition, or statement

Version 5.20, October 30, 2006 3 Introduction


C Library Reference Version 5.20 Programmer’s Guide

Model
Model Dependent Text Here!

CAUTION
Caution describes a condition that may result in damage to
equipment.

A warning describes a condition that may result in serious


bodily injury, or death!

Version 5.20, October 30, 2006 4 Introduction


C Library Reference Version 5.20 Programmer’s Guide

2 General Information

2.1 Operation Environment


The SPiiPlus C Library supports Microsoft® Windows® ME, NT, 2000, and XP.
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
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).
The authorized remote access is supported in Windows NT, Windows 2000 and Windows XP
(Service Pack 1 and Service Pack 2).

2.2 Communication Log


For a detailed description of the User-Mode Driver interface, refer to SPiiPlus Firmware and
Tools Release Notesfor Version 5.0.

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

October 30, 2006 5 General Information


C Library Reference Version 5.20 Programmer’s Guide

communication tasks.
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

spiiplushost

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.

October 30, 2006 6 General Information


C Library Reference Version 5.20 Programmer’s Guide

2.6 Programming Languages


The library directly supports development of C/C++ applications. Visual Basic® or other
languages can also be used with little additional effort. For languages other then 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.
• Communication history

October 30, 2006 7 General Information


C Library Reference Version 5.20 Programmer’s Guide

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 “Callbacks” on
Page 9,
• 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 “Callbacks” on Page 9. 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.
• Support for Windows 9/x/NT/2000/ME

October 30, 2006 8 General Information


C Library Reference Version 5.20 Programmer’s Guide

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.lib to the project.
For example, the following function 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.

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

October 30, 2006 9 General Information


C Library Reference Version 5.20 Programmer’s Guide

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).
• 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.

October 30, 2006 10 General Information


C Library Reference Version 5.20 Programmer’s Guide

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 bit S_FAULT.#ES
generated on positive or changes from zero to one.
negative edge of the The message is disabled if S_FMASK.#ES is
input ES signal. zero.
The edge is selected by
S_SAFINI.#ES bit.
Mark 1 and Mark 2 The interrupt is The message is sent when corresponding
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.
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).
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 of DPRAM communication in non-PCI communication channel is recommended if
an application is primarily intended for PCI channel, but requires full compatibility with
other communication channels.

October 30, 2006 11 General Information


C Library Reference Version 5.20 Programmer’s Guide

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; };
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

October 30, 2006 12 General Information


C Library Reference Version 5.20 Programmer’s Guide

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.

If you work with multiple non-waiting calls and the


Note 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.

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
buf, // input buffer that receives
// controller response
100, // size of this buffer
&Received, // number of characters that were
//actually received

October 30, 2006 13 General Information


C Library Reference Version 5.20 Programmer’s Guide

NULL // waiting call


{
printf(“transaction error: %d\n”, 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: %s\n”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘\0’;
printf(“error: %s\n”, buf);
}
}
else
{
printf(“transaction error: %d\n”, 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: %d\n”, acsc_GetLastError());
}

October 30, 2006 14 General Information


C Library Reference Version 5.20 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:
• SPII.SYS, WINDRVR.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.DLL – Dynamic Link Library that contains the API functions. The DLL is
installed in the SYSTEM directory, so it is accessible to all host applications.
• ACSCL.LIB – Static LIB file is required for a C/C++ project to access the DLL functions.
• 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.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 Files\ACS Motion Control\SPiiPlus …\ACSC to the project
directory. Include file ACSCL.LIB in your C/C++ project.
2. Include file ACSC.H in each project file where the functions must be called. Use the
statement #include “ACSC.H”.
3. Once the application that includes ACSCL.LIB file is activated it locates file ACSCL.DLL,
so the ACSCL.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.

Version 5.20, October 30, 2006 15 Using the SPiiPlus C Library


C Library Reference Version 5.20 Programmer’s Guide

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 Files\ACS Motion Control\SPiiPlus
…\Redist,” and include:
• ACSCL.DLL – C Library API
• MFC71.DLL,MSVCR71.DLL - Microsoft® C Runtime Libraries
• WINDRVR.SYS(Win 2000/XP/NT) or WINDRVR.VXD(WIN 95/98),
• WDUSB.SYS - (Jungo© WinDriver Device Driver)
• SPII.SYS or SPII.VXD – Kernel-mode PCI Device Driver
• ACSCSRV.EXE – SPiiPlus user-mode driver

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.DLL
• MFC71.DLL
• MSVCR71.DLL
• SHLWAPI.DLL (for Windows NT only)
The following files differ with each Windows version:
For Windows 2000\XP:
Place the following files in the "System directory"\DRIVERS:
• Win2000_XP\WINDRVR.SYS
• SPII.SYS
For Windows NT:
Place the following files in the "System directory"\DRIVERS:
• Win95_98_NT\WINDRVR.SYS
• Win95_98_NT\WDUSB.SYS
• SPII.SYS

Version 5.20, October 30, 2006 16 Using the SPiiPlus C Library


C Library Reference Version 5.20 Programmer’s Guide

For Windows 98:


Place the following files in the "System directory"\DRIVERS:
• Win95_98_NT\WINDRVR.SYS
• Win95_98_NT\WDUSB.SYS
Place SPII.VXD in the "System directory"\VMM32.
In order to provide WinDriver information for Windows "Plug and Play," redistribute INF files
as follows:
For Windows 98:
• Win95_98_NT\SB1218PCI.INF
For Windows 2000/XP:
• Win2000_XP\SB1218PCI.INF
• Win2000_XP\WD_VIRTUAL.INF

Note
The INF files are required only for registration process; they should be
placed at well-known destination.

Copy ACSCSRV.EXE to target machine. The exact place is not important; 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_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run 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.

Note
ACSCSRV.EXE may be placed anywhere on the target machine.

Version 5.20, October 30, 2006 17 Using the SPiiPlus C Library


C Library Reference Version 5.20 Programmer’s Guide

3.3.3 Kernel-mode Driver Registration


The easiest way to perform Kernel Mode driver installation is to use the following utilities:
• WDREG
• WDREG521
To add drivers to the registry execute the following commands, according to the operating
system, on the target machine and reboot.

Table 5 Registry Drivers


Operating System Files
Windows 2000\XP WDREG cleanoem
WDREG521 -name WinDriver -file windrvr.sys install
WDREG521 cleanphantom
WDREG521 -inf FullPath\sb1218pci.inf loadinf
WDREG521 -inf FullPath\wd_virtual.inf loadinf
WDREG -name "Spii" -file Spii CREATE
Windows NT WDREG.EXE CREATE
WDREG -name "Spii" -file Spii CREATE
Windows 98 WDREG.EXE CREATE
To remove drivers from the registry execute the following commands described in Table 6 on
the target machine, and then reboot.

Table 6 Registry Drivers


Operating System Files
Windows 2000\XP WDREG.EXE -name WinDriver DELETE
WDREG -name "Spii" -file Spii DELETE
Windows NT WDREG.EXE DELETE
WDREG -name "Spii" -file Spii DELETE
Windows 95/98 WDREG.EXE DELETE

Version 5.20, October 30, 2006 18 Using the SPiiPlus C Library


C Library Reference Version 5.20 Programmer’s Guide

4 List of Functions

4.1 Communication Functions


Table 7 Communication Functions
Function Description
acsc_OpenCommSerial Opens communication via serial port.
acsc_OpenCommEthernet Opens communication via Ethernet.
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.

4.2 Service Communication Functions


Table 8 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.

October 30, 2006 19 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

Table 8 Service Communication Functions (page 2 of 2)


Function Description
acsc_SetIterations Sets the number of iterations of one transaction.
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.3 ACSPL+ Program Management Functions


Table 9 ASSPL+ Program Management Functions
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.
acsc_CompileBuffer Compiles ACSPL+ program in the specified program
buffer(s).
acsc_DownloadBuffer The function is 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.

October 30, 2006 20 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

4.4 Read and Write Variables


Table 10 Read and Write Variables
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.5 Load File to ACSPL+ Variable


Table 11 Load File to ACSPL+ Variables
Function Description
acsc_LoadFileToIntegerVariable Loads file to integer variable.
acsc_LoadFileToRealVariable Loads file to real variable.

4.6 Multiple Thread Synchronization


Table 12 Multiple Thread Synchronization
Function Description
acsc_CaptureComm Captures a communication channel.
acsc_ReleaseComm Releases a communication channel.

4.7 History Buffer Management


Table 13 History Buffer Management
Function Description
acsc_OpenHistoryBuffer Opens a history buffer.
acsc_CloseHistoryBuffer Closes a history buffer.
acsc_GetHistory Retrieves the contents of the history buffer.

October 30, 2006 21 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

4.8 Unsolicited Messages Buffer Management


Table 14 Unsolicited Messages Buffer Management
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.9 Log File Management


Table 15 Log File Management
Function Description
acsc_OpenLogFile Opens a log file.
acsc_CloseLogFile Closes a log file.
acsc_WriteLogFile Writes to a log file.

4.10 System Configuration


Table 16 System Configuration
Function Description
acsc_SetConf The function writes system configuration data.
acsc_GetConf The function reads system configuration data.

4.11 Setting and Reading the Motion


Parameters
Table 17 Setting and Reading Motion Parameters (page 1 of 2)
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.

October 30, 2006 22 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

Table 17 Setting and Reading Motion Parameters (page 2 of 2)


Function Description
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.

4.12 Axis/Motor Management


Table 18 Axis/Motor Management (page 1 of 2)
Function Description
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.

October 30, 2006 23 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

Table 18 Axis/Motor Management (page 2 of 2)


Function Description
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.13 Motion Management

Table 19 Motion Management


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.
lacsc_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.
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.14 Point-to-Point Motion

Table 20 Point-to-Point Motion (page 1 of 2)


Function Description
acsc_ToPoint Initiates a single-axis motion to the specified point.
acsc_ToPointM Initiates a multi-axis motion to the specified point.

October 30, 2006 24 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

Table 20 Point-to-Point Motion (page 2 of 2)


Function Description
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.15 Track Motion Control

Table 21 Track Motion Control


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.16 Jogging

Table 22 Jogging
Function Description
acsc_Jog Initiates a single-axis jog motion.
acsc_JogM Initiates a multi-axis jog motion.

4.17 Slaved Motion

Table 23 Slaved Motion


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 following area.

October 30, 2006 25 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

4.18 Multi-Point Motion


Table 24 Multi-point Motion
Function Description
acsc_MultiPoint Initiates a single-axis multi-point motion.
acsc_MultiPointM Initiates a multi-axis multi-point motion.

4.19 Arbitrary Path Motion

Table 25 Arbitrary Path Motion


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.20 PVT Functions


Table 26 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.21 Segmented Motion


Table 27 Segmented Motion (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.

October 30, 2006 26 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

Table 27 Segmented Motion (page 2 of 2)


Function Description
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.
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.22 Points and Segments Manipulation


Table 28 Points and Segments Manipulation
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.23 Data Collection


Table 29 Data Collection
Function Description
acsc_Collect Initiates data collection.
acsc_CollectB Initiates data collection.
acsc_StopCollect Terminates data collection.

October 30, 2006 27 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

4.24 Status Report


Table 30 Status Report
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.

4.25 Input/Output Access


Table 31 Input/Output Access
Function Description
acsc_GetInput Retrieves the current state of the specified digital input.
acsc_GetInterruptMask 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.
acsc_SetExtOutput Sets the specified extended output to the specified value.
acsc_SetExtOutputPort Sets the specified extended output port to the specified
value.

October 30, 2006 28 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

4.26 Safety Control


Table 32 Safety Control
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_SetResponseMask 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.
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.27 Wait-for-Condition Functions


Table 33 Wait-for-Condition Functions (page 1 of 2)
Function Description
acsc_WaitMotionEnd Waits for the end of a motion.
acsc_WaitLogicalMotionEnd Waits for the logical end of a motion.

October 30, 2006 29 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

Table 33 Wait-for-Condition Functions (page 2 of 2)


Function Description
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.

4.28 Callback Registration


Table 34 Callback Registration
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_SetInterruptMask Sets the mask for the specified interrupt.
acsc_GetInterruptMask Retrieves the mask for the specified interrupt.
acsc_SetCallbackPriority Sets the priority for all callback threads.

4.29 Variables Management


Table 35 Variables Management
Function Description
acsc_DeclareVariable Creates the persistent global variable.
acsc_ClearVariables Deletes all persistent global variables.

4.30 Service Functions


Table 36 Service Functions
Function Description
acsc_GetFirmwareVersion Retrieves the firmware version of the controller.
acsc_GetSerialNumber Retrieves the controller serial number.

October 30, 2006 30 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

4.31 Error Diagnosis


Table 37 Error Diagnosis
Function Description
acsc_GetMotorError Retrieves the reason why the motor was disabled.
acsc_GetProgramError Retrieves the error code of the last program error
encountered in the specified buffer.

4.32 Dual Port RAM (DPRAM) Access


Functions
Table 38 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.33 Position Event Generation (PEG)


Functions
Table 39 Position Event Generation (PEG) Functions
Function Description
acsc_PegI Sets incremental PEG
acsc_PegR 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

October 30, 2006 31 List of Functions


C Library Reference Version 5.20 Programmer’s Guide

5 Detailed Function Descriptions


This section describes each of the functions available in the SPiiPlus C Library. The functions
are ordered alphabetically for easy use.
For each function there is a:
• Name and description
• Parameters-Calling syntax, list, and definition of arguments
• Return value
• Remarks
• Example-Short code example in C language

5.1 acsc_AddPoint
The function adds a point to a single-axis multi-point or spline motion.
int acsc_AddPoint(HANDLE Handle, int Axis, double Point, ACSC_WAITBLOCK*
Wait)

5.1.1 Parameters

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 383.

Point Coordinate of the added point.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 32 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.1.2 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.

5.1.3 Remarks
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.

October 30, 2006 33 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.1.4 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: %d\n",acsc_GetLastError());
break;
}
}
// finish the motion

acsc_EndSequence(Handle, 0, NULL); // end of the multi-point motion

5.2 acsc_AddPointM
The function adds a point to a multi-axis multi-point or spline motion.
int acsc_AddPointM(HANDLE Handle, int* Axes, double* Point,
ACSC_WAITBLOCK* Wait)

5.2.1 Parameters

Handle Communication handle.

October 30, 2006 34 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 383.

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 NULL, 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.

5.2.2 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.

5.2.3 Remarks
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

October 30, 2006 35 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

delete the Wait item until a call to the acsc_WaitForAsyncCall function.

5.2.4 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: %d\n", acsc_GetLastError());
break;
}
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion

5.3 acsc_AddPVPoint
The function adds a point to a single-axis PV spline motion and specifies velocity.
int acsc_AddPVPoint(HANDLE Handle, int Axis, double Point, double Velocity,
ACSC_WAITBLOCK* Wait)

5.3.1 Parameters

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 383.

October 30, 2006 36 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Point Coordinate of the added point.

Velocity Desired velocity at the point

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.3.2 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.

5.3.3 Remarks
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
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.

October 30, 2006 37 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.3.4 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: %d\n", 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);

5.4 acsc_AddPVPointM
The function adds a point to a multiple-axis PV spline motion and specifies velocity.
int acsc_AddPVPointM(HANDLE Handle, int *Axis, double *Point, double *Velocity,
ACSC_WAITBLOCK* Wait)

5.4.1 Parameters

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 383.

October 30, 2006 38 Detailed Function Descriptions


C Library Reference Version 5.20 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.

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 NULL, 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.

5.4.2 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.

5.4.3 Remarks
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.

October 30, 2006 39 Detailed Function Descriptions


C Library Reference Version 5.20 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.

5.4.4 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: %d\n", 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);

5.5 acsc_AddPVTPoint
The function adds a point to a single-axis PVT spline motion and specifies velocity and motion
time.
int acsc_AddPVTPoint(HANDLE Handle, int Axis, double Point, double Velocity,double
TimeInterval, ACSC_WAITBLOCK* Wait)

October 30, 2006 40 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.5.1 Parameters

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 383.

Point Coordinate of the added point.

Velocity Desired velocity at the point

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 NULL, 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.

5.5.2 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.

5.5.3 Remarks
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

October 30, 2006 41 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.5.4 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: %d\n", 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);

5.6 acsc_AddPVTPointM
The function adds a point to a multiple-axis PVT spline motion and specifies velocity and
motion time.
int acsc_AddPVTPointM(HANDLE Handle, int *Axis, double *Point, double
*Velocity,double TimeInterval, ACSC_WAITBLOCK* Wait)

October 30, 2006 42 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.6.1 Parameters

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 383.

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.

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 NULL, 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.

5.6.2 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.

5.6.3 Remarks
Before this function can be used, PVT spline motion must be initiated by calling acsc_SplineM
with the appropriate flags.

October 30, 2006 43 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

October 30, 2006 44 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.6.4 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: %d\n", 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);

5.7 acsc_AppendBuffer
The function appends one or more ACSPL+ lines to the program in the specified buffer.
int acsc_AppendBuffer(HANDLE Handle, int Buffer, char* Program, int Count,
ACSC_WAITBLOCK* Wait)

5.7.1 Parameters

Handle Communication handle

October 30, 2006 45 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Buffer Number of a program buffer in the controller.

Program Pointer to the buffer contained ACSPL+ program(s).

Count Number of characters in the buffer pointed by Program

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.7.2 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.

5.7.3 Remarks
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.

October 30, 2006 46 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.7.4 Example

// example of the waiting call of acsc_AppendBuffer


char buf[256];
strcpy(buf, "!This is a test ACSPL+ program\n" );
strcat(buf, "enable X\n" );
strcat(buf, "ptp X, 1000\n" );
strcat(buf, "stop\n" );
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: %d\n", acsc_GetLastError());
}

5.8 acsc_Arc1
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.
int acsc_Arc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int
Rotation, ACSC_WAITBLOCK* Wait)

5.8.1 Parameters

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 383.

October 30, 2006 47 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 NULL, 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.

5.8.2 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.

5.8.3 Remarks
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.
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.

October 30, 2006 48 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.8.4 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: %d\n", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);

5.9 acsc_Arc2
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point and the rotation angle.
int acsc_Arc2(HANDLE Handle, int* Axes, double* Center, double Angle,
ACSC_WAITBLOCK* Wait)

October 30, 2006 49 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.9.1 Parameters

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 383.

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 NULL, 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.

5.9.2 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.

October 30, 2006 50 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.9.3 Remarks
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.
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.

October 30, 2006 51 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.9.4 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: %d\n", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);

5.10 acsc_AssignPins
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.
int acsc_AssignPins(HANDLE Handle,int Axis,unsigned short Mask,
ACSC_WAITBLOCK* Wait)

5.10.1 Parameters

Handle Communication handle.

October 30, 2006 52 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 383.

Mask 16-bit mask defines pins state.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.10.2 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.

5.10.3 Remarks
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.

October 30, 2006 53 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.10.4 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: %d\n", acsc_GetLastError());
}

5.11 acsc_Break
The function terminates a motion immediately and provides a smooth transition to the next
motion.
int acsc_Break(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

5.11.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 54 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.11.2 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.

5.11.3 Remarks
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.

October 30, 2006 55 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.11.4 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);

5.12 acsc_BreakM
The function terminates several motions immediately and provides a smooth transition to the
next motions.
int acsc_BreakM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.12.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 56 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.12.2 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.

5.12.3 Remarks
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
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.

October 30, 2006 57 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.12.4 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);

5.13 acsc_CancelOperation
The function cancels any asynchronous (non-waiting) call or all operations with the specified
communication handle.
int acsc_CancelOperation(HANDLE Handle, ACSC_WAITBLOCK* Wait)

5.13.1 Parameters

Handle Communication handle

Wait Pointer to the ACSC_WAITBLOCK structure that was passed to the


function that initiated the asynchronous (non-waiting) call.

5.13.2 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. Get extended error information by call
acsc_GetLastError.

October 30, 2006 58 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.13.3 Remarks
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.

5.13.4 Example

// cancels all of the waiting and non-waiting calls


if (!acsc_CancelOperation(Handle, NULL))
{
printf("Cancel operation error: %d\n", acsc_GetLastError());
}

5.14 acsc_CaptureComm
The function captures a communication channel.
int acsc_CaptureComm(HANDLE Handle)

5.14.1 Parameters

Handle Communication handle

5.14.2 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.

5.14.3 Remarks
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

October 30, 2006 59 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.14.4 Example

if (!acsc_CaptureComm(Handle))
{
printf("capture communication error: %d\n", acsc_GetLastError());
}

5.15 acsc_ClearBuffer
The function deletes the specified ACSPL+ program lines in the specified program buffer.
int acsc_ClearBuffer(HANDLE Handle, int Buffer, int FromLine, int ToLine,
ACSC_WAITBLOCK* Wait)

5.15.1 Parameters

Handle Communication handle.

Buffer Buffer number, from 0 to 9.

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.

October 30, 2006 60 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.15.2 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.

5.15.3 Remarks
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.

5.15.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 61 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.16 acsc_ClearVariables
The function deletes all persistent global variables.
int acsc_ClearVariables (HANDLE Handle, ACSC_WAITBLOCK* Wait)

5.16.1 Parameters

Handle Communication handle.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.16.2 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.

5.16.3 Remarks
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.

October 30, 2006 62 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.16.4 Example

// example of the waiting call of acsc_ClearVariables


if (!acsc_ClearVariables(Handle, // communication handle
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.17 acsc_CloseComm
The function closes communication via the specified communication channel.
int acsc_CloseComm(HANDLE Handle)

5.17.1 Parameters

Handle Communication handle

5.17.2 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.

5.17.3 Remarks
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.

October 30, 2006 63 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.17.4 Example

if (!acsc_CloseComm(Handle))
{
printf("error closing communication: %d\n", acsc_GetLastError());
}

5.18 acsc_CloseHistoryBuffer
The function closes the history buffer and discards all stored history.
int acsc_CloseHistoryBuffer(HANDLE Handle)

5.18.1 Parameters

Handle Communication handle

5.18.2 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.

5.18.3 Remarks
The function closes the history buffer and releases the used memory. All information stored in
the buffer is discarded.

5.18.4 Example

if (!acsc_CloseHistoryBuffer(Handle))
{
printf("closing history buffer error: %d\n", acsc_GetLastError());
}

5.19 acsc_CloseLogFile
The function closes the log file.

October 30, 2006 64 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_CloseLogFile(HANDLE Handle)

5.19.1 Parameters

Handle Communication handle

5.19.2 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.

5.19.3 Remarks
An application must always call the acsc_CloseLogFile before it exits. Otherwise, the data
written to the file might be lost.

5.19.4 Example

if (!acsc_CloseLogFile(Handle))
{
printf("closing log file error: %d\n", acsc_GetLastError());
}

5.20 acsc_CloseMessageBuffer
The function closes the messages buffer and discards all stored unsolicited messages.
int acsc_CloseMessageBuffer(HANDLE Handle)

5.20.1 Parameters

Handle Communication handle

October 30, 2006 65 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.20.2 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.

5.20.3 Remarks
The function closes the message buffer and releases the used memory. All unsolicited messages
stored in the buffer are discarded.

5.20.4 Example

if (!acsc_CloseMessageBuffer(Handle))
{
printf("closing unsolicited messages buffer error: %d\n",
acsc_GetLastError());
}

5.21 acsc_Collect

Note
This function is equivalent to acsc_CollectB. It is mantained only for
compatibility with previous versions. For new software development
use acsc_CollectB.

The function initiates data collection.


int acsc_Collect(HANDLE Handle, int Flags, char* Array, int NSample, int Period,
char** Vars, ACSC_WAITBLOCK* Wait)

5.21.1 Parameters

Handle Communication handle.

October 30, 2006 66 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Flags Bit-mapped parameter that can include one or more of the following
flags:
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 infinitely. When the array is full, each
new sample overwrites the oldest sample in the array.

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 parameter
defines a minimal period.

Vars Variable list – array of pointers to null-terminated strings.


Each string contains one name of the variable. The values of this
variable 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.
The last element of the array must be NULL that marks the end of the
variable list.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.21.2 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

October 30, 2006 67 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

acsc_GetLastError.

5.21.3 Remarks
The array that stores the samples can be one or two-dimensional. One-dimensional array is
allowed only if the variable list contains one variable name.
The number of the array rows must be equal or more than the number of variables in the variable
list. The number of the array columns must be equal 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.

5.21.4 Example

// example of the waiting call of acsc_Collect


// 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)”, “FPOS(1)”, NULL };
acsc_DeclareVariable(Handle, ACSC_REAL_TYPE, ArrayName, NULL);
if (!acsc_Collect(Handle, // communication handle
0, // 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: %d\n", acsc_GetLastError());
}

5.22 acsc_CollectB
The function initiates data collection.
int acsc_CollectB(HANDLE Handle, int Flags, char* Array, int NSample, int Period,
char* Vars, ACSC_WAITBLOCK* Wait)

October 30, 2006 68 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Note
This function is an improvement of acsc_Collect. For new software
development, it is recommended to use acsc_CollectB.

5.22.1 Parameters

Handle Communication handle.

Flags Bit-mapped parameter that can include one or more of the following
flags:
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 infinitely. When the array is full, each
new sample overwrites the oldest sample in the array.

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 parameter
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.

October 30, 2006 69 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.22.2 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.

5.22.3 Remarks
The array that stores the samples can be one or two-dimensional. One-dimensional array is
allowed only if the variable list contains one variable name.
The number of the array rows must be equal or more than the number of variables in the variable
list. The number of the array columns must be equal 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.

October 30, 2006 70 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.22.4 Example

// example of the waiting call of acsc_Collect


// 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_CollectB(Handle, // communication handle
0, // 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: %d\n", acsc_GetLastError());
}

5.23 acsc_Command
The function sends a command to the controller and analyzes the controller response.
int acsc_Command (HANDLE Handle, char* OutBuf, int OutCount,
ACSC_WAITBLOCK* Wait)

Note
Any ASCII command being sent to the controller must end with '\r' (13)
character, otherwise it won't be recognized as valid.

5.23.1 Parameters

Handle Communication handle

OutBuf Output buffer that contains the request to be sent

October 30, 2006 71 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

OutCount Number of characters in the request

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.23.2 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.

5.23.3 Remarks
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.

October 30, 2006 72 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.23.4 Example

// example of the waiting call of acsc_Command


char* cmd = "enable X\r";
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: %d\n", acsc_GetLastError());
}

5.24 acsc_CompileBuffer
The function compiles ACSPL+ program in the specified program buffer(s).
int acsc_CompileBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait)

5.24.1 Parameters

Handle Communication handle.

Buffer Buffer number, from 0 to 9.


Use ACSC_NONE instead of the buffer number, to compile all
programs in all buffers.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 73 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.24.2 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. Get extended error
information by call 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.

5.24.3 Remarks
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.

5.24.4 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: %d\n", acsc_GetLastError());
}

5.25 acsc_DeclareVariable
The function creates the persistent global variable.
int acsc_DeclareVariable (HANDLE Handle, int Type, char* Name,
ACSC_WAITBLOCK* Wait)

October 30, 2006 74 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.25.1 Parameters

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 NULL, 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.

5.25.2 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.

5.25.3 Remarks
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.

October 30, 2006 75 Detailed Function Descriptions


C Library Reference Version 5.20 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.

5.25.4 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
));

5.26 acsc_Disable
The function shuts off a motor.
int acsc_Disable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

5.26.1 Parameters

Handle Communication handle.

October 30, 2006 76 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.26.2 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 calling
acsc_GetLastError.

5.26.3 Remarks
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.

5.26.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 77 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.27 acsc_DisableAll
The function shuts off all motors.
int acsc_DisableAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)

5.27.1 Parameters

Handle Communication handle.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.27.2 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.

5.27.3 Remarks
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.

October 30, 2006 78 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.27.4 Example

// example of the waiting call of acsc_DisableAll


if (!acsc_DisableAll(Handle, NULL))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.28 acsc_DisableExt
The function shuts off a motor and defines the disable reason.
int acsc_DisableExt(HANDLE Handle, int Axis,int Reason, ACSC_WAITBLOCK*
Wait)

5.28.1 Parameters

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 383.
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 NULL, 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.

5.28.2 Return Value


If the function succeeds, the return value is non-zero.

October 30, 2006 79 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.

5.28.3 Remarks
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.

5.28.4 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: %d\n", acsc_GetLastError());
}

5.29 acsc_DisableFault
The function disables the specified motor or system fault.
int acsc_DisableFault(HANDLE Handle, int Axis, int Fault, ACSC_WAITBLOCK*
Wait)

October 30, 2006 80 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Certain controller faults provide protection against potential


serious bodily injury and damage to equipment. Be aware of
the implications before disabling any alarm, limit, or error.

5.29.1 Parameters

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” on
Page 383.
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” on Page 387 for a detailed
description of these constants.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is NULL, 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.

5.29.2 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.

October 30, 2006 81 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.29.3 Remarks
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.

5.29.4 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: %d\n", acsc_GetLastError());
}

5.30 acsc_DisableM
The function shuts off several motors.
int acsc_DisableM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.30.1 Parameters

Handle Communication handle.

October 30, 2006 82 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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 383.

5.30.2 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.

5.30.3 Remarks
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.

October 30, 2006 83 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.30.4 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: %d\n", acsc_GetLastError());
}

5.31 acsc_DisableResponse
The function disables the default response to the specified motor or system fault.
int acsc_DisableResponse(HANDLE Handle, int Axis, int Response,
ACSC_WAITBLOCK* Wait)

Certain controller faults provide protection against potential


serious bodily injury and damage to equipment. Be aware of
the implications before disabling any alarm, limit, or error.

5.31.1 Parameters

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” on
Page 383.

October 30, 2006 84 Detailed Function Descriptions


C Library Reference Version 5.20 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” on Page 387 for a detailed
description of these constants.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.31.2 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.

5.31.3 Remarks
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.

October 30, 2006 85 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.31.4 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: %d\n", acsc_GetLastError());
}

5.32 acsc_DownloadBuffer
The function is renamed to acsc_AppendBuffer. Previously written applications can use this
function as before.

5.33 acsc_Enable
The function activates a motor.
int acsc_Enable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

5.33.1 Parameters

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 383.

October 30, 2006 86 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.33.2 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.

5.33.3 Remarks
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.

5.33.4 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: %d\n", acsc_GetLastError());
}

5.34 acsc_EnableFault
The function enables the specified motor or system fault.

October 30, 2006 87 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_EnableFault(HANDLE Handle, int Axis, int Fault, ACSC_WAITBLOCK* Wait)

5.34.1 Parameters

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” on
Page 383.

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” on Page 387 for a detailed
description of these constants.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.34.2 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.

5.34.3 Remarks
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.

October 30, 2006 88 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.34.4 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: %d\n", acsc_GetLastError());
}

5.35 acsc_EnableM
The function activates several motors.
int acsc_EnableM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.35.1 Parameters

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 383.

October 30, 2006 89 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.35.2 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.

5.35.3 Remarks
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.

5.35.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 90 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.36 acsc_EnableResponse
The function enables the response to the specified motor or system fault.
int acsc_EnableResponse(HANDLE Handle, int Axis, int Response,
ACSC_WAITBLOCK* Wait)

5.36.1 Parameters

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” on
Page 383.

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” on
Page 387 for a detailed description of these constants.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.36.2 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.

October 30, 2006 91 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.36.3 Remarks
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
delete the Wait item until a call to the acsc_WaitForAsyncCall function.

5.36.4 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: %d\n", acsc_GetLastError());
}

5.37 acsc_EndSequence
The function informs the controller, that no more points will be specified for the current single-
axis motion.
int acsc_EndSequence(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

5.37.1 Parameters

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 383.

October 30, 2006 92 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.37.2 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.

5.37.3 Remarks
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.

October 30, 2006 93 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.37.4 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: %d\n", acsc_GetLastError());
}

5.38 acsc_EndSequenceM
The function informs the controller, that no more points or segments will be specified for the
current multi-axis motion.
int acsc_EndSequence(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.38.1 Parameters

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 383.

October 30, 2006 94 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.38.2 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.

5.38.3 Remarks
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.

October 30, 2006 95 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.38.4 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: %d\n", acsc_GetLastError());
}

5.39 acsc_ExtAddPoint
The function adds a point to a single-axis multi-point or spline motion and specifies a specific
velocity or motion time.
int acsc_ExtAddPoint(HANDLE Handle, int Axis, double Point, double Rate,
ACSC_WAITBLOCK* Wait)

5.39.1 Parameters

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 383.

October 30, 2006 96 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.39.2 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.

5.39.3 Remarks
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.

October 30, 2006 97 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.39.4 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: %d\n", acsc_GetLastError());
break;
}
}
// finish the motion
acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);// end of multi-point motion

5.40 acsc_ExtAddPointM
The function adds a point to a multi-axis multi-point or spline motion and specifies a specific
velocity or motion time.
int acsc_ExtAddPointM(HANDLE Handle, int* Axes, double* Point, double Rate,
ACSC_WAITBLOCK* Wait)

October 30, 2006 98 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.40.1 Parameters

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 383.
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.
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 NULL, 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.

5.40.2 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.

5.40.3 Remarks
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

October 30, 2006 99 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.40.4 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: %d\n", acsc_GetLastError());
break;
}
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion

October 30, 2006 100 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.41 acsc_ExtArc1
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.
int acsc_ExtArc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int
Rotation, double Velocity, ACSC_WAITBLOCK* Wait)

5.41.1 Parameters

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 383.

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 NULL, 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.

October 30, 2006 101 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.41.2 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.

5.41.3 Remarks
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.

October 30, 2006 102 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.41.4 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

October 30, 2006 103 Detailed Function Descriptions


C Library Reference Version 5.20 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: %d\n", 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: %d\n", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);

5.42 acsc_ExtArc2
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.
int acsc_ExtArc2(HANDLE Handle, int* Axes, double* Center, double Angle, double
Velocity, ACSC_WAITBLOCK* Wait)

October 30, 2006 104 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.42.1 Parameters

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 383.

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 NULL, 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.

5.42.2 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.

5.42.3 Remarks
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.

October 30, 2006 105 Detailed Function Descriptions


C Library Reference Version 5.20 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 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.

October 30, 2006 106 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.42.4 Example

// 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: %d\n", 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

October 30, 2006 107 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Axes, // axes XY
Center, // center of the circle
-3.141529,// semicircle
15000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);

5.43 acsc_ExtLine
The function adds a linear segment to a segmented motion and specifies a motion velocity.
int acsc_ExtLine(HANDLE Handle, int* Axes, double* Point, double Velocity,
ACSC_WAITBLOCK* Wait)

5.43.1 Parameters

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 383.

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.

October 30, 2006 108 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.43.2 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.

5.43.3 Remarks
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.

October 30, 2006 109 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.43.4 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);

5.44 acsc_ExtToPoint
The function initiates a single-axis motion to the specified point using the specified velocity or
end velocity.

October 30, 2006 110 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_ExtToPoint(HANDLE Handle, int Flags, int Axis, double Point, double Velocity,
double EndVelocity, ACSC_WAITBLOCK* Wait)

5.44.1 Parameters

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 383.

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 NULL, 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.

October 30, 2006 111 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.44.2 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.

5.44.3 Remarks
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
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.

October 30, 2006 112 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.44.4 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: %d\n", acsc_GetLastError());
}

5.45 acsc_ExtToPointM
The function initiates a multi-axis motion to the specified point using the specified velocity or
end velocity.
int acsc_ExtToPointM(HANDLE Handle, int Flags, int* Axes, double* Point, double
Velocity, double EndVelocity, ACSC_WAITBLOCK* Wait)

5.45.1 Parameters

Handle Communication handle.

October 30, 2006 113 Detailed Function Descriptions


C Library Reference Version 5.20 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 383

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 NULL, 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.

October 30, 2006 114 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.45.2 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.

5.45.3 Remarks
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.

October 30, 2006 115 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.45.4 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: %d\n", acsc_GetLastError());
}

5.46 acsc_FaultClear
The function clears the current faults and the result of the previous fault stored in the
MERR variable.
int acsc_FaultClear(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

October 30, 2006 116 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.46.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.46.2 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 calling
acsc_GetLastError.

5.46.3 Remarks
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.

October 30, 2006 117 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.46.4 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: %d\n", acsc_GetLastError());

5.47 acsc_FaultClearM
The function clears the current faults and results of previous faults stored in the MERR variable
for multiple axes.
int acsc_FaultClearM(HANDLE Handle, int *Axes, ACSC_WAITBLOCK* Wait)

5.47.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 118 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.47.2 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 calling
acsc_GetLastError.

5.47.3 Remarks
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.

5.47.4 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: %d\n", acsc_GetLastError());
}

5.48 acsc_FlushLogFile
This function allows flushing the User-Mode Driver (UMD) internal binary buffer to a
specified text file from the C Library application.
acscFlushLogFile(char*filename)

5.48.1 Parameters

October 30, 2006 119 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.48.2 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 calling
acsc_GetLastError.

5.48.3 Remarks
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.

5.48.4 Example

{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.49 acsc_GetAcceleration
The function retrieves a value of motion acceleration.
int acsc_GetAcceleration(HANDLE Handle, int Axis, double* Acceleration,
ACSC_WAITBLOCK* Wait)

October 30, 2006 120 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.49.1 Parameters

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 383.

Acceleration Pointer to the variable that receives the value of motion acceleration.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.49.2 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 calling
acsc_GetLastError.

5.49.3 Remarks
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.

October 30, 2006 121 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.49.4 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: %d\n", acsc_GetLastError());
}

5.50 acsc_GetAnalogInput
The function retrieves the current numerical value of the specified analog inputs.
int acsc_GetAnalogInput(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK*
Wait)

5.50.1 Parameters

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.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 122 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.50.2 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.

5.50.3 Remarks
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.

5.50.4 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: %d\n", acsc_GetLastError());
}

5.51 acsc_GetAnalogOutput
The function retrieves the current numerical value of the specified analog outputs.
int acsc_GetAnalogOutput(HANDLE Handle, int Port, int* Value,
ACSC_WAITBLOCK* Wait)

October 30, 2006 123 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.51.1 Parameters

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 NULL, 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.

5.51.2 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.

5.51.3 Remarks
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
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.

October 30, 2006 124 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.51.4 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: %d\n", acsc_GetLastError());
}

5.52 acsc_GetAxisState
The function retrieves the current axis state.
int acsc_GetAxisState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK*
Wait)

5.52.1 Parameters

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 383.

October 30, 2006 125 Detailed Function Descriptions


C Library Reference Version 5.20 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 NULL, 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.

5.52.2 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.

5.52.3 Remarks
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.

October 30, 2006 126 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.52.4 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: %d\n", acsc_GetLastError());
}

5.53 acsc_GetCommOptions
The function retrieves the communication options.
int acsc_GetCommOptions(HANDLE Handle, unsigned int* Options)

5.53.1 Parameters

Handle Communication handle

Options Current communication options


Bit-mapped parameter that can include the following flag:
ACSC_COMM_USE_CHECKSUM: communication mode when each
command sends to the controller with checksum and the controller
responds with checksum.

5.53.2 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.

5.53.3 Remarks
The function retrieves the current communication options. To set the communication option

October 30, 2006 127 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

call acsc_SetCommOptions.

5.53.4 Example

// the example of using acsc_GetCommOptions


unsigned int Options;
if (!acsc_GetCommOptions(Handle, &Options))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.54 acsc_GetConf
The function reads system configuration data.
int acsc_GetConf(HANDLE Handle, int Key, int Index, double *Value,
ACSC_WAITBLOCK* Wait)

5.54.1 Parameters

Handle Communication handle.

Key Configuration Key (see “Configuration Keys” on Page 391 )


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

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 128 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.54.2 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.

5.54.3 Remarks
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.

5.54.4 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: %d\n", acsc_GetLastError());
}

5.55 acsc_GetDeceleration
The function retrieves a value of motion deceleration.
int acsc_GetDeceleration(HANDLE Handle, int Axis, double* Deceleration,
ACSC_WAITBLOCK* Wait)

5.55.1 Parameters

Handle Communication handle.

October 30, 2006 129 Detailed Function Descriptions


C Library Reference Version 5.20 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 383

Deceleration Pointer to the variable that receives the value of motion deceleration.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.55.2 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.

5.55.3 Remarks
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.

October 30, 2006 130 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.55.4 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: %d\n", acsc_GetLastError());
}

5.56 acsc_GetDefaultTimeout
The function retrieves default communication timeout.
int acsc_GetDefaultTimeout(HANDLE Handle)

5.56.1 Parameters

Handle Communication handle

5.56.2 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. Get extended error information by call
acsc_GetLastError.

5.56.3 Remarks
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.

October 30, 2006 131 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.56.4 Example

int DefTimeout = acsc_GetDefaultTimeout(Handle);


if (DefTimeout == 0)
{
printf("default timeout receipt error: %d\n", acsc_GetLastError());
}

5.57 acsc_GetEthernetCards
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.
int acsc_GetEthernetCards(in_addr*IPaddresses,int Max, int*Ncontrollers,unsigned
long BroadcastAddress)

5.57.1 Parameters

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

5.57.2 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.

5.57.3 Remarks

Function Execution
The function executes as follows:
1. Broadcasts a message to the network
2. Collects all received replies

October 30, 2006 132 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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-TECH80\r"

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.

Note
SPiiPlus controllers running with FW 4.50 or below will not be found
with a mask other than ACSC_NONE.

October 30, 2006 133 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.57.4 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 %d\n", 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("%s\n",Version);
}
acsc_CloseComm(h);
}
}

5.58 acsc_GetErrorString
The function retrieves the explanation of an error code.
int acsc_GetErrorString(HANDLE Handle, int ErrorCode, char* ErrorStr, int Count,
int* Received)

October 30, 2006 134 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.58.1 Parameters

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

5.58.2 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.

5.58.3 Remarks
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.

October 30, 2006 135 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.58.4 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);
}

5.59 acsc_GetExtInput
The function retrieves the current state of the specified extended input.
int acsc_GetExtInput(HANDLE Handle, int Port, int Bit, int* Value,
ACSC_WAITBLOCK* Wait)

5.59.1 Parameters

Handle Communication handle.

Port Number of the extended 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.

October 30, 2006 136 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.59.2 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.

5.59.3 Remarks
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.

October 30, 2006 137 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.59.4 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: %d\n", acsc_GetLastError());
}

5.60 acsc_GetExtInputPort
The function retrieves the current state of the specified extended input port.
int acsc_GetExtInputPort(HANDLE Handle, int Port, int* Value,
ACSC_WAITBLOCK* Wait)

5.60.1 Parameters

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 NULL, 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.

October 30, 2006 138 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.60.2 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.

5.60.3 Remarks
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
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.

5.60.4 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: %d\n", acsc_GetLastError());
}

5.61 acsc_GetExtOutput
The function retrieves the current state of the specified extended output.
int acsc_GetExtOutput(HANDLE Handle, int Port, int Bit, int* Value,
ACSC_WAITBLOCK* Wait)

5.61.1 Parameters

Handle Communication handle.

October 30, 2006 139 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 NULL, 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.

5.61.2 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.

5.61.3 Remarks
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.

October 30, 2006 140 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.61.4 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: %d\n", acsc_GetLastError());
}

5.62 acsc_GetExtOutputPort
The function retrieves the current state of the specified extended output port.
int acsc_GetExtOutputPort(HANDLE Handle, int Port, int* Value,
ACSC_WAITBLOCK* Wait)

5.62.1 Parameters

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.

October 30, 2006 141 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.62.2 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.

5.62.3 Remarks
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.

October 30, 2006 142 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.62.4 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: %d\n", acsc_GetLastError());
}

5.63 acsc_GetFault
The function retrieves the set of bits that indicate the motor or system faults.
int acsc_GetFault(HANDLE Handle, int Axis, int* Fault, ACSC_WAITBLOCK* Wait)

5.63.1 Parameters

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” on
Page 383.

Fault Pointer to the variable that receives the current set of fault bits.

October 30, 2006 143 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.63.2 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.

5.63.3 Remarks
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” on
Page 387 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.

October 30, 2006 144 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.63.4 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: %d\n", acsc_GetLastError());
}
if (Fault & ACSC_SAFETY_RL)printf("Right Limit fault\n”);
if (Fault & ACSC_SAFETY_LL)printf("Left Limit fault\n”);

5.64 acsc_GetFaultMask
The function retrieves the mask that defines which controller faults are examined and
processed.
int acsc_GetFaultMask(HANDLE Handle, int Axis, int* Mask, ACSC_WAITBLOCK*
Wait)

5.64.1 Parameters

Handle Communication handle

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” on
Page 383.

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” on Page 387 for a detailed description of
these constants.

October 30, 2006 145 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.64.2 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.

5.64.3 Remarks
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
delete the Mask and Wait items until a call to the acsc_WaitForAsyncCall function.

October 30, 2006 146 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.64.4 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: %d\n", acsc_GetLastError());
}

5.65 acsc_GetFirmwareVersion
The function retrieves the firmware version of the controller.
int acsc_GetFirmwareVersion(HANDLE Handle, char* Version, int Count, int*
Received, ACSC_WAITBLOCK* Wait)

5.65.1 Parameters

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.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 147 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.65.2 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.

5.65.3 Remarks
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.

5.65.4 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: %d\n", acsc_GetLastError());
}
else
{
Firmware[Received] = ‘\0’;
printf("Firmware version of the controller: %s\n", Firmware);
}

October 30, 2006 148 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.66 acsc_GetFPosition
The function retrieves an instant value of the motor feedback position.
int acsc_GetFPosition(HANDLE Handle, int Axis, double* FPosition,
ACSC_WAITBLOCK* Wait)

5.66.1 Parameters

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 383.

FPosition Pointer to a variable that receives the instant value of the motor
feedback position.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.66.2 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.

5.66.3 Remarks
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.

October 30, 2006 149 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.66.4 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: %d\n", acsc_GetLastError());
}

5.67 acsc_GetFVelocity
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.
int acsc_GetFVelocity(HANDLE Handle, int Axis, double* FVelocity,
ACSC_WAITBLOCK* Wait)

5.67.1 Parameters

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 383.

FVelocity Pointer to a variable that receives the instant value of the motor
feedback velocity.

October 30, 2006 150 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.67.2 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.

5.67.3 Remarks
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.

5.67.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 151 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.68 acsc_GetHistory
The function retrieves the contents of the history buffer.
int acsc_GetHistory(HANDLE Handle, char* Buf, int Count, int* Received, BOOL
bClear)

5.68.1 Parameters

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

bClear If TRUE, the function clears contents of the history buffer


If FALSE, the history buffer content is not cleared.

5.68.2 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.

5.68.3 Remarks
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.

October 30, 2006 152 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.68.4 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: %d\n", acsc_GetLastError());
}

5.69 acsc_GetIndexState
The function retrieves the current set of bits that indicate the index and mark state.
int acsc_GetIndexState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK*
Wait)

5.69.1 Parameters

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 383.

October 30, 2006 153 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.69.2 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.

5.69.3 Remarks
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.

October 30, 2006 154 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.69.4 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: %d\n", acsc_GetLastError());
}

5.70 acsc_GetInput
The function retrieves the current state of the specified digital input.
int acsc_GetInput(HANDLE Handle, int Port, int Bit, int* Value, ACSC_WAITBLOCK*
Wait)

5.70.1 Parameters

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 NULL, 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.

October 30, 2006 155 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.70.2 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.

5.70.3 Remarks
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.

5.70.4 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: %d\n", acsc_GetLastError());
}

5.71 acsc_GetInputPort
The function retrieves the current state of the specified digital input port.
int acsc_GetInputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK*
Wait)

October 30, 2006 156 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.71.1 Parameters

Handle Communication handle.

Port Number of the 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 NULL, 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.

5.71.2 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.

5.71.3 Remarks
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.

October 30, 2006 157 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.71.4 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: %d\n", acsc_GetLastError());
}

5.72 acsc_GetInterruptMask
The function retrieves the mask for specified interrupt.
int acsc_GetInterruptMask(HANDLE Handle, int Interrupt, int* Mask)

5.72.1 Parameters

Handle Communication handle

Interrupt See “Callback Interrupts Types” on Page 388.

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 Interrupts Masks” on Page 390 for a detailed
description of these constants.
As default all bits for each interrupts are set to one.

5.72.2 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

October 30, 2006 158 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

acsc_GetLastError.

5.72.3 Remarks
The function retrieves the bit mask for specified interrupt. To set the mask for specified
interrupt, call .

5.72.4 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: %d\n", acsc_GetLastError());
}

5.73 acsc_GetJerk
The function retrieves a value of motion jerk.
int acsc_GetJerk(HANDLE Handle, int Axis, double* Jerk, ACSC_WAITBLOCK*
Wait)

5.73.1 Parameters

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 383.

Jerk Pointer to the variable that receives the value of motion jerk.

October 30, 2006 159 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.73.2 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.

5.73.3 Remarks
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.

5.73.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 160 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.74 acsc_GetKillDeceleration
The function retrieves a value of motion kill deceleration.
int acsc_GetKillDeceleration(HANDLE Handle, int Axis, double* KillDeceleration,
ACSC_WAITBLOCK* Wait)

5.74.1 Parameters

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 383.

KillDeceleration Pointer to the variable that receives the value of motion kill
deceleration.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.74.2 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.

5.74.3 Remarks
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

October 30, 2006 161 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

function.

5.74.4 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: %d\n", acsc_GetLastError());
}

5.75 acsc_GetLastError
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.
int acsc_GetLastError()

5.75.1 Parameters
This function has no parameters.

5.75.2 Return Value


The return value is the calling thread’s last-error code value.

5.75.3 Remarks
It is necessary to call acsc_GetLastError immediately when some functions return zero value.
That is because all of the functions rewrite the error code value when they are called.
For a complete List of Error Codes, “List of Error Codes” on Page 375.

October 30, 2006 162 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.75.4 Example

printf("function returned error: %d\n", acsc_GetLastError());

5.76 acsc_GetLibraryVersion
The function retrieves the SPiiPlus C Library version number.
unsigned int acsc_GetLibraryVersion()

5.76.1 Parameters
This function has no parameters.

5.76.2 Return Value


The return value is the 32-bit unsigned integer value, which specifies binary version number.

5.76.3 Remarks
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.

5.76.4 Example

unsigned int Ver = acsc_GetLibraryVersion();


printf("SPiiPlus C Library version is %d.%d.%d.%d\n", HIBYTE(HIWORD(Ver)),
LOBYTE(HIWORD(Ver)), HIBYTE(LOWORD(Ver)), LOBYTE(LOWORD(Ver)));

5.77 acsc_GetMessage
The function retrieves unsolicited messages from the buffer. This function only works if you

October 30, 2006 163 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

setup a buffer using acsc_OpenMessageBuffer. If no message buffer is open, these messages


will be returned by acsc_Receive.
int acsc_GetMessage(HANDLE Handle, char* Buf, int Count, int* Received, BOOL
bClear)

5.77.1 Parameters

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

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.

5.77.2 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.

5.77.3 Remarks
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.

October 30, 2006 164 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.77.4 Example

nt 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: %d\n",
acsc_GetLastError());
}

5.78 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.

The function retrieves the termination code of the last executed motion of the specified axis.
int acsc_GetMotionError(HANDLE Handle, int Axis, int* Error,
ACSC_WAITBLOCK* Wait)

5.78.1 Parameters

Handle Communication handle.

October 30, 2006 165 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.
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 NULL, 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.

5.78.2 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.

5.78.3 Remarks
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.
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.

October 30, 2006 166 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.78.4 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: %d\n", acsc_GetLastError());
}

5.79 acsc_GetMotorError
The function retrieves the reason for motor disabling.
int acsc_GetMotorError(HANDLE Handle, int Axis, int* Error, ACSC_WAITBLOCK*
Wait)

5.79.1 Parameters

Handle Communication handle.

October 30, 2006 167 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.

Error Pointer to a variable that receives the reason why the motor was
disabled.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.79.2 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.

5.79.3 Remarks
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. 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.

October 30, 2006 168 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.79.4 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: %d\n", acsc_GetLastError());
}

5.80 acsc_GetMotorState
The function retrieves the current motor state.

October 30, 2006 169 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_GetMotorState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK*


Wait)

5.80.1 Parameters

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 383.

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 NULL, 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.

5.80.2 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.

5.80.3 Remarks
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.

October 30, 2006 170 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.80.4 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: %d\n", acsc_GetLastError());
}

5.81 acsc_GetOutput
The function retrieves the current state of the specified digital output.
int acsc_GetOutput(HANDLE Handle, int Port, int Bit, int* Value,
ACSC_WAITBLOCK* Wait)

5.81.1 Parameters

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 NULL, 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.

October 30, 2006 171 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.81.2 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.

5.81.3 Remarks
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.
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.

5.81.4 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: %d\n", acsc_GetLastError());
}

5.82 acsc_GetOutputPort
The function retrieves the current state of the specified digital output port.
int acsc_GetOutputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK*
Wait)

October 30, 2006 172 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.82.1 Parameters

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 NULL, 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.

5.82.2 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.

5.82.3 Remarks
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.

October 30, 2006 173 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.82.4 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: %d\n", acsc_GetLastError());
}

5.83 acsc_GetPCICards
The function retrieves information about the controller cards inserted in the computer PCI Bus.
int acsc_GetPCICards(ACSC_PCI_SLOT* Cards, int Count, int* ObtainedCards)

5.83.1 Parameters

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.

5.83.2 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.

5.83.3 Remarks
The function scans the PCI Bus for the inserted controller cards and fills the Cards array with

October 30, 2006 174 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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
• 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.

5.83.4 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 cards\n", DetectedCardsCount);
}
else
{
printf("error while scanning PCI bus: %d\n", acsc_GetLastError());
}

October 30, 2006 175 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.84 acsc_GetProgramError
The function retrieves the error code of the last program error encountered in the specified
buffer.
int acsc_GetProgramError(HANDLE Handle, int Buffer, int* Error,
ACSC_WAITBLOCK* Wait)

5.84.1 Parameters

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 NULL, 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.

5.84.2 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.

5.84.3 Remarks
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. To get the error explanation, use the
function acsc_GetErrorString.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or

October 30, 2006 176 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function.

5.84.4 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: %d\n", acsc_GetLastError());
}

5.85 acsc_GetProgramState
The function retrieves the current state of the program buffer.
int acsc_GetProgramState(HANDLE Handle, int Buffer, int* State,
ACSC_WAITBLOCK* Wait)

5.85.1 Parameters

Handle Communication handle.

Buffer Number of the buffer.

October 30, 2006 177 Detailed Function Descriptions


C Library Reference Version 5.20 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 NULL, 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.

5.85.2 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.

5.85.3 Remarks
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.

October 30, 2006 178 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.85.4 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: %d\n", acsc_GetLastError());
}

5.86 acsc_GetQueueOverflowTimeout
The function retrieves the Queue Overflow Timeout.
int acsc_GetQueueOverflowTimeout(HANDLE Handle)

5.86.1 Parameters

Handle Communication handle.

5.86.2 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. Get extended error information by call
acsc_GetLastError.

5.86.3 Remarks
See explanation about Queue Overflow Timeout in “Non-waiting Calls” on Page 12.

October 30, 2006 179 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.86.4 Example

int QueueTimeout = acsc_GetQueueOverflowTimeout(Handle);


if (QueueTimeout == ACSC_NONE)
{
printf("Queue Overflow Timeout receipt error: %d\n",
acsc_GetLastError());
}x

5.87 acsc_GetResponseMask
The function retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.
int acsc_GetResponseMask(HANDLE Handle, int Axis, int* Mask,
ACSC_WAITBLOCK* Wait)

5.87.1 Parameters

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” on
Page 383.

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” on Page 387 for a detailed description of
these constants.

October 30, 2006 180 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.87.2 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.

5.87.3 Remarks
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.

October 30, 2006 181 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.87.4 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: %d\n", acsc_GetLastError());
}

5.88 acsc_GetRPosition
The function retrieves an instant value of the motor reference position.
int acsc_GetRPosition(HANDLE Handle, int Axis, double* RPosition,
ACSC_WAITBLOCK* Wait)

5.88.1 Parameters

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 383.

Rposition Pointer to a variable that receives the instant value of the motor
reference position.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 182 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.88.2 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.

5.88.3 Remarks
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.

5.88.4 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: %d\n", acsc_GetLastError());
}

5.89 acsc_GetRVelocity
The function retrieves an instant value of the motor reference velocity.
int acsc_GetRVelocity(HANDLE Handle, int Axis, double* RVelocity,
ACSC_WAITBLOCK* Wait)

5.89.1 Parameters

Handle Communication handle.

October 30, 2006 183 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.

RVelocity Pointer to a variable that receives the instant value of the motor
reference velocity.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.89.2 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.

5.89.3 Remarks
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.

October 30, 2006 184 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.89.4 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: %d\n", acsc_GetLastError());
}

5.90 acsc_GetSafetyInput
The function retrieves the current state of the specified safety input.
int acsc_GetSafetyInput(HANDLE Handle, int Axis, int Input, int* Value,
ACSC_WAITBLOCK* Wait)

5.90.1 Parameters

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 383.

October 30, 2006 185 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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” on Page 387 for a detailed description of
these constants.

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 NULL, 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.

5.90.2 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.

5.90.3 Remarks
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.

October 30, 2006 186 Detailed Function Descriptions


C Library Reference Version 5.20 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 specific controller model. For
example, SPiiPlus SA controller does not provide Motor Overheat,
Preliminary Left Limit, or Preliminary Right Limit safety inputs.
See specific model documentation for details.

5.90.4 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: %d\n", acsc_GetLastError());
}

5.91 acsc_GetSafetyInputPort
The function retrieves the current state of the specified safety input port.
int acsc_GetSafetyInputPort(HANDLE Handle, int Axis, int* Value,
ACSC_WAITBLOCK* Wait)

5.91.1 Parameters

Handle Communication handle.

October 30, 2006 187 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 383.

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” on Page 387 for a detailed description of
these constants.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.91.2 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.

5.91.3 Remarks
The function retrieves the current state of the specified safety input port. To get the state of the

October 30, 2006 188 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

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.

5.91.4 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: %d\n", acsc_GetLastError());
}

5.92 acsc_GetSafetyInputPortInv
The function retrieves the set of bits that define inversion for the specified safety input port.
int acsc_GetSafetyInputPortInv(HANDLE Handle, int Axis, int* Value,
ACSC_WAITBLOCK* Wait)

5.92.1 Parameters

Handle Communication handle.

October 30, 2006 189 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 383.

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 NULL, 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.

5.92.2 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.

5.92.3 Remarks
The function retrieves the set of bits that define inversion for the specified safety input port. To

October 30, 2006 190 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.
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.

5.92.4 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: %d\n", acsc_GetLastError());
}

5.93 acsc_GetSerialNumber
The function retrieves the controller serial number.
int acsc_GetSerialNumber(HANDLE Handle, char* SerialNumber, int Count, int*
Received, ACSC_WAITBLOCK* Wait)

October 30, 2006 191 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.93.1 Parameters

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.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.93.2 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.

5.93.3 Remarks
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.

October 30, 2006 192 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.93.4 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: %d\n", acsc_GetLastError());
}
else

{
SerialNumber[Received] = ‘\0’;
printf("Controller serial number: %s\n", SerialNumber);
}

5.94 acsc_GetSingleMessage
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.
int acsc_GetSingleMessage (HANDLE Handle, char *Message,int *Length,int Timeout)

5.94.1 Parameters

Handle Communication handle

Message Pointer to the buffer that receives unsolicited messages, it should be at


least 1K.

Length The actual length of the message

October 30, 2006 193 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Timeout Timeout in milliseconds

5.94.2 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.

5.94.3 Remarks
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.

5.94.4 Example

int Length;
char Buf[10000];
if (!acsc_GetMessage(Handle, // communication handle
Buf, // pointer to the buffer that
// receives unsolicited messages
&L, // number of characters that were actually received
1000 // Wait for 1 second till a message arrives
))
{
printf("getting unsolicited message error: %d\n",
acsc_GetLastError());
}

5.95 acsc_GetTargetPosition
The function retrieves the instant value of track position.
int acsc_GetTargetPosition(HANDLE Handle, int Axis, double *TargetPosition,
ACSC_WAITBLOCK* Wait)

October 30, 2006 194 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.95.1 Parameters

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 383.

TargetPosition The pointer to variable that receives the instant value of the target
position.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.95.2 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.

5.95.3 Remarks
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.

October 30, 2006 195 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.95.4 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: %d\n", acsc_GetLastError());
}

5.96 acsc_GetTimeout
The function retrieves communication timeout.
int acsc_GetTimeout(HANDLE Handle)

5.96.1 Parameters

Handle Communication handle

5.96.2 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. Get extended error information by call
acsc_GetLastError.

5.96.3 Example

int Timeout = acsc_GetTimeout(Handle);


if (Timeout == 0)
{
printf("timeout receipt error: %d\n", acsc_GetLastError());
}

October 30, 2006 196 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.97 acsc_GetVelocity
The function retrieves a value of motion velocity.
int acsc_GetVelocity(HANDLE Handle, int Axis, double* Velocity,
ACSC_WAITBLOCK* Wait)

5.97.1 Parameters

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 383.

Velocity Pointer to the variable that receives the value of motion velocity.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.97.2 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.

5.97.3 Remarks
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.

October 30, 2006 197 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.97.4 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: %d\n", acsc_GetLastError());
}

5.98 acsc_Go
The function starts up a motion waiting in the specified motion queue.
int acsc_Go(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

5.98.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 198 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.98.2 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.

5.98.3 Remarks
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.

5.98.4 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: %d\n", acsc_GetLastError());
}

5.99 acsc_GoM
The function synchronously starts up several motions that are waiting in the specified motion
queues.
int acsc_GoM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

October 30, 2006 199 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.99.1 Parameters

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 383.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is NULL, 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.

5.99.2 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.

5.99.3 Remarks
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.

October 30, 2006 200 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.99.4 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: %d\n", acsc_GetLastError());
}

5.100 acsc_Group
The function creates a coordinate system for a multi-axis motion.
int acsc_Group(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.100.1 Parameters

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 383.
Wait Pointer to ACSC_WAITBLOCK structure.
If Wait is NULL, 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.

October 30, 2006 201 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.100.2 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.

5.100.3 Remarks
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.

5.100.4 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: %d\n", acsc_GetLastError());
}

5.101 acsc_Halt
The function terminates a motion using the full deceleration profile.
int acsc_Halt(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

5.101.1 Parameters

Handle Communication handle.

October 30, 2006 202 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.101.2 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.

5.101.3 Remarks
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.
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.

October 30, 2006 203 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.101.4 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: %d\n", acsc_GetLastError());
}

5.102 acsc_HaltM
The function terminates several motions using the full deceleration profile.
int acsc_HaltM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.102.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 204 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.102.2 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.

5.102.3 Remarks
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.

5.102.4 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: %d\n", acsc_GetLastError());
}

5.103 acsc_Jog
The function initiates a single-axis jog motion.
int acsc_Jog(HANDLE Handle, int Flags, int Axis, double Velocity,
ACSC_WAITBLOCK* Wait)

October 30, 2006 205 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.103.1 Parameters

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 383.

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.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.103.2 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.

5.103.3 Remarks
The function initiates a single-axis jog. To execute multi-axis jog, use acsc_JogM.

October 30, 2006 206 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.103.4 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: %d\n", acsc_GetLastError());
}

5.104 acsc_JogM
The function initiates a multi-axis jog motion.
int acsc_JogM(HANDLE Handle, int Flags, int* Axes, int* Direction, double Velocity,
ACSC_WAITBLOCK* Wait)

October 30, 2006 207 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.104.1 Parameters

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 383.

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 NULL, 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.

5.104.2 Return Value


If the function succeeds, the return value is non-zero.

October 30, 2006 208 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.

5.104.3 Remarks
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.
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.

October 30, 2006 209 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.104.4 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: %d\n", acsc_GetLastError());
}

5.105 acsc_Kill
The function terminates a motion using reduced deceleration profile.
int acsc_Kill(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)

October 30, 2006 210 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.105.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.105.2 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.

5.105.3 Remarks
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.

October 30, 2006 211 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.105.4 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: %d\n", acsc_GetLastError());
}

5.106 acsc_KillAll
The function terminates all currently executed motions.
int acsc_KillAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)

5.106.1 Parameters

Handle Communication handle.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.106.2 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.

October 30, 2006 212 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.106.3 Remarks
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.

5.106.4 Example

// example of the waiting call of acsc_KillAll


if (!acsc_KillAll(Handle, NULL))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.107 acsc_KillExt
The function terminates a motion using reduced deceleration profile and defines the kill reason.
int acsc_KillExt(HANDLE Handle, int Axis, int Reason,ACSC_WAITBLOCK* Wait)

5.107.1 Parameters

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 383.

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.

October 30, 2006 213 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.107.2 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.

5.107.3 Remarks
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.

October 30, 2006 214 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.107.4 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: %d\n", acsc_GetLastError());
}

5.108 acsc_KillM
The function terminates several motions using reduced deceleration profile.
int acsc_KillM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.108.1 Parameters

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 383.

October 30, 2006 215 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.108.2 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.

5.108.3 Remarks
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.

October 30, 2006 216 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.108.4 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: %d\n", acsc_GetLastError());
}

5.109 acsc_Line
The function adds a linear segment to a segmented motion.
int acsc_Line(HANDLE Handle, int* Axes, double* Point, ACSC_WAITBLOCK* Wait)

5.109.1 Parameters

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 383.

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.

October 30, 2006 217 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.109.2 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.

5.109.3 Remarks
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
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.

October 30, 2006 218 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.109.4 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: %d\n", acsc_GetLastError());
}

5.110 acsc_LoadBuffer
The function clears the specified program buffer and then loads ACSPL+ program to this
buffer.
int acsc_LoadBuffer(HANDLE Handle, int Buffer, char* Program, int Count,
ACSC_WAITBLOCK* Wait)

5.110.1 Parameters

Handle Communication handle

Buffer Number of a program buffer in the controller.

Program Pointer to the buffer contained ACSPL+ program(s).

Count Number of characters in the buffer pointed by Program

October 30, 2006 219 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.110.2 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.

5.110.3 Remarks
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.

October 30, 2006 220 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.110.4 Example

// example of the waiting call of acsc_LoadBuffer


char buf[256];
strcpy(buf, "!This is a test ACSPL+ program\n" );
strcat(buf, "enable X\n" );
strcat(buf, "ptp X, 1000\n" );
strcat(buf, "stop\n" );
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: %d\n", acsc_GetLastError());
}

5.111 acsc_LoadBufferIgnoreServiceLines
The function clears the specified program buffer and then loads ACSPL+ to this buffer.
All lines that start with # are ignored.
int acsc_LoadBufferIgnoreServiceLines(HANDLE Handle, int Buffer, char* Program,
int Count, ACSC_WAITBLOCK* Wait)

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.

5.111.1 Parameters

Handle Communication handle

Buffer Number of a program buffer in the controller.

October 30, 2006 221 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Program Pointer to the buffer contained ACSPL+ program(s).

Count Number of characters in the buffer pointed by Program

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.111.2 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.

5.111.3 Remarks
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.

October 30, 2006 222 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.111.4 Example

// example of the waiting call of acsc_LoadBuffer


char buf[256];
strcpy(buf, "!This is a test ACSPL+ program\n" );
strcat(buf, "#Version 3.0 \n" ); //Ignored – won’t be loaded
strcat(buf, "enable X\n" );
strcat(buf, "ptp X, 1000\n" );
strcat(buf, "stop\n" );
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: %d\n", acsc_GetLastError());
}

5.112 acsc_LoadBuffersFromFile
The function opens a file that contains one or more ACSPL+ programs allocated to several
buffers and download the programs to the corresponding buffers.
int acsc_LoadBuffersFromFile(HANDLE Handle, char *Filename,
ACSC_WAITBLOCK* Wait)

5.112.1 Parameters

Handle Communication handle

Filename Path of the file

October 30, 2006 223 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.112.2 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.

5.112.3 Remarks
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.

October 30, 2006 224 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.112.4 Example

// example of the waiting call of acsc_LoadBuffersFromFile


if (!acsc_LoadBuffersFromFile(Handle, // communication
//handle
“C:\\MMI\\Program.prg”, //full path
NULL // waiting call
))
{
printf("acsc_LoadBuffersFromFile: %d\n", acsc_GetLastError());
}

5.113 acsc_LoadFileToIntegerVariable
This function writes value(s) from text file to integer variable.
int acsc_LoadFileToIntegerVariable(HANDLE Handle, int NBuf, char* Var, int From1,
int To1, int From2, int To2, char* Filename,ACSC_WAITBLOCK* Wait)

5.113.1 Parameters

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).

From2, To2 Index range (second dimension).

Filename Path of the text data file.

October 30, 2006 225 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.113.2 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.

5.113.3 Remarks
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
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. The text file,
pointed by Filename parameter, must contain (To1-From1+1)x(To2-From2+1) values at least,
otherwise error will occur. The function uses the text file as follows: first, the function retrieves
the To2-From2 values and writes them to row From1 of the specified controller variable, then
retrieves next To2-From2 values and writes them to row From1+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. Line that starts with no digits is

October 30, 2006 226 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.113.4 Example

// example of the waiting call of acsc_LoadFileToIntegerVariable


if (!acsc_LoadFileToIntegerVariable(
Handle, // communication handle
ACSC_NONE, // standard variable
"UserArray", // variable name
0, 99, // first dimension indexes
0,9, // no second dimension
“UserArr.TXT”, // Text file name contained values
// that must be written
NULL // waiting call
))
{
printf("transaction error: %d\n", 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 ……………

5.114 acsc_LoadFileToRealVariable
The function writes value(s) from text file to real variable.
int acsc_LoadFileToRealVariable(HANDLE Handle, int NBuf, char* Var, int From1, int
To1, int From2, int To2, char* Filename,ACSC_WAITBLOCK* Wait)

October 30, 2006 227 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.114.1 Parameters

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).

From2, To2 Index range (second dimension).

Filename Path of the text data file.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.114.2 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.

5.114.3 Remarks
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.

October 30, 2006 228 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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. The text file,
pointed by Filename parameter, must contain (To1-From1+1)x(To2-From2+1) values at least,
otherwise error will occur. The function uses the text file as follows: first, the function retrieves
the To2-From2 values and writes them to row From1 of the specified controller variable, then
retrieves next To2-From2 values and writes them to row From1+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. 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.

October 30, 2006 229 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.114.4 Example

// example of the waiting call of acsc_LoadFileToRealVariable


if (!acsc_LoadFileToRealVariable(
Handle, // communication handle
ACSC_NONE, // standard variable
"UserArray", // real variable name
0, 99, // first dimension indexes
0,9, // no second dimension
“UserArr.TXT”,// Text file name contained values that must be
//written
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
UserArr.TXT has this structure:
0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ……………
0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ……………
0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ……………
0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ……………
0 1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0 ……………

5.115 acsc_MultiPoint
The function initiates a single-axis multi-point motion.
int acsc_MultiPoint(HANDLE Handle, int Flags, int Axis, double Dwell,
ACSC_WAITBLOCK* Wait)

5.115.1 Parameters

Handle Communication handle.

October 30, 2006 230 Detailed Function Descriptions


C Library Reference Version 5.20 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 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 383.

Dwell Dwell in each point in milliseconds.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.115.2 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.

5.115.3 Remarks
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.

October 30, 2006 231 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.115.4 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: %d\n", 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

October 30, 2006 232 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.116 acsc_MultiPointM
The function initiates a multi-axis multi-point motion.
int acsc_MultiPointM(HANDLE Handle, int Flags, int* Axes, double Dwell,
ACSC_WAITBLOCK* Wait)

5.116.1 Parameters

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 383.

Dwell Dwell in each point in milliseconds.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 233 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.116.2 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.

5.116.3 Remarks
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.

October 30, 2006 234 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.116.4 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: %d\n", 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

5.117 acsc_OpenCommDirect
The function starts up the Simulator and opens communication with the Simulator.
HANDLE acsc_OpenCommDirect()

5.117.1 Parameters
This function has no parameters.

5.117.2 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.

October 30, 2006 235 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

If the function fails, the return value is ACSC_INVALID (-1). Get extended error information
by call acsc_GetLastError.

5.117.3 Remarks
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.

5.117.4 Example

HANDLE Handle = acsc_OpenCommDirect();


if (Handle == ACSC_INVALID)
{
printf("error opening communication: %d\n", acsc_GetLastError());
}

5.118 acsc_OpenCommEthernet
The function opens communication with the controller via Ethernet.
HANDLE acsc_OpenCommEthernet(char* Address, int Port)

5.118.1 Parameters

Address Pointer to a null-terminated character string that contains the network


address of the controller in symbolic or TCP/IP dotted form.

October 30, 2006 236 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Port Service port.


For point-to-point communication, this parameter must be
ACSC_SOCKET_DGRAM_PORT.
For communication via Internet/Intranet, this parameter must be
ACSC_SOCKET_STREAM_PORT.

5.118.2 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). Get extended error information
by call acsc_GetLastError.

5.118.3 Remarks
After a channel is open, any SPiiPlus C function works with the channel irrespective of the
physical nature of the channel.
If the parameter Port is ACSC_SOCKET_DGRAM_PORT, the library opens communication
using the connectionless socket and UDP communication protocol.
If the parameter Port is ACSC_SOCKET_STREAM_PORT, the library opens communication
using the connection-oriented socket and TCP communication protocol.
The controller supports both protocols. The UDP protocol provides faster communication, but
is not reliable when used in a multi-node network.
Use UDP protocol if the host computer has a point-to-point Ethernet connection to the
controller.
Use TCP protocol if the host computer is connected to the controller through the multi-node
Ethernet network.

October 30, 2006 237 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.118.4 Example

HANDLE Handle = OpenCommEthernet(


“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: %d\n", acsc_GetLastError());
}

5.119 acsc_OpenCommPCI
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.
HANDLE acsc_OpenCommPCI(int SlotNumber)

5.119.1 Parameters

SlotNumber Number of the slot of the controller card.


If SlotNumber is ACSC_NONE, the function opens
communication with the first found controller card.

5.119.2 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). Get extended error information
by call acsc_GetLastError.

5.119.3 Remarks
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.

October 30, 2006 238 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.119.4 Example

// open communication with the first found controller card


HANDLE Handle = OpenCommPCI(ACSC_NONE);
if (Handle == ACSC_INVALID)
{
printf("error opening communication: %d\n", acsc_GetLastError());
}

5.120 acsc_OpenCommSerial
The function opens communication with the controller via a serial port.
HANDLE acsc_OpenCommSerial(int Channel, int Rate)

5.120.1 Parameters

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.

5.120.2 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). Get extended error information
by call acsc_GetLastError.

5.120.3 Remarks
After a channel is open, any SPiiPlus C function works with the channel irrespective of the
physical nature of the channel.

October 30, 2006 239 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.120.4 Example

HANDLE Handle = OpenCommSerial(1, // Communication port COM1


115200 // Baud rate 115200
);
if (Handle == ACSC_INVALID)
{
printf("error opening communication: %d\n", acsc_GetLastError());
}

5.121 acsc_OpenHistoryBuffer
The function opens a history buffer.
LP_ACSC_HISTORYBUFFER acsc_OpenHistoryBuffer(HANDLE Handle, int Size)

5.121.1 Parameters

Handle Communication handle

Size Required size of the buffer in bytes

5.121.2 Return Value


The function returns pointer to ACSC_HISTORYBUFFER structure.
If the buffer cannot be allocated, the return value is zero. Get extended error information by call
acsc_GetLastError.

5.121.3 Remarks
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.

October 30, 2006 240 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.121.4 Example

LP_ACSC_HISTORYBUFFER lpHistoryBuf = acsc_OpenHistoryBuffer(


Handle, // communication handle
10000 // size of the buffer
);
if (!lpHistoryBuf)
{
printf("opening history buffer error: %d\n", acsc_GetLastError());
}

5.122 acsc_OpenLogFile
The function opens log file.
int acsc_OpenLogFile(HANDLE Handle, char* FileName)

5.122.1 Parameters

Handle Communication handle

FileName Pointer to the null-terminated string contained name or path of the log
file.

5.122.2 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.

5.122.3 Remarks
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

October 30, 2006 241 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

log file is for debug purposes.

5.122.4 Example

if (!acsc_OpenLogFile(Handle, "acs_comm.log"))
{
printf("opening log file error: %d\n", acsc_GetLastError());
}

5.123 acsc_OpenMessageBuffer
The function opens an unsolicited messages buffer.
LP_ACSC_HISTORYBUFFER acsc_OpenMessageBuffer(HANDLE Handle, int Size)

5.123.1 Parameters

Handle Communication handle

Size Required size of the buffer in bytes

5.123.2 Return Value


The function returns pointer to ACSC_HISTORYBUFFER structure.
If the buffer cannot be allocated, the return value is zero. Get extended error information by call
acsc_GetLastError.

5.123.3 Remarks
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.
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

October 30, 2006 242 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.123.4 Example

LP_ACSC_HISTORYBUFFER lpMessageBuf = acsc_OpenMessageBuffer(


Handle, // communication handle
10000 // size of the buffer
);
if (!lpMessageBuf)
{
printf("opening unsolicited messages buffer error: %d\n",
acsc_GetLastError());
}

5.124 acsc_PegI
The function initiates incremental PEG. Incremental PEG function is defined by first point, last
point and the interval.
int acsc_PegI(HANDLE Handle, int Flags, int Axis, double Width, int FirstPoint, int
Interval, int LastPoint, int TbNumber, double TbPeriod, ACSC_WAITBLOCK* Wait)

5.124.1 Parameters

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 383.

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.

October 30, 2006 243 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

FirstPoint Position where the first pulse is generated.

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 NULL, 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.

5.124.2 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.

5.124.3 Remarks
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.

October 30, 2006 244 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.124.4 Example

// example of incremental PEG initialization


if (!acsc_PegI( Handle, // communication handle
ACSC_AMF_SYNCRONOUS, //synchronous PEG
ACSC_AXIS_X, // axis X
0.01, // 10 microseconds pulse width
1000, // start from 1000
100, // generate pulse every 100 units
10000, // stop generating at 10000

ACSC_NONE, // No time-based pulse generation


ACSC_NONE,
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.125 acsc_PegR
The function initiates random PEG. Random PEG function specifies an array of points where
position-based events should be generated.
int acsc_PegR(HANDLE Handle,int Flags,int Axis,double Width,char*
PointArray,char* StateArray,int TbNumber, double TbPeriod, ACSC_WAITBLOCK*
Wait)

5.125.1 Parameters

Handle Communication handle.

Flags Bit-mapped parameter that can include following flag:


• ACSC_AMF_SYNCHRONOUS: PEG starts synchronously with
the motion sequence.

October 30, 2006 245 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 383.

Width Width of desired pulse in milliseconds.

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 aren’t 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 NULL, 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.

5.125.2 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.

October 30, 2006 246 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.125.3 Remarks
The function initiates random PEG generation (see SPiiPlus ACSPL+ 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.

5.125.4 Example

// example of incremental PEG initialization


if (!acsc_PegR(Handle, // communication handle
0, // Not-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: %d\n", acsc_GetLastError());
}

5.126 acsc_Projection
The function sets a projection matrix for segmented motion.
int acsc_Projection(HANDLE Handle, int* Axes, char* Matrix, ACSC_WAITBLOCK*
Wait)

5.126.1 Parameters

Handle Communication handle.

October 30, 2006 247 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.

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 NULL, 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.

5.126.2 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.

5.126.3 Remarks
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.

October 30, 2006 248 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.126.4 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);

October 30, 2006 249 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.127 acsc_ReadDPRAMInteger
The function reads 32-bit integer from the DPRAM.
acsc_ReadDPRAMInteger(HANDLE Handle, int address,int *Value)

5.127.1 Parameters

Handle Communication handle

Address Address has to be even number from 128 to 508

Value Value that was read from DPRAM

5.127.2 Return Value


The function returns non-zero on success.
If the value cannot be read, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.127.3 Remarks
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.

Note
The function can be used only with the PCI and Simulator
communication channels.

5.127.4 Example

acsc_ReadDPRAMInteger( Handle, // communication handle


0xA0, // DPRAM address
&Value //Value that receives the result
)

October 30, 2006 250 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.128 acsc_ReadDPRAMReal
The function reads 64-bit Real from the DPRAM.
acsc_ReadDPRAMReal(HANDLE Handle, int address, double *Value)

5.128.1 Parameters

Handle Communication handle

Address Address has to be even number from 128 to 508

Value Value that was read from DPRAM

5.128.2 Return Value


The function returns non-zero on success.
If the value cannot be read, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.128.3 Remarks
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.

Note
The function can be used only with the PCI and Simulator
communication channels.

5.128.4 Example

acsc_ReadDPRAMReal( Handle, // communication handle


0xA0, // DPRAM address
&Value //Value that receives the result
)

October 30, 2006 251 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.129 acsc_ReadInteger
The function reads value(s) from integer variable.
int acsc_ReadInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, int* Values, ACSC_WAITBLOCK* Wait)

5.129.1 Parameters

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 NULL, 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.

5.129.2 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.

5.129.3 Remarks
The function reads specified integer variable or array.

October 30, 2006 252 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.
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.

5.129.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 253 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.130 acsc_ReadReal
The function reads value(s) from a real variable.
int acsc_ReadReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2,
int To2, double* Values, ACSC_WAITBLOCK* Wait)

5.130.1 Parameters

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).

From2, To2 Index range (second dimension).

Values Pointer to the buffer that receives requested values.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.130.2 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.

5.130.3 Remarks
The function reads specified real variable or array.

October 30, 2006 254 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.
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.

5.130.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 255 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.131 acsc_Receive
The function receives a message from the controller.
int acsc_Receive(HANDLE Handle, char* Buf, int Count, int* Received,
ACSC_WAITBLOCK* Wait)

5.131.1 Parameters

Handle Communication handle

Buf Buffer that receives a controller response

Count Size of the buffer

Received Number of characters that were actually received

Wait Pointer to ACSC_WAITBLOCK structure.


The function returns immediately irrespective of the value of this
parameter.

5.131.2 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.

5.131.3 Remarks
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
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.

October 30, 2006 256 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.131.4 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 received\n");
}

5.132 acsc_ReleaseComm
The function releases a communication channel.
int acsc_ReleaseComm(HANDLE Handle)

5.132.1 Parameters

Handle Communication handle

5.132.2 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

October 30, 2006 257 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

acsc_GetLastError.

5.132.3 Remarks
The function releases the communication handle captured by acsc_CaptureComm and allows
other threads to communicate through the channel.

5.132.4 Example

if (!acsc_ReleaseComm(Handle))
{
printf("release communication error: %d\n", acsc_GetLastError());
}

5.133 acsc_ResetIndexState
The function resets the specified bit of the index/mark state.
int acsc_ResetIndexState(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)

5.133.1 Parameters

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 383.

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

October 30, 2006 258 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.133.2 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.

5.133.3 Remarks
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.

5.133.4 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: %d\n", acsc_GetLastError());

October 30, 2006 259 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.133.5 acsc_ResetIndexState
The function resets the specified bit of the index/mark state.
int acsc_ResetIndexState(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)

5.133.6 Parameters

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 383.

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
• 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 NULL, 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.

5.133.7 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.

October 30, 2006 260 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.133.8 Remarks
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.

5.133.9 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: %d\n", acsc_GetLastError());
}

5.134 acsc_RunBuffer
The function starts up ACSPL+ program in the specified buffer.
int acsc_RunBuffer(HANDLE Handle, int Buffer, char* Label, ACSC_WAITBLOCK*
Wait)

5.134.1 Parameters

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.

October 30, 2006 261 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.134.2 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.

5.134.3 Remarks
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.
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.

October 30, 2006 262 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.134.4 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: %d\n", acsc_GetLastError());
}

5.135 acsc_Send
The function sends a message to the controller.
int acsc_Send(HANDLE Handle, char* Buf, int Count, ACSC_WAITBLOCK* Wait)

5.135.1 Parameters

Handle Communication handle

Buf Buffer that contains the command to be sent

Count Number of characters in the command

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.135.2 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

October 30, 2006 263 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

acsc_GetLastError.

5.135.3 Remarks
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.

5.135.4 Example

// example of the waiting call of acsc_Send


char* cmd = "enable X\r";
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: %d\n", acsc_GetLastError());
}

5.136 acsc_Segment
The function initiates a multi-axis segmented motion.
int acsc_Segment(HANDLE Handle, int Flags, int* Axes, double* Point,
ACSC_WAITBLOCK* Wait)

5.136.1 Parameters

Handle Communication handle.

October 30, 2006 264 Detailed Function Descriptions


C Library Reference Version 5.20 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_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.

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 383.

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 NULL, 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.

5.136.2 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

October 30, 2006 265 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

acsc_GetLastError.

5.136.3 Remarks
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
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.

October 30, 2006 266 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.136.4 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: %d\n", 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);

5.137 acsc_SetAcceleration
The function defines a value of motion acceleration.

October 30, 2006 267 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_SetAcceleration(HANDLE Handle, int Axis, double Acceleration,


ACSC_WAITBLOCK* Wait)

5.137.1 Parameters

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 383.

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 NULL, 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.

5.137.2 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.

5.137.3 Remarks
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.
The function has no effect on the master-slave motions.

October 30, 2006 268 Detailed Function Descriptions


C Library Reference Version 5.20 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.

5.137.4 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: %d\n", acsc_GetLastError());
}

5.138 acsc_SetAccelerationImm
The function defines a value of motion acceleration. Unlike acsc_SetAcceleration, the
function has immediate effect on any executed and planned motion.
int acsc_SetAccelerationImm(HANDLE Handle, int Axis, double Acceleration,
ACSC_WAITBLOCK* Wait)

5.138.1 Parameters

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 383.

Acceleration The value specifies required motion acceleration.

October 30, 2006 269 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.138.2 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.

5.138.3 Remarks
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.

October 30, 2006 270 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.138.4 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: %d\n", acsc_GetLastError());
}

5.139 acsc_SetAnalogOutput
The function writes the current numerical value to the specified analog outputs.
int acsc_SetAnalogOutput(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK*
Wait)

5.139.1 Parameters

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 NULL, 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.

5.139.2 Return Value


If the function succeeds, the return value is non-zero.

October 30, 2006 271 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

If the function fails, the return value is zero. Get extended error information by cal
lacsc_GetLastError.

5.139.3 Remarks
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.

5.139.4 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: %d\n", acsc_GetLastError());

5.140 acsc_SetCallback
The function installs a user-defined callback function for the specified interrupt condition
int acsc_SetCallback(HANDLE Handle, ACSC_INTR_CALLBACK_FUNC Callback,
int Interrupt)

5.140.1 Parameters

Handle Communication handle.

October 30, 2006 272 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 Types” on Page 388.

5.140.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.140.3 Remarks
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 Interrupts Masks” on Page 390 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.

October 30, 2006 273 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.140.4 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: %d\n", 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;
}

5.141 acsc_SetCallbackExt
The function installs a user-defined callback function for the specified interrupt condition with
user-defined parameter.

October 30, 2006 274 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_SetCallbackExt(HANDLE Handle, ACSC_INTR_CALLBACK_FUNC_EXT


Callback,void* UserParameter,int Interrupt)

5.141.1 Parameters

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 “Callback Interrupts Types” on Page 388

5.141.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.141.3 Remarks
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 Interrupts Masks” on Page 390 for a detailed description of
the parameter Param for each interrupt.
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,

October 30, 2006 275 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.141.4 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: %d\n", 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)
{

October 30, 2006 276 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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;
}

5.142 acsc_SetCallbackPriority
The function sets the priority for all callback threads.
int acsc_SetCallbackPriority(HANDLE Handle, int Priority)

5.142.1 Parameters

Handle Communication handle.

October 30, 2006 277 Detailed Function Descriptions


C Library Reference Version 5.20 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.

5.142.2 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.

5.142.3 Remarks
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 corresponding operating system guides for details.

Note
The function can be used only with the PCI communication channel.

October 30, 2006 278 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.142.4 Example

// the example sets the new priority for all callbacks


if (!acsc_SetCallbackPriority(Handle, THREAD_PRIORITY_ABOVE_NORMAL))
{
printf("set of callback priority error: %d\n", acsc_GetLastError());
}

5.143 acsc_SetCommOptions
The function sets the communication options.
int acsc_SetCommOptions(HANDLE Handle, unsigned int Options)

5.143.1 Parameters

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.

5.143.2 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.

5.143.3 Remarks
The function sets the communication options. To get current communication option, call
acsc_GetCommOptions.

October 30, 2006 279 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.143.4 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);

5.144 acsc_SetConf
The function writes system configuration data.
int acsc_SetConf(HANDLE Handle, int Key, int Index, double Value,
ACSC_WAITBLOCK* Wait)

5.144.1 Parameters

Handle Communication handle.

Key Configuration key, see “Configuration Keys” on Page 391, 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.

October 30, 2006 280 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.144.2 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.

5.144.3 Remarks
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 detailed description of system
configuration see the description of the SetConf function in the SPiiPlus ACSPL+
Programmer’s Guide.

5.144.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 281 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.145 acsc_SetDeceleration
The function defines a value of motion deceleration.
int acsc_SetDeceleration(HANDLE Handle, int Axis, double Deceleration,
ACSC_WAITBLOCK* Wait)

5.145.1 Parameters

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 383.

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 NULL, 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.

5.145.2 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.

5.145.3 Remarks
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.

October 30, 2006 282 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.145.4 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: %d\n", acsc_GetLastError());
}

5.146 acsc_SetDecelerationImm
The function defines a value of motion deceleration. Unlike acsc_SetDeceleration, the
function has immediate effect on any executed and planned motion.
int acsc_SetDecelerationImm(HANDLE Handle, int Axis, double Deceleration,
ACSC_WAITBLOCK* Wait)

5.146.1 Parameters

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 383.

Deceleration The value specifies required motion deceleration.

October 30, 2006 283 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.146.2 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.

5.146.3 Remarks
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.

October 30, 2006 284 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.146.4 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: %d\n", acsc_GetLastError());
}

5.147 acsc_SetExtOutput
The function sets the specified extended output to the specified value.
int acsc_SetExtOutput(HANDLE Handle, int Port, int Bit, int Value,
ACSC_WAITBLOCK* Wait)

5.147.1 Parameters

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 NULL, 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.

October 30, 2006 285 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.147.2 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.

5.147.3 Remarks
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.

5.147.4 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: %d\n", acsc_GetLastError());
}

5.148 acsc_SetExtOutputPort
The function sets the specified extended output port to the specified value.
int acsc_SetExtOutputPort(HANDLE Handle, int Port, int Value,
ACSC_WAITBLOCK* Wait)

October 30, 2006 286 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.148.1 Parameters

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 NULL, 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.

5.148.2 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.

5.148.3 Remarks
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.

October 30, 2006 287 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.148.4 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: %d\n", acsc_GetLastError());
}

5.149 acsc_SetFaultMask
The function sets the mask that enables or disables the examination and processing of controller
faults.
int acsc_SetFaultMask(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)

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.

5.149.1 Parameters

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” on
Page 383.

October 30, 2006 288 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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” on Page 387 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 NULL, 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.

5.149.2 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.

5.149.3 Remarks
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.

October 30, 2006 289 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.149.4 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: %d\n", acsc_GetLastError());
}

5.150 acsc_SetFPosition
The function assigns a current value of feedback position.
int acsc_SetFPosition(HANDLE Handle, int Axis, double FPosition,
ACSC_WAITBLOCK* Wait)

5.150.1 Parameters

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 383.

FPosition The value specifies the current value of feedback position.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 290 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.150.2 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.

5.150.3 Remarks
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.

5.150.4 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: %d\n", acsc_GetLastError());
}

5.151 acsc_SetInterruptMask
The function sets the mask for specified interrupt.
int acsc_SetInterruptMask(HANDLE Handle, int Interrupt, int Mask)

5.151.1 Parameters

Handle Communication handle

October 30, 2006 291 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Interrupt “Callback Interrupts Types” on Page 388

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 Interrupts Masks” on Page 390 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.

5.151.2 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.

5.151.3 Remarks
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.

Note
The function can be used only with the PCI communication channel.

October 30, 2006 292 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.151.4 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: %d\n", acsc_GetLastError());
}

5.152 acsc_SetIterations
The function sets the number of iterations in one transaction.
int acsc_SetIterations(HANDLE Handle, int Iterations)

5.152.1 Parameters

Handle Communication handle

Iterations Number of iterations

5.152.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.152.3 Remarks
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

October 30, 2006 293 Detailed Function Descriptions


C Library Reference Version 5.20 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.

5.152.4 Example

if (!acsc_SetIterations(Handle, 2))
{
printf("number of iterations setting error: %d\n",
acsc_GetLastError());
}

5.153 acsc_SetJerk
The function defines a value of motion jerk.
int acsc_SetJerk(HANDLE Handle, int Axis, double Jerk, ACSC_WAITBLOCK* Wait)

5.153.1 Parameters

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 383.

Jerk The value specifies a required motion jerk. The value will be used in the
subsequent motions except for the master-slave motions.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 294 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.153.2 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.

5.153.3 Remarks
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.

5.153.4 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: %d\n", acsc_GetLastError());
}

5.154 acsc_SetJerkImm
The function defines a value of motion jerk. Unlike acsc_SetJerk, the function has immediate
effect on any executed and planned motion.
int acsc_SetJerkImm(HANDLE Handle, int Axis, double Jerk, ACSC_WAITBLOCK*
Wait)

October 30, 2006 295 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.154.1 Parameters

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 383.

Jerk The value specifies required motion jerk.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.154.2 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.

5.154.3 Remarks
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.

October 30, 2006 296 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.154.4 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: %d\n", acsc_GetLastError());
}

5.155 acsc_SetKillDeceleration
The function defines a value of motion kill deceleration.
int acsc_SetKillDeceleration(HANDLE Handle, int Axis, double KillDeceleration,
ACSC_WAITBLOCK* Wait)

5.155.1 Parameters

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 383.

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 NULL, 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.

October 30, 2006 297 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.155.2 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.

5.155.3 Remarks
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.

5.155.4 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: %d\n", acsc_GetLastError());
}

5.156 acsc_SetKillDecelerationImm
The function defines a value of motion kill deceleration. Unlike acsc_SetKillDeceleration, the
function has an immediate effect on any executed and planned motion.
int acsc_SetKillDecelerationImm(HANDLE Handle, int Axis, double Deceleration,
ACSC_WAITBLOCK* Wait)

October 30, 2006 298 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.156.1 Parameters

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 383.

KillDeceleration The value specifies the required motion deceleration.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.156.2 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.

5.156.3 Remarks
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.

October 30, 2006 299 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.156.4 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: %d\n", acsc_GetLastError());
}

5.157 acsc_SetLogFileOptions
The function sets the log file options.
acsc_SetLogFileOptions(HANDLE Handle,ACSC_LOG_DETALIZATION_LEVEL
Detalization, ACSC_LOG_DATA_PRESENTATION Presentation)

5.157.1 Parameters

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.

October 30, 2006 300 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.157.2 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 calling
acsc_GetLastError.

5.157.3 Remarks
The function configures the log file options. The function may be called before or after the log
file is opened.

5.157.4 Example

//Example of function acsc_SetLogFileOptions


acsc_SetLogFileOptions(Handle,Maximum,Formatted);

5.158 acsc_SetMaster
The function initiates calculating of master value for an axis.
int acsc_SetMaster(HANDLE Handle, int Axis, char* Formula, ACSC_WAITBLOCK*
Wait)

5.158.1 Parameters

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 383.

Formula ASCII string that specifies a rule for calculating master value.

October 30, 2006 301 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.158.2 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.

5.158.3 Remarks
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.
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.

October 30, 2006 302 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.158.4 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: %d\n", acsc_GetLastError());
}

5.159 acsc_SetOutput
The function sets the specified digital output to the specified value.
int acsc_SetOutput(HANDLE Handle, int Port, int Bit, int Value, ACSC_WAITBLOCK*
Wait)

5.159.1 Parameters

Handle Communication handle.

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.

October 30, 2006 303 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.159.2 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.

5.159.3 Remarks
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.

October 30, 2006 304 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.159.4 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: %d\n", acsc_GetLastError());
}

5.160 acsc_SetOutputPort
The function sets the specified digital output port to the specified value.
int acsc_SetOutputPort(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK*
Wait)

5.160.1 Parameters

Handle Communication handle.

Port Number of the output port.

Value The value to be written to the specified output port.

October 30, 2006 305 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.160.2 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.

5.160.3 Remarks
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.

October 30, 2006 306 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.160.4 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: %d\n", acsc_GetLastError());
}

5.161 acsc_SetQueueOverflowTimeout
The function sets the Queue Overflow Timeout.
int acsc_SetQueueOverflowTimeout (HANDLE Handle, int Delay)

5.161.1 Parameters

Handle Communication handle.

Timeout Timeout value in milliseconds

5.161.2 Return Value


If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.

5.161.3 Remarks
The function sets Queue Overflow Timeout value in milliseconds. See also “Non-waiting
Calls” on Page 12.

October 30, 2006 307 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.161.4 Example

if (!acsc_ SetQueueOverflowTimeout(Handle,100))
{
printf("Queue Overflow Timeout setting error: %d\n",
acsc_GetLastError());
}

5.162 acsc_SetResponseMask
The function retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.
int acsc_SetResponseMask(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)

Certain controller default responses provide protection


against potential serious bodily injury and damage to
equipment. Be aware of the implications before disabling
responses to any alarm, limit, or error.

5.162.1 Parameters

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” on
Page 383.

October 30, 2006 308 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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” on Page 387 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.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.162.2 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.

5.162.3 Remarks
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.

October 30, 2006 309 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.162.4 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: %d\n", acsc_GetLastError());
}

5.163 acsc_SetRPosition
The function assigns a current value of reference position.
int acsc_SetRPosition(HANDLE Handle, int Axis, double RPosition,
ACSC_WAITBLOCK* Wait)

5.163.1 Parameters

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 383.

Rposition The value specifies the current value of reference position.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 310 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.163.2 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.

5.163.3 Remarks
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.

5.163.4 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: %d\n", acsc_GetLastError());

5.164 acsc_SetSafetyInputPortInv
The function sets the set of bits that define inversion for the specified safety input port.
int acsc_SetSafetyInputPortInv(HANDLE Handle, int Axis, int Value,
ACSC_WAITBLOCK* Wait)

October 30, 2006 311 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.164.1 Parameters

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 383.

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” on Page 387 for a detailed description of
these constants.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.164.2 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.

5.164.3 Remarks
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.

October 30, 2006 312 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.164.4 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: %d\n", acsc_GetLastError());
}

5.165 acsc_SetServer
The function defines user-mode driver host IP address
int acsc_SetServer(char *IP)

October 30, 2006 313 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.165.1 Parameters

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)

5.165.2 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.

5.165.3 Remarks
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(…)

October 30, 2006 314 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.165.4 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: %d\n", acsc_GetLastError());
}

5.166 acsc_SetServerExt
The function behaves as acsc_SetServer but explicitly specifies the IP port number for a
remore connection, where acsc_SetServer uses only the default port.
int acsc_SetServerExt(char*IP,intPort)

5.166.1 Parameters
IP IP address where to look for server.

Port Port number for connection

5.166.2 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.

October 30, 2006 315 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.166.3 Remarks
This function is used for access over varying IP ports

5.166.4 Example
This doesn’t look like the other examples

acsc_SetServerExt("10.0.0.13",7777)
Handle=acsc_OpenCommPCI(-1)//Will attempt to find active UMD running on host
//"10.0.0.13" and listenning on Port 7777
//And open communication with PCI card at that
host

5.167 acsc_SetServerLoginExt
The function behaves as acsc_SetServerExt and in addition passes login data.
int acsc_SetServerExtLogin(char *IP, int Port, char *Username, char *Password, char
*Domain)

5.167.1 Parameters

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

5.167.2 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.

October 30, 2006 316 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.167.3 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 attempt to login as "Mickey"
//And open communication with PCI card at that
host

5.168 acsc_SetTargetPosition
The function assigns a current value of track position.
int acsc_SetTargetPosition(HANDLE Handle, int Axis, double TargetPosition,
ACSC_WAITBLOCK* Wait)

5.168.1 Parameters

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 383.

TargetPosition The value specifies the current value of track position.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.168.2 Return Value


If the function succeeds, the return value is non-zero.

October 30, 2006 317 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.

5.168.3 Remarks
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.

5.168.4 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: %d\n", acsc_GetLastError());
}

5.169 acsc_SetTimeout
The function sets the communication timeout.
int acsc_SetTimeout(HANDLE Handle, int Timeout)

5.169.1 Parameters

Handle Communication handle

Timeout Maximum waiting time in milliseconds.

October 30, 2006 318 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.169.2 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.

5.169.3 Remarks
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
will return the ACSC_TIMEOUT error.

5.169.4 Example

if (!acsc_SetTimeout(Handle, 5000))
{
printf("timeout set error: %d\n", acsc_GetLastError());
}

5.170 acsc_SetVelocity
The function defines a value of motion velocity.
int acsc_SetVelocity(HANDLE Handle, int Axis, double Velocity, ACSC_WAITBLOCK*
Wait)

5.170.1 Parameters

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 383.

October 30, 2006 319 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 NULL, 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.

5.170.2 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.

5.170.3 Remarks
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 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.

October 30, 2006 320 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.170.4 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: %d\n", acsc_GetLastError());
}

5.171 acsc_SetVelocityImm
The function defines a value of motion velocity. Unlike acsc_SetVelocity, the function has
immediate effect on any executed or planned motion.
int acsc_SetVelocityImm(HANDLE Handle, int Axis, double Velocity,
ACSC_WAITBLOCK* Wait)

5.171.1 Parameters

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 383.

Velocity The value specifies required motion velocity.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 321 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.171.2 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.

5.171.3 Remarks
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.

5.171.4 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: %d\n", acsc_GetLastError());
}

5.172 acsc_Slave
The function initiates a master-slave motion.
int acsc_Slave(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait)

October 30, 2006 322 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.172.1 Parameters

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_POSITIONLOCK: the motion will use position lock.
If the flag is not specified, velocity lock is used (see “Remarks” on
Page 323).

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.172.2 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.

5.172.3 Remarks
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.

October 30, 2006 323 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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

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.

October 30, 2006 324 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.172.4 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: %d\n", acsc_GetLastError());
}

5.173 acsc_SlaveStalled
The function initiates master-slave motion within predefined limits.
int acsc_SlaveStalled(HANDLE Handle, int Flags, int Axis, double Left, double Right,
ACSC_WAITBLOCK* Wait)

5.173.1 Parameters

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 “Remarks” on
Page 326).

October 30, 2006 325 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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 383.

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 NULL, 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.

5.173.2 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.

5.173.3 Remarks
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-

October 30, 2006 326 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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
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.

October 30, 2006 327 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.173.4 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: %d\n", acsc_GetLastError());
}

5.174 acsc_Spline
The function initiates a single-axis spline motion. The motion follows an arbitrary path defined
by a set of points.
int acsc_Spline(HANDLE Handle, int Flags, int Axis, double Period,
ACSC_WAITBLOCK* Wait)

5.174.1 Parameters

Handle Communication handle.

October 30, 2006 328 Detailed Function Descriptions


C Library Reference Version 5.20 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_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 383.

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 NULL, 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.

October 30, 2006 329 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.174.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.174.3 Remarks
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.

October 30, 2006 330 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.174.4 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: %d\n", 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

5.175 acsc_SplineM
The function initiates a multi-axis spline motion. The motion follows an arbitrary path defined
by a set of points.
int acsc_SplineM(HANDLE Handle, int Flags, int* Axes, double Period,
ACSC_WAITBLOCK* Wait)

October 30, 2006 331 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.175.1 Parameters

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_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 383.

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 NULL, 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.

October 30, 2006 332 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.175.2 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.

5.175.3 Remarks
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.

October 30, 2006 333 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.175.4 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

Axes, // axes XY
10, // uniform interval 10 ms
NULL // waiting call
))
{
printf("transaction error: %d\n", 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

5.176 acsc_Split
The function breaks down an axis group created before.

October 30, 2006 334 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

int acsc_Split(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

5.176.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.176.2 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.

5.176.3 Remarks
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
delete the Wait item until a call to the acsc_WaitForAsyncCall function.

October 30, 2006 335 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.176.4 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: %d\n", acsc_GetLastError());
}

5.177 acsc_SplitAll
The function breaks down all axis groups created before.
int acsc_SplitAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)

5.177.1 Parameters

Handle Communication handle.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.177.2 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

October 30, 2006 336 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

acsc_GetLastError.

5.177.3 Remarks
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.

5.177.4 Example

// example of the waiting call of acsc_SplitAll


if (!acsc_SplitAll(Handle, NULL))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.178 acsc_StopBuffer
The function stops the execution of ACSPL+ program in the specified buffer(s).
int acsc_StopBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait)

5.178.1 Parameters

Handle Communication handle.

Buffer Buffer number, from 0 to 9.


Use ACSC_NONE instead of the buffer number, to stop the execution
of all programs in all buffers.

October 30, 2006 337 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.178.2 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.

5.178.3 Remarks
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.

5.178.4 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: %d\n", acsc_GetLastError());
}

October 30, 2006 338 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.179 acsc_StopCollect
The function terminates data collection.
int acsc_StopCollect(HANDLE Handle, ACSC_WAITBLOCK* Wait)

5.179.1 Parameters

Handle Communication handle.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.179.2 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.

5.179.3 Remarks
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.

October 30, 2006 339 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.179.4 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: %d\n", acsc_GetLastError());
}

5.180 acsc_StopPeg
The function stops PEG.
int acsc_StopPeg(HANDLE Handle,int Axis, ACSC_WAITBLOCK* Wait)

5.180.1 Parameters

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 383.

October 30, 2006 340 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.180.2 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.

5.180.3 Remarks
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.

5.180.4 Example

// example of incremental PEG initialization


if (!acsc_StopPeg(Handle, // communication handle
ACSC_AXIS_X, // axis X
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.181 acsc_Stopper
The function provides a smooth transition between two segments of segmented motion.
int acsc_Stopper(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)

October 30, 2006 341 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.181.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.181.2 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.

5.181.3 Remarks
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.
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.

October 30, 2006 342 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.181.4 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);

5.182 acsc_SuspendBuffer
The function suspends the execution of ACSPL+ program in the specified program buffer(s).
int acsc_SuspendBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait)

5.182.1 Parameters

Handle Communication handle.

October 30, 2006 343 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Buffer Buffer number, from 0 to 9.


Use ACSC_NONE instead of the buffer number, to suspend the
execution of all programs in all buffers.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.182.2 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.

5.182.3 Remarks
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.

October 30, 2006 344 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.182.4 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: %d\n", acsc_GetLastError());
}

5.183 acsc_Track
The function initiates a single-axis track motion.
int acsc_Track(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait)

5.183.1 Parameters

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 383.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

October 30, 2006 345 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.183.2 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.

5.183.3 Remarks
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.

5.183.4 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: %d\n", acsc_GetLastError());
}

5.184 acsc_ToPoint
The function initiates a single-axis motion to the specified point.
int acsc_ToPoint(HANDLE Handle, int Flags, int Axis, double Point,
ACSC_WAITBLOCK* Wait)

5.184.1 Parameters

Handle Communication handle.

October 30, 2006 346 Detailed Function Descriptions


C Library Reference Version 5.20 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 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 383.

Point Coordinate of the target point.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.184.2 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.

5.184.3 Remarks
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.

October 30, 2006 347 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.184.4 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: %d\n", acsc_GetLastError());
}

5.185 acsc_ToPointM
The function initiates a multi-axis motion to the specified point.
int acsc_ToPointM(HANDLE Handle, int Flags, int* Axes, double* Point,
ACSC_WAITBLOCK* Wait)

5.185.1 Parameters

Handle Communication handle.

October 30, 2006 348 Detailed Function Descriptions


C Library Reference Version 5.20 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_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 383.

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 NULL, 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.

5.185.2 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.

5.185.3 Remarks
The function initiates a multi-axis point-to-point motion.

October 30, 2006 349 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.185.4 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: %d\n", acsc_GetLastError());
}

5.186 acsc_Transaction
The function executes one transaction with the controller, i.e. it sends a command and receives
a controller response.
int acsc_Transaction (HANDLE Handle, char* OutBuf, int OutCount, char* InBuf, int
InCount, int* Received, ACSC_WAITBLOCK* Wait)

October 30, 2006 350 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Note
Any ASCII command being sent to the controller must end with '\r' (13)
character, otherwise it won't be recognized as valid.

5.186.1 Parameters

Handle Communication handle

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 NULL, 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.

5.186.2 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.

5.186.3 Remarks
The full operation of transaction includes the following steps:
1. Send OutCount characters from OutBuf to the controller.

October 30, 2006 351 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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
rest of the operation. The calling thread can validate if the operation finished and can retrieve
the operation result using the acsc_WaitForAsyncCall function.

October 30, 2006 352 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.186.4 Example

char* cmd = "?SN\r"; // 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: %d\n", 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: %s\n”, buf);
}

October 30, 2006 353 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘\0’;
printf("error: %s\n", buf);
}
}
else
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.187 acsc_UploadBuffer
The function uploads ACSPL+ program from the specified program buffer.
int acsc_UploadBuffer(HANDLE Handle, int Buffer, int Offset, char* Program, int
Count, int* Received, ACSC_WAITBLOCK* Wait)

5.187.1 Parameters

Handle Communication handle

Buffer Number of a program buffer in the controller.

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.

October 30, 2006 354 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.187.2 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.

5.187.3 Remarks
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.
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.

October 30, 2006 355 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.187.4 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: %d\n", acsc_GetLastError());
}

5.188 acsc_WaitCollectEnd
The function waits for the end of data collection.
int acsc_WaitCollectEnd(HANDLE Handle, int Timeout)

5.188.1 Parameters

Handle Communication handle.

Timeout Maximum waiting time in milliseconds.


If Timeout is INFINITE, the function's time-out interval never elapses.

5.188.2 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.

October 30, 2006 356 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.188.3 Remarks
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.

5.188.4 Example

if (!acsc_WaitCollectEnd(Handle, // communication handle


30000 // during 30 sec
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.189 acsc_WaitForAsyncCall
The function waits for completion of asynchronous call and retrieves a data.
int acsc_WaitForAsyncCall(HANDLE Handle, void* Buf, int* Received,
ACSC_WAITBLOCK* Wait, int Timeout)

5.189.1 Parameters

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.

October 30, 2006 357 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.189.2 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. 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.

5.189.3 Remarks
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.

October 30, 2006 358 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.189.4 Example

char* cmd = "?VR\r";// 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: %d\n", 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: %s\n”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘\0’;
printf("error: %s\n", buf);
}
}

October 30, 2006 359 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.190 acsc_WaitInput
The function waits for the specified state of digital input.
int acsc_WaitInput (HANDLE Handle, int Port, int Bit, int State, int Timeout)

5.190.1 Parameters

Handle Communication handle.

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.

5.190.2 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.

5.190.3 Remarks
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.

October 30, 2006 360 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.190.4 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: %d\n", acsc_GetLastError());
}

5.191 acsc_WaitLogicalMotionEnd
The function waits for the logical end of a motion.
int acsc_WaitLogicalMotionEnd (HANDLE Handle, int Axis, int Timeout)

5.191.1 Parameters

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 383.
The axis must be either a single axis not included in any group or a
leading axis of a group.

Timeout Maximum waiting time in milliseconds.


If Timeout is INFINITE, the function's time-out interval never
elapses.

5.191.2 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.

October 30, 2006 361 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.191.3 Remarks
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.

5.191.4 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: %d\n", acsc_GetLastError());
}

5.192 acsc_WaitMotionEnd
The function waits for the end of a motion.
int acsc_WaitMotionEnd (HANDLE Handle, int Axis, int Timeout)

5.192.1 Parameters

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 383.

Timeout Maximum waiting time in milliseconds.


If Timeout is INFINITE, the function's time-out interval never
elapses.

October 30, 2006 362 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.192.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.192.3 Remarks
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.

5.192.4 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: %d\n", acsc_GetLastError());
}

5.193 acsc_WaitMotorEnabled
The function waits for the specified state of the specified motor.
int acsc_WaitMotorEnabled (HANDLE Handle, int Axis, int State, int Timeout)

5.193.1 Parameters

Handle Communication handle.

October 30, 2006 363 Detailed Function Descriptions


C Library Reference Version 5.20 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 383.

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.

5.193.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.193.3 Remarks
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.

5.193.4 Example

if (!acsc_WaitProgramEnd(Handle, // communication handle


ACSC_AXIS_X, // buffer 0
30000 // during 30 sec
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.194 acsc_WaitProgramEnd
The function waits for the program termination in the specified buffer.
int acsc_WaitProgramEnd (HANDLE Handle, int Buffer, int Timeout)

October 30, 2006 364 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.194.1 Parameters

Handle Communication handle.

Buffer Buffer number, from 0 to 9.

Timeout Maximum waiting time in milliseconds.


If Timeout is INFINITE, the function's time-out interval never
elapses.

5.194.2 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.

5.194.3 Remarks
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.

5.194.4 Example

if (!acsc_WaitProgramEnd(Handle, // communication handle


0, // buffer 0
30000 // during 30 sec
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}

5.195 acsc_WaitUserCondition
The function waits for the user-defined condition.
int acsc_WaitUserCondition(HANDLE Handle, ACSC_USER_CONDITION_FUNC
UserCondition, int Timeout)

October 30, 2006 365 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.195.1 Parameters

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.

5.195.2 Return Value


If the function succeeds, the return value is non-zero. If the function fails, the return value is
zero. To get extended error information, call acsc_GetLastError.

5.195.3 Remarks
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.

October 30, 2006 366 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.195.4 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: %d\n", acsc_GetLastError());
}

5.196 acsc_WriteInteger
The function writes value(s) to integer variable.
int acsc_WriteInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, int* Values, ACSC_WAITBLOCK* Wait)

5.196.1 Parameters

Handle Communication handle

NBuf Number of program buffer for local variable or ACSC_NONE for


global and standard variable.

October 30, 2006 367 Detailed Function Descriptions


C Library Reference Version 5.20 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 contained values that must be written.

Wait Pointer to ACSC_WAITBLOCK structure.


If Wait is NULL, 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.

5.196.2 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.

5.196.3 Remarks
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
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

October 30, 2006 368 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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.

5.196.4 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: %d\n", acsc_GetLastError());
}

5.197 acsc_WriteLogFile
The function writes to log file.
int acsc_WriteLogFile(HANDLE Handle, char* Buf, int Count)

5.197.1 Parameters

Handle Communication handle

Buf Pointer to the buffer that contains the string to be written to log file.

October 30, 2006 369 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

Count Number of characters in the buffer

5.197.2 Return Value


If the function succeeds, the return value is non-zero.
If the function fails, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.197.3 Remarks
The function writes data from a buffer to log file. The log file should be previously opened by
the function acsc_OpenLogFile.
The function adds its arguments to the internal UMD binary buffer. In previous C Library
versions, the log file had to be explicitly opened by the function acsc_OpenLogFile, otherwise
the function would return an error. Starting with C Library version 5.0, this is no longer the case.
See, acsc_FlushLogFile.

5.197.4 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: %d\n", acsc_GetLastError());
}

5.198 acsc_WriteReal
The function writes value(s) to the real variable.
int acsc_WriteReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, double* Values, ACSC_WAITBLOCK* Wait)

October 30, 2006 370 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.198.1 Parameters

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).

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 NULL, 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.

5.198.2 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.

5.198.3 Remarks
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

October 30, 2006 371 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

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
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.

5.198.4 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: %d\n", acsc_GetLastError());
}

5.199 acsc_WriteDPRAMInteger
The function writes 32-bit integer to the DPRAM.
acsc_WriteDPRAMInteger(HANDLE Handle, int address,int Value)

October 30, 2006 372 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.199.1 Parameters

Handle Communication handle

Address Address has to be even number from 128 to 508

Value Value to be written

5.199.2 Return Value


The function returns non-zero on success.
If the value cannot be written, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.199.3 Remarks
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.

Note
The function can be used only with the PCI and Simulator
communication channels.

5.199.4 Example

acsc_WriteDPRAMInteger(Handle, // communication handle


0xA0, // DPRAM address
0 //Value to write
)

5.200 acsc_WriteDPRAMReal
The function writes 64-bit Real to the DPRAM.
acsc_WriteDPRAMReal(HANDLE Handle, int address, double Value)

October 30, 2006 373 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

5.200.1 Parameters

Handle Communication handle

Address Address has to be even number from 128 to 508

Value Value to be written

5.200.2 Return Value


The function returns non-zero on success.
If the value cannot be written, the return value is zero. To get extended error information, call
acsc_GetLastError.

5.200.3 Remarks
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.

Note
The function can be used only with the PCI and Simulator
communication channels.

5.200.4 Example

acsc_WriteDPRAMReal(Handle, // communication handle


0xA0, // DPRAM address
0 //Value to write
)

October 30, 2006 374 Detailed Function Descriptions


C Library Reference Version 5.20 Programmer’s Guide

6 List of Error Codes

Note
Any error code greater than 1000 is a controller error defined in the
SPiiPlus ACSPL+ Programmer’s Guide.

Table 40 Error Codes


Format Error Description
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. Upgrde the FW
of the controller.
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).
ACSC_TIMEOUT 130 The controller stopped responding.
This error indicates that during specified time-
out the controller did not respond or response
was invalid.

October 30, 2006 375 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

Table 40 Error Codes


Format Error Description
ACSC_INITFAILURE 132 Communication initialization failure.
This error is returned by one of the
acsc_Open*** functions 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.
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.
ACSC_INVALIDPARAMETERS 139 Function parameters are invalid.
ACSC_CLOSEDHISTORYBUF 140 History buffer is closed.
ACSC_EMPTYNAMEVAR 141 Name of variable must be specified.

October 30, 2006 376 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

Table 40 Error Codes


Format Error Description
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_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_REPLIESSEQUENCEERRO 154 Internal library error: The controller replies
R sequence is invalid.
ACSC_WAITFAILED 155 Internal library error: WaitForSingleObject
function returns error.
ACSC_INITMESSAGEBUFFAILE 157 Internal library error: Error of the unsolicited
D messages buffer initialization.

October 30, 2006 377 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

Table 40 Error Codes


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_CANCELOPERATIONERR 159 Error of the non-waiting call cancellation.
OR
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_TLSERROR 179 Internal library error: Thread local storage
error.

October 30, 2006 378 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

Table 40 Error Codes


Format Error Description
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_DDERROR 191 Problem occurred while activating one of
SPiiPlus device drivers. Returned by
acsc_OpenCommPCI
ACSC_INVALID_DPRAM_ADDR 192 Invalid DPRAM address was specified
Returned by DPRAM access functions, when
attempting to access illegal address
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.

October 30, 2006 379 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

Table 40 Error Codes


Format Error Description
ACSC_HW_PROBLEM 194 Problem in SPiiPlus PCI Hardware was
detected. Returned by acsc_OpenCommPCI
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.

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.
Verify that the files ACSCL.DLL and
ACSCSRV.EXE are of the same version.

October 30, 2006 380 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

Table 40 Error Codes


Format Error Description
ACSC_HW_NO_INT 502 No interrupt
ACSC_HW_ INT_PERIOD 504 Interrupt period
ACSC_HW_NO_INT_NOTIF 506 No interrupt notification event
ACSC_HW_SPiiFAILURE 508 SPii failure

October 30, 2006 381 List of Error Codes


C Library Reference Version 5.20 Programmer’s Guide

7 Constants

7.1 General
Table 41 General Constants
Constant Value Description
ACSC_INVALID -1 Invalid communication handle
ACSC_NONE -1 Placeholder for redundant values,
like the second index in a one-
dimensional array
ACSC_IGNORE 0xFFFFFFFF Used for non-waiting calls with
neglect of operation results
ACSC_INT_TYPE 1 Integer type of the variable
ACSC_REAL_TYPE 2 Real type of the variable
ACSC_MAX_LINE 100000 Maximum number of lines in the
program buffer
ACSC_COUNTERCLOCKWISE 1 Counterclockwise rotation
ACSC_CLOCKWISE -1 Clockwise rotation
ACSC_POSITIVE_DIRECTION 1 A move in positive direction
ACSC_NEGATIVE_DIRECTION -1 A move in negative direction

7.2 General Communication Options


Table 42 General Communication Options
Constant Value Description
ACSC-COMM-USECHECKSUM 0x000000001 The communication mode when
each command is sent to the
controller with checksum and the
controller also responds with
checksum
ASCS- 0x000000002 When a hardware error is detected in
COMM_AUTORECOVER_HW the communication channel and this
_ERROR bit is set, the library automatically
repeats the transaction without
counting iterations. By default, this
flag is not set.

October 30, 2006 382 Constants


C Library Reference Version 5.20 Programmer’s Guide

7.3 Ethernet Communication Options


Table 43 Ethernet Communication Options
Constant Value Description
ACSC_SOCKET_DGRAM_PORT 700 The library opens Ethernet
communication using the
connection-less socket and UDP
communication protocol.
ACSC_SOCKET_STREAM_PORT 701 The library opens Ethernet
communication using the
connection-oriented socket and TCP
communication protocol.

7.4 Axis Definitions


Table 44 Axis Definitions
Constant Value Description
ACSC_AXIS_X 0 Axis X
ACSC_AXIS_Y 1 Axis Y
ACSC_AXIS_Z 2 Axis Z
ACSC_AXIS_T 3 Axis T
ACSC_AXIS_A 4 Axis A
ACSC_AXIS_B 5 Axis B
ACSC_AXIS_C 6 Axis C
ACSC_AXIS_D 7 Axis D

October 30, 2006 383 Constants


C Library Reference Version 5.20 Programmer’s Guide

7.5 Motion Flags


Table 45 Motion Flags (page 1 of 2)
Constant Value Description
ACSC_AMF_WAIT 0x00000001 The controller plans the motion but
doesn’t start it until the acsc_Go
function is executed.
ACSC_AMF_RELATIVE 0x00000002 The value of the point coordinate is
relative to the end point coordinate
of the previous motion.
ACSC_AMF_VELOCITY 0x00000004 The motion uses the specified
velocity instead of the default
velocity.
ACSC_AMF_ENDVELOCITY 0x00000008 The motion comes to the end point
with the specified velocity
ACSC_AMF_POSITIONLOCK 0x00000010 The slaved motion uses position
lock. If the flag is not specified,
velocity lock is used.
ACSC_AMF_VELOCITYLOCK 0x00000020 The slaved motion uses velocity
lock.
ACSC_AMF_CYCLIC 0x00000100 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.
ACSC_AMF_VARTIME 0x00000200 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.
ACSC_AMF_CUBIC 0x00000400 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). [In the present version
third-order spline is not supported].
ACSC_AMF_EXTRAPOLATED 0x00001000 Segmented slaved motion: if a
master value travels beyond the
specified path, the last or the first
segment is extrapolated.

October 30, 2006 384 Constants


C Library Reference Version 5.20 Programmer’s Guide

Table 45 Motion Flags (page 2 of 2)


Constant Value Description
ACSC_AMF_STALLED 0x00002000 Segmented slaved motion: if a
master value travels beyond the
specified path, the motion stalls at
the last or first point.
ACSC_AMF_MAXIMUM 0x00004000 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.
ACSC_AMF_SYNCHRONOUS 0x00008000 Position Event Generation (PEG):
Start PEG synchronously with the
motion sequence.

7.6 Data Collection Flags


Table 46 Data Collection Flags
Constant Value Description
ACSC_DCF_TEMPORAL 0x00000001 Temporal data collection. The
sampling period is calculated
automatically according to the
collection time.
ACSC_DCF_CYCLIC 0x00000002 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.

7.7 Motor State Flags


Table 47 Data Collection Flags
Constant Value Description
ACSC_MST_ENABLE 0x00000001 Motor is enabled
ACSC_MST_INPOS 0x00000010 Motor has reached a target position.
ACSC_MST_MOVE 0x00000020 Motor is moving.
ACSC_MST_ACC 0x00000040 Motor is accelerating.

October 30, 2006 385 Constants


C Library Reference Version 5.20 Programmer’s Guide

7.8 Axis State Flags


Table 48 Axis State Flags
Constant Value Description
ACSC_AST_LEAD 0x00000001 Axis is leading in a group.
ACSC_AST_DC 0x00000002 Axis data collection is in progress.
ACSC_AST_PEG 0x00000004 PEG for the specified axis is in
progress.
ACSC_AST_MOVE 0x00000020 Axis is moving.
ACSC_AST_ACC 0x00000040 Axis is accelerating.
ACSC_AST_SEGMENT 0x00000080 Construction of segmented motion
for the specified axis is in progress.
ACSC_AST_VELLOCK 0x00000100 Slave motion for the specified axis is
synchronized to master in velocity
lock mode.
ACSC_AST_POSLOCK 0x00000200 Slave motion for the specified axis is
synchronized to master in position
lock mode.

7.9 Index and Mark State Flags


Table 49 Index and Mark State Flags
Constant Value Description
ACSC_IST_IND 0x00000001 Primary encoder index of the
specified axis is latched.
ACSC_IST_IND2 0x00000002 Secondary encoder index of the
specified axis is latched.
ACSC_IST_MARK 0x00000004 MARK1 signal has been generated
and position of the specified axis was
latched.
ACSC_IST_MARK2 0x00000008 MARK2 signal has been generated
and position of the specified axis was
latched.

October 30, 2006 386 Constants


C Library Reference Version 5.20 Programmer’s Guide

7.10 Program State Flags


Table 50 Program State Flags
Constant Value Description
ACSC_PST_COMPILED 0x00000001 Program in the specified buffer is
compiled.
ACSC_PST_RUN 0x00000002 Program in the specified buffer is
running.
ACSC_PST_SUSPEND 0x00000004 Program in the specified buffer is
suspended after the step execution or
due to breakpoint in debug mode.
ACSC_PST_DEBUG 0x00000020 Program in the specified buffer is
executed in debug mode, i.e.
breakpoints are active.
ACSC_PST_AUTO 0x00000080 Auto routine in the specified buffer is
running.

7.11 Safety Control Masks


Table 51 Safety Control Masks (page 1 of 2)
Constant Value Description Motor/System Fault
ACSC_SAFETY_RL 0x00000001 Right Limit Motor fault
ACSC_SAFETY_LL 0x00000002 Left Limit Motor fault
ACSC_SAFETY_RL2 0x00000004 Preliminary Right Motor fault
Limit
ACSC_SAFETY_LL2 0x00000008 Preliminary Left Motor fault
Limit
ACSC_SAFETY_HOT 0x00000010 Motor Overheat Motor fault
ACSC_SAFETY_SRL 0x00000020 Software Right Limit Motor fault
ACSC_SAFETY_SLL 0x00000040 Software Left Limit Motor fault
ACSC_SAFETY_ENCNC 0x00000080 Primary Encoder Not Motor fault
Connected
ACSC_SAFETY_ENC2NC 0x00000100 Secondary Encoder Motor fault
Not Connected
ACSC_SAFETY_DRIVE 0x00000200 Driver Alarm Motor fault

October 30, 2006 387 Constants


C Library Reference Version 5.20 Programmer’s Guide

Table 51 Safety Control Masks (page 2 of 2)


Constant Value Description Motor/System Fault
ACSC_SAFETY_ENC 0x00000400 Primary Encoder Motor fault
Error
ACSC_SAFETY_ENC2 0x00000800 Secondary Encoder Motor fault
Error
ACSC_SAFETY_PE 0x00001000 Position Error Motor fault
ACSC_SAFETY_CPE 0x00002000 Critical Position Motor fault
Error
ACSC_SAFETY_VL 0x00004000 Velocity Limit Motor fault
ACSC_SAFETY_AL 0x00008000 Acceleration Limit Motor fault
ACSC_SAFETY_CL 0x00010000 Current Limit Motor fault
ACSC_SAFETY_SP 0x00020000 Servo Processor Motor fault
Alarm
ACSC_SAFETY_PROG 0x02000000 Program Error System fault
ACSC_SAFETY_MEM 0x04000000 Memory Overuse System fault
ACSC_SAFETY_TIME 0x08000000 Time Overuse System fault
ACSC_SAFETY_ES 0x10000000 Emergency Stop System fault
ACSC_SAFETY_INT 0x20000000 Servo Interrupt System fault
ACSC_SAFETY_INTGR 0x40000000 Integrity Violation System fault

Note
See the SPiiPlus ACSPL+ Programmer’s Guide for detailed
explanations of faults.

7.12 Callback Interrupts Types


Table 52 describes Hardware Callback Interrupts, and Table 53 describes Software Callback
Interrupts.

Table 52 Callback Interrupts Types - Hardware (page 1 of 2)


Constant Value Description
ACSC_INTR_PEG 3 Position event signal (PEG) has been
generated.
ACSC_INTR_MARK1 7 MARK1 signal has been generated.

October 30, 2006 388 Constants


C Library Reference Version 5.20 Programmer’s Guide

Table 52 Callback Interrupts Types - Hardware (page 2 of 2)


Constant Value Description
ACSC_INTR_MARK2 8 MARK2 signal has been generated.
ACSC_INTR_EMERGENCY 15 EMERGENCY STOP signal has
been generated.

Table 53 Callback Interrupts Types - Software


Constant Value Description
ACSC_INTR_PHYSICAL_MOTION_ 16 Physical motion has finished.
END
ACSC_INTR_LOGICAL_MOTION_E 17 Logical motion has finished.
ND
ACSC_INTR_MOTION_FAILURE 18 Motion has been interrupted due to a
fault.
ACSC_INTR_MOTOR_FAILURE 19 Motor has been disabled due to a
fault.
ACSC_INTR_PROGRAM_END 20 ACSPL+ program has finished.
ACSC_INTR_COMMAND 21 A line of ACSPL+ commands has
been executed in a dynamic buffer.
ACSC_INTR_ACSPL_PROGRAM 22 ACSPL+ program has generated the
interrupt by INTERRUPT
command.
ACSC_INTR_INPUT 23 Digital input has changed from 0 to
1.
ACSC_INTR_MOTION_START 24 Motion Starts
ACSC_INTR_MOTION_PHASE_CH 25 Motion Profile Phase changes
ANGE
ACSC_INTR_TRIGGER 26 AST.#TRIGGER bit goes high
ACSC_INTR_MESSAGE 31 Communication interrupt (the
controller raises this interrupt after
sending a complete message to the
host)

October 30, 2006 389 Constants


C Library Reference Version 5.20 Programmer’s Guide

7.13 Callback Interrupts Masks


Table 54 Callback Interrupts Masks
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
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

October 30, 2006 390 Constants


C Library Reference Version 5.20 Programmer’s Guide

7.14 Configuration Keys


Table 55 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.

October 30, 2006 391 Constants


C Library Reference Version 5.20 Programmer’s Guide

8 Structures

8.1 ACSC_WAITBLOCK
The structure is used for non-waiting calls of the SPiiPlus C functions.
struct ACSC_WAITBLOCK { HANDLE Event; int Ret; };

8.1.1 Members

Table 56 Structure Members


Type Name Description
HANDLE Event Not Used
Int Ref The completion of a task

8.1.2 Remarks
To initiate 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.
The error codes stored in Ret are the same that the acsc_GetLastError function returns.

8.2 ACSC_PCI_SLOT
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.
struct ACSC_PCI_SLOT { unsigned int BusNumber; unsigned int SlotNumber; unsigned
int Function; };

October 30, 2006 392 Structures


C Library Reference Version 5.20 Programmer’s Guide

8.2.1 Members

Table 57 ACSC PCI Slot Members


Type Name Description
unsigned int BusNumber Bus number
unsigned int SlotNumber Slot number of the controller card
unsigned int Function PCI function of the controller card

8.2.2 Remarks
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.

8.3 ACSC_HISTORYBUFFER
The structure defines a state of the history and message buffers. This structure is used by the
acsc_OpenHistoryBuffer and acsc_OpenMessageBuffer functions.
struct ACSC_HISTORYBUFFER { int Max; int Cur; int Ring; char* Buf};

8.3.1 Members
Table 58 ACSC History Buffer Members
Type Name Description
int Max Buffer size
int Cur Number of bytes currently stored in the buffer
int Ring Circular index in the buffer
char Buf Pointer to the buffer

8.3.2 Remarks
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

October 30, 2006 393 Structures


C Library Reference Version 5.20 Programmer’s Guide

controller. For this reason the contents of the buffer and structure members can change
asynchronously to the user thread.

October 30, 2006 394 Structures


C Library Reference Version 5.20 Programmer’s Guide

9 Enums

9.1 ACSC_LOG_DETALIZATION_LEVEL
This enum is used for setting log file parameters in function acsc_SetLogFileOptions.
typedef enum ACSC_LOG_DETALIZATION_LEVEL{Minimum,Medium,Maximum};

9.1.1 Members
Table 59 ACSC Log Detalization Level Members
Type Name Description
int Minimum Value 0: Minumum information
int Medium Value 1: Medium information
int Maximum Value 2: Maximum information

9.2 ACSC_LOG_DATA_PRESENTATION
This enum is used for setting log file parameters in function acsc_SetLogFileOptions.
typedef enum ACSC_LOG_DATA_PRESENTATION {Compact,Formatted,Full};

9.2.1 Members

Table 60 ACSC Log Detalization Level Members


Type Name Description
int 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].
int Formatted Value 1: All the binary data will be logged. Non-printing
characters will be represented in [Hex ASCII code].
int Full Value 2: All the binary data will be logged as is.

Version 5.20, October 30, 2006 395 Enums


C Library Reference Version 5.20 Programmer’s Guide

10 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++® 5 and Visual C++ 6 can be found.

10.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.

10.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 Files\ACS Electronics\SB1218 Tools\ACSC\acsc.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[])
{

October 30, 2006 396 Sample Programs


C Library Reference Version 5.20 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 \r\n\
St: \r\n \
ptp X, 4000 \r\n\
ptp X, 0 \r\n \
goto St \r\n \
stop \r\n ";
printf ("ACS-Tech80 Ltd. Copyright (C) 2000. All Rights \
Reserved.\n");
printf ("Application executes reciprocated point-to-point motion\n");
/*****************************************************************/
// Open communication with simulator
printf ("Application opens communication with the simulator, \
downloads\n");
printf ("program to controller's and executes it using SPiiPlus C
Library \
functions\n\n");
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, downloads\n");
printf ("program to the controller and executes it using SPiiPlus C \
Library functions\n\n");
printf ("Wait for opening of communication with the \
controller...\n");

October 30, 2006 397 Sample Programs


C Library Reference Version 5.20 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, downloads\n");
printf ("program to the controller and executes it using SPiiPlus C \
Library functions\n\n");
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 and\n");
printf ("sends some commands to the controller using SPiiPlus C Library
\
functions\n\n");
printf ("Wait for opening of communication with the \

October 30, 2006 398 Sample Programs


C Library Reference Version 5.20 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 downloaded\n");

// Execute the program in the buffer 0


if (!acsc_RunBuffer(hComm, 0, NULL, NULL))
{
ErrorsHandler("run program error.\n", TRUE);
return -1;
}

October 30, 2006 399 Sample Programs


C Library Reference Version 5.20 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 ("%f\r", 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;
}

10.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 Files\ACS Electronics\SB1218 Tools\ACSC\acsc.h"
HANDLE hComm; // communication handle

October 30, 2006 400 Sample Programs


C Library Reference Version 5.20 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 motion\n");
/*****************************************************************/
// Open communication with the simulator
printf ("Application opens communication with the simulator and\n");
printf ("sends some commands to the simulator using SPiiPlus C Library \
functions\n\n");
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 and\n");
printf ("sends some commands to the controller using SPiiPlus C Library
\
functions\n\n");
printf ("Wait for opening of communication with the \
controller...\n");

October 30, 2006 401 Sample Programs


C Library Reference Version 5.20 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 the controller via Ethernet
printf ("Application opens communication with the controller via \
ethernet and\n");
printf ("sends some commands to the controller using SPiiPlus C Library
\
functions\n\n");
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 and\n");
printf ("sends some commands to the controller using SPiiPlus C Library
\
functions\n\n");

October 30, 2006 402 Sample Programs


C Library Reference Version 5.20 Programmer’s Guide

printf ("Wait for opening of communication with the \


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();
// Enable the motor X
if (!acsc_Enable(hComm, ACSC_AXIS_X, NULL))
{
ErrorsHandler("transaction error.\n", TRUE);
return -1;
}
printf ("Motor enabled\n");

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");

October 30, 2006 403 Sample Programs


C Library Reference Version 5.20 Programmer’s Guide

// Check if both of motions finished


do
{
if (acsc_GetFPosition(hComm, ACSC_AXIS_X, &FPOS,
NULL))
{
printf ("%f\r", 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;
}

10.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.

October 30, 2006 404 Sample Programs

You might also like