FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual - page 16
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[out] slot_no :INTEGER
[out] phy_port_type :INTEGER
[out] phy_port_no :INTEGER
[out] n_ports :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :IOSETUP
Details:
• log_port_type specifies the code for the type of port whose assignment is being accessed. Codes
are defined in FR:KLIOTYPS.KL.
• log_port_no specifies the number of the port whose assignment is being accessed.
• rack_no is returned with the rack containing the port module. For process I/O boards,
memory-image, and dummy ports, this is zero; for Allen-Bradley ports, this is 16.
• phy_port_type is returned with the type of port assigned to. Often this will be the same as
log_port_type. Exceptions are if log_port_type is a group type (io_gpin or io_gpout) or a port is
assigned to memory-image or dummy ports.
• phy_port_no is returned with the number of the port assigned to. If log_port_type is a group,
this is the port number for the least-significant bit of the group.
• n_ports is returned with the number of physical ports assigned to the logical port. This will be
1 in all cases except when log_port_type is a group type. In this case, n_ports indicates the
number of bits in the group.
• status is returned with zero if the parameters are valid and the specified port is assigned.
Otherwise, it is returned with an error code.
Example: The following example returns to the caller the module rack and slot number, port_number,
and number of bits assigned to a specified group input port. A boolean is returned indicating whether
the port is assigned to a DIN port. If the port is not assigned, a non-zero status is returned.
GET_PORT_ASG Built-In Procedure
PROGRAM getasgprog
%ENVIRONMENT IOSETUP
%INCLUDE FR:\kliotyps
ROUTINE get_gin_asg(gin_port_no: INTEGER;
rack_no: INTEGER;
slot_no: INTEGER;
frst_port_no: INTEGER;
n_ports: INTEGER;
asgd_to_din: BOOLEAN): INTEGER
VAR
A-150
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
phy_port_typ: INTEGER
status: INTEGER
BEGIN
GET_PORT_ASG(io_gpin, gin_port_no, rack_no, slot_no,
phy_port_typ, frst_port_no, n_ports, status)
IF status <> 0 THEN
RETURN (status)
ENDIF
asgd_to_din = (phy_port_typ = io_din)
END get_gin_asg
BEGIN
END getasgprog
A.8.6
GET_PORT_ATR Built-In Function
Purpose: Gets an attribute from the specified port
Syntax : GET_PORT_ATR(port_id, atr_type, atr_value)
Function Return Type :INTEGER
Input/Output Parameters :
[in] port_id :INTEGER
[in] atr_type :INTEGER
[out] atr_value :INTEGER
%ENVIRONMENT Group :FLBT
Details:
• port_id specifies which port is to be queried. Use one of the following predefined constants:
port_1
port_2
port_3
port_4
port_5
A-151
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• atr_type specifies the attribute whose current setting is to be returned. Use one of the following
predefined constants:
atr_readahd :Read ahead buffer
atr_baud :Baud rate
atr_parity :Parity
atr_sbits :Stop bit
atr_dbits :Data length
atr_xonoff :Xon/Xoff
atr_eol :End of line
atr_modem :Modem line
• atr_value receives the current value for the specified attribute.
• GET_PORT_ATR returns the status of this action to the port.
See Also: SET_PORT_ATR Built-In Function, Chapter 7 FILE INPUT/OUTPUT OPERATIONS
Example: The following example sets up the port to a desired configuration, if it is not already set to
the specified configuration.
GET_PORT_ATR Built-In Function
PROGRAM port_atr
%ENVIRONMENT FLBT
VAR
stat:
INTEGER
atr_value: INTEGER
BEGIN
-- sets read ahead buffer to desired value, if not
already correct
stat=GET_PORT_ATR(port_2,atr_readahd,atr_value)
IF(atr_value <> 2) THEN
stat=SET_PORT_ATR(port_2,atr_readahd,2) --set to
256 bytes
ENDIF
-- sets the baud rate to 9600, if not already set
stat=GET_PORT_ATR(port_2,atr_baud,atr_value)
IF(atr_value <> BAUD_9600) THEN
stat=SET_PORT_ATR(port_2,atr_baud,baud_9600)
ENDIF
-- sets parity to even, if not already set
stat=GET_PORT_ATR(port_2,atr_parity,atr_value)
IF(atr_value <> PARITY_EVEN) THEN
stat=SET_PORT_ATR(port_2,atr_parity,PARITY_EVEN)
A-152
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
ENDIF
-- sets the stop bit to 1, if not already set
stat=GET_PORT_ATR(port_2,atr_sbits,atr_value)
IF(atr_value <> SBITS_1) THEN
stat=SET_PORT_ATR(port_2,atr_sbits,SBITS_1)
ENDIF
-- sets the data bit to 5, if not already set
stat=GET_PORT_ATR(port_2,atr_dbits,atr_value)
IF(atr_value <> DBITS_5) THEN
stat=SET_PORT_ATR(port_2,atr_dbits,DBITS_5)
ENDIF
-- sets xonoff to not used, if not already set
stat=GET_PORT_ATR(port_2,atr_xonoff,atr_value)
IF(atr_value <> xf_not_used) THEN
stat=SET_PORT_ATR(port_2,atr_xonoff,xf_not_used)
ENDIF
-- sets end of line marker, if not already set
stat=GET_PORT_ATR(port_2,atr_eol,atr_value)
IF(atr_value <> 65) THEN
stat=SET_PORT_ATR(port_2,atr_eol,65)
ENDIF
END port_atr
A.8.7
GET_PORT_CMT Built-In Procedure
Purpose: Allows a KAREL program to determine the comment that is set for a specified logical port
Syntax : GET_PORT_CMT(port_type, port_no, comment_str, status)
Input/Output Parameters :
[in] port_type :INTEGER
[in] port_no :INTEGER
[out] comment_str :STRING
[out] status :INTEGER
%ENVIRONMENT Group :IOSETUP
Details:
• port_type specifies the code for the type of port whose comment is being returned. Codes are
defined in FR:KLIOTYPS.KL.
A-153
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• port_no specifies the port number whose comment is being set.
• comment_str is returned with the comment for the specified port. This should be declared as a
STRING with a length of at least 16 characters.
• status is returned with zero if the parameters are valid and the comment is returned for the
specified port.
See Also: GET_PORT_VAL, GET_PORT_MOD, SET_PORT_CMT, SET_PORT_VAL,
SET_PORT_MOD Built-in Procedures.
A.8.8
GET_PORT_MOD Built-In Procedure
Purpose: Allows a KAREL program to determine what special port modes are set for a specified
logical port
Syntax : GET_PORT_MOD(port_type, port_no, mode_mask, status)
Input/Output Parameters :
[in] port_type :INTEGER
[in] port_no :INTEGER
[out] mode_mask :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :IOSETUP
Details:
• port_type specifies the code for the type of port whose mode is being returned. Codes are defined
in FR:KLIOTYPS.KL.
• port_no specifies the port number whose mode is being set.
• mode_mask is returned with a mask specifying which modes are turned on. The following
modes are defined:
1 :reverse mode
Sense of the port is reversed; if the port is set to TRUE, the physical output is set to FALSE. If the
port is set to FALSE, the physical output is set to TRUE. If a physical input is TRUE, when the port
is read, FALSE is returned. If a physical input is FALSE, when the port is read, TRUE is returned.
2 :complementary mode
A-154
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
The logical port is assigned to two physical ports whose values are complementary. In this case,
port_no must be an odd number. If port n is set to TRUE, then port n is set to TRUE and port n +
1 is set to FALSE. If port n is set to FALSE, then port n is set to FALSE and port n + 1 is set to
TRUE. This is effective only for output ports.
• status is returned with zero if the parameters are valid and the specified mode is returned for the
specified port.
Example: The following example gets the mode(s) for a specified port.
GET_PORT_MOD_Built-In Procedure
PROGRAM getmodprog
%ENVIRONMENT IOSETUP
%INCLUDE FR:\kliotyps
ROUTINE get_mode( port_type: INTEGER;
port_no:
INTEGER;
reverse:
BOOLEAN;
complementary: BOOLEAN): INTEGER
VAR
mode: INTEGER
status: INTEGER
BEGIN
GET_PORT_MOD(port_type, port_no, mode,
status)
IF (status <>0) THEN
RETURN (status)
ENDIF
IF (mode AND 1) <> 0 THEN
reverse = TRUE
ELSE
reverse = FALSE
ENDIF
IF (mode AND 2) <> 0 THEN
complementary = TRUE
ELSE
complementary = FALSE
ENDIF
RETURN (status)
END get_mode
BEGIN
END getmodprog
A.8.9
GET_PORT_SIM Built-In Procedure
Purpose: Gets port simulation status
A-155
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Syntax : GET_PORT_SIM(port_type, port_no, simulated, status)
Input/Output Parameters:
[in] port_type :INTEGER
[in] port_no :INTEGER
[out] simulated :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :IOSETUP
Details:
• port_type specifies the code for the type of port to get. Codes are defined in FRS:KLIOTYPS.KL.
• port_no specifies the number of the port whose simulation status is being returned.
• simulated returns TRUE if the port is being simulated, FALSE otherwise.
• status is returned with zero if the port is valid.
See Also: GET_PORT_MOD, SET_PORT_SIM, SET_PORT_MOD Built-in Procedures.
A.8.10
GET_PORT_VAL Built-In Procedure
Purpose: Allows a KAREL program to determine the current value of a specified logical port
Syntax : GET_PORT_VAL(port_type, port_no, value, status)
Input/Output Parameters :
[in] port_type :INTEGER
[in] port_no :INTEGER
[out] value :STRING
[out] status :INTEGER
%ENVIRONMENT Group :IOSETUP
Details:
• port_type specifies the code for the type of port whose comment is being returned. Codes are
defined in FR:KLIOTYPS.KL.
A-156
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• port_no specifies the port number whose comment is being set.
• value is returned with the current value (status) of the specified port. For BOOLEAN port types,
(i.e. DIN), this will be 0 = OFF, or 1 = ON.
• status is returned with zero if the parameters are valid and the comment is returned for the
specified port.
See Also: GET_PORT_CMT, GET_PORT_MOD, SET_PORT_CMT, SET_PORT_VAL,
SET_PORT_MOD Built-in Procedures.
A.8.11
GET_POS_FRM Built-In Procedure
Purpose: Gets the uframe number and utool number of the specified position in the specified teach
pendant program.
Syntax : GET_POS_FRM(open_id, position_no, gnum, ufram_no, utool_no, status)
Input/Output Parameters :
[in] open_id :INTEGER
[in] position_no :INTEGER
[in] gnum :INTEGER
[out] ufram_no :INTEGER
[out] utool_no :INTEGER
[out] status :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 teach pendant program.
• gnum specifies the group number of position.
• ufram_no is returned with the frame number of position_no.
• utool_no is returned with the tool number of position_no.
• If the specified position, position_no , is uninitialized, the status is set to 17038, "Uninitialized
TPE position."
• status indicates the status of the attempted operation. If not equal to 0, then an error occurred.
A-157
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
See Also: GET_POS_TYP, CHECK_EPOS.
A.8.12
GET_POS_REG Built-In Function
Purpose: Gets an XYZWPR value from the specified register
Syntax : GET_POS_REG(register_no, status <,group_no>)
Function Return Type :XYZWPREXT
Input/Output Parameters:
[in] register_no :INTEGER
[out] status :INTEGER
[in] group_no :INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the position register to get.
• If group_no is omitted, the default group for the program is assumed.
• If group_no is specified, it must be in the range of 1 to the total number of groups defined on
the controller.
• GET_POS_REG returns the position in XYZWPREXT format. Use POS_REG_TYPE to
determine the position representation.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: GET_JPOS_REG, SET_JPOS_REG, SET_POS_REG, GET_REG Built-in Procedures.
Example: Refer to Section B.5 ,"Using Register Built-ins" (REG_EX.KL), for a detailed program
example.
A.8.13
GET_POS_TPE Built-In Function
Purpose: Gets an XYZWPREXT value from the specified position in the specified teach pendant
program
Syntax : GET_POS_TPE(open_id, position_no, status <, group_no>)
Function Return Type :XYZWPREXT
A-158
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Input/Output Parameters:
[in] open_id : INTEGER
[in] position_no : INTEGER
[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 to get.
• No conversion is done for the position representation. The positional data must be in XYZWPR
or XYZWPREXT, otherwise, an error status is returned. Use GET_POS_TYP to get the position
representation.
• If the specified position in the program is uninitialized, the returned XYZWPR value is
uninitialized and status is set to 17038, "Uninitialized TPE Position."
• If group_no is omitted, the default group for the program is assumed.
• If group_no is specified, it must be in the range of 1 to the total number of groups defined on
the controller.
• status explains the status of the attempted operation. If not equal to 0, then an error has occurred.
See Also: GET_JPOS_TPE, SET_JPOS_TPE, SET_POS_TPE, GET_POS_TYP Built-in Procedures.
Example: Refer to Section B.14 , "Applying Offsets to a Copied Teach Pendant Program"
(CPY_TP.KL), for a detailed program example.
A.8.14
GET_POS_TYP Built-In Procedure
Purpose: Gets the position representation of the specified position in the specified teach pendant
program
Syntax : GET_POS_TYP(open_id, position_no, group_no, posn_typ, num_axs, status)
Input/Output Parameters:
[in] open_id :INTEGER
[in] position_no :INTEGER
A-159
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[in] group_no :INTEGER
[out] posn_typ :INTEGER
[out] num_axs :INTEGER
[out] status :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.
• group_no specifies the group number.
• Position type is returned by posn_typ. posn_typ is defined as follows:2 :XYZWPR6
:XYZWPREXT9 :JOINTPOS
• If it is in joint position, the number of the axis in the representation is returned by num_axs .
• If the specified position in the program is uninitialized, then a status is set to 17038, "Unintialized
TPE Position."
• status explains the status of the attempted operation. If not equal to 0, then an error has occurred.
Example: Refer to Section B.14 , "Applying Offsets to a Copied Teach Pendant Program"
(CPY_T.KL), for a detailed program example.
A.8.15 GET_PREG_CMT Built-In-Procedure
Purpose: To retrieve the comment information of a KAREL position register based on a given
register number.
Syntax: GET_PREG_CMT (register_no, comment_string, status)
Input/Output Parameters:
[in] register_no: INTEGER
[out] comment_string: STRING
[out] status: INTEGER
%ENVIORNMENT group: REGOPE
Details:
A-160
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• Register_no specifies which position register to retrieve the comments from. The comment of
the given position register is returned in the comment_string.
A.8.16
GET_QUEUE Built-In Procedure
Purpose: Retrieves the specified oldest entry from a queue
Syntax : GET_QUEUE(queue, queue_data, value, status, sequence_no)
Input/Output Parameters:
[in,out] queue_t :QUEUE_TYPE
[in,out] queue_data :ARRAY OF INTEGER
[out] value :INTEGER
[out] sequence_no :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :PBQMGR
Details:
• queue_t specifies the queue variable for the queue from which the value is to be obtained.
• queue_data specifies the array variable with the queue data.
• value is returned with the oldest entry obtained from the queue.
• sequence_no is returned with the sequence number of the returned entry.
• status is returned with the zero if an entry is successfully obtained from the queue. Otherwise, a
value of 61002, ‘‘Queue is empty,’’ is returned.
See Also: MODIFY_QUEUE Built-In Procedure, Section 15.8 , "Using Queues for Task
Communication
Example: In the following example the routine get_nxt_err returns the oldest entry from the error
queue, or zero if the queue is empty.
GET_QUEUE Built-In Procedure
PROGRAM get_queue_x
%environment PBQMGR
VAR
error_queue FROM global_vars: QUEUE_TYPE
error_data FROM global_vars: ARRAY[100] OF INTEGER
A-161
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
ROUTINE get_nxt_err: INTEGER
VAR
status: INTEGER
value: INTEGER
sequence_no: INTEGER
BEGIN
GET_QUEUE(error_queue, error_data, value, sequence_no, status)
IF (status = 0) THEN
RETURN (value)
ELSE
RETURN (0)
ENDIF
END get_nxt_err
BEGIN
END get_queue_x
A.8.17
GET_REG Built-In Procedure
Purpose: Gets an INTEGER or REAL value from the specified register
Syntax : GET_REG(register_no, real_flag, int_value, real_value, status)
Input/Output Parameters:
[in] register_no :INTEGER
[out] real_flag :BOOLEAN
[out] int_value :INTEGER
[out] real_value :REAL
[out] status :INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the register to get.
• real_flag is set to TRUE and real_value to the register content if the specified register has a real
value. Otherwise, real_flag is set to FALSE and int_value is set to the contents of the register.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
A-162
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Example: Refer to Section B.5 ,"Using Register Built-ins" (REG_EX.KL), for a detailed program
example.
A.8.18
GET_REG_CMT
Purpose: To retrieve the comment information of a KAREL register based on a given register number.
Syntax: GET_REG_CMT (register_no, comment_string, status)
Input/Output Parameters:
[in] register_no: INTEGER
[out] comment_string: STRING
[out] status: INTEGER
%ENVIRONMENT group: REGOPE
Details:
• Register_no specifies which register to retrieve the comments from. The comment of the given
register is returned in comment_string.
A.8.19 GET_SREG_CMT Builtin Procedure
Purpose: Gets the comment from the specified string register.
Syntax : GET_SREG_CMT(register_no, comment, status)
Input/Output Parameters:
[in] register_no :INTEGER
[out] comment :STRING[254]
[out] status :INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the string register to get.
• comment contains the comment of the specified string register.
A-163
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: GET_STR_REG, SET_STR_REG, SET_SREG_CMT Built-in Procedures.
A.8.20 GET_STR_REG Built-In Procedure
Purpose: Gets the value from the specified string register.
Syntax : GET_STR_REG(register_no, value, status)
Input/Output Parameters:
[in] register_no :INTEGER
[out] value :STRING[254]
[out] status :INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the string register to get.
• value contains the value of the specified string register.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: GET_SREG_CMT, SET_STR_REG, SET_SREG_CMT Built-in Procedures.
A.8.21 GET_TIME Built-In Procedure
Purpose: Retrieves the current time (in integer representation) from within the KAREL system
Syntax : GET_TIME(i)
Input/Output Parameters:
[out] i :INTEGER
%ENVIRONMENT Group :TIM
Details:
• i holds the INTEGER representation of the current time stored in the KAREL system. This value
is represented in 32-bit INTEGER format as follows:
A-164
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Table
A-11.
INTEGER Representation of Current Time
31-25
24-21
20-16
year
month
day
15-11
10-5
4-0
hour
minute
second
• The contents of the individual fields are as follows:
— DATE:
Bits 31-25 — Year since 1980
Bits 24-21 — Month (1-12)
Bits 20-16 — Day of the month
— TIME:
Bits 15-11 — Number of hours (0-23)
Bits 10-5 — Number of minutes (0-59)
Bits 4-0 — Number of 2-second increments (0-29)
• INTEGER values can be compared to determine if one time is more recent than another.
• Use the CNV_TIME_STR built-in procedure to convert the INTEGER into the ‘‘DD-MMM-YYY
HH:MM:SS’’ STRING format.
See Also: CNV_TIME_STR Built-In Procedure
Example: Refer to Section B.9 , "Using the File and Device Built-ins" (FILE_EX.KL), for a detailed
program example.
A.8.22
GET_TPE_CMT Built-in Procedure
Purpose: This built-in provides the ability for a KAREL program to read the comment associated
with a specified position in a teach pendant program.
Syntax : GET_TPE_CMT(open_id, pos_no, comment, status)
Input/Output Parameters:
[in] open_id :INTEGER
[in] pos_no :INTEGER
A-165
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[out] comment :STRING
[out] status :INTEGER
%ENVIRONMENT Group :TPE
Details:
• open_id specifies the open_id returned from a previous call to OPEN_TPE.
• pos_no specifies the number of the position in the TPP program to get a comment from.
• comment is associated with specified positions and is returned with a zero length string if the
position has no comment. If the string variable is too short for the comment, an error is returned
and the string is not changed.
• status indicates zero if the operation was successful, otherwise an error code will be displayed.
See Also: SET_TPE_CMT and OPEN_TPE for more Built-in Procedures.
A.8.23
GET_TPE_PRM Built-in Procedure
Purpose: Gets the values of the parameters when parameters are passed in a TPE CALL or MACRO
instruction.
Syntax : GET_TPE_PRM(param_no, data_type, int_value, real_value, str_value, status)
Input/Output Parameters:
[in] param_no :INTEGER
[out] data_type :INTEGER
[out] int_value :INTEGER
[out] real_value :REAL
[out] str_value :STRING
[out] status :INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• param_no indicates the number of the parameter. There can be at most ten parameters.
• data_type indicates the data type for the parameter, as follows:
A-166
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
— 1 : INTEGER
— 2 : REAL
— 3 : STRING
• int_value is the value of the parameter if the data_type is INTEGER.
• real_value is the value of the parameter if the data_type is REAL.
• str_value is the value of the parameter if the data_type is STRING.
• status explains the status of the attempted operation. If not equal to 0, then an error has occurred.
• If the parameter designated by param_no does not exist, a status of 17042 is returned, which is the
error message: "ROUT-042 WARN TPE parameters do not exist." If this error is returned, confirm
the param_no and the parameter in the CALL or MACRO command in the main TPE program.
See Also: Application-Specific FANUC Robotics Setup and Operations Manual, for information on
using parameters in teach pendant CALL or MACRO instructions.
Example: The following example shows the implementation of a macro (Send Event) with CALL
parameters that are retrieved by a KAREL program that uses the GET_TPE_PRM built-in.
GET_TPE_PRM Built-In Procedure
Macro table entry for the Send Event macro:
109 [Send Event
] [SENDEVNT]--[
0]
Teach pendant program, TEST1.TP, which uses the Send Event
macro:
1:
! Send Event 7
2:
! Wait for PC answer
3:
! Answer in REG 5
4:
Send Event(7,1,5)
5:
IF R[5]<9999,JMP LBL[10]
6:
! Error in macro
7:
!
8:
LBL[10]
Teach pendant program SENDEVNT.TP, which implements the
Send Event macro by calling the GESNDEVT KAREL
program and passing the CALL parameters from Send Event:
1:
!Send Event Macro
2:
CALL GESNDEVT(AR[1],AR[2],AR[3])
Snippet of the KAREL program GESNDEVT.KL, which gets the
parameter information using the GET_TPE_PRM
built-in:
PROGRAM GESNDEVT
BEGIN
-- Send Event(event_no [,wait_sw [,status_reg]] )
-- get parameter 1 (mandatory parameter)
A-167
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Get_tpe_prm(1, data_type, event_no,real_value,string_value,status)
IF status<>0 THEN
-- 17042 "ROUT-042 TPE parameters do not exist"
POST_ERR(status, ’’, 0, er_abort)
ELSE
IF data_type <> PARM_INTEGER THEN
-- make sure parm is an integer
POST_ERR(er_pceventer, ’1’, 0, er_abort)
ELSE
IF (event_no < MIN_EVENT) OR (event_no > MAX_EVENT) THEN
POST_ERR(er_illevent, ’’, 0, er_abort)
ENDIF
ENDIF
ENDIF
-- get second parameter (optional)
Get_tpe_prm(2, data_type, wait_sw,real_value,string_value,status)
IF status<>0 THEN
IF status = ER17042 THEN
-- "ROUT-142 Parameter doesn’t exist"
wait_sw = 0
-- DEFAULT no wait
ELSE
POST_ERR(status, ’’, 0, er_warn) -- other error
ENDIF
A.8.24
GET_TSK_INFO Built-In Procedure
Purpose: Get the value of the specified task attribute
Syntax : GET_TSK_INFO(task_name, task_no, attribute, value_int, value_str, status)
Input/Output Parameters:
[in,out] task_name :STRING
[in,out] task_no :INTEGER
[in] attribute :INTEGER
[out] value_int :INTEGER
[out] value_str :STRING
[out] status :INTEGER
%ENVIRONMENT Group :PBCORE
A-168
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Details:
•
task_name is the name of the task of interest. task_name is used as input only if task_no is
uninitialized or set to 0, otherwise, task_name is considered an output parameter.
•
task_no is the task number of interest. If task_no is uninitialized or set to 0, it is returned as
an output parameter.
•
attribute is the task attribute whose value is to be returned. It will be returned in value_int unless
otherwise specified. The following attributes are valid:
TSK_HOLDCOND : Task hold conditions
TSK_LINENUM : Current executing line number
TSK_LOCKGRP : Locked group
TSK_MCTL : Motion controlled groups
TSK_NOABORT : Ignore abort request
TSK_NOBUSY : Busy lamp off
TSK_NOPAUSE : Ignore pause request
TSK_NUMCLDS : Number of child tasks
TSK_PARENT : Parent task number
TSK_PAUSESFT : Pause on shift release
TSK_PRIORITY : Task priority
TSK_PROGNAME : Current program name returned in value_str
TSK_PROGTYPE : Program type - refer to description below
TSK_ROUTNAME : Current routine name returned in value_str
TSK_STACK : Stack size
TSK_STATUS : Task status — refer to description below
TSK_STEP : Single step task
TSK_TIMESLIC : Time slice duration in ms
TSK_TPMOTION : TP motion enable
TSK_TRACE : Trace enable
A-169
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
TSK_TRACELEN : Length of trace array
• TSK_STATUS is the task status: The return values are:
PG_RUNACCEPT : Run request has been accepted
PG_ABORTING : Abort has been accepted
PG_RUNNING : Task is running
PG_PAUSED : Task is paused
PG_ABORTED : Task is aborted
• TSK_PROGTYPE is the program type. The return values are:
PG_NOT_EXEC : Program has not been executed yet
PG_MNEMONIC : Teach pendant program is or was executing
PG_AR_KAREL : KAREL program is or was executing
• status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.
See Also: Chapter 15 MULTI-TASKING
Example: See examples in Chapter 15 MULTI-TASKING
A.8.25 GET_USEC_SUB Built-In Procedure
Purpose: Returns an INTEGER value indicating the elapsed time in microseconds (1/1,000,000).
Syntax: us_delta = GET_USEC_SUB(us2, us1)
Function Return Type :INTEGER
Input/Output Parameters :
[in] us2: INTEGER
[in] us1: INTEGER
%ENVIRONMENT Group: TIM
Details:
• us2 is the second time returned from GET_USEC_TIM.
• us1 is the first time returned from GET_USEC_TIM.
A-170
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• The returned value is the INTEGER representation of the elapsed time us2 - us1 in microseconds.
• This is intended to measure fast operations. The result will wrap after 2 minutes and will no
longer be valid.
Example: The following example measures the amount of time in microseconds to increment a
number.
Figure A-3. GET_USEC_SUB Built-In Function
i = 0
us1 = GET_USEC_TIM
i = i + 1
us_delta = GET_USEC_SUB(GET_USEC_TIM, us1)
WRITE (’Time to increment a number: ’, us_delta, ’ us’, CR)
A.8.26 GET_USEC_TIM Built-In Function
Purpose: Returns an INTEGER value indicating the current time in microseconds (1/1,000,000) from
within the KAREL system.
Syntax: us = GET_USEC_TIM
Function Return Type: INTEGER
Input/Output Parameters:
None
%ENVIRONMENT Group: TIM
Details:
• The returned value is the INTEGER representation of the current time in microseconds stored in
the KAREL system.
• This function is used with the GET_USEC_SUB built-in function to determine the elapsed time
of an operation.
A.8.27
GET_VAR Built-In Procedure
Purpose: Allows a KAREL program to retrieve the value of a specified variable
Syntax : GET_VAR(entry, prog_name, var_name, value, status)
A-171
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Input/Output Parameters:
[in,out] entry :INTEGER
[in] prog_name :STRING
[in] var_name :STRING
[out] value :Any valid KAREL data type except PATH
[out] status :INTEGER
%ENVIRONMENT Group :SYSTEM
Details:
•
entry returns the entry number in the variable data table of var_name in the device directory
where var_name is located. This variable should not be modified.
•
prog_name specifies the name of the program that contains the specified variable. If prog_name is
blank, it will default to the current task name being executed. Set the prog_name to ‘*SYSTEM*’
to get a system variable. prog_name can also access a system variable on a robot in a ring.
•
var_name must refer to a static, program variable.
•
var_name can contain node numbers, field names, and/or subscripts.
•
If both var_name and value are ARRAYs, the number of elements copied will equal the size of
the smaller of the two arrays.
•
If both var_name and value are STRINGs, the number of characters copied will equal the size of
the smaller of the two strings.
•
If both var_name and value are STRUCTUREs of the same type, value will be an exact copy
of var_name .
•
value is the value of var_name .
•
status explains the status of the attempted operation. If not equal to 0, then an error occurred.
•
If the value of var_name is uninitialized, then value will be set to uninitialized and status will
be set to 12311.
•
The designated names of all the robots can be found in the system variable $PH_MEMBERS[].
This also include information about the state of the robot. The ring index is the array index for
this system variable. KAREL users can write general purpose programs by referring to the names
and other information in this system variable rather than explicit names.
See Also: SET_VAR Built-In Procedure, Internet Options Manual for information on accessing
system variables on a robot in a ring.
A-172
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Caution
Using GET_VAR to modify system variables could cause unexpected results.
Example 1:To access $TP_DEFPROG on the MHROB03 robot in a ring, see Accessing
$TP_DEFPROG on MHROB03 .
Accessing $TP_DEFPROG on MHROB03
GET_VAR(entry, ‘\\MHROB03\*system*’, ‘$TP_DEFPROG’, strvar, status)
Example 2: GET_VAR Built-In Procedure displays two programs, util_prog and task . The program
util_prog uses a FOR loop to increment the value of the INTEGER variable num_of_parts .
util_prog also assigns values to the ARRAY part_array . The program task uses two GET_VAR
statements to retrieve the values of num_of_parts and part_array[3] . The value of num_of_parts
is assigned to the INTEGER variable count and part_array[3] is assigned to the STRING variable
part_name . The last GET_VAR statement places the value of count into another INTEGER
variable newcount .
GET_VAR Built-In Procedure
PROGRAM util_prog
VAR
j, num_of_parts : INTEGER
part_array
: ARRAY[5] OF
STRING[10]
BEGIN
num_of_parts = 0
FOR j = 1 to 20 DO
num_of_parts = num_of_parts
+ 1
ENDFOR
part_array[1] = 10
part_array[2] = 20
part_array[3] = 30
part_array[4] = 40
part_array[5] = 50
END util_prog
PROGRAM task
VAR
entry, status
: INTEGER
count, new_count : INTEGER
part_name
: STRING[20]
BEGIN
GET_VAR(entry, ’util_prog’, ’part_array[3]’,
part_name,
status)
WRITE(’Part Name is Now
>’, part_name, cr)
GET_VAR(entry, ’util_prog’, ’num_of_parts’, count, status)
A-173
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
WRITE(’COUNT Now Equals
>’, count, cr)
GET_VAR(entry, ’task’, ’count’, new_count, status)
END task
In GET_VAR SET_VAR Built-In Procedure , an array [ipgetset]set_data[x,y] is set on all robots in
the ring from all robots in the ring. In this array, x is the source robot index and y is the destination
robot index:
GET_VAR SET_VAR Built-In Procedure
FOR idx = 1 TO $PH_ROSIP.$NUM_MEMBERS DO
IF idx = $PH_ROSIP.$MY_INDEX THEN
-- This will work but it this robot so is inefficient
ELSE
SELECT $PH_MEMBERS[idx].$STATE OF
CASE (0) : -- Offline
sstate = ’ Offline’
CASE (1) : -- Online
sstate = ’ Online ’
CASE (2) : -- Synchronized
sstate = ’ Synch
’
CNV_INT_STR(idx, 1, 10, sidx)
prog_name = ’\\’ + $PH_MEMBERS[idx].$NAME + ’\ipgetset’
var_name = ’set_data[’+ smy_index + ’,’ + sidx + ’]’
GET_VAR(entry, prog_name, var_name, set_data[$PH_ROSIP.$MY_INDEX,
idx], status[idx])
IF status[idx] = 0 THEN
IF uninit(set_data[$PH_ROSIP.$MY_INDEX, idx]) THEN
set_data[$PH_ROSIP.$MY_INDEX, idx] = 0
ELSE
set_data[$PH_ROSIP.$MY_INDEX, idx] = set_data[$PH_ROSIP.$MY_INDEX,
idx] + 1
ENDIF
SET_VAR(entry, prog_name, var_name, set_data[$PH_ROSIP.$MY_INDEX, idx],
status[idx])
ENDIF
ENDSELECT
ENDIF
ENDFOR
Example 3 GET_VAR and SET_VAR can also be used to set register values.
A-174
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
This will work for the local robot with the program names *posreg* and *numreg*. For the local robot
this has similar functionality to the GET_POS_REG, GET_REG and SET_REG, SET_POS_REG
built-ins. The built-ins only work for the local robot. You can access robots in the ring via GET_VAR
and SET_VAR by using the robot name as part of the program name.
For the case of GET_VAR on numeric registers, the type of the KAREL variable must match the type
of the register or the error, “Incompatible value” is returned. In the example below if numeric register
10 is a real value an error will be returned and the real value will be set in the error case.
If a position register is locked and you attempt to set it, the error position register locked is returned.
See Using GET_VAR and SET_VAR To Set Register Values .
Using GET_VAR and SET_VAR To Set Register Values
program GETREG
%nolockgroup
VAR
entry: integer
status: integer
int_data: integer
real_data: real
posext_data: xyzwprext
BEGIN
GET_VAR(entry, ’\\mhrob01\*numreg*’, ’$NUMREG[10]’, int_data, status)
IF status <> 0 THEN
GET_VAR(entry, ’\\mhrob01\*numreg*’, ’$NUMREG[10]’, real_data, status)
ENDIF
GET_VAR(entry, ’\\mhrob01\*posreg*’, ’$POSREG[1, 10]’, posext_data, status)
SET_VAR(entry, ’\\mhrob01\*numreg*’, ’$NUMREG[20]’, int_data, status)
SET_VAR(entry, ’\\mhrob01\*numreg*’, ’$NUMREG[21]’, real_data, status)
SET_VAR(entry, ’\\mhrob01\*posreg*’, ’$POSREG[1, 20]’, posext_data, status)
end GETREG
A.8.28
GO TO Statement
Purpose: Transfers control to a specified statement
Syntax : || GO TO | GOTO || stmnt_label
where:
stmnt_label : A valid KAREL identifier
A-175
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Details:
• stmnt_label must be defined in the same routine or program body as the GO TO statement.
• Label identifiers are followed by double colons (::). Executable statements may or may not
follow on the same line.
• GOTO should only be used in special circumstances where normal control structures such as
WHILE, REPEAT, and FOR loops would be awkward or difficult to implement.
See Also: Section 2.1.5 , ‘‘Labels,’’ for more information on rules for labels, Appendix E , ‘‘Syntax
Diagrams,’’ for additional syntax information
Example: The following example moves the TCP from one position to another depending on the
status of DIN[1].
GO TO Statement
BEGIN
IF NOT DIN[1] THEN
move_to_p1 —— Call TP program to do move
ELSE
GO TO end_it
ENDIF
IF NOT DIN[1] THEN
move_to_p2 —— Call TP program to do move
ELSE
GO TO end_it
ENDIF
END_IT::
A.9
- H - KAREL LANGUAGE DESCRIPTION
A.9.1
HOLD Action
Purpose: Causes the current motion to be held and prevents subsequent motions from starting
Syntax : HOLD <GROUP[n,{,n}]>
Details:
• Any motion in progress is held. Robot and auxiliary or extended axes decelerate to a stop.
• An attempted motion after a HOLD is executed is also held. HOLD cannot be overridden by
a condition handler which issues a motion.
• HOLD is released using the UNHOLD statement or action.
A-176
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• If the group clause is not present, all groups for which the task has control (when the condition is
defined) will be canceled.
• If a motion that is held is part of a SIMULTANEOUS or COORDINATED motion with other
groups, the motions for all groups are held.
• Motion cannot be held for a different task.
See Also: Chapter 8 POSITION DATA , for more information on starting and stopping motions
Example: The following example shows a Condition Handler that holds motion when DIN[1] turns
on.
HOLD Action
CONDITION[1]:
WHEN DIN[1] = ON DO
HOLD
ENDCONDITION
A.9.2
HOLD Statement
Purpose: Causes the current motion to be held and prevents subsequent motions from starting
Syntax : HOLD <GROUP[n{,n}]>
Details:
• Any motion in progress is held. Robot and auxiliary or extended axes decelerate to a stop.
• An attempted motion after a HOLD is executed is also held. HOLD cannot be overridden by
a condition handler which issues a motion.
• HOLD is released using the UNHOLD statement or action.
• All held motions are canceled if a RELEASE statement is executed while motion is held.
• If the group clause is not present, all groups for which the task has control will be canceled.
• If a 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 held for a different task.
See Also: Chapter 8 POSITION DATA , for more information on starting and stopping motions,
Appendix E , ‘‘Syntax Diagrams,’’ for additional syntax information
A-177
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.10
- I - KAREL LANGUAGE DESCRIPTION
A.10.1
IF ... ENDIF Statement
Purpose: Executes a sequence of statements if a BOOLEAN expression is TRUE; an alternate
sequence can be executed if the condition is FALSE.
Syntax : IF bool_exp THEN
{ true_stmnt } < ELSE
{ false_stmnt } >ENDIF
where:
bool_exp : BOOLEAN
true_stmnt : An executable KAREL statement
false_stmnt : An executable KAREL statement
Details:
• If bool_exp evaluates to TRUE, the statements contained in the true_stmnt are executed.
Execution then continues with the first statement after the ENDIF.
• If bool_exp evaluates to FALSE and no ELSE clause is specified, execution skips directly to
the first statement after the ENDIF.
• If bool_exp evaluates to FALSE and an ELSE clause is specified, the statements contained in the
false_stmnt are executed. Execution then continues with the first statement after the ENDIF.
• IF statements can be nested in either true_stmnt or false_stmnt .
See Also: Appendix E , ‘‘Syntax Diagrams,’’ for additional syntax information
Example: Refer to the following sections for detailed program examples:
Section B.3 , "Saving Data to the Default Device" (SAVE_VR.KL)
Section B.5 , "Using Register Built-ins" (REG_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.9 , "Using the File and Device Built-ins" (FILE_EX.KL)
A-178
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
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.13 , "Using the DISCTRL_ALPHA Built-in" (DCALP_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.10.2
IN Clause
Purpose: Specifies where a variable will be created
Syntax : IN (CMOS | DRAM | SHADOW)
Details:
• The IN clause can be part of a variable declaration. It should be specified before the FROM clause.
• IN CMOS specifies that the variable will be created in permanent memory.
• IN DRAM specifies that the variable will be created in temporary memory.
• IN SHADOW specifies that any changes made to the variable will be maintained in CMOS.
Writes to this type of variable are slower but reads are much faster. This a good memory type to
use for configuration parameters that are currently in CMOS.
• IN UNINIT_DRAM specifies that a DRAM variable is UNINITIALIZED at startup.
• If the IN clause is not specified all variables are created in temporary memory; unless the
%CMOSVARS or %SHADOW directive is specified, in which case all variables will be created
in permanent memory.
• The IN clause cannot be used when declaring variables in the declaration section of a routine.
See Also: Section 1.4.1 , %CMOSVARS Translator Directive, %SHADOW Translator Directive,
%SHADOWCMOS Translator Directive
Example: Refer to the following sections for detailed program examples:
In DRAM, Section B.2 , "Copying Path Variables" (CPY_PTH.KL)
In CMOS, Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL) or Section B.11 ,
"Manipulating Values of Dynamically Displayed Variables" (CHG_DATA.KL)
A-179
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.10.3
%INCLUDE Translator Directive
Purpose: Inserts other files in a program at translation time.
Syntax : %INCLUDE file_spec
Details:
•
file_spec is the name of the file to include. It has the following details:
— The file name specified must be no longer than 12 characters.
— The file type defaults to .KL, and so it does not appear in the directive.
•
The %INCLUDE directive must appear on a line by itself.
•
The specified files usually contain declarations, such as CONST or VAR declarations. However,
they can contain any portion of a program including executable statements and even other
%INCLUDE directives.
•
Included files can themselves include other files up to a maximum depth of three nested included
files. There is no limit on the total number of included files.
•
When the KAREL language translator encounters a %INCLUDE directive during translation of a
file, it begins translating the included file just as though it were part of the original file. When the
entire file has been included, the translator resumes with the original file.
•
Some examples in Appendix A reference the following include files:
%INCLUDE FR:\klevkmsk
%INCLUDE FR:\klevkeys
%INCLUDE FR:\klevccdf
%INCLUDE FR:\kliotyps
These files contain constants that can be used in your KAREL programs. If you are translating on
the controller, you can include them directly from the FROM disk.
The include files are also available on the OLPC disks, and are copied to the hard disk as part
of the installation process.
Example: Refer to the following sections for detailed program examples:
Section B.2 , "Copying Path Variables" (CPY_PTH.KL)
Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL)
Section B.13 , "Using the DISCTRL_ALPHA Built-in" (DCALP_EX.KL)
A-180