950 lines
32 KiB
HTML
Executable File
950 lines
32 KiB
HTML
Executable File
<! This document generated using mif2html Version 1.0 - Walt Akers - 1996 !>
|
|
<head>
|
|
<title>CDEV Documentation</title>
|
|
</head>
|
|
|
|
<body bgcolor="#E0E0FF">
|
|
|
|
<body>
|
|
<! ************************ FILE : cdevScriptServiceTITLE.mif *****************************!>
|
|
<br><hr><br>
|
|
<table width=100%>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start ADDRESS-TITLE ***!><font size=+12 color=Black><strong><em>
|
|
CDEV Script Service
|
|
<!*** Finish ADDRESS-TITLE ***!></p></strong></em></font>
|
|
<!*** Start ADDRESS-VERSION ***!><font size=+1 color=Black>
|
|
|
|
</p>
|
|
A Tool for Using Interactive Scripts from CDEV
|
|
</p>
|
|
|
|
</p>
|
|
Walt Akers
|
|
</p>
|
|
|
|
</p>
|
|
Version 1.0 - February 11, 1997
|
|
</p>
|
|
|
|
</p>
|
|
TJNAF - Thomas Jefferson National Accelerator Facility
|
|
</p>
|
|
|
|
<!*** Finish ADDRESS-VERSION ***!></p></font>
|
|
</td></tr>
|
|
</table>
|
|
<! *************************** TABLE OF CONTENTS ****************************!>
|
|
<br><hr><br>
|
|
<table width=100%>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top align=center>
|
|
<!*** Start CLASS-TOC-TITLE ***!><font size=+3><strong>
|
|
Table of Contents
|
|
<!*** Finish CLASS-TOC-TITLE ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<table>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
1.
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF1">Script Service Fundamentals</a>
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF2">Overview of the Script Service</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF3">Features of the Script Service</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
2.
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF4">Building the Script Service</a>
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF5">Location of Files</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF6">Steps to Building Service</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
3.
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF7">Structure of Data Provided to the Script</a>
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF8">General Form of Data String</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF9">Representation of Scalar Data</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF10">Representation of Array Data</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
4.
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF11">Structure of Data Returned from the Script</a>
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF12">Returning Data to the Calling CDEV Application</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF13">General Form of String Data </a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF14">Returning a Single Result Packet </a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF15">Returning Multiple Result Packets </a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF16">Special Considerations</a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
5.
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF17">DDL Entries for the Script Service</a>
|
|
<!*** Finish HEADING1TOC ***!><br></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start UHEADING2TOC ***!><font size=+1 color=Black>
|
|
<a href="cdevScriptService.html#TOCREF18">Setting Up the DDL </a>
|
|
<!*** Finish UHEADING2TOC ***!><br></font>
|
|
</td></tr>
|
|
</table>
|
|
</td></tr>
|
|
</table>
|
|
<! **************************** LIST OF FIGURES *****************************!>
|
|
<br><hr><br>
|
|
<table width=100%>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top align=center>
|
|
<!*** Start CLASS-LOF-TITLE ***!><font size=+3><strong>
|
|
List of Figures
|
|
<!*** Finish CLASS-LOF-TITLE ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start FIGURELOF ***!><font size=+1 color=Black>
|
|
Figure 1:
|
|
<a href="cdevScriptService.html#LOFREF1">General form of string representation of cdevData</a>
|
|
<!*** Finish FIGURELOF ***!><br></font>
|
|
<!*** Start FIGURELOF ***!><font size=+1 color=Black>
|
|
Figure 2:
|
|
<a href="cdevScriptService.html#LOFREF2">String representation of scalar data in a cdevData object</a>
|
|
<!*** Finish FIGURELOF ***!><br></font>
|
|
<!*** Start FIGURELOF ***!><font size=+1 color=Black>
|
|
Figure 3:
|
|
<a href="cdevScriptService.html#LOFREF3">String representation of array data</a>
|
|
<!*** Finish FIGURELOF ***!><br></font>
|
|
<!*** Start FIGURELOF ***!><font size=+1 color=Black>
|
|
Figure 4:
|
|
<a href="cdevScriptService.html#LOFREF4">Returning a single result packet to the CDEV application</a>
|
|
<!*** Finish FIGURELOF ***!><br></font>
|
|
<!*** Start FIGURELOF ***!><font size=+1 color=Black>
|
|
Figure 5:
|
|
<a href="cdevScriptService.html#LOFREF5">Returning a multiple result packets to the CDEV application</a>
|
|
<!*** Finish FIGURELOF ***!><br></font>
|
|
<!*** Start FIGURELOF ***!><font size=+1 color=Black>
|
|
Figure 6:
|
|
<a href="cdevScriptService.html#LOFREF6">Simple DDL file for the Script Service</a>
|
|
<!*** Finish FIGURELOF ***!><br></font>
|
|
</td></tr>
|
|
</table>
|
|
<! ************************ FILE : ./cdevScriptService.mif *****************************!>
|
|
<br><hr><br>
|
|
<table width=100%>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
1.
|
|
<!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
<a name="TOCREF1">
|
|
Script Service Fundamentals
|
|
</a> <!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF2">
|
|
Overview of the
|
|
Script Service
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
The CDEV Script Service is designed to allow a a CDEV application to execute an
|
|
external script to process a message. The output that is produced by the executable
|
|
will be returned to the caller in the form of a cdevData. The CDEV Script Service
|
|
meets the following requirements.
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF3">
|
|
Features of the
|
|
Script Service
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<table>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
The filename of the script is associated with a CDEV device/message
|
|
combination by using the "filename" field of the service data in the CDEV DDL file.
|
|
Syntax is described later in this document.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
A new process will be spawned for the script each time it is executed. Its standard
|
|
output (stdout) file descriptor will be redirected to return data to the main CDEV
|
|
application, allowing the script to return results to the parent process.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
The external executable file can be any form of user shell, batch file or binary
|
|
application that is supported on the host platform.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
The Script Service supports all of CDEV's send mechanisms; "send",
|
|
"sendNoBlock" and "sendCallback". Because of limits imposed on the number of
|
|
active processes, the user is advised to use the synchronous "send" method
|
|
whenever practical.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
When called by CDEV, the script will receive three arguments; the name of the
|
|
CDEV device associated with the request, the message string that was submitted
|
|
to the device, and a string that describes the contents of the outbound cdevData
|
|
object.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
The reply that is written to the standard output by the script must have a specific
|
|
format as described later in this document. A script may return more than one
|
|
reply packet to the caller.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
The script notifies CDEV that it has written its last reply packet by writing "done"
|
|
alone on a line to the standard output.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
If the script is to return multiple results, it should write "end" alone on a line to the
|
|
standard output between each packet, and write "done" alone on a line following
|
|
the last packet.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
If the script returns a value in the "status" tag of its reply packet, this will be
|
|
provided to the caller as the completion code of the message. Traditionally a
|
|
status of 0 indicates success, and all other values indicated an error occurred.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
<img src="bullet.jpg">
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BULLETED ***!><font size=+1 color=Black>
|
|
Because the callback mechanism of the Script Service is triggered by output from
|
|
the script, the script developer should at least write "done" to the standard output
|
|
even if the application returns no output.
|
|
<!*** Finish BULLETED ***!></p></font>
|
|
</td></tr>
|
|
</table>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
2.
|
|
<!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
<a name="TOCREF4">
|
|
Building the Script Service
|
|
</a> <!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF5">
|
|
Location of Files
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
The source code for the Script Service is provided with the CDEV distribution starting
|
|
with version 1.5. The source code is located in the directory $CDEV/extensions/
|
|
ScriptService. The following steps should be taken to build the ScriptService.
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF6">
|
|
Steps to Building
|
|
Service
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<table>
|
|
<tr><td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
1.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
Obtain and install the CDEV distribution - Version 1.5 or higher.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
2.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
Follow the installation steps to build CDEV on your system. This includes setting
|
|
all of the environment variables required by CDEV.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
3.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
Change directories to <em>$CDEV/extensions/ScriptService/src</em>.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
4.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
There is a collection of platform specific makefiles in the directory <em>$CDEV/
|
|
extensions/cdevGenericServer/include/makeinclude</em>. Link the makefile that is
|
|
appropriate to your architecture to the file Makefile.OS.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
<!*** Start INDENTED ***!><font size=+1 color=Black>
|
|
For example, to link to the makefile for HP-UX, you would type the following
|
|
command.
|
|
</p>
|
|
|
|
</p>
|
|
<em>ln -s Makefile.hpux Makefile.OS</em>
|
|
</p>
|
|
|
|
<!*** Finish INDENTED ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
5.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start NUMBERED ***!><font size=+1 color=Black>
|
|
Type make to compile and link the Script Service shared object. Note that you
|
|
must be using GNU make in order to build this distribution.
|
|
<!*** Finish NUMBERED ***!></p></font>
|
|
</td></tr>
|
|
</table>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
Upon completion the Makefile will generate the shared object for the Script Service
|
|
and will install it into your CDEVSHOBJ directory. At this point you are ready to use
|
|
the Script Service.
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
3.
|
|
<!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
<a name="TOCREF7">
|
|
Structure of Data Provided to the Script
|
|
</a> <!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF8">
|
|
General Form of
|
|
Data String
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
When a developer makes a CDEV send call, he may provide outbound data in the
|
|
form of a cdevData object. Before calling the script, this data is converted into a string
|
|
and provided as the third argument to the application (the first argument is the device
|
|
name and the second is the message). The structure of the outbound data string is of
|
|
the following form.
|
|
</p>
|
|
|
|
<!*** Finish BODY ***!></p></font>
|
|
<!*** Start FIGURE ***!><font size=+0 color=Black><em>
|
|
Figure 1:
|
|
<a name="LOFREF1">
|
|
General form of string representation of cdevData
|
|
<table border=1><tr><td>
|
|
<table>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start PROGRAM ***!><pre><font size=+0 color=Black><strong><em>
|
|
tag1="string value"
|
|
tag2=1.00
|
|
<!*** Finish PROGRAM ***!></strong></em></font></pre>
|
|
</td></tr>
|
|
</table>
|
|
</tr></td></table>
|
|
<AFrame 13>
|
|
</a> <!*** Finish FIGURE ***!></p></em></font>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF9">
|
|
Representation of
|
|
Scalar Data
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
The above example shows two data entries of the form <em>tag=value</em>. Each entry is
|
|
separated by a carriage return. The first entry has a tag name of <em>'tag1'</em> and a value of
|
|
<em>'string value'</em>. You will note that <em>'string value'</em> is enclosed in double quotes in the
|
|
example. This is used to notify the script that the value is a non-numeric character
|
|
string. In the second data entry the value <em>'1.0' </em>is not enclosed in quotes, indicating that
|
|
the value is a number.
|
|
</p>
|
|
The following example illustrates how scalar values stored in a cdevData object would
|
|
look when they are passed to the script.
|
|
</p>
|
|
|
|
<!*** Finish BODY ***!></p></font>
|
|
<!*** Start FIGURE ***!><font size=+0 color=Black><em>
|
|
Figure 2:
|
|
<a name="LOFREF2">
|
|
String representation of scalar data in a cdevData object
|
|
<table border=1><tr><td>
|
|
<table>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start PROGRAM ***!><pre><font size=+0 color=Black><strong><em>
|
|
Data stored in cdevData object:
|
|
Tag: value
|
|
Data Type: character string
|
|
Value: Test
|
|
|
|
Tag: status
|
|
Data Type: integer
|
|
Value: 0
|
|
|
|
Tag: controlHigh
|
|
Data Type: double
|
|
Value: 1.001
|
|
|
|
String representation provided to script:
|
|
value="Test"\\n
|
|
status=0\\n
|
|
controlHigh=1.001\\n
|
|
<!*** Finish PROGRAM ***!></strong></em></font></pre>
|
|
</td></tr>
|
|
</table>
|
|
</tr></td></table>
|
|
<AFrame 1>
|
|
</a> <!*** Finish FIGURE ***!></p></em></font>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF10">
|
|
Representation of
|
|
Array Data
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
If array data is stored in the outbound cdevData object, it too can be provided to the
|
|
script. The data is structured in the standard C format where opening and closing
|
|
braces mark the beginning and end (respectively) of each array bound. The following
|
|
example illustrates how various arrays would be represented as strings.
|
|
<!*** Finish BODY ***!></p></font>
|
|
<!*** Start FIGURE ***!><font size=+0 color=Black><em>
|
|
Figure 3:
|
|
<a name="LOFREF3">
|
|
String representation of array data
|
|
<table border=1><tr><td>
|
|
<table>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start PROGRAM ***!><pre><font size=+0 color=Black><strong><em>
|
|
Data stored in cdevData object:
|
|
Tag: value
|
|
Data Type: character string [3]
|
|
Value: "value1" "value2" "value3"
|
|
|
|
String representation provided to script:
|
|
value={"value1","value2","value3"}\\n
|
|
|
|
<AFrame 5>
|
|
|
|
Data stored in cdevData object:
|
|
Tag: value
|
|
Data Type: double [3]
|
|
Value: 1.0, 2.0, 3.01
|
|
|
|
String representation provided to script:
|
|
value={1,2,3.01}\\n
|
|
|
|
<AFrame 6>
|
|
|
|
Data stored in cdevData object:
|
|
Tag: value
|
|
Data Type: double [3][2]
|
|
Value: 1.0, 2.0, 3.0, 4.0, 5.0, 6.0
|
|
|
|
String representation provided to script:
|
|
value={{1,2},{3,4},{5,6}}\\n
|
|
<!*** Finish PROGRAM ***!></strong></em></font></pre>
|
|
</td></tr>
|
|
</table>
|
|
</tr></td></table>
|
|
<AFrame 3>
|
|
</a> <!*** Finish FIGURE ***!></p></em></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
4.
|
|
<!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
<a name="TOCREF11">
|
|
Structure of Data Returned from the Script
|
|
</a> <!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF12">
|
|
Returning Data to
|
|
the Calling CDEV
|
|
Application
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
Before CDEV starts the script, it creates a pipe that is used to pass data between the
|
|
script and the CDEV application. One end of this pipe is maintained by the application
|
|
and the other end of the pipe is provided to the script as its standard output. This
|
|
means that anytime the script uses the "echo" command or the "printf" command, the
|
|
data that it output's will be transmitted through the pipe to the parent application.
|
|
</p>
|
|
The script is responsible for formatting the data into a collection of character strings
|
|
that can be recognized by the CDEV application.
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF13">
|
|
General Form of
|
|
String Data
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
In general, the data that is returned from a script is of the same form as described in
|
|
the preceding section, "<em>Structure of Data Provided to the Script</em>". The most notable
|
|
difference is that the script must terminate the list by providing a character string that
|
|
indicates that the group of data items is complete; the string "<em>end</em>" or "<em>done</em>" alone on
|
|
a line.
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF14">
|
|
Returning a
|
|
Single Result
|
|
Packet
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
If the script is going to return exactly one result packet (<em>a group of tags and values that
|
|
will be used to populate the result cdevData</em>), then it should write the string "<em>done</em>" on
|
|
a line by itself immediately following the output data. This will notify the Script Service
|
|
that no more data will be returned from the script.
|
|
</p>
|
|
The following example shows how a single result will be returned from a script. Note
|
|
that the "status" tag contains the completion code that will be returned to the CDEV
|
|
application.
|
|
<!*** Finish BODY ***!></p></font>
|
|
<!*** Start FIGURE ***!><font size=+0 color=Black><em>
|
|
Figure 4:
|
|
<a name="LOFREF4">
|
|
Returning a single result packet to the CDEV application
|
|
<table border=1><tr><td>
|
|
<table>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start PROGRAM ***!><pre><font size=+0 color=Black><strong><em>
|
|
#\\! /bin/csh -f
|
|
|
|
echo value=\\"Test\\"
|
|
echo status=0
|
|
echo controlLow=1.5
|
|
echo controlHigh=25.1
|
|
echo done
|
|
<!*** Finish PROGRAM ***!></strong></em></font></pre>
|
|
</td></tr>
|
|
</table>
|
|
</tr></td></table>
|
|
<AFrame 7>
|
|
</a> <!*** Finish FIGURE ***!></p></em></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF15">
|
|
Returning
|
|
Multiple Result
|
|
Packets
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
Returning multiple results from a single script execution is not generally advised.
|
|
However, If the script is going to return more than one result packet, then each interim
|
|
packet should be terminated by the "<em>end</em>" keyword on a line by itself. The "<em>done</em>"
|
|
keyword should follow the last entry.
|
|
</p>
|
|
The following example shows how two results will be returned from a script.
|
|
<!*** Finish BODY ***!></p></font>
|
|
<!*** Start FIGURE ***!><font size=+0 color=Black><em>
|
|
Figure 5:
|
|
<a name="LOFREF5">
|
|
Returning a multiple result packets to the CDEV application
|
|
<table border=1><tr><td>
|
|
<table>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start PROGRAM ***!><pre><font size=+0 color=Black><strong><em>
|
|
#\\! /bin/csh -f
|
|
|
|
echo value=\\"Start Result 1\\"
|
|
echo status=0
|
|
echo end
|
|
echo value=\\"Start Result 2\\"
|
|
echo status=-1
|
|
echo done
|
|
<!*** Finish PROGRAM ***!></strong></em></font></pre>
|
|
</td></tr>
|
|
</table>
|
|
</tr></td></table>
|
|
<AFrame 9>
|
|
</a> <!*** Finish FIGURE ***!></p></em></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF16">
|
|
Special
|
|
Considerations
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
If the script that is being executed will not return a result, then the developer should
|
|
still write "<em>done"</em> to the standard output in order to notify the CDEV application that it
|
|
should no longer wait for output. If the script is not returning a result, it may write the
|
|
terminating <em>"done"</em> at the beginning of the script or at the end. Because synchronous
|
|
calls will block until a reply is received, the developer should return a result to the
|
|
CDEV application as quickly as possible.
|
|
</p>
|
|
If the developer never writes anything to the standard output, then the user specified
|
|
CDEV callback will never be executed... therefore, it is crucial to notify the CDEV
|
|
application when the script has completed.
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
<tr><td valign=top align=right>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
5.
|
|
<!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start HEADING1 ***!><font size=+3 color=Black><strong>
|
|
<a name="TOCREF17">
|
|
DDL Entries for the Script Service
|
|
</a> <!*** Finish HEADING1 ***!></p></strong></font>
|
|
</td></tr>
|
|
<tr><td valign=top>
|
|
<!*** Start UHEADING2 ***!><font size=+1 color=Black><strong>
|
|
<a name="TOCREF18">
|
|
Setting Up the
|
|
DDL
|
|
</a> <!*** Finish UHEADING2 ***!></p></strong></font>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
The following example illustrates how to add a service entry to identify the Script
|
|
Service and how to use the service data to specify the filename that the Script Service
|
|
will execute to service a message.
|
|
<!*** Finish BODY ***!></p></font>
|
|
<!*** Start FIGURE ***!><font size=+0 color=Black><em>
|
|
Figure 6:
|
|
<a name="LOFREF6">
|
|
Simple DDL file for the Script Service
|
|
<table border=1><tr><td>
|
|
<table>
|
|
<tr><td>
|
|
<! ***** Empty Column ***** !>
|
|
</td>
|
|
<td valign=top>
|
|
<!*** Start PROGRAM ***!><pre><font size=+0 color=Black><strong><em>
|
|
/*
|
|
* This is the service definition, it tells CDEV that there is
|
|
* a service named Script and that it will use the cdevData
|
|
* tag 'filename' to read configuration information from the
|
|
* DDL file entries.
|
|
*/
|
|
service Script
|
|
{
|
|
tags {filename}
|
|
}
|
|
|
|
/*
|
|
* This class definition identifies the class scriptClass which
|
|
* supports the "get and "set" commands on attributes "attrib0"
|
|
* and "attrib1". Note that attrib0 will call script /bin/ouch
|
|
* and attrib1 will call script /bin/wammo.
|
|
*/
|
|
class scriptClass
|
|
{
|
|
verbs {get, set}
|
|
attributes
|
|
{
|
|
attrib0 Script {filename = /bin/ouch};
|
|
attrib1 Script {filename = /bin/wammo};
|
|
}
|
|
}
|
|
|
|
/*
|
|
* Finally, the CDEV DDL identifies two devices that are of type
|
|
* scriptClass. Any time one of the supported messages is passed
|
|
* to one of these devices it will activate the corresponding
|
|
* script.
|
|
*/
|
|
scriptClass : device0, device1;
|
|
|
|
<!*** Finish PROGRAM ***!></strong></em></font></pre>
|
|
</td></tr>
|
|
</table>
|
|
</tr></td></table>
|
|
<AFrame 11>
|
|
</a> <!*** Finish FIGURE ***!></p></em></font>
|
|
<!*** Start BODY ***!><font size=+1 color=Black>
|
|
|
|
<!*** Finish BODY ***!></p></font>
|
|
</td></tr>
|
|
</table>
|
|
</body>
|