FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual - page 22
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• A substring of src is returned by the function.
• The length of substring is the number of characters, specified by len , that starts at the indexed
position specified by strt .
• strt must be positive. Otherwise, the program is aborted with an error. If strt is greater than the
length of src , then an empty string is returned.
• len must be positive. Otherwise, the program is aborted with an error. If len is greater than the
declared length of the return STRING, then the returned STRING is truncated to fit.
Example: Refer to the following sections for detailed program examples:
Section B.2 , "Copying Path Variables" (CPY_PTH.KL)
Section B.7 , "Listing Files and Programs and Manipulating Strings" (LIST_EX.KL)
Section B.9 , "Using the File and Device Built-ins" (FILE_EX.KL)
A.21
- T - KAREL LANGUAGE DESCRIPTION
A.21.1
TAN Built-In Function
Purpose: Returns a REAL value that is the tangent of the specified REAL argument
Syntax : TAN(angle)
Function Return Type :REAL
Input/Output Parameters:
[in] angle : REAL
%ENVIRONMENT Group :SYSTEM
Details:
• The value of angle must be in the range of ± 18000 degrees. Otherwise, the program will be
aborted with an error.
Example: The following example uses the TAN Built-In function to specify the tangent of the
variable angle . The tangent should be equal to the SIN( angle ) divided by COS( angle ).
TAN Built-In Function
WRITE (’enter an angle:’)
READ (angle,CR)
ratio = SIN(angle)/COS(angle)
A-336
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
IF ratio = TAN(angle) THEN
WRITE (’ratio is correct’,CR)
ENDIF
A.21.2
%TIMESLICE Translator Directive
Purpose: Supports round-robin type time slicing for tasks with the same priority
Syntax : %TIMESLICE = n
Details:
• n specifies task execution time in msec for one slice. The default value is 256 msec.
• The timeslice value must be greater than 0.
• This value is the maximum duration for executing the task continuously if there are other tasks
with the same priority that are ready to run.
• This function is effective only when more than one KAREL task with the same priority is
executing at the same time.
• The timeslice duration can be set during task execution by the SET_TSK_ATTR Built-In routine.
A.21.3
%TPMOTION Translator Directive
Purpose: Specifies that task motion is enabled when the teach pendant is on
Syntax : %TPMOTION
Details:
• This attribute can be set during task execution by the SET_TSK_ATTR Built-In routine.
A.21.4
TRANSLATE Built-In Procedure
Purpose: Translates a KAREL source file (.KL file type) into p-code (.PC file type), which can be
loaded into memory and executed.
Syntax : TRANSLATE(file_spec, listing_sw, status)
Input/Output Parameters:
[in] file_spec : STRING
A-337
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] listing_sw : BOOLEAN
[out] status : INTEGER
%ENVIRONMENT Group :trans
Details:
•
file_spec specifies the device, name and type of the file to translate. If no device is specified, the
default device will be used. The type, if specified, is ignored and .KL is used instead.
•
The p-code file will be created on the default device. The default device should be set to the
ram disk.
•
listing_sw specifies whether a .LS file should be created. The .LS file contains a listing of
the source lines and any errors which may have occurred. The .LS file will be created on the
default device.
•
The KAREL program will wait while the TRANSLATE Built-In executes. If the KAREL
program is paused, translation will continue until completed. If the KAREL program is aborted,
translation will also be aborted and the .PC file will not be created.
•
If the KAREL program must continue to execute during translation, use the KCL_NO_WAIT
Built-In instead.
•
status explains the status of the attempted operation. If the number 0 is returned, the translation
was successful. If not, an error occurred. Some of the status codes are shown below:
0 Translation was successful
268 Translator option is not installed
35084 File cannot be opened or created.KL file cannot be found or default device is not the
RAM disk
-1 Translation was not successful (Please see .LS file for details)
Example: The following example program will create, translate, load, and run another program
called hello.
TRANSLATE Built-In Procedure
OPEN FILE util_file (’RW’, ’hello.kl’)
WRITE util_file (’PROGRAM hello’, CR)
WRITE util_file (’%NOLOCKGROUP’, CR)
WRITE util_file (’BEGIN’, CR)
WRITE util_file (’ WRITE (’’hello world’’, CR)’, CR)
WRITE util_file (’END hello’, CR)
CLOSE FILE util_file
TRANSLATE(’hello’, TRUE, status)
IF status = 0 THEN
A-338
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
LOAD(’hello.pc’, 0, status)
ENDIF
IF status = 0 THEN
CALL_PROG(’hello’, prog_index)
ENDIF
A.21.5
TRUNC Built-In Function
Purpose: Converts the specified REAL argument to an INTEGER value by removing the fractional
part of the REAL argument
Syntax : TRUNC(x)
Function Return Type :INTEGER
Input/Output Parameters:
[in] x : REAL
%ENVIRONMENT Group :SYStem
Details:
• The returned value is the value of x after any fractional part has been removed. For example, if x
= 2.3, the .3 is removed and a value of 2 is returned.
• x must be in the range of -2147483648 to +2147483583. Otherwise, the program is aborted
with an error.
• ROUND and TRUNC can both be used to convert a REAL expression to an INTEGER expression.
See Also: ROUND Built-In Function
Example: The following example uses the TRUNC Built-In to determine the actual INTEGER
value of miles divided by hours to get mph.
TRUNC Built-In Function
WRITE (’enter miles driven, hours used: ’)
READ (miles,hours,CR)
mph = TRUNC(miles/hours)
WRITE (’miles per hour=’,mph::5)
A-339
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.22
- U - KAREL LANGUAGE DESCRIPTION
A.22.1
UNHOLD Action
Purpose: Releases a HOLD of motion
Syntax : UNHOLD <GROUP [n{,n}]>
Details:
• Any motion that was in progress when the last HOLD was executed is resumed.
• If motions are not held, the action has no effect.
• Held motions are canceled if a RELEASE statement is executed.
• If the group clause is not present, all groups or which the task has control (when the condition is
defined) will be resumed.
• Motion cannot be stopped for a different task.
Example: The following example shows a global condition handler that issues an UNHOLD action to
resume robot motion is when TPIN[1] is pressed.
UNHOLD Action
CONDITION[1]:
WHEN TPIN[1]+ DO
UNHOLD
ENDCONDITION
A.22.2
UNHOLD Statement
Purpose: Releases a HOLD of motion
Syntax : UNHOLD <GROUP [n{,n}]>
Details:
• Any motion that was in progress when the last HOLD was executed is resumed.
• If motions are not held, the statement has no effect.
• Held motions are canceled if a RELEASE statement is executed.
• If the group clause is not present, all groups or which the task has control (when the condition is
defined) will be resumed.
A-340
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• Motion cannot be stopped for a different task.
See Also: Appendix E , ‘‘Syntax Diagrams,’’ for more syntax information
Example: The following example initiates a move to PR[1] and HOLDs the motion. If DIN[1] is
ON, UNHOLD allows the program to resume motion.
UNHOLD Statement
move_to_pr1 —— Call TP program to move to PR[1]
HOLD
IF DIN[1] THEN
UNHOLD
ENDIF
A.22.3
UNINIT Built-In Function
Purpose: Returns a BOOLEAN value indicating whether or not the specified argument is uninitialized
Syntax : UNINIT(variable)
Function Return Type :BOOLEAN
Input/Output Parameters :
[in] variable :any KAREL variable
%ENVIRONMENT Group :SYSTEM
Details:
• A value of TRUE is returned if variable is uninitialized. Otherwise, FALSE is returned.
• variable can be of any data type except an unsubscripted ARRAY, PATH, or structure.
Example: Refer to Section B.12 , "Displaying a List from a Dictionary File" (DCLST_EX.KL) for a
detailed program example.
A.22.4
%UNINITVARS Translator Directive
Purpose: This directive specifies that all variables are by default uninitialized.
Syntax : %UNINITVARS
A-341
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.22.5
UNLOCK_GROUP Built-In Procedure
Purpose: Unlocks motion control for the specified group of axes
Syntax : UNLOCK_GROUP(group_mask, status)
Input/Output Parameters:
[in] group_mask :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :MULTI
Details:
• group_mask specifies the group of axes to unlock for the running task. The group numbers must
be in the range of 1 to the total number of groups defined on the controller.
Table
A-23.
Group_mask Settings
GROUP
DECIMAL
BIT
Group 1
1
1
Group 2
2
2
Group 3
4
3
To specify multiple groups select the decimal values, shown in Table A-23 , which correspond to
the desired groups. Then connect them together using the OR operator. For example to specify
groups 1, 3, enter "1 OR 4".
• Unlocking a group indicates that the task is done with the motion group.
• When a task completes execution (or is aborted), all motion groups that are locked by the
program will be unlocked automatically.
• If motion is executing or pending when the UNLOCK_GROUP Built-In is called, then status
is set to 17039, "Executing motion exists."
• If motion is stopped when the UNLOCK_GROUP Built-In is called, then status is set to 17040,
"Stopped motion exists."
• If a motion statement is encountered in a program that has the %NOLOCKGROUP Directive, the
task will attempt to get motion control for all the required groups if it does not already have it.
The task will pause if it cannot get motion control.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
A-342
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
See Also: LOCK_GROUP Built-In Procedure, Chapter 15 MULTI-TASKING , for more information
and examples.
Example: The following example unlocks groups 1, 2, and 3, and then locks group 3.
UNLOCK_GROUP Built-In Procedure
PROGRAM lock_grp_ex
%ENVIRONMENT MOTN
%ENVIRONMENT MULTI
VAR
status: INTEGER
BEGIN
REPEAT
-- Unlock groups 1, 2, and 3
UNLOCK_GROUP(1 OR 2 OR 4, status)
IF status = 17040 THEN
CNCL_STP_MTN
-- or RESUME
ENDIF
DELAY 500
UNTIL status = 0
-- Lock only group 3
LOCK_GROUP(4, status)
END lock_grp_ex
A.22.6
UNPAUSE Action
Purpose: Resumes program execution long enough for a routine action to be executed
Syntax : UNPAUSE
Details:
• If a routine is called as an action, but program execution is paused, execution is resumed only for
the duration of the routine and then is paused again.
• If more than one routine is called, all of the routines will be executed before execution is
paused again.
• The resume and pause caused by UNPAUSE do not satisfy any RESUME and PAUSE conditions.
See Also: RESUME, PAUSE Actions
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A-343
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.22.7
UNPOS Built-In Procedure
Purpose: Sets the specified REAL variables to the location (x,y,z) and orientation (w,p,r) components
of the specified XYZWPR variable and sets the specified CONFIG variable to the configuration
component of the XYZWPR
Syntax : UNPOS(posn, x, y, z, w, p, r, c)
Input/Output Parameters:
[in] posn :XYZWPR
[out] x, y, z :REAL
[out] w, p, r :REAL
[out] c :CONFIG
%ENVIRONMENT Group :SYSTEM
Details:
• x, y, z, w, p , and r arguments are set to the x, y, and z location coordinates and yaw, pitch,
and roll orientation angles of posn .
• c returns the configuration of posn .
Example: The following example uses the UNPOS Built-In to add 100 to the x location argument.
UNPOS Built-In Procedure
UNPOS (CURPOS,x,y,z,w,p,r,config)
next_pos = POS (x+100,y,z,w,p,r,config)
SET_POS_REG(1, next_pos, status) —— Put next_pos in PR[1]
move_to_pr1 —— Call TP program to move to PR[1]
A.22.8
USING ... ENDUSING Statement
Purpose: Defines a range of executable statements in which fields of a variable of a STRUCTURE
type can be accessed without repeating the name of the variable.
Syntax : USING struct_var{,struct_var} DO
{statement} ENDUSING
where:
A-344
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
struct_var : a variable of STRUCTURE type
statement : an executable KAREL statement
Details:
• In the executable statement, if the same name is both a field name and a variable name, the
field name is used.
• If the same field name appears in more than one variable, the right-most variable in the USING
statement is used.
• When the translator sees any field, it searches the structure type variables listed in the USING
statement from right to left.
Example: Refer to Section B.2 , "Copying Path Variables" (CPY_PTH.KL), for a detailed program
example.
A.23
- V - KAREL LANGUAGE DESCRIPTION
A.23.1
V_CAM_CALIB iRVision Built-In Procedure
Purpose: Finds the calibration grid for either a single plane or multiple plane calibration.
Syntax:V_CAM_CALIB (cal_name, func_code, status)
[in] cal_name : STRING
[in] func_code : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group: CVIS
Details:
• cal_name is the name of the calibration setup file created in setup mode.
• func_code is the plane number to find. One (1) for first plane or single plane calibration and two
(2) for second plane in multiplane calibration. See Table A-24 .
A-345
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Table A-24. Function Code Values
Calibration Type
Function Code
Grid Pattern Calibration
Specify the index of the calibration plane: 1 or 2.
3DL Calibration
Specify the index of the calibration plane: 1 or 2.
Visual Tracking Calibration
Not supported
Simple 2D Calibration
Not supported
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• The calibration file must already exist and be set up. This built-in will recalibrate an already
calibrated file.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
Example:
------------------------------------------------------------------
PROGRAM cal
------------------------------------------------------------------
%NOLOCKGROUP
%ENVIRONMENT CVIS
%ALPHABETIZE
%COMMENT = ’IRVision CAL Built-in’
%NOPAUSE = ERROR + COMMAND + TPENABLE
VAR
STATUS
: INTEGER
----------------------------------------
BEGIN
-- Find calibration plane one
V_CAM_CALIB(’CAL1’,1,STATUS)
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_CAM_CALIB failed - ERROR ’, STATUS, CR)
ABORT
ENDIF
END cal
A-346
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
A.23.2
V_GET_OFFSET iRVision Built-In Procedure
Purpose: Gets a vision offset from a vision process and stores it in a specified vision register.
Syntax:V_GET_OFFSET(vp_name, register_no, status)
[in] vp_name: STRING
[in] register_no: INTEGER
[out] status: INTEGER
% ENVIRONMENT GROUP: CVIS
Details:
• vp_name is the name of the vision process created in setup mode
• register_no is the register number in which the offset and vision data is placed.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• This command is used after a V_RUN_FIND built-in procedure. If image processing is not
yet completed when V_GET_OFFSET is executed, it waits for the completion of the image
processing. V_GET_OFFSET stores the vision offset for a workpiece in a vision register. When
the vision process finds more than one workpiece, V_GET_OFFSET should be called repeatedly.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
Example Program:
------------------------------------------------------------------
PROGRAM vision
------------------------------------------------------------------
%NOLOCKGROUP
%ENVIRONMENT cvis
%ALPHABETIZE
%COMMENT = ’IRVision Built-in’
%NOPAUSE = ERROR + COMMAND + TPENABLE
VAR
STATUS
: INTEGER
visprocess
: STRING[8]
int_value
: INTEGER
real_value
: REAL
A-347
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
--
----------------------------------------
BEGIN
-- the name of the vision process passed from a TP program or MACRO
-- TP example CALL VISION(’VP1’)
GET_TPE_PRM(1,3,int_value,real_value,visprocess,STATUS)
-- V_RUN_FIND, snap an image and run the vision process
V_RUN_FIND(visprocess, 0, STATUS)
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_RUN_FIND FAILED with ERROR CODE ’, STATUS, CR)
ABORT
ENDIF
-- V_GET_OFFSET, get the first offset from the run_find command
-- put the offset into VR[1]
-- call V_GET_OFFSET multiple times to get offsets from multiple parts
V_GET_OFFSET(visprocess, 1, STATUS)
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_GET_OFFSET FAILED with ERROR CODE ’, STATUS, CR)
ABORT
ENDIF
-- Get all the offset values from VR[1] so they can be put into a PR
VREG_OFFSET(1,1,status)
END vision
A.23.3
V_GET_PASSFL iRVision Built-In Procedure
Purpose: Gets the status of the error proofing vision process. It then stores the result in a specified
numeric register.
Syntax:V_GET_PASSFL (vp_name, register_no, status)
[in] vp_name : STRING
A-348
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] register_no : INTEGER
[out] status : INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• vp_name is the name of the error proofing vision process created in setup mode
• register_no is the register number the command will set with the error proofing operations status.
— Zero - error proofing operation failed
— One - error proofing operation was successful
— Two - error proofing operation is undetermined because the parent tool failed
• status explains the status of the attempted operation. If status is not equal to 0, then an error
occurred.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
Example:
------------------------------------------------------------------
PROGRAM eproof
------------------------------------------------------------------
%NOLOCKGROUP
%ENVIRONMENT CVIS
%ALPHABETIZE
%COMMENT = ’IRVision EP Built-in’
%NOPAUSE = ERROR + COMMAND + TPENABLE
VAR
STATUS
: INTEGER
----------------------------------------
BEGIN
-- Run error proofing vision process ’EP1’
V_RUN_FIND(’EP1’,0,STATUS)
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_RUN_FIND FAILED with ERROR CODE ’, STATUS, CR)
ABORT
ENDIF
-- Put error proofing result into R[1]
V_GET_PASSFL(’EP1’,1,STATUS)
A-349
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_GET_PASSFL FAILED with ERROR CODE ’, STATUS, CR)
ABORT
ENDIF
END eproof
A.23.4
V_GET_QUEUE iRVision Built-in Procedure
Purpose: Gets a part from the specified queue and stores the information in a vision register.
Syntax: V_GET_QUEUE (queue_num, vr_num, timeout, status)
[in] queue_num: INTEGER
[in] vr_num: INTEGER
[in] timeout: INTEGER
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• Queue_num is the number of the queue from which to get the parts.
• Vr_num is the number of the vision register (VR) in which to put the offsets.
• Timeout is the time to wait until a timeout occurs.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• This command sets, as a tracking trigger, the value of the existing encoder when the picked up
target is found.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.5
V_INIT_QUEUE iRVision Built-in Procedure
Purpose: Initializes the specified queue.
Syntax: V_INIT_QUEUE (queue_num, status)
[in] queue_num: INTEGER
A-350
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• Queue_num is the number of the queue to be initialized.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• All workpiece information held in the queue when the command is executed is cleared.
• When multiple robots are used to pick up workpieces on one conveyor, this command must be
executed individually for all robots.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.6
V_RALC_QUEUE iRVision Built-in Procedure
Purpose: Places or reallocates a part received from the queue back onto the queue for a downstream
robot.
Syntax: V_RALC_QUEUE (queue_num, vr_num, status)
[in] queue_num: INTEGER
[in] vr_num: INTEGER
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• Queue_num is the number of the queue in which to reallocate the parts.
• Vr_num is the number of the vision register (VR) of the offset to reallocate.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.7
V_RUN_FIND iRVision Built-In Procedure
Purpose: Starts an iRVision process. When a specified vision process has more than one camera
view, location is performed for the specified camera views.
Syntax:
A-351
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
V_RUN_FIND(vp_name,camera_view,status)
[in] vp_name: STRING
[in] camera_view: INTEGER
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• vp_name is the name of the vision process created in setup mode
• camera_view is the number of the camera view. Used for multi camera vision processes. A
value of -1 will run all of the views.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
Example Program:
------------------------------------------------------------------
PROGRAM vision
------------------------------------------------------------------
%NOLOCKGROUP
%ENVIRONMENT cvis
%ALPHABETIZE
%COMMENT = ’IRVision Built-in’
%NOPAUSE = ERROR + COMMAND + TPENABLE
VAR
STATUS
: INTEGER
visprocess
: STRING[8]
int_value
: INTEGER
real_value
: REAL
--
----------------------------------------
BEGIN
-- the name of the vision process passed from a TP program or MACRO
-- TP example CALL VISION(’VP1’)
A-352
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
GET_TPE_PRM(1,3,int_value,real_value,visprocess,STATUS)
-- V_RUN_FIND, snap an image and run the vision process
V_RUN_FIND(visprocess, 0, STATUS)
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_RUN_FIND FAILED with ERROR CODE ’, STATUS, CR)
ABORT
ENDIF
-- V_GET_OFFSET, get the first offset from the run_find command
-- put the offset into VR[1]
-- call V_GET_OFFSET multiple times to get offsets from multiple parts
V_GET_OFFSET(visprocess, 1, STATUS)
-- success if status is zero
IF STATUS <> 0 THEN
WRITE (’V_GET_OFFSET FAILED with ERROR CODE ’, STATUS, CR)
ABORT
ENDIF
-- Get all the offset values from VR[1] so they can be put into a PR
VREG_OFFSET(1,1,status)
END vision
A.23.8
V_SET_REF iRVision Built-In Procedure
Purpose: Sets the reference position in the specified vision process after V_RUN_FIND has been run.
Syntax:
V_SET_REF(vp_name, status)
[in] vp_name: STRING
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• vp_name is the name of the vision process created in setup mode.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
A-353
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• If a vision process remains open on the setup PC when SET_REFERENCE is executed for the
vision process, the reference position cannot be written to the vision process, which results in an
alarm. Close the setup window, then re-execute the command.
• When the vision process finds more than one workpiece, the position of the workpiece having the
highest score is set as the reference position.
• It is recommended that only one workpiece be placed within the camera view so that an incorrect
position is not set as the reference position.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.9
V_START_VTRK iRVision Built-in Procedure
Purpose: Starts the specified visual tracking vision process.
Syntax: V_START_VTRK (vp_name, status)
[in] vp_name: STRING
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• Vp_name is the name of the visual tracking vision process.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• After this command is executed, iRVision monitors a specified condition (such as a conveyor
move distance). iRVision executes the specified vision process each time a specified condition is
satisfied. When multiple robots are used with one conveyor, this command is executed only in the
robots on which iRVision resides.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.10
V_STOP_VTRK iRVision Built-in Procedure
Purpose: Stops the specified visual tracking vision process.
Syntax: V_STOP_VTRK (vp_name, status)
[in] vp_name: STRING
[out] status: INTEGER
%ENVIRONMENT GROUP: CVIS
A-354
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Details:
• Vp_name is the name of the visual tracking vision process.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• When multiple robots are used with one conveyor, this command is executed only in the robots
on which iRVision resides.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.11
VAR_INFO Built-In Procedure
Purpose: Allows a KAREL program to determine data type and numerical information regarding
internal or external program variables
Syntax: VAR_INFO(prog_name, var_name, uninit, type_nam, type_value, dims, slen, status)
Input/Output Parameters:
[in] prog_name: STRING
[in] var_name: STRING
[out] uninit_b :BOOLEAN
[out] type_nam :STRING
[out] dims:ARRAY[3] OF INTEGER
[out] type_value :INTEGER
[out] status :INTEGER
[out] slen :INTEGER
%ENVIRONMENT Group :BYNAM
Details:
• prog_name specifies the name of the program that contains the specified variable. If prog_name
is blank, then it defaults to the current program being executed.
• var_name must refer to a static program variable.
• var_name can contain node numbers, field names, and/or subscripts.
• uninit_b will return a value of TRUE if the variable specified by var_name is uninitialized and
FALSE if the variable specified by var_name is initialized.
A-355
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• type_nam returns a STRING specifying the type name of var_name
• type_value returns an INTEGER corresponding to the data type of var_name. The following
table lists valid data types and their representative INTEGER values.
Table
A-25.
Valid Data Types
Data Type
Value
POSITION
1
XYZWPR
2
XYZWPREXT
6
INTEGER
16
REAL
17
BOOLEAN
18
VECTOR
19
VIS_PROCESS
21
MODEL
22
SHORT
23
BYTE
24
JOINTPOS1
25
CONFIG
28
FILE
29
PATH
31
CAM_SETUP
32
JOINTPOS2
41
JOINTPOS3
57
JOINTPOS4
73
JOINTPOS5
89
JOINTPOS6
105
JOINTPOS7
121
JOINTPOS8
137
JOINTPOS9
153
JOINTPOS
153
STRING
209
user-defined type
210
A-356
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• dims returns the dimensions of the array, if any. The size of the dims array should be 3.
— dims[1] = 0 if not an array
— dims[2] = 0 if not a two-dimensional array
— dims[3] = 0 if not a three-dimensional array
• slen returns the declared length of the variable specified by var_name if it is a STRING variable.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
Example: The following example retrieves information regarding the variable counter , located
in util_prog , from within the program task.
VAR_INFO Built-In Procedure
PROGRAM util_prog
VAR
counter, i : INTEGER
BEGIN
counter = 0
FOR i = 1 TO 10 DO
counter = counter + 1
ENDFOR
END util_prog
PROGRAM task
VAR
uninit_b
: BOOLEAN
type_name
: STRING[12]
type_code
: INTEGER
slen, status
: INTEGER
alen
: ARRAY[3] OF
INTEGER
BEGIN
VAR_INFO(’util_prog’, ’counter’,
uninit_b, type_name, type_code,
alen, slen, status)
WRITE(’counter : ’, CR)
WRITE(’UNINIT : ’, uninit_b, ’
TYPE : ’, type_name, cr)
END task
A.23.12
VAR_LIST Built-In Procedure
Purpose: Locates variables in the specified KAREL program with the specified name and data type
Syntax : VAR_LIST(prog_name, var_name, var_type, n_skip, format, ary_nam, n_vars, status)
Input/Output Parameters:
A-357
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] prog_name : STRING
[in] var_name : STRING
[in] var_type : INTEGER
[in] n_skip : INTEGER
[in] format : INTEGER
[out] ary_nam : ARRAY of STRING
[out] n_vars : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group :BYNAM
Details:
• prog_name specifies the name of the program that contains the specified variables. prog_name
can be specified using the wildcard (*) character, which specifies all loaded programs.
• var_name is the name of the variable to be found. var_name can be specified using the wildcard
(*) character, which specifies that all variables for prog_name be found.
• var_type represents the data type of the variables to be found. The following is a list of valid
data types:
Table
A-26.
Valid Data Types
Data Type
Value
All variable types
0
POSITION
1
XYZWPR
2
INTEGER
16
REAL
17
BOOLEAN
18
VECTOR
19
VIS_PROCESS
21
MODEL
22
SHORT
23
BYTE
24
A-358
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Table
A-26.
Valid Data Types (Cont’d)
Data Type
Value
JOINTPOS1
25
CONFIG
28
FILE
29
PATH
31
CAM_SETUP
32
JOINTPOS2
41
JOINTPOS3
57
JOINTPOS4
73
JOINTPOS5
89
JOINTPOS6
105
JOINTPOS7
121
JOINTPOS8
137
JOINTPOS9
153
JOINTPOS
153
STRING
209
user-defined type
210
• n_skip is used when more variables exist than the declared length of ary_nam . Set n_skip to
0
the first time you use VAR_LIST. If ary_nam is completely filled with variable names, copy the
array to another ARRAY of STRINGs and execute the VAR_LIST again with n_skip equal to
n_vars . The call to VAR_LIST will skip the variables found in the first pass and locate only the
remaining variables.
• format specifies the format of the program name and variable name. The following values
are valid for format :
1=prog_name only, no blanks
2 =var_name only, no blanks
3 =[prog_name]var_name, no blanks
4 =’prog_name var_name
’,
Total length = 27 characters, prog_name
starts with character 1 and var_name starts with character 16.
• ary_nam is an ARRAY of STRINGs to store the variable names. If the declared length of the
STRING in ary_nam is not long enough to store the formatted data, then status is returned with an
error.
A-359
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• n_vars is the number of variables stored in ary_name.
• status will return zero if successful.
See Also: FILE_LIST, PROG_LIST Built-In Procedures
Example: Refer to Section B.2 , "Copying Path Variables" (CPY_PTH.KL), for a detailed program
example.
A.23.13
VECTOR Data Type
Purpose: Defines a variable, function return type, or routine parameter as VECTOR data type
Syntax : VECTOR
Details:
• A VECTOR consists of three REAL values representing a location or direction in three
dimensional Cartesian coordinates.
• Only VECTOR expressions can be assigned to VECTOR variables, returned from VECTOR
function routines, or passed as arguments to VECTOR parameters.
• Valid VECTOR operators are:
— Addition (+) and subtraction (-) mathematical operators
— Equal (=) and the not equal (<>) relational operators
— Cross product (#) and the inner product (@) operators.
— Multiplication (*) and division (÷) operators
— Relative position (:) operator
• Component fields of VECTOR variables can be accessed or set as if they were defined as follows:
VECTOR Data Type
VECTOR = STRUCTURE
X: REAL
Y: REAL
Z: REAL
ENDSTRUCTURE
Note: All fields are read-write
Example: The following example shows VECTOR as variable declarations, as parameters in a
routine, and as a function routine return type.
A-360
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
VECTOR Data Type
VAR
direction, offset : VECTOR
ROUTINE calc_offset(offset_vec:VECTOR):VECTOR FROM util_prog
A.23.14
VOL_SPACE Built-In Procedure
Purpose: Returns the total bytes, free bytes, and volume name for the specified device
Syntax : VOL_SPACE(device, total, free, volume)
Input/Output Parameters:
[in] device :STRING
[out] total :INTEGER
[out] free :INTEGER
[out] volume :STRING
%ENVIRONMENT Group :FLBT
Details:
• devices can be:
RD: The RAM disk returns all three parameters, but the volume name is ’’ since it is not
supported. The RAM disk must be mounted in order to query it.
FR: The FROM disk returns all three parameters, but the volume name is ’’ since it is not
supported. The FROM disk must be mounted in order to query it.
FR: Size of the Flash ROM. This only sets the total parameter.
DRAM: Size of the DRAM. This only sets the total parameter.
CMOS: Size of the CMOS ROM. This only sets the total parameter.
TPP : The area of system memory where teach pendant programs are stored.
PERM: The area of permanent CMOS RAM memory where system variables and selected
KAREL variables are stored.
A-361
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
TEMP: The area of temporary DRAM memory used for loaded KAREL programs, KAREL
variables, program execution information, and system operations.
SYSTEM: The area of temporary DRAM memory where the system software and options are
stored. This memory is saved to FROM and restored on power up.
Note All device names must end with a colon (:).
• total is the original size of the memory, in bytes.
• free is the amount of available memory, in bytes.
• volume is the name of the storage device used.
See Also: Section 1.4.1 , Status Memory in the "Status Displays and Indicators," chapter of the
appropriate application-specific FANUC Robotics Setup and Operations Manual .
Example: The following example gets information about the different devices.
VOL_SPACE Built-In Procedure
PROGRAM space
%NOLOCKGROUP
%ENVIRONMENT FLBT
VAR
total: INTEGER
free:
INTEGER
volume: STRING [30]
BEGIN
VOL_SPACE(’rd:’, total, free, volume)
VOL_SPACE(’fr:’, total, free, volume)
VOL_SPACE(’frp:’, total, free, volume)
VOL_SPACE(’fr:’, total, free, volume)
VOL_SPACE(’dram:’, total, free, volume)
VOL_SPACE(’cmos:’, total, free, volume)
VOL_SPACE(’tpp:’, total, free, volume)
VOL_SPACE(’perm:’, total, free, volume)
VOL_SPACE(’temp:’, total, free, volume)
END space
A.23.15
VREG_FND_POS iRVision Built-in Procedure
Purpose: Populates the specified position register with the found position data in the specified
vision register.
Syntax: VREG_FND_POS (visreg_no, camera_view, posreg_no, status)
A-362
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] visreg_no : INTEGER
[in] camera_view : INTEGER
[in] posreg_no : INTEGER
[out] status : INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• Visreg_no is the vision register (VR) number that contains the offset data.
• Camera_view is the specified camera view for a multi view vision process.
• Posreg_no is the position register (PR) number that is to be populated with the offset data.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A.23.16
VREG_OFFSET iRVision Built-in Procedure
Purpose: Populates the specified position register with the offset data in the specified vision register.
Syntax: VREG_OFFSET(visreg_no, posreg_no, status)
[in] visreg_no : INTEGER
[in] posreg_no : INTEGER
[out] status : INTEGER
%ENVIRONMENT GROUP: CVIS
Details:
• Visreg_no is the vision register (VR) number that contains the offset data
• Posreg_no is the position register (PR) number that is to be populated with the offset data.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
• This built-in requires the iRVision KAREL Interface Software Option (J870).
A-363
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.24
- W - KAREL LANGUAGE DESCRIPTION
A.24.1
WAIT FOR Statement
Purpose: Delays continuation of program execution until some condition(s) are met
Syntax : WAIT FOR cond_list
where:
cond_list: one or more conditions
Details:
• All of the conditions in a single WAIT FOR statement must be satisfied simultaneously for
execution to continue.
See Also: Chapter 6 CONDITION HANDLERS , Appendix E , ‘‘Syntax Diagrams,’’ for more syntax
information
Example: Refer to the following sections for detailed program examples:
Section B.6 , "Path Variables and Condition Handlers Program" (PTH_MOVE.KL)
Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
A.24.2
WHEN Clause
Purpose: Used to specify a conditions/actions pair in a global condition handler
Syntax : WHEN cond_list DO action_list
where:
cond_list : one or more conditions
action_list : one or more conditions
Details:
• All of the conditions in the cond_list of a single WHEN clause must be satisfied simultaneously
for the condition handler to be triggered.
• The action_list represents a list of actions to be taken when the corresponding conditions of a
WHEN clause are satisfied simultaneously.
A-364
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• Calls to function routines are not allowed in a CONDITION statement and, therefore, cannot be
used in a WHEN clause.
• CONDITION statements can include multiple WHEN clauses.
See Also: Chapter 6 CONDITION HANDLERS , Appendix E , ‘‘Syntax Diagrams,’’ for more syntax
information
Example: Refer to the following sections for detailed program examples:
Section B.6 , "Path Variables and Condition Handlers Program" (PTH_MOVE.KL)
Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL)
Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
A.24.3
WHILE...ENDWHILE Statement
Purpose: Used when an action is to be executed as long as a BOOLEAN expression remains TRUE
Syntax : WHILE boolean_exp DO{ statement }ENDWHILE
where:
boolean_exp : a BOOLEAN expression
statement : a valid KAREL executable statement
Details:
• boolean_exp is evaluated before each iteration.
• As long as boolean_exp is TRUE, the statements in the loop are executed.
• If boolean_exp is FALSE, control is transferred to the statement following ENDWHILE, and the
statement or statements in the body of the loop are not executed.
See Also: Appendix E , ‘‘Syntax Diagrams,’’ for more syntax information
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A.24.4
WITH Clause
Purpose: Used in condition handlers to specify condition handler qualifiers
A-365
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Syntax : WITH param_spec {, param_spec}
where:
param_spec is of the form : with_sys_var = value
with_sys_var : one of the system variables available for use in the WITH clause
value : an expression of the type corresponding to the type of the system variable
Details:
• The actual system variables specified are not changed.
•
$PRIORITY and $SCAN_TIME are condition handler qualifiers that can be used in a WITH
clause only when the WITH clause is part of a condition handler statement.
A.24.5
WRITE Statement
Purpose: Writes data to a serial device or file
Syntax : WRITE <file_var> (data_item { ,data_item })
where:
file_var : a FILE variable
data_item : an expression and its optional format specifiers or the reserved word CR
Details:
• If file_var is not specified in a WRITE statement the default TPDISPLAY is used. %CRTDEVICE
directive will change the default to OUTPUT.
• If file_var is specified, it must be one of the output devices or a variable that has been equated
to one of them.
• If file_var attribute was set with the UF option, data is transmitted to the specified file or device
in binary form. Otherwise, data is transmitted as ASCII text.
• data_item can be any valid KAREL expression.
• If data_item is of type ARRAY, a subscript must be provided.
• If data_item is of type PATH, you can specify that the entire path be read, a specific node be
read [n], or a range of nodes be read [n .. m].
• Optional format specifiers can be used to control the amount of data that is written for each
data_item .
A-366