B0193ne F

® B0193NE
REV F
I/A Series®
Integrated Control Configurator
Application Programming Interface
November 30, 1998
HOST AP or AW
pdef/olist
CSA ICC and ICCAPI Control Station
Work file
Checkpoint file
Foxboro and I/A Series are registered trademarks of The Foxboro Company.
UNIX is a trademark of X/Open Company LTD.
Copyright 1994-1998 by The Foxboro Company

All rights reserved
SOFTWARE LICENSE AND COPYRIGHT INFORMATION

Before using the Foxboro supplied software supported by this Foxboro documentation, you
should read and understand the following information concerning copyrighted software.
1. The license provisions in the Foxboro Software License for your system govern
your obligations and usage rights to the software described in this documentation.
If any portion of those license provisions is violated, The Foxboro Company will
no longer provide you with support services and assumes no further responsibili-
ties for your system or its operation.
2. All software issued by The Foxboro Company, and copies of the software that you
are specifically permitted to make, are protected in accordance with Federal copy-
right laws. It is illegal to make copies of any software media provided to you by
The Foxboro Company for any purpose other than those purposes mentioned in
the Foxboro Software License.
Contents
Preface............................................................................................................................. vii
Revision Information ........................................................................................................ vii
1. Theory of Operation ................................................................................................... 1

ICCAPI Components ......................................................................................................... 1
Features of the ICCAPI ....................................................................................................... 1
External Interface ................................................................................................................ 3
The pdef and olist Files ....................................................................................................... 3
Principles of Operation ....................................................................................................... 4
ICCAPI Function Library .............................................................................................. 4
Session-Based Operation ............................................................................................ 4
Transactions .............................................................................................................. 5
Security Levels ........................................................................................................... 6
Logging ...................................................................................................................... 6
Partial List Processing ................................................................................................ 6
Load and Save Considerations ................................................................................... 7
Characters and Case Conversion ................................................................................ 7
Database Creation ...................................................................................................... 7
Special Compounds and Blocks ................................................................................. 8
Block Order ............................................................................................................... 8
Error Handling .......................................................................................................... 9
Data Structures ................................................................................................................... 9
Data Structures used in Function Interface ..................................................................... 9
Parameter Values ....................................................................................................... 9
Default Parameter Information ................................................................................ 10
Driver Task ....................................................................................................................... 11
Overview ...................................................................................................................... 11
Driver Task Input/Output Streams .............................................................................. 11
Command Input Stream .......................................................................................... 12
Command Output Stream ....................................................................................... 13
Command Output Stream Example: ....................................................................... 13
Data Output Stream ................................................................................................ 13
2. ICCAPI Function Calls ............................................................................................. 15

General Conventions ........................................................................................................ 15
Compound/Block Name .............................................................................................. 15
Compound and Block Position .................................................................................... 15
Function Return Values ................................................................................................ 16
iii
B0193NE – Rev F Contents
CSA Functions .................................................................................................................. 16

ICCAPI Functions ............................................................................................................ 16
ICCopen() – Session Open ........................................................................................... 17
ICCclose() – Session Close ........................................................................................... 18
ICCoverride() – Lock Override .................................................................................... 18
ICCget() – Get Parameters ........................................................................................... 19
ICCseqget() – Get Sequence Code ............................................................................... 22
ICCgetdef() – Get Default Information ....................................................................... 23
ICCadd() – Add Compound or Block .......................................................................... 24
ICCseqput() – Replace Sequence Code ........................................................................ 24
ICCladget() – Get Plb Source File ................................................................................ 25
ICCladput() – Replace Plb Source File ......................................................................... 26
ICCladcmp1() – Compile the Plb Source File .............................................................. 26
ICCdelete() – Delete Compound or Block ................................................................... 27
ICCmodify() – Modify Compound or Block ................................................................ 28
ICCmove() – Move Compound or Block ..................................................................... 28
ICCcopy() – Copy Block .............................................................................................. 29
ICCinit() – Initialize CP Database ............................................................................... 30
ICCupload() – Upload Database from CP ................................................................... 30
ICCchkpt() – Checkpoint Control Station Database .................................................... 31
ICCshrink() – Shrink Workfile .................................................................................... 31
ICCsave() – Save Data to Disk File .............................................................................. 32
ICCload() – Load Data from Disk File ......................................................................... 33
ICClogopen() – Open Log File .................................................................................... 33
ICClogclose() – Close Log File ..................................................................................... 35
ICClogset() – Set Logging Options .............................................................................. 35
ICClogflags() – Query Logging Options ...................................................................... 35
ICCerr() – Get Error Information ................................................................................ 36
3. ICCAPI Driver Task Commands .............................................................................. 37

Driver Task Command Output ........................................................................................ 37
Data Output ..................................................................................................................... 38
Data Input ........................................................................................................................ 38
Input Stream Timeout ...................................................................................................... 39
Error Handling ................................................................................................................. 39
OPEN Command ............................................................................................................. 39
OVERRIDE Command ................................................................................................... 40
CLOSE Command ........................................................................................................... 41
GET Command ................................................................................................................ 41
GETORDER Command .................................................................................................. 42
GETSEQ Command ........................................................................................................ 43
iv
Contents B0193NE – Rev F
GETDEF Command ........................................................................................................ 44

LIST Command ................................................................................................................ 45
List Compounds/Blocks Command .............................................................................. 45
List CPS/Volumes Command ...................................................................................... 47
List Station Types Command ....................................................................................... 47
List Block Types Command ......................................................................................... 48
ADD Command ............................................................................................................... 48
CMPLSEQ Command ..................................................................................................... 49
PUTSEQ Command ........................................................................................................ 50
GETPLB Command ......................................................................................................... 50
PUTPLB Command ......................................................................................................... 51
CMPLPLB Command ...................................................................................................... 52
DELETE Command ......................................................................................................... 52
MODIFY Command ........................................................................................................ 53
MOVE Command ............................................................................................................ 53
COPY Command ............................................................................................................. 54
INITIALIZE Command ................................................................................................... 55
UPLOAD Command ....................................................................................................... 55
CHECKPOINT Command ............................................................................................. 56
SHRINK Command ......................................................................................................... 56
SAVE Command .............................................................................................................. 57
LOAD Command ............................................................................................................. 57
TIMEOUT Command ..................................................................................................... 58
LOGOPEN Command .................................................................................................... 59
LOGCLOSE Command ................................................................................................... 60
LOGSET Command ........................................................................................................ 60
LOGSTAT Command ...................................................................................................... 60
LOGOPTION Command ................................................................................................ 61
SHELL Command ............................................................................................................ 61
CALL Command .............................................................................................................. 62
EXIT Command ............................................................................................................... 62
4. Using the ICCAPI..................................................................................................... 63

Installation and Initialization ............................................................................................ 63
Operation ......................................................................................................................... 63
v
B0193NE – Rev F Contents
ICCAPI Function Interface .......................................................................................... 63

Application Build ..................................................................................................... 63
ICCAPI Driver Task .................................................................................................... 63
Utilities ............................................................................................................................. 64
LOAD_ALL Script ....................................................................................................... 64
SAVE_ALL Script ........................................................................................................ 65
LOAD_ALL/SAVE_ALL Recommendations ............................................................... 65
ICCPRT Script ............................................................................................................ 66
5. Writing Applications Using the Driver Task ............................................................. 69

Replacing iccprt and bldcio ............................................................................................... 69
Sample Implementation .................................................................................................... 70
Appendix A. Driver Task Commands — Quick Reference ............................................ 75
Index .............................................................................................................................. 77
vi
Preface
This document describes the functions and operations of the Integrated Control Configurator
Application Programming Interface (ICCAPI).
The ICCAPI is a package that allows application programs to manipulate the databases that
define compounds and blocks in CPs and CP-like stations. It supports many of the operations
supported by the Integrated Control Configurator.
Revision Information
For Release 6.1.1, the following change was made:
Chapter 4 “Using the ICCAPI”
♦ Corrected example for the ICCPRT Script.
NOTE
The term “CP” is used as a general term to refer to any control station (for
example, gateways), not only the CP10 and CP30 stations.
vii
B0193NE – Rev F Preface
viii
1. Theory of Operation
This section contains information on the features, components, principles of
operation, and data structure of the ICCAPI. Also in this section is a list of the
external interfaces for the ICCAPI: the pdef and olist files define all the possible
block types, their configurable parameters, and their associated default values for
a given release of I/A Series. The ICCAPI Driver Task reads commands, by
default, from stdin, and writes its output, by default, to stderr and stdout.
The Integrated Control and I/O Configurator Application Program Interface (ICCAPI) pro-
vides an interface to applications that need to manipulate the three databases used by the Inte-
grated Control and I/O Configurator (ICC):
♦ CP memory resident database and associated checkpoint file
♦ ICC workfile database
♦ CSA database
With the aid of the ICCAPI, applications can modify the databases in a manner consistent
with the methods used by the ICC. The ICCAPI performs all checks necessary to prevent
duplicate compound or block names. When accessing the databases, the ICCAPI conforms to
the protocol followed by the ICC with regard to locking the checkpoint file and establishing a
connection with the CP.
ICCAPI Components
The ICCAPI has two major components:
♦ A library of functions. An application running on an AP/AW can link into this
library to gain access to the ICCAPI capabilities.
♦ A Driver Task that uses the library, interprets commands from a user-specified
input file, and outputs responses to a user-specified output file.
A set of useful scripts involving the Driver Task is also provided. For example, you
can use the iccprt script to generate reports for any block in a given station. The
source code is supplied to serve as an example of programming with the API driver
task.
Features of the ICCAPI

The ICCAPI is fully compatible with the ICC and supports nearly all the functionality of the
ICC. The principal functional characteristics of the ICCAPI are:
♦ Supports library volumes transparently to the user, as does the ICC.
♦ Supports checkpoints of the CP database on session close and on request from the
user. The ICCAPI does not wait for checkpoint operations to complete on session
close. The user has the option to wait for a checkpoint operation requested
through the checkpoint command or ICCchkpt() function to complete.
1
B0193NE – Rev F 1. Theory of Operation
♦ Automatically creates the required entries in the databases for a CP or library vol-
ume when it detects that a particular session is the initial access of a CP or library
volume.
♦ Supports all current block types, including sequence and PLB blocks.
♦ Checks compound and block parameter names supplied by the user for validity. It
also checks parameter values to the extent that the Configurator does (for example,
it checks that values that are supposed to be numbers contain only numeric char-
acters and values that are supposed to be connections actually look like
connections). Further checking is left to the CP, since the information and logic
needed to perform such checking are in the CP.
♦ Supports manipulation of CPs hosted by the station on which the ICCAPI is run-
ning and of CPs hosted by remote stations.
♦ Does not limit the number of compounds and blocks that can be configured for a
CP or a volume. It is up to the user to keep track of CP resources and to limit
compounds and blocks so as not to overrun those resources.
♦ All function calls to the ICCAPI (except ICCchkpt()) are synchronous and do not
return to the caller until the operation either completes or fails.
♦ Supports several levels of security for a session. These vary from a strictly read-only
level that disallows any changes, to a fully enabled level that allows all operations
supported by the ICCAPI.
♦ Supports a checkpoint file lock override function. Since the ICCAPI Function
Library is used during application development, it is possible that a task using the
library exits without closing a session, leaving the checkpoint file locked.
♦ Supports saving to and loading from disk directories and other mounted devices,
but does not have built-in device mount or device formatting support, nor does it
support saving or loading more than one compound per function call. The caller
must ensure that the storage device is mounted and contains a valid file system
before calling the ICCAPI save/load functions. If more than one compound is to
be saved or loaded, the caller must repeatedly call the appropriate ICCAPI func-
tion. If an error is encountered while loading a compound and its blocks, the
compound is deleted.
♦ Uses the I/A Series err_rpt() facility to report significant events such as checkpoint
file lock overrides to the System Monitor.
♦ The function library and the include files in it are ANSI compliant. All function
names begin with the letters “ICC”, and all constants begin with the letters “ICC”.
♦ All log messages generated by the ICCAPI are formatted with machine readability
(for example, grep) in mind.
♦ The ICCAPI uses the PDEF data from the AP that hosts the CP or volume being
accessed. There is no guarantee that the PDEF data on a given AP matches that on
any other AP, although usually they match.
♦ Connectable parameters may be configured with shared variable names and Bool-
ean parameters.
2
1. Theory of Operation B0193NE – Rev F
External Interface
The ICCAPI interfaces with the following:
♦ Any task that links in the library and calls its functions. A task using the ICCAPI
interfaces with the ICCAPI library using function calls (described later in this doc-
ument) or with the ICCAPI Driver Task using command and response files.
♦ Software Processing. The ICCAPI uses Software Processing routines to obtain sys-
tem configuration information pertinent to configuration operations, and to lock
and unlock the checkpoint file.
♦ Software Manager. The ICCAPI communicates with the Software Manager to per-
form checkpoints of CP databases.
♦ Compound Summary Access (CSA). The ICCAPI uses CSA library calls to deter-
mine whether specific compound and block names exist in the system.
♦ The CP being manipulated. All modifications to the CP database are sent to the
CP DB Installer through IPC messages.
♦ The I/A Series error reporter (err_rpt()). The ICCAPI calls the err_rpt() function
to report significant events to the System Monitor.
♦ Driver Task Input and Output Files. The ICCAPI Driver Task interfaces with the
ICCAPI function library and with its input and output files. Once started, the
Driver Task reads its input command file and interprets the commands it finds
there. It writes any output to its output files.
The pdef and olist Files

The pdef and olist files define all the possible block types, their configurable parameters, and
their associated default values for a given release of I/A Series. The ICC and the ICCAPI can
work only on block types defined in the pdef/olist pair. The function of the pdef/olist files in
relation to the ICC and ICCAPI is illustrated in Figure 1-1.
External Interface 3
HOST AP or AW
Upload from
control station
pdef/olist via Upload task
upon request by
ICC and ICCAPI
CSA ICC and ICCAPI Control Station
Work file
Checkpoint file
Checkpoint occurs
via Software Manager
upon request by
ICC and ICCAPI
Figure 1-1. Function of the pdef/olist Files
CSA, a task running on the I/A Series system, guarantees compound name uniqueness
throughout the system. CSA is updated with the block names for each configured compound.
The work file is created for each control station and volume by the ICC and ICCAPI. It con-
tains all blocks and compounds configured for the station together with the associated param-
eter values.
The ICC and ICCAPI send the blocks and compounds, together with their configurable
parameter values, to the memory in the control station. All block parameters, both the config-
urable and the non-configurable, are stored there.
Principles of Operation
ICCAPI Function Library
Session-Based Operation
Operation of the ICCAPI is based on the concept of a session. Only one CP or library volume
can be accessed during each session. There are specific functions in the ICCAPI to open and
close each session.
A task using the ICCAPI function library may conduct several sessions during each execution
of the task, as long as the sessions are sequential. The ICCAPI does not support more than
one simultaneous session per instance.
4
The session open function ensures sole access to a given CP or library volume by locking the
checkpoint file.
During each session, several operations (transactions) may take place, such as showing the
parameters of a compound or block, adding or deleting a block, and so on.
On session close, the ICCAPI performs all necessary processing, including disconnecting
from the CP and unlocking the checkpoint file (no checkpoint is performed if no changes
have been made).
A task using the ICCAPI may exit prematurely, leaving a CP checkpoint file locked, prevent-
ing subsequent access to the CP. For this reason, the ICCAPI allows a lock override operation.
Transactions
The following transactions or operations are supported during an ICCAPI session:
1. Obtain various lists, including the following:
a. Values of all parameters, the standard parameters, or a user-specified subset of
parameters for a single compound or block or for multiple compounds and
blocks
b. Default parameters for a specified block type
c. All the CPs or library volumes in the system:
All the blocks in a specified compound
All the compounds in a CP or library volume
2. Add a compound or block.
3. Delete a compound or block.
4. Copy a block from any CP or library volume in the system.
5. Modify one or more parameters of a compound or block.
6. Checkpoint the CP database.
7. Move a compound within the CP or a block within a compound.
8. Optimize the storage of the workfile.
9. Save a compound to a file in SAVEALL format.
10. Load a compound from a file in SAVEALL format.
11. Initialize the database for a CP or library volume.
12. Upload the database from a CP: a single block, a single compound, or all com-
pounds may be uploaded.
The function calls and Driver Task commands for each of these transaction types are
described later in this document.
Principles of Operation 5
Security Levels
The ICCAPI supports several levels of security for a given session. The desired security level is
specified when the session is opened. The ICCAPI provides no facilities for determining
whether a caller should be able to use a given security level – that is the caller’s responsibility.
The following list shows the security levels:
ICC_SEC_READONLY — read only: no operations that change anything are
allowed.
ICC_SEC_CHKPT — allows operations allowed by ICC_SEC_READONLY and
checkpoint operations.
ICC_SEC_UPLOAD — allows operations allowed by ICC_SEC_CHKPT and lets
the caller perform an upload command.
ICC_SEC_MODIFY — allows operations allowed by ICC_SEC_UPLOAD and lets
the caller modify the parameters of existing compounds and blocks.
ICC_SEC_ALL — allows all ICCAPI operations.
Logging
The ICCAPI has facilities for printing supplementary information about its operations to
file(s). The information is useful in debugging applications using the ICCAPI. Log messages
can be sent to two locations:
♦ Significant events are logged to the System Monitor using the err_rpt() facility.
Events include opening and closing non-read-only sessions, lock overrides, and so
on.
♦ Several levels of logging can be enabled and sent to a file or stream specified by the
calling task.
When the ICCAPI library is initialized, its log file is stderr, and error message logging is dis-
abled.
Partial List Processing

When the ICCget() function is called, the caller supplies an array of fixed length strings in
which the returned values are to be placed (see the section “Data Structures” on page 9). The
ICCget() function may be asked to return some or all the parameters for one or more com-
pounds and blocks. The conventions followed by ICCget() are:
♦ If the caller provides an array that is too small to contain all the requested parame-
ters which span more than one block, ICCget() attempts to put in as many
complete sets of parameters as will fit (one complete set contains parameters for
one compound or block).
♦ ICCget() never puts a partial set of parameters for a single block into the array if
the array is not big enough to hold one set. An insufficient space error code is
returned for that case.
♦ If ICCget() has more sets of parameters to return than will fit into the array, it
returns a more data available status code. There is a provision for the caller to
specify that a call to ICCget() is a “continuation” from a previous call.
6
The above conventions mean that the caller must provide an array large enough to hold all the
requested parameters for one compound or block.
Load and Save Considerations

The load and save operations load or save one compound for each function call. The caller is
responsible for calling the appropriate function repeatedly to save or load more than one com-
pound.
If the load function encounters any errors while loading a compound and its blocks, it deletes
the compound and any blocks loaded so far from the CP/volume.
At the function call level, to obtain a list of compounds for saving, the caller can call the CSA
function CSlcmpnd(). At the Driver Task level, the ICCAPI GETORDER command can
provide a list of compounds in the current CP/volume.
At the function call level, to obtain a list of compounds for loading, the caller can use the
UNIX ls command, which produces a directory listing of the disk directory. At the Driver
Task level, the Driver Task SHELL command can be used to invoke the ls command to pro-
vide a list of files in a specified file directory.
Characters and Case Conversion

The ICCAPI performs character set checking and automatic case conversion for some argu-
ments.
The characters sets used for checking are:
1. For CP letterbugs, the character set is the set of all upper case alphanumeric char-
acters and the underscore character.
2. For compound, block, and shared variable names, the character set is the set of all
upper case characters and numeric characters and the underscore character.
The case conversions are:
1. For CP letterbugs, the characters are automatically converted to upper case except
when the first three characters are the string “vol”.
2. For compound, block, and shared variable names, the characters are automatically
converted to upper case.
Database Creation
At session open time, the ICCAPI performs database existence and content verification check-
ing. If it determines that the database disk directory or files do not exist or are incorrect, it cre-
ates a directory and files, as appropriate. The processing is similar to that performed by the
Control Configurator.
The following is the minimum database set:
1. A subdirectory with the name of the CP/volume (/opt/fox/ciocfg/cpname for the
50 series).
2. A workfile with the name of the CP/volume and the extension .wf (cpname.wf).
Principles of Operation 7
3. A compound index O_LIST file with the name of the CP/volume and the exten-
sion .O (cpname.O).
4. A compound with the name of the CP/volume and the string “_ECB” appended
(cpname_ECB or cpname_VECB for a volume) and a block index O_LIST file
for that compound (cpname_ECB_O).
5. A block in the cpname_ECB or cpname_VECB compound with the type ECBP
and the name PRIMARY_ECB.
6. A compound with the name of the CP/volume and the string “_STA” appended
(cpname_STA or cpname_VSTA for a volume) and its block index file
(cpname_STA.O). This compound is placed in front of the cpname_ECB com-
pound.
7. A block in the cpname_STA compound with the type STA and the name
STATION.
Special Compounds and Blocks

The compound in each station with the name of the station and the string “_ECB” appended
is treated specially: the ICCAPI does not allow it to be deleted, modified, or moved.
The cpname_STA compound and the STATION and PRIMARY_ECB blocks are also
treated specially.
The cpname_STA compound is always the first compound in the compound list, and cannot
be edited, deleted, or moved from its position. Its parameters can be displayed. It has only one
block (the STATION block). The STATION block’s parameters can be displayed and modi-
fied, but the STATION block cannot be deleted or moved. No other blocks can be inserted
into the cpname_STA compound. If the STATION block is loaded from diskette, all its
parameters are sent to the CP (not just the ones that have changed).
The cpname_ECB compound cannot be deleted, edited, or moved. Its parameters can be dis-
played. Its first block is always the PRIMARY_ECB block. The PRIMARY_ECB block
parameters can be displayed and modified, but the block cannot be deleted or moved. If the
PRIMARY_ECB block is loaded from diskette, all its parameters are sent to the CP (not just
the ones that have changed). Other ECB blocks can be added to the cpname_ECB com-
pound, but they must follow the PRIMARY_ECB in processing order.
Block Order
The ICCAPI checks for valid block ordering when adding, moving, or copying a block.
Each block list is divided into four zones, which must appear in the following order:
1. ECB zone – contains only (and all) ECB blocks. The end of the ECB zone is spec-
ified as -END_ECB_ZONE.
2. CONT1 zone – can contain non-ECB and non-sequence blocks. The end of the
CONT1 zone is specified as -END_CONT1_ZONE.
3. SEQ zone – can contain sequence blocks. The end of the SEQ zone is specified as
-END_SEQ_ZONE. Three sub-zones are enforced within it:
8
a. MON and TIM blocks

b. EXC blocks
c. DEP and IND blocks
Sequence blocks are restricted with respect to other sequence blocks:
♦ MON blocks must precede other sequence block types (TIM, EXC, DEP
and IND).
♦ TIM blocks must precede EXC, DEP and IND blocks.
♦ EXC blocks must precede DEP and IND blocks.
4. DATA zone – can contain only DATA blocks. The end of the DATA zone is spec-
ified as -END_DATA_ZONE.
Note that there are no explicit sequence subzone delimiters.
5. CONT2 zone – can contain non-ECB and non-sequence blocks. The end of the
CONT2 zone is specified as -END_CONT2_ZONE.
Error Handling
All ICCAPI functions return zero if no error is detected.
When an error is detected, an ICCAPI function returns a non-zero error class. In addition,
the ICCAPI saves an error number and some associated error text for the lowest level mean-
ingful error. This error number and text can be retrieved by calling the ICCerr() function any
time before the next ICCAPI function is called (exclusive of ICCerr(), of course). In other
words, as soon as the ICCAPI saves an error number and text, that information is latched
until the next ICCAPI public function (except ICCerr()) is called.
In addition, if the ICC_LOG_ERRORS option is set, whenever any ICCAPI function detects
an error, either in its own processing or as an error return from another function, it logs infor-
mation to the ICCAPI log file.
Data Structures
Data Structures used in Function Interface
Parameter Values
Parameter values are passed between the ICCAPI and its callers using an array of strings, each
of which has length ICC_PARAM_LENGTH. For convenience, each string can be defined
using the ICC_PARAM_ITEM data type:
typedef struct icc_param_item
{
char text[ICC_PARAM_LENGTH];
} ICC_PARAM_ITEM;
A typical array, large enough to hold 100 parameters, can be defined as follows:
ICC_PARAM_ITEM param_array[100];
Data Structures 9
An equivalent definition is:

char param_array[100][ICC_PARAM_LENGTH];
Each ICC_PARAM_ITEM contains a null terminated ASCII string of the form:
parameter = value
where the white space before and after the “=” is optional on input to the ICCAPI. The
ICCAPI always puts exactly one space character before and after the “=” on output.
Default Parameter Information

The default parameter names and values for a block type are passed from the ICCAPI func-
tion library to its callers using the following data structure:
typedef struct icc_default_item
{
char name[ICC_NAM_SIZE];
char value[ICC_VAL_SIZE];
char data_type;
int array;
int connection_type;
int disp_control;
int disp_option;
} ICC_DEFAULT_ITEM;
where:
name contains the name of the parameter, null terminated.
value contains the value of the parameter, null terminated. If the parameter is
numeric, the value field contains the ASCII representation of the number.
data_type contains the data type of the value. The possible values for data_type are:
ICC_CHARACTER
ICC_INTEGER
ICC_REAL
ICC_STRING
ICC_BOOL
ICC_LONG_INT
ICC_PERIOD
ICC_SHORT_INT
ICC_CHAR_ARRAY
ICC_INT_ARRAY
ICC_REAL_ARRAY
ICC_BOOL_ARRAY
ICC_LONG_ARRAY
ICC_SHORT_ARRAY
10
ICC_CONNECTION
array indicates whether the parameter is an array parameter.
connection_type indicates whether the parameter defines a connection for the block
type, and, if so, what type of connection it is:
ICC_CONN_NOT_SET
ICC_CONN_NO_CONNECT
ICC_CONN_OUTPUT
ICC_CONN_INPUT
disp_control indicates whether the parameter is displayable and/or editable:
ICC_DISP_DISPLAY
ICC_DISP_NOT_EDIT
ICC_DISP_NOT_DISPLAY
disp_option indicates whether the parameter is a standard parameter:
ICC_DISPOPT_STD
ICC_DISPOPT_OPT
Each default parameter passed uses one ICC_DEFAULT_ITEM. When multiple parameters
are passed, an array of ICC_PARAM_ITEMs is passed. The memory used is always supplied
by the caller.
Driver Task
Overview
The Driver Task reads commands, by default, from stdin, and writes its output, by default, to
stderr and stdout.
A program using the Driver Task can read the Driver Task’s output and send the Driver Task
more commands during a session, based on the output generated previously during that same
session. To make this possible, the Driver Task is not terminated when it encounters the end
of file condition on the input stream. Instead, it starts a timeout period, during which it waits
for more commands in the input stream. If the Driver Task encounters the EXIT command
in the input stream, if the timeout period expires, or if the Driver Task detects a UNIX signal
that indicates it is about to be terminated, the Driver Task closes the current session and exits.
The default value for the Driver Task input timeout is infinity (indicated by a value of zero). A
Driver Task command allows setting the timeout value to a different number as defined later
in this document.
Driver Task Input/Output Streams

The ICCAPI Driver Task input and output streams are ASCII text streams. Although the
input command stream would normally be created by a program and that the output response
streams would be interpreted by a similar program, these can be files created or viewed using a
Driver Task 11
text editor such as vi. The commands and responses are designed to make creation and inter-
pretation as simple as possible.
By default, the Driver Task takes its input from the stdin stream. This can be altered using
normal UNIX redirection conventions or with the -i command line parameter, described later
in this document.
Driver Task output is divided into two categories: data and command. Data output refers to
data obtained through one of the commands that returns lists of data (for example, block
parameters), while command output refers to all other types of output, including success and
failure notifications and error messages.
The command output normally goes to the stderr stream; the data output normally goes to
the stdout stream. These can be altered using UNIX redirection or the -o and -d command
line parameters, described later in this document.
Command Input Stream

The command input stream contains text lines interpreted by the ICCAPI Driver Task. Most
lines in the command input stream are command lines that begin with a Driver Task com-
mand, although the ADD and MODIFY commands are followed by data lines containing
parameter names and values.
The Driver Task echoes each input line that it reads to the command output stream, unless
disabled by options described later.
Comments are allowed in the input command stream. A comment is signified by the presence
of a sharp character (#). Text that follows a (#) is ignored by the Driver Task (except for being
echoed to the command output stream), until the start of the next line.
Blank lines are ignored by the Driver Task (except for being echoed to the command output
stream).
Data lines that follow commands like ADD and MODIFY must be followed by an END
command.
The format of command and data lines is flexible:
♦ White space (blank and/or tab characters) is allowed in front of the first token on
each line, but it is not required.
♦ White space is allowed at the end of each line, but it is not required.
♦ Tokens on each line must be separated by white space or by a comma character.
Different token separators can be intermixed on a single line (a tab can be used
after the command word; commas can be used to separate the various arguments).
Command Input Stream Example:
add comp1:block1
type = ain
period = 1
phase = 1
end
getorder comp1
12
Command Output Stream

The command output stream is generated by the ICCAPI Driver Task as it processes the com-
mand input stream.
The Driver Task normally echoes each line read from the command input stream, and out-
puts at least one line showing the success or failure of each command. Commands such as
SHOW that are intended to display information produce output to the data output stream.
The Driver Task can optionally put more verbose information in the command output
stream:
♦ The Driver Task puts progress report messages into the command output stream.
♦ When an error is detected, the Driver Task puts additional information into the
command output stream that may help identify the cause of the error.
Command Output Stream Example:
ECHO 1 add comp1:block1

ECHO 2 type = ain
ECHO 3 period = 1
ECHO 4 phase = 1
ECHO 5 end
DONE 5 COMP1:BLOCK1 Tue May 3 15:22:34 1994
ECHO 6 getorder
DONE 6 getorder Tue May 3 15:22:45 1994
Data Output Stream

The Driver Task sends the data lines from any commands to the data output stream. These
lines are formatted to be suitable for input to the Driver Task: the data for each compound or
block is always preceded by a line showing the compound or block name, and is always fol-
lowed by an END line. Each parameter line has a parameter name and parameter value, sepa-
rated by the three character string “=”.
Data Output Stream Example:
List of Block Order in Compound COMP1
-END_ECB_ZONE
NAME: BLOCK1 TYPE: AIN
-END_CONT1_ZONE
-END_SEQ_ZONE
-END_CONT2_ZONE
Driver Task 13
14
2. ICCAPI Function Calls
This section contains information on ICCAPI function calls including general
conventions, CSA functions and ICCAPI functions.
A task using the ICCAPI library must be written so it accesses one CP or library volume at a
time. Each session must be started by a call to ICCopen(). The session can consist of one or
more session-oriented calls, and should be terminated with a call to ICCclose().
General Conventions
Compound/Block Name
The following conventions apply to the functions that require a compound or block name:
1. A string without a colon (:) character is assumed to be the name of a compound.
2. A string with a colon (:) in any position except first and last is assumed to be a
compound:block name.
3. A string with a colon (:) in the first position is assumed to be a block name in the
most recently mentioned compound.
4. A string with a colon (:) in the last position or with multiple colons is invalid.
Compound and Block Position

Several function calls allow the caller to specify the position at which a compound or block is
to be inserted. The caller may specify the name of an existing compound (for inserting a com-
pound) or block (for inserting a block), or may specify no position. If a name is specified, the
new (moved or copied) compound or block is inserted just before the named compound or
block. If no name is specified, the new compound or block is appended to the end of the
compound list for the CP/volume or to the end of the appropriate block zone for the com-
pound.
The caller has the following choices for block position:
1. The name of an existing block may be specified, causing the new block to be
inserted in front of the named block.
2. The caller may specify one of the following mnemonics to insert the block at the
end of a block zone:
-END_ECB_ZONE
-END_CONT1_ZONE
-END_SEQ_ZONE
-END_CONT2_ZONE
Note that the dash character (-) eliminates these mnemonics as possible block
names.
15
B0193NE – Rev F 2. ICCAPI Function Calls
3. The caller may specify no block position. The ICCAPI inserts the block at an
appropriate default position, as follows:
♦ An ECB block is inserted at the end of the ECB zone.
♦ A non-sequence, non-ECB, block is inserted at the end of the CONT1 zone.
♦ A sequence block is inserted at the end of the appropriate sequence block sub-
zone, according to its type.
♦ A data block is inserted at the end of the DATA zone.
Function Return Values

If no errors were detected, the ICCAPI functions return a value of zero. When an error is
detected, the value returned is one of the error classes listed below:
ERR_IPC – IPC error
ERR_CP – error reported from CP
ERR_SIO – I/O error
ERR_CSF – CSA error
ERR_ICC – ICCAPI error
Of the above error classes, only ERR_ICC is specific to the ICCAPI. The other classes and
their error codes come from previously implemented parts of the I/A Series system. The
ICCerr() function is used to identify the error code within the error class.
The following value is used to indicate that the CP has returned a warning response to a
request:
ERR_CPW - warning reported from CP
CSA Functions
The following CSA functions return information about compounds and blocks:
CSlblk() – returns a list of the blocks in a specified compound.
CSlcmpd() – returns a list of compounds.
CSblkdef() – returns a list of parameter names for a block type.
CSgetblk() – returns the location and type of a block.
CSgetcmpd() – returns the location of a compound and the number of blocks it has.
ICCAPI Functions
Examples of how to use the ICCAPI functions are located in /opt/fox/ciocfg/api/examples
for Model 50/51 workstations and in /usr/fox/ciocfg/api/examples for AP20 and PW sta-
tions.
16
2. ICCAPI Function Calls B0193NE – Rev F
ICCopen() – Session Open

Opens a session with the specified CP or library volume. It locks the checkpoint file and
establishes a connection with the CP (if not a library volume).
The versions of the CP database and the PDEF file are checked for consistency. If they are not
compatible, an error code is returned.
The ICCopen() function sends a message to the System Error Reporter through err_rpt(): the
message contains the CP/volume name, the security level, the user ID string, and indication
as to whether the session was successfully opened.
Because the ICCclose() function does not wait for its checkpoint operation to complete,
ICCopen() can return an error code indicating that the specified station is being check-
pointed. The appropriate action is to try again after a suitable delay (for example, several sec-
onds).
FUNCTION int ICCopen(char *cp_name, int security, char *user_id)
ARGUMENTS 1. char *cp_name - input

A pointer to null terminated string that contains the CP letterbug or
the library volume name.
2. int security - input
An integer set to one of the following values:
ICC_SEC_READONLY
ICC_SEC_CHKPT
ICC_SEC_UPLOAD
ICC_SEC_MODIFY
ICC_SEC_ALL
3. char *user_id
A pointer to a null terminated string that contains text identifying the
ICCAPI user. This string may not be empty (its first byte must be non-
zero). The maximum length of the string is 256 bytes for the 50 Series,
40 bytes for Intel.
The first 64 characters of this string are included with SYSMON mes-
sages sent through err_rpt().
The characters before the first white space, up to 16, are used to create
the name of an ICCAPI session id file in the /opt/fox/ciocfg/cpname
directory (for Model 50). This file contains the full user_id string, the
time the session was started and ended, and the UNIX process ID.
ERRORS Unknown CP or library volume.

CP or library volume checkpoint file already locked (meaning,
session is already in progress).
CP or library volume unavailable.
Invalid security level.
Invalid user ID string.
CP being checkpointed.
Not enough arguments.
ICCAPI Functions 17
Unable to establish connection with CSA and/or control system.

Unable to access PDEF files.
SECURITY LEVEL
Not applicable with respect to ability to execute function.
EXAMPLE Refer to ciocfg/api/examples/dthdlrs.c.
ICCclose() – Session Close

Closes the current session. ICCclose() always disconnects from CP and unlocks checkpoint
file. If the file is not read-only and has been modified, ICCclose() initiates a checkpoint as
well.
The ICCclose() function sends a message to the System Error Reporter through err_rpt(): the
message contains the CP/volume name, the security level, the user ID string, and whether any
changes were made during the session.
FUNCTION int ICCclose(void)
ARGUMENTS None
ERRORS No session in progress.

Checkpoint failure.
Unable to close PDEF files.
Unable to write workfile.
SECURITY LEVEL
Not required.
EXAMPLES Refer to ciocfg/api/examples/dthdlrs.c.
ICCoverride() – Lock Override

Unlocks the checkpoint file for the specified CP or volume.
The ICCAPI user should be cautioned that this function is for error recovery only. An appli-
cation should override the checkpoint lock only when it has erroneously been left in a locked
state, and should not automatically, as a matter of normal operations, override the lock.
This function call is valid only if no session is currently in progress. No security level checking
is performed.
The ICCoverride() function sends a message to the System Error Reporter through err_rpt():
the message contains the CP/volume name and the user ID string.
FUNCTION int ICCoverride(char *cp_name, char *user_id)
ARGUMENTS 1. char *cp_name

A pointer to a null terminated string that contains the CP letterbug or
the library volume name.
18
2. char *user_id
A pointer to a null terminated string that contains text that identifies
the ICCAPI user. This string may not be empty. The first 64 characters
are included with the message sent to the System Error Reporter.
ERRORS CP or library volume unavailable.

Session already in progress.
Unable to unlock checkpoint file.
SECURITY LEVEL
Not applicable.
ICCget() – Get Parameters

Returns the requested set of parameters and their values for the specified compound(s) or
block(s) in the opened CP/volume.
FUNCTION int ICCget(char *name, char *type, int request, char *position,
ICC_PARAM_ITEM *item, int maxlen, int *count, int zones)
ARGUMENTS 1. char *name - input

A pointer to a null terminated string containing the name of the com-
pound or block for which the parameters are being requested. The
string may contain wild characters to indicate name filtering as follows:
A single “?” matches any character.
A “*” character matches any sequence of characters.
The following examples illustrate conventions for the name argument:
“CPD:” – the compound parameters for the compound “CPD”.
“CPD:BLK” – the block parameters for the block “BLK” in the com-
pound “CPD”
“CPD:*” – the block parameters for all blocks in the compound
“CPD”.
“CP*:BLK*” – the block parameters for all blocks whose names start
with the string “BLK” in compounds whose names begin with the
string “CP”.
“*” – the parameters for all compounds
“*:*” – the parameters for all compounds and all blocks
2. char *type - input
A pointer to a null terminated string containing the type of block for
which parameters are desired. The string may contain wild characters
ICCAPI Functions 19
to indicate name filtering as described above under the name argu-

ment. For example, the following string:
“PID*”
specifies only blocks of type PID, PIDX, PIDXE, etc. If this argument
has a value of NULL or points to a byte with a value of zero, no type
filtering is performed.
3. int request - input
The type of data being requested, selected from the following list:
ICC_PARAMS_ALL – all parameters for each compound or block are
returned.
ICC_PARAMS_STD – only the “standard” parameters for each com-
pound or block are returned.
ICC_PARAMS_SUBSET – only a subset of parameters, as defined by
the item argument, are returned.
4. char *position - input/output
A pointer to a null terminated string, or, the value NULL.
For a call to obtain only one set of parameters, the caller may set this
argument to the value NULL, or may set the argument to point to a
zero length string.
For a call to obtain multiple sets of values, the caller should set the
argument to point to a string buffer big enough to hold a string of
length ICC_CPDBLK_LEN. The buffer should have a zero in the first
byte for the first call.
If a call to ICCget() returns a status indicating more data is available,
the ICCAPI copies the name of the last item returned to the caller into
the string buffer. If the caller wishes to continue getting more parame-
ters, the caller must leave that name in the buffer for the next subse-
quent call to ICCget(), which uses the value determine which
compound or block is the next one to return.
5. ICC_PARAM_ITEM *item - input/output
A pointer to an array of ICC_PARAM_ITEMs (or an array of fixed
length strings, each ICC_PARAM_LENGTH long). When the request
argument has the value ICC_PARAMS_SUBSET, the caller must fill
in the names of the parameters desired. The array entry after the last
input parameter name must have a zero in the first byte, unless the
number of parameter names passed by the caller matches the value of
*count (that is, all of the array entries are used).
On output, if the function call is successful, the array is filled in with as
many of the requested values as will fit into the array, as indicated by
the value the caller gives the *count variable.
The ICCAPI always attempts to return all of the requested parameters
for a given compound or block in the item array. If the parameters for
the first compound or block do not fit into the array, the ICCAPI
20
returns an error code. In this case, the caller must supply a larger array
to obtain the complete set of desired parameters.
If the ICCAPI is returning the parameters for several compounds
and/or blocks, it places as many complete sets of parameters into the
array as will fit, and does not place a partial set at the end of the array.
Each returned parameter consists of a string like “param = value”.
the name of the compound or block: “name = value” and is followed by
an “END”. If the parameters are for a block, the name line includes the
compound name to which the block belongs.
If ICC_PARAMS_SUBSET is specified and the first entry in the
item[] array has a zero in its first byte, ICCget() returns only the name
of each matching compound or block, and does not return the string
“END”. Thus each returned compound or block uses only one item[]
array entry.
6. int maxlen - input
The number of text strings (array entries) in the structure pointed to by
the item argument.
7. int *count - output
A pointer to an integer variable. On output, the variable is set to the
number of ICC_PARAM_ITEMs filled in.
8. int zones - input
This parameter is used for the I/A Series release 4.0 level product. It
specifies whether the ICCget() function should include block end zone
markers between blocks when appropriate. For the markers to be
included, this argument must be set to 1 and the “name” argument
must be of the form “CPD:*”, where “CPD” is the name of a com-
pound.
This argument is ignored by ICCget() for the release 3.x level product.

Unknown compound or block.
Invalid arguments.
Insufficient space (array not big enough for returned compound
or block).
More data available.
SECURITY LEVEL
Allowed for all security levels.
EXAMPLES Refer to ciocfg/api/examples/dtget.c.
ICCAPI Functions 21
ICCseqget() – Get Sequence Code

Used to obtain the sequence files for a specified block. There are two distinct sets of sequence
blocks.
1. SFC/ST — Sequential Function Charts (SFC) and Structured Text (ST) Sequence
Blocks.
a. Valid blocks — IND, DEP, EXC
b. Files (.a, .b, .f, .g, .h, .i, .k, .r) maintained by the ICCAPI and the Control
Configurator and placed in the specified file directory using the specified base
file name.
2. NON SFC/ST Sequence Blocks.
a. Valid blocks — IND, DEP, EXC, MON
b. Files (.i, .r, .s) maintained by the ICCAPI and the Control Configurator and
placed in the specified file directory using the specified base file name.
FUNCTION int ICCseqget(char *blk_name, char *base_path_name)
ARGUMENTS 1. char *blk_name

Contains a pointer to a null terminated string that contains the name
of the block for which the sequence code is requested.
2. char *base_path_name
of the directory path and base file name to be used to return the files.
For example, for non SFC/ST sequence blocks, if the following call
were used:
ICCseqget("cpd:block1", "/tmp/sequence")
the ICCAPI would copy the three files: block1.s, block1.i, block1.r
from the directory /opt/fox/ciocfg/cpd (for the 50 Series) to the files
sequence.s, sequence.i, sequence.r respectively, in the directory /tmp.
For example, if the block is a SFC/ST sequence block:
ICCseqget(“cpd:block1”, “/tmp/sequence”)
the ICCAPI would copy the eight files: block1.a, block1.b, block1.f,
block1.g, block1.h, block1.i, block1.k, block1.r from the directory
/opt/fox/cioctg/cpd (for the 50 Series) to the files sequence.a,
sequence.b,…respectively, in the directory /tmp.
ERRORS No Session in progress.

Unknown block.
Not valid for compound type.
Block does not have sequence code.
Invalid path_name argument
Wild characters not allowed.
22
SECURITY LEVEL
EXAMPLE Refer to ciocfg/api/examples/dtseq.c.
ICCgetdef() – Get Default Information

Used to obtain default parameter information for a specified block type.
FUNCTION int ICCgetdef(char *type, ICC_DEFAULT_ITEM *item, int maxlen,

int *count)
ARGUMENTS 1. char *type - input

Contains a pointer to a null terminated string that contains the type of
the block for which the default parameters are desired.
2. ICC_DEFAULT_ITEM *item output
Contains a pointer to an array of ICC_DEFAULT_ITEM structures
(or an array of fixed length strings, of length
ICC_PARAM_LENGTH). The number of entries in the array is
defined by the *count variable on input.
The array must be large enough to contain all of the default parameters
for the specified block type. If it is not, an “insufficient space” error
code is returned.
3. int maxlen - input
The number of text strings (array entries) in the structure pointed to by
the item argument.
4. int count - output
Contains a pointer to an integer variable. On output, the variable con-
tains the number of entries filled by ICCgetdef().
ERRORS Unknown block type.

Insufficient space.
Invalid parameter name.
Unable to access PDEF file.
SECURITY LEVEL
EXAMPLE Refer to ciocfg/api/examples/dtget.c.
ICCAPI Functions 23
ICCadd() – Add Compound or Block

Adds the specified compound or block. Any specified parameters and their values are put into
the compound or block. Parameters not supplied are set to their default values.
FUNCTION int ICCadd(char *name, ICC_PARAM_ITEM *item, char *position)

of the compound or block to be added.
2. ICC_PARAM_ITEM *item - input
length strings, each of length ICC_PARAM_LENGTH). The array
must contain at least the TYPE parameter and must have “END” in
the last entry.
3. char *position
A pointer to a null terminated string that specifies where the new com-
pound or block is to be positioned, or the value NULL.

Duplicate compound or block.
Invalid parameter value.
Invalid position argument.
SECURITY LEVEL
Allowed only for the ICC_SEC_ALL security level.
EXAMPLE Refer to ciocfg/api/examples/dtmod.c.
ICCseqput() – Replace Sequence Code

Copies the specified sequence code files (already compiled) to the appropriate directory for
the block and sends the appropriate data to the CP.
FUNCTION int ICCseqput(char *blk_name, char *base_path_name)

Contains a pointer to a null terminated string containing the name of
the block for which the sequence code is supplied.
Contains a pointer to a null terminated string containing the name of
the directory and base file name where the sequence files are located.
For non SFC/ST sequence blocks the three files with extensions of “.s,”
“.c,” and “.r” must exist. For SFC/ST sequence blocks the eight files
24
with extensions of “.a,” “.b,” “.f,” “.g,” “.h,” “.i,” “.k,” and “.r” must
exist.
For example, if the directory /tmp contains the files
sequence.s
sequence.r
sequence.i
the argument should be /tmp/sequence.

Insufficient security level.
Unknown block.
Not valid for compound.
Invalid path name argument (no such directory, or file(s) missing).
CP error.
SECURITY Allowed only for the ICC_SEC_MODIFY security level and above.
EXAMPLE Refer to ciocfg/api/examples/dtseq.c.
ICCladget() – Get Plb Source File

Used to obtain the ladder file for a specified block. The block must be a plb type block. The
.p file that is maintained by the ICCAPI and the Control Configurator is placed in the speci-
fied directory using the specified base file name.
FUNCTION int ICCladget(char *blk_name, char *base_path_name)

of the block for which the plb ladder file is requested.
of the directory path and base file name to be used to return the files.
For example, if the following call were used:
ICCladget("cpd:plb1", “/tmp/plb1”)
the ICCAPI would copy the PLB1.p file from the directory
/opt/fox/ciocfg/CPD (for the 50 Series) to the file PLB1.p in the
directory tmp.
ERRORS NULL Argument.

No Session in Progress.
Unknown block.
Invalid base_path name_argument.
Block is not of type PLB.
ICCAPI Functions 25
SECURITY Allowed for all security levels.
EXAMPLE Refer to ciocfg/api/examples/dtplb.c.
ICCladput() – Replace Plb Source File

Copies the specified plb.p file (already compiled without errors) to the appropriate directory
for the block and installs the ladder in the CP.
FUNCTION int ICCladput(char *blk_name, char *base_path_name)

of the block for which the plb ladder file is to be supplied.
of the directory path and base file name where the plb ladder file is
located.
ICCladput("cpd:plb1", "/tmp/plb1")
the ICCAPI would copy the PLB1.p file from the directory /tmp (for
the 50 Series) to the file PLB1.p in the directory
/opt/fox/ciocfg/CPD.

Unknown block.
SECURITY Allowed only for the ICC_SEC_MODIFY security level and above.
ICCladcmp1() – Compile the Plb Source File

Runs the PLB compiler on the ladder file in the directory specified. The compilation is for
error checking only. All files generated by the PLB compiler remain in the specified directory.
When a compilation is successful then a PUTPLB command is needed to install the ladder in
the CP.
FUNCTION int ICCladcmp1(char *base_path_name)
ARGUMENTS char *base_path_name
26

of the directory path and base file name where the plb ladder file is
located.
ICCladcmp1("/tmp/plb1")
the ICCAPI would exec to the PLB compiler to compile the ladder file
PLB1.p in the directory /tmp (for the 50 Series). The two files PLB1.p
and PLB1.m resulting from the compilation remain in /tmp. The
PLB1.m file contains a compilation success or failure message.

Unable to start plb compiler.
Exec to compiler failed.
SECURITY Allowed for all security levels.
ICCdelete() – Delete Compound or Block

Deletes the specified compound or block from the CP (if not a volume), from CSA (if CSA
has it registered with the open CP/volume), and from the workfile database.
These deletions are independent from each other – an error encountered from deleting from
one of them does not prevent the other deletions. This makes the ICCdelete() function an
important tool for reconciling differences among these three databases.
FUNCTION int ICCdelete(char *name)
ARGUMENTS char *name - input

Contains a pointer to a null terminated string containing the specified
compound or block.

Invalid deletion.
SECURITY LEVEL
ICCAPI Functions 27
ICCmodify() – Modify Compound or Block

Modifies one or more parameters for the specified compound or block.
Certain types of parameter modifications are invalid. For example, it is invalid to change the
type of a block.
FUNCTION int ICCmodify(char *name, ICC_PARAM_ITEM *item)

compound or block.
2. ICC_PARAM_ITEM *item - input
length strings, each of length ICC_PARAM_LENGTH), one for each
parameter to be modified. The last entry must be “END”.

Invalid modification.
SECURITY LEVEL
Allowed only for the ICC_SEC_MODIFY security level and above.
ICCmove() – Move Compound or Block

Moves a compound or block from its current processing order position within the CP or com-
pound (respectively) to a new processing order position. The caller specifies the name of the
compound or block to be moved, and the position to which it should be moved.
FUNCTION int ICCmove(char *name, char *pos_name)

compound or block.
2. char *name_pos - input
Contains a pointer to a null terminated string specifying the position to
which the compound or block should be moved. Moving a compound
or block with a null name_pos will move the object to the end of the
list.
28

Unknown compound or block to move (i.e. source block).
Unknown compound or block position (i.e. destination).
Invalid position for compound or block.
SECURITY LEVEL
ICCcopy() – Copy Block

Allows the caller to copy a block from any compound in any CP or library volume (not just
the one currently open) to a compound in the current CP or library volume.
FUNCTION int ICCcopy(char *new_name, char *name, char *position)
ARGUMENTS 1. char *new_name - input

A pointer to a null terminated string specifying the name the block
should have when it is added. If the string contains only the block
name (for example, “:blk”), the compound name used is the most
recently mentioned compound name.
2. char *name - input
A pointer to a null terminated string specifying the name of the block
to be copied. The block may be from another CP or library volume. If
the string contains only the block name, the compound name used is
the most recently mentioned compound name (which will be the same
compound name used for the new_name argument).
3. char *position - input
A pointer to a null terminated string specifying the position where the
block should be inserted, or the value NULL (i.e., set position=
(char*)0).

Unknown compound or block to move (i.e. source block).
Unknown compound or block position (i.e. destination).
Invalid position for compound or block.
SECURITY LEVEL
Allowed only for the ICC_SEC_ALL level.
ICCAPI Functions 29
ICCinit() – Initialize CP Database

Initializes the database of the CP or library volume. All compounds and blocks are deleted
from the CP or library volume, and the minimum base set of files, compounds and blocks is
created.
The ICCinit() function sends a message to the System Error Reporter through err_rpt(): the
message contains the CP/volume name and a statement that a CP reboot is necessary.
This function ends the current session, if one is in progress. This is to remind the user that a
CP reboot is required after the database is initialized.
FUNCTION int ICCinit(char *cp_name)
ARGUMENTS char *cp_name

Contains a pointer to a null terminated string that identifies the
CP/volume that should be initialized, or the value NULL.
If a session is in progress, the current CP/vol for the session is initial-
ized.
If no session is in progress, this argument identifies the CP or volume
that should be initialized.
ERRORS No session in progress and no name supplied.

Session in progress and name supplied.
Unable to lock the station checkpoint file (if no session was in
progress).
Session is read only.
SECURITY LEVEL
EXAMPLE Refer to ciocfg/api/examples/dtldlrs.c.
ICCupload() – Upload Database from CP

Uploads the CP database from the CP.
The ICCupload() function sends a message to the System Error Reporter through err_rpt():
the message contains the CP/volume name and what was uploaded.
FUNCTION ICCupload(char *name)
ARGUMENTS char *name - input

A pointer to a null terminated string that specifies what should be
uploaded. There are several possibilities:
NULL or zero length string – specifies that all compounds and blocks
from the CP are to be uploaded.
“cpd” – a compound name by itself specifies that the compound's
parameters are to be uploaded.
30
“cpd:blk” – a block name specifies that the block's parameters are to be

uploaded.
“cpd:*” – a compound name with a “*” in the block name portion
specifies that all blocks for the compound are to be uploaded.

Operation not valid for library volume.
SECURITY LEVEL
Allowed for the ICC_SEC_UPLOAD security level and above.
ICCchkpt() – Checkpoint Control Station Database

Initiates a checkpoint operation for the CP or library volume for the current session.
Note that the ICCAPI allows this function call for a library volume, although it does not do
anything.
The ICCchkpt() function sends a message to the System Error Reporter through err_rpt().
FUNCTION int ICCchkpt(int delay)
ARGUMENTS int delay - input

Specifies how long to wait, in seconds, for the checkpoint operation to
complete before returning to the caller.
=0 — no delay; return immediately
>0 — delay for specified number of seconds
<0 — delay for default timeout = 240 seconds

Operation not allowed for current security level.
Operation did not complete within specified delay period.
SECURITY LEVEL
Allowed for the ICC_SEC_CHKPT security level and above.
ICCshrink() – Shrink Workfile

Optimizes storage the workfile by performing garbage collection.
The ICCshrink() function sends a message to the System Error Reporter through err_rpt().
FUNCTION int ICCshrink(void)
ARGUMENTS None
ICCAPI Functions 31

SECURITY LEVEL
Allowed for the ICC_SEC_MODIFY security level and above.
ICCsave() – Save Data to Disk File

Saves a compound to the specified disk directory. It creates a directory with the name of the
compound (or empties it, if it already exists) and puts into that directory a file with the name
“parameters” into it that conforms to the Control Configurator “save all” conventions. It also
puts into that directory any auxiliary files found in the compound directory, including
sequence code files, ladder logic files, IFD files and any other files in the directory.
Note it does not create or maintain the hidden compound index file as does the Control Con-
figurator. Currently the only application that uses this file is the ADC interface.
FUNCTION int ICCsave(char *pathname, char *cpd_name, char *save_name)
ARGUMENTS 1. char *pathname - input

Specifies the directory path to be used as the destination of the save
operation. It must specify a currently mounted device with a valid file
system.
2. char *cpd_name - input
A pointer to a null terminated string that specifies the name of a com-
pound to save.
3. char *save_name - input
A pointer to a null terminated string that specifies the compound name
under which to save the data (the name to be assigned to the save sub-
directory).

Invalid pathname.
Invalid save item.
Insufficient room to store specified compound.
SECURITY LEVEL
32
ICCload() – Load Data from Disk File

Loads a compound from the specified directory to the CP or library volume.
If any errors are encountered while loading the compound and its blocks into the CP/volume,
the compound and its blocks are deleted from the CP/volume.
FUNCTION int ICCload(char *pathname, char *new_name, char *name, char

*position)
ARGUMENTS 1. char *pathname - input

Specifies the directory path to be used as the source of the load opera-
tion. It must be a mounted device with a valid file system.
2. char *new_name - input
A pointer to a null terminated string that specifies the name the com-
pound should be assigned when it is installed.
3. char *name - input
A pointer to a null terminated string that specifies the name of the
compound to load.
4. char *position - input
A pointer to a null terminated string that specifies where the com-
pound is to be inserted, or the value NULL.
RETURN VALUE (returns int)

No session in progress.
Invalid pathname.
The name in load_item was not found.
The name in new_name is a duplicate of an existing compound.
SECURITY LEVEL
ICClogopen() – Open Log File

This function is used to open a log file (to be used in place of stderr) and to enable logging of
ICCAPI transactions. The caller specifies the name of the file to be created to contain the log-
ging messages, and which log messages are to be enabled.
After having called ICClogopen(), the user must call ICClogclose() before calling ICClo-
gopen() again.
The caller can modify the logging options for the current log file using the ICClogset() call,
described later in this document.
FUNCTION FILE *ICClogopen(char *fname, unsigned long flags)
ICCAPI Functions 33
ARGUMENTS 1. char *fname - input

A pointer to a null terminated string containing the desired file name.
Unless the ICC_LOG_APPEND flag is set (see below) any existing file
by that name is deleted.
2. unsigned long flags - input
A long with various bits set to specify which logging messages are
desired. All logging options are set or cleared according to their corre-
sponding bits in the flags argument.
The following bits are defined:
BIT 0 ICC_LOG_ARGS – log all calls and argument values.

BIT 1 ICC_LOG_PARAMS_IN – log all compound/block
parameter names and values supplied with calls to ICCadd()
and ICCmodify().
BIT 2 ICC_LOG_PARAMS_OUT – log all compound/block
parameter names and values returned to the user with calls to
ICCget().
BIT 3 ICC_LOG_ERRORS – log information about errors detected
by ICCAPI.
BIT 5 ICC_LOG_WARNINGS – log information about warnings
generated by the CP.
BIT 6 ICC_LOG_ERR_RPTS – log messages sent through the
err_rpt() function.
BIT 8 ICC_LOG_CSA – log additions and deletions of compound
and block names with CSA.
BIT 9 ICC_LOG_CP_MSGS – log messages to and from the CP.
BIT 12 ICC_LOG_APPEND – causes the log output file to be
opened such that new log messages are appended to the file. If
this bit is not set, any previously existing file with the specified
name is deleted.
ERRORS Unable to open the specified file.

Log file already open.
Unable to write to the specified stream.
SECURITY LEVEL
No security level checking is performed for this function call.
EXAMPLE Refer to ciocfg/api/examples/dtlog.c.

Note that the ICC_LOG_CP_MSGS option can cause potentially very long text lines to be
written to a log file.
34
ICClogclose() – Close Log File

This function is used to close the current log file and redirect enabled log messages back to
stderr.
FUNCTION int ICClogclose()
ARGUMENTS None
ERRORS File already closed.

No log file open.
SECURITY LEVEL
ICClogset() – Set Logging Options

This function is used to enable or disable logging options for the current log file (either stderr
or a file opened through ICClogopen()).
Multiple calls to ICClogset() cumulatively modify the logging options for the log file. Calling
ICClogset() with a zero in the flags argument disables all logging for the log file.
FUNCTION int ICClogset(unsigned long flags)
ARGUMENTS unsigned long flags - input

A long with various bits set to specify which logging messages are
desired. See the description of the flags argument under ICClogopen().
ERRORS None
SECURITY LEVEL
No security level checking is performed for this call.
ICClogflags() – Query Logging Options

This function is used to query the currently enabled logging options for the log file.
FUNCTION int ICClogflags(unsigned long *flags)
ARGUMENTS unsigned long *flags - input/output

A pointer to a long into which the currently enabled logging bits are
copied.
ERRORS Invalid FILE pointer.

Unknown FILE pointer.
ICCAPI Functions 35
SECURITY LEVEL
No security level checking is performed for this call.
ICCerr() – Get Error Information

This function can be used to retrieve error information that has been saved by the ICCAPI.
FUNCTION int ICCerr(int *err_code, char *err_bfr, int bfr_len)
ARGUMENTS 1. int *err_code - output

A pointer to an integer. On return, the integer contains the error code
for the error saved by the ICCAPI.
2. char *err_bfr - input/output
A pointer to the caller’s buffer. On return, the caller’s buffer has a ver-
bose explanation of the error saved by the ICCAPI.
3. int bfr_len - input
The length of the caller’s buffer. If the caller’s buffer is not long enough
to hold the entire null terminated error text, the ICCAPI truncates it
by putting a null byte in the last byte of the buffer and putting an aster-
isk (“*”) character in the next to last byte of the buffer.
ERRORS No error to report on.

Error text truncated.
SECURITY LEVEL
EXAMPLE Refer to ciocfg/api/examples/dtlog.c and ciocfg/api/examples/dtget.c.
36
3. ICCAPI Driver Task Commands
In this section is information on ICCAPI Driver Task Commands and
descriptions of the commands that can appear in the ICCAPI Driver Task
command file.
The Driver Task is a translation interface that translates ASCII commands to ICCAPI func-
tion calls and parameters, and ICCAPI return values and parameters to ASCII result mes-
sages. Available commands and their arguments reflect the ICCAPI function calls. In
addition, several function calls from other libraries (for example, the CSA library) are sup-
ported by Driver Task commands.
Following are descriptions of the commands that can appear in the ICCAPI Driver Task input
command file. Each command is described using the following structure:
FUNCTION The name of the ICCAPI library function call that supports the com-
mand.
SYNTAX The command with its arguments.
ARGUMENTS Description of each argument.
OUTPUT Description and example of outputs (when applicable).
ERRORS Description of the errors that can be detected for the command.
Driver Task Command Output

By default, the Driver Task writes two types of output to the Command Output stream
(which, by default, is stderr). Each command is echoed, and a response line is written for each
command. You can disable each of these and can request additional response lines for each
command.
The output response line has three possible formats:
1. DONE operation objname time where:
DONE indicates the command completed successfully
operation is the command word, echoed
objname is the current object name, expressed as “lbug!cpd:blk”
time is the current system date and time
2. FAIL operation objname time failure where:

FAIL indicates the operation failed
objname is the current object name, expressed as “lbug!cpd:blk”
37
B0193NE – Rev F 3. ICCAPI Driver Task Commands
time is the current system date and time

failure is the failure data, including the error class, code, and text
3. FLSH operation where:

FLSH indicates that the operation has been ignored because of
earlier failure
NOTE
When a FLSH response is received from the driver, all commands except
CLOSE, OVERRIDE, and EXIT are illegal, and they will be rejected by the driver
with a FLSH response until the driver receives a CLOSE, OVERRIDE, or EXIT
command.
Data Output
For output lines (generated by the GET, GETDEF and LIST commands), each line is sent to
the data output stream (which defaults to stdout).
The output from one command consists of a header line with the name of the compound or
block, data parameter lines, and a tail line consisting of the word “END”. Each data parame-
ter line consists of the parameter name and the parameter value, separated by the string “=”.
For example:
NAME = BLK4
TYPE = PID
PERIOD = 3
PHASE = 1
MEAS = :BLK3.PNT
FBK = :BLK3.OUT
END
Data Input
For input lines (ADD, MODIFY), each line consists of the parameter name and the parame-
ter value, separated by (at least) “=”. White space (tab or space characters) can appear before
or after the parameter name and the parameter value.
All occurrences of the characters carriage return (13) and control-z (26) are ignored and dis-
carded by the Driver Task. This allows files generated on a DOS system to be handled with-
out having to strip these characters.
When the Driver Task encounters a string of the form “$(var)”, it attempts to replace that
string by the value of “var” in the environment.
When array block parameters are input, each array element input must contain the parameter
name and array index (for example, “PARAM[2]”, not “[2]”).
38
3. ICCAPI Driver Task Commands B0193NE – Rev F
Input Stream Timeout

When the end of the command input stream is reached, the current value of the input com-
mand timeout is checked. If it is non-zero, the command input timer is started. If the timer
expires before more input is received, the Driver Task closes any currently open sessions and
terminates. If input is received before the timer expires, the timer is stopped.
The default behavior for the Driver Task is to wait forever for more command input stream
input.
When a CALL command redirects input to a called file, the Driver Task saves the current tim-
eout value and disables the timeout. This means that it returns to the calling file when the end
of the called file is reached. The saved timeout value is restored upon return.
Error Handling
If a command line error is detected, the Driver Task terminates with a non-zero error code
(see Chapter 4 “Using the ICCAPI”).
If an error is detected while executing commands from the command input stream, error han-
dling depends on whether the current input is coming from the original input stream speci-
fied on the command line or from a “called” file.
If the input is coming from a called input file, the Driver Task returns immediately to the call-
ing file, ignoring any subsequent commands in the called file.
If the input is coming from the original input stream, the Driver Task attempts to find the
next command. For commands with parameter lists, it ignores lines until an “END” or an
“EXIT” is found or the end of the input stream is reached, whichever comes first. If the erro-
neous command is an OPEN command, the Driver Task ignores lines until the matching
CLOSE is found or the end of the input stream is reached, whichever comes first.
OPEN Command
This command is required to open an ICCAPI session. It uses the ICCopen() function.
FUNCTION ICCopen()
SYNTAX OPEN cpname { READ | CHKPT | UPLOAD | MODIFY | ALL }

user_id_string
ARGUMENTS 1. cpname
The CP letterbug or the library volume name to be accessed during the
session.
2. { READ | CHKPT | UPLOAD | MODIFY | ALL }
The second argument specifies the security level for the session.
Input Stream Timeout 39

3. user_id_string
User identification string, with maximum length of 256 characters. If
blanks are included, it must be surrounded by double quote characters
(").
EXAMPLE OPEN C33CP3 ALL JohnB

OPEN Vol005 READ JohnB
ERRORS Unknown CP or library volume.

CP or library volume checkpoint file already locked
(meaning, session is already in progress).
CP or library volume unavailable.
Invalid security level.
Invalid user ID string.
CP being checkpointed.
Not enough arguments.
Unable to establish connection with CSA and/or control
system.
Unable to access PDEF files.
NOTES If a session is already open with the target volume or control station, an
error message is displayed. At this point, the only valid commands are
CLOSE, OVERRIDE, and EXIT. Other commands are flushed
(FLSH).
OVERRIDE Command
Unlocks the checkpoint file for the specified CP or volume. It uses the ICCoverride() func-
tion.
FUNCTION ICCoverride()
SYNTAX OVERRIDE cpname <user id string>
ARGUMENTS 1. cpname
The CP letterbug or library volume name for which the checkpoint file
should be unlocked.
2. user_id_string
User identification string, with maximum length of 256 characters. If
blanks are included, it must be surrounded by double quote characters
(").
EXAMPLE OVERRIDE C33CP3 JohnB
ERRORS CP or library volume unavailable.

Session already in progress.
Unable to unlock checkpoint file.
40
CLOSE Command
Closes the current session. It uses the ICCclose() function. Another session may be opened
after closing the current session.
FUNCTION ICCclose()
SYNTAX CLOSE
ARGUMENTS None

Checkpoint failure.
Unable to close PDEF files.
Unable to write workfile.
GET Command
Lists the parameter values for an existing compound or block to the Driver Task data output
stream. It uses the ICCget() function.
FUNCTION ICCget()
SYNTAX GET { compound | block } { all | std | subset } [ blktype ]
ARGUMENTS 1. { compound | block }

The name of the compound(s) or block(s) for which parameters are
desired. The name may contain wild card characters (“?” or “*”), which
allow the user to specify more than one compound or block. For exam-
ples of compound/block name strings and the objects they specify, see
“ICCget() – Get Parameters” on page 19.
2. { all | std | subset }
Specifies which parameters are desired: the “standard” set (“std”), the
entire set (“all”), or a user specified subset (“subset”). If “subset” is spec-
ified, the GET command must be immediately followed by the list of
desired parameters, one per line, ending with “END”.
3. [ blktype ]
This optional argument allows filtering based on block type. It is
ignored if the name argument contains no wild card characters. The
blktype string may contain wild card characters.
EXAMPLES The following examples illustrate conventions for the GET command:
GET APICMP1 ALL
Get the entire set of parameters for compound APICMP1.
GET APICMP1 STD
Get the standard set of parameters for compound APICMP1.
CLOSE Command 41
GET APICMP1:* SUBSET

NAME
TYPE
END
Get the NAME and TYPE of all blocks in compound APICMP1.
GET APICMP1:* SUBSET PLB
NAME
IOM_ID
END
Get the NAME and IOM_ID for all PLB blocks in Compound
APICMP1.
GET *:* SUBSET PID*
NAME
END
Get the NAME of all PID* blocks in the currently open station or vol-
ume.
GET API???1:PLB?1 SUBSET
NAME
IOM_ID
END
Get the NAME and IOM_ID parameters for all blocks that begin with
the letters “PLB”, any 3rd character, and the 4th character of “1” in all
compounds that begin with the letters “API”, any 4-6th character, and
a 7th character of “1”.
OUTPUT The output for this command always starts with the NAME and TYPE
lines and always ends with the END line. Other parameters requested
are shown following the TYPE line.
NAME = name_value
TYPE = type_value
... (other parameters)
END

Invalid arguments.
or block).
More data available
GETORDER Command
Lists the compounds of the CP or the blocks of a specified compound in actual processing
order (as opposed to alphabetical order, as shown by the LIST command).
FUNCTION ICCget()
SYNTAX GETORDER [ compound ]
42
ARGUMENTS [ compound ]
If present, this argument specifies the compound for which the list of
blocks is requested.
If absent, just the list of compounds for the opened CP/volume is
returned.
EXAMPLES GETORDER
List all compounds in opened CP/volume.
GETORDER APICMPI
List all blocks in Compound APICMP1.
OUTPUT COMPOUND ORDER FOR stn_name:

CPD1
CPD2
...
END
BLOCK ORDER FOR COMPOUND cpd_name:
BLK1 - type
...
END

Invalid arguments.
or block).
More data available
GETSEQ Command
Lists the sequence code or returns the sequence code files for the specified block (if the block
is a sequence type block).
FUNCTION ICCseqget()
SYNTAX GETSEQ Compound_Block base_path_name
ARGUMENTS 1. Compound_Block
Specifies the name of the block for which the sequence code is
requested.
2. base_path_name
Specifies the disk directory and base file name to be used by the Driver
Task to return the sequence code files. For non SFC/ST sequence
blocks the three code files (.s, .i, and .r) are copied to the specified
directory under the specified file name. For SFC/ST sequence blocks
GETSEQ Command 43
the eight files (.a, .b, .f, .g, .h, .i, .k, and .r) are copied to the specified
directory under the specified name.
EXAMPLE GETSEQ APICMP1:IND001 /tmp/IND002

The files IND001.s, IND001.i, IND001.r from the directory
/opt/fox/ciocfg/APICMP1 (for the 50 Series) are copied to the files
IND002.s, IND002.i, IND002.r in directory /tmp.

Unknown block.
Not valid for compound type.
Block does not have sequence code.
Invalid path_name argument.
GETDEF Command
This command lists the default parameters for a compound or a specified block type to the
Driver Task data output stream. It uses the ICCgetdef() function.
FUNCTION ICCgetdef()
SYNTAX GETDEF type
ARGUMENTS type
Specifies the entity for which default values are requested. It can have
the value “COMPND”, in which case the default parameters for a
compound are listed, or it can be a block type (e.g. “PID”).
EXAMPLES GETDEF cmpnd

GETDEF pid
OUTPUT The output for this command always starts with the TYPE line and
ends with the END line. For each parameter defined for the compound
or the block type, a line is generated that contains the parameter name,
its default value, its data type, its connection type, its access control
value and its option value.
Although the following example shows the line split over two lines, the
Driver Task outputs all of the data for each parameter on a single line.
type
name = default_value TYPE= data_type CONN= conn_type
CTL= ctl_val OPT= opt_val ARY= ary_val
END
where:
name = the name of the parameter
default_value = the default value of the parameter - it may be blank
data_type = the data type of the parameter, as follows:
44
1 - character
2 - integer
3 - floating point
4 - character string
5 - boolean (values 0 or 1)
6 - long integer (32 bits)
7 - processing period
8 - short integer (16 bits)
9 - packed boolean (16 bits)
10 - packed long boolean (32 bits)
11 - character array
12 - integer array
13 - floating point array
15 - boolean array
16 - long integer array
18 - short integer array
conn_type = the connection type of the parameter, as follows:
1 - not settable
2 - not connectable
3 - output connection
4 - input connection
ctl_val = the display control value of the parameter, as follows:
0 - editable
1 - not editable
opt_val = the display option value of the parameter, as follows:
0 - standard parameter
1 - optional parameter
ary_val = whether the parameter is an array parameter, as follows:
0 - not an array
n - an array with “n” entries
ERRORS Unknown block type.

Insufficient space.
Unable to access PDEF file.
LIST Command
Provides access to various lists that the Driver Task user may find useful. Since the various
classes of requests differ in format and output, they are described in the following sections.
No current session is required for any of the LIST commands.
List Compounds/Blocks Command

Produces a list of compounds in the current CP or a list of blocks in a specified compound.
Note that the list is obtained from CSA, which maintains them in alphabetical order. To
obtain the actual processing order, use the GETORDER command.
LIST Command 45
FUNCTION CSA retrieval functions are used.
SYNTAX LIST [CPNAME!]cpd[:blk]
ARGUMENTS 1. [cpname!]
This optional argument specifies that the list of compounds or blocks
should be limited to stations whose names match “cpname”. The wild
characters “*” and “?” are allowed in this argument.
2. cpd
This argument specifies which compounds should be included in the
list. Wild characters (*/?) are allowed in this argument.
3. [:blk]
This optional argument specifies which blocks should be included in
the list. Wild characters (*/?) are allowed in this argument. If this argu-
ment is absent, only compounds are listed. If it is present, only blocks
are listed.
EXAMPLES LIST C33CP3!*:*

Every compound and block in Station C33CP3
LIST C*!*:*
Every station beginning with “C” and all compounds, all blocks
LIST C33CP3!*:PL*
All block names beginning with “PL” in Station C33CP3
LIST C33CP3!*:PL?1
All block names beginning with “PL” and any 3rd character followed
by a numeric “1” in Station C33CP3
LIST BO*
All compounds in CSA beginning with the characters “BO”
LIST *:PLB*
All compounds in CSA that have blocks beginning with “PLB”
OUTPUT LIST C33CP3!*:*

NAME: PLB1 CMPD: PLBCMPS STN:C33CP3 TYPE:PLB
NAME: PLB2 CMPD: PLBCMPS STN:C33CP3 TYPE:PLB
NAME: AIN1 CMPD: AINCMPS STN:C33CP3 TYPE:AIN
...
...
END
ERRORS Unable to open file containing library volume ids.

Unable to open file containing control station ids.
Insufficient memory space.
Unable to find file containing relevant block names for this station
type.
Unable to read file containing relevant block names for this
46
station type.
Unable to get commands/blocks from CSA.
List CPS/Volumes Command

Produces a list of known control stations or library volumes. For control stations, the station
type is shown.
FUNCTION Internal Driver Task functions
SYNTAX LIST { -CPS | -VOLUMES } [ type ]
ARGUMENTS 1. { -CPS | -VOLUMES }

Specifies whether the list should show control stations (-CPS) or library
volumes (-VOLUMES).
2. [ type ]
Optional argument requesting that only control stations of the speci-
fied type should be listed.
To use the [type] parameter, first get a list of control stations (LIST -
CPS). The type of each control station is printed as part of the list.
These are the mnemonics that must be used in the [type] field to differ-
entiate the stations.
EXAMPLES
LIST -CPS #All CPS
LIST -CPS CP #CP10 Types
LIST -CPS C30 #CP30 Types
LIST -Volumes #All Volumes
OUTPUT LIST of CPS

lbug1 - type
...
END
List of VOLUMES
vol1
...
END
ERRORS Unable to open appropriate logical name file.
List Station Types Command

Produces a list of known station types. The station types are the mnemonics known to the
Integrated Control Configurator. These station types must be used in the [stn_type] field of
the LIST -TYPES command.
FUNCTION Internal Driver Task functions are used.
SYNTAX LIST -STATIONS
LIST Command 47
ARGUMENTS None
OUTPUT LIST OF STATION TYPES:

CP
CP3
FDG
...
END
ERRORS Unable to open station list file.
List Block Types Command

Obtains a list of valid block types.
FUNCTION Internal Driver Task functions are used.
SYNTAX LIST -TYPES [stn_type]
ARGUMENTS [stn_type]
Specifies the type of station for which the block types are requested. If
absent, all known block types are listed. Use the types from the LIST -
STATIONS command.
OUTPUT BLOCK TYPES

type1
...
END
ERRORS Unable to open block types file for station type.
ADD Command
Adds the specified compound or block, along with the supplied parameters.
FUNCTION ICCadd()
SYNTAX ADD { compound | block } [position]

data lines
END
ARGUMENTS 1. compound | block

This is the name of the compound or block to add. This argument is
required.
2. [position]
Can be used to specify the position where the new compound (or
block) should be placed.
48
3. data lines
These lines specify the values of the parameters for the compound or
block, one per input line. The format of a data line is specified previ-
ously in this document.
EXAMPLES ADD APICMP0 APICMP1

type = compnd
END
Adds APICMP0 compound immediately before APICMP1 com-
pound.
ADD APICMP1:AIN0 APICMP1:AIN1
type = AIN
END
Adds Block AIN0 immediately before AIN1 in Compound APICMP1.
ADD APICMP1:AIN9 -END_CONT2_ZONE
type = AIN
END
Adds Block AIN9 immediately before the end of Continuous Zone 2.

Duplicate compound or block.
Invalid position argument.
NOTES The four main zones are Continuous Zone 1, Sequence Zone 1, Con-
tinuous Zone 2, and Data Zone. To insert blocks at the end of these
zones, use -END_CONT1_ZONE, -END_CONT2_ZONE,
-END_SEQ_ZONE, and -END_DATA_ZONE.
CMPLSEQ Command
Runs the sequence code compiler on the non SFC/ST sequence code file (.s). CMPLSEQ
cannot be used to compile SFC/ST sequence code. The SFC/ST compiler is used to generate
native High Level Batch Language (HLBL) code.
FUNCTION ICCseqcmpl()
SYNTAX CMPLSEQ sequence_block_type base_path_name
ARGUMENTS 1. sequence_block_type
Specifies the type of block the code should be compiled for. The types
are “IND”, “DEP”, “MON”, or “EXC”.
2. base_path_name
Specifies the name of directory and file that contains the sequence code
to be compiled. This argument is passed to the ICCseqcmpl() func-
CMPLSEQ Command 49
tion, which appends the “.s” file extension. The files created by the
sequence compiler are left in the specified directory.
EXAMPLE CMPLSEQ IND /tmp/IND002

Sequence compiler errors.
Sequence compiler warnings.
PUTSEQ Command
Installs sequence code into the specified block.
It is assumed that the specified disk directory contains .s, .i, and .r files (for non SFC/ST
sequence blocks) or .a, .b, .f, .g, .h, .i, .k, and .r files (for SFC/ST sequence blocks) from a
previous CMPLSEQ command or SFC/ST compile.
FUNCTION ICCseqput()
SYNTAX PUTSEQ block base_path_name
ARGUMENTS 1. block
Specifies the block for which the sequence code is being supplied.
2. base_path_name
Specifies the directory and file name (less the file extension) where the
sequence code is located. The sequence code will be retrieved from this
directory and attached to the block.
EXAMPLE PUTSEQ APICMP1:IND002 /tmp/IND002

Get the sequence code from /tmp/IND002 and attach it to Block
IND002 in Compound APICMP1.

Unknown block.
Not valid for compound.
Invalid path name argument (no such directory, or file(s) missing).
CP error.
GETPLB Command
Retrieves the ladder file for the specified plb type block.
FUNCTION ICCladget()
SYNTAX GETPLB blk_name base_path_name
50
ARGUMENTS 1. blk_name
Specifies the name of the block that contains the ladder file ( .p).
2. base_path_name
Specifies the disk directory and base file name to be used by the Driver
Task to return the ladder file ( .p ). The ladder file is copied to the spec-
ified directory under the specified file name and extension of .p .
EXAMPLE GETPLB APICMP1:PLB1 /tmp/PLB1

No session in Progress.
Unknown block.
Invalid base_path_name argument.
PUTPLB Command
Copies the .p file to the directory specified by the blk_name argument and installs the ladder
file for the FBM associated with the specified blk_name.
It is assumed that the specified disk directory contains the .p file. This .p file may or may not
have been compiled previously by the CMPLPLB command. All segment files ( .p’s ) associ-
ated with the FBM are compiled and if there are no compiler errors, the ladder is installed in
the CP.
FUNCTION ICCladput()
SYNTAX PUTPLB blk_name base_path_name
ARGUMENTS 1. blk_name
Specifies the name of the block for which the ladder file ( .p) is being
supplied.
2. base_path_name
Specifies the disk directory and base file name (less the file extension)
where the .p file is located.
EXAMPLE PUTPLB APICMP1:PLB1 /tmp/PLB1

Unknown block.
PUTPLB Command 51
CMPLPLB Command
Runs the PLB compiler on the .p file in directory specified by the base_path_name. The
compilation is for error checking only. When a compilation is successful then a PUTPLB
command must be executed to install the ladder into the CP.
FUNCTION ICCladcmpl()
SYNTAX CMPLPLB base_path_name
ARGUMENTS base_path_name
Specifies the disk directory and base file name (less the file extension)
where the .p file is located. The files created by the PLB compiler are
left in the specified directory.
EXAMPLE CMPLPLB /tmp/PLB1

Unable to start plb compiler.
Exec to compiler failed.
DELETE Command
Deletes the specified compound or block.
FUNCTION ICCdelete()
SYNTAX DELETE { compound | block }
ARGUMENTS compound | block

Identifies the compound or block to be deleted. This argument is
required.
EXAMPLES DELETE APICMP1

Delete a compound.
DELETE APICMP1:IND001
Delete a block.

Invalid deletion.
52
MODIFY Command
Modifies the specified compound or block, using the supplied parameters.
FUNCTION ICCmodify()
SYNTAX MODIFY { compound | block }

data lines
END
ARGUMENTS 1. compound | block

Identifies the compound or block to be modified. This argument is
required.
2. data lines
These lines, one for each parameter, specify the parameters to be modi-
fied.
EXAMPLES MODIFY APICMP1

GR1DV1 = LP01
END
Modify the GR1DV1 parameter in Compound APICMP1.
MODIFY APICMP1:PLB1
IOM_ID = F93433
END
Modify the IOM_ID parameter of the PLB1 block in Compound
APICMP1.

Invalid modification.
MOVE Command
Moves the specified compound or block to a new processing order position.
FUNCTION ICCmove()
SYNTAX MOVE { compound | block } { position }
ARGUMENTS 1. compound | name

Identifies the compound or block to be moved.
2. position
Specifies the new position for the compound (or block).
MODIFY Command 53
EXAMPLES MOVE APICMP1:PLB0 APICMP1:PLB1

Move Block PLB0 immediately in front of Block PLB1 in compound
APICMP1.
MOVE APICMP1:PLB0 -END_CONT2_ZONE
Move Block PLB0 immediately in front of the END of Continuous
Zone 2.

Unknown compound or block to move.
Unknown position.
Invalid position.
NOTES The four main zones are Continuous Zone 1, Sequence Zone 1, Con-
tinuous Zone 2, and Data Zone. To insert blocks at the end of a zone,
use -END_CONT1_ZONE, -END_SEQ_ZONE,
-END_CONT2_ZONE, or -END_DATA_ZONE.
COPY Command
Creates a new block that has the same parameters as a specified block.
FUNCTION ICCcopy()
SYNTAX COPY [dest_cpd]:dest_blk [src_cpd]:src_blk [ pos_blk ]
ARGUMENTS 1. [dest_cpd]:dest_blk
Specifies the compound to which the block is to be added and the
name the block is to be assigned. If the compound part of the name is
missing, it defaults to the most recently mentioned compound name.
2. [src_cpd]:src_blk
Identifies the block that is to be copied. This block does not have to
reside in the open CP/volume. If the compound part of the name is
missing, it defaults to the most recently mentioned compound name
(which will always be the same as the value being used for “dest_cpd”.
3. [ pos_blk ]
This optional argument specifies the position the block should have.
EXAMPLES COPY APICMP1:PLB4 APICMP1:PLB1

Create Block PLB4 from Block PLB1 in Compound APICMP1.
COPY APICMP1:PLB5 APICMP1:PLB1 -END_CONT2_ZONE
Create Block PLB5 from Block PLB1 and place Block PLB5 immedi-
ately before the end of Continuous Zone 2.
54
COPY :PLB6 :PLB1

Create Block PLB6 in Compound APICMP1 from Block PLB1 in
Compound APICMP1. Note: this command uses the most recently
entered compound name.

Unknown source compound/block.
Unknown destination compound/block.
Invalid position.
NOTES The four main zones are Continuous Zone 1, Continuous Zone 2,
Sequence Zone 1, and Data Zone. To insert blocks at the end of these
zones, use -END_CONT1_ZONE, -END_CONT2_ZONE,
-END_SEQ_ZONE, or -END_DATA_ZONE.
INITIALIZE Command
Initializes the CP/volume database. It ends the current session, if one is in progress.
FUNCTION ICCinitialize()
SYNTAX INITIALIZE [ CPNAME ]
ARGUMENTS CPNAME
Specifies the name of the CP or volume to be initialized. This argu-
ment is required if no session is in progress, and is invalid if a session is
in progress.

UPLOAD Command
Uploads a specified portion of the database from the CP. This command causes a warning
message if used on a library volume.
FUNCTION ICCupload()
SYNTAX UPLOAD [ cpd | cpd:blk ]
ARGUMENTS [ cpd | cpd:blk ]

This optional argument specifies the portion to be uploaded.
If the argument is absent, all compounds and blocks are uploaded.
If “cpd” is specified, the named compound's parameters plus all blocks
(and their parameters) in the named compound are uploaded.
If “cpd:blk” is specified, the named block's parameters are uploaded.
INITIALIZE Command 55
EXAMPLES UPLOAD
Upload all compounds and blocks from the currently opened CP.
UPLOAD APICMP1
Upload all parameters for Compound APICMP1.
UPLOAD APICMP1:PLB1
Upload only the parameters for the block PLB1.

CHECKPOINT Command
Performs a CP database checkpoint operation. This command is allowed for a library volume,
although it does not do anything.
FUNCTION ICCchkpt()
SYNTAX CHECKPOINT delay
ARGUMENTS delay
Specifies how long, in seconds, the ICCchkpt() function should delay
while waiting for the checkpoint operation to complete.
0 — no delay; return immediately
>0 — delay for specified services
<0 — default delay = 240 seconds
EXAMPLES CHECKPOINT 0 — no delay

CHECKPOINT 360 — delay for 6 minutes
CHECKPOINT -1 — default, delay for 4 minutes

Operation did not complete within specified delay period.
SHRINK Command
Optimizes storage in the workfile by performing garbage collection.
FUNCTION ICCshrink()
SYNTAX SHRINK
ARGUMENTS None

56
SAVE Command
Saves the specified compound and all its blocks to the specified file directory.
FUNCTION ICCsave()
SYNTAX SAVE cpd_name path save_name
ARGUMENTS 1. cpd_name
Specifies the compound to be saved.
2. path
Specifies where to create the compound subdirectory in which to save
the data. It must be a mounted file directory.
3. save_name
Specifies the name to be assigned to the compound subdirectory.
EXAMPLES SAVE APICMP1 /f0 APICMP1

where a mountable floppy is mounted on /dev/fd0 /f0 (50 Series).
SAVE APICMP1 /tmp APICMP1
where /tmp/save_cmps is a directory on the mounted file system.

Invalid pathname.
Invalid save item.
Insufficient room to store specified compound.
LOAD Command
Loads the specified compound and all its blocks from the specified file directory.
FUNCTION ICCload()
SYNTAX LOAD newname loadname path [ position ]
ARGUMENTS 1. newname
Specifies the name the compound is to be assigned in the current
CP/volume.
2. loadname
Specifies which compound should be loaded.
3. path
Specifies the file directory from which the load should take place. It
must be a mounted file directory.
SAVE Command 57
4. [ position ]
Specifies the position where the compound is to be inserted. This posi-
tion is expressed as an existing compound. The new compound will
immediately precede this compound.
EXAMPLES LOAD APICMP1 APICMP1 /f0

Load Compound APICMP1 from floppy mounted on /f0 and use
same compound name for loaded compound.
LOAD APICMP3 APICMP2 /f0
Load Compound APICMP2 from floppy mounted on /f0 and change
name of loaded compound to APICMP3.
LOAD APICMP4 APICMP1 /tmp
Load Compound APICMP1 from /tmp and change the compound
name to APICMP4.
LOAD APICMP0 APICMP1 /tmp APICMP1
Load Compound APICMP1 from /tmp; rename the compound to
APICMP0 and place it immediately in front of compound APICMP1.
ERRORS None.
TIMEOUT Command
This command is used to specify a new command input timeout value. The value is specified
in seconds. If the value is set to 0 (the default setting), the driver waits indefinitely for input.
If the value is set to -1, then the driver does not wait for input at all (that is, input is already
present in another file).
FUNCTION (none)
SYNTAX TIMEOUT value
ARGUMENTS value
The new value, in seconds, for the timeout. If the argument has a value
of zero, the timeout value is “infinity”. If the argument has a value of -
1, the timeout is disabled (the Driver Task never waits for input).
ERRORS Invalid timeout value.
58
LOGOPEN Command
This function is used to initiate internal API logging to the specified file.
FUNCTION ICClogopen()
SYNTAX LOGOPEN fname options
ARGUMENTS 1. fname
Specifies the name of the file to open for logging. Unless the append
option is specified, this command deletes any previous file by the spec-
ified name.
2. options
Zero or more of the following option keywords:
ARGS print all arguments to corresponding library function
call
PARAMS_IN print all relevant parameters used by library function
call
PARAMS_OUT print all data gathered by library function call as it is
gathered
ERRORS print all intermediate errors encountered by API
CP_MSGS print the protocol used by the API and the control
station
CSA print all data to/from CSA
WARNINGS print all warnings received from the control station
ERR_RPTS print all messages sent to the error reporter
APPEND append any/all the above data to an existing file
MALLOC print all calloc/free function calls
If more than one of the above keywords is specified, they may be sepa-
rated by one or more space, tab or comma characters.
EXAMPLE LOGOPEN /tmp/apilog args errors
ERRORS Unable to open the specified file.

Log file already open.
Unable to write to the specified stream.
NOTES Only one logfile may be opened at any one time.
LOGOPEN Command 59
LOGCLOSE Command
This function is used to terminate logging to current log file, redirecting log messages back to
stderr. This command is invalid if logging is not currently directed to a file as a result of the
LOGOPEN command.
FUNCTION ICClogclose()
SYNTAX LOGCLOSE
ARGUMENTS None.
ERRORS File already closed.

No log file open.
LOGSET Command
This function is used to set the logging options for the log file. If the command is used with-
out the LOGOPEN command, all messages are sent to stderr.
FUNCTION ICClogset()
SYNTAX LOGSET options
ARGUMENTS options
Zero or more of the option keywords described under the LOGOPEN
command.
EXAMPLE LOGSET WARNINGS ERRORS
ERRORS None.
LOGSTAT Command
This function is used to obtain the current logging options for the current log file, if one is
specified, or for stderr.
FUNCTION ICClogflags()
SYNTAX LOGSTAT
ARGUMENTS None.
OUTPUT OPTIONS: HEX=00000100, BITS=CSA

(configured CSA messages to be logged via LOGSET CSA command)
ERRORS Invalid FILE pointer.

Unknown FILE pointer.
60
LOGOPTION Command
Enables or disables the logging of various Driver Task messages to the command output
stream (stdout).
FUNCTION Internal Driver Task functions.
SYNTAX LOGOPTION [ option value ]
ARGUMENTS If no arguments are present, the current logging options are displayed.
option value
Specifies the option to be set and its value. The string “option” must be
one of “ECHO”, “DONE”, “WARN”, or “FAIL”. The string “value”
must be one of “ON” or “OFF”.
EXAMPLES LOGOPTION
Lists currently active options.
LOGOPTION WARN OFF
Turns logging of WARN messages off.
LOGOPTION WARN ON
Turns logging of WARN messages on.
OUTPUT Current Log Options: ECHO DONE WARN FAIL
ERRORS No ON/OFF arg.
SHELL Command
This function is used to execute an arbitrary Unix command. The string after the SHELL
command keyword is passed to the Unix system() function.
FUNCTION system() - UNIX system call
SYNTAX SHELL string
ARGUMENTS string
EXAMPLE SHELL ls -l /tmp
OUTPUT The output of the Unix command is sent to stdout and stderr accord-
ing to its usual conventions. The Driver Task redirects stderr to the
command output stream and stdout to the data output stream for the
duration of the system() call.
ERRORS UNIX shell unable to execute command.
LOGOPTION Command 61
CALL Command
Allows temporary redirection of Driver Task input to a specified file. Control returns to the
line after the CALL command when an EXIT command is encountered in the file, when the
end of the file is reached, or when an error is detected while executing a command from the
file.
The input command timeout value is set to -1 (disabled, no waiting) by this command, after
first saving the current value so it can be restored when control returns to the line after the
CALL command.
FUNCTION Internal driver task function
SYNTAX CALL file_name
ARGUMENTS file_name
The name of the file to which control should be transferred.
ERRORS File does not exist.
EXIT Command
Terminates the Driver Task if encountered in the base input command stream, and causes a
“return” to the “calling” file if encountered in a “called” file. The “return” causes the saved
input command timeout value to be restored from the value saved when the “called” file was
entered.
FUNCTION Internal driver task function
SYNTAX EXIT
62
4. Using the ICCAPI
This section contains information on using the ICCAPI including installation,
initialization, utilities, and operation.
Installation and Initialization

The API is provided as part of the Integrated Control Configurator (ICC) package. It is fully
installed together with the ICC. The ICCAPI Driver Task and the utility scripts reside in the
following directories:
AW/AP50, AW/AP51 path = /opt/fox/ciocfg/api
AP/20, PW path = /usr/fox/ciocfg/api
Operation
ICCAPI Function Interface
Using the ICCAPI function interface requires the usual steps of editing source files, compiling
the source files, linking the object files, and running the linked image.
Application Build
The following ICCAPI components are used during the above steps:
iccapi.h A header file that defines constants and data structures used in the
ICCAPI function calls. This file should be included in C source files
that call ICCAPI functions.
libiccapi.so The dynamically linkable library file that contains the ICCAPI func-
tions. This file is linked at runtime to an application task making
ICCAPI function calls.
ICCAPI Driver Task

The Driver Task is started using the following syntax:
iccdrvr.tsk [-i input_file] [-o output_file]
[-d data_output_file] [-n echo] [-n done] [-n warn]
[-n fail]
where:
[-i input_file] is an optional argument specifying the input command file. If this
argument is absent, the Driver Task reads its input command from stdin.
[-o output_file] is an optional argument specifying the command output file. If
this argument is absent, the Driver Task writes its command output to stderr.
63
B0193NE – Rev F 4. Using the ICCAPI
[-d data_output_file] is an optional argument specifying the data output file. If

this argument is absent, the Driver Task writes its data output to stdout.
[-n echo ] is an optional argument that specifies that input command lines are not
to be echoed to the command output file.
[-n done ] is an optional argument that specifies that DONE status lines are not to
be sent to the command output file.
[-n warn ] is an optional argument that specifies that WARN status lines are not to
be sent to the command output file.
[-n fail] is an optional argument that specifies that FAIL status lines are not to be
sent to the command output file.
The following is an example input command file:
OPEN CP0002 MODIFY USER_1
GET FEEDWATER:INPUT1
GET :INPUT2
MODIFY :INPUT3
RI01 = 5.5
END
CLOSE
EXIT
Utilities
LOAD_ALL Script
This script lets the user perform a “Load All” operation of a specified control station’s com-
pounds and blocks from a specified location. The location may be specified as a directory on a
mounted file system or as the file system’s device name. Refer to “LOAD_ALL/SAVE_ALL
Recommendations” on page 65 for requirements.
Usage: load_all [-d] <station> <path>

-d debug mode: do not remove command input file to
driver task.
<station> is the Control Station to be loaded.
<path> is the directory (or device) from which the data is to
be loaded.
Example: load_all C10A50 $OPT/stn_save

or
load_all C10A50 /dev/fd0
or
load_all -d C10A50 /dev/fd0
64
4. Using the ICCAPI B0193NE – Rev F
SAVE_ALL Script
This script lets the user perform a “Save All” operation of a specified control station’s com-
pounds and blocks to a specified location. The location may be specified as a directory on a
mounted file system or as the file system’s device name.
At a minimum, this script requires enough free disk space in the $OPT partition of the local
hard drive to hold any one compound at a time, from the specified control station. This
requirement is temporary and will be returned upon completion of the script. After each com-
pound is moved to the final destination, its associated data (stored in $OPT) is removed,
before starting the processing of a new compound. Refer to “LOAD_ALL/SAVE_ALL Rec-
ommendations” on page 65 for requirements.
Usage: save_all [-d] <station> <path>
-d debug mode: do not remove command input file to
driver task.
<station> is the Control Station to be saved.
<path> is the directory (or device) to which the data is to be
saved.
Example: save_all C10A50 $OPT/stn_save

or
save_all C10A50 /dev/fd0
or
save_all -d C10A50 /dev/fd0
LOAD_ALL/SAVE_ALL Recommendations
The V4.2 release of ICCAPI supports the ability to perform saving and loading of the Inte-
grated Control Configurator (CioCfg) databases via Foxboro supplied shell scripts (load_all,
save_all).
The load_all and save_all shell scripts support reading and writing to local AP/AW hard
drives. A remote AP/AW hard drive can be used. To do so, a user must first rmount the
remote AP/AW prior to running the load_all/save_all shell script.
Foxboro recommends users doing Batch Processing (recipes), using Sequence type blocks:
(IND, DEP, TIM, EXC, MON) should use the load_all/save_all shell scripts and perform
SaveAlls/LoadAlls to/from a hard drive. Due to the size and quantity of Sequence blocks and
Sequence Logic, a compound may not fit onto a floppy diskette. SaveAlls stored onto a hard
drive can then be backed up to tape.
Before using the load_all/save_all shell script, consider the following:
♦ The load_all/save_all shell scripts will check to see if there is enough space on the
AP/AW’s LOCAL hard drive to handle the save_all/load_all files. If a remote hard
drive is used for save_alls, the save_all shell script does NOT check and the user is
required to verify that there is enough space on the remote drive.
♦ If a remote AP/AW is to be used for saving to or loading from, the user is required
to MANUALLY rmount the AP/AW prior to running the load_all/save_all shell
script.
Utilities 65
♦ Care MUST be taken in selecting a save_all location. Foxboro recommends using

the “/opt” partition on an AP/AW 50 or 51 and the “/usr” partition on the Intel
platform. Also the user should create a unique directory such as “/opt/save” or
“/usr/save” in the appropriate partition so that NO Foxboro I/A Series files are
corrupted or overwritten.
♦ The load_all and save_all shell scripts should be run on the AP/AW that hosts the
control station.
♦ The load_all/save_all shell scripts allow a user to read or write directly to the
LOCAL floppy drive (/dev/fd0, /dev/fh0, /dev/fh1) If the local floppy drive is
used, the load_all and save_all shell scripts automatically mount the floppy device
for the user.
♦ Databases that have been saved to an AP/AW hard drive can then be saved to a
streaming tape.
♦ Users wanting to perform “batch” processing (saving multiple stations at a time),
can create shell script(s) to invoke the save_all/load_all shell scripts.
♦ Only ONE invocation of the load_all or save_all shell script should be run on an
AP/AW at a time. Users should NOT attempt to run BOTH load_all and save_all
at the same time on the same AP/AW.
♦ Due to the shell limitation (bourne shell) on the Intel platform, the load_all and
save_all shell scripts can fail with the error message - “sh: /bin/cp: arg list too
long”. This failure can be caused by the large quantity of sequence blocks config-
ured within a compound. If a compound contains more than 30 sequence blocks,
the load_all/save_all shell scripts can fail. For each sequence block configured
within a compound, there exists a sequence source file (.s extension), a sequence
interpretive code file (.i extension) and a sequence display file (.r extension). Also if
the compound contains Intelligent Transmitters (ECB18s), there will exist for that
block an IT configuration file (.x extension). For the PLB block there will exist a
Ladder file (.p extension) and (if configured within the same compound) the
ECB8s PLB segment file (.p extension).
ICCPRT Script
This script lets the user produce a report of:
♦ All parameter names and values of all (or a subset of) compounds and blocks in a
specified station or volume
♦ Compounds within a station
♦ Blocks within a specified compound
Usage: iccprt [-p] [-n compound[:block]] [-o outputfile] <station>
-n compound and/or block list to be reported (wildcards are
valid); default is for all compounds.
-o output file to which report will be redirected; default is to
console.
-p generate report on compound and/or block PARAME-
TERS rather than compound and/or block ORDER.
<station> is the Control Station or volume to be reported.
66
4. Using the ICCAPI B0193NE – Rev F
Examples:
List all blocks in Compound APICMP1 to printer:
iccprt -n APICMP1 C10A50
List all blocks in Compound APICMP1 to a file apicmp1.txt:
iccprt -n APICMP1 -o /tmp/apicmp1.txt C10A50
List all block parameters in Compound APICMP:PLB001 to a file apicmp1.txt:
iccprt -p -n APICMP1:PLB001 -o /tmp/apicmp1.txt C10A50
List all compounds and all blocks to a file apicmp1.txt:
iccprt -n \* -o /tmp/apicmp1.txt C10A50
List all parameters in all compounds and all blocks to a file apicmp1.txt:
iccprt -p -n \* -o /tmp/apicmp1.txt C10A50
Utilities 67
68
5. Writing Applications Using the
Driver Task
This section contains information on writing applications using the Driver Task
including replacing iccprt and bldcio with ICCAPI and sample implementation.
The Driver Task forms an ASCII parser shell around the API. It accepts ASCII input com-
mands from the keyboard or from a file and generates two types of output: a data output and
a status output. Outputs are routed to stdout and stderr, both of which are the terminal by
default. The two outputs can be written to separate files.
When using the Driver Task in a UNIX shell script, you must consider three top-level compo-
nents:
1. An input command file used to open a session.
2. An intelligent program that can evaluate results and conditionally generate new
commands based on the output of the driver.
3. A close and exit segment.
Replacing iccprt and bldcio

The ICCAPI takes the place of two utilities, iccprt and bldcio, which are no longer sup-
ported.
The original iccprt utility was designed to generate reports on a block or compound built
with the aid of the ICC. The reports are identical with those produced by the ICC’s print
function. A script (also called iccprt) that invokes the Driver Task and produces identical
reports is listed in this section and is delivered along with the ICCAPI.
The bldcio utility was designed to generate a “Save All” diskette that can later be loaded into
the ICC using either the Load All or Load From Diskette menu picks. The “Save All” dis-
kette is generated from an input ASCII file in the form of a compound definition, followed by
definitions of all the blocks that reside in the compound.
The ICCAPI obviates the need for the bldcio utility. Replacing the utility is the Driver Task,
which accepts a modified version of the input ASCII file. The following example illustrates
the way in which the input file to the bldcio utility needs to be modified to serve as the input
file to the ICCAPI Driver Task.
When preparing input files to the Driver Task, observe the following rules:
♦ Comments cannot start in middle of a line. Place all comments on separate lines.
♦ Each parameter must be given its parameter value.
NOTE
Parameters can be supplied in any order.
69
B0193NE – Rev F 5. Writing Applications Using the Driver Task
Sample Input File for bldcio (partial listing)

# First two entries must be letterbug and station type
LBUG IG0022
STATION IG
# First compound
NAME SSI_TEST
TYPE COMPND
# and so on
Sample Input File for the Driver Task (partial listing)

# open command required by the Driver Task
open IG0022 all username
# First compound
# replace tbe NAME parameter in the bldcio input fileadd SSI_TEST
TYPE COMPND
# and so on
#
# end of Driver Task looping
close
# exiting the Driver Task
exit
The other portions of the input file remain unchanged.
Sample Implementation
Listed below is the implementation of the iccprt involving a UNIX script that contains the
first and third components described above, and an AWK program constituting the second
component. The following example shows the code of both the script and the AWK program
used to generate a report that lists blocks, compounds, and their parameters within a station.
UNIX Script
:
#**************************************************************************
# %W% New System, Foxboro Co. %G%
#**************************************************************************
#
# (C) Copyright by Foxboro Company 1993
# All rights reserved: Foxboro Company 1993
#
#**************************************************************************
#
# FILE ID : iccprt
#
# FUNCTION : This script allows the user to produce a report of:
#
# - all parameter names and values of all (or a subset) of
# compounds and blocks in a specified station or volume
#
# - compounds within a station
#
# - blocks within a specified compound
#
# SYNOPSIS : iccprt [-m num] [-n compound[:block]] [-o outputfile] station
# where : -n compound / block set to report on
# (defaults to ALL parameters of ALL
# compounds and blocks; wildcard
# characters are supported)
# -o file to which parameter data will be
# written
# -p report on compound / block parameters
70
5. Writing Applications Using the Driver Task B0193NE – Rev F
# rather than block order

# station control station letterbug (required)
#
# Eg., iccprt -n APICMP1:* C10A50
#
# FLOW OF CONTROL:
#
# FUNCTIONS CALLED: iccprt.awk
#
# COMPONENT HISTORY:
# 17 Nov 93 KS Original release
#
#
##########################################################################
if [ -f /venix ]
then
ICCDRVR=/usr/fox/ciocfg/api/iccdrvr.tsk
AWK=awk
else
ICCDRVR=/opt/fox/ciocfg/api/iccdrvr.tsk
AWK=nawk
fi
###########################################################################
# Function to display command usage and exit
###########################################################################
usage_exit ()
{
echo "Usage: $0 [-p] [-n compound[:block]] [-o outputfile] <station>"
echo " -n print parameters for specified compound(s)"
echo " or block(s); default is for all compounds"
echo " -o output file to which all parameter values will"
echo " be written; default is to /dev/tty"
echo " -p report on compound and/or block parameters"
echo " default report is compound order report"
echo " <station> is the Control Station or volume to be reported"
exit 1
}
###########################################################################
# Check command line for correct number of arguments
###########################################################################
if [ $# -lt 1 ]
then
usage_exit
fi
##########################################################################
Check for option flag in command line
###########################################################################
while [ $# -ge 2 ]
do
case $1 in
-n ) SEARCH_LIST=$2
shift 2;;
-o ) DATA_OUTFILE=$2
shift 2;;
-m ) if [ $2 -gt 3 ]
then
SEARCH_COMMAND=getorder
else
SEARCH_COMMAND=get
fi
shift 2;;
Sample Implementation 71
-p ) SEARCH_COMMAND=get
shift;;
-h ) echo "Obsolete option: ignored"
shift;;
-s ) echo "Obsolete option: ignored"
shift;;
* ) usage_exit;;
esac
done
###########################################################################
# check for variables; set defaults if needed
###########################################################################
test -n "$DATA_OUTFILE" || DATA_OUTFILE=/dev/tty

test -n "$SEARCH_COMMAND" || SEARCH_COMMAND=getorder
if [ -z "$SEARCH_LIST" ]
then
if [ $SEARCH_COMMAND = "getorder" ]
then
SEARCH_LIST=
else
SEARCH_LIST=\*:\*
fi
fi
###########################################################################
# setup local names for the command line arguments
###########################################################################
STATION=$1
USERNAME=iccprt.‘uname -n‘.$1
IN_FILE=/tmp/input$$
###########################################################################
# output the open command to the IN_FILE, for the driver task to start
###########################################################################
echo open $STATION read $USERNAME > $IN_FILE
###########################################################################
# invoke the driver task / awk pair of commands
# The driver task continues to execute till it sees exit in IN_FILE.
###########################################################################
$ICCDRVR -n echo -i $IN_FILE -d $DATA_OUTFILE 2>&1 | \

$AWK -f ./iccprt.awk s_cmd=$SEARCH_COMMAND s_list=$SEARCH_LIST \
station=$STATION outfile=$IN_FILE
RETCODE=$?
###########################################################################
# remove the input file to the driver task
###########################################################################
rm -f ${IN_FILE}*
###########################################################################
exit $RETCODE
AWK Program
#**************************************************************************
72
5. Writing Applications Using the Driver Task B0193NE – Rev F
# %W% New System, Foxboro Co. %G%

#**************************************************************************
#
# (C) Copyright by Foxboro Company 1993
# All rights reserved: Foxboro Company 1993
#
#**************************************************************************
#
# FILE ID : iccprt.awk
#
# FUNCTION : This awk program is invoked by the iccprt script in the
# following manner:
#
# iccdrvr.tsk | awk -f iccprt.awk
#
# This awk program has two main functions:
#
# 1) parse the output of the ICCAPI driver task (whose data
# is received via stdin)
# 2) generate more driver task commands based on the output
# described in (1). These commands are then placed into
# the "input file" feeding the driver task.
#
# Therefore, the basic operation of the pipe is that the
# driver task’s initial output is fed through the
# iccprt.awk program which, then, generates appropriate
# commands. This cycle of
#
# ’driver task -> iccprt.awk -> driver task’
#
# continues until the iccprt.awk program generates a
# close/exit command.
#
#
# COMPONENT HISTORY:
#
#**************************************************************************
{
# On any failure, exit the driver task
if( ($1 == "FAIL" || $3 == "ERROR:") && close_issued != 1 )
{
printf "Driver task %s failure\n", $3;
printf "close\nexit\n" >> outfile;
close_issued = 1;
}
# Issue GET command for all compounds / blocks specified by user

else if( ($1 == "DONE" && do_Get != 1 ) )
{
if( s_cmd == "get" )
printf "%s %s all\n", s_cmd, s_list >> outfile;
else
printf "%s %s\n", s_cmd, s_list >> outfile;
do_Get = 1;
}
# otherwise close and exit.

else if( close_issued != 1 )
{
# Insert command to close and exit when storing is done
printf "close\nexit\n" >> outfile;
close_issued = 1;
}
}
.
An alternative implementation consists of a single UNIX script containing a loop that checks
the output of the driver and generates all the necessary commands according to these outputs.
Sample Implementation 73
74
Appendix A. Driver Task
Commands — Quick Reference
Command Arguments
OPEN cpname {READ | CHKPT | UPLOAD | MODIFY | ALL } <user_id_string>
OVERRIDE cpname <user id string>
INITIALIZE [cpname]
GET {compound | block } { all | std | subset } [TYPE blktype]
GETORDER [compound]
GETSEQ blk_name base_path_name
PUTSEQ blk_name base_path_name
GETPLB blk_name base_path_name
PUTPLB blk_name base_path_name
GETDEF blk_type
LIST [CPNAME!]cpd[:blk]
LIST { -CPS | -VOLUMES } [ type ]
LIST -STATIONS
LIST -TYPES [stn_type]
ADD { compound | block } [position]
MODIFY { compound | block }
COPY [dest_cpd]:dest_blk [src_cpd]:src_blk [pos_blk]
DELETE { compound | block }
MOVE { compound | block } {position}
CMPLSEQ sequence_block_type base_path_name
CMPLPLB base.path_name
UPLOAD [cpd | cpd:* | cpd:blk]
CHECKPOINT delay_in_seconds
SAVE cpd_name path save_name
LOAD newname loadname path [position]
TIMEOUT value
LOGOPEN file_name { ARGS | PARAMS_IN | PARAMS_OUT | ERRORS | CP_MSGS
| CSA | WARNINGS | ERR_RPTS | APPEND }
LOGSET { ARGS | PARAMS_IN | PARAMS_OUT | ERRORS | CP_MSGS | CSA |
WARNINGS | ERR_RPTS | APPEND }
LOGOPTION [option value] [option value] …
LOGCLOSE
75
B0193NE – Rev F Appendix A. Driver Task Commands — Quick Reference
Command Arguments
SHELL string
CALL file_name
CLOSE
EXIT
76
Index
A
ASCII parser shell 69
B
Bldcio utility 69
Block insertion position 15
Blocks
order 8
special 8
C
Characters
case conversion 7
Command
input timer 39
output 37
output stream 37
Components of the ICCAPI 1
Compound
insertion position 15
Compounds
special 8
Control station 4
CSA functions 16–36
D
Data
structures 9
Database
creation 7
Databases
modifying 1
used by the ICC 1
Default
parameter values 10
DONE operation 37
Driver task 1, 37
command output 37
commands 37–62
Input/Output stream processing 11
77
B0193NE – Rev F Index
syntax 63
E
Error handling 9
Establishing a connection with the CP 1
F
FAIL operation 37
Features of the ICCAPI 1
File
example of input command line 64
Files
pdef/olist 3
Function
return values 16
Function calls
ICCAPI 15
Functions
CSA 16–36
library 1
I
I/O stream processing 11
ICC (Integrated Control and I/O Configurator) 1
ICCAPI
block order 8
characters and case conversion 7
command input stream 12
conventions 15
database creation 7
default parameter names 10
default parameter values 10
driver task Input/Output streams 11
error handling 9
external interface 3
function calls 15
function return values 16
load and save considerations 7
logging 6
operation 4–11
parameter information 10
partial list processing 6
security levels 6
special compounds and blocks 8
transactions 5
78
Index B0193NE – Rev F
ICCPRT script 65
Iccprt utility 69
Input command file
example 64
Input file sample 70
Insertion position
compound and block 15
L
Library of functions 1
List processing 6
Load
considerations 7
LOAD_ALL script 64
Locking the checkpoint file 1
Logging 6
O
"olist" files 3
P
Parameter information 10
Parameter values
function interface 9
Parser
ASCII shell 69
"pdef" files 3
Preparing input files to the driver task 69
S
Save
considerations 7
SAVE_ALL script 65
Scripts
ICCPRT 65
LOAD_ALL 64
SAVE_ALL 65
UNIX shell 69
UNIX shell - example 70–73
Security 6
Session 4
Stream processing
I/O 11
String
79
B0193NE – Rev F Index
“$(var)” 38
Syntax
driver task 63
T
Task command output response
DONE 37
FAIL 37
Timer
command input 39
U
UNIX shell script 69
Utilities 64
ICCPRT script 65
LOAD_ALL script 64
SAVE_ALL Script 65
W
Work file 4
The Foxboro Company

33 Commercial Street
Foxboro, Massachusetts 02035-2099
United States of America
http://www.foxboro.com
Inside U.S. 1-508-543-8750 or 1-888-FOXBORO (1-888-369-2676)
Outside U.S. - Contact your local Foxboro Representative.
Printed in U.S.A. 1198

An Invensys company

B0193ne F

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

B0193ne F

Uploaded by

Copyright:

Available Formats

® B0193NE

CSA ICC and ICCAPI Control Station

Copyright 1994-1998 by The Foxboro Company

SOFTWARE LICENSE AND COPYRIGHT INFORMATION

1. Theory of Operation ................................................................................................... 1

2. ICCAPI Function Calls ............................................................................................. 15

CSA Functions .................................................................................................................. 16

3. ICCAPI Driver Task Commands .............................................................................. 37

GETDEF Command ........................................................................................................ 44

4. Using the ICCAPI..................................................................................................... 63

ICCAPI Function Interface .......................................................................................... 63

5. Writing Applications Using the Driver Task ............................................................. 69

Appendix A. Driver Task Commands — Quick Reference ............................................ 75

Features of the ICCAPI

The pdef and olist Files

CSA ICC and ICCAPI Control Station

Figure 1-1. Function of the pdef/olist Files

Partial List Processing

Load and Save Considerations

Characters and Case Conversion

Special Compounds and Blocks

a. MON and TIM blocks

An equivalent definition is:

Default Parameter Information

Driver Task Input/Output Streams

Command Input Stream

Command Output Stream

Command Output Stream Example:

ECHO 1 add comp1:block1

Data Output Stream

Compound and Block Position

Function Return Values

ICCopen() – Session Open

FUNCTION int ICCopen(char *cp_name, int security, char *user_id)

ARGUMENTS 1. char *cp_name - input

ERRORS Unknown CP or library volume.

Unable to establish connection with CSA and/or control system.

EXAMPLE Refer to ciocfg/api/examples/dthdlrs.c.

ICCclose() – Session Close

FUNCTION int ICCclose(void)

ERRORS No session in progress.

EXAMPLES Refer to ciocfg/api/examples/dthdlrs.c.

ICCoverride() – Lock Override

FUNCTION int ICCoverride(char *cp_name, char *user_id)

ARGUMENTS 1. char *cp_name

ERRORS CP or library volume unavailable.

EXAMPLE Refer to ciocfg/api/examples/dthdlrs.c.

ICCget() – Get Parameters

ARGUMENTS 1. char *name - input

to indicate name filtering as described above under the name argu-

ERRORS No session in progress.

EXAMPLES Refer to ciocfg/api/examples/dtget.c.

ICCseqget() – Get Sequence Code

FUNCTION int ICCseqget(char *blk_name, char *base_path_name)

ARGUMENTS 1. char *blk_name

ERRORS No Session in progress.

EXAMPLE Refer to ciocfg/api/examples/dtseq.c.

ICCgetdef() – Get Default Information

FUNCTION int ICCgetdef(char *type, ICC_DEFAULT_ITEM *item, int maxlen,

ARGUMENTS 1. char *type - input

ERRORS Unknown block type.

EXAMPLE Refer to ciocfg/api/examples/dtget.c.

ICCadd() – Add Compound or Block

FUNCTION int ICCopen(char cp_name, int security, char user_id)

FUNCTION int ICCoverride(char cp_name, char user_id)

FUNCTION int ICCseqget(char blk_name, char base_path_name)

FUNCTION int ICCgetdef(char type, ICC_DEFAULT_ITEM item, int maxlen,

FUNCTION int ICCadd(char name, ICC_PARAM_ITEM item, char *position)

FUNCTION int ICCseqput(char blk_name, char base_path_name)

FUNCTION int ICCladget(char blk_name, char base_path_name)

FUNCTION int ICCladput(char blk_name, char base_path_name)

FUNCTION int ICCmodify(char name, ICC_PARAM_ITEM item)

FUNCTION int ICCmove(char name, char pos_name)

FUNCTION int ICCcopy(char new_name, char name, char *position)

FUNCTION int ICCsave(char pathname, char cpd_name, char *save_name)