CaWingz User's Guide
(by Ben-chin Cha 4/25/94)
Table of Contents
This document assumes that you have read and understood the Wingz user's manuals.
CaWingz is an external Wingz program which, when combined with a set of script files, provides easy-to-use EPICS channel access interface functions for Wingz users. The external function run allows Wingz user to invoke any Unix processor within caWingz.
Few additional functions for accessing static database field and monitoring of value change event is available for EPICS users after release 3.11.
The functions, script files, and usage are briefly described in this document. The script files supplied here serve as examples only. Users are responsible for generating their own spreadsheet and script files.
CaWingz communicates with IOC through channel access function calls.
Program caWingz consists of a set of channel access get and put functions - caGet, caPut, caGetA, caPutA; a set of value change monitoring functions - caAdd, caEvent, caClear, caDebug, caWait; a static database access function - dbField, and a run external process function - run.
The caGet and caPut functions handle getting and putting a numerical (integer or floating point) value from or to a channel device. The caGetA and caPutA functions handle getting and putting a string value (maximum length of 40) to a channel device or database field. The function caAdd adds the process variable into the monitoring list, the caEvent checks for any new event happened for the process variable, and the caClear removes the process variable from the monitoring list. The caWait function allows the user to set the pending event wait time used by CA. The dbField function allows the user to access record type or any static database field. The caDebug function allows the user turns off / on the caWingz output on the terminal. The run function provides the system command invocation feature to caWingz users.
The function caGet accepts the channel process variable name as input argument and returns a numerical value which is the current value obtained from the IOC. For example a channel name corresponding to the highlighted spreadsheet cell can be used as the input argument.
The function caPut accepts the channel process variable name and a numerical number as input arguments and writes the value to the IOC. For example a current highlighted spreadsheet cell can be used to resolve the input arguments.
The function caGetA accepts the channel process variable name as input argument and returns a string value obtained from the IOC. For example a channel name corresponding to the highlighted spreadsheet cell can be used as the input argument.
The function caPutA accepts the channel process variable name and a string value as input arguments and writes the string value to the IOC. For example a channel name corresponding to the highlighted spreadsheet cell can be used to resolve the input arguments.
The function caAdd accepts the channel process variable name as input argument and adds the channel name into the value change monitor list. It starts the value change monitoring for the specified channel.
The function caEvent accepts the channel name as input argument and checks whether new value change event occurred for the specified channel. This function returns 1 if new value change detected, and returns 0 if no new value change detected. Before calling caEvent a caAdd function call must be issued.
The function caClear accepts the channel process variable name as input argument and clears the channel name from the value change monitor list. It stops the value change monitoring for the specified channel.
The function caDebug accepts no input argument. It toggles the terminal printing option. Currently caWingz starts with default printing option ON.
The function caWait accepts a real time value as input argument. It flushes pending events then resets the wait time to this new value for subsequent ca_pend_event calls. Currently caWingz starts with default timeout value of 0.001 second.
The function dbField accepts three input string arguments: database name, channel process variable name, and a database field name. It returns the string of the field for the process variable found from the specified static database. It can also be used to get record type (see example script file caField.txt in next section).
The function run accepts a command string as input and then automatically invokes the command string. The string can be a system command or a name of shell script file which contains more than one tasks.
It is assumed that a user will run Wingz from the wingz directory and the official release of EPICS system resides in the /net/phebos/epics/epics directory. This should be replaced by the corresponding release directory (e.g. for EPICS 3.11 it should be /net/phebos/epics/R3.11). All the work sheets will be stored in the user's wingz directory. All the script files will be stored in the scripts subdirectory.
Few sample script files to demonstrate the usage of the functions from the caWingz are described below. In the following example the &userhomepath should be replaced by the corresponding user home path (e.g. /home/phebos2/CHA)
This script file contains the execution steps associated with the work sheet.
on activate
Run script "&userhomepath/wingz/scripts/caOpen.txt"
end activate
on deactivate
Run script "&userhomepath/wingz/scripts/caClose.txt"
end deactivate
By attaching this script file to a work sheet, the Wingz program automatically runs the script file caOpen.txt when the work sheet is activated and automatically runs the script file caClose.txt when the work sheet is deactivated.
This script file sets the external program caWingz so that the functions defined in caWingz can be accessed from Wingz.
GET EXTERNAL "&userhomepath/wingz/external/caWingz"
This script file removes the external program caWingz so that the functions defined in caWingz can no longer be accessed from Wingz.
REMOVE EXTERNAL "caWingz"
This script file calls the caGet function which gets new values from the IOC and updates the values of a work sheet for the selected column and range of rows. It is assumed that the column 1 contains the process variable names.
DEFINE rangeRef,rowN,row1st,rowI,colI,pvName,rtnVal
rangeRef=REFERENCE(SELECTION(1))
rowN=ROWS(RANGE(rangeRef))
row1st=ROWOF(RANGE(rangeRef))
colI=COLOF(RANGE(rangeRef))
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:caGet(pvName)
PUT rtnVal INTO MAKECELL(colI,rowI)
END FOR
If instead of numerical value a string value to be returned by the channel access call then the calling function caWingz:caGet should be replaced by the caWingz:caGetA.
This script file calls the caPut function which sends values from the selected column and range of rows in a work sheet to the IOC. It is assumed that the column 1 contains the process variable names.
DEFINE rangeRef,rowN,row1st,rowI,colI,pvName,sendVal,rtnVal
rangeRef=REFERENCE(SELECTION(1))
rowN=ROWS(RANGE(rangeRef))
row1st=ROWOF(RANGE(rangeRef))
colI=COLOF(RANGE(rangeRef))
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
sendVal=INDIRECT(MAKECELL(colI,rowI))
rtnVal=caWingz:caPut(pvName,sendVal)
END FOR
If the contents from the selected cells to be put to the IOC as strings by the channel access call then the calling function caWingz:caPut should be replaced by the caWingz:caPutA.
This script file shows an example of monitoring a selected column from the work sheet. It resolves a list of process variable names from the selected column and the range of rows, then add the names to the monitoring list. It monitors the selected channels for 10 seconds and checks for new events every one second and updates the value if event happened. At the end of monitoring it clears the process variable names from the monitoring list. It is assumed that the column 1 contains the process variable names.
DEFINE rangeRef,rowN,row1st,rowI,colI,pvName,rtnVal
DEFINE itime,rtnEvent
rangeRef=REFERENCE(SELECTION(1))
rowN=ROWS(RANGE(rangeRef))
row1st=ROWOF(RANGE(rangeRef))
colI=COLOF(RANGE(rangeRef))
{ ***Add the selected process variable names to the monitoring list *** }
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:caAdd(pvName)
END FOR
{ ***Check for new event and updates the work sheet with the new value*** }
FOR itime=1 TO 10 STEP 1
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnEvent=caWingz:caEvent(pvName)
IF rtnEvent=1
rtnVal=caWingz:caGet(pvName)
PUT rtnVal INTO MAKECELL(colI,rowI)
END IF
END FOR
WAIT FOR 1 SECONDS
END FOR
{ ***Clear the process variable names from the monitoring list *** }
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:caClear(pvName)
END FOR
This script file generates a table combining database definition and IOC information for the selected process variable names. It is assumed that the column 1 of the work sheet contains the process variable names. It uses the caWingz:dbField function to find out the static database information. It puts the record TYPE in column 3, the SCAN field in column 4, and the DTYP field in column 5. It calls the caWingz:caGet to find the current value from the IOC and put the value in column 6. It calls the caWingz:caGetA to find the current setting of string value of the SCAN field from the IOC and put the value in column 7.
DEFINE rangeRef,rowN,row1st,rowI,colI,pvName,rtnVal
DEFINE database,field,rtnBase
rangeRef=REFERENCE(SELECTION(1))
rowN=ROWS(RANGE(rangeRef))
row1st=ROWOF(RANGE(rangeRef))
colI=3
database="chademo.database"
{ ***get database record type put in column 3 ***}
field="TYPE"
PUT field INTO MAKECELL(colI,rowN+2)
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:dbField(database,pvName,field)
PUT rtnVal INTO MAKECELL(colI,rowI)
END FOR
{ ***get database SCAN field put in column 4 ***}
field="SCAN"
PUT field INTO MAKECELL(colI+1,rowN+2)
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:dbField(database,pvName,field)
PUT rtnVal INTO MAKECELL(colI+1,rowI)
END FOR
{ ***get database DTYP field put in column 5 ***}
field="DTYP"
PUT field INTO MAKECELL(colI+2,rowN+2)
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:dbField(database,pvName,field)
PUT rtnVal INTO MAKECELL(colI+2,rowI)
END FOR
{ ***get value from IOC, put in column 6 *** }
field="VAL"
PUT field INTO MAKECELL(colI+3,rowN+2)
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI))
rtnVal=caWingz:caGet(pvName)
PUT rtnVal INTO MAKECELL(colI+3,rowI)
END FOR
{ ***get SCAN value as string from IOC, put in column 7 *** }
field=".SCAN"
PUT field INTO MAKECELL(colI+4,rowN+2)
FOR rowI=row1st TO (row1st+rowN-1) STEP 1
pvName=INDIRECT(MAKECELL(1,rowI)) & field
rtnVal=caWingz:caGetA(pvName)
PUT rtnVal INTO MAKECELL(colI+4,rowI)
END FOR
An example of script file which calls the run function is given below.
DEFINE command,rtnVal
command="/home/phebos2/CHA/bin/testdm"
rtnVal=caWingz:run(command)
where "testdm" is an executable shell script file, the content of "testdm" is given below.
cd /home/phebos2/CHA/appl2/3.5.x3
dm test.dl &
cd /home/phebos2/CHA/appl2
xmca &
This shell script file "testdm" will invoke two processors dm and xmca for user and return to the caller Wingz.
To use the external program caWingz, a Wingz user must follow the procedure below. The purpose here is only to provide an example of how to access caWingz functions from a user's point of view. A user has to refer to the Wingz documents for the detail information of how to use Wingz program.
It is assumed that a user will run Wingz from the wingz directory and the official release of EPICS system resides in the /net/phebos/epics/epics directory. All the work sheets will be stored in the wingz directory. All the script files will be stored in the scripts subdirectory.
- Create a directory for Wingz application, make a link to caWingz in the external directory, and copy the script files to your own script directory.
cd
mkdir wingz
cd wingz
mkdir external
mkdir scripts
cd external
ln -s /net/phebos/epics/epics/Unix/sun4/bin/caWingz .
cd ..
cd scripts
cp /net/phebos/epics/epics/share/src/toolsComm/wingz/scripts/*.txt .
chmod 644 *.txt
- Modify the script file caWingz.txt to replace the script path directory
/home/phebos1/epics/share/src/toolsComm/wingz/scripts/ . . .
by your own script path directory , e. g.
/home/phebos1/USERID/wingz/scripts/ . . .
- Make database link (optional)
If a user desires to use the dbField function, a user has to make appropriate database softlink in the wingz directory.
- Go to the wingz directory, and invoke the Wingz program.
cd
cd wingz
Wingz &
- Create a work sheet with channel names defined in column 1 (column A).
- Select the "Script" pull down menu from the Wingz window, then select the 'Attach Script' item from the menu to attach the 'caWingz.txt' file to the work sheet.
- Create a channel access get value button on your work sheet.
Use the "button icon" from the work sheet to create and place a button on the work sheet.
Select the "Format" pull down menu from the Wingz window, then select the 'Button Info' item from the menu. Name the button as "caGet" or any name you prefer. You may change the appearance of this newly-created button by selecting the size, color, or font from the menu.
Select the "Script" pull down menu from the Wingz window, then select the 'Attach Script' item from the menu to attach the 'caGet.txt' script file to this newly created button.
- Repeat step 1 for creating "caPut", "caGetA", and "caPutA" buttons (Only needed button should be created).
Make sure to save the work sheet under your wingz directory after any new button creation or modification.
- Highlight the range of rows (i.e. corresponding to device names) of a given column (not the column 1) where the new values to be recorded.
Click the "caGet" button resulting that these newly-obtained values been written to the highlighted column of the work sheet.
- Enter new values to a column corresponding to process variable names on the the work sheet. Highlight the new value column and click the "caPut" button resulting that these new values been put to IOC from the work sheet.
- Use the "button icon" from the work sheet to create and place a button on the work sheet.
- Select the "Format" pull down menu from the Wingz window, then select the 'Button Info' item from the menu. Name the button reflecting the processor you want to run.
- You may change the appearance of this newly-created button by selecting the size, color, or font from the menu.
- Select the "Script" pull down menu from the Wingz window, then select the 'Button Script' item from the menu to open the button object script window for this newly created button.
- Type in the following button script
DEFINE command,rtnVal
command="command or name of script file"
rtnVal=caWingz:run(command)
- Select the "Close" option from the menu of the button object script window, and click the "Save" button before closing the window
- Turn on the pointer "selection icon" from the work sheet and click the newly created run button to test the command
Note: You should see the "Enter caWingz Version:#.#" printed on your terminal session, before you can use any of the channel access buttons. If you don't see the "Enter caWingz" message, quit the work sheet window and reopen the work sheet again. This should properly load the caWingz functions into Wingz. You will see the "Exit caWingz" message printed on your terminal session when you quit the work sheet window.
The average execution time in seconds used by caWingz functions are tabulated in the following table. Number of iterations used is 200 in each case.
TABLE 1. Time in Seconds Used in Wingz Functions for 200 Steps
-----------------------------------------------------
Function Name Time in Seconds Time in Seconds
in caWingz (with printing on) (without printing)
-----------------------------------------------------
caGet 3 1
caPut 2 <1
caGetA 3 1
caPutA 2 1
caEvent 1 <1
caAdd 1 <1
caClear 1 <1
dbField 28 25
PUT 3 3
caGet + PUT 6 4
-----------------------------------------------------
The PUT function is the Wingz function which puts a value or string to a cell on the work sheet. The average time used by a simple Wingz PUT takes 3/200 = 0.015 seconds. All the caWingz functions involving the sheet update should add the additional time used by PUT function. For example for a simple caGet plus writing the return value to the work sheet takes about (3+3)/200 = 0.03 second.