| blob | 203acad5cc6299d9242b8bdfa6a045fcd9d3171d |
1 \r
2 \r
3 \r
4 \r
5 \r
6 \r
7 SimpleRexx\r
8 \r
9 A Simplified Interface into the world of ARexx\r
10 \r
11 \r
12 ARexx, ARexx, ARexx. 2.0 has ARexx. So, why and how do I\r
13 support ARexx?\r
14 \r
15 The "Why?" has been answered elsewhere and that is not what this\r
16 article is about. Let it suffice that you should support ARexx\r
17 within your application. It is a standard that Commodore is\r
18 pushing and we hope that all new applications will have ARexx\r
19 support.\r
20 \r
21 As to the "How?", that is what this article is about. We\r
22 understand that your existing software may not currently support\r
23 ARexx and that some of you may never even have looked at what is\r
24 needed to support ARexx. New applications can be designed with\r
25 ARexx support in mind and, with the advent of the AppShell by\r
26 David Junod, the work involved to support ARexx is nothing more\r
27 than what is needed to support the features within you\r
28 application. However, existing code may not move into the\r
29 AppShell to easily and you may wish to do a minor upgrade to\r
30 your application to support ARexx.\r
31 \r
32 SimpleRexx is a set of routines that handle the low-level ARexx\r
33 work for you in such a way as to have your application work with\r
34 or without ARexx on the target system. The goal of SimpleRexx is\r
35 to make adding at least the minimum level of ARexx support to an\r
36 application a trivial task.\r
37 \r
38 \r
39 Working with ARexx\r
40 \r
41 REXX is, at its heart, a string processing language. Most\r
42 everything that happens in REXX is in the form of a string; even\r
43 numbers are passed as ASCII representations in most situations.\r
44 \r
45 The Amiga implementation of REXX, known as ARexx, and is part of\r
46 Release 2.0 of AmigaDOS. ARexx has a very complete\r
47 implementation of the REXX language plus the ability to send and\r
48 receive control messages from "outside" sources. ARexx the can\r
49 operate on them in synchronous fashion. The messages contain\r
50 text strings that are then interpreted by ARexx as REXX commands\r
51 or by the "outside" source (the Application) as its commands.\r
52 \r
53 An application that "supports ARexx" is one that can receive and\r
54 send ARexx messages. The messages are, like the REXX language,\r
55 string based and contain the command string of the operation\r
56 wanted.\r
57 \r
58 To make this even more interesting, there are ways to send and\r
59 receive data from ARexx. The data can come in the message itself\r
60 or via the ARexx RVI (Rexx Variable Interface). In either case\r
62 \r
63 \r
64 \r
65 \r
66 data can be transferred to and from ARexx. A complete ARexx\r
67 supporting application would need to be able to send data to a\r
68 requesting ARexx program/script and get data from that program.\r
69 \r
70 The following code shows how to use the ARexx support library to\r
71 send and receive ARexx messages. It also is a "wrapper" around\r
72 these functions to provide a simplified interface to ARexx to\r
73 help promote and simplify the idea of adding ARexx support to\r
74 your existing applications.\r
75 \r
76 SimpleRexxExample.c is a very simple example of the use of the\r
77 calls in SimpleRexx. The test.rexx script is an example script\r
78 to try running while SimpleRexxExample is running. It will send\r
79 commands to SimpleRexxExample in order to control it.\r
80 test.results is the output of test.rexx.\r
81 \r
82 \r
83 Overview of Functions\r
84 \r
85 The source to SimpleRexx is a single file. It is SimpleRexx.c.\r
86 The header file to that contains the type definitions and\r
87 prototypes for the functions is in the file SimpleRexx.h.\r
88 \r
89 Functions that are "available" via SimpleRexx are used as\r
90 follows:\r
91 \r
92 \r
93 rexx_handle=InitARexx(AppBaseName,Extension)\r
94 \r
95 This initializes a SimpleRexx context. The rexx_handle\r
96 is much like a file handle in that it will be used in\r
97 all other calls that make use of this SimpleRexx\r
98 context. Since all SimpleRexx calls correctly check\r
99 the rexx_handle before doing work, you do not need to\r
100 check the return result of this call. If ARexx is not\r
101 available on your system, SimpleRexx will just not do\r
102 anything.\r
103 \r
104 \r
105 port_name=ARexxName(rexx_handle)\r
106 \r
107 This function returns a pointer to the name of the\r
108 ARexx port for your context. The name is based on the\r
109 AppBaseName plus an invocation number such that\r
110 multiple copies of an application can run at the same\r
111 time. If you have no ARexx port, it returns NULL.\r
112 \r
113 \r
114 sigmask=ARexxSignal(rexx_handle)\r
115 \r
116 This function returns the signal bit mask that is\r
117 needed for the port that is part of your context. This\r
118 should be combined with other signal masks to produce\r
119 the argument to the Wait() call. This returns NULL if\r
121 \r
122 \r
123 \r
124 \r
125 there is no signal mask.\r
126 \r
127 \r
128 rmsg=GetARexxMsg(rexx_handle)\r
129 \r
130 This function returns the next Rexx message that is\r
131 waiting. rmsg==NULL if there is no message or ARexx is\r
132 not around. rmsg==REXX_RETURN_ERROR if a message sent\r
133 to ARexx via SendARexxMsg() returns an error.\r
134 \r
135 \r
136 ReplyARexxMsg(rexx_handle,rmsg,result,error)\r
137 \r
138 This function replies the ARexx message gotten via\r
139 GetARexxMsg(). The "result" is a pointer to a result\r
140 string that is returned via OPTIONS RESULTS in the\r
141 RESULT ARexx variable. If you have no result, set this\r
142 to NULL. Error is the error severity level. If this\r
143 is 0, the result string will be returned, if this is\r
144 non-zero, the error level will be returned in RC.\r
145 \r
146 \r
147 worked=SendARexxMsg(rexx_handle,string,StringFileFlag)\r
148 \r
149 This function sends the string to ARexx. It sets the\r
150 default host to the context and sets the RXFB_STRING\r
151 bit in the message if the "StringFileFlag" is set.\r
152 This routine returns FALSE if the message was not sent\r
153 for some reason.\r
154 \r
155 \r
156 worked=SetARexxLastError(rexx_handle,rmsg,ErrorString)\r
157 \r
158 This function uses the RVI (Rexx Variable Interface) to\r
159 set a variable named <AppBaseName>.LASTERROR to the\r
160 ErrorString. This is where the "error" message should\r
161 go if there is an error. This function returns FALSE\r
162 if this fails for any reason.\r
163 \r
164 \r
165 FreeARexx(rexx_handle)\r
166 \r
167 This closes a SimpleRexx context. The rexx_handle is\r
168 one that was gotten from InitARexx(). The routine is\r
169 fully error checked so that you can pass it a NULL and\r
170 it will do nothing. This is useful if you want to\r
171 just blindly use the rexx_handle.\r
172 \r
173 \f