1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>hsc - Execute Shell Commands</TITLE>
<LINK REV="owns" TITLE="Thomas Aglassinger" HREF="mailto:agi@giga.or.at">
<LINK REL="Next" HREF="../project/index.html">
<LINK REL="Copyright" HREF="../copy.html">
<LINK REL="Previous" HREF="prefs.html">
<META name="ROBOTS" content="NOINDEX, NOFOLLOW">
</HEAD>
<BODY>
<A HREF="../index.html"><IMG SRC="../image/main.gif" ALT="Contents" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<IMG SRC="../image/noindex.gif" ALT="-----" ALIGN="middle" WIDTH="70" HEIGHT="16">
<A HREF="../copy.html"><IMG SRC="../image/copy.gif" ALT="Copyright" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="../index.html"><IMG SRC="../image/back.gif" ALT="Up" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="prefs.html"><IMG SRC="../image/prev.gif" ALT="Previous" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="../project/index.html"><IMG SRC="../image/next.gif" ALT="Next" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<HR>
<H1>Execute Shell Commands</H1>
<P>You can invoke shell-commands during processing of a hsc source. The
output of the command can be assigned to an special attribute or
immediately being included into the document. This can be useful to
include data from external applications (like databases), prepared
by scripts (eg. Rexx), which of course you have to write yourself.</P>
<P>This functionality is provided by the hsc tag <CODE><$exec></CODE></P>
<H2>Possible Attributes</H2>
<DL>
<DT><CODE>COMMAND:string/required</CODE>
<DD>Specifies command to be executed. This attribute is required
<DT><CODE>INCLUDE:bool</CODE>
<DD>If this attribute occurs, the output the command sends to
<CODE>stdout</CODE> (or the filename specified with <CODE>FILE</CODE>)
is included in the document.
<DT><CODE>ATTRIBUTE:string</CODE>
<DD>Using this attribute, you can select an attribute you've
created before using <A HREF="spctags.html#define"><CODE><$define></CODE></A> to store the data the
command sends to <CODE>stdout</CODE>.
<DT><CODE>FILE:string</CODE>
<DD>Specifies filename where the command is expected to store
the output. The filename is relative to the source-directory.
If this attribute is not set, <KBD>hsc</KBD> will assume the command
to output to <CODE>stdout</CODE> and will redirect the output to a
temporary file. This attribute is only useful if you have
also set at least one of <CODE>INCLUDE</CODE> or
<CODE>ATTRIBUTE</CODE>
<DT><CODE>TEMPORARY:bool</CODE>
<DD>This attribute has the same meaning as within <A HREF="spctags.html#include"><CODE><$include></CODE></A>. Note that
it can be reasonable to specify it, even if you set a specific
output-file, and not only for temporary-files created by <KBD>hsc</KBD>.
<DT><CODE>REMOVE:enum("auto|on|off")="auto"</CODE>
<DD>This attribute tells <KBD>hsc</KBD> what to do with the output-file after
all data have been read. If you set it to
<CODE>REMOVE="off"</CODE>, the file will be left untouched. If no one
else is going to remove it, it will continue to exist until
doomsday or the next head-crash.
<P>If you didn't specify an output filename (using <CODE>FILE</CODE>),
this can clutter your temporary-directory (usually "<I>t:</I>")
with loads of files having strange names like
"<I>hsc0x321764.tmp</I>".</P>
<P>To avoid this, you can set <CODE>REMOVE="on"</CODE>, so the output-file
will always be removed.</P>
<P>By default, <CODE>REMOVE="auto"</CODE> is set. This will remove the
file, if <CODE>TEMPORARY</CODE> has been enabled, and - if
<CODE>INCLUDE</CODE> has been activated, too - no messages
showed up during including the file.</P>
<STRONG>Note</STRONG>: Never trust freeware-programmers when they
start removing your files. So never use <CODE><$exec></CODE> on important
data without any backup, and always use <CODE>REMOVE="off"</CODE>
if your data are not really completely temporary.
</DL>
<P>Additionally, you can use all attributes of <CODE><$include></CODE> that change
the appearance of the included data, like <CODE>PRE</CODE>,
<CODE>SOURCE</CODE> etc. - Of course, this only makes sense if the
<CODE>INCLUDE</CODE>-attribute has been set.</P>
<P>You can set both <CODE>INCLUDE</CODE> and <CODE>ATTRIBUTE</CODE> with
one call to <CODE><$exec></CODE>.</P>
<H2>Examples</H2>
<DL>
<DT><CODE><$exec COMMAND="dpaint"></CODE>
<DD>Invokes Deluxe-Paint. Now you can paint whatever you like.
When you quit the program, <KBD>hsc</KBD> will continue to process
it's source. Note that this is not a very useful example.
<DT><CODE><$exec COMMAND="list #?.hsc" TEMPORARY INCLUDE SOURCE PRE></CODE>
<DD>List all hsc-sources in the current directory and include
this list into the current document. The output of the
<KBD>list</KBD>-command is redirected to a temporary file,
which is removed afterwards.
<DT><CODE><$exec COMMAND="echo Hello! >echo.tmp" TEMPORARY INCLUDE FILE="echo.tmp"></CODE>
<DD>List all hsc-sources in the current directory and include
this list into the current document. The output of the
<KBD>list</KBD>-command is obviously redirected to a file
called <I>echo.tmp</I>, which <KBD>hsc</KBD> tries to read because of
the <CODE>FILE</CODE>-attribute.
<DT><CODE><$define output:string></CODE><BR>
<CODE><$exec COMMAND="list #?.hsc" ATTRIBUTE="output"></CODE>
<DD>List all *.hsc-files in current directory and assign output to
the attribute <CODE>output</CODE>; no data are included into the
current document.
</DL>
<H2>A More Complex Example</H2>
If you want to create a portable hsc source to insert a listing of a
directory, you could try something like this:
<PRE><$if COND=(HSC.SYSTEM="AMIGA")>
<$exec COMMAND="list DIRS" TEMPORARY INCLUDE SOURCE PRE>
<$elseif COND=(HSC.SYSTEM="UNIX")>
<$exec COMMAND="ls -ld" TEMPORARY INCLUDE SOURCE PRE>
<$else>
<$message text="operating system not supported" class="warning">
</$if>
</PRE>
And the data created by this code sequence would look like this:
<PRE>exmpl Dir ---arwed 26-May-97 00:18:03
project Dir ----rwed Yesterday 22:45:55
features Dir ----rwed Yesterday 01:21:05
macro Dir ----rwed 10-Oct-97 03:59:24
inc Dir ----rwed Today 03:17:57
script Dir ----rwed Yesterday 21:57:24
6 directories - 12 blocks used
</PRE>
<H2>Computing Complex Data</H2>
<P>As <KBD>hsc</KBD> is only a simple preprocessor, but not a programming language, it
can not do certain things. For example, there are no string functions. But
you can use external commands to gain the same result.</P>
<P>The Rexx-script <I><A HREF="../../grafflwerk/StripNastyChars.rexx">grafflwerk/StripNastyChars.rexx</A></I> together with
<I><A HREF="../../grafflwerk/StripNastyChars.hsc">grafflwerk/StripNastyChars.hsc</A></I> shows how to strip all but alpha numeric
characters from a given string.</P>
To better understand what <I>StripNastyChars.rexx</I>, you can first try to call it from
the command line. Set your working directory to <I>grafflwerk</I>, and
type:
<PRE>rx StripNastyChars.rexx bla:sülz:fasel</PRE>
results in
<PRE>blaslzfasel</PRE>
If you tried this yourself, you maybe noticed that the Rexx-script does not
output a linefeed at the end of line. This is done by avoiding to use
<PRE>SAY stripped</PRE>
to display the converted data. Instead, you will find a
<PRE>call WriteCH(stdout, stripped)</PRE>
This simply is because <I>StripNastyChars.hsc</I> assigns the output of this script to
a target attribute called <CODE>clean-data</CODE> by means of
<PRE>
<$exec command=("rx StripNastyChars.rexx " + nasty-data) ATTRIBUTE=clean-data>
</PRE>
Because of obvious reasons, the linefeed character created by
<CODE>SAY</CODE> would be unwanted in the value of the target
attribute. Therefor, the interesting part of the created html-document
will look like:
<PRE>
Converted "This#Text|Contains!Ñâ§ïÿ/Characters"
to "ThisTextContainsCharacters".
</PRE>
It should be easy for you to put this functionality in a macro.
<H2>Problems</H2>
<P>Technically speaking, <KBD>hsc</KBD> redirects the output of you command by
appending a " <CODE>></CODE><I>filename</I>" to the command-string.
For example, if you called</P>
<PRE>
<$exec COMMAND="list #?.hsc" INCLUDE>
</PRE>
<P><KBD>hsc</KBD> will invoke the command like</P>
<PRE>
list #?.hsc >hsc0x321764.tmp
</PRE>
<P>with <I>hsc0x321764.tmp</I> chosen as temporary output file by
<KBD>hsc</KBD>. If you specify the <CODE>FILE</CODE> attribute, you tell <KBD>hsc</KBD>
where to expect the output. But now you are responsible to redirect
it yourself. For example,</P>
<PRE>
<$exec COMMAND="list #?.hsc >list.tmp" INCLUDE FILE="list.tmp">
<$exec COMMAND="list #?.hsc TO list.tmp" INCLUDE FILE="list.tmp">
</PRE>
<P>will both create an output in <I>list.tmp</I>, where <KBD>hsc</KBD> will
also look for it. But the next one will fail:</P>
<PRE>
<$exec COMMAND="list #?.hsc >list.tmp" FILE="tmp.list">
</PRE>
<P>The reason is obvious: The command outputs to <I>list.tmp</I>,
but <KBD>hsc</KBD> tries to read <I>tmp.list</I>, which most likely will
not exist.</P>
<P>Another problem will occur, if you redirect the output yourself
within the command call, but do not specify the
<CODE>FILE</CODE>-attribute: <KBD>hsc</KBD> will try to redirect the output twice:
For example,</P>
<PRE>
<$exec COMMAND="list #?.hsc >list.tmp" INCLUDE>
</PRE>
<P>will try to invoke something like</P>
<PRE>
list #?.hsc >list.tmp >hsc0x321764.tmp
</PRE>
<P>The behavior of this call is system dependent, but there's a general
statement on this topic: it most likely won't work.</P>
</BODY></HTML>
|
