FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual - page 17
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
A.10.4
INDEX Built-In Function
Purpose: Returns the index for the first character of the first occurrence of a specified STRING
argument in another specified STRING argument. If the argument is not found, a 0 value is returned.
Syntax : INDEX(main, find)
Function Return Type :INTEGER
Input/Output Parameters:
[in] main :STRING
[in] find :STRING
%ENVIRONMENT Group :SYSTEM
Details:
• The returned value is the index position in main corresponding to the first character of the first
occurrence of find or 0 if find does not occur in main .
Example: The following example uses the INDEX built-in function to look for the first occurrence
of the string ‘‘Old’’ in part_desc .
INDEX Built-In Function
class_key = ’Old’
part_desc = ’Refurbished Old Part’
IF INDEX(part_desc, class_key) > 0 THEN
in_class = TRUE
ENDIF
A.10.5
INI_DYN_DISB Built-In Procedure
Purpose: Initiates the dynamic display of a BOOLEAN variable. This procedure displays elements of
a STRING ARRAY depending of the current value of the BOOLEAN variable.
Syntax : INI_DYN_DISB (b_var, window_name, field_width, attr_mask, char_size, row, col,
interval, strings, status)
Input/Output Parameters :
A-181
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] b_var :BOOLEAN
[in] window_name :STRING
[in] field_width :INTEGER
[in] attr_mask :INTEGER
[in] char_size :INTEGER
[in] row :INTEGER
[in] col :INTEGER
[in] interval :INTEGER
[in] strings :ARRAY OF STRING
[out] status :INTEGER
%ENVIRONMENT Group :UIF
Details:
• The dynamic display is initiated based on the value of b_var . If b_var is FALSE, strings[1] is
displayed; if b_var is TRUE, strings[2] is displayed. If b_var is uninitialized, a string of *’s is
displayed. Both b_var and strings must be static (not local) variables.
• window_name must be a previously defined window name. See Section 7.10.1 . and Section
7.10.2 for predefined window names.
• If field_width is non-zero, the display is extended with blanks if the element of strings[n] is
shorter than this specified width. The area is cleared when the dynamic display is canceled.
• attr_mask is a bit-wise mask that indicates character display attributes. This should be one
of the following constants:
0 :Normal
1 :Bold (Supported only on the CRT)
2 :Blink (Supported only on the CRT)
4 :Underline
8 :Reverse video
• To have multiple display attributes, use the OR operator to combine the constant attribute values
together. For example, to have the text displayed as bold and underlined use 1 OR 4.
A-182
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• char_size specifies whether data is to be displayed in normal, double-wide, or double-high,
double-wide sizes. This should be one of the following constants:
0 :Normal
1 :Double-wide (Supported only on the CRT)
2 :Double-high, double-wide
• row and col specify the location in the window in which the data is to be displayed.
• interval indicates the minimum time interval, in milliseconds, between updates of the display.
This must be greater then zero. The actual time might be greater since the task that formats
the display runs at a low priority.
• strings[n] contains the text that will be displayed.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: CNC_DYN_DISB built-in procedure
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.10.6
INI_DYN_DISE Built-In Procedure
Purpose: Initiates the dynamic display of an INTEGER variable. This procedure displays elements of
a STRING ARRAY depending of the current value of the INTEGER variable.
Syntax : INI_DYN_DISE (e_var, window_name, field_width, attr_mask, char_size, row, col,
interval, strings, status)
Input/Output Parameters :
[in] e_var :INTEGER
[in] window_name :STRING
[in] field_width :INTEGER
[in] attr_mask :INTEGER
[in] char_size :INTEGER
[in] row :INTEGER
[in] col :INTEGER
[in] interval :INTEGER
A-183
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] strings :ARRAY OF STRING
[out] status :INTEGER
%ENVIRONMENT Group :UIF
Details:
• The dynamic display is initiated based on the value of e_var . If e_var has a value of n,
strings[n+1] is displayed; if e_var has a negative value, or a value greater than or equal to the
length of the array of strings , a string of ’?’s is displayed. Both e_var and string s must be
static (not local) variables.
• Refer to the INI_DYN_DISB built-in procedure for a description of the other parameters listed
above.
See Also: CNC_DYN_DISE built-in procedure
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.10.7
INI_DYN_DISI Built-In Procedure
Purpose: Initiate the dynamic display of an INTEGER variable in a specified window.
Syntax : INI_DYN_DISI(i_var, window_name, field_width, attr_mask, char_size, row, col, interval,
buffer_size, format, status)
Input/Output Parameters:
[in] i_var :INTEGER
[in] window_name :STRING
[in] field_width :INTEGER
[in] attr_mask :INTEGER
[in] char_size :INTEGER
[in] row :INTEGER
[in] col :INTEGER
[in] interval :INTEGER
[in] buffer_size :INTEGER
A-184
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] format :STRING
[out] status :INTEGER
%ENVIRONMENT Group :UIF
Details:
•
i_var is the integer whose dynamic display is to be initiated.
•
If field_width is non-zero, the display is extended with blanks if i_var is shorter than this specified
width. The area is cleared when the dynamic display is canceled.
•
buffer_size is not implemented.
•
format is used to print out the variable. This can be passed as a literal enclosed in single quotes.
The format string begins with a % and ends with a conversion character. Between the % and the
conversion character there can be, in order:
— Flags (in any order), which modify the specification:
- : specifies left adjustment of this field.
+ : specifies that the number will always be printed with a sign.
0 specifies padding a numeric field width with leading zeroes.
— A number that specifies the minimum field width. The converted argument will be printed in
a field at least this wide. If necessary it will be padded on the left (or right, if left adjustment
is called for) to make up the field width.
— A period, which separates the field width from the precision.
— A number, the precision, that specifies the maximum number of characters to be printed from
a string, or the number of digits after the decimal point of a floating-point value, or the
minimum number of digits for an integer.
The format specifier must contain one of the conversion characters in Table A-12 .
Table
A-12.
Conversion Characters
Character
Argument Type; Printed As
d
INTEGER; decimal number
o
INTEGER; unsigned octal notation (without a leading zero).
x,X
INTEGER; unsigned hexadecimal notation (without a leading 0x or 0X), using
abcdef or ABCDEF for 10, ..., 15.
u
INTEGER; unsigned decimal notation.
s
STRING; print characters from the string until end of string or the number of
characters given by the precision.
A-185
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Table
A-12.
Conversion Characters (Cont’d)
Character
Argument Type; Printed As
f
REAL; decimal notation of the form [-]mmm.dddddd, where the number of d’s
is given by the precision. The default precision is 6; a precision of 0 suppresses
the decimal point.
e,E
REAL; decimal notation of the form [-]m.dddddde+-xx or [-]m.ddddddE+-xx, where
the number of d’s is given by the precision. The default precision is 6; a precision of
0 suppresses the decimal point.
g,G
REAL; %e or %E is used if the exponent is less than -4 or greater than or equal to
the precision; otherwise %f is used. Trailing zeros and a trailing decimal pointer
are not printed.
%
no argument is converted; print a %.
• Refer to the INI_DYN_DISB built-in procedure for a description of the other parameters listed
above.
See Also: CNC_DYN_DISI, DEF_WINDOW Built-In Procedure
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.10.8
INI_DYN_DISP Built-In Procedure
Purpose: Initiates the dynamic display of a value of a port in a specified window, based on the
port type and port number.
Syntax : INI_DYN_DISP (port_type, port_no, window_name, field_width, attr_mask, char_size,
row, col, interval, strings, status)
Input/Output Parameters :
[in] port_type :INTEGER
[in] port_no :INTEGER
[in] window_name :STRING
[in] field_width :INTEGER
[in] attr_mask :INTEGER
[in] char_size :INTEGER
A-186
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] row :INTEGER
[in] col :INTEGER
[in] interval :INTEGER
[in] strings :ARRAY OF STRING
[out] status :INTEGER
Details:
• port_type specifies the type of port to be displayed. Codes are defined in FROM: KLIOTYPS.KL.
— If the port_type is a BOOLEAN port (e.g., DIN), If the is FALSE, strings[1] is displayed; If
variable is TRUE, strings[2] is displayed.
— If the port_type is an INTEGER port (e.g., GIN), if the value of the port is n, strings[n+1 ]
will be displayed. If the value of the port is greater than or equal to the length of the array of
strings, a string of ’?’s is displayed.
• port_no specifies the port number to be displayed.
• Refer to the INI_DYN_DISB built-in procedure for a description of other parameters listed above.
See Also: CNC_DYN_DISP Built-In procedure
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.10.9
INI_DYN_DISR Built-In Procedure
Purpose: Initiates the dynamic display of a REAL variable in a specified window.
Syntax : INI_DYN_DISR(r_var, window_name, field_width, attr_mask, char_size, row, col, interval,
buffer_size, format, status)
Input/Output Parameters:
[in] r_var :REAL
[in] window_name :STRING
[in] field_width :INTEGER
[in] attr_ mask :INTEGER
[in] char_size :INTEGER
A-187
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] row :INTEGER
[in] col :INTEGER
[in] interval :INTEGER
[in] buffer_size :INTEGER
[in] format :STRING
[out] status :INTEGER
%ENVIRONMENT Group :UIF
Details:
• r_var is the REAL variable whose dynamic display is to be initiated.
• If field_width is non-zero, the display is extended with blanks if r_var is shorter than this
specified width. The area is cleared when the dynamic display is canceled.
• Refer to the INI_DYN_DISI built-in procedure for a description of other parameters listed above.
See Also: CNC_DYN_DISR Built-In Procedure
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.10.10
INI_DYN_DISS Built-In Procedure
Purpose: Initiates the dynamic display of a STRING variable in a specified window.
Syntax : INI_DYN_DISS(s_var, window_name, field_width, attr_mask, char_size, row, col, interval,
buffer_size, format, status)
Input/Output Parameters:
[in] s_var :STRING
[in] window_name :STRING
[in] field_width :INTEGER
[in] attr_ mask :INTEGER
[in] char_size :INTEGER
[in] row :INTEGER
A-188
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] col :INTEGER
[in] interval :INTEGER
[in] buffer_size :INTEGER
[in] format :STRING
[out] status :INTEGER
%ENVIRONMENT Group :UIF
Details:
• s_var is the STRING variable whose dynamic display is to be initiated.
• If field_width is non-zero, the display is extended with blanks if s_var is shorter than this
specified width. The area is cleared when the dynamic display is canceled.
• Refer to the INI_DYN_DISI built-in procedure for a description of other parameters listed above.
See Also: CNC_DYN_DISS, INI_DYN_DISI Built-In Procedures
Example: Refer to Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL), for a
detailed program example.
A.10.11
INIT_QUEUE Built-In Procedure
Purpose: Sets a queue variable entry to have no entries in the queue
Syntax : INIT_QUEUE(queue)
Input/Output Parameters:
[out] queue_t :QUEUE_TYPE
%ENVIRONMENT Group : PBQMGR
Details:
• queue_t is the queue to be initialized
See Also: GET_QUEUE, MODIFY_QUEUE Built-In Procedures, QUEUE_TYPE Data Type,
Section 15.8 ,"Using Queues for Task Communication"
Example: The following example initializes a queue called job_queue.
A-189
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
INIT_QUEUE Built-In Procedure
PROGRAM init_queue_x
%environment PBQMGR
VAR
job_queue FROM globals: QUEUE_TYPE
BEGIN
INIT_QUEUE(job_queue)
END init_queue_x
A.10.12
INIT_TBL Built-In Procedure
Purpose: Initializes a table on the teach pendant
Syntax : INIT_TBL(dict_name, ele_number, num_rows, num_columns, col_data, inact_array,
change_array, value_array, vptr_array, table_data, status)
Input/Output Parameters:
[in] dict_name :STRING
[in] ele_number :INTEGER
[in] num_rows :INTEGER
[in] num_columns :INTEGER
[in] col_data :ARRAY OF COL_DESC_T
[in] inact_array :ARRAY OF BOOLEAN
[in] change_array :ARRAY OF ARRAY OF BOOLEAN
[in] value_array :ARRAY OF STRING
[out] vptr_array :ARRAY OF ARRAY OF INTEGER
[in,out] table_data :XWORK_T
[out] status :INTEGER
%ENVIRONMENT Group :UIF
Details:
• The INIT_TBL and ACT_TBL built-in routines should only be used instead of DISCTRL_TBL
A-190
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
if special processing needs to be done with each keystroke or if function key processing needs to
be done without exiting the table menu.
•
INIT_TBL must be called before using the ACT_TBL built-in.INIT_TBL does not need to be
called if using the DISCTRL_TBL built-in.
•
dict_name is the four-character name of the dictionary containing the table header.
•
ele_number is the element number of the table header.
•
num_rows is the number of rows in the table.
•
num_columns is the number of columns in the table.
•
col_data is an array of column descriptor structures, one for each column in the table. It contains
the following fields:
— item_type : Data type of values in this column. The following data type constants are defined:
TPX_INT_ITEM — Integer type
TPX_REL_ITEM — Real type
TPX_FKY_ITEM — Function key enumeration type
TPX_SUB_ITEM — Subwindow enumeration type
TPX_KST_ITEM — KAREL string type
TPX_KSL_ITEM — KAREL string label type (can select, not edit)
TPX_KBL_ITEM — KAREL boolean type
TPX_BYT_ITEM — Byte type
TPX_SHT_ITEM — Short type
TPX_PBL_ITEM — Port boolean type
TPX_PIN_ITEM — Port integer type
— start_col : Starting character column (1..40) of the display field for this data column.
— field_width : Width of the display field for this data column.
— num_ele : Dictionary element used to display values for certain data types. The format of
the dictionary elements for these data types are as follows:
- TPX_FKY_ITEM: The enumerated values are placed on function key labels. There can
be up to 2 pages of function key labels, for a maximum of 10 labels. Each label is a string
of up to 8 characters. However, the last character of a label which is followed by another
label should be left blank or the two labels will run together.
A-191
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
- A single dictionary element defines all of the label values. Each value must be put on
a separate line using &new_line. The values are assigned to the function keys F1..F5,
F6..F10 and the numeric values 1..10 in sequence. Unlabeled function keys should be left
blank. If there are any labels on the second function key page, F6..F10, the labels for keys
5 and 10 must have the character ‘‘>’’ in column 8. If there are no labels on keys F6..F10,
lines do not have to be specified for any key label after the last non-blank label.
Example:
$ example_fkey_label_c
"" &new_line
"F2" &new_line
"F3" &new_line
"F4" &new_line
"F5 >" &new_line
"F6" &new_line
"F7" &new_line
"" &new_line
"" &new_line
" >"
-
-- TPX_SUB_ITEM: The enumerated values are selected from a subwindow on the
display device. There can be up to 5 subwindow pages, for a maximum of 35 values.
Each value is a string of up to 16 characters.
- A sequence of consecutive dictionary elements, starting with enum_dict, define the
values. Each value must be put in a separate element, and must not end with &new_line.
The character are assigned the numeric values 1..35 in sequence. The last dictionary
element must be "\a".
Example:
$ example_sub_win_enum_c
"Red"
$
"Blue"
$
"Green"
$
"Yellow"
$
"\a"
- TPX_KBL_ITEM, TPX_PBL_ITEM: The ‘‘true’’ and ‘‘false’’ values are placed on
function key labels F4 and F5, in that order. Each label is a string of up to 8 characters.
However, the last character of the ‘‘true’’ label should be left blank or the two labels
will run together.
A-192
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
- A single dictionary element the label values. Each value must be put on a separate line
using &new_line, with the ‘‘false’’ value first.
Example:
$ example_boolean_c
"OFF" &new_line
"ON"
— enum_dict : Dictionary name used to display data types TPX_FKY_ITEM, TPX_SUB_ITEM,
TPX_KBL_ITEM, or TPX_PBL_ITEM
— format_spec : Format string is used to print out the data value. The format string contains a
format specifier. The format string can also contain any desired characters before or after
the format specifier. The format specifier itself begins with a % and ends with a conversion
character. Between the % and the conversion character there may be, in order:
- Flags (in any order), which modify the specification:
- : specifies left adjustment of this field.
+ : specifies that the number will always be printed with a sign.
space : if the first character is not a sign, a space will be prefixed.
0 : specifies padding a numeric field width with leading zeroes.
- A number that specifies the minimum field width. The converted argument will be
printed in a field at least this wide. If necessary it will be padded on the left (or right, if
left adjustment is called for) to make up the field width.
- A period, which separates the field width from the precision.
- A number, the precision, that specifies the maximum number of characters to be printed
from a string, or the number of digits after the decimal point of a floating-point value, or
the minimum number of digits for an integer.
•
The format specifier must contain one of the conversion characters in the following table:
Table
A-13.
Conversion Characters
Character
Argument Type; Printed As
d
INTEGER; decimal number.
o
INTEGER; unsigned octal notation (without a leading zero).
x,X
INTEGER; unsigned hexadecimal notation (without a leading 0x or 0X), using abcdef
or ABCDEF for 10, ..., 15.
u
INTEGER; unsigned decimal notation.
A-193
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Table
A-13.
Conversion Characters (Cont’d)
Character
Argument Type; Printed As
s
STRING; print characters from the string until end of string or the number of
characters given by the precision.
f
REAL; decimal notation of the form [-]mmm.dddddd, where the number of d’s is
given by the precision. The default precision is 6; a precision of 0 suppresses the
decimal point.
e,E
REAL; decimal notation of the form [-]m.dddddde+-xx or [-]m.ddddddE+-xx, where
the number of d’s is given by the precision. The default precision is 6; a precision of
0
g,G
REAL; %e or %E is used if the exponent is less than -4 or greater than or equal to
the precision; otherwise %f is used. Trailing zeros and a trailing decimal pointer
are not printed.
%
no argument is converted; print a %.
Example: "%d" or "%-10s"
The format specifiers which can be used with the data types specified in the item_type field
in col_data are as follows:
TPX_INT_ITEM %d, %o, %x, %X, %u
TPX_REL_ITEM %f, %e, %E, %g, %G
TPX_FKY_ITEM %s
TPX_SUB_ITEM %s
TPX_KST_ITEM %s
TPX_KSL_ITEM %s
TPX_KBL_ITEM %s
TPX_BYT_ITEM %d, %o, %x, %X, %u, %c
TPX_SHT_ITEM %d, %o, %x, %X, %u
TPX_PBL_ITEM %s
TPX_PIN_ITEM %d, %o, %x, %X, %u
— max_integer : Maximum value if data type is TPX_INT_ITEM, TPX_BYT_ITEM, or
TPX_SHT_ITEM.
A-194
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
— min_integer : Minimum value if data type is TPX_INT_ITEM, TPX_BYT_ITEM, or
TPX_SHT_ITEM.
— max_real : Maximum value for reals.
— min_real : Minimum value for reals.
— clear_flag : If data type is TPX_KST_ITEM, 1 causes the field to be cleared before entering
characters and 0 causes it not to be cleared.
— lower_case : If data type is TPX_KST_ITEM, 1 allows the characters to be input to the string
in upper or lower case and 0 restricts them to upper case.
•
inact_array is an array of booleans that corresponds to each column in the table.
— You can set each boolean to TRUE which will make that column inactive. This means
the column cannot be cursored to.
— The array size can be less than or greater than the number of items in the table.
— If inact_array is not used, then an array size of 1 can be used, and the array does not need to
be initialized.
•
change_array is a two dimensional array of booleans that corresponds to formatted data item in
the table.
— If the corresponding value is set, then the boolean will be set to TRUE, otherwise it is set to
FALSE. You do not need to initialize the array.
— The array size can be less than or greater than the number of data items in the table.
— If change_array is not used, then an array size of 1 can be used.
•
value_array is an array of variable names that correspond to the columns of data in the table.
Each variable name can be specified as ’[prog_name]var_name’.
— [prog_name] specifies the name of the program that contains the specified variable. If
[prog_name] is not specified, then the current program being executed is used.
— var_name must refer to a static, global program variable.
— var_name can contain node numbers, field names, and/or subscripts.
— Each of these named variables must be a KAREL array of length num_rows . Its data type
and values should be consistent with the value of the item_type field in col_data for the
corresponding column, as follows:
- TPX_INT_ITEM: ARRAY OF INTEGER containing the desired values.
- TPX_REL_ITEM: ARRAY OF REAL containing the desired values.
- TPX_FKY_ITEM: ARRAY OF INTEGER with values referring to items in the
dictionary element specified in the enum_ele field in col_data . There can be at most 2
function key pages, or 10 possible function key enumeration values.
- TPX_SUB_ITEM: ARRAY OF INTEGER with values referring to items in the
dictionary element specified in the enum_ele field in col_data . There can be at most 28
subwindow enumeration values.
A-195
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
- TPX_KST_ITEM: ARRAY OF STRING containing the desired values.
- TPX_KST_ITEM: ARRAY OF STRING containing the desired values.
- TPX_KSL_ITEM: ARRAY OF STRING containing the desired values. These values
cannot be edited by the user. If one is selected, ACT_TBL will return.
- TPX_KBL_ITEM: ARRAY OF BOOLEAN containing the desired values. The
dictionary element specified by the enum_ele field in col_data should have exactly two
elements, with the false item first and the true item second. TPX_BYT_ITEM: ARRAY
OF BYTE containing the desired values. "--" TPX_SHT_ITEM: ARRAY OF SHORT
containing the desired values. "--" TPX_PBL_ITEM: ARRAY OF STRING containing
the names of the ports, for example ‘‘DIN[5]’’. "--" TPX_PIN_ITEM: ARRAY OF
STRING containing the names of the ports, for example ‘‘GOUT[3]’’.
- TPX_BYT_ITEM: ARRAY OF BYTE containing the desired values.
- TPX_SHT_ITEM: ARRAY OF SHORT containing the desired values.
- TPX_PBL_ITEM: ARRAY OF STRING containing the names of the ports, for example
‘‘DIN[5]’’.
- TPX_PIN_ITEM: ARRAY OF STRING containing the names of the ports, for example
‘‘GOUT[3]’’.
•
vptr_array is an array of integers that corresponds to each variable name in value_array. Do
not change this data; it is used internally.
•
table_data is used to display and control the table. Do not change this data; it is used internally.
•
status explains the status of the attempted operation. If not equal to 0, then an error occurred.
Example: In this example, TPXTABEG.TX is loaded as ‘XTAB’ on the controller. TPEXTBL
calls INIT_TBL to initialize a table with five columns and four rows. It calls ACT_TBL in a
loop to read and process each key pressed.
INIT_TBL Built-In Procedure
----------------------------------------------
TPXTABEG.TX
----------------------------------------------
$title
&reverse "DATA Test Schedule" &standard &new_line
"E1: " &new_line
"
W(mm) TEST C(%%) G(123456) COLOR"
^1
?2
$function_keys
"f1"
&new_line
"f2"
&new_line
"f3"
&new_line
"f4"
&new_line
" HELP >" &new_line
"f6"
&new_line
A-196
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
"f7"
&new_line
"f8"
&new_line
"f9"
&new_line
"f10
>"
$help_text "Help text
goes
here...
"$enum1
"" &new_line
"" &new_line
"TRUE" &new_line
"FALSE" &new_line
""
$enum2
"Red"
$
"Blue"
$
"Green"
$
"Yellow"
$
"Brown"
$
"Pink"
$
"Mauve"
$
"Black"
$
"
"
----------------------------------------------
TPEXTBL.KL
----------------------------------------------
PROGRAM tpextbl
%ENVIRONMENT uif
%INCLUDE FROM:\klevccdf
%INCLUDE FROM:\klevkeysVAR
dict_name: STRING[6]
ele_number: INTEGER
num_rows: INTEGER
num_columns: INTEGER
col_data: ARRAY[5] OF COL_DESC_T
inact_array: ARRAY[5] OF BOOLEAN
change_array: ARRAY[4,5] OF BOOLEAN
value_array: ARRAY[5] OF STRING[26]
vptr_array: ARRAY[4,5] OF INTEGER
table_data: XWORK_T
status: INTEGER
A-197
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
action: INTEGER
def_item: INTEGER
term_char: INTEGER
attach_sw: BOOLEAN
save_action: INTEGER
done: BOOLEAN
value1: ARRAY[4]
OF INTEGER
value2: ARRAY[4]
OF INTEGER
value3: ARRAY[4]
OF REAL
value4: ARRAY[4]
OF STRING[10]
value5: ARRAY[4]
OF INTEGER
BEGIN
def_item = 1
value_array[1] =
’value1’
value_array[2] =
’value2’
value_array[3] =
’value3’
value_array[4] =
’value4’
value_array[5] =
’value5’
value1[1] = 21
value1[2] = 16
value1[3] = 1
value1[4] = 4
value2[1] = 3
value2[2] = 2
value2[3] = 3
value2[4] = 2
value3[1] = -13
value3[2] = 4.1
value3[3] = 23.9
value3[4] = -41
value4[1] = ’XXX---’
value4[2] = ’--X-X-’
value4[3] = ’XXX-XX’
value4[4] = ’-X-X--’
value5[1] = 1
value5[2] = 1
value5[3] = 2
value5[4] = 3
inact_array[1] = FALSE
inact_array[2] = FALSE
inact_array[3] = FALSE
inact_array[4] = FALSE
inact_array[5] = FALSE
col_data[1].item_type =
TPX_INT_ITEM
col_data[1].start_col =
6
col_data[1].field_width
= 4
col_data[1].format_spec
= ’%3d’
A-198
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
col_data[1].max_integer = 99
col_data[1].min_integer = -99
col_data[2].item_type = TPX_FKY_ITEM
col_data[2].start_col = 12
col_data[2].field_width = 5
col_data[2].format_spec = ’%s’
col_data[2].enum_ele = 3
-- enum1 element
number
col_data[2].enum_dict = ’XTAB’
col_data[3].item_type = TPX_REL_ITEM
col_data[3].start_col = 18
col_data[3].field_width = 5
col_data[3].format_spec = ’%3.1f’
col_data[4].item_type = TPX_KST_ITEM
col_data[4].start_col = 26
col_data[4].field_width = 6
col_data[4].format_spec = ’%s’
col_data[5].item_type = TPX_SUB_ITEM
col_data[5].start_col = 34
col_data[5].field_width = 6
col_data[5].format_spec = ’%s’
col_data[5].enum_ele = 4
-- enum2 element
number
col_data[5].enum_dict = ’XTAB’
dict_name = ’XTAB’
ele_number = 0
-- title element number
num_rows = 4
num_columns = 5
def_item = 1
attach_sw = TRUE
INIT_TBL(dict_name, ele_number, num_rows, num_columns,
col_data,
inact_array, change_array, value_array, vptr_array,
table_data, status)
IF status <> 0 THEN
WRITE(’INIT_TBL status = ’, status, CR);
ELSE
def_item = 1
-- Initial display of table
ACT_TBL(ky_disp_updt, def_item, table_data, term_char,
attach_sw, status)
IF status <> 0 THEN
WRITE(CR, ’ACT_TBL status = ’, status)
ENDIF
ENDIF
IF status = 0 THEN
-- Loop until a termination key is selected.
done = FALSE
action = ky_reissue -- read new key
WHILE NOT done DO
A-199
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
-- Read new key, act on it, and return it
ACT_TBL(action, def_item, table_data, term_char,
attach_sw, status)save_action = action
action = ky_reissue -- read new key
-- Debug only
WRITE TPERROR (CHR(cc_home) + CHR(cc_clear_win))
-- Process termination keys.
SELECT (term_char) OF
CASE (ky_select, ky_new_menu):
done = TRUE;
CASE (ky_f1):
-- Perform F1
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F1 pressed’)
CASE (ky_f2):
-- Perform F2
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F2 pressed’)
CASE (ky_f3):
-- Perform F3
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F3 pressed’)
CASE (ky_f4):
-- Perform F4
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F4 pressed’)
CASE (ky_f5):
-- Perform F5 Help
action = ky_help
CASE (ky_f6):
-- Perform F6
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F6 pressed’)
CASE (ky_f7):
-- Perform F7
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F7 pressed’)
CASE (ky_f8):
-- Perform F8
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F8 pressed’)
CASE
(ky_f9):
-- Perform F9
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F9 pressed’)
CASE (ky_f10):
-- Perform F10
A-200
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F10 pressed’)
CASE (ky_undef):
-- Process special keys.
SELECT (save_action) OF
CASE (ky_f1_s):
-- Perform Shift F1
SET_CURSOR(TPERROR, 1, 1, status)
WRITE TPERROR (’F1 shifted pressed’)
ELSE:
ENDSELECT
ELSE:
action = term_char
-- act on this key
ENDSELECT
ENDWHILE
IF term_char <> ky_new_menu THEN
-- Cancel the dynamic display
ACT_TBL(ky_cancel, def_item, table_data, term_char,
attach_sw, status)
ENDIF
ENDIF
END tpextbl
A.10.13
IN_RANGE Built-In Function
Purpose: Returns a BOOLEAN value indicating whether or not the specified position argument can
be reached by a group of axes
Syntax : IN_RANGE(posn)
Function Return Type :BOOLEAN
Input/Output Parameters:
[in] posn : XYZWPREXT
%ENVIRONMENT Group :SYSTEM
Details:
• The returned value is TRUE if posn is within the work envelope of the group of axes; otherwise,
FALSE is returned.
• The current $UFRAME and $UTOOL are applied to posn .
A-201
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
See Also: CHECK_EPROS Built-in procedure
Example: The following example checks to see if the new position is in the work envelope before
moving the TCP to it.
IN_RANGE Built-In Function
IF IN_RANGE(part_slot) THEN
SET_POS_REG(1, part_slot, status)
move_to_pr —— Call TP program to move to PR[1]
ELSE WRITE(’I can’t get there!’,CR)
ENDIF
A.10.14
INSERT_NODE Built-In Procedure
Purpose: Inserts an uninitialized node in the specified PATH argument preceding the specified
path node number
Syntax : INSERT_NODE(path_var, node_num, status)
Input/Output Parameters:
[in] path_var :PATH
[in] node_num :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :PATHOP
Details:
• node_num specifies the index number of the path node before which the new uninitialized node is
to be inserted.
• The new node can be assigned values by directly referencing its NODEDATA structure.
• All nodes following the inserted node are renumbered.
• Valid node_num values are in the range node_num => 1 and node_num <= PATH_LEN( path_va
r ).
• If node_num is not a valid node number, status is returned with an error.
• If the program does not have enough RAM for an INSERT_NODE request, an error will occur.
• If the program is paused, the INSERT_NODE request is NOT retried.
See Also: DELETE_NODE, APPEND_NODE Built-in Procedures
A-202
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Example: In the following example, the PATH_LEN built-in is used to set the variable length equal
to the number of nodes in path_var. INSERT_NODE inserts a new path node before the last node
in path_var.
INSERT_NODE Built-In Procedure
length = PATH_LEN(path_var)
INSERT_NODE(path_var, length, status)
A.10.15
INSERT_QUEUE Built-In Procedure
Purpose: Inserts an entry into a queue if the queue is not full
Syntax : INSERT_QUEUE(value, sequence_no, queue, queue_data, status)
Input/Output Parameters:
[in] value :INTEGER
[in] sequence_no :INTEGER
[in,out] queue_t :QUEUE_TYPE
[in,out] queue_data :ARRAY OF INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :PBQMGR
Details:
• value specifies the value to be inserted into the queue, queue_t.
• sequence_no specifies the sequence number of the entry before which the new entry is to be
inserted.
• queue_t specifies the queue variable for the queue.
• queue_data specifies the array used to hold the data in the queue. The length of this array
determines the maximum number of entries in the queue.
• status is returned with 61002, ‘‘Queue is full,’’ if there is no room for the entry in the queue, with
61003, ‘‘Bad sequence no,’’ if the specified sequence number is not in the queue.
See Also: MODIFY_QUEUE, APPEND_QUEUE, DELETE_QUEUE Built-In Procedures, Section
15.8 , "Using Queues for Task Communication"
A-203
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Example: In the following example, the routine ins_in_queue adds an entry value ) to a queue (
queue_t and queue_data ) following the specified entry sequence_no ); it returns TRUE if this was
successful; otherwise it returns FALSE.
INSERT_QUEUE Built-In Procedure
PROGRAM ins_queue_x
%environment PBQMGR
ROUTINE ins_in_queue(value: INTEGER;
sequence_no: INTEGER;
queue_t: QUEUE_TYPE;
queue_data: ARRAY OF INTEGER): BOOLEAN
VAR
status: INTEGER
BEGIN
INSERT_QUEUE(value, sequence_no, queue_t, queue_data, status)
return (status = 0)
END ins_in_queue
BEGIN
END ins_queue_x
A.10.16
INTEGER Data Type
Purpose: Defines a variable, function return type, or routine parameter as INTEGER data type
Syntax : INTEGER
Details:
• An INTEGER variable or parameter can assume whole number values in the range -2147483648
through +2147483646.
• INTEGER literals consist of a series of digits, optionally preceded by a plus or minus sign.
They cannot contain decimal points, commas, spaces, dollar signs ($), or other punctuation
characters. (See Table A-14 )
Table A-14. Valid and Invalid INTEGER Literals
Valid
Invalid
Reason
1
1.5
Decimal point not allowed (must be a whole number)
–2500450
-2,500,450
Commas not allowed
+65
+6 5
Spaces not allowed
• If an INTEGER argument is passed to a routine where a REAL parameter is expected, it is
treated as a REAL and passed by value.
A-204
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• Only INTEGER expressions can be assigned to INTEGER variables, returned from INTEGER
function routines, or passed as arguments to INTEGER parameters.
• Valid INTEGER operators are:
— Arithmetic operators (+, -, *, /, DIV, MOD)
— Relational operators (>, >=, =, <>, <, <=)
— Bitwise operations (AND, OR, NOT)
See Also: Chapter 5 ROUTINES , for more information on passing by value, Chapter 7 FILE
INPUT/OUTPUT OPERATIONS , for more information on format specifiers
Example: Refer to Appendix B for detailed program examples.
A.10.17
INV Built-In Function
Purpose: Used in coordinate frame transformations with the relative position operator (:) to
determine the coordinate values of a POSITION in a frame that differs from the frame in which
that POSITION was recorded
Syntax : INV(pos) Function Return Type :POSITION
Input/Output Parameters:
[in] pos :POSITION
%ENVIRONMENT Group :SYSTEM
Details:
• The returned value is the inverse of the pos argument.
• The configuration of the returned POSITION will be that of the pos argument.
Example: The following example uses the INV built-in to determine the POSITION of part_pos with
reference to the coordinate frame that has rack_pos as its origin. Both part_pos and rack_pos were
originally taught and recorded in User Frame. The robot is then instructed to move to that position.
INV Built-In Function
PROGRAM p_inv
VAR
rack_pos, part_pos, p1 : POSITION
BEGIN
p1 = INV(rack_pos):part_pos
SET_POS_REG(1, p1, status)
move_to_pr1 -— Call TP program to move to PR[1]
END p_inv
A-205
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.10.18
IO_MOD_TYPE Built-In Procedure
Purpose: Allows a KAREL program to determine the type of module in a specified rack/slot
Syntax : IO_MOD_TYPE(rack_no, slot_no, mod_type, status)
Input/Output Parameters:
[in] rack_no :INTEGER
[in] slot_no :INTEGER
[out] mod_type :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :IOSETUP
Details:
• rack_no is the rack containing the port module. For process I/O boards, this is zero; for
Allen-Bradley and Genius ports, this is 16.
• slot_no is the slot containing the port module. For process I/O boards, this is the position of the
board in the SLC-2 chain.
• mod_type is the module type.
6 A16B-2202-470
7 A16B-2202-472
8 A16B-2202-480
• status is returned with zero if the parameters are valid and there is a module or board with the
specified rack/slot number as follows:
Example: The following example returns to the caller the module in the specified rack and slot
number.
IO_MOD_TYPE Built-In Procedure
PROGRAM iomodtype
%ENVIRONMENT IOSETUP
ROUTINE get_mod_type(rack_no: INTEGER;
slot_no: INTEGER;
mod_type: INTEGER): INTEGER
A-206
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
VAR
status: INTEGER
BEGIN
IO_MOD_TYPE(rack_no, slot_no, mod_type, status)
RETURN (status)
END get_mod_type
BEGIN
END iomodtype
A.10.19
IO_STATUS Built-In Function
Purpose: Returns an INTEGER value indicating the success or type of failure of the last operation
on the file argument
Syntax : IO_STATUS(file_id)
Function Return Type :INTEGER
Input/Output Parameters:
[in] file_id :FILE
%ENVIRONMENT Group :PBCORE
Details:
• IO_STATUS can be used after an OPEN FILE, READ, WRITE, CANCEL FILE, or CLOSE
FILE statement. Depending on the results of the operation, it will return 0 if successful or one
of the errors listed in the application-specific FANUC Robotics Setup and Operations Manual .
Some of the common errors are shown in Table A-15 .
Table
A-15.
IO_STATUS Errors
0
Last operation on specified file was successful
2021
End of file for RAM disk device
10006
End of file for floppy device
12311
Uninitialized variable
12324
Illegal open mode string
12325
Illegal file string
12326
File var is already used
12327
Open file failed
A-207
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Table
A-15.
IO_STATUS Errors (Cont’d)
12328
File is not opened
12329
Cannot write the variable
12330
Write file failed
12331
Cannot read the variable
12332
Read data is too short
12333
Illegal ASCII string for read
12334
Read file failed
12335
Cannot open pre_defined file
12336
Cannot close pre_defined file
12338
Close file failed
12347
Read I/O value failed
12348
Write I/O value failed
12358
Timeout at read request
12359
Read request is nested
12367
Bad base in format
• Use READ file_id(cr) to clear any IO_STATUS error.
• If file_id does not correspond to an opened file or one of the pre-defined ‘‘files’’ opened to the
respective CRT/KB, teach pendant, and vision windows, the program is aborted with an error.
Example: Refer to Section B.12 , "Displaying a List From a Dictionary File" (DCLIST_EX.KL), for
a detailed program example.
A.11
- J - KAREL LANGUAGE DESCRIPTION
A.11.1
J_IN_RANGE Built-In Function
Purpose: Returns a BOOLEAN value indicating whether or not the specified joint position argument
can be reached by a group of axes
Syntax : J_IN_RANGE(posn)
Function Return Type :BOOLEAN
Input/Output Parameters:
[in] posn :JOINTPOS
A-208
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
%ENVIRONMENT Group :SYSTEM
Details:
• The returned value is TRUE if posn is within the work envelope; otherwise, FALSE is returned.
See Also: IN_RANGE Built-in Function, CHECK_EPROS Built-in procedure
A.11.2
JOINTPOS Data Type
Purpose: Defines a variable, function return type, or routine parameter as JOINTPOS data type.
Syntax : JOINTPOS<n> <IN GROUP[m]>
Details:
• A JOINTPOS consists of a REAL representation of the position of each axis of the group,
expressed in degrees or millimeters (mm).
• n specifies the number of axes, with 9 as the default. The size in bytes is 4 + 4 * n.
• A JOINTPOS may be followed by IN GROUP[m], where m indicates the motion group with
which the data is to be used. The default is the group specified by the %DEFGROUP directive
or 1.
• CNV_REL_JPOS and CNV_JPOS_REL Built-ins can be used to access the real values.
• A JOINTPOS can be assigned to other positional types. Note that some motion groups, for
example single axis positioners, have no XYZWPR representation. If you attempt to assign a
JOINTPOS to a XYZWPR or POSITION type for such a group, a run-time error will result.
Example: Refer to the following sections for detailed program examples:
Section B.5 ,"Using Register Built-ins" (REG_EX.KL)
Section B.6 , "Path Variables and Condition Handlers Program" (PTH_MOVE.KL)
Section B.8 , "Generating and Moving Along a Hexagon Path" (GEN_HEX.KL)
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.11.3
JOINT2POS Built-In Function
Purpose: This routine is used to convert joint angles (in_jnt) to a Cartesian position (out_pos) by
calling the forward kinematics routine.
A-209
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Syntax : JOINT2POS (in_jnt - Joint angles can be converted to Cartesian, uframe, utool, config_ref,
out_pos, wjnt_cfg, ext_ang, and status).
Input/Output Parameters:
[in] in_jnt :Jointpos
[in] uframe :POSITION
[in] utool :POSITION
[in] config_ref :INTEGER
[out] out_pos :POSITION
[out] wjnt_cfg :CONFIG
[out] ext_ang :ARRAY OF REAL
[out] status :INTEGER
%ENVIRONMENT Group :MOTN
Details:
• The input in_jnt is defined as the joint angles to be converted to the Cartesian position.
• The input uframe is the user frame for the Cartesian position.
• The input utool is defined as the corresponding tool frame.
• The input config_ref is an integer representing the type of solution desired. The values listed
below are valid. Also, the pre-defined constants in the parentheses can be used and the values can
be added as required. One example includes: config_ref = HALF_SOLN + CONFIG_TCP.
— 0 :(FULL_SOLN) = Default
— 1 : (HALF_SOLN) = Wrist joint (xyz456). This value does not calculate/use wpr.
— 2 :(CONFIG_TCP) = The Wrist Joint Config (up/down) is based on the fixed wrist.
— 4 :(APPROX_SOLN) = Approximate solution. This value reduce calculation time for
some robots.
— 8 :(NO_TURNS) = Ignore wrist turn numbers. Use the closest path for joints 4, 5 and 6
(uses ref_jnt).
— 16 :(NO_M_TURNS) = Ignore major axis (J1 only) turn number. Use the closest path.
• The output out_pos is the Cartesian position corresponding to the input joint angles.
• The output wjnt_cfg is the wrist joint configuration. The value will be output when config_ref
corresponds to HALF_SOLN.
A-210
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• The output ext_ang contains the values of the joint angles for the extended axes if they exist.
• The output status explains the status of the attempted operation. If it is not equal to 0, then an
error has occurred.
A.12
- K - KAREL LANGUAGE DESCRIPTION
A.12.1
KCL Built-In Procedure
Purpose: Sends the KCL command specified by the STRING argument to KCL for execution.
Syntax : KCL (command, status)
Input/Output Parameters :
[in] command :STRING
[out] status :INTEGER
%ENVIRONMENT Group :kclop
Details:
• command must contain a valid KCL command.
• command cannot exceed 126 characters.
• Program execution waits until execution of the KCL command is completed or until an error is
detected.
• All KCL commands are performed as if they were entered at the command level, with the
exception of destructive commands, such as CLEAR ALL, for which no confirmation is required.
• status indicates whether the command was executed successfully.
• If a KCL command file is being executed and $STOP_ON_ERR is FALSE, the KCL built-in will
continue to run to completion. The first error detected will be returned or a 0 if no errors occurred.
See Also: KCL_NO_WAIT, KCL_STATUS Built-In Procedures
Example: The following example will show programs and wait until finished. Status will be the
outcome of this operation.
KCL Built-In Procedure
PROGRAM kcl_test
VAR
command :STRING[20]
status :INTEGER
BEGIN
A-211