FANUC Robotics SYSTEM R-30iA and R-30iB Controller. KAREL Reference Manual - page 19
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Input/Output Parameters :
[in] pipe_name :STRING
[in] cmos_flag :BOOLEAN
[in] n_sectors :INTEGER
[in] record_size :INTEGER
[in] form_dict :STRING
[in] form_ele :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :FLBT
Details:
• pipe_name is the name of the pipe file. If the file does not exist it will be created with this
operation.
• CMOS_flag if set to TRUE will put the pipe data in CMOS. By default pipe data is in DRAM.
• n_sectors number of 1024 byte sectors to allocate to the pipe. The default is 8.
• record_size the size of a binary record in a pipe. If set to 0 the pipe is treated as ASCII. If a pipe
is binary and will be printed as a formatted data then this must be set to the record length.
• form_dict is the name of the dictionary containing formatting information.
• form_ele is the element number in form_dict containing the formatting information.
• status explains the status of the attempted operation. If it is not equal to 0, then an error occurred.
See Also: For further information see "PIP: Device" in Section 9.3.4 .
A.17.9
POP_KEY_RD Built-In Procedure
Purpose: Resumes key input from a keyboard device
Syntax : POP_KEY_RD(key_dev_name, pop_index, status)
Input/Output Parameters:
[in] key_dev_name :STRING
[in] pop_index :INTEGER
A-243
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[out] status :INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• Resumes all suspended read requests on the specified keyboard device.
• If there were no read requests active when suspended, this operation will not resume any inputs.
This is not an error.
• key_dev_name must be one of the keyboard devices already defined:
’TPKB’ :Teach Pendant Keyboard Device
’CRKB’ :CRT Keyboard Device
• pop_id is returned from PUSH_KEY_RD and should be used to re-activate the read requests.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: PUSH_KEY_RD, READ_KB Built-in Procedures
Example: Refer to the example for the READ_KB Built-In Routine.
A.17.10
Port_Id Action
Purpose: Sets the value of a port array element to the result of an expression
Syntax : port_id[n] = expression
where:
port_id :an output port array
n :an INTEGER
expression :a variable, constant, or EVAL clause
Details:
• The value of expression is assigned to the port array element referenced by n .
• The port array must be an output port array that can be written to by a KAREL program. Refer to
Chapter 2, ‘‘Language Elements.’’
• expression can be a user-defined, static variable, a system variable that can be read by a KAREL
program, any constant, or an EVAL clause.
A-244
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• If expression is a variable, the value used is the current value of the variable at the time the action
is taken, not when the condition handler is defined.
• If expression is an EVAL clause, it is evaluated when the condition handler is defined and that
value is assigned when the action is taken.
• The expression must be of the same type as port_id .
• You cannot assign a port array element to a port array element directly.
• If the expression is a variable that is uninitialized when the condition handler is enabled, the
program will be aborted with an error.
See Also: Chapter 6 CONDITION HANDLERS , Chapter 7 FILE INPUT/OUTPUT OPERATIONS ,
Relational Conditions, Appendix A, ‘‘KAREL Language Alphabetical Description’’
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A.17.11
Port_Id Condition
Purpose: Monitors a digital port signal
Syntax : <NOT> port_id[n] < + | - >
where:
port_id :a port array
n :an INTEGER
Details:
• n specifies the port array signal to be monitored.
• port_id must be one of the predefined BOOLEAN port array identifiers with read access. Refer to
Chapter 2, ‘‘Language Elements.’’
• For event conditions, only the + or - alternatives are used.
• For state conditions, only the NOT alternative is used.
See Also: Chapter 6 CONDITION HANDLERS , Chapter 7 FILE INPUT/OUTPUT OPERATIONS ,
Relational Conditions, Appendix A, ‘‘KAREL Language Alphabetical Description’’
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A-245
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.17.12
POS Built-In Function
Purpose: Returns an XYZWPR composed of the specified location arguments (x,y,z), orientation
arguments (w,p,r), and configuration argument (c)
Syntax : POS(x, y, z, w, p, r, c)
Function Return Type : XYZWPR
Input/Output Parameters:
[in] x, y, z, w, p, and r :REAL
[in] c :CONFIG
%ENVIRONMENT Group :SYStem
Details:
• c must be a valid configuration for the robot attached to the controller. CNV_STR_CONF can be
used to convert a string to a CONFIG variable.
• x , y , and z are the Cartesian values of the location (in millimeters). Each argument must be in the
range±10000000 mm (±10 km). Otherwise, the program is paused with an error.
• w , p , and r are the yaw, pitch, and roll values of the orientation (in degrees). Each argument
must be in the range ±180 degrees. Otherwise, the program is paused with an error.
See Also: Chapter 8 POSITION DATA
Example: The following example uses the POS Built-In to designate numerically the POSITION
next_pos.
POS Built-In Function
CNV_STR_CONF(’n’, config_var, status)
next_pos = POS(100,-400.25,0.5,10,-45,30,config_var)
A.17.13
POS2JOINT Built-In Function
Purpose: This routine is used to convert Cartesian positions (in_pos) to joint angles (out_jnt) by
calling the inverse kinematics routine.
Syntax : POS2JOINT (ref_jnt, in_pos, uframe, utool, config_ref, wjnt_cfg, ext_ang, out_jnt, and
status).
Input/Output Parameters:
A-246
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] ref_jnt :JOINTPOS
[in] in_pos :POSITION
[in] uframe :POSITION
[in] utool :POSITION
[in] config_ref :INTEGER
[in] wjnt_cfg :CONFIG
[in] ext_ang :ARRAY OF REAL
[out] out_jnt :JOINTPOS
[out] status :INTEGER
%ENVIRONMENT Group :MOTN
Details:
•
The input ref_jnt are the reference joint angles that represent the robot's position just before
moving to the current position.
•
The input in_pos is the robot Cartesian position to be converted to joint angles.
•
The input uframe is the user frame for the Cartesian position.
•
The input utool is 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 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. 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 input wjnt_cfg is the wrist joint configuration. This value must be input when config_ref
corresponds to HALF_SOLN.
•
The input ext_ang contains the values of the joint angles for the extended axes if they exist.
•
The output out_jnt are the joint angles that correspond to the Cartesian position
A-247
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• The output status explains the status of the attempted operation. If it is not equal to 0, then an
error has occurred.
A.17.14
POS_REG_TYPE Built-In Procedure
Purpose: Returns the position representation of the specified position register
Syntax : POS_REG_TYPE (register_no, group_no, posn_type, num_axes, status)
Input/Output Parameters :
[in] register : INTEGER
[in] group_no : INTEGER
[out] posn_type : INTEGER
[out] num_axes : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group :REGOPE
Details:
• register_no specifies the position register.
• 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.
• posn_type returns the position type. posn_type is defined as follows:
— 1 :POSITION
— 2 :XYZWPR
— 6 :XYZWPREXT
— 9 :JOINTPOS
• num_axes returns number of axes in the representation if the position type is a JOINTPOS. If the
position type is an XYZWPREXT, only the number of extended axes is returned by num_axes.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: GET_POS_REG, GET_JPOS_REG, SET_POS_REG, SET_JPOS_REG Built-in
Procedures
A-248
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Example: The following example determines the position type in the register and uses the appropriate
built-in to get data.
POS_REG_TYPE Built-In Procedure
PROGRAM get_reg_data
%NOLOCKGROUP
%ENVIRONMENT REGOPE
VAR
entry: INTEGER
group_no: INTEGER
jpos: JOINTPOS
maxpregnum: integer
num_axes: INTEGER
posn_type: INTEGER
register_no: INTEGER
status: INTEGER
xyz: XYZWPR
xyzext: XYZWPREXTBEGIN
group_no = 1
GET_VAR(entry, ’*POSREG*’ ,’$MAXPREGNUM’, maxpregnum, status)
-- Loop for each register
FOR register_no = 1 to 10 DO
-- Get the position register type
POS_REG_TYPE(register_no, group_no, posn_type, num_axes, status)
-- Get the position register
WRITE(’PR[’, register_no, ’] of type ’, posn_type, CR)
SELECT posn_type OF
CASE (2):
xyz = GET_POS_REG(register_no, status)
CASE (6):
xyzext = GET_POS_REG(register_no, status)
CASE (9):
jpos = GET_JPOS_REG(register_no, status)
ELSE:
ENDSELECT
ENDFOR
END get_reg_data
A.17.15
POSITION Data Type
Purpose: Defines a variable, function return type, or routine parameter as POSITION data type
Syntax : POSITION <IN GROUP[n]>
Details:
A-249
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• A POSITION consists of a matrix defining the normal, orient, approach, and location vectors and
a component specifying a configuration string, for a total of 56 bytes.
• The configuration string indicates the joint placements and multiple turns that describe the
configuration of the robot when it is at a particular position.
• A POSITION is always referenced with respect to a specific coordinate frame.
• The POSITION data type can be used to represent a frame of reference in which case the
configuration component is ignored.
• Coordinate frame transformations can be done using the relative position operator (:).
• A POSITION can be assigned to other positional types.
• Valid POSITION operators are the
— Relative position (:) operator
— Approximately equal (>=<) operator
• A POSITION can be followed by IN GROUP[n], where n indicates the motion group with which
the data is to be used. The default is the group specified by the %DEFGROUP directive, or 1.
• Components of POSITION variables can be accessed or set as if they were defined as follows:
POSITION Data Type
POSITION = STRUCTURE
NORMAL: VECTOR
-- read-only
ORIENT: VECTOR
-- read-only
APPROACH: VECTOR
-- read-only
LOCATION: VECTOR
-- read-write
CONFIG_DATA: CONFIG
-- read-write
ENDSTRUCTURE
See Also: POS, UNPOS Built-In Functions
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A.17.16
POST_ERR Built-In Procedure
Purpose: Posts the error code and reason code to the error reporting system to display and keep
history of the errors
Syntax: POST_ERR(error_code, parameter, cause_code, severity)
Input/Output Parameters:
A-250
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
[in] error_code :INTEGER
[in] parameter :STRING
[in] cause_code :INTEGER
[in] severity :INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• error_code is the error to be posted.
• parameter will be included in error_code’s message if %s is specified in the dictionary text. If not
necessary, then enter the null string.
• cause_code is the reason for the error. 0 can be used if no cause is applicable.
• error_code and cause_code are in the following format:
ffccc (decimal)
where
ff represents the facility code of the error.
ccc represents the error code within the specified facility.
• severity is defined as follows:
0 : WARNING, no change in task execution
1 : PAUSE, all tasks and stop all motion
2 : ABORT, all tasks and cancel
See Also: ERR_DATA Built-In Procedure, the appropriate application-specific FANUC Robotics
Setup and Operations Manual, "Error Codes"
Example: Refer to Section B.13 , "Using the DISCTRL_ALPHA Built-in" (DCALP_EX.KL), for a
detailed program example.
A.17.17 POST_ERR_L Built-In Procedure
Purpose: Posts the error code with local severity to the error reporting system to display and keep
history of the errors
A-251
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Syntax: POST_ERR_L(error_code, parameter, cause_code, severity)
Input/Output Parameters:
[in] error_code :INTEGER
[in] parameter :STRING
[in] cause_code :INTEGER
[in] severity :INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• error_code is the error to be posted.
• parameter will be included in error_code’s message if %s is specified in the dictionary text. If not
necessary, then enter the null string.
• cause_code is the reason for the error. 0 can be used if no cause is applicable.
• error_code and cause_code are in the following format:
ffccc (decimal)
where
ff represents the facility code of the error.
ccc represents the error code within the specified facility.
• severity is defined as follows:
ERSEV_NONE : No severity
ERSEV_WARN : WARNING, no change in task execution
ERSEV_PAUSE : PAUSE Global, pause all tasks and stop all motion after current motion segment
ERSEV_PAUSEL : PAUSE Local, pause local task and stop all motion for local task after current
motion segment
ERSEV_STOP : STOP Global, pause all tasks and stop all motion
ERSEV_STOPL : STOP Local, pause local task and stop all motion for local task
ERSEV_SERVO : SERVO Global, turn off all servo power and pause all tasks
A-252
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
ERSEV_SERVOL : SERVO Local, turn off servo power for local task motion groups and pause
local tasks
ERSEV_ABORT : ABORT Global, abort all tasks and cancel all motion
ERSEV_ABORTL : ABORT Local, abort local task and cancel all motion for local task
ERSEV_SYSTEM : SYSTEM Global, system problem exist and prevent any further operation
See Also: POST_ERR Built-In
A.17.18
POST_SEMA Built-In Procedure
Purpose: Add one to the value of the indicated semaphore
Syntax : POST_SEMA(semaphore_no)
Input/Output Parameters:
[in] semaphore_ no : INTEGER
%ENVIRONMENT Group : MULTI
Details:
• The semaphore indicated by semaphore_no is incremented by one.
• semaphore_no must be in the range of 1 to the number of semaphores defined on the controller.
See Also: PEND_SEMA, CLEAR_SEMA Built-In Procedures, SEMA_COUNT Built-In Function,
Chapter 15 MULTI-TASKING ,
Example: See examples in Chapter 15 MULTI-TASKING
A.17.19
PRINT_FILE Built-In Procedure
Purpose: Prints the contents of an ASCII file to the default device
Syntax : PRINT_FILE(file_spec, nowait_sw, status)
Input/Output Parameters:
[in] file_spec :STRING
[in] nowait_sw :BOOLEAN
A-253
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
[out] status :INTEGER
%ENVIRONMENT Group : FDEV
Details:
• file_spec specifies the device, name, and type of the file to print.
• If nowait_sw is TRUE, execution of the program continues while the command is executing. If it
is FALSE, the program stops, including condition handlers, until the operation has completed.
If you have time critical condition handlers in your program, put them in another program that
executes as a separate task.
Note nowait_sw is not available in this release and should be set to FALSE.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
A.17.20
%PRIORITY Translator Directive
Purpose: Specifies task priority
Syntax : %PRIORITY = n
Details:
• n is the priority and is defined as follows:
1 to 89 : lower than motion, higher than user interface
90 to 99 : lower than user interface
• The lower the value, the higher the task priority.
• The default priority is 50. Refer to Section 15.4 , "Task Scheduling" for more information on
how the specified priority is converted into the system priority.
• The priority can be set during task execution by the SET_TSK_ATTR Built-In routine.
Example: Usually an error handling task pends on an error and when an error occurs, it processes the
error recovery as soon as possible. In this case, the error handling task might need to have a higher
priority than other tasks, so ‘‘n’’ should be less than 50.
%PRIORITY Translator Directive
%PRIORITY = 49
A-254
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
A.17.21
PROG_BACKUP Built-In Procedure
Purpose: Saves the specified program and all called programs from execution memory to a storage
device. If the called programs call other programs they will be saved recursively. You can specify
that any associated program variables be saved.
Syntax: PROG_BACKUP (file_spec, prog_type, max_size, write_prot, status)
Input/Output Parameters
[in] file_spec :STRING
[in] prog_type :INTEGER
[in] max_size: INTEGER
[in] write_prot: BOOLEAN
[out] status :INTEGER
%ENVIRONMENT Group: CORE
Details:
• file_spec specifies the device and program to save. If a file type is specified, it is ignored.
• prog_type specifies the type of programs to be saved. The valid types are:
PBR_VRTYPE :VR - programs which contain variables
PBR_MNTYPE :JB, PR, MR, TP
PBR_JBTYPE :JB - job programs only
PBR_PRTYPE :PR - process programs only
PBR_MRTYPE :MR - macro programs only
PBR_PCTYPE : VR - saves VR files not PC files
PBR_ALLTYPE :all programs VR, JB, PR, MR, TP
PBR_NVRTYPE :all programs except VR
PBR_NMRTYPE :JB, PR, TP (all TPs except Macros)
• max_size specifies the maximum size of disk space in kilobytes required to backup the programs.
If not enough memory is available on the storage device, no programs will be backed up and status
will equal 2002, “FILE-002 Device is Full”.
A-255
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
•
If the required disk space to backup the programs exceeds max_size the backup will continue.
The backup might still fail if there is not enough space to save all the programs. The return status
will equal 2002, “ FILE-002 Device is Full”. In this case a partial backup will exist. To prevent
this case be sure that max_size is large enough to prevent this error.
•
write_prot , if true, specifies that write protected programs should be saved. If false, specifies that
write protected programs should not be saved.
•
status explains the status of the attempted operation. If not equal to 0, then an error occurred.
•
The system will stay in the loop and handle as many programs as it can even when it gets an
error. For example, if there is one missing program out of eight, the remaining seven programs are
saved. In this case the error "Program does not exist" is returned to the user in status. An error
is posted in this case with the program name in the error for each program. The cause code is
whatever is returned from the save routine.
•
If a subdirectory is specified on the storage device, it will be created if it does not already exist.
All programs will be saved into the subdirectory.
•
If a file already exists but the no changes have occurred, the file is not overwritten.
•
If a file already exists but the program has been changed, it will be overwritten and no error is
returned.
•
A KAREL or teach pendant program of the same name with variables must exist in memory as a
called program or else the system will not save the VR.
•
The PROG_BACKUP, PROG_CLEAR and PROG_RESTORE builtins consider all references to
programs except for macros. This includes any programs referenced in the following statements:
CALL, RUN, ERROR_PROG, RESUME_PROG, and MONITOR.
Example: The following example saves ANS00003 with the appropriate extension to GMX_211
subdirectory on FR: device. It will save all programs that are called recursively by ANS00003
regardless of program type. It will not save KAREL variables. It will fail if there is less than 200k of
free space on the FR: device.
VAR
status: INTEGER
BEGIN
PROG_BACKUP(‘FR:\GMX_211\ANS00003’, PBR_NVRTYPE, 200, TRUE, status)
Example : The following example saves ANS00003 with the appropriate file extension to GMX_211
subdirectory on FR: device. It will save JB, PR, MR, or TP programs that are called recursively by
ANS00003. It will not save write-protected programs. It will fail if there is less than 100k of free
space on the FR: device.
A-256
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
VAR
status: INTEGER
BEGIN
PROG_BACKUP(‘FR:\GMX_211\ANS00003’, PBR_MNTYPE, 100, FALSE, status)
Example : The following example saves MAIN to MC: device with the appropriate file extension.
It will save all programs and variables that are called recursively by MAIN. It will fail if there is
less than 300k of free space on the MC: device.
VAR
status: INTEGER
BEGIN
PROG_BACKUP(‘MC:\MAIN’, PBR_ALLTYPE, 300, TRUE, status)
A-257
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.17.22
PROG_CLEAR Built-In Procedure
Purpose: Clear the specified program and all called programs from execution memory. If the called
programs call other programs they will be cleared recursively. You can specify that any associated
program variables also be cleared. Variables which are referenced from other programs will not
be cleared.
Syntax: PROG_CLEAR (prog_name, prog_type, status)
Input/Output Parameters:
[in] prog_name :STRING
[in] prog_type :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group: CORE
Details:
•
prog_name specifies the root program which is to be cleared.
•
prog_type specifies the type of programs to be cleared. The valid types are:
PBR_VRTYPE :VR - programs which contain variables
PBR_MNTYPE :JB, PR, MR, TP
PBR_JBTYPE :JB - job programs only
PBR_PRTYPE :PR - process programs only
PBR_MRTYPE :MR - macro programs only
PBR_PCTYPE : VR - saves VR files not PC files
PBR_ALLTYPE :all programs VR, JB, PR, MR, TP
PBR_NVRTYPE :all programs except VR
PBR_NMRTYPE :JB, PR, TP (all TPs except Macros)
•
status explains the status of the attempted operation. If not equal to 0, then an error occurred.
•
The system will stay in the loop and clear as many programs as it can. If one of the called
programs is missing, this is not an error. However, if that missing program calls other programs
those other programs will not be found and will not be cleared. Errors are posted with the
program name in the error for each program which is not cleared. The cause code is whatever
is returned from the clear routine.
A-258
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• Clearing of any VR data is subject to being referenced by another program. This error will
be ignored for any variable clear operation.
• If a programs which is identified for clearing is the selected program it will not be cleared.
The error “Program is in use” is returned in this case. As a countermeasure the use must use
SELECT_TPE() built-in to select a program which is not in the clear set.
• The PROG_BACKUP, PROG_CLEAR and PROG_RESTORE builtins consider all references to
programs except for macros. This includes any programs referenced in the following statements:
CALL, RUN, ERROR_PROG, RESUME_PROG, and MONITOR.
Example: The following example clears ANS00003.TP from memory. It will clear all programs that
are called recursively by ANS00003 regardless of program type and clear them from memory. It will
not clear write-protected programs. It will not clear any KAREL variables.
VAR
status: INTEGER
BEGIN
PROG_CLEAR(‘ANS00003.TP’, PBR_NVRTYPE, status)
Example: The following example clears ANS00003.TP program from memory. It will clear only JB,
PR, MR, and TP programs that are called recursively by ANS00003. It will not clear write-protected
programs.
VAR
status: INTEGER
BEGIN
PROG_CLEAR(‘ANS00003.TP’, PBR_MNTYPE, status)
A-259
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.17.23
PROG_RESTORE Built-In Procedure
Purpose: Restores (loads) the specified program and all called programs into execution memory.
If the called programs call other programs they will be loaded recursively. Any associated program
variables will also be loaded if the VR files exist.
Syntax: PROG_RESTORE (file_spec, status)
Input/Output Parameters:
[in] file_spec :STRING
[out] status :INTEGER
%ENVIRONMENT Group: CORE
Details:
•
file_spec specifies the storage device and program to restore. If a file type is specified, it
is ignored.
•
status explains the status of the attempted operation. If not equal to 0, then an error occurred.
•
The system will stay in the loop and handles as many programs as it can even when it gets an
error. For example, if there is one missing program out of eight, the remaining seven programs
are loaded. In this case the error "File does not exist" is returned to the user in status. An error
is posted in this case with the program name in the error for each program. The cause code is
whatever is returned from the load routine.
•
If a subdirectory is specified, the called programs are loaded from that subdirectory. Any extra
files in that subdirectory will not automatically be loaded.
•
If the program already exists, it will not be restored and no error is returned.
•
A KAREL or TP program of the same name must already exist in memory as a called program or
else the system will not load the VR.
•
VR types will be restored even if the variables already exist. That is the system will overwrite
any existing variable values with the values saved in the VR file.
•
ASCII programs (.LS) cannot be restored.
•
If not enough memory is available, then an error is returned and the restore is incomplete.
•
The PROG_BACKUP, PROG_CLEAR and PROG_RESTORE builtins consider all references to
programs except for macros. This includes any programs referenced in the following statements:
CALL, RUN, ERROR_PROG, RESUME_PROG, and MONITOR.
Example: The following example restores ANS00003.TP from GMX_211 subdirectory on FR:
device. It will restore all programs that are called recursively by ANS00003 regardless of program
type. It will restore VR files if they are in the restore directory.
A-260
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
VAR
status: INTEGER
BEGIN
PROG_RESTORE(‘FR:\GMX_211\ANS00003.TP’, status)
Example: The following example restores ANS00003.TP from GMX_211 subdirectory on FR:
device. It will restore only TP programs that are called recursively by ANS00003.
VAR
status: INTEGER
BEGIN
PROG_RESTORE(‘FR:\GMX_211\ANS00003’, status)
Example: The following example restores MAIN from MC: device by finding its file type. It will
restore all programs and variables that are called recursively by MAIN.
VAR
status: INTEGER
BEGIN
PROG_RESTORE(‘MC:\MAIN’, status)
A-261
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.17.24
PROG_LIST Built-In Procedure
Purpose: Returns a list of program names.
Syntax : prog_list(prog_name, prog_type, n_skip, format, ary_name, n_progs <,f_index>)
Input/Output Parameters :
[in] prog_name :STRING
[in] prog_type :INTEGER
[in] n_skip :INTEGER
[in] format :INTEGER
[out] ary_name :ARRAY of string
[out] n_progs :INTEGER
[out] status :INTEGER
[in,out] f_index :INTEGER
%ENVIRONMENT Group :BYNAM
Details:
• prog_name specifies the name of the program(s) to be returned in ary_name . prog_name may
use the wildcard (*) character, to indicate that all programs matching the prog_type should be
returned in ary_name .
• prog_type specifies the type of programs to be retrieved. The valid types are:
1 :VR - programs which contain only variables
2 :JB, PR, MR, TP3 :JB - job programs only
4 :PR - process programs only
5 :MR - macro programs only
6 :PC - KAREL programs only
7 :all programs VR, JB, PR, MR, TP, PC
8 :all programs except VR
A-262
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
•
n_skip This parameter can only be used when using * for the program name and 7 for the program
type. Otherwise used the f_index parameter for multiple calls when more programs exist than the
declared length of ary_name. Set n_skip to 0 the first time you use PROG_LIST. If ary_name
is completely filled with program names, copy the array to another ARRAY of STRINGS and
execute PROG_LIST again with n_skip equal to n_skip + n_progs . The call to PROG_LIST will
then skip the programs found in the previous passes and locate only the remaining programs..
•
format specifies the format of the program name. The following values are valid for format :
1 :program name only, no blanks
2 :’program name program type’
total length = 15 characters
•
prog_name = 12 characters followed by a space
•
prog_type = 2 characters
•
ary_name is an ARRAY of STRING used to store the program names.
•
n_progs is the number of variables stored in the ary_name .
•
status will return zero if successful.
•
f_index is an optional parameter for fast indexing. If you specify prog_name as a complex
wildcard (anything other than the straight *), then you should use this parameter. The first call to
PROG_LIST set f_index and n_skip both to zero. f_index will then be used internally to quickly
find the next prog_name. DO NOT change f_index once a listing for a particular prog_name
has begun.
See Also: VAR_LIST Built-In Procedure
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.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.17.25
PROGRAM Statement
Purpose: Identifies the program name in a KAREL source program
Syntax : PROGRAM prog_name
where:
prog_name : a valid KAREL identifier
A-263
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Details:
• It must be the first statement (other than comments) in a program.
• The identifier used to name a program cannot be used in the program for any other purpose, such
as to identify a variable or constant.
• prog_name must also appear in the END statement that marks the end of the executable section
of the program.
• The program name can be used to call the program as a procedure routine from within a program
in the same way routine names are used to call procedure routines.
Example: Refer to Appendix B , "KAREL Example Programs," for more detailed examples of
how to use the PROGRAM Statement.
A.17.26
PULSE Action
Purpose: Pulses a digital output port for a specified number of milliseconds
Syntax : PULSE DOUT[port_no] FOR time_in_ms
where:
port_no : an INTEGER variable or literal
time_in_ms : an INTEGER
Details:
• port_no must be a valid digital output port number.
• time_in_ms specifies the duration of the pulse in milliseconds.
• If time_in_ms duration is zero, no pulse will occur. Otherwise, the period is rounded up to
the next multiple of 8 milliseconds.
• A pulse always turns on the port at the start of the pulse and turns off the port at the end of
the pulse.
• If the port is ‘‘normally on,’’ negative pulses can be accomplished by setting the port to reversed
polarity, or by executing the following sequence:
DOUT[n] = FALSE
DELAY x
DOUT[n] = TRUE
• NOWAIT is not allowed in a PULSE action.
• If the program is paused while a pulse is in progress, the pulse will end at the correct time.
A-264
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• If the program is aborted while a pulse is in progress, the port stays in whatever state it was in
when the abort occurred.
• If time_in_ms is negative or greater than 86,400,000 (24 hours), the program is aborted with an
error.
See Also: Chapter 6 CONDITION HANDLERS , Chapter 7 FILE INPUT/OUTPUT OPERATIONS
Example: Refer to Section B.1 , "Setting Up Digital Output Ports for Monitoring" (DOUT_EX.KL)
for a detailed program example.
A.17.27
PULSE Statement
Purpose: Pulses a digital output port for a specified number of milliseconds.
Syntax : PULSE DOUT[port_no] FOR time_in_ms < NOWAIT >
where:
port_no : an INTEGER variable or literal
time_in_ms : an INTEGER
Details:
• port_no must be a valid digital output port number.
• time_in_ms specifies the duration of the pulse in milliseconds.
• If time_in_ms duration is zero, no pulse will occur. Otherwise, the period is rounded up to
the next multiple of 8 milliseconds.
The actual duration of the pulse will be from zero to 8 milliseconds less than the rounded value.
For example, if 100 is specified, it is rounded up to 104 (the next multiple of 8) milliseconds. The
actual duration will be from 96 to 104 milliseconds.
• A pulse always turns on the port at the start of the pulse and turns off the port at the end of
the pulse.
• If the port is ‘‘normally on,’’ negative pulses can be accomplished by setting the port to reversed
polarity, or by executing the following sequence:
DOUT[n] = FALSE
DELAY x
DOUT[n] = TRUE
A-265
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
• If NOWAIT is specified in a PULSE statement, the next KAREL statement will be executed
concurrently with the pulse.
• If NOWAIT is not specified in a PULSE statement, the next KAREL statement will not be
executed until the pulse is completed.
See Also: Appendix E , ‘‘Syntax Diagrams’’ for more syntax information
Example: In the following example a digital output is pulsed, followed by the pulsing of a second
digital output. Because NOWAIT is specified, DOUT[start_air] will be executed before DOUT[5] is
completed.
PULSE Statement
PULSE DOUT[5] FOR (seconds * 1000) NOWAIT
PULSE DOUT[start_air] FOR 50 NOWAIT
A.17.28
PURGE CONDITION Statement
Purpose: Deletes the definition of a condition handler from the system
Syntax : PURGE CONDITION[cond_hand_no]
where:
cond_hand_no : an INTEGER expression
Details:
• The statement has no effect if there is no condition handler defined with the specified number.
• The PURGE CONDITION Statement is used only to purge global condition handlers.
• The PURGE CONDITION Statement will purge enabled conditions.
• If a condition handler with the specified number was previously defined, it must be purged
before it is replaced with a new one.
See Also: ENABLE CONDITION Statement Chapter 6 CONDITION HANDLERS , Appendix E ,
‘‘Syntax Diagrams’’ for more syntax information
Example: In the following example, if the BOOLEAN variable ignore_cond is TRUE, the
global condition handler, CONDITION[1], will be purged using the PURGE statement; otherwise
CONDITION[1] is enabled.
PURGE CONDITION Statement
IF ignore_cond THEN
PURGE CONDITION[1]
A-266
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
ELSE
ENABLE CONDITION[1]
ENDIF
A.17.29
PURGE_DEV Built-In Procedure
Purpose: Purges the specified memory file device by freeing any used blocks that are no longer
needed
Syntax : PURGE_DEV (device, status)
Input/Output Parameters :
[in] device : STRING
[out] status : INTEGER
%ENVIRONMENT Group :FDEV
Details:
• device specifies the memory file device to purge. device should be set to ’FR:’ for FROM disk,
’RD:’ for RAM disk, or ’MF:’ for both disks.
• The purge operation is only necessary when the device does not have enough memory to perform
an operation. The ’FR:’ device will return 85001 if the FROM disk is full. The ’RD:’ device will
return 85020 if the RAM disk is full.
• The purge operation will erase file blocks that were previously used, but no longer needed. These
are called garbage blocks. The FROM disk may contain many garbage blocks if files are deleted
or overwritten. The RAM disk does not normally contain garbage blocks, but they can occur
when power is removed during a file copy.
• The VOL_SPACE built-in can be used to determine the number of garbage blocks on the FROM
disk. Hardware limitations may reduce the number of blocks actually freed.
• The device must be mounted and no files can be open on the device or an error will be returned.
• status explains the status of the attempted operation. If not equal to 0 then an error occurred.
85023 is returned if no errors occurred, but no blocks were purged.
Example: Return to Section B.9 , "Using the File and Device Built-Ins" (FILE_EX.KL), for a more
detailed program example.
A-267
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
A.17.30
PUSH_KEY_RD Built-In Procedure
Purpose: Suspend key input from a keyboard device
Syntax : PUSH_KEY_RD(key_dev_name, key_mask, pop_index, status)
Input/Output Parameters:
[in] key_dev_name :STRING
[in] key_mask :INTEGER
[out] pop_index :INTEGER
[out] status :INTEGER
%ENVIRONMENT Group :PBCORE
Details:
•
Suspends all read requests on the specified keyboard device that uses (either as accept_mask or
term_mask) any of the specified key classes.
•
If there are no read requests active, a null set of inputs is recorded as suspended. This is not an
error.
•
key_dev_name must be one of the keyboard devices already defined:
’TPKB’ :Teach Pendant Keyboard Device
’CRKB’ :CRT Keyboard Device
•
key_mask is a bit-wise mask indicating the classes of characters that will be suspended. This
should be an OR of the constants defined in the include file klevkmsk.kl.
kc_display :Displayable keys
kc_func_key :Function keys
kc_keypad :Keypad and Edit keys
kc_enter_key :Enter and Return keys
kc_delete :Delete and Backspace keys
kc_lr_arw :Left and Right Arrow keys
kc_ud_arw :Up and Down Arrow keys
kc_other :Other keys (such as Prev)
A-268
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
• pop_id is returned and should be used in a call to POP_KEY_RD to re-activate the read requests.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred.
See Also: POP_KEY_RD Built-In Procedure
Example: Refer to the READ_KB Built-In Procedure for an example.
A.18
- Q - KAREL LANGUAGE DESCRIPTION
A.18.1
QUEUE_TYPE Data Type
Purpose: Defines the data type for use in QUEUE built-in routines
Syntax : queue_type = STRUCTURE
n_entries : INTEGER
sequence_no : INTEGER
head : INTEGER
tail : INTEGER
ENDSTRUCTURE
Details:
• queue_type is used to initialize and maintain queue data for the QUEUE built-in routines. Do
not change this data; it is used internally.
See Also: APPEND_QUEUE, DELETE_QUEUE, INSERT_QUEUE, COPY_QUEUE,
GET_QUEUE, INIT_QUEUE, MODIFY_QUEUE Built-In Procedures
A.19
- R - KAREL LANGUAGE DESCRIPTION
A.19.1
READ Statement
Purpose: Reads data from a serial I/O device or file
Syntax : READ < file_var > (data_item {,data_item})
where:
file_var : a FILE variable
A-269
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
data_item : a variable identifier and its optional format specifiers or the reserved word CR
Details:
•
If file_var is not specified in a READ statement the default TPDISPLAY is used. %CRTDEVICE
directive will change the default to INPUT.
•
If file_var is specified, it must be one of the input devices (INPUT, CRTPROMPT, TPDISPLAY,
TPPROMPT) or a variable that was set in the OPEN FILE statement.
•
If file_var attribute was set with the UF option, data is transmitted into the specified variables
in binary form. Otherwise, data is transmitted as ASCII text.
•
data_item can be a system variable that has RW access or a user-defined variable.
•
When the READ statement is executed, data is read beginning with the next nonblank input
character and ending with the last character before the next blank, end of line, or end of file
for all input types except STRING.
•
If data_item is of type ARRAY, a subscript must be provided.
•
If data_item is of type PATH, you can specify that the entire path be read, a specific node be read
([n]), or a range of nodes be read ([n .. m]).
•
Optional format specifiers can be used to control the amount of data read for each data_item .
The effect of format specifiers depends on the data type of the item being read and on whether the
data is in text (ASCII) or binary (unformatted) form.
•
The reserved word CR, which can be used as a data item, specifies that any remaining data in
the current input line is to be ignored. The next data item will be read from the start of the
next input line.
•
If reading from a file and any errors occur during input, the variable being read and all subsequent
variables up to CR in the data list are set uninitialized.
•
If file_var is a window device and any errors occur during input, an error message is displayed
indicating the bad data item and you are prompted to enter a replacement for the invalid data item
and to reenter all subsequent items.
•
Use IO_STATUS (file_var) to determine if the read operation was successful.
Note Read CR should never be used in unformatted mode.
See Also: Chapter 7 FILE INPUT/OUTPUT OPERATIONS , for more information on the READ
format specifiers, IO_STATUS Built-In Function, Appendix E , ‘‘Syntax Diagrams,’’ for more syntax
information
Example: Refer to the following sections for detailed program examples:
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)
A-270
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
Section B.14 , "Applying Offsets to a Copied Teach Pendant Program" (CPY_TP.KL)
A.19.2
READ_DICT Built-In Procedure
Purpose: Reads information from a dictionary
Syntax : READ_DICT(dict_name, element_no, ksta, first_line, last_line, status)
Input/Output Parameters:
[in] dict_name : STRING
[in] element_no : INTEGER
[out] ksta : ARRAY OF STRING
[in] first_line : INTEGER
[out] last_line : INTEGER
[out] status : INTEGER
%ENVIRONMENT Group :PBCORE
Details:
• dict_name specifies the name of the dictionary from which to read.
• element_no specifies the element number to read. This element number is designated with
a $ in the dictionary file.
• ksta is a KAREL STRING ARRAY used to store the information being read from the dictionary
text file.
• If ksta is too small to store all the data, then the data is truncated and status is set to 33008,
"Dictionary Element Truncated."
• first_line indicates the array element of ksta , at which to begin storing the information.
• last_line returns a value indicating the last element used in the ksta array.
• status explains the status of the attempted operation. If not equal to 0, then an error occurred
reading the element from the dictionary file.
• &new_line is the only reserved attribute code that can be read from dictionary text files using
READ_DICT. The READ_DICT Built-In ignores all other reserved attribute codes.
See Also: ADD_DICT, WRITE_DICT, REMOVE_DICT Built-In Procedures. Refer to the program
example for the DISCTRL_LIST Built-In Procedure. Chapter 10 DICTIONARIES AND FORMS
A-271
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
MARRC75KR07091E Rev D
Example: Refer to Section B.12 , "Displaying a List From a Dictionary File" (DCLST_EX.KL), for a
detailed program example.
A.19.3
READ_DICT_V Built-In-Procedure
Purpose: Reads information from a dictionary with formatted variables
Syntax : READ_DICT_V(dict_name, element_no, value_array, ksta, status)
Input/Output Parameters:
[in] dict_name : STRING
[in] element_no : INTEGER
[in] value_array : ARRAY OF STRING
[out] ksta : ARRAY OF STRING
[out] status : INTEGER
%ENVIRONMENT Group :UIF
Details:
• dict_name specifies the name of the dictionary from which to read.
• element_no specifies the element number to read. This number is designated with a $ in the
dictionary file.
• value_array is an array of variable names that corresponds to each formatted data item in the
dictionary text. 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 not
specified, then the current program being executed is used.
— var_name must refer to a static variable.
— var_name may contain node numbers, field names, and/or subscripts.
• ksta is a KAREL STRING ARRAY used to store the information that is being read from the
dictionary text file.
• If ksta is too small to store all the data, then the data is truncated and status is set to 33008,
"Dictionary Element Truncated."
• status explains the status of the attempted operation. If not equal to 0, then an error occurred
reading the element from the dictionary file.
• &new_line is the only reserved attribute code that can be read from dictionary text files using
READ_DICT_V. The READ_DICT_V Built-In ignores all other reserved attribute codes.
A-272
MARRC75KR07091E Rev D
A. KAREL LANGUAGE ALPHABETICAL DESCRIPTION
See Also: WRITE_DICT_V Built-In Procedure, Chapter 10 DICTIONARIES AND FORMS
Example: In the following example, TPTASKEG.TX contains dictionary text information which will
display a system variable. This information is the first element in the dictionary. Element numbers
start at 0. util_prog uses READ_DICT_V to read in the text and display it on the teach pendant.
READ_DICT_V Built-In Procedure
----------------------------------------------
TPTASKEG.TX
----------------------------------------------
$ "Maximum number of tasks = %d"
----------------------------------------------
UTILITY PROGRAM:
----------------------------------------------
PROGRAM util_prog
%ENVIRONMENT uif
VAR
ksta: ARRAY[1] OF STRING[40]
status: INTEGER
value_array: ARRAY[1] OF STRING[30]
BEGIN
value_array[1] = ’[*system*].$scr.$maxnumtask’
ADD_DICT(’TPTASKEG’, ’TASK’, dp_default, dp_open, status)
READ_DICT_V(’TASK’, 0, value_array, ksta, status)
WRITE(ksta[i], cr)
END util_prog
A.19.4
READ_KB Built-In Procedure
Purpose: Read from a keyboard device and wait for completion
Syntax : READ_KB(file_var, buffer, buffer_size, accept_mask, term_mask, time_out, init_data,
n_chars_got, term_char, status)
Input/Output Parameters:
[in] file_var : FILE
[out] buffer : STRING
[in] buffer_size : INTEGER
[in] accept_mask : INTEGER
[in] time_out : INTEGER
A-273