FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual - page 20
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] term_mask : INTEGER
[in] init_data : STRING
[out] n_chars_got : INTEGER
[out] term _char : INTEGER
[out] stat us : INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• Causes data from specified classes of characters to be stored in a user-supplied buffer until a
termination condition is met or the buffer is full. Returns to the caller when the read is terminated.
• If you use READ_KB for the CRT/KB, you will get "raw" CRT characters returned. To get teach
pendant equivalent key codes, you must perform the following function:
tp_key = $CRT_KEY_TBL[crt_key + 1]
This mapping allows you to use common software between the CRT/KB and teach pendant
devices.
•
READ_KB and some other utilities use a variable in your KAREL program called device_stat to
establish the association between the KAREL program and user interface display. For example,
if you have a task [MAINUIF] which calls READ_KB, the variable which is used to make the
association is [MAINUIF]device_stat. If you do not set device_stat, then you can only read
characters in single screen mode, or in the left pane.
•
device_stat must be set to the paneID in which your application is running. For the standard single
mode/monochrome pendant, device_stat =1. To interact in the right pane, set device_stat=2. To
interact in the lower right pane, set device_stat=3. External Internet Explorer connections use
panes 4-9. For the CRT/KB, set device_stat=255.
•
[MAINUIF]device_stat must be set to the correct pane ID before you open the keyboard file that
is assoicated with READ_KB. The pane ID for the iPendant can be either 1, 2 or 3.
•
The application running in Pane ID 1 is stored in $TP_CURSCRN. Pane ID 2 is stored in
$UI_CURSCRN[1], or in general $UI_CURSCRN[device_stat-1]. The CRT applicaton uses
$CT_CURSCRN.
•
file_var must be open to a keyboard-device. If file_var is also associated with a window, the
characters are echoed to the window.
•
The characters are stored in buffer , up to a maximum of buffer_size or the size of the string,
whichever is smaller.
•
accept_mask is a bit-wise mask indicating the classes of characters that will be accepted as input.
This should be an OR of the constants defined in the include file klevkmsk.kl.
A-274
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
kc_display :Displayable keys
kc_func_key :Function keys
kc_keypad :Key-pad and Edit keys
kc_enter_key :Enter and Return keys
kc_delete :Delete and Backspace keys
kc_lr_arw :Left and Right Arrow keys
kc_ud_arw :Up and Down Arrow keys
kc_other :Other keys (such as Prev)
•
It is reasonable for accept_mask to be zero; this means that no characters are accepted as input.
This is used when waiting for a single key that will be returned as the term_char. In this case,
buffer_size would be zero.
•
If accept_mask includes displayable characters, the following characters, if accepted, have the
following meanings:
— Delete characters - If the cursor is not in the first position of the field, the character to the left
of the cursor is deleted.
— Left and right arrows - Position the cursor one character to the left or right from its present
position, assuming it is not already in the first or last position already.
— Up and down arrows - Fetch input previously entered in reads to the same file.
•
term_mask is a bit-wise mask indicating conditions which will terminate the request. This should
be an OR of the constants defined in the include file klevkmsk.kl.
kc_display :Displayable keys
kc_func_key :Function keys
kc_keypad :Key-pad and Edit keys
kc_enter_key :Enter and Return keys
kc_delete :Delete and Backspace keys
kc_lr_arw :Left and Right Arrow keys
kc_ud_arw :Up and Down Arrow keys
kc_other :Other keys (such as Prev)
•
time_out specifies the time, in milliseconds, after which the input operation will be automatically
canceled. A value of -1 implies no timeout.
A-275
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
•
init_data_p points to a string which is displayed as the initial value of the input field. This
must not be longer than buffer_size.
•
n_chars_got is set to the number of characters in the input buffer when the read is terminated.
•
term_char receives a code indicating the character or other condition that terminated the form.
The codes for key terminating conditions are defined in the include file klevkeys.kl. Keys
normally returned are pre-defined constants as follows:
ky_up_arw
ky_dn_arw
ky_rt_arw
ky_lf_arw
ky_enter
ky_prev
ky_f1
ky_f2
ky_f3
ky_f4
ky_f5
ky_next
•
status explains the status of the attempted operation. If not equal to 0, then an error occurred.
Example: Refer to Section B.2 , "Copying Path Variables" (CPY_PTH.KL), for a detailed program
example.
The following example suspends any teach pendant reads, uses READ_KB to read a single key, and
then resumes any suspended reads.
READ_KB Built-In Procedure
PROGRAM readkb
%NOLOCKGROUP
%ENVIRONMENT flbt
%ENVIRONMENT uif
%INCLUDE FR:eklevkmsk
VAR
file_var: FILE
key: INTEGER
A-276
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
n_chars_got: INTEGER
pop_index: INTEGER
status: INTEGER
str: STRING[1]
BEGIN
-- Suspend any outstanding TP Keyboard reads
PUSH_KEY_RD(’TPKB’, 255, pop_index, status)
IF (status = 0) THEN
WRITE (CR, ’pop_index is ’, pop_index)
ELSE
WRITE (CR, ’PUSH_KEY_RD status is ’, status)
ENDIF
-- Open a file to TP Keyboard with PASALL and FIELD attributes
-- and NOECHO
SET_FILE_ATR(file_var, ATR_PASSALL)
SET_FILE_ATR(file_var, ATR_FIELD)
OPEN FILE file_var (’RW’, ’KB:TPKB’)
-- Read a single key from the TP Keyboard
READ_KB(file_var, str, 1, 0, kc_display+kc_func_key+kc_keypad+
kc_enter_key+kc_lr_arw+kc_ud_arw+kc_other, 0, ’’,
n_chars_got, key, status)
IF (status = 0) THEN
WRITE (CR, ’key is ’, key, ’, n_chars_got = ’, n_chars_got)
ELSE
WRITE (CR, ’READ_KB status is ’, status)
ENDIF
CLOSE FILE file_var
-- Resume any outstanding TP Keyboard reads
POP_KEY_RD(’TPKB’, pop_index, status)
IF (status <> 0) THEN
WRITE (CR, ’POP_KEY_RD status is ’, status)
ENDIF
END readkb
A.19.5
REAL Data Type
Purpose: Defines a variable, function return type, or routine parameter as a REAL data type with a
numeric value that includes a decimal point and a fractional part, or numbers expressed in scientific
notation
Syntax : REAL
Details:
A-277
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
•
REAL variables and expressions can have values in the range of -3.4028236E+38 through
-1.175494E-38, 0.0, and from +1.175494E-38 through +3.4028236E+38, with approximately
seven decimal digits of significance. Otherwise, the program will be aborted with the ‘‘Real
overflow’’ error.
•
The decimal point is mandatory when defining a REAL constant or literal (except when using
scientific notation). The decimal point is not mandatory when defining a REAL variable as
long as it was declared as REAL.
•
Scientific notation is allowed and governed by the following rules:
— The decimal point is shifted to the left so that only one digit remains in the INTEGER part.
— The fractional part is followed by the letter E (upper or lower case) and ±an INTEGER.
This part specifies the magnitude of the REAL number. For example, 123.5 is expressed as
1.235E2.
— The fractional part and the decimal point can be omitted. For example, 100.0 can be
expressed as 1.000E2, as 1.E2, or 1E2.
•
All REAL variables with magnitudes between -1.175494E- 38 and +1.175494E-38 are treated
as 0.0.
•
Only REAL or INTEGER expressions can be assigned to REAL variables, returned from REAL
function routines, or passed as arguments to REAL parameters.
•
If an INTEGER expression is used in any of these instances, it is treated as a REAL value. If
an INTEGER variable is used as an argument to a REAL parameter, it is always passed by
value, not by reference.
•
Valid REAL operators are (refer to Table A-18 ):
— Arithmetic operators (+, +, *, /)
— Relational operators (>, >=, =, < >, <, <=)
Table
A-18.
Valid and Invalid REAL operators
VALID
INVALID
REASON
1.5
15
Decimal point is required (15 is an INTEGER not a REAL)
1.
Must include an INTEGER or a fractional part
+2500.450
+2,500.450
Commas not allowed
1.25E-4
1.25E -4
Spaces not allowed
Example: Refer to the following sections for detailed program examples:
Section B.5 ,"Using Register Built-ins" (REG_EX.KL)
Section B.8 , "Generating and Moving Along a Hexagon Path" (GEN_HEX.KL)
Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL)
A-278
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Section B.11 , "Manipulating Values of Dynamically Displayed Variables" (CHG_DATA.KL)
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.19.6
Relational Condition
Purpose: Used to test the relationship between two operands
Syntax : variable <[subscript]> rel_op expression
where:
variable : a static INTEGER or REAL variable or a BOOLEAN port array element
subscript : an INTEGER expression (only used with port arrays)
rel_op : a relational operator
expression : a static variable, constant, or EVAL clause
Details:
•
Relational conditions are state conditions, meaning the relationship is tested during every scan.
•
The following relational operators can be used:
= :equal
<> :not equal
< :less than
=< :less than or equal
> :greater than
>= :greater than or equal
•
Both operands must be of the same data type and can only be of type INTEGER, REAL, or
BOOLEAN. INTEGER values can be used where REAL values are required, and will be treated
as REAL values.
•
variable can be any of the port array signals, a user-defined static variable, or a system variable
that can be read by a KAREL program.
•
expression can be a user-defined static variable, a system variable that can be read by a KAREL
program, any constant, or an EVAL clause.
•
Variables used in relational conditions must be initialized before the condition handler is enabled.
A-279
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A.19.7
RELAX HAND Statement
Purpose: Turns off open signal for a tool controlled by one signal or turns off both open and close
signals for a tool controlled by a pair of signals.
Syntax : RELAX HAND hand_num
where:
hand_num : an INTEGER expression
Details:
• The actual effect of the statement depends on how the HAND signals are set up. Refer to Chapter
13, ‘‘Input/Output System.’’
• hand_num must be a value in the range 1-2. Otherwise, the program is aborted with an error.
• The statement has no effect if the value of hand_num is in range but the hand is not connected.
• If the value of hand_num is in range but the HAND signal represented by that value has not been
assigned, the program is aborted with an error.
See Also: Chapter 13, ‘‘Input/Output System,’’ Appendix D, ‘‘Syntax Diagrams,’’ for more syntax
information
Example: In the following example, the robot hand, specified by gripper , is relaxed using the
RELAX HAND statement. The robot then moves to the POSITION pstart before closing the hand.
RELAX HAND Statement
PROGRAM p_release
%NOPAUSE=TPENABLE
%ENVIRONMENT uif
BEGIN
RELAX HAND gripper
SET_POS_REG(1, pstart, status) —— Put position in PR[1]
move_to_pr1 —— Call TP program to move to PR[1]
CLOSE HAND gripper
END p_release
A-280
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
A.19.8
RELEASE Statement
Purpose: Releases all motion control of the robot arm and auxiliary or extended axes from the KAREL
program so that they can be controlled by the teach pendant while a KAREL program is running
Syntax : RELEASE
Details:
• Motion stopped prior to execution of the RELEASE statement can only be resumed after the
execution of the next ATTACH statement.
• If motion is initiated from the program while in a released state, the program is aborted with the
following error, ‘‘MCTRL Denied because Released.’’
• If RELEASE is executed while motion is in progress or in a HOLD condition, the program is
aborted with the following error, "Detach request failed."
• All motion control from all KAREL tasks will be released.
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.19.9
REMOVE_DICT Built-In Procedure
Purpose: Removes the specified dictionary from the specified language or from all existing languages
Syntax : REMOVE_DICT(dict_name, lang_name, status)
Input/Output Parameters:
[in] dict_name : STRING
[in] lang_name : STRING
[out] status : INTEGER
%ENVIRONMENT Group :UIF
Details:
• dict_name specifies the name of the dictionary to remove.
• lang_name specifies which language the dictionary should be removed from. One of the
following pre-defined constants should be used:
A-281
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
dp_default
dp_english
dp_japanese
dp_french
dp_german
dp_spanish
If lang_name is ’’, it will be removed from all languages in which it exists.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred
removing the dictionary file.
See Also: ADD_DICT Built-In Procedure, Chapter 10 DICTIONARIES AND FORMS
Example: Refer to Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL), for a
detailed program example.
A.19.10
RENAME_FILE Built-In Procedure
Purpose: Renames the specified file name
Syntax : RENAME_FILE(old_file, new_file, nowait_sw, status)
Input/Output Parameters:
[in] old_file : STRING
[in] new_file : STRING
[in] nowait_sw : BOOLEAN
[out] status : INTEGER
%ENVIRONMENT Group :FDEV
Details:
• old_file specifies the device, name, and type of the file to rename.
• new_file specifies the name and type of the file to rename to.
• If nowait_sw is TRUE, execution of the program continues while the command is executing. If it
is FALSE, the program stops, including condition handlers, until the operation has completed.
A-282
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
If you have time critical condition handlers in your program, put them in another program that
executes as a separate task.
Note nowait_sw is not available in this release and should be set to FALSE.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: COPY_FILE, DELETE_FILE Built-In Procedures
A.19.11
RENAME_VAR Built-In Procedure
Purpose: Renames a specified variable in a specified program to a new variable name
Syntax : RENAME_VAR(prog_nam, old_nam, new_nam, status)
Input/Output Parameters:
[in] prog_nam : STRING
[in] old_nam : STRING
[in] new_nam : STRING
[out] status : INTEGER
%ENVIRONMENT Group :MEMO
Details:
• prog_nam is the name of the program that contains the variable to be renamed.
• old_nam is the current name of the variable.
• new_nam is the new name of the variable.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: CREATE_VAR, SET_VAR Built-In Procedures
A.19.12
RENAME_VARS Built-In Procedure
Purpose: Renames all of the variables in a specified program to a new program name
Syntax : RENAME_VARS(old_nam, new_nam, status)
Input/Output Parameters:
A-283
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] old_nam : STRING
[in] new_nam : STRING
[out] status : INTEGER
%ENVIRONMENT Group :MEMO
Details:
• old_nam is the current name of the program.
• new_nam is the new name of the program.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: CREATE_VAR, RENAME_VARS Built-in Procedures
A.19.13
REPEAT ... UNTIL Statement
Purpose: Repeats statement(s) until a BOOLEAN expression evaluates to TRUE
Syntax : REPEAT
{ statement }
UNTIL boolean_exp
where:
statement : a valid KAREL executable statement
boolean_exp : a BOOLEAN expression
Details:
• boolean_exp is evaluated after execution of the statements in the body of the REPEAT loop to
determine if the statements should be executed again.
• statement continues to be executed and the boolean_exp is evaluated until it equals TRUE.
• statement will always be executed at least once.
Caution
Make sure your REPEAT statement contains a boolean flag that is modified
by some condition, and an UNTIL statement that terminates the loop. If it
does not, your program could loop infinitely.
A-284
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
See Also: Appendix E , ‘‘Syntax Diagrams,’’ for more syntax information
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)
Section B.11 , "Manipulating Values of Dynamically Displayed Variables" (CHG_DATA.KL)
Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL)
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.19.14
RESET Built-In Procedure
Purpose: Resets the controller
Syntax : RESET(successful)
Input/Output Parameters:
[out] successful : BOOLEAN
%ENVIRONMENT Group :MOTN
Details:
• successful will be TRUE even if conditions exist which prevent resetting the controller.
• To determine whether the reset operation was successful, delay 1 second and check OPOUT[3]
(FAULT LED). If this is FALSE, the reset operation was successful.
• The statement following the RESET Built-In is not executed until the reset fails or has completed.
The status display on the CRT or teach pendant will indicate PAUSED during the reset.
• The controller appears to be in a PAUSED state while a reset is in progress but, during this time,
PAUSE condition handlers will not be triggered.
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A-285
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.19.15
RESUME Action
Purpose: Restarts the last stopped motion issued by the task
Syntax : RESUME <GROUP[n{,n}]>
Details:
• A motion set is a group of motions issued but not yet terminated when a STOP statement
or action is issued.
• If there are no stopped motion sets, no motion will result from the RESUME.
• If more than one motion set has been stopped, RESUME restarts the most recently stopped,
unresumed motion set. Subsequent RESUMEs will start the others in last-in-first-out sequence.
• The motions contained in a stopped motion set are resumed in the same order in which they
were originally issued.
• If a motion is in progress when the RESUME action is issued, any resumed motion(s) occur
after the current motion is completed.
• If the group clause is not present, all groups for which the task has control (when the condition is
defined) will be resumed.
• If the motion that is stopped, resumed, canceled, or held is part of a SIMULTANEOUS or
COORDINATED motion with other groups, the motions for all groups are stopped, resumed,
canceled, or held.
• Motion cannot be resumed for a different task.
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A.19.16
RESUME Statement
Purpose: Restarts the last stopped motion issued by the task
Syntax : RESUME <GROUP[n{,n}]>
• A motion set is a group of motions issued but not yet terminated when a STOP statement
or action is issued.
• If there are no stopped motion sets, no motion will result from the RESUME.
• If more than one motion set has been stopped, RESUME restarts the most recently stopped,
unresumed motion set. Subsequent RESUMEs will start the others in last-in-first-out sequence.
• Those motions in a stopped motion set are resumed in the same order in which they were
originally issued.
A-286
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• If a motion is in progress when the RESUME statement is issued, any resumed motion(s) occur
after the current motion is completed.
• If the group clause is not present, all groups for which the task has control will be resumed.
• If the motion that is stopped, resumed, canceled, or held is part of a SIMULTANEOUS or
COORDINATED motion with other groups, the motions for all groups are stopped, resumed,
canceled, or held.
• Motion cannot be resumed for a different task.
See Also: Appendix E , ‘‘Syntax Diagrams’’ for more syntax information
Example: In the following example, motion is stopped if DIN[1] is ON. It is resumed after F1
is pressed.
RESUME Statement
CONDITION[1]:
WHEN DIN[1] = ON DO
STOP
ENDCONDITION
move_to_pr1 —— Call TP program to move to PR[1]
IF DIN[1] THEN
WRITE(’ Motion stopped’)
WRITE(CR, ’Motion and the program will resume’)
WRITE(CR, ’
when F1 of teach pendant is pressed’)
WAIT FOR TPIN[129]
RESUME
ENDIF
A.19.17
RETURN Statement
Purpose: Returns control from a routine/program to the calling routine/program, optionally returning
a result
Syntax : RETURN < (value) >
Details:
• value is required when returning from functions, but is not permitted when returning from
procedures. The data type of value must be the same as the type used in the function declaration.
• If a main program executes a RETURN statement, execution is terminated and cannot be
resumed. All motions in progress will be completed normally.
• If no RETURN is specified, the END statement serves as the return.
A-287
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• If a function routine returns with the END statement instead of a RETURN statement, the
program is aborted with the 12321 error, ‘‘END STMT of a func rtn.’’
See Also: Appendix E , ‘‘Syntax Diagrams,’’ for more syntax information
Example: Refer to the following sections for detailed program examples:
Section B.7 , "Listing Files and Programs and Manipulating Strings" (LIST_EX.KL)
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.19.18
ROUND Built-In Function
Purpose: Returns the INTEGER value closest to the specified REAL argument
Syntax : ROUND(x)
Function Return Type :INTEGER
Input/Output Parameters:
[in] x :REAL
%ENVIRONMENT Group :SYStem
Details:
• The returned value is the INTEGER value closest to the REAL value x, as demonstrated by
the following rules:
— If x >= 0, let n be a positive INTEGER such that n <= x <= n + 1
— If x >= n + 0.5, then n + 1 is returned; otherwise, n is returned.
— If x <= 0, let n be a negative INTEGER such that n >= x >= n - 1
— If x <= n - 0.5, then n - 1 is returned; otherwise, n is returned.
• x must be in the range of -2147483648 to +2147483646. Otherwise, the program will be aborted
with an error.
See Also: TRUNC Built-In Function
Example: Refer to Section B.7 , "Listing Files and Programs and Manipulating Strings"
(LIST_.EX.KL), for a detailed program example.
A-288
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
A.19.19
ROUTINE Statement
Purpose: Specifies a routine name, with parameters and types, and a returned value data type for
function routines
Syntax : ROUTINE name < param_list > <: return_type >
where:
name : a valid KAREL identifier
param_list : described below
return_type : any data type that can be returned by a function, that is, any type except FILE, PATH,
and vision types
Details:
• name specifies the routine name.
• param_list is of the form ( name_group { ; name_group } )
— name_group is of the form param_name : param_type
— param_name is a parameter which can be used within the routine body as a variable of
data type param_type.
— If a param_type or return_type is an ARRAY, the size is excluded. If the param_type is
a STRING, the string length is excluded.
• When the routine body follows the ROUTINE statement, the names in param_list are used to
associate arguments passed in with references to parameters within the routine body.
• When a routine is from another program, the names in the parameter list are of no significance
but must be present in order to specify the number and data types of parameters.
• If the ROUTINE statement contains a return_type, the routine is a function routine and returns a
value. Otherwise, it is a procedure routine.
• The ROUTINE statement must be followed by a routine body or a FROM clause.
Example: Refer to the following sections for detailed program examples:
Section B.2 , "Copying Path Variables" (CPY_PTH.KL)
Section B.4 ,"Standard Routines" (ROUT_EX.KL)
Section B.6 , "Path Variables and Condition Handlers Program" (PTH_MOVE.KL)
Section B.7 , "Listing Files and Programs and Manipulating Strings" (LIST_EX.KL)
Section B.8 , "Generating and Moving Along a Hexagon Path" (GEN_HEX.KL)
A-289
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Section B.9 , "Using the File and Device Built-ins" (FILE_EX.KL)
Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL)
Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL)
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
A.19.20
RUN_TASK Built-In Procedure
Purpose: Runs the specified program as a child task
Syntax : RUN_TASK (task_name, line_number, pause_on_sft, tp_motion, lock_mask, status)
Input/Output Parameters:
[in] task_name : STRING
[in] line_number : INTEGER
[in] pause_on_sft : BOOLEAN
[in] tp_motion : BOOLEAN
[in] lock_mask : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group :MULTI
Details:
• task_name is the name of the task to be run. This creates a child task. The task that executes
this built-in is called the parent task.
• If the task already exists and is paused, it will be continued. A new task is not created.
• line_number specifies the line from which execution starts. Use 0 to start from the beginning of
the program. This is only valid for teach pendant programs.
• If pause_on_sft is TRUE, the task is paused when the teach pendant shift key is released.
• If tp_motion is TRUE, the task can execute motion while the teach pendant is enabled. The
TP must be enabled if tp_motion is TRUE.
• The control of the motion groups specified in lock_mask will be transferred from parent task to
child task, if tp_motion is TRUE and the teach pendant is enabled. The group numbers must be in
A-290
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
the range of 1 to the total number of groups defined on the controller. Bit 1 specifies group 1, bit
2 specifies group 2, and so forth.
Table A-19.
Group_mask setting
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-19 , which correspond to
the desired groups. Then connect them together using the OR operator. For example to specify
groups 1 and 3, enter "1 OR 4".
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: CONT_TASK, PAUSE_TASK, ABORT_TASK Built-In Procedures, Chapter 15
MULTI-TASKING
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.20
- S - KAREL LANGUAGE DESCRIPTION
A.20.1
SAVE Built-In Procedure
Purpose: Saves the program or variables into the specified file
Syntax : SAVE (prog_nam, file_spec, status)
Input/Output Parameters :
[in] prog_nam :STRING
[in] file_spec :STRING
[out] status :INTEGER
%ENVIRONMENT Group :MEMO
Details:
• prog_nam specifies the program name. If program name is ’*’, all programs or variables of the
specified type are saved. prog_name must be set to "*SYSTEM*" in order to save all system
variables.
A-291
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• file_spec specifies the device, name, and type of the file being saved to. The type also implies
whether programs or variables are being saved.
The following types are valid:
.TP : Teach pendant program
.VR : KAREL variables
.SV : KAREL system variables
.IO : I/O configuration data
• If file_spec already exists on the specified device, then an error is returned the save does not occur.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: CLEAR, LOAD Built-In Procedures
Example: Refer to Section B.3 ,"Saving Data to the Default Device" (SAVE_VRS.KL), for a
detailed program example.
A.20.2
SAVE_DRAM Built-In Procedure
Purpose: Saves the RAM variable content to FlashROM.
Syntax: SAVE_DRAM (prog_nam, status)
Input/Output Parameters:
[in] prog_nam: STRING
[out] status: INTEGER
%ENVIRONMENT Group: MEMO
Details:
• prog_nam specifies the program name. This operation will save the current values of any
variables in DRAM to FlashROM for the specified program. At power up these saved values will
automatically be loaded into DRAM.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
A-292
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
A.20.3
SELECT ... ENDSELECT Statement
Purpose: Permits execution of one out of a series of statement sequences, depending on the value
of an INTEGER expression.
Syntax: SELECT case_val OF
CASE(value{,value}):
{statement}
{ CASE(value{, value}):
{statement} }
<ELSE:
{ statement }>
ENDSELECT
where:
case_val : an INTEGER expression
value : an INTEGER constant or literal
statement : a valid KAREL executable statement
Details:
• case_val is compared with each of the values following the CASE in each clause. If it is equal to
any of these, the statements between the CASE and the next clause are executed.
• Up to 1000 CASE clauses can be used in a SELECT statement.
• If the same INTEGER value is listed in more than one CASE, only the statement sequence
following the first matching CASE will be executed.
• If the ELSE clause is used and the expression case_val does not match any of the values in the
CASE clauses, the statements between the keywords ELSE and ENDSELECT are executed.
• If no ELSE clause is used and the expression case_val does not match any of the values in the
CASE clauses, the program is aborted with the ‘‘No match in CASE’’ error.
See Also: Appendix E , ‘‘Syntax Diagrams,’’ for more syntax information
Example: Refer to the following sections for detailed program examples:
Section B.3 , "Saving Data to the Default Device" (SAVE_VR.KL)
A-293
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL)
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.20.4
SELECT_TPE Built-In Procedure
Purpose: Selects the program of the specified name
Syntax : SELECT_TPE(prog_name, status)
Input/Output Parameters :
[in] prog_name :STRING
[out] status : :INTEGER
%ENVIRONMENT Group :TPE
Details:
• prog_name specifies the name of the program to be selected as the teach pendant default. This is
the program that is "in use" by the teach pendant. It is also the program that will be executed if the
CYCLE START button is pressed or the teach pendant FWD key is pressed.
• status explains the status of the attempted operation. If it is not equal to 0, then an error has
occurred.
See Also: OPEN_TPE Built-in Procedure
Example: Refer to Section B.14 , "Applying Offsets to a Copied Teach Pendant Program"
(CPY_TP.KL), for a detailed program example.
A.20.5
SEMA_COUNT Built-In Function
Purpose: Returns the current value of the specified semaphore
Syntax : SEMA_COUNT (semaphore_no)
Function Return Type :INTEGER
Input/Output Parameters :
[in] semaphore_no : INTEGER
%ENVIRONMENT Group :MULTI
A-294
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Details:
• The value of the semaphore indicated by semaphore_no is returned.
• This value is incremented by every POST_SEMA call and SIGNAL SEMAPHORE Action
specifying the same semaphore_no . It is decremented by every PEND_SEMA call.
• If SEMA_COUNT is greater than zero, a PEND_SEMA call will "fall through" immediately. If it
is -n (minus n), then there are n tasks pending on this semaphore.
See Also: POST_SEMA, PEND_SEMA, CLEAR_SEMA Built-In Procedures, Chapter 15
MULTI-TASKING
Example: See examples in Chapter 15 MULTI-TASKING
A.20.6
SEMAPHORE Condition
Purpose: Monitors the value of the specified semaphore
Syntax : SEMAPHORE[semaphore_no]
Details:
• semaphore_no specifies the semaphore number to use.
• semaphore_no must be in the range of 1 to the number of semaphores defined on the controller.
• When the value of the indicated semaphore is greater than zero, the condition is satisfied (TRUE).
A.20.7
SEND_DATAPC Built-In Procedure
Purpose: To send an event message and other data to the PC.
Syntax : SEND_DATAPC(event_no, dat_buffer, status)
Input/Output Parameters :
[in] event_no :INTEGER
[in] dat_buffer :ARRAY OF BYTE
[out] status :INTEGER
%ENVIRONMENT Group :PC
Details:
A-295
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• event_no - a GEMM event number. Valid values are 0 to 255.
• dat_buffer - an array of up to 244 bytes. The KAREL built-ins ADD_BYNAMEPC,
ADD_INTPC, ADD_REALPC, and ADD_STRINGPC can be used to format a KAREL byte
buffer. The actual data buffer format depends on the needs of the PC. There is no error checking
of the dat_buffer format on the controller.
• status - the status of the attempted operation. If not 0, then an error occurred and the event
request was not sent to the PC.
See Also: ADD_BYNAMEPC, ADD_INTPC, ADD_REALPC, ADD_STRINGPC
Example: The following example sends event 12 to the PC with a data buffer.
SEND_DATAPC Built-In Procedure
PROGRAM TESTDATA
%ENVIRONMENT PC
CONST
er_abort = 2
VAR
dat_buffer:
ARRAY[100] OF BYTE
index:
INTEGER
status:
INTEGER
BEGIN
index = 1
ADD_INTPC(dat_buffer,index,55,status)
ADD_REALPC(dat_buffer,index,123.5,status)
ADD_STRINGPC(dat_buffer,index,’YES’,status)
-- send event 12 and data buffer to PC
SEND_DATAPC(12,dat_buffer,status)
IF status<>0 THEN
POST_ERR(status,’’,0,er_abort)
ENDIF
END testdata
A.20.8
SEND_EVENTPC Built-In Procedure
Purpose: To send an event message to the PC.
Syntax : SEND_EVENTPC(event_no, status)
Input/Output Parameters :
[in] event_no :INTEGER
A-296
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[out] status :INTEGER
%ENVIRONMENT Group :PC
Details:
• event_no - a GEMM event number. Valid values are 0 through 255.
• status - the status of the attempted operation. If not 0, then an error occurred and the event
request was not sent to the PC.
Example: The following example sends event 12 to the PC.
SEND_EVENTPC Built-In Procedure
PROGRAM TESTEVT
%ENVIRONMENT PC
CONST
er_abort = 2
VAR
status: INTEGER
BEGIN
-- send event 12 to PC
SEND_EVENTPC(12,status)
-- call built-in here
IF status<>0 THEN
POST_ERR(status,’’,0,er_abort)
ENDIF
END testevt
A.20.9
SET_ATTR_PRG Built-In Procedure
Purpose: Sets attribute data of the specified teach pendant or KAREL program
Syntax : SET_ATTR_PRG(program_name, attr_number, int_value, string_value, status)
Input/Output Parameters :
[in] program_name : STRING
[in] attr_number : INTEGER
[in] int_value : INTEGER
[in] string_value : STRING
[out] status : INTEGER
A-297
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
%ENVIRONMENT Group :TPE
Details:
•
program_name specifies the program to which attribute data is set.
•
attr_number is the attribute whose value is to be set. The following attributes are valid:
AT_PROG_TYPE : (#) Program type
AT_PROG_NAME : Program name (String[12])
AT_OWNER : Owner (String[8])
AT_COMMENT : Comment (String[16])
AT_PROG_SIZE : (#) Size of program
AT_ALLC_SIZE : (#) Size of allocated memory
AT_NUM_LINE : (#) Number of lines
AT_CRE_TIME : (#) Created (loaded) time
AT_MDFY_TIME : (#) Modified time
AT_SRC_NAME : Source file ( or original file ) name (String[128])
AT_SRC_VRSN : Source file version
AT_DEF_GROUP : Default motion groups (for task attribute)
AT_PROTECT : Protection code; 1 :protection OFF; 2 : protection ON
AT_STORAGE : Storage type; TPSTOR_CMOS; TPSTOR_SHADOW; TPSTOR_FILE;
TPSTOR_SHOD
AT_STK_SIZE : Stack size (for task attribute)
AT_TASK_PRI : Task priority (for task attribute)
AT_DURATION : Time slice duration (for task attribute)
AT_BUSY_OFF : Busy lamp off (for task attribute)
AT_IGNR_ABRT : Ignore abort request (for task attribute)
AT_IGNR_PAUS : Ignore pause request (for task attribute)
A-298
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
AT_CONTROL : Control code (for task attribute)
(#) --- Cannot be set.
• If the attribute data is a number, it is set to int_value and string_value is ignored.
• If the attribute data is a string, it is set to string_value and int_value is ignored.
• status explains the status of the attempted operation. If it is not equal to 0, then an error has
occurred. Some of the errors which could occur are:
7073 The program specified in program_name does not exist
7093 The attribute of a program cannot be set while it is running
17033 attr_number has an illegal value or cannot be set
A.20.10
SET_CURSOR Built-In Procedure
Purpose: Set the cursor position in the window
Syntax : SET_CURSOR(file_var, row, col, status)
Input/Output Parameters :
[in] file_var : FILE
[in] row : INTEGER
[in] col : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• Sets the current cursor of the specified file that is open to a window so subsequent writes will
start in the specified position.
• file_var must be open to a window.
• A row value of 1 indicates the top row of the window. A col value of 1 indicates the left-most
column of the window.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: DEF_WINDOW Built-In Procedure
Example: Refer to the following sections for detailed program examples:
A-299
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Section B.2 , "Copying Path Variables" (CPY_PTH.KL)
Section B.6 , "Path Variables and Condition Handlers Program" (PTH_MOVE.KL)
Section B.13 , "Using the DISCTRL_ALPHA Built-in" (DCALP_EX.KL)
A.20.11
SET_EPOS_REG Built-In Procedure
Purpose: Stores an XYZWPREXT value in the specified register
Syntax : SET_EPOS_REG(register_no, posn, status <, group_no>)
Input/Output Parameters :
[in] register_no : INTEGER
[in] posn : XYZWPREXT
[out] status : INTEGER
[in] group_no :INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the position register in which to store the value.
• The position data is set in XYZWPREXT representation.
• status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.
• If group_no is omitted, the default group for the program is assumed. Data for other groups
is not changed.
• If group_no is specified, it must be in the range of 1 to the total number of groups defined on
the controller.
See Also: SET_POS_REG, SET_JPOS_REG Built-In Procedures, GET_POS_REG,
GET_JPOS_REG Built-In Functions
Example: The following example sets the extended position for the specified register.
SET_EPOS_REG Built-In Procedure
PROGRAM spe
%environment REGOPE
VAR
cur_pos: XYZWPREXT
A-300
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
posget: XYZWPREXT
status: INTEGER
v_mask, g_mask: INTEGER
reg_no: INTEGER
BEGIN
reg_no = 1
cur_pos = CURPOS(v_mask,g_mask)
SET_EPOS_REG(reg_no,cur_pos,status)
posget = GET_POS_REG(reg_no,status)
END spe
A.20.12
SET_EPOS_TPE Built-In Procedure
Purpose: Stores an XYZWPREXT value in the specified position in the specified teach pendant
program
Syntax: SET_EPOS_TPE (open_id, position_no, posn, status <,group_no>)
Input/Output Parameters :
[in] open_id : INTEGER
[in] position_no : INTEGER
[in] posn : XYZWPREXT
[out] status : INTEGER
[in] group_no : INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• open_id specifies the opened teach pendant program. A program must be opened before calling
this built-in.
• position_no specifies the position in the program in which to store the value.
• A motion instruction must already exist that uses the position_no or the position will not be
used by the teach pendant program.
• The position data is set in XYZWPREXT representation with no conversion.
• status explains the status of the attempted operation. If not equal to 0, then an error has occurred.
• If group_no is omitted, the default group for the program is assumed. Data for other groups
is not changed.
A-301
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• If group_no is specified, it must be in the range of 1 to the total number of groups defined on
the controller.
A.20.13
SET_FILE_ATR Built-In Procedure
Purpose: Sets the attributes of a file before it is opened
Syntax : SET_FILE_ATR(file_id, atr_type <,atr_value>)
Input/Output Parameters :
[in] file_id: FILE
[in] atr_type : INTEGER expression
[in] atr_value : INTEGER expression
%ENVIRONMENT Group :PBCORE
Details:
• file_id is the file variable that will be used in the OPEN FILE, WRITE, READ, and/or CLOSE
FILE statements.
• atr_type specifies the attribute type to set. The predefined constants as specified in Table 7-2
should be used.
• atr_value is optional depending on the attribute type being set.
XML Related
Purpose: Sets the attributes file to XML before it is opened
Syntax : SET_FILE_ATR(xml_file, ATR_XML)
Input/Output Parameters :
[in] xml_file: FILE
[in] ATR_XML: INTEGER expression
Details:
• xml_file is the file variable that will be used in the OPEN FILE, WRITE, READ, and/or CLOSE
FILE statements.
• ATR_XML specifies the attribute type to set. The predefined constants as specified in Table
7-2 should be used.
A-302
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• The file must then be opened as a RO file. You cannot do any other XMl operations until the
file has been opened.
See Also: SET_PORT_ATR Built-In Function, Section Section 7.3.1 ., ‘‘Setting File Attributes" and
Section Section 9.5 , ‘‘Formatting XML Input"
Example: Refer to Section Section 9.5 , ‘‘Formatting XML Input"
A.20.14
SET_FILE_POS Built-In Procedure
Purpose: Sets the file position for the next READ or WRITE operation to take place in the specified
file to the value of the new specified file position
Syntax : SET_FILE_POS(file_id, new_file_pos, status)
Input/Output Parameters :
[in] file_id : FILE
[in] new_file_pos : INTEGER expression
[out] status : INTEGER variable
%ENVIRONMENT Group :FLBT
Details:
• The file associated with file_id must be opened and uncompressed on either the FROM or RAM
disks. Otherwise, the program is aborted with an error.
• new_file_pos must be in the range of -1 to the number of bytes in the file.at_eof : specifies that
the file position is to be set at the end of the file. at_sof : specifies that the file position is to be
set at the start of the file.
— Any other value causes the file to be set the specified number of bytes from the beginning of
the file.
• status is set to 0 if the new_file_pos is between -1 and the number of bytes in the file, indicating
the file position was successfully set. If not equal to 0, then an error occurred.
See Also: Chapter 7 FILE INPUT/OUTPUT OPERATIONS
Example: The following example opens the filepos.dt data file, sets the file position from a directory,
reads the positions from the file, and stores the positions in the PATH, my_path .
SET_FILE_POS Built-In Procedure
OPEN FILE file_id (’RW’,’filepos.dt’)
A-303
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
FOR i = 1 TO PATH_LEN(my_path) DO
SET_FILE_POS(file_id, pos_dir[i], status)
IF status = 0 THEN
READ file_id (temp_pos)
my_path[i].node_pos = temp_pos
ENDIF
ENDFOR
A.20.15
SET_INT_REG Built-In Procedure
Purpose: Stores an integer value in the specified register
Syntax : SET_INT_REG(register_no, int_value, status)
Input/Output Parameters :
[in] register_no : INTEGER
[in] int_value : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the register into which int_value will be stored.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: GET_INT_REG, GET_REAL_REG, SET_REAL_REG Built-in Procedures
Example: Refer to Section B.5 , "Using Register Built-ins" (REG_EX.KL), for a detailed program
example.
A.20.16
SET_JPOS_REG Built-In Procedure
Purpose: Stores a JOINTPOS value in the specified register
Syntax : SET_JPOS_REG(register_no, jpos, status<, group_no>)
Input/Output Parameters :
[in] register_no : INTEGER
A-304