FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

command = ’SHOW PROGRAMS’

KCL (command, status)

END kcl_test

Example: Refer to Example Program for Display Only Data Items for another example.

A.12.2

KCL_NO_WAIT Built-In Procedure

Purpose: Sends the KCL command specified by the STRING argument to KCL for execution, but

does not wait for completion of the command before continuing program execution.

Syntax : KCL_NO_WAIT (command, status)

Input/Output Parameters :

[in] command :STRING

[out] status :INTEGER

%ENVIRONMENT Group :kclop

Details:

• command must contain a valid KCL command.

• status indicates whether KCL accepted the command.

• Program execution waits until KCL accepts the command or an error is detected.

See Also: KCL, KCL_STATUS Built-In Procedures

Example: The following example will load a program, but will not wait for the program to be loaded

before returning. Status will indicate if the command was accepted or not.

KCL_NO_WAIT Built-In Procedure

PROGRAM kcl_test

VAR

command :STRING[20]

status :INTEGER

BEGIN

command = ’Load prog test_1’

KCL_NO_WAIT (command, status)

delay 5000

status = KCL_STATUS

END kcl_test

A-212

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

A.12.3

KCL_STATUS Built-In Procedure

Purpose: Returns the status of the last executed command from either KCL or KCL_NO_WAIT

built-in procedures.

Syntax : KCL_STATUS

Function Return Type :INTEGER

%ENVIRONMENT Group :kclop

Details:

• Returns the status of the last executed command from the KCL or KCL_NO_WAIT built-ins.

• Program execution waits until KCL can return the status.

See Also: KCL_NO_WAIT, KCL Built-In Procedures

A.13

- L - KAREL LANGUAGE DESCRIPTION

A.13.1

LN Built-In Function

Purpose: Returns the natural logarithm of a specified REAL argument

Syntax : LN(x)

Function Return Type :REAL

Input/Output Parameters:

[in] x : REAL

%ENVIRONMENT Group :SYSTEM

Details:

• The returned value is the natural logarithm of x .

• x must be greater than zero. Otherwise, the program will be aborted with an error.

Example: The following example returns the natural logarithm of the input variable a and assigns

it to the variable b .

LN Built-In Function

WRITE(CR, CR, ’enter a number =’)

READ(a,CR)

A-213

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

b = LN(a)

A.13.2

LOAD Built-In Procedure

Purpose: Loads the specified file

Syntax : LOAD (file_spec, option_sw, status)

Input/Output Parameters:

[in] file_spec :STRING

[in] option_sw :INTEGER

[out] status :INTEGER

%ENVIRONMENT Group :PBCORE

Details:

• file_spec specifies the device, name, and type of the file to load. The following types are valid:

.TP Teach pendant program

.PC KAREL program

.VR KAREL variables

.SV KAREL system variables

.IO I/O configuration data

no ext KAREL program and variables

• option_sw specifies the type of options to be done during loading.

The following value is valid for .TP files:

— 1 If the program already exists, then it overwrites the program. If option_sw is not 1 and the

program exists, an error will be returned.

The following value is valid for .SV files:

— 1 Converts system variables.

• option_sw is ignored for all other types.

A-214

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

• status explains the status of the attempted operation. If not equal to 0, then an error occurred.

The following note applies to R-30iB controllers:

Note The KAREL option must be installed on the robot controller in order to load KAREL

programs.

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.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL)

A.13.3

LOAD_STATUS Built-In Procedure

Purpose: Determines whether the specified KAREL program and its variables are loaded into memory

Syntax : LOAD_STATUS(prog_name, loaded, initialized)

Input/Output Parameters:

[in] prog_name :STRING

[out] loaded :BOOLEAN

[out] initialized :BOOLEAN

%ENVIRONMENT Group :PBCORE

Details:

• prog_name must be a program and cannot be a routine.

• loaded returns a value of TRUE if prog_name is currently loaded into memory. FALSE is

returned if prog_name is not loaded.

• initialized returns a value of TRUE if any variable within prog_name has been initialized. FALSE

is returned if all variables within prog_name are uninitialized.

• If either loaded or initialized is FALSE, use the LOAD built-in procedure to load prog_name

and its variables.

Example: Refer to the following sections for detailed program examples:

A-215

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

Section B.7 , "Listing Files and Programs and Manipulating Strings" (LIST_EX.KL)

Section B.10 , "Using Dynamic Display Built-ins" (DYN_DISP.KL)

A.13.4

LOCK_GROUP Built-In Procedure

Purpose: Locks motion control for the specified group of axes

Syntax : LOCK_GROUP(group_mask, status)

Input/Output Parameters:

[in] group_mask : INTEGER

[out] status : INTEGER

%ENVIRONMENT Group :MULTI

Details:

• group_mask specifies the group of axes to lock for the running task. The group numbers must be

in the range of 1 to the total number of groups defined on the controller.

• The group_mask is specified by setting the bit(s) for the desired group(s).

Table

A-16.

Group_mask Setting

GROUP

DECIMAL

BIT

Group 1

Group 2

Group 3

To specify multiple groups select the decimal values, shown in Table A-16 , which correspond to

the desired groups. Then connect them together using the OR operator. For example to specify

groups 1, 3, enter "1 OR 4".

• Motion control is gained for the specified motion groups.

• If one or more of the groups cannot be locked, then an error is returned, and any available groups

will be locked.

• Moving a group automatically locks the group if it has not been previously locked by another task.

• If a task tries to move a group that is already locked by another task, it will be paused.

• status explains the status of the attempted operation. If not equal to 0, an error occurred.

A-216

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

Example: The following example unlocks group 1, 2, and 3, and then locks group 3. Refer to Chapter

15 MULTI-TASKING , for more examples.

LOCK_GROUP Built-In Procedure

%ENVIRONMENT MOTN

%ENVIRONMENT MULTI

VAR

status: INTEGER

BEGIN

REPEAT

-- Unlock groups 1, 2, and 3

UNLOCK_GROUP(1 OR 2 OR 4, status)

IF status = 17040 THEN

CNCL_STP_MTN -- or RESUME

ENDIF

DELAY 500

UNTIL status = 0

-- Lock only group 3

LOCK_GROUP(4, status)

END lock_grp_ex

A.13.5

%LOCKGROUP Translator Directive

Purpose: Specifies the motion group(s) to be locked when calling this program or a routine from

this program.

Syntax : %LOCKGROUP = n, n ,...

Details:

• n is the number of the motion group to be locked.

• The range of n is 1 to the number of groups on the controller.

• When the program or routine is called, the task will attempt to get motion control for all the

specified groups if it does not have them locked already. The task will pause if it cannot get

motion control.

• If %LOCKGROUP is not specified, all groups will be locked.

• The %NOLOCKGROUP directive can be specified if no groups should be locked.

See Also: %NOLOCKGROUP Directive, LOCK_GROUP, UNLOCK_GROUP Built-In Procedures

A-217

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

A.14

- M - KAREL LANGUAGE DESCRIPTION

A.14.1

MIRROR Built-In Function

Purpose: Determines the mirror image of a specified position variable.

Syntax : MIRROR (old_pos, mirror_frame, orientation_flag)

Function Return Type: XYZWPREXT

Input/Output Parameters :

[in] old_pos :POSITION

[in] mirror_frame :POSITION

[in] orient_flag :BOOLEAN

%ENVIRONMENT Group :MIR

Details:

• old_pos and mirror_frame must both be defined relative to the same user frame.

• old_pos specifies the value whose mirror image is to be generated.

• mirror_frame specifies the value across whose xz_plane the image is to be generated.

• If orient_flag is TRUE, both the orientation and location component of old_pos will be mirrored.

If FALSE, only the location is mirrored and the orientation of the new mirror-image position is

the same as that of old_pos.

• The returned mirrored position is not guaranteed to be a reachable position, since the mirrored

position can be outside of the robot’s work envelope.

See Also: The appropriate application-specific FANUC Robotics Setup and Operations Manual

, chapter on "Advanced Functions"

Example: The following example gets the current position of the robot, creates a mirror frame, and

generates a mirrored position which is mirrored about the y axis.

MIRROR Built-In Function

PROGRAM mir_exam

VAR

cur_pos:

XYZWPREXT

org_pos:

POSITION

mir_pos:

XYZWPREXT

A-218

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

mir_posa: POSITION

pos_frame: XYZWPREXT

frame:

POSITION

orient_flag: BOOLEAN

BEGIN

cur_pos = curpos(0,0) -- Get the current position of the robot

cur_pos.x = 1000.00

-- Create a new position which is at(1000,0,300,w,p,r)

cur_pos.y = 0.0

cur_pos.z = 300.00

SET_EPOS_REG(1, cur_pos, status)

move_to_pr1 -— Call TP program to move to PR[1]

-- The robot is now at a known position:

--(1000,0,300,w,p,r) where (w,p,r) have not

--changed from the original position.

pos_frame = curpos(0,0) -- Create a frame used to mirror about.

pos_frame.w = 0

-- By setting (w,p,r) to 0, the x-z plane of

pos_frame.p = 0

-- pos_frame will be parallel to the world’s x-z

pos_frame.r = 0

-- plane. pos_frame now set to (1000,0,300,0,0,0)

frame = pos_frame

-- Convert the mirror frame to a POSITION type.

cur_pos.y = 200

-- Move 200mm in the y direction.

SET_EPOS_REG(1, cur_pos, status)

move_to_pr1

-- Current position is (1000,200,300,w,p,r)

org_pos = cur_pos

-- Convert org_pos to a POSITION type.

orient_flag = FALSE

-- Send Mirror current position: (1000, 200, 300,

-- w,p,r), and mirror frame: (1000,0,300,0,0,0).

-- Mirrors about the y axis without mirroring the

-- orientation (w,p,r).

mir_pos = mirror(org_pos, frame, orient_flag)

-- mir_pos is the mirrored position: (1000, -200,

-- 300, w, p, r).

-- The orientation is the same as org_pos.

orient_flag = TRUE

-- The mirrored position includes mirroring of

-- the tool orientation.

mir_posa = mirror(org_pos,frame,orient_flag)

-- mir_posa is the mirrored position where Normal

-- Orient, & Approach vectors have been mirrored.

end mir_exam

A.14.2

MODIFY_QUEUE Built-In Procedure

Purpose: Replaces the value of an entry of a queue.

Syntax : MODIFY_QUEUE(value, sequence_no, queue_t, queue_data, status)

A-219

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

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.

• sequence_no specifies the sequence number of the entry whose value is to be modified

• 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 61003, ‘‘Bad sequence no,’’ if the specified sequence number is not in

the queue.

See Also: COPY_QUEUE, GET_QUEUE, DELETE_QUEUE Built-In Procedures Section 15.8 ,

"Using Queues for Task Communication"

Example: In the following example, the routine update_queue replaces the value of the specified

entry ( sequence_no ); of a queue ( queue and queue_data with a new value ( value ).

MODIFY_QUEUE Built-In Procedure

PROGRAM mod_queue_x

%ENVIRONMENT PBQMGR

ROUTINE update_queue(value: INTEGER;

sequence_no: INTEGER;

queue_t: QUEUE_TYPE;

queue_data: ARRAY OF INTEGER)

VAR

status: INTEGER

BEGIN

MODIFY_QUEUE(value, sequence_no, queue_t, queue_data, status)

return

END update_queue

BEGIN

END mod_queue_x

A-220

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

A.14.3

MOTION_CTL Built-In Function

Purpose: Determines whether the KAREL program has motion control for the specified group of axes

Syntax : MOTION_CTL<(group_mask)>

Function Return Type :BOOLEAN

Input/Output Parameters:

[in] group_mask :INTEGER

%ENVIRONMENT Group :MOTN

Details:

• If group_mask is omitted, the default group mask for the program is assumed.

• The default group_mask is determined by the %LOCKGROUP and %NOLOCKGROUP

directives.

• The group_mask is specified by setting the bit(s) for the desired group(s).

Table

A-17.

Group_mask Setting

GROUP

DECIMAL

BIT

Group 1

Group 2

Group 3

To specify multiple groups select the decimal values, shown in Table A-17 , which correspond to

the desired groups. Then connect them together using the OR operator. For example to specify

groups 1, 3, enter "1 OR 4".

• Returns TRUE if the KAREL program has motion control for the specified group of axes.

A.14.4

MOUNT_DEV Built-In Procedure

Purpose: Mounts the specified device

Syntax : MOUNT_DEV (device, status)

Input/Output Parameters:

A-221

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

[in] device : STRING

[out] status :INTEGER

%ENVIRONMENT Group :FDEV

Details:

• device specifies the device to be mounted.

• status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.

See Also: DISMOUNT_DEV and FORMAT_DEV

Example: Refer to Section B.9 , "Using the File and Device Built-ins" (FILE_EX.KL), for a detailed

program example.

A.14.5

MOVE_FILE Built-In Procedure

Purpose: Moves the specified file from one memory file device to another

Syntax : MOVE_FILE (file_spec, status)

Input/Output Parameters :

[in] file_spec : string

[out] status : integer

%ENVIRONMENT Group :FDEV

Details:

• file_spec specifies the device, name, and type of the file to be moved. The file should exist on

the FROM or RAM disks.

• If file_spec is a file on the FROM disk, the file is moved to the RAM disk, and vice versa.

• The wildcard character (*) can be used to replace the entire file name, the first part of the file

name, the last part of the file name, or both the first and last parts of the file name. The file type

can also use the wildcard in the same manner. If file_spec specifies multiple files, then they are

all moved to the other disk.

• status explains the status of the attempted operation. If not equal to 0, then an error occurred.

Example: In the following example, all .KL files are moved from the RAM disk to the FROM disk.

MOVE_FILE Built-In Procedure

PROGRAM move_files

A-222

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

%NOLOCKGROUP

%ENVIRONMENT FDEV

VAR

status: INTEGER

BEGIN

MOVE_FILE(’RD:\*.KL’, status)

IF status <> 0 THEN

POST_ERR(status, ’’, 0, 0)

ENDIF

END move_files

A.14.6

MSG_CONNECT Built-In Procedure

Purpose: Connect a client or server port to another computer for use in Socket Messaging.

Syntax : MSG_CONNECT (tag, status)

Input/Output Parameters :

[in] tag :STRING

[out] status :INTEGER

%ENVIRONMENT Group :FLBT

Details:

• Tag is the name of a client port (C1:-C8) or server port (S1:S8).

• Status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.

See Also: Socket Messaging in the FANUC Robotics Internet Options Setup and Operations Manual.

Example: The following example connects to S8: and reads messages. The messages are displayed

on the teach pendant screen.

MSG_CONNECT Built-In Procedure

PROGRAM tcpserv8

VAR

file_var : FILE

tmp_int

: INTEGER

tmp_int1 : INTEGER

tmp_str

: string [128]

tmp_str1 : string [128]

status

: integer

A-223

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

entry

: integer

BEGIN

SET_FILE_ATR (file_var, ATR_IA)

-- Set up S8 server tag

DISMOUNT_DEV(’S8:’,status)

MOUNT_DEV(’S8:’,status)

write

(’ Mount Status = ’,status,cr)

status = 0

IF status = 0 THEN

-- Connect the tag

write (’Connecting ..’,cr)

MSG_CONNECT (’S8:’,status)

write

(’Connect Status = ’,status,cr)

IF status < > 0 THEN

MSG_DISCO(’S8:’,status)

write

(’ Connecting..’,cr)

MSG_CONNECT(’S8:’,status)

write

(’ Connect Status = ’,status,cr)

ENDIF

IF status = 0 THEN

-- OPEN S8:

write (’Opening’,cr)

OPEN FILE file_var (’rw’,’S8:’)

status = io_status(file_var)

FOR tmp_int

1 TO 1000 DO

write

(’Reading’,cr)

BYTES_AHEAD(file_var, entry, status)

-- Read 10 bytes

READ file_var (tmp_str::10)

status = i/o_status(file_var)

--Write 10 bytes

write (tmp_str::10,cr)

status = io_status(file_var)

ENDFOR

CLOSE FILE file_var

write

(’Disconnecting..’,cr)

MSG_DISCO(’S8:’,status)

write

(’Done.’,cr)

ENDIF

END tcpserv8

A-224

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

A.14.7

MSG_DISCO Built-In Procedure

Purpose: Disconnect a client or server port from another computer.

Syntax : MSG_DISCO (tag, status)

Input/Output Parameters :

[in] tag :STRING

[out] status :INTEGER

%ENVIRONMENT Group :FLBT

Details:

• Tag is the name of a client port (C1:-C8) or server port (S1:S8).

• Status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.

See Also: Socket Messaging in the FANUC Robotics Internet Options Setup and Operations Manual .

Example: Refer to MSG_CONNECT Built-In Procedure for more examples.

A.14.8

MSG_PING

Syntax : MSG_PING (host name, status)

Input/Output Parameters :

[in] host name :STRING

[out] status :INTEGER

%ENVIRONMENT Group :FLBT

Details:

• Host name is the name of the host to perform the check on. An entry for the host has to be present

in the host entry tables (or the DNS option loaded and configured on the robot).

• Status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.

See Also: Ping in the FANUC Robotics Internet Options Setup and Operations Manual.

Example: The following example performs a PING check on the hostname "fido". It writes the

results on the teach pendant.

A-225

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

MSG_PING Built-In Procedure

PROGRAM pingtest

VAR

Tmp_int

: INTEGER

Status

: integer

BEGIN

WRITE(’pinging..’,cr)

MSG_PING(’fido’,status)

WRITE(’ping Status = ’,status,cr)

END pingtest

A.15

- N - KAREL LANGUAGE DESCRIPTION

A.15.1

NOABORT Action

Purpose: Prevents program execution from aborting when an external error occurs

Details:

• The NOABORT action usually corresponds to an ERROR[n].

• If the program is aborted by itself (i.e., executing an ABORT statement, run time error), the

NOABORT action will be ignored and program execution will be aborted.

Example: The following example uses a global condition handler to test for error number 11038,

"Pulse Mismatch." If this error occurs, the NOABORT action will prevent program execution from

being aborted.

NOABORT Action

PROGRAM noabort_ex

%NOLOCKGROUP

BEGIN

--Pulse Mismatch condition handler

CONDITION[801]:

WHEN ERROR[11038] DO

NOABORT

ENDCONDITION

ENABLE CONDITION[801]

END noabort_ex

A-226

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

A.15.2

%NOABORT Translator Directive

Purpose: Specifies a mask for aborting

Syntax : %NOABORT = ERROR + COMMAND

Details:

• ERROR and COMMAND are defined as follows:

ERROR : ignore abort error severity

COMMAND : ignore abort command

• Any combination of ERROR and COMMAND can be specified.

• If the program is aborted by itself (for example, executing an ABORT statement, run-time error),

the %NOABORT directive will be ignored and program execution will be aborted.

• This directive is only effective for programs with %NOLOCKGROUP. If the program has motion

control, the %NOABORT directive will be ignored and program execution will be aborted.

A.15.3

%NOBUSYLAMP Translator Directive

Purpose: Specifies that the busy lamp will be OFF during execution.

Syntax: %NOBUSYLAMP

Details:

• The busy lamp can be set during task execution by the SET_TSK_ATTR built-in.

A.15.4

NODE_SIZE Built-In Function

Purpose: Returns the size (in bytes) of a PATH node

Syntax : NODE_SIZE(path_var)

Function Return Type :INTEGER

Input/Output Parameters:

[in] path_var : PATH

%ENVIRONMENT Group :PATHOP

Details:

A-227

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

• The returned value is the size of an individual PATH node, including the positional data type

size and any associated data.

• The returned value can be used to calculate file positions for random access to nodes in files.

Example: The following example program reads a path, while overlapping reads with preceding

moves. The routine read_header reads the path header and prepares for reading of nodes. The

routine read_node reads a path node.

NODE_SIZE Built-In Function

PROGRAM read_and_mov

VAR my_path: PATH

xyz_pos: XYZWPR

path_base: INTEGER

node_size: INTEGER

max_node_no: INTEGER

i: INTEGER

file_var: FILE

ROUTINE read_header

BEGIN

READ file_var(my_path[0])

IF IO_STATUS(file_var) <> 0 THEN

WRITE(’HEADER READ ERROR:’,IO_STATUS(file_var),cr)

ABORT

ENDIF

max_node_no = PATH_LEN(my_path)

node_size = NODE_SIZE(my_path)

path_base = GET_FILE_POS(file_var)

END read_header

ROUTINE read_node(node_no: INTEGER)

VAR status: INTEGER

BEGIN

SET_FILE_POS(file_var, path_base+(node_no-1)*node_size,

status)

READ file_var(my_path[node_no])

END read_node

BEGIN

SET_FILE_ATR(file_var, atr_uf)

OPEN FILE F1(’RO’,’PATHFILE.DT’)

read_header

FOR i = 1 TO max_node_no DO

read_node(i)

xyz_pos = my_path[i]

SET_POS_REG(1 xyz_pos, status)

move_to_pr1 —— Call TP program to move to node

ENDFOR

A-228

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

CLOSE FILE file_var

END read_and_mov

A.15.5

%NOLOCKGROUP Translator Directive

Purpose: Specifies that motion groups do not need to be locked when calling this program, or a

routine defined in this program.

Syntax : %NOLOCKGROUP

Details:

• When the program or routine is called, the task will not attempt to get motion control.

• If %NOLOCKGROUP is not specified, all groups will be locked when the program or routine

is called, and the task will attempt to get motion control. The task will pause if it cannot get

motion control.

• The task will keep motion control while it is executing the program or routine. When it exits the

program or routine, the task automatically unlocks all the motion groups.

• If the task contains executing or stopped motion, then task execution is held until the motion is

completed. Stopped motion must be resumed and completed or cancelled.

• If a program that has motion control calls a program with the %NOLOCKGROUP Directive

or a routine defined in such a program, the program will keep motion control even though it

is not needed.

• The UNLOCK_GROUP built-in routine can be used to release control.

• If a motion statement is encountered in a program that has the %NOLOCKGROUP Directive, the

task will attempt to get motion control for all the required groups if it does not already have it.

The task will pause if it cannot get motion control.

See Also: %LOCKGROUP Translator Directive, LOCK_GROUP, UNLOCK_GROUP Built-In

Procedures

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.10 , "Using Dynamic Display Built-ins" (DYN_DISP.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)

A-229

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

Section B.13 , "Using the DISCTRL_ALPHA Built-in" (DCALP_EX.KL)

A.15.6

NOMESSAGE Action

Purpose: Suppresses the display and logging of error messages

Syntax : NOMESSAGE

Details:

• Display and logging of the error messages are suppressed only for the error number specified in

the corresponding condition.

• Use a wildcard (*) to suppress all messages.

• Abort error messages still will be displayed and logged even if NOMESSAGE is used.

Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)

for a detailed program example.

A.15.7

NOPAUSE Action

Purpose: Resumes program execution if the program was paused, or prevents program execution

from pausing

Syntax : NOPAUSE

Details:

• The NOPAUSE action usually corresponds to an ERROR[n] or PAUSE condition.

• The program will be resumed, even if it was paused before the error.

• If the program is paused by itself, the NOPAUSE action will be ignored and program execution

will be paused.

Example: The following example uses a global condition handler to test for error number 12311. If

this error occurs, the NOPAUSE action will prevent program execution from being paused and the

NOMESSAGE action will suppress the error message normally displayed for error number 12311.

This will allow the routine uninit_error to be executed without interruption.

NOPAUSE Action

ROUTINE uninit_error

BEGIN

WRITE (’Uninitialized operand’,CR)

WRITE (’Use KCL> SET VAR to initialize operand’,CR)

A-230

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

WRITE (’Press Resume at Test/Run screen to ’,cr)

WRITE (’continue program’,cr)

PAUSE

--pauses program (undoes NOPAUSE action)

END uninit_error

CONDITION[1]:

WHEN ERROR[12311] DO

NOPAUSE, NOMESSAGE, uninit_error

ENDCONDITION

A.15.8

%NOPAUSE Translator Directive

Purpose: Specifies a mask for pausing

Syntax : %NOPAUSE = ERROR + COMMAND + TPENABLE

Details:

• The bits for the mask are as follows:

ERROR : ignore pause error severity

COMMAND : ignore pause command

TPENABLE : ignore paused request when TP enabled

• Any combination of ERROR, COMMAND, and TPENABLE can be specified.

• If the program is paused by itself, the %NOPAUSE directive will be ignored and program

execution will be paused.

• This directive is only effective for programs with %NOLOCKGROUP. If the program has motion

control, the %NOPAUSE Directive will be ignored and program execution will be paused.

A.15.9

%NOPAUSESHFT Translator Directive

Purpose: Specifies that the task is not paused if shift key is released.

Syntax : %NOPAUSESHFT

Details:

• This attribute can be set during task execution by the SET_TSK_ATTR built-in routine.

A-231

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

A.16

- O - KAREL LANGUAGE DESCRIPTION

A.16.1

OPEN FILE Statement

Purpose: Associates a data file or communication port with a file variable

Syntax : OPEN FILE file_var ( usage_string, file_string)

where:

file_var : FILE

usage_string : a STRING

file_string : a STRING

Details:

• file_var must be a static variable not already in use by another OPEN FILE statement.

• The usage_string is composed of the following:

‘RO’ :Read only

‘RW’ :Read write

‘AP’ :Append

‘UD’ :Update

• The file_string identifies a data file name and type, a window or keyboard, or a communication

port.

• The SET_FILE_ATR built-in routine can be used to set a file’s attributes.

• When a program is aborted or exits normally, any opened files are closed. Files are not closed

when a program is paused.

• Use the IO_STATUS built-in function to verify if the open file operation was successful.

See Also: IO_STATUS Built-In Function, SET_FILE_ATR Built-In Procedure, Chapter 7 FILE

INPUT/OUTPUT OPERATIONS , Chapter 9 FILE SYSTEM , 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.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL)

A-232

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

A.16.2

OPEN HAND Statement

Purpose: Opens a hand on the robot

Syntax : OPEN 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: Appendix D, ‘‘Syntax Diagrams’’ for more syntax information

Example: The following example moves the TCP to the position register PR[2] and opens the hand

of the robot specified by the INTEGER variable hand_num .

OPEN HAND Statement

move_to_pr2

—— Call TP program to move to PR[2]

OPEN HAND hand_num

A.16.3

OPEN_TPE Built-In Procedure

Purpose: Opens the specified teach pendant program

Syntax : OPEN_TPE(prog_name, open_mode, reject_mode, open_id, status)

Input/Output Parameters:

[in] prog_name :STRING

[in] open_mode :INTEGER

[in] reject_mode :INTEGER

[out] open_id :INTEGER

A-233

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

[out] status :INTEGER

%ENVIRONMENT Group :PBCORE

Details:

•

prog_name specifies the name of the teach pendant program to be opened. prog_name must be

in all capital letters.

•

prog_name must be closed, using CLOSE_TPE, before prog_name can be executed.

•

open_mode determines the access code to the program. The access codes are defined as follows:

0 : none

TPE_RDACC : Read Access

TPE_RWACC : Read/Write Access

•

reject_mode determines the reject code to the program. The program that has been with a reject

code cannot be opened by another program. The reject codes are defined as follows:

TPE_NOREJ : none

TPE_RDREJ : Read Reject

TPE_WRTREJ : Write Reject

TPE_RWREJ : Read/Write Reject

TPE_ALLREJ : All Reject

•

open_id indicates the id number of the opened program.

•

status explains the status of the attempted operation. If not equal to 0, then an error has occurred.

•

All open teach pendant programs are closed automatically when the KAREL program is aborted

or exits normally.

See Also: CREATE_TPE Built-In Procedure, COPY_TPE Built-In Procedure, AVL_POS_NUM

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

ORD Built-In Function

Purpose: Returns the numeric ASCII code corresponding to the character in the STRING argument

that is referenced by the index argument

A-234

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

Syntax : ORD(str, str_index)

Function Return Type :INTEGER

Input/Output Parameters:

[in] str :STRING

[in] str_index :INTEGER

%ENVIRONMENT Group :SYSTEM

Details:

• The returned value represents the ASCII numeric code of the specified character.

• str_index specifies the indexed position of a character in the argument str . A value of 1 indicates

the first character.

• If str_index is less than one or greater than the current length of str , the program is paused

with an error.

See Also: Appendix D , ‘‘Character Codes’’

Example: Refer to Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL), for a

detailed program example.

A.16.5

ORIENT Built-In Function

Purpose: Returns a unit VECTOR representing the y-axis (orient vector) of the specified POSITION

argument

Syntax : ORIENT(posn)

Function Return Type :VECTOR

Input/Output Parameters:

[in] posn : POSITION

%ENVIRONMENT Group :VECTR

Details:

• Instead of using this built-in, you can directly access the Orient Vector of a POSITION.

• The returned value is the orient vector of posn .

• The orient vector is the positive y-direction in the tool coordinate frame.

A-235

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

A.17

- P - KAREL LANGUAGE DESCRIPTION

A.17.1

PATH Data Type

Purpose: Defines a variable or routine parameter as PATH data type

Syntax : PATH

Details:

• A PATH is a varying length list of elements called path nodes, numbered from 1 to the number of

nodes in the PATH.

• No valid operators are defined for use with PATH variables.

• A PATH variable is indexed (or subscripted) as if it were an ARRAY variable. For example,

tool_track[1] refers to the first node of a PATH called tool_track .

• An uninitialized PATH has a length of zero.

• PATH variables cannot be declared local to routines and cannot be returned from functions.

• Only PATH expressions can be assigned to PATH variables or passed as arguments to PATH

parameters.

• A PATH variable can specify a data structure constituting the data for each path node.

• A PATH variable can specify a data structure constituting the path header. This can be used to

specify the UFRAME and/or UTOOL to be used with recording the path. It can also specify an

axis group whose current position defines a table-top coordinate frame with respect to which

the robot data is recorded.

• A PATH can be declared with either, neither, or both of the following clauses following the

word PATH:

— NODEDATA = node_struct_name, specifying the data structure constituting a path node.

— PATHHEADER = header_struct_name, specifying the structure constituting the path header.

If both fields are present, they can appear in either order and are separated by a comma and optionally

a new line.

• If NODEDATA is not specified, it defaults to the STD_PTH_NODE structure described in

Appendix A.

• If PATHHEADER is not specified, there is no (user-accessible ) path header.

• An element of the PATHHEADER structure can be referenced with the syntax

path_var_name.header_field_name.

• An element of a NODEDATA structure can be referenced with the syntax

path_var_name[node_no].node_field_name.

A-236

MARRC75KR07091E Rev D

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

• The path header structure can be copied from one path to another with the path_var1 = path_var2

statement.

• The path node structure can be copied from one node to another with the path_var[2] =

path_var[1] statement.

• A path can be passed as an argument to a routine as long as the PATHHEADER and NODEDATA

types match. A path that is passed as an argument to a built-in routine can be of any type.

• A path node can be passed as an argument to a routine as long as the routine parameter is the

same type as the NODEDATA structure.

• A path can be declared with a NODEDATA structure having no position type elements. This can

be a useful way of maintaining a list structure.

See Also: APPEND_NODE, DELETE_NODE, INSERT_NODE Built-In Procedures, PATH_LEN,

NODE_SIZE Built-In Functions

Example: The following example shows different declarations of PATH variables.

PATH Data Type

TYPE

node_struct = STRUCTURE

node_posn: XYZWPR IN GROUP[1]

aux_posn: JOINTPOS IN GROUP[2]

weld_time: INTEGER

weld_current: INTEGER

ENDSTRUCTURE

hdr_struct = STRUCTURE

uframe1: POSITION

utool: POSITION

speed: REAL

ENDSTRUCTURE

VAR

path_1a: PATH PATHHEADER = hdr_struct, NODEDATA = node_struct

path_1b: PATH NODEDATA = node_struct, PATHHEADER = hdr_struct

path_2: PATH NODEDATA = node_struct -- no header

path_3: PATH -- NODEDATA is STD_PTH_NODE

path_4: PATH PATHHEADER = hdr_struct -- NODEDATA is STD_PTH_NODE

The following example shows how elements of the NODEDATA and PATHHEADER structures

can be referenced.

PATH Data Type

-- Using declarations for path_1a:

-- Using NODEDATA fields:

path_1a[1].node_posn = CURPOS(0, 0)

A-237

A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION

MARRC75KR07091E Rev D

cnt_dn_time = path_1a[node_no].weld_time

-- Using PATHHEADER fields:

path_1a.utool = tool_1

Example: Refer to the following sections for detailed program examples:

Section B.2 , "Copying Path Variables" (CPY_PTH.KL)

Section B.6 , "Path Variables and Condition Handlers Program" (PTH_MOVE.KL)

A.17.2

PATH_LEN Built-In Function

Purpose: Returns the number of nodes in the PATH argument

Syntax : PATH_LEN(path_nam)

Function Return Type : INTEGER

Input/Output Parameters :

[in] path_nam : PATH

%ENVIRONMENT Group :PBCORE

Details:

• The returned value corresponds to the number of nodes in the PATH variable argument.

• Calling PATH_LEN with an uninitialized PATH returns a value of zero.

FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual - page 18