Professional Documents
Culture Documents
Commands Reference
Onsystex 2012
All Rights Reserved
Note:
This document may contain Confidential Privileged
information and is intended only for the recipient(s).
Receipt of this document by any person other than the
intended recipient does not constitute permission to
examine, copy, or distribute this document thereto and
doing so is strictly prohibited.
If you receive this document in error, please notify the
sender immediately, by either electronic mail message or
telephone. We kindly request that no copies be made of the
original electronic document.
Publisher
Onsystex Publications
Managing Editor
Onsystex Mark eting
Technical Editors
Onsystex Technical Support Team
Onsystex Engineering
Cover Designer
Onsystex - Euphoria .NET
Team Coordinator
Onsystex Technical Publications
Production
Onsystex Mark eting
Contents
Table of Contents
1 Elements of Syntax Statements
49
2 !
49
3 #
49
4 #<
49
5 #>
49
6 $BASICTYPE
50
7 $DEFINE
50
8 $IFDEF
51
9 $IFNDEF
52
10 $INCLUDE
53
11 $INSERT
54
12 $UNDEFINE
54
13 &
54
14 *
55
15 **
55
16 *=
55
17 +
56
18 +=
56
19 -
57
20 -=
57
21 /
58
22 /=
58
23 :
58
24 ^
59
25 :=
59
26 <
60
27 <=
60
28 <>
60
29 =
60
30 =>
60
31 =<
60
32 ><
61
33 >
61
34 >=
61
35 @
61
36 []
64
37 {}
65
38 ABORT
66
39 ABS
67
40 ACOS
68
41 ALPHA
68
42 AND
69
43 ASCII
69
44 ASIN
70
2012 Onsystex Corp.
Contents
45 ATAN
70
46 BITAND
71
47 BITNOT
71
48 BITOR
72
49 BITXOR
73
50 BPIOCP
73
51 BPIOCPN
74
52 BREAK
75
1 Syntax
................................................................................................................................... 75
2 Description
................................................................................................................................... 75
3 Parameters
................................................................................................................................... 75
4 Examples
................................................................................................................................... 76
5 Related
...................................................................................................................................
Command
76
53 BYTELEN
76
1 Syntax
................................................................................................................................... 76
2 Description
................................................................................................................................... 76
3 Example
................................................................................................................................... 76
4 Related
...................................................................................................................................
Commands
77
54 CALCULATE
77
55 CALL
78
56 CALLC
80
57 CASE
81
58 CAT
82
59 CATS
83
60 CHAIN
84
61 CHANGE
84
62 CHAR
85
63 CHARLEN
86
64 CHARS
86
65 CHECKSUM
87
66 CLEAR
87
67 CLEARCOMMON
88
68 CLEARDATA
89
69 CLEARFILE
89
70 CLEARINPUT
90
71 CLEARSELECT
91
72 CLEARSQL
91
73 CLOSE
92
74 CLOSESEQ
93
75 COL1
93
76 COL2
94
77 COMMON
94
78 CONTINUE
97
79 CONVERT
98
80 CONVERT
99
81 COS
100
82 COUNT
100
83 COUNTS
101
84 CRT
102
85 DATA
102
2012 Onsystex Corp.
Contents
86 DATE
103
87 DBTOXML
103
88 DCOUNT
104
89 DEBUG
105
90 DEFFUN
105
91 DEL
107
92 DELETE
108
93 DELETE
109
94 DELETELIST
110
95 DELETEU
111
96 DIM
112
97 DIGEST
114
98 DIR
115
99 DISPLAY
115
100 DISPLAYWIDTH
115
101 DOWNCASE
116
102 DQUOTE
116
103 DROUND
116
104 EBCDIC
117
105 ECHO
118
106 ENCODE
118
107 ENCRYPT
119
108 END
121
10
109 ENTER
121
110 EQ
122
111 EQS
123
112 EQU
123
113 EREPLACE
125
114 EXECUTE
125
115 EXECUTESQL
128
116 EXIT
131
117 EXP
131
118 EXTRACT
132
119 FIELD
133
120 FIELDSTORE
134
121 FILEINFO
135
122 FILELOCK
137
123 FILEUNLOCK
138
124 FIND
138
125 FINDSTR
140
126 FLUSH
141
127 FMT
141
128 FOOTING
143
1 Examples
................................................................................................................................... 143
2 Related
...................................................................................................................................
Commands
144
129 FORMLIST
144
1 Syntax
................................................................................................................................... 144
2 Description
................................................................................................................................... 144
2012 Onsystex Corp.
Contents
11
3 Parameters
................................................................................................................................... 144
4 Examples
................................................................................................................................... 144
5 Related
...................................................................................................................................
Commands
145
130 FOR/NEXT
145
1 Syntax
................................................................................................................................... 145
2 Description
................................................................................................................................... 145
3 Parameters
................................................................................................................................... 146
4 Examples
................................................................................................................................... 146
5 Related
...................................................................................................................................
Commands
147
131 FUNCTION
147
1 Syntax
................................................................................................................................... 147
2 Description
................................................................................................................................... 147
3 Parameters
................................................................................................................................... 147
4 Examples
................................................................................................................................... 148
5 Related
...................................................................................................................................
Command
148
132 GARBAGECOLLECT
149
1 Syntax
................................................................................................................................... 149
2 Description
................................................................................................................................... 149
133 GE
149
1 Syntax
................................................................................................................................... 149
2 Synonyms
................................................................................................................................... 149
3 Description
................................................................................................................................... 149
4 Example
................................................................................................................................... 149
5 Related
...................................................................................................................................
Command
150
134 GES
150
1 Syntax
................................................................................................................................... 150
2 Description
................................................................................................................................... 150
3 Example
................................................................................................................................... 150
135 GET
150
1 Syntax
................................................................................................................................... 150
2 Description
................................................................................................................................... 150
3 Parameters
................................................................................................................................... 151
4 Example
................................................................................................................................... 151
5 Related
...................................................................................................................................
Commands
152
11
12
136 GETENV
152
1 Syntax
................................................................................................................................... 152
2 Description
................................................................................................................................... 152
3 Examples
................................................................................................................................... 152
137 GETLIST
152
1 Syntax
................................................................................................................................... 152
2 Description
................................................................................................................................... 153
3 Parameters
................................................................................................................................... 153
4 Examples
................................................................................................................................... 153
5 Related
...................................................................................................................................
Commands
154
138 GETPTR
154
1 Syntax
................................................................................................................................... 154
2 Description
................................................................................................................................... 154
3 GETPTR
...................................................................................................................................
Function Return Values
154
4 STATUS
...................................................................................................................................
Function Return Values
155
5 Example
................................................................................................................................... 155
6 Related
...................................................................................................................................
Command
155
139 GETPU
155
1 Syntax
................................................................................................................................... 155
2 Description
................................................................................................................................... 155
3 Related
...................................................................................................................................
Commands
155
140 GETQUEUE
156
1 Syntax
................................................................................................................................... 156
2 Description
................................................................................................................................... 156
3 GETQUEUE
...................................................................................................................................
Function Return Values
156
141 GETREADU
157
1 Syntax
................................................................................................................................... 157
2 Description
................................................................................................................................... 157
3 GETREADU
...................................................................................................................................
Function Return Values
157
142 GETUSERGROUP
158
1 Syntax
................................................................................................................................... 158
2 Description
................................................................................................................................... 158
3 Examples
................................................................................................................................... 158
4 Related
...................................................................................................................................
Commands
158
Contents
143 GETUSERID
13
158
1 Syntax
................................................................................................................................... 158
2 Description
................................................................................................................................... 159
3 Example
................................................................................................................................... 159
4 Related
...................................................................................................................................
Commands
159
144 GETUSERNAME
159
1 Syntax
................................................................................................................................... 159
2 Description
................................................................................................................................... 159
3 Examples
................................................................................................................................... 159
4 Related
...................................................................................................................................
Commands
159
145 GOSUB
160
1 Syntax
................................................................................................................................... 160
2 Description
................................................................................................................................... 160
3 Examples
................................................................................................................................... 160
4 Related
...................................................................................................................................
Commands
160
146 GOTO
161
1 Syntax
................................................................................................................................... 161
2 Synonym
................................................................................................................................... 161
3 Description
................................................................................................................................... 161
4 Examples
................................................................................................................................... 161
5 Related
...................................................................................................................................
Commands
161
147 GROUP
161
1 Syntax
................................................................................................................................... 161
2 Description
................................................................................................................................... 162
3 Parameters
................................................................................................................................... 162
4 Examples
................................................................................................................................... 162
5 Related
...................................................................................................................................
Commands
162
148 GROUPSTORE
162
1 Syntax
................................................................................................................................... 162
2 Description
................................................................................................................................... 163
3 Parameters
................................................................................................................................... 163
4 Examples
................................................................................................................................... 164
149 GT
165
1 Syntax
................................................................................................................................... 165
13
14
150 GTS
166
1 Syntax
................................................................................................................................... 166
2 Description
................................................................................................................................... 166
3 Example
................................................................................................................................... 166
151 HASH
166
1 Syntax
................................................................................................................................... 166
2 Description
................................................................................................................................... 166
3 Parameters
................................................................................................................................... 167
152 HEADING
167
1 Syntax
................................................................................................................................... 167
2 Description
................................................................................................................................... 167
3 Parameters
................................................................................................................................... 167
4 Examples
................................................................................................................................... 168
5 Related
...................................................................................................................................
Commands
168
153 HUSH
168
1 Syntax
................................................................................................................................... 168
2 Description
................................................................................................................................... 169
3 Parameters
................................................................................................................................... 169
4 Example
................................................................................................................................... 169
154 ICONV
169
1 Syntax
................................................................................................................................... 169
2 Description
................................................................................................................................... 169
3 Parameters
................................................................................................................................... 170
4 STATUS
...................................................................................................................................
Function Return Values
170
5 Examples
................................................................................................................................... 171
6 Related
...................................................................................................................................
Command
171
171
1 Syntax
................................................................................................................................... 171
2 Description
................................................................................................................................... 171
3 Parameters
................................................................................................................................... 171
4 STATUS
...................................................................................................................................
Function Return Values
172
2012 Onsystex Corp.
Contents
15
5 Examples
................................................................................................................................... 173
6 Related
...................................................................................................................................
Commands
173
173
1 Syntax
................................................................................................................................... 173
2 Description
................................................................................................................................... 173
3 Parameters
................................................................................................................................... 174
4 Example
................................................................................................................................... 174
5 Related
...................................................................................................................................
Command
174
174
1 Syntax
................................................................................................................................... 174
2 Description
................................................................................................................................... 174
3 Parameters
................................................................................................................................... 175
4 Example
................................................................................................................................... 175
5 Related
...................................................................................................................................
Command
175
175
1 Syntax
................................................................................................................................... 175
2 Description
................................................................................................................................... 175
3 Parameters
................................................................................................................................... 175
4 Example
................................................................................................................................... 176
5 Related
...................................................................................................................................
Commands
176
176
1 Syntax
................................................................................................................................... 176
2 Description
................................................................................................................................... 176
3 Parameters
................................................................................................................................... 177
4 Examples
................................................................................................................................... 177
5 Related
...................................................................................................................................
Command
177
178
1 Syntax
................................................................................................................................... 178
2 Description
................................................................................................................................... 178
3 Parameters
................................................................................................................................... 178
4 Example
................................................................................................................................... 178
5 Related
...................................................................................................................................
Command
179
179
1 Syntax
................................................................................................................................... 179
2 Description
................................................................................................................................... 179
2012 Onsystex Corp.
15
16
179
1 Syntax
................................................................................................................................... 179
2 Description
................................................................................................................................... 179
3 Related
...................................................................................................................................
Command
180
180
1 Syntax
................................................................................................................................... 180
2 Description
................................................................................................................................... 180
3 Parameters
................................................................................................................................... 180
4 Example
................................................................................................................................... 181
5 Related
...................................................................................................................................
Command
181
181
1 Syntax
................................................................................................................................... 181
2 Description
................................................................................................................................... 181
3 Parameters
................................................................................................................................... 181
4 Example
................................................................................................................................... 182
5 Related
...................................................................................................................................
Commands
182
182
1 Syntax
................................................................................................................................... 182
2 Description
................................................................................................................................... 182
3 Parameters
................................................................................................................................... 182
4 Examples
................................................................................................................................... 183
5 Related
...................................................................................................................................
Commands
184
184
1 Syntax
................................................................................................................................... 184
2 Description
................................................................................................................................... 184
184
1 Syntax
................................................................................................................................... 184
2 Description
................................................................................................................................... 184
3 Parameters
................................................................................................................................... 184
4 Example
................................................................................................................................... 185
5 Related
...................................................................................................................................
Command
185
185
2012 Onsystex Corp.
Contents
17
1 Syntax
................................................................................................................................... 185
2 Description
................................................................................................................................... 185
3 Example
................................................................................................................................... 185
4 Related
...................................................................................................................................
Commands
185
186
1 Syntax
................................................................................................................................... 186
2 Description
................................................................................................................................... 186
3 Parameters
................................................................................................................................... 186
4 Examples
................................................................................................................................... 186
5 Related
...................................................................................................................................
Commands
186
186
1 Syntax
................................................................................................................................... 187
2 Description
................................................................................................................................... 187
171 ICONVS
187
1 Syntax
................................................................................................................................... 187
2 Description
................................................................................................................................... 187
3 Parameters
................................................................................................................................... 187
4 STATUS
...................................................................................................................................
Function Return Values
187
5 Example
................................................................................................................................... 188
6 Related
...................................................................................................................................
Commands
188
172 IF/THEN/ELSE
188
1 Syntax
................................................................................................................................... 188
2 Description
................................................................................................................................... 188
3 Examples
................................................................................................................................... 189
4 Related
...................................................................................................................................
Commands
189
173 IN
189
1 Syntax
................................................................................................................................... 189
2 Description
................................................................................................................................... 190
3 Example
................................................................................................................................... 190
4 Related
...................................................................................................................................
Commands
190
174 INDEX
190
1 Syntax
................................................................................................................................... 190
2 Description
................................................................................................................................... 190
3 Parameters
................................................................................................................................... 190
4 Examples
................................................................................................................................... 190
2012 Onsystex Corp.
17
18
175 INDICES
191
1 Syntax
................................................................................................................................... 191
2 Description
................................................................................................................................... 191
3 Parameters
................................................................................................................................... 192
4 Related
...................................................................................................................................
Commands
192
176 INMAT
192
1 Syntax
................................................................................................................................... 192
2 Description
................................................................................................................................... 192
3 INMAT
...................................................................................................................................
Function Return Values
192
4 Examples
................................................................................................................................... 193
5 Related
...................................................................................................................................
Commands
193
177 INPUT
193
1 Syntax
................................................................................................................................... 194
2 Description
................................................................................................................................... 194
3 Parameters
................................................................................................................................... 194
4 Examples
................................................................................................................................... 195
5 Related
...................................................................................................................................
Commands
196
178 INPUT @
196
1 Syntax
................................................................................................................................... 196
2 Description
................................................................................................................................... 196
3 Parameters
................................................................................................................................... 196
4 Examples
................................................................................................................................... 197
5 Related
...................................................................................................................................
Commands
198
179 INPUTCLEAR
198
1 Synonym
................................................................................................................................... 198
180 INPUTERR
198
1 Syntax
................................................................................................................................... 198
2 Description
................................................................................................................................... 198
3 Example
................................................................................................................................... 199
4 Related
...................................................................................................................................
Commands
199
181 INPUTIF
199
1 Syntax
................................................................................................................................... 199
2 Description
................................................................................................................................... 199
Contents
19
3 Parameters
................................................................................................................................... 199
4 Related
...................................................................................................................................
Commands
200
182 INPUTNULL
200
1 Syntax
................................................................................................................................... 200
2 Description
................................................................................................................................... 200
3 Example
................................................................................................................................... 200
183 INPUTTRAP
200
1 Syntax
................................................................................................................................... 201
2 Description
................................................................................................................................... 201
3 Parameters
................................................................................................................................... 201
4 Example
................................................................................................................................... 201
5 Related
...................................................................................................................................
Commands
201
184 INS
201
1 Syntax
................................................................................................................................... 202
2 Description
................................................................................................................................... 202
3 Parameters
................................................................................................................................... 202
4 Examples
................................................................................................................................... 202
5 Related
...................................................................................................................................
Commands
202
185 INSERT
203
1 Syntax
................................................................................................................................... 203
2 Description
................................................................................................................................... 203
3 Parameters
................................................................................................................................... 203
4 Examples
................................................................................................................................... 203
5 Related
...................................................................................................................................
Commands
204
186 INT
204
1 Syntax
................................................................................................................................... 204
2 Description
................................................................................................................................... 204
3 Example
................................................................................................................................... 204
187 ISMB
204
1 Syntax
................................................................................................................................... 204
2 Description
................................................................................................................................... 204
3 Related
...................................................................................................................................
Commands
205
188 ISNV
205
1 Syntax
................................................................................................................................... 205
19
20
189 ISNVS
206
1 Syntax
................................................................................................................................... 206
2 Description
................................................................................................................................... 206
3 Example
................................................................................................................................... 206
4 Related
...................................................................................................................................
Command
207
190 ITYPE
207
1 Syntax
................................................................................................................................... 207
2 Description
................................................................................................................................... 207
3 Examples
................................................................................................................................... 207
4 Related
...................................................................................................................................
Commands
208
191 LE
208
1 Syntax
................................................................................................................................... 208
2 Synonyms
................................................................................................................................... 208
3 Description
................................................................................................................................... 208
4 Example
................................................................................................................................... 209
5 Related
...................................................................................................................................
Command
209
192 LEN
209
1 Syntax
................................................................................................................................... 209
2 Description
................................................................................................................................... 209
3 Examples
................................................................................................................................... 209
4 Related
...................................................................................................................................
Commands
210
193 LENS
210
1 Syntax
................................................................................................................................... 210
2 Description
................................................................................................................................... 210
3 Example
................................................................................................................................... 210
4 Related
...................................................................................................................................
Commands
210
194 LES
210
1 Syntax
................................................................................................................................... 210
2 Description
................................................................................................................................... 211
3 Example
................................................................................................................................... 211
195 LISTUSER
211
2012 Onsystex Corp.
Contents
196 LN
21
212
1 Syntax
................................................................................................................................... 212
2 Description
................................................................................................................................... 212
3 Example
................................................................................................................................... 212
4 Related
...................................................................................................................................
Command
213
197 LOCATE
213
1 Syntax
................................................................................................................................... 213
2 Description
................................................................................................................................... 213
3 Parameters
................................................................................................................................... 213
4 Examples
................................................................................................................................... 215
5 Related
...................................................................................................................................
Commands
216
198 LOCK
216
1 Syntax
................................................................................................................................... 216
2 Description
................................................................................................................................... 216
3 Parameters
................................................................................................................................... 216
4 Examples
................................................................................................................................... 217
5 Related
...................................................................................................................................
Commands
217
199 LOOP/REPEAT
217
1 Syntax
................................................................................................................................... 217
2 Description
................................................................................................................................... 217
3 Parameters
................................................................................................................................... 218
4 Examples
................................................................................................................................... 218
5 Related
...................................................................................................................................
Commands
219
200 LOWER
219
1 Syntax
................................................................................................................................... 219
2 Description
................................................................................................................................... 219
3 Example
................................................................................................................................... 219
4 Related
...................................................................................................................................
Command
220
201 LT
220
1 Syntax
................................................................................................................................... 220
2 Synonym
................................................................................................................................... 220
3 Description
................................................................................................................................... 220
4 Example
................................................................................................................................... 220
5 Related
...................................................................................................................................
Command
221
21
22
202 LTS
221
1 Syntax
................................................................................................................................... 221
2 Description
................................................................................................................................... 221
3 Example
................................................................................................................................... 221
203 MAT
221
1 Syntax
................................................................................................................................... 221
2 Description
................................................................................................................................... 221
3 Parameters
................................................................................................................................... 222
4 Examples
................................................................................................................................... 222
5 Related
...................................................................................................................................
Commands
223
204 MATBUILD
223
1 Syntax
................................................................................................................................... 223
2 Description
................................................................................................................................... 223
3 Parameters
................................................................................................................................... 223
4 Examples
................................................................................................................................... 224
5 Related
...................................................................................................................................
Commands
224
205 MATCH
224
1 Syntax
................................................................................................................................... 224
2 Synonym
................................................................................................................................... 224
3 Description
................................................................................................................................... 224
4 Parameters
................................................................................................................................... 225
5 Examples
................................................................................................................................... 225
206 MATCHFIELD
226
1 Syntax
................................................................................................................................... 226
2 Description
................................................................................................................................... 226
3 Parameters
................................................................................................................................... 226
4 Examples
................................................................................................................................... 227
207 MATPARSE
227
1 Syntax
................................................................................................................................... 227
2 Description
................................................................................................................................... 227
3 Parameters
................................................................................................................................... 227
4 Examples
................................................................................................................................... 228
5 Related
...................................................................................................................................
Commands
228
208 MATREAD
229
2012 Onsystex Corp.
Contents
23
1 Syntax
................................................................................................................................... 229
2 Description
................................................................................................................................... 229
3 Parameters
................................................................................................................................... 229
4 Examples
................................................................................................................................... 230
5 Related
...................................................................................................................................
Commands
230
209 MATREADL
230
1 Syntax
................................................................................................................................... 230
2 Description
................................................................................................................................... 231
3 Parameters
................................................................................................................................... 231
4 Example
................................................................................................................................... 232
5 Related
...................................................................................................................................
Commands
232
210 MATREADU
232
1 Syntax
................................................................................................................................... 232
2 Description
................................................................................................................................... 232
3 Parameters
................................................................................................................................... 233
4 Examples
................................................................................................................................... 233
5 Related
...................................................................................................................................
Commands
234
211 MATWRITE
234
1 Syntax
................................................................................................................................... 234
2 Description
................................................................................................................................... 234
3 Parameters
................................................................................................................................... 234
4 Example
................................................................................................................................... 235
5 Related
...................................................................................................................................
Commands
235
212 MATWRITEU
235
1 Syntax
................................................................................................................................... 235
2 Description
................................................................................................................................... 235
3 Parameters
................................................................................................................................... 236
4 Example
................................................................................................................................... 236
5 Related
...................................................................................................................................
Commands
236
213 MAXIMUM
236
1 Syntax
................................................................................................................................... 237
2 Description
................................................................................................................................... 237
3 Examples
................................................................................................................................... 237
4 Related
...................................................................................................................................
Command
237
214 MBLEN
237
23
24
215 MDPERFORM
238
1 Syntax
................................................................................................................................... 238
2 Description
................................................................................................................................... 238
3 Parameters
................................................................................................................................... 239
4 Examples
................................................................................................................................... 239
5 Related
...................................................................................................................................
Commands
240
216 MINIMUM
240
1 Syntax
................................................................................................................................... 240
2 Description
................................................................................................................................... 240
3 Examples
................................................................................................................................... 241
4 Related
...................................................................................................................................
Command
241
217 MOD
241
1 Syntax
................................................................................................................................... 241
2 Synonym
................................................................................................................................... 241
3 Description
................................................................................................................................... 241
4 Example
................................................................................................................................... 241
218 NE
242
1 Syntax
................................................................................................................................... 242
2 Synonyms
................................................................................................................................... 242
3 Description
................................................................................................................................... 242
4 Examples
................................................................................................................................... 242
5 Related
...................................................................................................................................
Command
242
219 NEG
242
1 Syntax
................................................................................................................................... 243
2 Description
................................................................................................................................... 243
3 Example
................................................................................................................................... 243
4 Related
...................................................................................................................................
Command
243
220 NES
243
1 Syntax
................................................................................................................................... 243
2 Description
................................................................................................................................... 243
3 Example
................................................................................................................................... 243
2012 Onsystex Corp.
Contents
221 NOCONVERT
25
243
1 Syntax
................................................................................................................................... 244
2 Description
................................................................................................................................... 244
222 NOT
244
1 Syntax
................................................................................................................................... 244
2 Description
................................................................................................................................... 244
3 Example
................................................................................................................................... 245
4 Related
...................................................................................................................................
Commands
245
223 NOTS
245
1 Syntax
................................................................................................................................... 245
2 Description
................................................................................................................................... 245
3 Example
................................................................................................................................... 245
224 NULL
245
1 Syntax
................................................................................................................................... 245
2 Description
................................................................................................................................... 246
3 Example
................................................................................................................................... 246
225 NUM
246
1 Syntax
................................................................................................................................... 246
2 Description
................................................................................................................................... 246
3 Examples
................................................................................................................................... 246
4 Related
...................................................................................................................................
Commands
247
226 NUMS
247
1 Syntax
................................................................................................................................... 247
2 Description
................................................................................................................................... 247
3 Example
................................................................................................................................... 247
4 Related
...................................................................................................................................
Commands
247
227 OCONV
248
1 Syntax
................................................................................................................................... 248
2 Description
................................................................................................................................... 248
3 Parameters
................................................................................................................................... 248
4 Related
...................................................................................................................................
Command
249
249
1 Syntax
................................................................................................................................... 249
2 Description
................................................................................................................................... 249
2012 Onsystex Corp.
25
26
251
1 Syntax
................................................................................................................................... 251
2 Description
................................................................................................................................... 252
3 Parameters
................................................................................................................................... 252
4 Example
................................................................................................................................... 252
5 Related
...................................................................................................................................
Command
252
252
1 Syntax
................................................................................................................................... 252
2 Description
................................................................................................................................... 252
3 Parameters
................................................................................................................................... 253
4 Example
................................................................................................................................... 253
5 Related
...................................................................................................................................
Command
253
253
1 Syntax
................................................................................................................................... 253
2 Description
................................................................................................................................... 253
3 Parameters
................................................................................................................................... 253
4 Examples
................................................................................................................................... 254
5 Related
...................................................................................................................................
Commands
255
255
1 Syntax
................................................................................................................................... 255
2 Description
................................................................................................................................... 255
3 Parameters
................................................................................................................................... 255
4 Examples
................................................................................................................................... 256
5 Related
...................................................................................................................................
Command
256
257
1 Description
................................................................................................................................... 257
2 Parameters
................................................................................................................................... 257
3 Examples
................................................................................................................................... 258
4 Related
...................................................................................................................................
Command
258
259
1 Syntax
................................................................................................................................... 259
2 Description
................................................................................................................................... 259
2012 Onsystex Corp.
Contents
27
3 Related
...................................................................................................................................
Command
259
259
1 Syntax
................................................................................................................................... 259
2 Description
................................................................................................................................... 259
3 Related
...................................................................................................................................
Command
259
259
1 Syntax
................................................................................................................................... 260
2 Description
................................................................................................................................... 260
3 Parameters
................................................................................................................................... 260
4 Examples
................................................................................................................................... 261
5 Related
...................................................................................................................................
Command
261
261
1 Syntax
................................................................................................................................... 261
2 Description
................................................................................................................................... 261
3 Parameters
................................................................................................................................... 262
4 Related
...................................................................................................................................
Commands
262
262
1 Syntax
................................................................................................................................... 262
2 Description
................................................................................................................................... 262
3 Parameters
................................................................................................................................... 262
4 Examples
................................................................................................................................... 263
5 Related
...................................................................................................................................
Commands
263
263
1 Syntax
................................................................................................................................... 264
2 Description
................................................................................................................................... 264
3 Parameters
................................................................................................................................... 264
4 Examples
................................................................................................................................... 264
264
1 Syntax
................................................................................................................................... 264
2 Description
................................................................................................................................... 265
3 Parameters
................................................................................................................................... 265
4 Example
................................................................................................................................... 265
5 Related
...................................................................................................................................
Command
265
27
28
265
1 Syntax
................................................................................................................................... 265
2 Description
................................................................................................................................... 266
3 Parameters
................................................................................................................................... 266
4 Example
................................................................................................................................... 266
5 Related
...................................................................................................................................
Commands
266
266
1 Syntax
................................................................................................................................... 266
2 Description
................................................................................................................................... 266
3 Parameters
................................................................................................................................... 267
4 Examples
................................................................................................................................... 267
5 Related
...................................................................................................................................
Commands
267
267
1 Syntax
................................................................................................................................... 267
2 Description
................................................................................................................................... 267
3 Parameters
................................................................................................................................... 268
4 Examples
................................................................................................................................... 268
5 Related
...................................................................................................................................
Command
269
244 OCONVS
269
1 Syntax
................................................................................................................................... 269
2 Description
................................................................................................................................... 269
3 Parameters
................................................................................................................................... 269
4 Examples
................................................................................................................................... 269
5 Related
...................................................................................................................................
Commands
270
245 ON/GOSUB
270
1 Syntax
................................................................................................................................... 270
2 Description
................................................................................................................................... 270
3 Parameters
................................................................................................................................... 270
4 Examples
................................................................................................................................... 271
5 Related
...................................................................................................................................
Commands
271
246 ON/GOTO
271
1 Syntax
................................................................................................................................... 271
2 Description
................................................................................................................................... 271
3 Parameters
................................................................................................................................... 271
4 Example
................................................................................................................................... 272
2012 Onsystex Corp.
Contents
29
5 Related
...................................................................................................................................
Commands
272
247 OPEN
272
1 Syntax
................................................................................................................................... 272
2 Description
................................................................................................................................... 272
3 Parameters
................................................................................................................................... 273
4 Examples
................................................................................................................................... 274
5 Related
...................................................................................................................................
Command
274
248 OPENSEQ
274
1 Syntax
................................................................................................................................... 274
2 Description
................................................................................................................................... 275
3 Parameters
................................................................................................................................... 275
4 Example
................................................................................................................................... 275
5 Related
...................................................................................................................................
Commands
276
249 OR
276
1 Syntax
................................................................................................................................... 276
2 Synonym
................................................................................................................................... 276
3 Description
................................................................................................................................... 276
4 Example
................................................................................................................................... 276
5 Related
...................................................................................................................................
Commands
276
250 OSBREAD
276
1 Syntax
................................................................................................................................... 277
2 Description
................................................................................................................................... 277
3 Parameters
................................................................................................................................... 277
4 STATUS
...................................................................................................................................
Function Return Values
278
5 Examples
................................................................................................................................... 278
6 Related
...................................................................................................................................
Command
278
251 OSBWRITE
278
1 Syntax
................................................................................................................................... 279
2 Description
................................................................................................................................... 279
3 Parameters
................................................................................................................................... 279
4 STATUS
...................................................................................................................................
Function Return Values
280
5 Examples
................................................................................................................................... 280
6 Related
...................................................................................................................................
Commands
280
252 OSCLOSE
280
1 Syntax
................................................................................................................................... 281
2012 Onsystex Corp.
29
30
253 OSDELETE
281
1 Syntax
................................................................................................................................... 282
2 Description
................................................................................................................................... 282
3 Parameters
................................................................................................................................... 282
4 STATUS
...................................................................................................................................
Function Return Values
282
5 Examples
................................................................................................................................... 282
6 Related
...................................................................................................................................
Commands
283
254 OSOPEN
283
1 Syntax
................................................................................................................................... 283
2 Description
................................................................................................................................... 283
3 Parameters
................................................................................................................................... 283
4 Example
................................................................................................................................... 284
5 Related
...................................................................................................................................
Command
284
255 OSREAD
284
1 Syntax
................................................................................................................................... 284
2 Description
................................................................................................................................... 284
3 Parameters
................................................................................................................................... 284
4 Example
................................................................................................................................... 285
5 Related
...................................................................................................................................
Commands
285
256 OSWRITE
285
1 Syntax
................................................................................................................................... 285
2 Description
................................................................................................................................... 286
3 Parameters
................................................................................................................................... 286
4 Example
................................................................................................................................... 286
5 Related
...................................................................................................................................
Commands
286
257 PAGE
286
1 Syntax
................................................................................................................................... 286
2 Description
................................................................................................................................... 286
3 Parameters
................................................................................................................................... 287
4 Examples
................................................................................................................................... 287
5 Related
...................................................................................................................................
Commands
287
2012 Onsystex Corp.
Contents
258 PAUSE
31
287
1 Syntax
................................................................................................................................... 287
2 Description
................................................................................................................................... 288
3 Examples
................................................................................................................................... 288
4 Related
...................................................................................................................................
Commands
288
259 PCPERFORM
289
1 Syntax
................................................................................................................................... 289
2 Description
................................................................................................................................... 289
3 Parameters
................................................................................................................................... 289
4 Example
................................................................................................................................... 289
5 Related
...................................................................................................................................
Commands
289
260 PERFORM
289
1 Synonym
................................................................................................................................... 290
261 PRECISION
290
1 Syntax
................................................................................................................................... 290
2 Description
................................................................................................................................... 290
3 Related
...................................................................................................................................
Command
290
262 PRINT
290
1 Syntax
................................................................................................................................... 291
2 Description
................................................................................................................................... 291
3 Parameters
................................................................................................................................... 291
4 Examples
................................................................................................................................... 291
5 Related
...................................................................................................................................
Commands
292
263 PRINTER
292
1 Syntax
................................................................................................................................... 293
2 Description
................................................................................................................................... 293
3 Example
................................................................................................................................... 293
293
1 Syntax
................................................................................................................................... 293
2 Description
................................................................................................................................... 293
3 Example
................................................................................................................................... 293
4 Related
...................................................................................................................................
Command
294
265 PRINTERR
294
1 Syntax
................................................................................................................................... 294
2012 Onsystex Corp.
31
32
266 PROCREAD
296
1 Syntax
................................................................................................................................... 296
2 Description
................................................................................................................................... 296
3 Parameters
................................................................................................................................... 296
4 Examples
................................................................................................................................... 296
5 Related
...................................................................................................................................
Command
299
267 PROCWRITE
299
1 Syntax
................................................................................................................................... 299
2 Description
................................................................................................................................... 299
3 Example
................................................................................................................................... 299
4 Related
...................................................................................................................................
Command
300
268 PROGRAM
300
1 Syntax
................................................................................................................................... 300
2 Description
................................................................................................................................... 300
3 Example
................................................................................................................................... 300
4 Related
...................................................................................................................................
Command
300
269 PROMPT
300
1 Syntax
................................................................................................................................... 301
2 Description
................................................................................................................................... 301
3 Example
................................................................................................................................... 301
4 Related
...................................................................................................................................
Commands
301
270 PWR
301
1 Syntax
................................................................................................................................... 301
2 Description
................................................................................................................................... 302
3 Example
................................................................................................................................... 302
4 Related
...................................................................................................................................
Command
302
271 QUOTE
302
1 Syntax
................................................................................................................................... 302
2 Synonym
................................................................................................................................... 302
3 Description
................................................................................................................................... 302
4 Examples
................................................................................................................................... 302
5 Related
...................................................................................................................................
Command
303
2012 Onsystex Corp.
Contents
272 RAISE
33
303
1 Syntax
................................................................................................................................... 303
2 Description
................................................................................................................................... 303
3 Example
................................................................................................................................... 303
4 Related
...................................................................................................................................
Command
303
273 READ
303
1 Syntax
................................................................................................................................... 303
2 Description
................................................................................................................................... 304
3 Parameters
................................................................................................................................... 304
4 STATUS
...................................................................................................................................
Function Return Values
304
5 Example
................................................................................................................................... 304
6 Related
...................................................................................................................................
Commands
305
274 READBCK
305
1 Syntax
................................................................................................................................... 305
2 Description
................................................................................................................................... 305
3 Parameters
................................................................................................................................... 305
4 STATUS
...................................................................................................................................
Function Return Values
306
5 Example
................................................................................................................................... 306
6 Related
...................................................................................................................................
Commands
306
275 READBCKL
307
1 Syntax
................................................................................................................................... 307
2 Description
................................................................................................................................... 307
3 Parameters
................................................................................................................................... 307
4 STATUS
...................................................................................................................................
Function Return Values
308
5 Example
................................................................................................................................... 308
6 Related
...................................................................................................................................
Commands
309
276 READBCKU
309
1 Syntax
................................................................................................................................... 309
2 Description
................................................................................................................................... 309
3 Parameters
................................................................................................................................... 309
4 STATUS
...................................................................................................................................
Function Return Values
310
5 Example
................................................................................................................................... 310
6 Related
...................................................................................................................................
Commands
311
277 READFWD
311
1 Syntax
................................................................................................................................... 311
2012 Onsystex Corp.
33
34
278 READFWDL
313
1 Syntax
................................................................................................................................... 313
2 Description
................................................................................................................................... 313
3 Parameters
................................................................................................................................... 313
4 STATUS
...................................................................................................................................
Function Return Values
314
5 Example
................................................................................................................................... 314
6 Related
...................................................................................................................................
Commands
314
279 READFWDU
315
1 Syntax
................................................................................................................................... 315
2 Description
................................................................................................................................... 315
3 Parameters
................................................................................................................................... 315
4 STATUS
...................................................................................................................................
Function Return Values
316
5 Example
................................................................................................................................... 316
6 Related
...................................................................................................................................
Commands
316
280 READL
317
1 Syntax
................................................................................................................................... 317
2 Description
................................................................................................................................... 317
3 Parameters
................................................................................................................................... 317
4 STATUS
...................................................................................................................................
Function Return Values
318
5 Examples
................................................................................................................................... 318
6 Related
...................................................................................................................................
Commands
318
281 READLIST
318
1 Syntax
................................................................................................................................... 319
2 Synonym
................................................................................................................................... 319
3 Description
................................................................................................................................... 319
4 Parameters
................................................................................................................................... 319
5 Example
................................................................................................................................... 319
6 Related
...................................................................................................................................
Commands
320
282 READNEXT
320
1 Syntax
................................................................................................................................... 320
2012 Onsystex Corp.
Contents
35
2 Description
................................................................................................................................... 320
3 Parameters
................................................................................................................................... 321
4 Examples
................................................................................................................................... 322
5 Related
...................................................................................................................................
Commands
322
283 READNEXTTUPLE
322
1 Syntax
................................................................................................................................... 322
2 Description
................................................................................................................................... 323
3 Parameters
................................................................................................................................... 323
4 Example
................................................................................................................................... 323
5 Related
...................................................................................................................................
Commands
324
284 READSELECT
324
1 Synonym
................................................................................................................................... 324
285 READSEQ
324
1 Syntax
................................................................................................................................... 324
2 Description
................................................................................................................................... 324
3 Parameters
................................................................................................................................... 325
4 Example
................................................................................................................................... 325
5 Related
...................................................................................................................................
Commands
325
286 READT
325
1 Syntax
................................................................................................................................... 325
2 Description
................................................................................................................................... 325
3 Parameters
................................................................................................................................... 325
4 Example
................................................................................................................................... 326
5 Related
...................................................................................................................................
Commands
326
287 READU
327
1 Syntax
................................................................................................................................... 327
2 Description
................................................................................................................................... 327
3 Parameters
................................................................................................................................... 327
4 STATUS
...................................................................................................................................
Function Return Values
328
5 Examples
................................................................................................................................... 328
6 Related
...................................................................................................................................
Commands
328
288 READV
328
1 Syntax
................................................................................................................................... 329
2 Description
................................................................................................................................... 329
3 Parameters
................................................................................................................................... 329
2012 Onsystex Corp.
35
36
289 READVL
330
1 Syntax
................................................................................................................................... 330
2 Description
................................................................................................................................... 330
3 Parameters
................................................................................................................................... 330
4 Example
................................................................................................................................... 331
5 Related
...................................................................................................................................
Commands
331
290 READVU
331
1 Syntax
................................................................................................................................... 331
2 Description
................................................................................................................................... 332
3 Examples
................................................................................................................................... 332
Param eters .......................................................................................................................................................... 332
4 Related
...................................................................................................................................
Commands
333
291 READXBCK
333
1 Syntax
................................................................................................................................... 333
2 Description
................................................................................................................................... 333
3 Parameters
................................................................................................................................... 333
4 Related
...................................................................................................................................
Commands
334
292 READXFWD
334
1 Syntax
................................................................................................................................... 334
2 Description
................................................................................................................................... 334
3 Parameters
................................................................................................................................... 334
4 Related
...................................................................................................................................
Commands
335
293 RECORDLOCKED
335
1 Syntax
................................................................................................................................... 335
2 Description
................................................................................................................................... 335
3 Parameters
................................................................................................................................... 335
4 RECORDLOCKED
...................................................................................................................................
Function Return Values
336
5 STATUS
...................................................................................................................................
Function Return Values
336
6 Related
...................................................................................................................................
Commands
337
294 RECORDLOCKL
337
1 Syntax
................................................................................................................................... 337
2 Description
................................................................................................................................... 337
3 Parameters
................................................................................................................................... 337
Contents
37
4 Examples
................................................................................................................................... 338
5 Related
...................................................................................................................................
Commands
338
295 RECORDLOCKU
338
1 Syntax
................................................................................................................................... 338
2 Description
................................................................................................................................... 338
3 Parameters
................................................................................................................................... 339
4 Related
...................................................................................................................................
Commands
339
296 RELEASE
340
1 Syntax
................................................................................................................................... 340
2 Description
................................................................................................................................... 340
3 Parameters
................................................................................................................................... 340
4 Examples
................................................................................................................................... 340
5 Related
...................................................................................................................................
Commands
341
297 REM
341
1 Syntax
................................................................................................................................... 341
2 Synonyms
................................................................................................................................... 341
3 Description
................................................................................................................................... 341
4 Example
................................................................................................................................... 341
298 REMOVE
342
1 Syntax
................................................................................................................................... 342
2 Description
................................................................................................................................... 342
3 Parameters
................................................................................................................................... 342
4 Examples
................................................................................................................................... 343
5 Related
...................................................................................................................................
Commands
345
299 REMOVE
345
1 Syntax
................................................................................................................................... 345
2 Description
................................................................................................................................... 345
3 Parameters
................................................................................................................................... 346
4 Related
...................................................................................................................................
Commands
346
300 REPLACE
346
1 Syntax
................................................................................................................................... 346
2 Description
................................................................................................................................... 347
3 Parameters
................................................................................................................................... 347
4 Examples
................................................................................................................................... 347
5 Related
...................................................................................................................................
Commands
348
2012 Onsystex Corp.
37
38
301 RESIZET
348
1 Syntax
................................................................................................................................... 349
2 Description
................................................................................................................................... 349
3 Parameters
................................................................................................................................... 349
4 Example
................................................................................................................................... 349
5 Related
...................................................................................................................................
Commands
349
302 RETURN
350
1 Syntax
................................................................................................................................... 350
2 Description
................................................................................................................................... 350
3 Example
................................................................................................................................... 350
4 Related
...................................................................................................................................
Commands
350
303 REUSE
350
1 Syntax
................................................................................................................................... 350
2 Description
................................................................................................................................... 350
3 Examples
................................................................................................................................... 351
304 REWIND
351
1 Syntax
................................................................................................................................... 351
2 Description
................................................................................................................................... 351
3 Parameters
................................................................................................................................... 352
4 Example
................................................................................................................................... 352
5 Related
...................................................................................................................................
Commands
352
305 RND
352
1 Syntax
................................................................................................................................... 353
2 Description
................................................................................................................................... 353
3 Example
................................................................................................................................... 353
4 Related
...................................................................................................................................
Command
353
306 RNDSEED
353
1 Syntax
................................................................................................................................... 353
2 Description
................................................................................................................................... 353
3 Example
................................................................................................................................... 353
4 Related
...................................................................................................................................
Command
354
307 RQM
354
1 Synonym
................................................................................................................................... 354
308 SADD
354
2012 Onsystex Corp.
Contents
39
1 Syntax
................................................................................................................................... 354
2 Description
................................................................................................................................... 354
3 Example
................................................................................................................................... 354
309 SCMP
355
1 Syntax
................................................................................................................................... 355
2 Description
................................................................................................................................... 355
3 SCMP
...................................................................................................................................
Function Return Values
355
4 Example
................................................................................................................................... 355
310 SDIV
355
1 Syntax
................................................................................................................................... 355
2 Description
................................................................................................................................... 355
3 Example
................................................................................................................................... 356
311 SELECT
356
1 Syntax
................................................................................................................................... 356
2 Description
................................................................................................................................... 356
3 Parameters
................................................................................................................................... 357
4 Examples
................................................................................................................................... 357
5 Related
...................................................................................................................................
Commands
358
312 SELECTINDEX
359
1 Syntax
................................................................................................................................... 359
2 Description
................................................................................................................................... 359
3 Parameters
................................................................................................................................... 359
4 STATUS
...................................................................................................................................
Function Return Values
359
5 Examples
................................................................................................................................... 359
6 Related
...................................................................................................................................
Commands
360
313 SELECTINFO
360
1 Syntax
................................................................................................................................... 360
2 Description
................................................................................................................................... 360
3 Parameters
................................................................................................................................... 360
4 SELECTINFO
...................................................................................................................................
Function Return Values
361
5 Related
...................................................................................................................................
Commands
361
314 SEND
361
1 Syntax
................................................................................................................................... 361
2 Description
................................................................................................................................... 361
3 Parameters
................................................................................................................................... 361
2012 Onsystex Corp.
39
40
315 SEQ
362
1 Syntax
................................................................................................................................... 362
2 Description
................................................................................................................................... 362
3 Example
................................................................................................................................... 363
4 Related
...................................................................................................................................
Commands
363
316 SEQS
363
1 Syntax
................................................................................................................................... 363
2 Description
................................................................................................................................... 363
3 Example
................................................................................................................................... 363
4 Related
...................................................................................................................................
Commands
363
317 SETENV
363
318 SETINDEX
364
1 Syntax
................................................................................................................................... 364
2 Description
................................................................................................................................... 364
3 Parameters
................................................................................................................................... 364
4 STATUS
...................................................................................................................................
Function Return Values
365
5 Examples
................................................................................................................................... 366
6 Related
...................................................................................................................................
Commands
367
319 SIN
367
1 Syntax
................................................................................................................................... 367
2 Description
................................................................................................................................... 367
3 Examples
................................................................................................................................... 367
4 Related
...................................................................................................................................
Commands
368
320 SLEEP
368
1 Syntax
................................................................................................................................... 368
2 Synonym
................................................................................................................................... 368
3 Description
................................................................................................................................... 368
4 Parameters
................................................................................................................................... 368
5 Examples
................................................................................................................................... 368
321 SMUL
369
1 Syntax
................................................................................................................................... 369
2 Description
................................................................................................................................... 369
Contents
41
3 Example
................................................................................................................................... 369
322 SORT
369
323 SOUNDEX
370
1 Syntax
................................................................................................................................... 370
2 Description
................................................................................................................................... 370
3 Examples
................................................................................................................................... 371
4 Related
...................................................................................................................................
Commands
371
324 SPACE
371
1 Syntax
................................................................................................................................... 371
2 Description
................................................................................................................................... 371
3 Example
................................................................................................................................... 371
4 Related
...................................................................................................................................
Command
371
325 SPACES
372
1 Syntax
................................................................................................................................... 372
2 Description
................................................................................................................................... 372
3 Example
................................................................................................................................... 372
4 Related
...................................................................................................................................
Command
372
326 SPLICE
372
1 Syntax
................................................................................................................................... 372
2 Description
................................................................................................................................... 372
3 Parameters
................................................................................................................................... 372
4 Examples
................................................................................................................................... 373
5 Related
...................................................................................................................................
Commands
373
327 SQRT
374
1 Syntax
................................................................................................................................... 374
2 Description
................................................................................................................................... 374
3 Example
................................................................................................................................... 374
328 SQUOTE
374
1 Syntax
................................................................................................................................... 374
2 Description
................................................................................................................................... 374
3 Examples
................................................................................................................................... 374
4 Related
...................................................................................................................................
Command
374
329 SSUB
375
1 Syntax
................................................................................................................................... 375
2012 Onsystex Corp.
41
42
330 STATUS
375
1 Syntax
................................................................................................................................... 375
2 Description
................................................................................................................................... 375
3 Example
................................................................................................................................... 376
4 Related
...................................................................................................................................
Commands
376
331 STOP
376
1 Syntax
................................................................................................................................... 376
2 Description
................................................................................................................................... 376
3 Examples
................................................................................................................................... 376
4 Related
...................................................................................................................................
Command
377
332 STR
377
1 Syntax
................................................................................................................................... 377
2 Description
................................................................................................................................... 377
3 Parameters
................................................................................................................................... 377
4 Example
................................................................................................................................... 378
5 Related
...................................................................................................................................
Command
378
333 STRS
378
1 Syntax
................................................................................................................................... 378
2 Description
................................................................................................................................... 378
3 Example
................................................................................................................................... 378
4 Related
...................................................................................................................................
Command
378
334 SUBROUTINE
378
1 Syntax
................................................................................................................................... 379
2 Description
................................................................................................................................... 379
3 Parameters
................................................................................................................................... 379
4 Examples
................................................................................................................................... 379
5 Related
...................................................................................................................................
Commands
380
380
1 Syntax
................................................................................................................................... 380
2 Description
................................................................................................................................... 380
3 Parameters
................................................................................................................................... 380
4 Examples
................................................................................................................................... 381
Contents
43
382
1 Syntax
................................................................................................................................... 382
2 Description
................................................................................................................................... 382
3 Parameters
................................................................................................................................... 382
4 STATUS
...................................................................................................................................
Function Return Values
383
5 Example
................................................................................................................................... 383
337 SUBSTRINGS
384
1 Syntax
................................................................................................................................... 384
2 Description
................................................................................................................................... 384
3 Parameters
................................................................................................................................... 384
4 Example
................................................................................................................................... 384
5 Related
...................................................................................................................................
Commands
384
338 SUM
384
1 Syntax
................................................................................................................................... 384
2 Description
................................................................................................................................... 385
3 Parameters
................................................................................................................................... 385
4 Examples
................................................................................................................................... 385
339 SWAP
385
1 Syntax
................................................................................................................................... 385
2 Description
................................................................................................................................... 386
3 Parameters
................................................................................................................................... 386
4 Examples
................................................................................................................................... 386
5 Related
...................................................................................................................................
Command
387
340 SYSTEM
387
1 Syntax
................................................................................................................................... 387
2 Description
................................................................................................................................... 387
3 Parameters
................................................................................................................................... 387
4 Example
................................................................................................................................... 389
341 TAN
390
1 Syntax
................................................................................................................................... 390
2 Description
................................................................................................................................... 390
3 Example
................................................................................................................................... 390
4 Related
...................................................................................................................................
Commands
390
342 TIME
390
43
44
343 TIMEDATE
391
1 Syntax
................................................................................................................................... 391
2 Description
................................................................................................................................... 391
3 Example
................................................................................................................................... 391
4 Related
...................................................................................................................................
Commands
391
391
1 Syntax
................................................................................................................................... 391
2 Description
................................................................................................................................... 392
3 Example
................................................................................................................................... 392
4 Related
...................................................................................................................................
Commands
392
392
1 Syntax
................................................................................................................................... 392
2 Description
................................................................................................................................... 393
3 Parameters
................................................................................................................................... 393
4 Examples
................................................................................................................................... 393
5 Related
...................................................................................................................................
Commands
394
394
1 Syntax
................................................................................................................................... 394
2 Description
................................................................................................................................... 394
3 Parameters
................................................................................................................................... 394
4 Example
................................................................................................................................... 395
5 Related
...................................................................................................................................
Commands
395
347 TRIM
395
1 Syntax
................................................................................................................................... 395
2 Description
................................................................................................................................... 395
3 Parameters
................................................................................................................................... 395
4 Examples
................................................................................................................................... 396
5 Related
...................................................................................................................................
Commands
397
348 TRIMB
397
1 Syntax
................................................................................................................................... 397
2 Description
................................................................................................................................... 397
2012 Onsystex Corp.
Contents
45
3 Example
................................................................................................................................... 397
4 Related
...................................................................................................................................
Commands
397
349 TRIMF
397
1 Syntax
................................................................................................................................... 397
2 Example
................................................................................................................................... 397
3 Related
...................................................................................................................................
Commands
398
350 TRIMS
398
1 Syntax
................................................................................................................................... 398
2 Description
................................................................................................................................... 398
3 Parameters
................................................................................................................................... 398
4 Example
................................................................................................................................... 398
5 Related
...................................................................................................................................
Commands
399
351 OASEXECUTE
399
1 Syntax
................................................................................................................................... 399
2 Description
................................................................................................................................... 399
3 Parameters
................................................................................................................................... 399
4 Related
...................................................................................................................................
Commands
400
352 UNASSIGNED
400
1 Syntax
................................................................................................................................... 400
2 Description
................................................................................................................................... 400
3 Example
................................................................................................................................... 400
353 UNLOCK
401
1 Syntax
................................................................................................................................... 401
2 Description
................................................................................................................................... 401
3 Example
................................................................................................................................... 401
4 Related
...................................................................................................................................
Commands
401
354 UPCASE
401
1 Syntax
................................................................................................................................... 401
2 Description
................................................................................................................................... 402
3 Example
................................................................................................................................... 402
4 Related
...................................................................................................................................
Commands
402
355 WAKE
402
1 Syntax
................................................................................................................................... 402
2 Description
................................................................................................................................... 402
45
46
356 WEOF
403
1 Syntax
................................................................................................................................... 403
2 Description
................................................................................................................................... 403
3 Parameters
................................................................................................................................... 403
4 STATUS
...................................................................................................................................
Function Return Values
404
5 Example
................................................................................................................................... 404
6 Related
...................................................................................................................................
Commands
404
357 WEOFSEQ
404
1 Syntax
................................................................................................................................... 404
2 Description
................................................................................................................................... 404
3 Parameters
................................................................................................................................... 405
4 Example
................................................................................................................................... 405
5 Related
...................................................................................................................................
Commands
405
358 WRITE
405
1 Syntax
................................................................................................................................... 405
2 Description
................................................................................................................................... 405
3 Parameters
................................................................................................................................... 406
4 STATUS
...................................................................................................................................
Function Return Values
406
5 Examples
................................................................................................................................... 407
6 Related
...................................................................................................................................
Commands
407
359 WRITELIST
407
1 Syntax
................................................................................................................................... 407
2 Description
................................................................................................................................... 407
3 Parameters
................................................................................................................................... 407
4 Related
...................................................................................................................................
Commands
408
360 WRITESEQ
408
1 Syntax
................................................................................................................................... 408
2 Description
................................................................................................................................... 408
3 Parameters
................................................................................................................................... 408
4 Example
................................................................................................................................... 409
5 Related
...................................................................................................................................
Commands
409
361 WRITESEQF
409
1 Syntax
................................................................................................................................... 409
2012 Onsystex Corp.
Contents
47
2 Description
................................................................................................................................... 409
3 Parameters
................................................................................................................................... 410
4 Example
................................................................................................................................... 410
5 Related
...................................................................................................................................
Commands
410
362 WRITET
411
1 Syntax
................................................................................................................................... 411
2 Description
................................................................................................................................... 411
3 Parameters
................................................................................................................................... 411
4 STATUS
...................................................................................................................................
Function Return Values
412
5 Example
................................................................................................................................... 412
6 Related
...................................................................................................................................
Commands
412
363 WRITEU
412
1 Syntax
................................................................................................................................... 412
2 Description
................................................................................................................................... 412
3 Parameters
................................................................................................................................... 413
4 STATUS
...................................................................................................................................
Function Return Values
413
5 Example
................................................................................................................................... 414
6 Related
...................................................................................................................................
Commands
414
364 WRITEV
414
1 Syntax
................................................................................................................................... 414
2 Description
................................................................................................................................... 414
3 Parameters
................................................................................................................................... 414
4 STATUS
...................................................................................................................................
Function Return Values
415
5 Examples
................................................................................................................................... 415
6 Related
...................................................................................................................................
Commands
416
365 WRITEVU
416
1 Syntax
................................................................................................................................... 416
2 Description
................................................................................................................................... 416
3 Parameters
................................................................................................................................... 416
4 STATUS
...................................................................................................................................
Function Return Value
417
5 Related
...................................................................................................................................
Commands
417
366 XLATE
418
1 Syntax
................................................................................................................................... 418
2 Description
................................................................................................................................... 418
3 Parameters
................................................................................................................................... 418
4 Related
...................................................................................................................................
Command
418
2012 Onsystex Corp.
47
48
418
424
1 @variables
................................................................................................................................... 424
2 Delimiter
...................................................................................................................................
@variables
426
3 @SYSTEM.RETURN.CODE
...................................................................................................................................
Values
427
ECL @SYSTEM.RETURN.CODE
..........................................................................................................................................................
Values
427
OAS Basic @SYSTEM.RETURN.CODE
..........................................................................................................................................................
Values
428
428
1 Arithmetic
...................................................................................................................................
Operators
428
2 Boolean
...................................................................................................................................
Operators
429
3 Relational
...................................................................................................................................
Operators
429
430
434
437
Index
49
!
! is a synonym for the * and REM commands, which you can use to create comments. It also is a synonym for the
OR operator. For information about creating comments, see REM. For information about the OR operator, see OR.
Synonyms
*, REM, OR
#
# is a synonym for the NE relational operator. For more information, see NE.
Synonyms
<>, ><, NE
#<
#< is a synonym for the GE relational operator. For more information, see GE.
Synonyms
>=, =>, GE
#>
#> is a synonym for the LE relational operator. For more information, see LE.
50
Synonyms
<=, =<, LE
$BASICTYPE
Syntax
$BASICTYPE "param"
Description
The OASYS Basic $BASICTYPE command compiles data in a specified BASICTYPE. The $BASICTYPE
statement must be the first noncomment statement in the program or subroutine.
You can include only one $BASICTYPE statement per file (main program or subroutine), but you can split a
program into separately cataloged subroutines for the purpose of changing BASICTYPE.
If you do not specify $BASICTYPE, OASYS compiles the program in the BASICTYPE specified in the ECL
BASICTYPE command. The default type is U.
Note: The BASICTYPE param must be in quotation marks.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
U
P
R
M
OASYS Basic
Pick BASIC
Advanced Revelation BASIC
M cDonnell Douglas BASIC/ Reality BASIC
$BASICTYPE Parameters
Related Command
OASYS
BASICTYPE For information, see the OASYS Commands Reference.
$DEFINE
Syntax
$DEFINE var
Description
The OASYS Basic $DEFINE command defines a control variable you can use later to direct compilation.
Tip: Keep $DEFINE statements in a separate INCLUDE file to facilitate recompiling programs with different
definitions.
Example
2012 Onsystex Corp.
$DEFINE
51
In the following example, SMALL is defined when the program segment is compiled, and OASYS defines array1
as a 10-element array initialized with 0:
Related Commands
OASYS Basic
$UNDEFINE, EQU
$IFDEF
Syntax
$IFDEF var statements1 [$ELSE statements2] $ENDIF
Description
The OASYS Basic $IFDEF command conditionally compiles OASYS Basic statements depending on the
existence of a variable definition. Variables are defined by $DEFINE.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
statements1
statements2
Examples
In the following example, when you compile the program segment, the system defines array1 as a 10-element array
initialized with 0:
In the next example, when you compile the program segment, the system defines array1 as a 100-element array
and initializes it with 1:
52
Related Commands
OASYS Basic
$DEFINE, $IFNDEF
$IFNDEF
Syntax
$IFNDEF var statements1 [$ELSE statements2] $ENDIF
Description
The OASYS Basic $IFNDEF command conditionally compiles OASYS Basic statements depending on the
absence of a variable definition. Variables are defined by $DEFINE.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
statements1
statements2
Example
In the following example, the program segment nests the $IFDEF and $IFNDEF statements. Upon compilation of
this program, the size of array A might be 1000, 10, or 100 depending on whether LARGE or SMALL is defined. If
both are undefined, the size of A is 100 elements, and the initialized value of array A might be 1 or 0, depending
on whether ONE is defined.
$IFNDEF
Related Commands
OASYS Basic
$DEFINE, $IFDEF
10
$INCLUDE
Syntax
$INCLUDE record [FROM [DICT] filename]
$INCLUDE filename {, | | > } record
$INCLUDE [pathname {, | | > }] seq.filename
Synonym
$INSERT
Description
The OASYS Basic $INCLUDE and $INSERT commands insert OASYS Basic source code from the file you
specify into the program being compiled.
The third form of the syntax inserts code from a UNIX, or Windows platform sequential file.
Note: In $BASICTYPEs P and M, you can enter $INCLUDE or INCLUDE.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
record
filename
Specifies the record that contains the code you want to insert.
Specifies the name of a OASYS directory containing the record. If you do
not specify filename, the system searches for record in the current file
where the program being compiled resides.
Specifies the directory containing seq.filename. If you do not specify
pathname, the system searches for seq.filename in the current directory. The
delimiter between the path and the file or record can be a space, comma (,) or
a greater than sign (>).
pathname
53
54
seq.filename
Note: filename can identify a remote file as determined by the VOC entry. The code to be inserted can also
contain $INCLUDE or $INSERT statements.
Examples
In the following example, the program statement inserts into the program being compiled the code contained in
file code_seg1 in directory BP:
The next example demonstrates the use of the $INCLUDE command in OASYS for UNIX. The program statement
inserts into the program being compiled the code contained in sequential file my_code in directory /usr/ud/mydir:
11
$INSERT
$INSERT is a synonym for the $INCLUDE command. For more information, see $INCLUDE.
Synonym
$INCLUDE
12
$UNDEFINE
Syntax
$UNDEFINE var
Description
The OASYS Basic $UNDEFINE command deletes the definition of var previously defined by $DEFINE.
Related Commands
OASYS Basic
$DEFINE, EQU
13
&
& is a synonym for the AND Boolean operator. For more information, see AND.
Synonym
AND
14
55
*
Syntax
expr * expr
Synonyms
!, REM
Description
The * arithmetic operator multiplies the expressions on either side of the operator. The asterisk (*) also is a
synonym for the ! and REM commands, which you can use to create comments. For information about creating
comments, see REM.
Note: You must include the REUSE function to apply arithmetic operations to all elements of a dynamic array.
Example
The following program segment uses the * operator to multiply VAR1 and VAR2:
Related Commands
OASYS Basic
REM, SMUL
15
**
** is a synonym for the ^ arithmetic operator. For more information, see ^.
Synonym
^
16
*=
Syntax
var *= expr
Description
The *= arithmetic operator multiplies the value of a variable by the number you specify.
Tip: Using the *= operator is a more efficient way of multiplying a variable. For example,
more efficient than
is
Note: You must include the REUSE function to apply arithmetic operations to all elements of a dynamic array.
56
Example
In the following example, the variable LINES is multiplied by 2, which sets LINES equal to 14:
17
+
Syntax
expr + expr
+expr
Description
In the first version of the syntax, the + arithmetic operator adds the two numbers on either side of the operator.
In the second version of the syntax, + acts as a unary plus operator (same as multiplying by +1).
Example
The following program segment is taken from the sample program in Appendix A - Sample Program in
Developing OASYS Basic Applications. The third statement places the cursor at the location computed by
, then the program displays the seventh element of the array ORDER.REC at that location.
Related Commands
OASYS Basic
ABS, NEG, SADD, SUM
18
+=
Syntax
var += expr
Description
The += arithmetic operator increments the value of a variable by the number you specify.
Tip: Using the += operator is a more efficient way of incrementing a variable. For example,
more efficient than
is
+=
57
Example
In the following example, the variable LINES is incremented by 1, which sets LINES equal to 8:
19
Syntax
expr -expr
-expr
Description
In the first version of the syntax, the - arithmetic operator subtracts the expr on the right from the expr on the left
of the operator.
In the second version of the syntax, - acts as a unary minus operator, which produces the same result as
multiplying by -1.
Examples
In the following example, VAR2 is subtracted from VAR1 and the result is assigned to the variable X:
In the next example, the - operator is used as the unary minus and changes the sign of VAR:
Related Commands
OASYS Basic
ABS, NEG
20
-=
Syntax
var -= expr
Description
The -= arithmetic operator decrements the value of a variable by the number you specify.
Tip: Using the -= operator is a more efficient way to decrement a variable. For example,
more efficient than
Example
2012 Onsystex Corp.
is
58
In the following example, the variable LINES is decremented by 1, which sets LINES equal to 6:
21
/
Syntax
expr1 / expr2
Description
The / arithmetic operator divides the two numbers on either side of the operator.
Example
The following statement divides price by cost to determine quantity:
Related Command
OASYS Basic
SDIV
22
/=
Syntax
var /= expr
Description
The /= arithmetic operator divides the value of a variable by the number you specify.
Tip: Using the /= operator is a more efficient way of dividing a variable. For example,
efficient than
is more
Example
In the following example, the variable LINES is divided by 2, which sets LINES equal to 10:
23
:
: is a synonym for the CAT function. For more information, see CAT.
59
Synonym
CAT
24
^
Syntax
expr1^expr2
Synonym
**
Description
The ^ arithmetic operator raises expr1 to the power of expr2.
Example
In the following example, the program segment raises variable X to the power of 3, first using an exponentiation
operator **, second using the PWR function, and last using the exponentiation operator ^. The results are
identical.
Related Command
OASYS Basic
PWR
25
:=
Syntax
var := expr
Description
The := arithmetic operator concatenates the value of an expression to a variable.
Tip: Using the := operator is a more efficient way of concatenating a variable. For example,
more efficient than
Example
In the following example, the variable LINES is concatenated with 0, which sets LINES equal to 100:
is
60
26
<
< is a synonym for the LT (less than) relational operator. For more information, see LT.
Synonym
LT
27
<=
<= is a synonym for the LE relational operator. For more information, see LE.
Synonyms
#>, =<, LE
28
<>
The OASYS Basic <> function retrieves, inserts, or replaces elements in a dynamic array. It also acts as the not
equal to relational operator. For information about retrieving, see EXTRACT. For information about inserting and
replacing, see REPLACE. For information about the not equal to relational operator, see NE.
Synonyms
#, ><, NE
29
=
= is a synonym for the EQ relational operator. For more information, see EQ.
Synonym
EQ
30
=>
=> is a synonym for the GE relational operator. For more information, see GE.
Synonyms
#<, >=, GE
31
=<
=< is a synonym for the LE relational operator. For more information, see LE.
Synonyms
#>, <=, LE
2012 Onsystex Corp.
=<
32
61
><
>< is a synonym for NE relational operator. For more information, see NE.
Synonyms
#, <>, NE
33
>
> is a synonym for the GT relational operator. For more information, see GT.
Synonym
GT
34
>=
>= is a synonym for the GE relational operator. For more information, see GE.
Synonyms
#<, =>, GE
35
@
Syntax
@(col.expr [,row.expr])
@(-num.expr)
Description
The OASYS Basic @ function positions the cursor on the video screen. In the first form, the system positions the
cursor at the column and row you specify.
In the second form, you can specify various terminal functions by num.expr.
Any reference to @ functions turns off automatic screen pagination.
Tip: Assign @ functions to variables if you expect to use the @ function more than once.
Use the @ function in a PRINT statement to direct the terminal to take some action before printing.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
62
col.expr
,row.expr
-num.expr
Tip: Use PRINT, DISPLAY, and CRT in combination with the OASYS Basic @ function to position the cursor on
the screen before printing or to execute other terminal functions. Execute the ECL REUSE.ROW command to
determine whether a line feed is executed when the OASYS Basic PRINT @ function references column only.
For example, PRINT @(10) rather than PRINT @(3,10).
@ Function Options
The following @ function options direct the terminal to take an action.
Option
Description
-1
-2
-3
Option
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
Description
Clear from cursor to end of line.
Enter blink mode.
Stop blink mode.
Enter protected mode.
Stop protected mode.
Backspace one character.
M ove cursor up one line.
Enter half-intensity mode.
Stop half-intensity mode.
Enter reverse video mode.
Stop reverse video mode.
Enter underlining mode.
Stop underlining mode.
Down one line.
Nondestructive space (cursor right).
Audible signal (bell).
Delete character.
Insert character.
Delete line.
Add new blank line.
Turn on the printer.
Turn off the printer.
Print contents of the screen.
Start alternate character set.
@ Function Options (continued)
Option
63
Description
-28
-29 to -49
-50
-51
-52
-53
-54
-55
-56
-57
-58
-59
-60
-61
-62
-63
-64
-65
-66
-67
-68
-69
-70
-71
Option
-72
-73
-74
-75
-76
-77
-78
-79
-80
-81
-82
-83
-84
Description
Sent by function key F9.
Sent by function key F10.
Sent by the next-page key.
Sent by the previous-page key.
Sent by the scroll forward/down key.
Sent by the scroll backward/up key.
Sent by the set-tab key.
Sent by the terminal up arrow key.
Out of keypad transmit key.
Turn bold on.
Turn bold off.
Turn standout on.
Turn standout off.
@ Function Options (continued)
Examples
In the following example, the statement prints the message HI in the fifth column from the left of the screen and
the tenth row down from the top:
In the next example, the program segment prints two messages at different points on the screen:
64
In the next example, the program segment initiates reverse video mode, prints a prompt, and then stops reverse
video mode:
In the next example, the program segment clears the screen and places the cursor in the home position (0,0):
Related Commands
OASYS Basic
@variables For information, see Appendix B, OAS Basic@variables.
OASYS
REUSE.ROW For information, see the OASYS Commands Reference.
36
[]
Syntax
string.expr [num.expr1,num.expr2] = expr
expr = string.expr [num.expr1, num.expr2]
Description
The OASYS Basic [] (square brackets) function extracts or replaces strings.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
string.expr
In the first form, the function replaces part or all of string.expr. In the
second form, the function extracts part or all of string.expr.
Indicates the starting position for the operation. It refers to the character
position where the replacement or extraction operation occurs.
Indicates the number of characters involved in the operation. If OASYS
performs an extraction, it returns that number of characters. If OASYS
performs a replacement, it replaces that number of characters.
[ ] Parameters
num.expr1
num.expr2
[]
65
Examples
In the following example, the program segment extracts the first character of the variable LAST.NAME (in this
case, an S):
In the next example, the program segment changes the first letter of the word Bind in the variable TITLE to W.
The resulting string is Gone with the Wind.
In the next example, the program segment changes the substring 234 spaces:
The following program inserts the null value into string X, which contains 12345, and then prints this element
before and after converting @NULL to the printable string @NULL:
37
{}
{} is a synonym for the CALCULATE function. For more information, see CALCULATE.
Synonym
CALCULATE
66
38
ABORT
Syntax
ABORT [expr]
Description
The OASYS Basic ABORT command terminates the program or subroutine in progress, returning the user to the
OASYS system level. ABORT returns the user to the OASYS prompt, whether the aborted program was called by
another program or executed through a OASYS menu or paragraph. ABORT can include an optional string expr
to display when the program aborts. The expression can contain variables, functions, and/or arithmetic or string
operators.
The OASYS Basic commands ABORT and PRINTERR return the system message whose ID you specify in the
command. You can also retrieve system messages using a OASYS Basic program by opening the system
message file and reading a message record by ID.
Note: ENGLISH.MSG is the default system message file that is activated when you install OASYS. If you execute
oaslang.config to select a language group, a different system message file could be activated. To find out which
language is installed on your system, execute the ECL command SET.LANG CURRENT. For more information,
see OASYS International.
The ABORT command in BASICTYPE P provides additional functions. ABORT prints either a user-defined
message specified by the string expr, or a OASYS system message identified by message-id:
ABORT [message-id]
ABORT [expr,...]
In the first form of the syntax, the message-id must be a variable that evaluates to a key contained in the OASYS
message file. If no message exists, the number entered in message-id is returned. In the second form of the above
syntax, you can specify more than one expr.
Note: You can use the ECL ON.ABORT command so that ABORT does not terminate the process. For
information about the ECL ON.ABORT command, see the OASYS Commands Reference.
Examples
In the following program segment, the user is prompted if an error flag ERR.FLAG has been set. The users input
is read into the variable answer. If answer equals Y, the program aborts.
In the next example, in BASICTYPE P, an error message prints and the program terminates when CLIENTS cannot
be opened:
ABORT
67
In the next example, in BASICTYPE P, the program segment prints the error message from record 10075 in the
error message file if the program aborts:
Related Commands
OASYS Basic
PRINTERR, STOP
OASYS
ON.ABORT, CLEAR.ONABORT For information, see the OASYS Commands Reference.
Error Message File For information, see Administering OASYS on UNIX or Administering OASYS on Windows
Platforms.
39
ABS
Syntax
ABS(expr)
Description
The OASYS Basic ABS function returns the positive numeric value (absolute value) of the argument. expr can be
any numeric expression.
Examples
In the following example, the program segment prints the absolute value of the variable NUM, which is 999:
In the next example, the program statement replaces the variable NUM with its absolute value:
Related Command
OASYS Basic
NEG
68
40
ACOS
Syntax
ACOS(expr)
Description
The OASYS Basic ACOS function returns the trigonometric arc cosine (inverse cosine) of a numeric expression
in degrees. expr must be a value between -1 and +1. ACOS returns a value expressed as the degree of the arc
cosine of the input, which ranges from 0 to 180. If expr evaluates to a value outside the range of -1 to +1, OASYS
displays an error message and returns 0 as the result.
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. Therefore, ACOS returns the null value when expr is the null value.
Examples
In the following example, the program statement assigns 60, the arc cosine of 0.5, to ARCCOS:
In the next example, the program statement prints out the arc cosine of -0.5, which is 120:
Related Commands
ASIN, ATAN, COS, SIN, TAN
41
ALPHA
Syntax
ALPHA("str.expr")
Description
The OASYS Basic ALPHA function tests a string to see if it is composed entirely of alphabetic characters. If str.
expr is made entirely of alphabetic characters (not special characters, escape sequences, or the null value), the
function returns 1. If numeric or other characters are present in str.expr, or if str.expr evaluates to an empty string
or the null value, the function returns 0.
Because OASYS Basic does not recognize multibyte characters as alphabetic, ALPHA returns 0 instead of
converting them.
Examples
In the following example, the program statement prints 0 because the literal string contains the numeric character
2:
In the next example, the program segment prints 1 because the string ALPHA contains only alphabetic
characters:
2012 Onsystex Corp.
ALPHA
69
In the next example, the program statement prints 0 because the string does not contain any characters. An empty
string is not considered to be an alphabetic character.
42
AND
Syntax
expr1 AND expr2
Synonym
&
Description
The AND Boolean operator combines a set of expressions. If expr1 or expr2 is false, the combined expression is
false. Both expressions must be true for a true condition.
Example
In the following example, the program segment combines two expressions (X < Y) and (Y < Z). Both expressions
must be true for the program to call subroutine RETRY.
Related Commands
OASYS Basic
NOT, OR
43
ASCII
Syntax
ASCII(expr)
Description
The OASYS Basic ASCII (American Standard Code for Information Interchange) function converts a string in
EBCDIC (Extended Binary Coded Decimal Information Code) format to the corresponding ASCII values. Even
though the
ASCII function works with data in any format, its results are meaningful only when it is applied to EBCDIC data.
For more information about ASCII character codes, see Appendix A, ASCII Character Codes.
70
Note: Use the OASYS Basic commands CHAR and SEQ to convert between ASCII character and decimal value.
Example
In the following example, the program statement converts the EBCDIC data in the variable E.VAR to ASCII format
and assigns the value to the variable A.VAR:
Related Commands
OASYS Basic
CHAR, CHARS, EBCDIC, SEQ
44
ASIN
Syntax
ASIN(expr)
Description
The OASYS Basic ASIN function returns the trigonometric arc sine (inverse sine) of a numeric expression. expr
must be a value between -1 and +1. ASIN returns a value expressed as the degree of the arc sine of the input,
which ranges from -90 to +90. If expr evaluates to a value outside the range of -1 and +1, the OASYS displays an
error message and returns 0 as the result.
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. Therefore, ASIN returns the null value when expr is the null value.
Examples
In the following example, the program statement assigns 30, the arc sine of 0.5, to ARCSIN:
In the next example, the program statement prints -30, the arc sine of -0.5:
Related Commands
ACOS, ATAN, COS, SIN, TAN
45
ATAN
Syntax
ATAN(expr)
Description
The OASYS Basic ATAN function returns the trigonometric arc tangent (inverse tangent) of a numeric
expression expr in degrees.
2012 Onsystex Corp.
ATAN
71
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. Therefore, ATAN returns the null value when expr is the null value.
Example
In the following example, the program segment prints the arc tangent of the variable VAL. VAL is set to 45.
Related Commands
ACOS, ASIN, COS, SIN, TAN
46
BITAND
Syntax
BITAND(num.expr1,num.expr2)
Description
The OASYS Basic BITAND function performs the bit-wise AND logical function on the arguments num.expr1
and num.expr2.
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. BITAND returns the null value when num.expr1 or num.expr2 is the null value.
The following table shows the results of the BITAND function on various sets of input.
num.expr1
num.expr2
Result
0
0
1
1
3
23
0
1
0
1
9
87
0
0
0
1
1
23
Example
In the following example, the program statement prints a 0:
47
BITNOT
Syntax
BITNOT(num.expr)
72
Description
The OASYS Basic BITNOT function performs the bit-wise NOT logical function on the argument num.expr.
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. Therefore, BITNOT returns the null value when num.expr is the null value.
The following table shows the results of the BITNOT function on the valid input: 0 and 1.
num.expr
0
1
Results
1
0
Example
In the following example, the program statement prints 1:
48
BITOR
Syntax
BITOR(num.expr1,num.expr2)
Description
The OASYS Basic BITOR function performs the bit-wise OR logical function on the arguments num.expr1 and
num.expr2.
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. Therefore, BITOR returns the null value when num.expr1 or num.expr2 is the null value.
The following table shows the results of the BITOR function on various sets of input.
num.expr1
0
0
1
1
3
23
num.expr2
Result
0
0
1
1
0
1
1
1
9
11
87
87
BITOR Function Operation Results
Example
In the following example, the program statement prints a 1:
BITXOR
49
73
BITXOR
Syntax
BITXOR(num.expr1,num.expr2)
Description
The OASYS Basic BITXOR function performs the bit-wise XOR logical function on the arguments num.expr1
and num.expr2.
With null value handling on, the result of any mathematical operation, function, or comparison involving the null
value is the null value. Therefore, BITXOR returns the null value when num.expr1 or num.expr2 is the null value.
The following table shows the results of the BITXOR function on various sets of input.
num.expr1
num.expr2
Result
0
0
0
0
1
1
1
0
1
1
1
0
3
9
10
23
87
64
BITXOR Function Operation Results
Example
In the following example, the program statement prints 1:
50
BPIOCP
Syntax
BPIOCP
Description
The OASYS Basic BPIOCP command turns automatic pagination on. With pagination on, printing to a terminal
(without using cursor addressing) pauses at the bottom of each screen display. The user is prompted before the
next screen is displayed as follows:
Three user responses are valid for this prompt,which are listed in the following table.
Input
ENTER
N
Q
Description
Pressing ENTER displays another screen of data.
Continues display and disables automatic pagination (no pause at bottom of
each screen display).
Quits the current process and returns to the previous process.
74
Example
The page control process is automatically disabled if the @ function is executed. For example, all of the following
statements disable terminal pagination:
With page control disabled, OASYS assumes that the program will control the paging of data. To turn automatic
pagination on from within a OASYS Basic program, use BPIOCP.
An example is provided with the BPIOCPN command.
Related Command
OASYS Basic
BPIOCPN
51
BPIOCPN
Syntax
BPIOCPN
Description
The OASYS Basic BPIOCPN command turns off automatic pagination. With pagination off, printing to a terminal
does not pause at the bottom of each screen display.
Example
In the following example, the program prints the first 60 records of the INVENTORY file with pagination disabled
by @(0,0). Then the BPIOCP command enables automatic pagination. The next 23 records are printed, and the
user is prompted to press ENTER to continue. At this point, the user also can enter N to disable pagination.
After all 60 records have printed, BPIOCPN executes. A prompt displays this information. When the user presses
ENTER at the prompt, 60 records print with pagination off.
BPIOCPN
75
Related Command
OASYS Basic
BPIOCP
52
BREAK
Enter topic text here.
52.1
Syntax
BREAK [KEY] {ON | OFF | expr}
52.2
Description
The OASYS Basic BREAK command enables or disables the interrupt key to exit a program to the ! debugger
prompt and displays the current program line number. The program must have been compiled and run with
debugger options. For instructions, see the ECL BASIC and RUN commands in the OASYS Commands Reference.
The system increments a counter each time BREAK OFF executes and decrements that same counter when
BREAK ON executes. Until the system counter is less than or equal to zero (more BREAK ON statements
executed than BREAK OFF statements), the interrupt key is not operational. This status continues even if you
exit a program with the interrupt key disabled.
52.3
Parameters
The following table describes each parameter of the syntax.
Parameter Description
KEY
76
only.
ON
OFF
expr
52.4
Enables the terminal interrupt key to stop the execution of a OASYS Basic
program and enter the OASYS Basic debugger.
Disables the interrupt key. Pressing the interrupt key has no effect on
program execution.
Enables the terminal interrupt key (to stop the execution of a OASYS Basic
program and enter the OASYS Basic debugger) if the expression is valid.
BREAK Parameters
Examples
In the following example, the program statement decrements the system counter and enables the interrupt key if
the break counter is less than or equal to zero:
In the next example, a numeric expression determines whether to enable the interrupt key. If X is greater than 0,
OASYS enables the interrupt key.
52.5
Related Command
OASYS
PTERM For information, see the OASYS Commands Reference.
53
BYTELEN
Enter topic text here.
53.1
Syntax
BYTELEN (string)
53.2
Description
The OASYS Basic BYTELEN function returns the number of bytes required to store a character. From one to four
bytes could be required.
53.3
Example
The following figure illustrates a string that shows below each character the number of bytes required to store
that character. The string contains eight bytes. Therefore, BYTELEN would return 8 for this string.
BYTELEN
53.4
77
Related Commands
OASYS Basic
CHARLEN, DISPLAYWIDTH, ISMB, LEN, MBLEN
54
CALCULATE
Syntax
CALCULATE(dictionary.item)
{dictionary.item}
Description
The OASYS Basic CALCULATE or {} (braces) function executes a virtual attribute. The dictionary.item must be
a valid virtual attribute within the dictionary previously opened to the @DICT variable with an OPEN statement.
Note: Before you use this function, you must compile the dictionary of the file you will open to the @DICT
variable by using the ECL COMPILE.DICT or CD command.
In the CALCULATE() form, the dictionary.item can be a quoted string or a OASYS Basic variable. The expression
uses the data from the current @RECORD during the evaluation process.
In the {} form, the dictionary.item must be the literal dictionary name with no quotation marks.
You must open a dictionary to @DICT and read the data record into @RECORD for the function to work
properly.
If these functions are successful, they update the values in @CONV, @FORMAT, and @HEADER. You can then
use these @ variables in other OASYS Basic functions, such as ICONV, OCONV, and FMT. For more information
about @ variables, see Appendix B, OASYS Basic@variables.
Example
In the following example, the program segment opens the ORDERS file to the variable ORDER.FILE and the
dictionary of the ORDERS file to the special @DICT variable. After selecting the ORDERS file, the program reads
the value of each record ID into @ID, reads the value of the order record into @RECORD, then uses the {}
(braces) function to evaluate the order balance (storing the total in TOTAL.DUE). The braces function updates
the @CONV and @FORMAT variables, which are used to print the total with the correct format.
78
Related Command
OASYS Basic
ITYPE
55
CALL
Syntax
CALL *sub.name [[(argument1[,argument2][MAT array1 [,MAT array2]]...)] [ASYNC | SYNC] [ON connection
]
CALL @var [[(argument1[,argument2][MAT array1 [,MAT array2]]...)] [ASYNC | SYNC] [ON connection]
CALL sub.name [[(argument1[,argument2][MAT array1 [,MAT array2]]...)] [ASYNC | SYNC] [ON connection]
Description
The OASYS Basic CALL command transfers program control to an external subroutine.
The first form of the syntax calls a globally cataloged subroutine.
The second form of the syntax calls a subroutine named in a variable.
The third form of the syntax calls a subroutine directly.
The called program or subroutine must contain a RETURN statement, which returns control to the calling
program or subroutine.
You can nest subroutines up to 1,024 levels deep.
Note: You must catalog subroutines before using them in a OASYS Basic CALL statement.
You must separate individual arguments by commas and enclose the set of arguments within parentheses. You
can place arguments on multiple lines. Each continued line must end with a comma. Regardless of placement, the
number and type of arguments in the CALL statement must match the number and type of arguments in the
SUBROUTINE statement within the external subroutine. Arrays and singlevalued arguments can be passed in the
CALL
79
same
CALL statement.
Tip: You can also pass variables through named and unnamed common areas. Variables stored in common
area(s) are accessible to both calling and called programs without being passed as arguments. You cannot use
the same variable name in both a SUBROUTINE argument and a common variables list.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
sub.name
@var
argument1, argument2
M AT array1,M AT
array2
ASYNC | SYNC
ON connection
Examples
Note: A sample program that calls an external subroutine is provided in Appendix A, Sample Program in
Developing OASYS Basic Applications.
In the following example, the program statement calls the subroutine VID, passing the variables TITLE and ST:
In the next example, the program segment calls the subroutine MONTHTOTAL by calling @var VID (see CALL
Parameter table above), which holds the string MONTHTOTAL. Note that VID is defined before it is called.
In the next example, the program segment calls the contents of cell (1,12) in the array cells, thus calling the
subroutine RECEIPTS with the argument MON1_12. In the use of @matrices, you can select the array element
by the use of an index (a variable within the dimensions of the array).
In the next example, the program statement calls the globally cataloged subroutine PROMPT.ROUTINE:
In the following example, the CALL statement is invalid because subroutine SUBS, which is shown after this
example, has a different number of arguments than the CALL statement. Called and calling programs must pass
the same number of parameters.
Related Commands
2012 Onsystex Corp.
80
OASYS Basic
CHAIN, COMMON, ENTER, GOSUB, RETURN, SUBROUTINE
56
CALLC
Syntax
CALLC c.sub.name [(argument1[,argument2]...)]
CALLC @var [(argument1[,argument2]...)]
Description
The OASYS Basic CALLC command transfers program control to an external function (c.sub.name). The second
form of the syntax calls a function whose name is stored in a OASYS Basic variable (@var). The program could
pass back return values in variables. CALLC arguments can be simple variables or complex expressions, but not
arrays.
CALLC can be used as a command or function.
For more information about this procedure, see Developing OASYS Basic Applications.
Examples
In the following example, the called subroutine draws a circle with its center at the twelfth row and twelfth column
and a radius of 3:
In the next example, the subroutine name is stored in the variable SUB.NAME, and it is called indirectly:
CALLC
81
In the next example, CALLC is used as a function, assigning the return value of the subroutine PROGRAM.
STATUS in the variable RESULT:
Related Command
OASYS Basic
CALL
57
CASE
Syntax
BEGIN CASE CASE expression1 statements1[ CASE expression2 statements2] .. .. .[ CASE 1 statements]END
CASE
Description
The OASYS Basic CASE command creates a series of branches based on conditional expressions. Case
structures must always begin with BEGIN CASE and terminate with END CASE.
The number of CASE commands within BEGIN CASE and END CASE is unlimited. The number of statements
within each CASE branch is unlimited. CASE statements can be nested.
The CASE command tests each of the expressions in sequence. If an expression evaluates as true, the system
executes the statements that follow it. When one of the CASE expressions is found to be true, the system does
not test any subsequent expressions. If none of the conditions is true, the system does not execute any
statements.
With null value handling turned on, a test of the null value returns a negative result. For an overview of how the
null value affects OASYS Basic, see Developing OASYS Basic Applications.
Parameters
The following table describes each parameter of the syntax.
Parameter
CAS E expression1
statements1
CAS E expression2
statements2
CAS E 1statements
Description
Any OASYS Basic conditional expression. If the expression is true,
execute statements1.
The OASYS Basic statements to execute if expression1 is true.
Any OASYS Basic conditional expression. If the expression is true,
execute statements2.
The OASYS Basic statements to execute if expression2 is true.
This clause always evaluates as true. By placing it at the end of the
CASE statements, you can specify a set of statements to execute if
all previous statements evaluate as false.
CASE Parameters
Examples
Note: An example of the use of CASE is included in the sample program in Appendix A - Sample Program of
Developing OASYS Basic Applications.
82
In the following example, if the variable DUE.DATE is greater than the system date, the program calls the
subroutine PRINT.OVERDUE. (Notice that both dates are in internal format.) If DUE.DATE is less than or equal
to the system date, the program prints the message Okay on the display terminal.
Tip: The multiline indented statement layout shown in these examples makes the code easier to read.
In the next example, the program segment transfers program control to either CHARGE: or CHECK: based on
the value of the variable VAL. If VAL is not 1 or 2, the program executes the statements after the CASE 1 clause.
In the following example, the statement is invalid because the evaluation expression appears on the BEGIN CASE
line:
In the next example, the statement is invalid because BEGIN CASE must appear before the first CASE statement:
Related Commands
OASYS Basic
IF/THEN/ELSE, LOOP/REPEAT
58
CAT
Syntax
expr1 CAT expr2
Synonym
:
Description
The OASYS Basic CAT arithmetic operator concatenates expr1 to expr2.
Examples
In the following example, the program segment concatenates A to B, and then prints 123456:
CAT
83
The following program segment compiles and runs only with null value handling on. The program concatenates
two strings, one ending with the null value, and another beginning with 123. This produces the string
. The called subroutine, print.setup, converts OASYS delimiters and the null value to
printable characters. (This subroutine is printed in the entry for CHANGE on page 133.)
Related Commands
OASYS Basic
CATS, SPLICE
59
CATS
Syntax
CATS(array1,array2)
Description
The OASYS Basic CATS function concatenates array1 to array2. Each element of array2 is concatenated to its
corresponding element in array1.
Example
In the following example, the program segment concatenates array A to array B and prints 300A}400B}401C}
402D}100E:
Related Commands
OASYS Basic
CAT, SPLICE
84
60
CHAIN
Syntax
CHAIN "str.expr"
Description
The OASYS Basic CHAIN command terminates the current OASYS Basic program and executes the ECL
command str.expr. CHAIN performs a function similar to the EXECUTE statement, except that control is not
returned to the original program. OASYS treats str.expr as a command you type at the ECL colon (:) prompt. If str.
exp executes a OASYS Basic program, variables could be passed through common areas, but all other variables
are reinitialized when the new program begins.
Tip: Use this command to avoid system-imposed limitations on program size by sequentially running several
smaller programs rather than one large program.
CUST.OPTIONS 6 and 40 affect the operation of the CHAIN command. For more information, see the CUST.
OPTIONS Commands Reference.
Examples
In the following example, the program terminates and OASYS executes the ECL command RUN BP FORMLET.
FORMLET is a compiled OASYS Basic program. OASYS does not return control to the original program when
FORMLET terminates.
In the next example, the current program terminates and the paragraph RUN.ACCOUNTS executes:
Related Commands
OASYS Basic
CALL, COMMON, ENTER, GOSUB
61
CHANGE
Syntax
CHANGE(string, old.substring, new.substring)
Description
The OASYS Basic CHANGE function replaces all occurrences of old.substring in string with new.substring. If
old.substring is an empty string, the system does not change string. CHANGE supports multibyte languages.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
string
CHANGE
old.substring
new.substring
85
Examples
In the following example, the program segment prints OAS Basic Release 6.1:
In the next example, the program segment prints NEW STRC = A23A24A25A26:
The following subroutine converts OASYS delimiters and the null value to printable characters. (This subroutine
compiles only with null value handling turned on.)
62
CHAR
Syntax
CHAR(expr)
Description
The OASYS Basic CHAR function changes a numeric expression to its ASCII (American Standard Code for
Information Interchange) character string equivalent. expr can be a constant, variable, numeric function, or any
combination of these. expr must evaluate to a positive number from 0 to 255 (the range of ASCII character codes).
CHAR supports multibyte languages.
Not all ASCII codes are printable. Some represent terminal controls, and others are reserved for special uses. For
more information about ASCII character codes, see Appendix A, ASCII Character Codes.
Tip: Use @variables to represent OASYS delimiters and the null value. Onsystex recommends that you not use
the OASYS Basic functions CHAR or CHARS to insert these variables because the ASCII code that represents it
varies with language group.
Examples
In the following example, the program segment assigns the ASCII string equivalent of the numeric expression
VAL to the variable VSTRING. The final numeric value of the argument is 90, so VSTRING becomes Z, the
character equivalent of 90 in ASCII code.
86
In the next example, the program statement sends the ASCII code 12 to the current print device. In ASCII, this is a
form feed.
Related Commands
OASYS Basic
ASCII, CHARS, EBCDIC, SEQ
63
CHARLEN
Syntax
CHARLEN (string)
Description
The OASYS Basic CHARLEN function returns the number of characters in a character string. A multibyte
character could require from one to four bytes to encode.
Example
The following figure illustrates a string of four multibyte characters. CHARLEN would return 4 for this string.
Related Commands
OASYS Basic
BYTELEN, DISPLAYWIDTH, ISMB, LEN, MBLEN
64
CHARS
Syntax
CHARS(array)
Description
The OASYS Basic CHARS function changes a numeric value in array to its ASCII (American Standard Code for
Information Interchange) character string equivalent. array elements can contain a constant, variable, numeric
function, or any combination of these. array elements must evaluate to a positive number 0255 (the range of
ASCII character codes). CHARS supports multibyte languages.
Not all ASCII codes are printable. Some represent terminal controls, and others are reserved for special uses. For
CHARS
87
more information about ASCII character codes, see Appendix A, ASCII Character Codes.
Tip: Use @variables to represent OASYS delimiters and the null value. Onsystex recommends that you not use
the OASYS Basic functions CHAR or CHARS to insert these variables because the ASCII code that represents it
varies with language group.
Example
In the following example, the program segment assigns the ASCII string equivalent of the elements of array VAL
to the variable VARRAY. VARRAY now contains W}X}Y}Z, the character equivalent of 87,88,89, and 90 in the
ASCII code system.
Related Commands
OASYS Basic
ASCII, CHAR, EBCDIC, SEQ
65
CHECKSUM
Syntax
CHECKSUM(str.expr)
Description
The OASYS Basic CHECKSUM function computes the positional checksum of the string str.expr you specify.
The positional checksum is the sum of the ASCII value of each character in the string, multiplied by the position
of the character in the string. For more information about ASCII characters values, see Appendix A, ASCII
Character Codes.
Tip: You can use the CHECKSUM function to check whether data was copied correctly, or whether
information processed properly, by comparing the CHECKSUM of the original data with the CHECKSUM of
the copy.
Example
In the following example, the program statement prints out 2445, the checksum of string 123456789:
66
CLEAR
Syntax
CLEAR
Description
The OASYS Basic CLEAR command sets the values of all variables stored in local memory to 0, including all
array elements. Variables assigned to named or unnamed common areas are not affected.
2012 Onsystex Corp.
88
Examples
In the following example, the program statement clears all variables not held in common if the variable
INITIALIZE is true and BASICTYPE is U. The variable INITIALIZE also set to 0 (false) if the variable is not held
in common.
In the next example, the program segment sets X, Y, and all elements in NAME, to zero in BASICTYPEs P and M:
Related Commands
OASYS Basic
COMMON, CLEARCOMMON
OASYS
DELETECOMMON For information, see the OASYS Commands Reference.
67
CLEARCOMMON
Syntax
CLEARCOMMON [/common.label/]
Synonyms
CLEAR COMMON, CLEARCOM, CLEAR COM
Description
The OASYS Basic CLEARCOMMON command sets all variables in a named common area to zero. If you do not
specify common.label, CLEARCOMMON sets all variables specified in the unnamed common area to zero.
Examples
In the following example, the program statement sets to zero all variables named in COM_1:
In the next example, the program statement sets to zero all variables held in common areas if the variable
INITIALIZE.COMMON is true:
CLEARCOMMON
89
Related Commands
OASYS Basic
CLEAR, COMMON
OASYS
DELETECOMMON, STACKCOMMON For information, see the OASYS Commands Reference.
68
CLEARDATA
Syntax
CLEARDATA
Description
The OASYS Basic CLEARDATA command clears data stored by any executed DATA statements. Subsequent
INPUT statements request data from the keyboard because the input queue is empty.
Example
In the following example, a DATA statement sets up an input queue. An INPUT statement then reads the first
item (100) into the variable VAL. Because the value of VAL is 100, a CLEARDATA statement executes and clears
the remaining list of data items. The last INPUT statement then requests information from the keyboard rather
than getting it from the input queue. If the first value had not been 100, 120 would have been assigned from the
second item in the input queue.
Related Commands
OASYS Basic
DATA, INPUT
69
CLEARFILE
Syntax
CLEARFILE [file.var] [ON ERROR statements]
Description
The OASYS Basic CLEARFILE command clears all records from a file, but does not delete the file itself. You can
clear only one file at a time with a CLEARFILE statement.
Tip: The CLEARFILE statement clears any of the files that you can open, even if they reside in a remote
account.
90
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var
ON ERROR statements
Example
In the following example, the program statement removes all records from the file PASTDUE. The dictionary of
PASTDUE remains unchanged after the execution of this statement.
Related Commands
OASYS Basic
OPEN, OPENSEQ, OSOPEN
OASYS
CLEAR.FILE For information, see the OASYS Commands Reference.
70
CLEARINPUT
Syntax
CLEARINPUT
Synonym
INPUTCLEAR
Description
The OASYS Basic CLEARINPUT command clears the terminal type-ahead buffer so the next INPUT statement
forces a response from the user.
Example
In the following example, the CLEARINPUT statement clears the terminal type-ahead buffer so the user must
respond to the prompt:
CLEARINPUT
91
Related Commands
OASYS Basic
CLEARDATA, INPUT, SYSTEM
71
CLEARSELECT
Syntax
CLEARSELECT [num.expr] [ALL]
Description
The OASYS Basic CLEARSELECT command clears active select lists. You can specify a particular ID list by
specifying num.expr as 0 through 9. ALL clears all active select lists. If you do not specify a parameter, OASYS
clears the default ID list (zero). If you specify an ID list outside the valid range, a runtime error occurs.
You generally create active lists by executing the ECL SELECT, SSELECT, or GET.LIST commands, or the OASYS
Basic SELECT or GETLIST commands. These commands report or process a specific subset of IDs within a file.
Because multiple select lists can be active at one time, the CLEARSELECT statement could clear one or all of the
currently active lists.
Examples
In the following example, the program segment clears select list 1:
In the next example, the program statement clears the default list 0:
Related Commands
OASYS Basic
SELECT, GETLIST
UniQuery
GET.LIST, SELECT, SSELECT For information, see Using UniQuery.
72
CLEARSQL
Syntax
CLEARSQL [file.name.expr]
Description
The OASYS Basic CLEARSQL command clears all active temporary tables that were created during the current
session (for example, created with the EXECUTESQL command with a corresponding TO clause). If you do not
2012 Onsystex Corp.
92
specify
file.name.expr, CLEARSQL clears all the OASYS SQL file variables created during this OASYS Basic session.
Note: When a program returns to the OASYS prompt, OASYS clears all OASYS SQL file variables regardless of
whether you execute CLEARSQL.
Related Command
OASYS Basic
EXECUTESQL
73
CLOSE
Syntax
CLOSE [file.var] [ON ERROR statements]
Description
The OASYS Basic CLOSE command closes a dictionary or data file.
Note: You can use the OPEN command to access an unlimited number of files in a single OASYS process.
However, the operating system could limit the number of files that can be opened across numerous processes
and users.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var
ON ERROR statements
Example
In the following example, the program segment opens and closes the file INVENTORY:
Related Command
OASYS Basic
OPEN
CLOSESEQ
74
93
CLOSESEQ
Syntax
CLOSESEQ seq.file.var [ON ERROR statements]
Description
The OASYS Basic CLOSESEQ command closes a sequential file that you opened with the OPENSEQ or
OSOPEN command. The CLOSESEQ command releases the exclusive file lock set by the OPENSEQ command. If
any new lines (sequential records) were added to the file, OASYS writes a new end-of-file mark after the new
lines.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
seq.file.var
ON ERROR statements
Example
In the following example, the statement closes the sequential file referred to by the file variable DATA.59:
Related Commands
OASYS Basic
CLOSE, OPENSEQ, OSCLOSE, OSOPEN
75
COL1
Syntax
COL1( )
Description
The OASYS Basic COL1 function returns the column position preceding a substring found by the FIELD
function. The COL1 function has no arguments. If you do not execute the FIELD function before executing COL1,
the function returns 0. COL1 supports multibyte languages.
The FIELD function examines a string for a particular delimiter and returns the substring marked by the specified
occurrence of that delimiter. While the FIELD function returns the substring itself, the COL1 function returns the
position preceding the substring.
2012 Onsystex Corp.
94
Example
In the following example, the FIELD function searches the string STRING for the third occurrence of the delimiter
,. FIELD retrieves the substring 10 in the variable SSTR. The COL1 function assigns column 6, the column
position of the character before 10, to the variable SPOS.
Related Commands
OASYS Basic
COL2, FIELD, INDEX
76
COL2
Syntax
COL2( )
Description
The OASYS Basic COL2 function returns the column position following a substring found by the FIELD
function. The COL2 function has no arguments. If you do not execute the FIELD before executing COL2, the
function returns a zero. COL2 supports multibyte languages.
The FIELD function examines a string for a particular delimiter and returns the substring marked by the specified
occurrence of that delimiter. While the FIELD function returns the substring itself, the COL2 function returns the
position immediately after the substring within the string sent to the FIELD function.
Example
In the following example, the FIELD function searches the string STRING for the third occurrence of the delimiter
,. FIELD assigns the substring 10 to the variable SSTR. The COL1 function assigns column 9, the column
position of the character after 10, to the variable SPOS2.
Related Commands
OASYS Basic
COL1, FIELD, INDEX
77
COMMON
Syntax
COMMON [/common.name/] var1 [,var2][ARR1]...[,]
2012 Onsystex Corp.
COMMON
95
Synonym
COM
Description
The OASYS Basic COMMON command stores variables that can be accessed from any subroutine or program.
You can declare one unnamed common area and multiple named common areas. The number of variables that a
common area can contain depends on the virtual memory of your system. For information about virtual memory,
see Administering OASYS on UNIX or Administering OASYS on Windows Platforms.
COMMON BASICTYPEs
You can pass variables using common in any BASICTYPE. Here are some notes:
With BASICTYPEs M and P, use of COMMON is more flexible because in these BASICTYPEs no zero element
is maintained in arrays. For example, two programs declare COMMON, which are described in the following
table.
First Program
Second Program
STACKCOMMON
The ECL STACKCOMMON command makes use of common areas more flexible, although it requires additional
memory. STACKCOMMON settings have the following effects:
If STACKCOMMON is off when one program executes another, the contents of unnamed common areas are
passed to the executed program and back to the executing program.
If STACKCOMMON is on when one program executes another program, the contents of unnamed common
96
areas are not passed to the program you execute. Instead, they are saved, and the called programs unnamed
common areas are initialized to 0. When control is passed back to the calling program, it is restored to its value
before the program call. Unnamed common areas are never passed to a phantom program.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
/common.name/
var1
,var2
ARR1
Examples
In the following example, the COMMON statement declares the arrays NAME and DATES, and declares the
variable DCHANGE in unnamed common:
In the next example, the program segment creates two named common areas. The second COMMON statement
continues on a second line. The comma (,) continuation character ends the continued line.
In the following example, the program segment is invalid because COMMON is not the first statement in the
called program, and because variables in COMMON cannot be reassigned new values in a called program:
The following two programs demonstrate passing a variable through common. The FIRST_PROG establishes the
common variable VAR, and then NEXT_PROG declares this variable, adds 1 to it, and prints it.
COMMON
97
Related Commands
OASYS Basic
CLEAR, CLEARCOMMON
OASYS
DELETECOMMON, STACKCOMMON For information, see the OASYS Commands Reference manual.
78
CONTINUE
Syntax
CONTINUE
Description
The OASYS Basic CONTINUE command transfers control to the next iteration of a FOR/NEXT or LOOP/REPEAT
statement.
Tip: Use CONTINUE instead of GOTO in structured programs.
Generally, the statements within a FOR/NEXT or LOOP/REPEAT structure execute one by one. If you want to
break the sequence to begin the next iteration without a CONTINUE statement, you could use the GOTO
statement.
However, this makes the code more difficult to read and maintain. By using CONTINUE, you can clearly express
the program logic without degrading program structure.
Example
In the following example, the program segment prints the value of I until I reaches eight. When I is equal to eight,
the CONTINUE statement drops out of the FOR/NEXT loop, and the next statement in the program executes.
98
Related Command
OASYS Basic
EXIT
79
CONVERT
Syntax
CONVERT expr1 TO expr2 IN var
Description
The OASYS Basic CONVERT command changes all occurrences of the substring expr1 in var to the string
expr2. OASYS Basic compares each character of the replacement string expr2 and, if necessary, replaces each
character of the target string expr1 on an individual basis. OASYS Basic does not compare and insert strings as a
whole. CONVERT supports multibyte languages.
CONVERT can delete characters from a string, but it does not insert additional characters. If the replacement
substring expr2 contains more characters than are in the substring it replaces (expr1), the extra characters are
ignored.
Parameters
The following table describes each parameter of the syntax.
Parameter
expr1
expr2
var
Description
Specifies the target string to replace with expr2.
Specifies the string with which to replace expr1.
Specifies the string to search for expr1.
CONVERT Parameters
Examples
In the following example, the program segment converts all occurrences of 1 to 3 and all occurrences of 2 to 4.
The new contents of NSTRING becomes 34,0,03,35,44.
In the next example, the program segment converts all occurrences of AC to X, which sets NSTRING equal to
XBDEFG (notice that C is deleted):
In the following example, the replacement string of F,G is longer than the string it is intended to replace, so the
extra characters, ,G, are ignored. After the conversion, NSTRING equals F,C,D,E.
Related Commands
2012 Onsystex Corp.
CONVERT
99
OASYS Basic
CONVERT function, SWAP
80
CONVERT
Syntax
CONVERT(expr1, expr2, expr3)
Description
The OASYS Basic CONVERT function changes all occurrences of the substring expr1 in expr3 to the string
expr2. The system compares each character of the replacement string expr2 and, if necessary, replaces each
character of the target string expr1 on an individual basis. OASYS Basic does not compare and insert strings as a
whole. CONVERT supports multibyte languages.
CONVERT can delete characters from a string expression, but it does not insert additional characters. If the
replacement substring expr2 contains more characters than are in the substring it replaces (expr1), the extra
characters are ignored.
Parameters
The following table describes each parameter of the syntax.
Parameter
expr1
expr2
expr3
Description
Specifies the target string to replace with expr2.
Specifies the string with which to replace expr1.
Specifies the string to search for expr1.
CONVERT Parameters
Examples
In the following example, the program segment changes OLDSTR to NEWSTR, which now contains
868,848,838,808:
In the next example, the program segment displays 1AA33BB667. Note that the fives in X are dropped because no
corresponding substitute is provided.
In the following example, Z becomes kakakakaka because the extra character t in S2 is ignored:
Related Commands
100
OASYS Basic
CONVERT command, SWAP
81
COS
Syntax
COS(expr)
Description
The OASYS Basic COS function returns the trigonometric cosine of a numeric expression.
Examples
In the following example, the program statement assigns the cosine of a 60-degree angle to the variable COSINE.
COSINE is assigned the value of 0.5.
In the next example, the program statement prints the cosine of the variable VAL plus 10:
Related Commands
ACOS, ASIN, ATAN, COS, SIN, TAN
82
COUNT
Syntax
COUNT(str.expr1, str.expr2)
Description
The OASYS Basic COUNT function returns the number of times a substring appears within a string. The string
you want to search, str.expr1, must be longer than the substring str.expr2. After str.expr2 is found, the system
searches the string again with the new starting point after the entire first occurrence of str.expr2. If str.expr2 is
not found, the COUNT function returns 0. COUNT supports multibyte languages.
Note: In BASICTYPEs P and M, after OASYS finds str.expr2, it searches the string again with the new starting
point after the first character of the first occurrence of str.expr2. OASYS can find overlapping character strings.
Parameters
The following table describes each parameter of the syntax.
Parameter
str.expr1
str.expr2
Description
Specifies the string to search. This string must be longer than str.expr2.
Specifies the target string to search for and count occurrences of in str.expr1.
COUNT Parameters
COUNT
101
Examples
In the following example, the program segment searches the string STRING for the number of occurrences of the
substring II. It returns this number, 2, in the variable IC.
In the next example, the same program segment compiled under BASICTYPE P or M searches the string STRING
for the number of occurrences of the substring II and assigns that number, 3, to the variable IC. It counts two
occurrences of the substring II in ROCKYIII.
83
COUNTS
Syntax
COUNTS(expr,str.expr)
Description
The OASYS Basic COUNTS function returns the number of times a substring appears within each element of an
array. The elements in the array you want to search, expr, must be longer than the substring str.expr. After str.
expr is found, the system searches the array again with the new starting point after the entire first occurrence of
str.expr. If str.expr is not found, COUNTS returns 0. COUNTS supports multibyte languages.
Note: In BASICTYPEs P and M, after OASYS finds str.expr, it searches the string again with the new starting
point after the first character of the first occurrence of str.expr. OASYS can find overlapping character strings.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
expr
Specifies the array to search. The elements of this array must be longer than str.expr.
str.expr
Specifies the target string to search for and count occurrences of in elements of expr.
COUNTS Parameters
Examples
In the following example, the program segment searches the string STR for the number of occurrences of
substring I, and returns the answer in the variable IC. After execution, IC contains 2}3}1.
In the next example, the same program segment compiled under BASICTYPE P or M searches the string STR for
the number of occurrences of the substring II and assigns the values to the variable IC. After execution, IC
contains 1}2}0.
102
If the preceding code is compiled in BASICTYPE U or R, COUNTS returns 1}1}0 in the variable IC.
84
CRT
Syntax
CRT [print.expr]
Synonym
DISPLAY
Description
The OASYS Basic CRT command sends output to the display terminal regardless of the use of the PRINTER ON/
OFF command. print.expr can consist of any of the following:
String data.
Any number of strings or numeric variables.
OASYS Basic functions.
Tip: Use the OASYS Basic @ function before the CRT command to position the cursor on the screen or execute
other terminal functions before printing to the terminal.
Set CUST.OPTIONS 5 on if you want the display to pause at the end of each page. For information about
CUST.OPTIONS, see the CUST.OPTIONS Commands Reference.
To suppress the line feed at the end of displayed text, end the CRT or DISPLAY statement with a colon.
85
DATA
Syntax
DATA expr1 [,expr2]...
Description
The OASYS Basic DATA command places data in an input queue stored in @DATA. ASCII character 013 (CR)
delimits elements in the queue. Each subsequent INPUT statement reads one element. @DATA is read-only. For
more information about @ variables, see Appendix B, OAS Basic@variables.
The expressions (expr1 and expr2) can be literal strings or variables. You can continue DATA statements over
several lines by placing a comma at the end of each line to be continued.
OASYS places data in the queue in order of execution of DATA commands. The queue processes on a first-in,
first-out basis. When the input queue is empty, OASYS requests input from the terminal. The input queue
remains available through program CHAIN and EXECUTE operations, but is cleared when control returns to the
OASYS ECL prompt (:).
Tip: You can load inline prompts in paragraphs with the DATA command. For instructions, see the OASYS
Commands Reference.
Example
2012 Onsystex Corp.
DATA
103
In the following example, the program segment executes a DATA statement containing variables and constants
of both string and numeric types. The first value, 10, is read by a subsequent input statement and assigns the
value to the variable COUNT.
86
DATE
Syntax
DATE( )
Description
The OASYS Basic DATE function returns the current system date in internal format. Internal format is the number
of days after December 31, 1967.
Example
The following statement prints the current system date in external format:
Related Commands
OASYS Basic
ICONV Date (D), OCONV Date (D), TIMEDATE
87
DBTOXML
Syntax
DBTOXML(xml_document, doc_location, u2xmap_file, u2xmap_location, condition, status)
Description
Creates an XML document from the OASYS database.
Parameters
The following table describes each parameter of the syntax.T
Parameter
Description
xml_document
doc_flag
u2xmap_file
104
u2xmap_location
condition
Status
XM L.SUCCESS or XM L.FAILURE.
DBTOXML Parameters
88
DCOUNT
Syntax
DCOUNT(str,delim)
Description
The OASYS Basic DCOUNT function returns the number of substrings delimited by delim in a string. If str is an
empty string, OASYS returns 0. If str contains data but no delimiter, OASYS returns 1. DCOUNT supports
multibyte languages.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
str
Specifies the string to search for occurrences of substrings delimited by delim.
delim
Specifies the delimiter to use in searching str.
DCOUNT Parameters
Examples
In the following example, the program segment finds three occurrences of the value mark and prints 3:
In the next example, the program segment prints 1 because no delimiter is found in the string:
Related Commands
OASYS Basic
COUNT, COUNTS
DEBUG
89
105
DEBUG
Syntax
DEBUG
Description
The OASYS Basic DEBUG command stops program execution, turns control over to the interactive OASYS Basic
debugger, and then displays the debugger prompt (!). Pressing the interrupt key also gives control to the
debugger. For information about the OASYS Basic debugger, see Using the OASYS Basic Debugger.
To use the DEBUG command to display the contents of variables, you must compile the program with the D
option.
Note: The setting of CUST.OPTIONS 14 determines where to return control after exiting a OASYS Basic
program when you are using the OASYS Basic debugger and enter ABORT or END. For information about
CUST.OPTIONS, see the CUST.OPTIONS Commands Reference.
When you enter the debugger, a message similar to the following displays, and the cursor is placed at the
debugger prompt:
Related Commands
OASYS Basic
ABORT
OASYS
BASIC, DEBUG.FLAG, DEBUGLINE.ATT, DEBUGLINE.DET, ON.ABORT, RUN, SETDEBUGLINE,
UNSETDEBUGLINE For information, see the OASYS Commands Reference.
90
DEFFUN
Syntax
DEFFUN function.name [([MAT] arg.1[,[MAT]arg.2]...)] [CALLING catalog.name]
Description
The OASYS Basic DEFFUN command declares a user-written function, making the function available in a OASYS
Basic program. You must declare the function before you can use it in a program.
Note: You also must define the function with the OASYS Basic FUNCTION command in a separately cataloged
file before you can call it.
Function Naming
The function name used in the DEFFUN statement must be the same as the name of the cataloged file that
contains the FUNCTION statement. Either of the following statements declares the function cataloged under the
name func.name:
2012 Onsystex Corp.
106
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
function.name
Specifies the function name that the calling statement uses in this
program.
(M AT arg.1 ,M AT arg.2 Specifies the arguments to be passed to the function. You must
...)
enclose arguments in parentheses and separate them with
commas. Precede an argument with M AT to indicate that the
argument is an array.
CALLING file.name
Specifies the functions cataloged file name. Include this
statement if the cataloged program name differs from function.
name. Can be a literal or variable.
DEFFUN Parameters
Examples
The DEFFUN statement in the following example declares myfunc. The CALLING clause indicates that the name
of the cataloged file that contains the FUNCTION statement is called yourfunc. In the first print statement, the
function is called and the return value is printed.
The preceding program calls the following function. The name of this cataloged file is yourfunc. This is the name
that must match the DEFFUN statement in the program above. Notice that the function definition uses yet
another name for the function (anotherfunc).
The following screen example shows the command that runs the program and the output from the program:
DEFFUN
Related Command
OASYS Basic
FUNCTION
91
DEL
Syntax
DEL dyn.array.var <attrib.expr[,val.expr [,subval.expr]]>
Description
The OASYS Basic DEL command deletes an attribute, value, or subvalue from a dynamic array. The
corresponding delimiter is also removed.
The DELETE function and the DEL command perform the same action.
Warning: DEL destroys the data and the corresponding delimiters. Use the DEL command with caution.
Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
attrib.expr
,val.expr
,subval.expr
Description
Specifies the dynamic array on which to perform the delete operation.
Specifies which attribute of the dynamic array to delete. If val.expr is
omitted, DEL deletes the entire attribute, including all values and
subvalues.
Specifies which value of the dynamic array attribute to delete. If subval.
expr is omitted, DEL deletes the entire value, including the subvalues.
Specifies which subvalue of the dynamic array attribute value to delete.
DEL Parameters
Examples
The following program segment is taken from Appendix A, Sample Program of Developing OASYS Basic
107
108
Applications. It deletes the attribute in the variable POSITION. This removes one order for a particular client from
the CLIENTS file in the demo database.
In the following example, the program segment deletes the third attribute of the dynamic array ARRAY1. The
attribute removed is Anne.
In the following example, the statement is invalid. The DEL statement has too many parameters:
Related Commands
OASYS Basic
DELETE, EXTRACT, INSERT, REMOVE, REPLACE, SUBSTRINGS
92
DELETE
Syntax
DELETE [file.var,] record.ID.expr [ON ERROR statements]
Description
The OASYS Basic DELETE command deletes a record from a OASYS file. In addition, the DELETE command
releases any locks on the record that have been set by previous commands.
Note: The DELETEU command also deletes a record, but it does not release locks. This is the only difference
between DELETE and DELETEU statements.
OASYS Basic locks are advisory only. For more information,see Developing OASYS Basic Applications.
Parameters
The following table describes each parameter of the syntax.
Parameter
file.var
record.ID.expr
ON ERROR statements
Description
Specifies the file from which to delete the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal DELETE error occurs.
A default file is one for which no file variable is assigned in the
OPEN statement.
Specifies the record to delete.
Specifies OASYS Basic statements to execute if the DELETE
statement fails because OASYS cannot find the file, or a default
file is not open. If you do not specify the ON ERROR clause,
2012 Onsystex Corp.
DELETE
109
Examples
The following program statement eliminates the record with the ID of PEANUT from the default file:
The following program segment deletes the record whose ID is specified by the variable DEL_ID from the file
previously opened to the PARTS variable:
The following statement is invalid because the file variable is specified incorrectly in the DELETE statement:
The following program segment is taken from Appendix A, Sample Program of Developing OASYS Basic
Applications. The DELETE command deletes the record in the ORDERS file after the corresponding attribute is
deleted from the CLIENTS file. Both steps are necessary to remove the order record itself, and to remove the
reference to the order in the client record (the attribute in the CLIENTS file).
Related Commands
OASYS Basic
DEL, DELETE, DELETEU
93
DELETE
Syntax
DELETE(dyn.array, attrib.expr[,val.expr [,subval.expr]])
Description
The OASYS Basic DELETE function deletes an attribute, value, or subvalue from a dynamic array. The
corresponding delimiter is also removed.
110
The DELETE function and the DEL command perform the same action.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.var
attrib.expr
,val.expr
,subval.expr
DELETE Parameters
Examples
In this first example, the program segment deletes the first attribute (125) and the attribute mark from the dynamic
array ARRAY:
In the next example, the program statement removes the first subvalue of the first value of the second attribute in
ARRAY. The modified array is assigned to ARRAY2.
In the next example, the program segment deletes the third attribute, including A, B, and C:
Related Commands
OASYS Basic
DEL, DELETE, DELETEU
94
DELETELIST
Syntax
DELETELIST list.name.expr
Description
The OASYS Basic DELETELIST command deletes a saved select list.
Select lists are saved by the UniQuery SAVE.LIST command and the OASYS Basic WRITELIST command.
list.name.expr is the name of the saved list to be deleted. If the list you specify cannot be found, OASYS
displays an error message and takes no action.
DELETELIST
111
Example
The following statement deletes the saved list CUST in the current account:
Related Commands
OASYS Basic
FORMLIST, READLIST, SELECT, SELECTINDEX, SELECTINFO, WRITELIST
UniQuery
DELETE.LIST, GET.LIST, SAVE.LIST, SELECT, SSELECT For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
95
DELETEU
Syntax
DELETEU [file.var,] record.ID.expr [ON ERROR statements]
Description
The OASYS Basic DELETEU command deletes the specified record from a OASYS file.
The DELETEU command retains record locks that were set by the same user process. This allows OASYS to
delete a record and re-create it while retaining a lock on it.
Note: The DELETE command also deletes a record, but it releases locks. This is the only difference between
DELETE and DELETEU statements.
OASYS Basic locks are advisory only. For information about OASYS file and record locks, see Developing
OASYS Basic Applications.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var,
record.ID.expr
ON ERROR statements
112
Examples
In the following example, the statement eliminates the record with the record ID of JONES from the most recently
opened default file:
The following segment deletes the record. The record ID is stored in the variable DEL_ID. The file was opened to
the variable DISCOUNT.
Related Commands
OASYS Basic
DEL, DELETE, DELETE function, RELEASE
96
DIM
Syntax
DIM name1(rows[,cols]) [,name2(rows[,cols])]...
Synonym
DIMENSION
Description
The OASYS Basic DIM command creates and determines the dimensions of a dimensioned array. You can specify
arrays with one dimension (rows) or two dimensions (rows or rows, cols). In addition, the following limitations
apply:
You must dimension any array before you use it within a program.
Zero elements other than 0,0 (such as 0,5 or 1,0) are invalid.
The maximum number of elements you can specify is based on the total amount of virtual memory available on
your system.
Arrays passed to a subroutine cannot be redimensioned within the subroutine.
For information about system configurations, see Administering OASYS on UNIX or Administering OASYS on
Windows Platforms.
MATREAD, MATWRITE, and MATPARSE load and empty an array from left to right and from top to bottom
beginning with element 1,1 and ending by placing excess data in element 0,0.
Note: BASICTYPEs M and P do not support position 0,0 in arrays. You could lose data if an array is too small
for the amount of data you are attempting to load into it with MATPARSE.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
name1
DIM
rows
,cols
113
Description
The dimensioned array was not created. OASYS returns an error message, but
program execution continues.
M emory was insufficient to create the dimensioned array. OASYS returns an error
message, but program execution continues.
The dimensioned array was created. n is the number of elements in the array.
1
n
Resizing Arrays
You can use the DIM statement to dynamically redimension an array without losing any data if the size of the
redimensioned array is large enough to contain all data in the original array. When you redimension, OASYS
Basic places the old data elements into the new array from left to right and from top to bottom. All leftover data is
placed in the 0,0 element.
Although you can change the size of an array during program execution, its configuration cannot change. For
example, a two-dimensional array cannot be changed to one-dimensional and vice versa.
Examples
In the following example, the program statement creates three arrays: one-dimensional NAME, one-dimensional
TITLES, and two-dimensional DATES.
In the next example, two DIMENSION statements are included in the same program, although because the new
array is smaller than the original, all excess data is placed in element 0,0. After the execution of the second
DIMENSION statement, the array has the dimension of 100 by 10.
The following program segment creates the array TEST by setting variable A to 30, and then declaring TEST as a
one-dimensional array of 30 elements:
The following sample code is invalid because array size is declared with nonnumeric variables ( and ) and
because you cannot use a variable in a dimension statement:
114
Related Commands
OASYS Basic
INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATREADU, MATWRITE,
MATWRITEU
97
DIGEST
Syntax
DIGEST(algorithm, data, dataLoc, result)
Description
The DIGEST function generates a message digest of supplied data. A message digest is the result of a one-way
hash function (digest algorithm) performed on the message. Message digest has the unique properties that alight
change in the input results in a significant difference in the resulting digest. Therefore, the probability of two
different messages resulting in the same digest (collision) is very unlikely. It is also virtually impossible to reverse
to the original message from a digest. Message digest is widely used for digital signatures and other purposes.
The desired digest algorithm is specified in algorithm. OASYS supports the MD5 (Message Digest 5, 128-bit)
and SHA1 (Secure Hash Algorithm 1, 160-bit) algorithms. You specify data and its location are with data and
dataLoc, respectively. OASYS puts the arrived digest into a dynamic array in result. Since digest is short and has
a fixed length, it is always put into a string, and no file option is provided. The result can be in either binary or hex
format.
Parameters
The following table describes each parameter of the syntax
Parameter
Description
algorithm
Parameter
Description
data
dataLoc
result
Return Code
Status
0
1
2
3
4
Success
Unsupported digest algorithm
The data file cannot be read
M essage digest cannot be obtained
Invalid parameters
Return Code Status
DIR
98
115
DIR
Syntax
DIR(file.expr)
Description
The OASYS Basic DIR function returns the file size (in bytes), the last date and time the file was modified (in
internal format), and the privileges for the file. OASYS stores these values in the first four attributes of the return
value. file.expr must evaluate to a file name at the operating system level. If you do not specify a path, OASYS
searches the current directory.
Example
The following UNIX program segment retrieves the file statistics on the OASYS file stored in the subdirectory /
usr/accounting/gl. The first attribute contains the file size in bytes, the second attribute contains the date the file
was last updated, and the third attribute contains the time the file was last updated. OASYS stores the second
and third attributes in internal format, and the example converts them to the external format.
99
DISPLAY
DISPLAY is a synonym for the CRT command. For further information, see CRT.
Synonym
CRT
100 DISPLAYWIDTH
Syntax
DISPLAYWIDTH (string)
Description
The OASYS Basic DISPLAYWIDTH function returns the number of bytes needed to display a string expression.
For instance, the display width of English characters is one. In languages that use multibyte characters, the
display width of a character can be 1, 2, 3, or 4 bytes, depending on the language and the character.
Example
The following illustration shows a string that indicates below each character the number of bytes required to
display that character. The string contains eight bytes. Therefore, DISPLAYWIDTH would return 8 for this
string.
116
Related Commands
OASYS Basic
BYTELEN, CHARLEN, ISMB, LEN, MBLEN
101 DOWNCASE
Syntax
DOWNCASE(str.expr)
Description
The OASYS Basic DOWNCASE function converts all characters in a string (str.expr) to lowercase. Special
characters, including the null value, are not converted by this function. DOWNCASE does not convert multibyte
characters.
Example
In the following example, the program segment converts the contents of the variable USTRING to lowercase
letters:
Related Commands
OASYS Basic
ICONV Masked Character (MC), OCONV Masked Character (MC), UPCASE
102 DQUOTE
DQUOTE is a synonym for the QUOTE function. For more information, see QUOTE.
Synonym
QUOTE
103 DROUND
Syntax
DROUND(val.expr [,precision.expr])
2012 Onsystex Corp.
DROUND
117
Description
The OASYS Basic DROUND function performs double-precision rounding on a value. Double-precision
rounding uses two words to store a number, accommodating a larger number than in single-precision rounding,
which stores each number in a single word.
Note: DROUND affects the internal representation of the numeric value. It performs the rounding without
conversion to and from string variables. This increases the speed of calculation.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
val.expr
,precision.expr
Example
In the following example, the DROUND statement results in 18.84955596. The equation is resolved, and then the
result is rounded to eight decimal places.
Related Commands
OASYS Basic
PRECISION
OASYS
FLOAT.PRECISION For information, see the OASYS Commands Reference.
104 EBCDIC
Syntax
EBCDIC(expr)
Description
The OASYS Basic EBCDIC (Extended Binary Coded Decimal Information Code) function converts the ASCII
(American Standard Code for Information Interchange) data in expr to its corresponding EBCDIC values.
Note: BASICTYPE U, the standard application, converts data to EBCDIC format before the data is written to
tape.
Example
In the following example, the program statement first prints a message, and then prints the EBCDIC equivalent of
the ASCII variable VAL:
118
Related Commands
OASYS Basic
ASCII, CHAR, CHARS, SEQ
105 ECHO
Syntax
ECHO [ON | OFF | expr]
Description
The OASYS Basic ECHO command controls whether characters display on the terminal screen as you type them
on the keyboard.
Tip: Use ECHO for security purposes when the entry of an ID or password should not display on the terminal
screen.
Parameters
The following table describes each parameter of the syntax.
Parameter
ON
OFF
expr
Description
Enables the display of characters as you type them on the keyboard.
Disables the display of characters as you type them on the keyboard.
When expr is 0, ECHO is set to OFF. When expr is not 0, ECHO is set to
ON. expr must be numeric.
ECHO Parameters
Example
The following program segment enables echoing because A+B is not 0:
106 ENCODE
Syntax
ENCODE(algorithm, action, data, dataLoc, result, resultLoc)
Description
The ENCODE() function performs data encoding on input data. Currently, OASYS supports only Base64
encoding. Base 64 encoding is designed to represent arbitrary sequences of octets that do not need to be
humanly readable. A 65-character subset of US-ASCII is used, enabling 6-bits to be represented per printable
character. The subset has the important property that it is represented identically in all versions of ISO646,
ENCODE
119
including US-ASCII, and all characters in the subset are also represented identically in all versions of EBCDIC.
The encoding process represents 24-bit groups of input bits as output strings of 4 encoded characters. The
encoded output stream must be represented in lines of no more than 76 characters each. All line breaks must be
ignored by the decoding process. All other characters not found in the 65-character subset should trigger a
warning by the decoding process.
The function can perform either encoding or decoding, as specified by action. The data can either be in the
dynamic array, data, or in a file whose name is specified in data, determined by dataLoc.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
algorithm
action
data
Data or the name of the file containing the data to be encoded or decoded.
ENCODE Parameters
Parameter
Description
dataLoc
result
Encoded or decoded data or the name of the file storing the processed
data.
1 - Result in a string2 - Result in a file.
resultLoc
Status
0
1
2
Success.
Unsupported algorithm.
Invalid parameters (invalid data or result location
type, and so forth).
The data cannot be read.
The data cannot be encoded or decoded.
3
4
107 ENCRYPT
Syntax
ENCRYPT(algorithm, action, data, dataLoc,key, keyLoc, keyAction, salt, IV, result, resultLoc)
Description
The ENCRYPT() function performs symmetric encryption operations. You can call various block and stream
symmetric ciphers through this function. The supported ciphers are listed in OASYS Basic Extensions.
You specify ciphers by algorithm, and they are not case sensitive. You can specify Base64 encoding and
decoding with the action parameter. If you specify encoding, the encrypted data is Base64 encoded before being
entered into result. If you specify decoding, the data is Base64 decoded before being encrypted. Specify the data
2012 Onsystex Corp.
120
and its location using data and dataLoc, respectively. You can explicitly specify Key, read it from a file, or,
alternatively, derived it on the fly by specifying keyAction, in which case the key string is used as a pass phrase
to derive the actual key. The encrypted or decrypted data is put into the dynamic array result, or a file, as
specified by resultLoc.
Salt is used to provide more security against certain kinds of cryptanalysis attacks, such as dictionary attacks. If
you specify an empty salt, OASYS uses an internally generated salt in deriving the key. OASYS ignores Salt
when action is set to decrypt. OASYS uses IV (Initialization Vector) to provide additional security to some block
ciphers. It does not need to be secret but should be fresh, meaning different for each encrypted data. If you
supply an existing key, IV is generally needed. However, if the encryption key is to be derived from a pass
phrase, IV can be generated automatically. Both salt and IV must be provided in hexadecimal format.
Parameters
he following table describes each parameter of the syntax.
Parameter
Description
algorithm
action
data
dataLoc
key
keyLoc
keyAction
Salt
IV
result
resultLoc
Success.
Invalid cipher.
Invalid parameters (location/action value is
out of range, etc.).
ENCRYPT Return Codes
Return Code
3
4
5
6
Status
Status
END
121
108 END
Syntax
END
Description
The OASYS Basic END command declares the end of a program or a block of statements.
OASYS Basic does not require you to use END at the end of a program.
Example
In the following example, the END in bold type declares the end of the program segment. (The first END ELSE
ends the THEN clause in the IF/THEN/ELSE statement.)
109 ENTER
Syntax
ENTER filename
ENTER @variable
Description
The OASYS Basic ENTER command passes control to the program you specify. It terminates the program that is
passing control and executes the cataloged program. The ENTER command allows variables to pass through
common areas, but all other variables are reinitialized when the new program begins.
Note: This command does not return control to the original program by default. For structured programming,
use GOSUB and RETURN. This makes the program easier to read and maintain.
The ENTER command processes faster than the CHAIN command.
Examples
In the following example, the program statement transfers control to cataloged program CHECK_1:
In the next example, the program segment transfers control to cataloged program CHECK_2:
122
Related Commands
OASYS Basic
CALL, CHAIN, COMMON, GOSUB
110 EQ
Syntax
variable = expr
expr1 EQ expr2
Synonym
=
Description
The OASYS Basic EQ operator serves as an assignment operator and a relational operator. As an assignment
operator, it assigns expr to variable. As a relational operator, it tests whether expression expr1 is equal to expr2.
expr1 and expr2 can be any valid OASYS Basic expressions, variables, strings, or literals.
Relational operators make the comparisons that direct program flow in conditional statements like the following:
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
variable
expr
Examples
In the following example, the program statement assigns the value of 60 to the variable PAGELENGTH:
In the next example, the EQ relational operator is used in a conditional test. The program segment tests whether A
equals B. In this case, the message NOT EQUAL prints.
EQ
123
Related Command
OASYS Basic
EQS
111 EQS
Syntax
EQS(array1,array2)
Description
The OASYS Basic EQS function compares each value in array1 to its corresponding value in array2. OASYS
returns an array with 1 in each position where values are equal, and 0 in each position for values that are not
equal.
Example
In the following example, the program segment compares ARRAY1 to ARRAY 2 and returns ARRAY3. After
EQS, ARRAY3 contains 1}1}1}0}0.
112 EQU
Syntax
EQU constant1 TO value1 [[,constant2 TO value2]...]
EQU constant1 {LITERALLY | LIT} string2 [[,constant2 {LITERALLY | LIT} string2]...]
Synonym
EQUATE
Description
The OASYS Basic EQU command replaces a constant with an array, function, number, string, or variable name
when the program is compiled.
The only difference between the statements using TO and those using LITERALLY is the use of quotation
marks. In the TO form, you cannot enclose literals in quotation marks. In the LITERALLY form, you must enclose
literals in quotation marks.
124
After the execution of an EQUATE statement, you can use the constant symbols and variables interchangeably
at all levels of the program.
EQUATE variables are available from within the OASYS Basic debugger.
The variable literal string limit is 2,048 characters. EQUATE has the same limit.
Tip: EQUATE enables you to use longer, more meaningful names as you write code. These names are replaced
with the actual value when the program is compiled. EQUATE also lets you equate a control character to a
meaningful name. OASYS does not use memory for a constant symbol because the replacement takes place
during compilation.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
constant
Specifies the constant to be replaced with value when the program is compiled.
value
string
Specifies the value to replace constant with when the program is compiled.
Specifies a literal string, in quotes, to replace constant with when the program
is compiled.
EQ Parameters
Examples
In the following example, all occurrences of the constant SB are replaced with the value CHAR(8) (clear screen)
during program compilation:
In the next example, OASYS replaces every occurrence of the constant TITLE with the string ALGONQUIN:
In the next example, OASYS replaces every occurrence of the constant TRUE with the value 1, and every
occurrence of the constant FALSE with the value 0:
In the next example, OASYS replaces every occurrence of the constant FULLNAME with the expression in the
EQUATE statement. The program segment prints Mary Jones.
After the program is compiled, the print statement looks like this:
EQU
125
The following example shows the same program segment using the TO form of the statement syntax. In this case,
the quotation marks around
are removed.
113 EREPLACE
Syntax
EREPLACE(expression, substring, replacement [,occurrence [,begin] ] )
Description
The EREPLACE function replaces substring in expression with another substring. If you do not specify
occurrence, each occurrence of substring is replaced.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expression
substring
replacement
occurrence
begin
If expression evaluates to the null value, null is returned. If substring, replacement, occurrence, or begin
evaluates to the null value, the EREPLACE function fails and the program terminates with a run-time error
message.
Note: The EREPLACE function behaves like the CHANGE function except when substring evaluates to an
empty string.
114 EXECUTE
Syntax
EXECUTE "str.expr" [[ASYNC | SYNC] ON connection [ON ERROR statements]] [PASSLIST list.num.expr]
[RTNLIST list.num.expr] [CAPTURING dyn.array.var] [RETURNING dyn.array.var] [PASSCOM]
Synonym
PERFORM
126
Description
The OASYS Basic EXECUTE command executes an ECL or OASYS SQL command from within a OASYS Basic
program.
You can execute multiple commands with a single EXECUTE statement by separating each command by attribute
marks. When the EXECUTE statement executes, OASYS separates each command and executes them in order.
Note: The settings of CUST.OPTIONS affect the way ECL commands execute. For information about these
options, see the CUST.OPTIONS Commands Reference. For information about CUST.OPTIONS that could
affect that command, see the appropriate ECL command in the OASYS Commands Reference.
Reminder: When you compile EXECUTE and PERFORM in BASICTYPE P, a different parser is used. The P-type
parser scans a file of commands that are defined in the Spectrum-SMA standards or in the McDonnell Douglas
REALITY operating system. If the command is found in this file, it is parsed using the P-type parser. If the
command is not found in the REALITY file, it is parsed as if the program had been compiled with BASICTYPE U.
Because all REALITY commands are uppercase, using lowercase commands will always result in the use of the
standard OASYS parser.
If you want to execute a standard OASYS, UniQuery, or ECL command from within a program compiled with
BASICTYPE P, use the OASYS Basic command OASEXECUTE.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
Parameter
Description
EXECUTE
RTNLIST int.expr
PASSLIST int.expr
PASSCOM
127
Reminder: The error message numbers you capture with RETURNING will vary, depending upon which version
of OASYS you are running.
Examples
In the following example, the program statement performs the command in cmd3 and sends output to a dynamic
array cpt_var:
In the next example, the program segment executes a variable containing a OASYS command:
In the next example, the EXECUTE statement creates a record ID list using the SELECT statement. The select list
is then used to read records from the file.
128
In the next example, the program segment executes a paragraph from within a OASYS Basic program using the
EXECUTE statement:
Related Commands
OASYS Basic
COMMON, EXECUTESQL, MDPERFORM, PCPERFORM, OASEXECUTE
OASYS
STACKCOMMON For more information, see the OASYS Commands Reference.
115 EXECUTESQL
Syntax
EXECUTESQL str.expr [ASYNC | SYNC] [ON connection [ON ERROR statements]]
Description
The OASYS Basic EXECUTESQL command executes a OASYS SQL statement within a OASYS Basic program.
If the OASYS SQL statement includes a SELECT statement with the intent to process internal program items, the
SELECT statement must contain a TO clause with a resulting file name. Otherwise, OASYS displays the result of
the statement. If you select only the @ID attribute, OASYS stores the @IDs in a select list. If the OASYS SQL
statement includes a TO clause, the data is stored in the output file and is then available to the OASYS Basic
program via the READNEXTTUPLE statement.
Note: After you execute a SELECT statement and complete processing of the selected records, you must execute
the CLEARSQL command to clear the select list and make all records in the file available for further
processing.
Parameters
2012 Onsystex Corp.
EXECUTESQL
129
Description
str.expr
Parameter
Description
ASYNC | SYNC
Examples
In the following example, the program segment executes a OASYS SQL command:
The following output displays on the terminal screen when you execute the preceding program:
In the next example, the program segment executes the same OASYS SQL command with a TO clause that stores
the OASYS SQL output in a file that you can access using the READNEXTTUPLE statement. (This program uses
the CLIENTS file in the demo database.)
130
In the next example, the OASYS SQL statement selects an @ID only. OASYS uses a select list instead of storing
the output. In this case, the OASYS SQL command does not require a TO clause, and the OASYS Basic
READNEXT statement processes the IDs selected.
Related Commands
OASYS Basic
EXECUTE, READNEXT, READNEXTTUPLE
OASYS SQL
For more information about OASYS SQL commands, see the OASYS SQL Commands Reference.
EXIT
131
116 EXIT
Syntax
EXIT
Description
The OASYS Basic EXIT command terminates a FOR/NEXT or LOOP/REPEAT structure and transfers control to
the following statement. As with the CONTINUE statement, EXIT forms well structured programs.
Tip: Use EXIT in structured programs instead of GOTO. This makes the code easier to read and maintain.
Example
In the following example, the program segment exits the FOR/NEXT loop when I is greater than 8:
Related Commands
OASYS Basic
CONTINUE, FOR/NEXT, LOOP/REPEAT
117 EXP
Syntax
EXP(expr)
Description
The OASYS Basic EXP function raises e to the power of expr. e is approximately 2.71828. expr must be numeric.
The function ex is its own derivative. If y = ex, then x is the natural logarithm of y.
If exp is too large or too small, a warning message is printed and 0 is returned. If exp is an empty string, the empty
string is returned.
Example
In the following example, the program statement raises e to the power of 2, and assigns this value, 7.3891, to the
variable ETOX:
Related Command
OASYS Basic
LN
132
118 EXTRACT
Syntax
EXTRACT(dyn.array.expr, attrib.expr,[val.expr [,subval.expr]])
dyn.array.expr <attrib.expr,[val.expr [,subval.expr]]>
Description
The OASYS Basic EXTRACT function retrieves data from an attribute, value, or subvalue in a dynamic array.
The dynamic array itself remains unchanged. You can use either of the preceding syntax forms.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.expr
attrib.expr
val.expr
subval.expr
Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. The variable ENTRY is used to extract the user-requested values from
the ORDERS record.
In the following example, the program segment assigns the string Joan to the variable MID. Joan is the second
attribute in the dynamic array ARR. The value and subvalue expressions are 0, resulting in the extraction of an
attribute.
In the next example, the program segment assigns the string Dagny, the second value of the third attribute, to the
variable MID:
EXTRACT
133
Related Commands
OASYS Basic
DEL, INSERT, REMOVE, REPLACE, SUBSTRINGS
119 FIELD
Syntax
FIELD(string.expr,delim.expr,field.expr [,rep.expr])
Description
The OASYS Basic FIELD function treats a string as an array, with fields delimited by any specified ASCII
character (for example, spaces, commas, or periods), and returns a substring or group of substrings. FIELD
supports multibyte languages.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
string.expr
delim.expr
field.expr
,rep.expr
Examples
In the following example, the program segment assigns the third value (Guy) in the array ARR to the array
NARRAY:
In the next example, the program segment assigns the two fields following the third occurrence of the delimiter ,
in the variable ARR to NARRAY. OASYS stores the value 5,8 in NARRAY.
In the next example, the program segment assigns the second group of characters in a string delimited by spaces
in the variable NAME to LNAME. OASYS stores the value Smith in LNAME.
Related Commands
134
OASYS Basic
COL1, COL2, INDEX
120 FIELDSTORE
Syntax
FIELDSTORE(str.expr,delimiter,b.pos,option,new.expr)
Description
The OASYS Basic FIELDSTORE function inserts an expression and an appropriate delimiter into a string.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
delimiter
b.pos
option
new.expr
Options
The value of option determines the operation to be executed. The following table describes these options and
their results.
Value
If option > 0
If option = 0
If option < 0
Description
OASYS replaces the number of substrings specified in option.
OASYS inserts new.expr at the position indicated by b.pos.
OASYS deletes the number of substrings specified in option, and inserts
new.expr at the location indicated by b.pos.
FIELDSTORE Options
Examples
In the following example, the program segment inserts AR in the string ASTATES. After execution, ASTATES
contains the string AL:AK:AR:AZ.
The following program segment compiles and runs only when null value handling is on. The program segment
inserts AR, and then inserts the null value into ASTATES. It calls the externally cataloged subroutine PRINT.
SETUP to convert the null value to a printing character, and then prints the converted ASTATES. (PRINT.SETUP
is shown under CHANGE.)
2012 Onsystex Corp.
FIELDSTORE
135
In the next example, the program segment specifies that processing begins at the fifth value (ugly), that this value
is deleted (the -1 option), and that the new.expr (orange,black) is to be inserted in the same position. After
processing, COLORS contains the string yellow,blue,red,green,orange, black,white.
Related Commands
OASYS Basic
INS, INSERT
121 FILEINFO
Syntax
FILEINFO(file.var, code)
Description
The FILEINFO function returns information about the configuration of a file.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
file.var
Specifies the file to be analyzed.
file.var is the file variable previously used in an OPEN or OPENSEQ
statement.
code
Specifies the type of information to return.
FILEINFO Parameters
FILEINFO Codes
code indicates the information requested. The following table describes the codes and the return values of the
function.
136
Code
Return Value
ALL
2
3
M odulo of file
ALL
HASHED
DYNAM IC
DIRECTORY
SEQUENTIAL
NFA
OS
EDA
HASH & DYN
(KEYONLY)
HASH & DYN
(KEYDATA)
OTHERS
HASH
DIRECTORY
DYNAM IC
OTHERS
DYNAM IC
1= Open
0= Not open
Pathname of file
2
3
4
5
7
8
13
Hash type (0 or 1)
Hash type (32 or 33)
10
11
13
17
18
19
Access permissions
20
ALL
21
ALL
Key value
14
M odulo
0
Current modulo
Not applicable
M inimum modulo
(Block size/1024)-1
Not applicable
Block size
Not applicable
M erge factor
Not applicable
Split factor
Not applicable
Percent result of the
formula:
(keyspace(grp) *100)/
blksize
Not applicable
1= yes; 2 = no
Not applicable
Next line number
Not applicable
VOC entry name
Not applicable
Block size
Not applicable
FILEINFO
137
READFWD and
READBCK.
22
ALL
1 Recoverable
0 Nonrecoverable
24
ALL
FILEINFO Codes
122 FILELOCK
Syntax
FILELOCK [file.var] [ON ERROR statements] LOCKED statements
Description
The OASYS Basic FILELOCK command locks the dictionary or data portion of a file against access by READL,
READU, READVU, MATREADL, MATREADU, MATWRITEU, WRITEU, and WRITEVU statements. Other file
input/output commands ignore FILELOCK.
Reminder: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic
Applications.
Parameters
The following table describes each parameter of the syntax.
Parameter
file.var
ON ERROR statements
LOCKED statements
Description
Specifies the file to lock.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
A default file is one for which no file variable is assigned in the
OPEN statement.
Specifies statements to perform if the FILELOCK statement
fails with a fatal error condition because the file is not open.
If you do not specify the ON ERROR clause, the program
terminates abnormally.
Specifies statements to execute if the file is already locked.
FILELOCK Parameters
Example
In the following example, the FILELOCK statement locks the file STAT, preventing lock-checking commands from
accessing this file:
2012 Onsystex Corp.
138
Related Commands
OASYS Basic
FILEUNLOCK, RECORDLOCKED, RELEASE
123 FILEUNLOCK
Syntax
FILEUNLOCK [file.var] [ON ERROR statements]
Description
The OASYS Basic FILEUNLOCK command unlocks a file previously locked with a FILELOCK command.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var
ON ERROR statements
Example
In the following example, the FILEUNLOCK statement unlocks the file referred to by the file variable
INVENTORY.FILE:
Related Commands
OASYS Basic
FILELOCK, RECORDLOCKED, RELEASE
124 FIND
Syntax
FIND expr IN dyn.array[,occur] SETTING f [,v[,s]] {THEN statements | ELSE statements}
2012 Onsystex Corp.
FIND
139
Description
The OASYS Basic FIND command determines the position of the given expression in a dynamic array. FIND
returns the attribute, value, and subvalue position of the found string. The expression must match the entire array
element to make a match.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
Specifies the expression to find. expr must be either a numeric value or a string
value.
Specifies the dynamic array in which to find expr.
Specifies the occurrence of expr to find. The default is 1 (the first occurrence).
dyn.array
,occur
FIND Parameters
Parameter
f,v,s
THEN
statements
ELSE
statements
Description
Specifies variables in which to place the position of expr:
f Attribute
v Value
s Subvalue
If the attribute found has neither multivalues nor subvalues, then v and s, if
specified, are set to 0. If only multivalues are present, s is set to 0. If only
subvalues exist, v is also set to 0.
Specifies statements to execute if the expr is found in the array. END is
required when statements extend over more than one line. Either a THEN
statement or an ELSE statement is required.
Specifies statements to execute if the expr is not found in the array. END is
required when statements are multiline. Either a THEN statement or an
ELSE statement is required.
FIND Parameters (continued)
For more information about writing THEN...ELSE parameters, see Developing OASYS Basic Applications. The
OASYS Basic FIND and LOCATE commands are compared in this manual.
Examples
In the following example, the program segment searches for an occurrence of 31 in the string DA. This results in
F=3, V=1, and S=0 because 31 is found in the third attribute as the first multivalue, and this attribute has no
subvalues.
In the next example, the program segment searches for the second occurrence of 41 in the string DA. This results
in F=3, V=4, and S=0 because the second occurrence of 41 is found in the third attribute as the fourth multivalue,
and this attribute has no subvalues.
140
Related Commands
OASYS Basic
[], FINDSTR, LOCATE
125 FINDSTR
Syntax
FINDSTR substr IN dyn.array[,occur] SETTING f[,v[,s]] {THEN statements | ELSE statements}
Description
The OASYS Basic FINDSTR command determines the position of a given substring in a dynamic array.
FINDSTR supports multibyte languages.
Parameters
The following table describes each parameter of the syntax.
Parameter
substr
dyn.array
,occur
Parameter
Description
Specifies the substring to find. substr must be either a numeric value or a
string value.
Specifies the dynamic array in which to find substr.
Specifies which occurrence of substr you want to find in the array. The
default for occur is 1 (the first occurrence).
FINDSTR Parameters
Description
f,v,s
Examples
In the following example, the program segment searches for 3 in the string DA. This results in F=3, V=1, and S=0
because 3 is found in the third attribute as the first multivalue, and this attribute has no subvalues.
In the next example, the program segment searches for the second occurrence of 4 in the string DA. This results
in F=3, V=4, and S=0 because the second occurrence of 4 is found in the third attribute as the 4 multivalue, and
this attribute has no subvalues.
2012 Onsystex Corp.
FINDSTR
141
Related Commands
OASYS Basic
FIND, LOCATE
126 FLUSH
Syntax
FLUSH
The FLUSH command flushes output to the terminal when CUST.OPTIONS 46 is on.
Note: For more information about CUST.OPTIONS 46, see the CUST.OPTIONS Commands Reference.
127 FMT
Syntax
FMT(expr, "len [f.char] {L | R | T | C} [n] [$] [,] [Z] [mask]")
FMT(expr, "{L | R | T | C} # len [f.char] [n] [$] [,] [Z] [mask]")
expr "[L | R | T | C] # len [f.char] [n] [$] [,] [Z] [mask]"
FMT(expr, pattern.var)
Description
The OASYS Basic FMT function formats data in expr for display purposes. FMT can format a dynamic array that
contains multivalues. The statement can be no longer than 2,046 characters.
In the first form of the syntax, L, R, C, or T and len are required.
The second form is the same as the first form with the elements in a different order.
The third form does not include the keyword FMT, but the elements are in the same order as in the second form.
In the fourth form, you provide the pattern format in a variable, pattern.var.
Note: The FMT function can produce different results based on the BASICTYPE setting. The parameter
descriptions that follow represent BASICTYPE U.
Parameters
The following table describes each parameter of the syntax.
Parameter Description
len
Specifies the total number of single-byte characters to appear in the output
string.
2012 Onsystex Corp.
142
f.char
L
R
C
T
n
$
,
Z
mask
Description
0
1
2
Successful completion.
String expression is invalid or exceeds the allowable string size.
Conversion code is invalid.
STATUS Function Return Values
Examples
In the following example, the program segment prints the variable SS.NUM as a formatted string using a pattern
mask. The result printed is a string with 11 characters, left-justified:543-70-4128.
In the next example, the program segment prints the variable NUM as a 12-character, right-justified number with
two decimal places, preceded by a dollar sign and composed with commas. The segment prints the value
$16,526.00.
In the next example, the program segment formats the string OUT.STRING with 0 as the fill character, rightjustified, and in a column of four spaces. The segment prints 0044.
In the next example, the program statement saves the variable STR as a right-justified, eight column string:
FMT
143
In the next example, the program segment uses a variable to specify the pattern format. OASYS formats STR
according to the variable PATTERN:
128 FOOTING
Syntax
FOOTING [ON num.expr] str.expr ['option']...
Description
The OASYS Basic FOOTING command causes the specified string to print or display at the bottom of each page
of a report. You can specify a footer of any length. The ECL LIMIT command has no effect on this command.
Note: Turn on OASYS.OPTION 64 to force the footing to appear on the last page or screen. With this option
turned off, the footing does not appear on the last page or screen. For more information about OASYS.OPTION
64, see the CUST.OPTIONS Commands Reference.
The PRINTER command directs the output of a FOOTING command not sent to a print file as follows:
PRINTER OFF causes a report, together with its footings, to appear on the users terminal screen.
PRINTER ON causes all subsequent footings, headings, and PRINT output to be sent to the destination
specified by the current SETPTR setting.
Parameters
The following table describes each parameter of the syntax.
Parameter
ON num.expr
str.expr
Description
Specifies a print file to which you want to send the footing: 0254.
Specifies the string to display at the bottom of each page.
option...
option must be enclosed in single quotation marks. You can place option
(s) anywhere in the footing expression. option can be any of the
following:
ASCII code Passes to the printer or file code controlling paging
characteristics.
P or S Prints current page number.
N Suppresses the pagination prompt after each page.
L Advances one line. Used for multiline footings.
D Prints date in M M -DD-YY format.
T Prints time/date in M M -DD-YY HH:M M :SS format.
C Centers the footing text.
G Forces the line to fill the width of the page.
FOOTING Parameters
128.1 Examples
In the following example, the program statement produces a footing using a character string:
144
In the next example, the program statement prints Page and the current page number. It advances one line and
then prints Pauls Produce. Notice the two single quotation marks in the middle of the strings. They are
necessary to print a single apostrophe in the footer. The ON 2 clause sends the footing to print file 2.
OASYS
SETPTR For information, see the OASYS Commands Reference.
129 FORMLIST
129.1 Syntax
FORMLIST dynamic.array.var [TO list.num.expr]
129.2 Description
The OASYS Basic FORMLIST command creates an active select list from a dynamic array. FORMLIST uses the
attribute marks in dynamic.array.var to create a select list that you can use with READNEXT statements or other
list processing commands such as external LIST statements.
129.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dynamic.array.var
TO list.num.expr
Description
Specifies a dynamic array from which to create a select list.
Specifies which list, 0 through 9, you want the list sent to. 0 is
the default list.
FORMLIST Parameters
129.4 Examples
In the following example, the program segment creates a select list and then uses that list to print four records in
the CLIENTS file:
FORMLIST
145
UniQuery
DELETE.LIST, GET.LIST, SELECT, SSELECT, SAVE.LIST For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
130 FOR/NEXT
Enter topic text here.
130.1 Syntax
FOR var = val1 TO val2 [STEP val3]
statements]
[UNTIL | WHILE expr]
statements
NEXT [var]
130.2 Description
The OASYS Basic FOR/NEXT command executes statements repeatedly while incrementing a variable over a
range until it reaches the end of the range, or until the condition in the WHILE or UNTIL clause is achieved. You
can nest FOR/NEXT constructions. Each FOR statement must end with a NEXT statement.
FOR/NEXT should be constructed so termination occurs based on the WHILE or UNTIL condition. Use the
CONTINUE statement to transfer control to the next iteration of the command.
146
130.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
val1
val2
STEP val3
statements
UNTIL |
WHILE
exprstatements
NEXT var
Description
Specifies the variable to increment.
Specifies the beginning of the range for incrementing var.
Specifies the end of the range for incrementing var.
Specifies the change to use in incrementing var. The increment can be
negative or positive, making the variable decrease or increase.
Specifies the statements to carry out for each loop.
Specifies a condition, expr, to test after each loop. If the UNTIL keyword
is used, the loop continues until expr is true. If the WHILE keyword is
used, the loop continues until expr is not true. In either case, when the loop
stops, the statements are executed before the program continues.
The NEXT statement defines the end of the block of statements to be
repeated. The optional var is the same variable as in the beginning of the
FOR/NEXT statement.
FOR/NEXT Parameters
130.4 Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. This segment prints multivalues from the ORDERS file when a client has
ordered multiple items.
In the following example, the program segment prints the string 10,8,6,4,2,. The loop terminates before printing 0
because the FOR/NEXT statement specifies that when the variable I falls below 1, the loop terminates.
FOR/NEXT
147
In the next example, the optional WHILE expression clause creates a secondary condition for the termination of
the FOR/NEXT structure. While a normal FOR/NEXT loop repeats the contained statements 10 times, the WHILE
clause results in this example stopping after only three repetitions. This occurs because the value read from the
DATA statement by the INPUT command exceeds the value of I on the third iteration. The WHILE clause with
the same statements results in the loop terminating after one iteration. After the iteration, I is less than K,
satisfying the condition and causing the loop to stop.
131 FUNCTION
131.1 Syntax
FUNCTION function.name [([MAT] arg.1[, [MAT] arg.2]...)]
RETURN var
131.2 Description
The OASYS Basic FUNCTION command begins the definition of a user-written function. The FUNCTION
command must be the first noncomment line in the file, which must be cataloged locally or globally.
The cataloged file name must be included in the DEFFUN statement in the calling program.
The calling program must specify the same number and type of arguments in the calling statement as are included
in the FUNCTION statement.
Note: OASYS triggers are OASYS Basic subroutines or functions that are called when a user attempts to
update or delete a record. For more information about coding a OASYS Basic function that is called by a
trigger, see Developing OASYS Basic Applications.
131.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
function.name
148
(M AT arg.1 ,M AT arg.2 Specifies the arguments to be passed from the calling program.
...)
Arguments must be enclosed in parentheses and separated by
commas. Precede an argument with M AT to indicate that the
argument is an array. Up to 254 arguments can be passed.
RETURN var
Returns control to the calling program. Can pass back an
argument.
FUNCTION Parameters
131.4 Examples
The following function performs calculations on a dimensioned array, returning values in the function arguments
and return value, r. The name of the cataloged file that contains this function definition is yourfunc. This name
must be used in the DEFFUN statement in the calling program. Notice that the function definition uses yet a
different name (anotherfunc). The name anotherfunc is not referenced anywhere.
The following program calls the preceding function. Because the function is called myfunc within this program,
the CALLING clause is included in the DEFFUN statement to identify the cataloged program file yourfunc. Note
that values in arguments a and b are passed back, although they are not used by the program.
GARBAGECOLLECT
149
132 GARBAGECOLLECT
132.1 Syntax
GARBAGECOLLECT
132.2 Description
The OASYS Basic GARBAGECOLLECT command releases all reserved but nonactive memory allocated for
OASYS Basic variables.
133 GE
133.1 Syntax
expr1 GE expr2
133.2 Synonyms
#<, =>, >=
133.3 Description
The OASYS Basic >= relational operator tests whether expression expr1 is greater than or equal to expr2.
expr1 and expr2 can be any valid OASYS Basic expressions, variables, strings, or literals.
Relational operators make the comparisons that direct program flow in conditional statements like the following:
133.4 Example
In the following example, the program segment tests whether A is greater than or equal to B. Because A is greater
than B, the message Greater Than or Equal To prints.
150
134 GES
Enter topic text here.
134.1 Syntax
GES(array1,array2)
134.2 Description
The OASYS Basic GES function compares each value in array1 to its corresponding value in array2. OASYS
returns an array with 1 in each position where the value in array1 is greater than or equal to the value in the
corresponding position in array2. OASYS returns 0 in each position for values that are less than array2.
134.3 Example
In the following example, the program segment compares ARRAY1 to ARRAY2 and returns ARRAY3. ARRAY3
then contains 1}1}1}0}0.
135 GET
135.1 Syntax
GET[X] var[,length] [SETTING count.var] FROM line.expr [UNTIL term.expr]
[RETURNING term.var] [WAITING seconds]
[THEN statements |ELSE statements]
135.2 Description
The OASYS Basic GET command receives unprompted input from an attached line. OASYS accepts all control
characters, including the carriage return and line feed as input characters. All data read from the attached line is
placed in var. GET supports multibyte languages.
Performance of the GET statement varies according to the termination conditions specified, and whether the
THEN or ELSE clauses are specified.
Input from the attached line is terminated in four ways:
2012 Onsystex Corp.
GET
151
135.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
,length
SETTING count.var
FROM line.expr
UNTIL term.expr
RETURNING term.var
WAITING seconds
THEN statements | ELSE
statements
135.4 Example
In the following example, the program segment waits 15 seconds for 10 characters of input from line 0. If time
expires before 10 characters are received from the attached line, OASYS stops receiving, returns the data
2012 Onsystex Corp.
152
OASYS
PROTOCOL For information, see the OASYS Commands Reference.
136 GETENV
Enter topic text here.
136.1 Syntax
GETENV(var | "envir.var")
136.2 Description
The OASYS Basic GETENV function returns the contents of the UNIX, or Windows platform environment
variable. If you include the environment variable explicitly (as opposed to including it in a variable), you must
enclose it in quotation marks.
136.3 Examples
In the following example, the program statement retrieves the value of OASBIN in X:
In the next example, the program retrieves the value of OASBIN in X, but uses a variable to define OASBIN:
137 GETLIST
137.1 Syntax
GETLIST list.name [,acct.name] [TO list.num] [SETTING count.var]
{THEN | ELSE} statements [END]
GETLIST
153
137.2 Description
The OASYS Basic GETLIST command restores a select list from a saved list.
Tip: Use GETLIST to access a list without having to issue multiple SELECT or SSELECT commands.
137.3 Parameters
Parameters
The following table describes each parameter of the syntax.
Parameter
list.name
acct.name
Description
Specifies the saved list.
Specifies a full path of a directory where the list resides if list.
name is not in the current account.
TO list.num
Specifies the number of the active list. list.num can be 0 through
9. The default list is 0.
SETTING count.var
Specifies a variable to contain the number of elements the
GETLIST command generates.
THEN | ELSE statements Specifies statements to execute if the command succeeds (THEN)
or fails (ELSE). Either a THEN or an ELSE statement is required.
END is required to terminate multiline statements.
GETLIST Parameters
137.4 Examples
In the following example, the program segment retrieves the previously saved list CS_STAFF and assigns it to
active list 2. If the list is not found, the program aborts and displays an error message.
In the next example, the program segment creates a select list and saves it. GETLIST then retrieves the saved list
to active list 0 (the default). The program then uses the IDs in list 0 to retrieve the first 22 Canadian clients.
154
UniQuery
DELETE.LIST, GET.LIST, SELECT, SSELECT, SAVE.LIST For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
138 GETPTR
Enter topic text here.
138.1 Syntax
GETPTR(unit.no)
138.2 Description
The OASYS Basic GETPTR function returns a string variable containing the values of the current printer settings
for the unit.no specified.
Tip: GETPTR can store the values associated with a print unit so those values can be reset to their initial
values at the end of a process.
Description
unit
width
length
topmargin
bottommargin
mode
options
GETPTR
155
Description
If success.
If there are no more rows.
Other error.
STATUS Function Re turn Value s
138.5 Example
In the following example, the program segment assigns the printer settings to the variable PRINTER.STRING:
139 GETPU
Enter topic text here.
139.1 Syntax
GETPU(unit.number)
139.2 Description
The OASYS Basic GETPU function returns the full path of the current print or hold file ID created by the current
user process. unit.number is the number of the logical printer unit.
Tip: Use the ECL SETPTR command to determine the current printer unit of your system.
OASYS
SETPTR For information, see the OASYS Commands Reference.
156
140 GETQUEUE
140.1 Syntax
GETQUEUE()
140.2 Description
The OASYS Basic GETQUEUE function returns a dynamic array containing information about all records
currently locked and waiting to be released.
OASYS Basic commands that check for locks, such as READU and READVU, cause processes to wait for locks
to be released before proceeding.
This command delivers the same information as the ECL command LIST.QUEUE, but in a different format. A value
mark separates these pieces of information. An attribute mark separates the information about different locks.
If GETQUEUE is successful, OASYS sets @SYSTEM.RETURN.CODE to the number of locks waiting to be
released. If unsuccessful, OASYS sets @SYSTEM.RETURN.CODE to -1.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Description
The number of the OASYS process that locked the file.
The ID of the process that ran the OASYS application that locked the
file.
The user ID of the user who ran the OASYS application that locked the
file.
GETQUEUE Function Return Values
Value
Description
USERNAM E
The user name of the user who ran the OASYS application that locked
the file.
TTY
The terminal ID of the user who ran the OASYS application that locked
the file.
FILE NAM E
INBR
GETQUEUE
157
For Windows platforms, this value consists of the high integer and low
integer of the i-node used by the locked file. The high integer and the low
integer are separated by a space.
DNBR
RECORD ID
M ODE
141 GETREADU
Enter topic text here.
141.1 Syntax
GETREADU()
141.2 Description
The OASYS Basic GETREADU function returns a dynamic array containing information about all records that
have been locked by any OASYS Basic or ECL command that updates any record.
This command delivers the same information as the ECL command LIST.READU, but in a different format. A
value mark separates these pieces of information. An attribute mark separates the information about different
locks.
If GETREADU is successful, OASYS sets @SYSTEM.RETURN.CODE to the number of locks set. If
unsuccessful, OASYS sets @SYSTEM.RETURN.CODE to -1.
Note: OASYS Basic locks are advisory only. For more information, see the Developing OASYS Basic
Applications.
Description
OASNO
USERNBR
UID
USERNAM E
TTY
158
FILE NAM E
INBR
DNBR
RECORD ID
M ODE
TIM E
DATE
142 GETUSERGROUP
Enter topic text here.
142.1 Syntax
GETUSERGROUP(uid)
142.2 Description
For UNIX, the OASYS Basic GETUSERGROUP function returns the group number for the user ID you specify
by uid. For Windows platforms, it returns 0.
142.3 Examples
In the following example, the program statement assigns the user group to variable X:
In the next example, the program statement assigns the user group for 1023 to variable X:
143 GETUSERID
143.1 Syntax
GETUSERID(user.name)
GETUSERID
159
143.2 Description
The OASYS Basic GETUSERID function returns the user ID for a user name. For UNIX, this is the systemrecognized user ID. For Windows platforms, the returned user ID is meaningful in OASYS only.
143.3 Example
In the following example, the program statement assigns the user ID for John to variable X:
144 GETUSERNAME
Enter topic text here.
144.1 Syntax
GETUSERNAME(uid)
144.2 Description
The OASYS Basic GETUSERNAME function returns the user name for a user ID. To obtain the ID of the current
user, use the OASYS Basic @UID variable (or, for UNIX, enter id at the UNIX prompt). After you obtain the
user ID, you can specify it explicitly in the GETUSERNAME function.
144.3 Examples
In the following example, the program statement assigns the user name to variable X:
In the next example, the program statement assigns the user name for 1023 to variable X:
160
145 GOSUB
Enter topic text here.
145.1 Syntax
GOSUB label[:]
145.2 Description
The OASYS Basic GOSUB command transfers program control to an internal subroutine. OASYS requires a valid
statement label. Control returns to the main program when the RETURN statement is encountered in the
subroutine.
145.3 Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. This is an example of subroutines used in structured programming style.
GOSUB
161
146 GOTO
Enter topic text here.
146.1 Syntax
GOTO label [:]
146.2 Synonym
GO
146.3 Description
The OASYS Basic GOTO command branches unconditionally to a statement label within a program or
subroutine. A statement label must exist in the program or subroutine. If the label you specify does not exist, the
compiler generates an error message and the program aborts. After a program executes a GOTO, it does not keep
track of the point of departure, but simply moves to the new statement and begins executing there.
You cannot use the OASYS Basic RETURN command in conjunction with a GOTO statement.
Tip: Use GOSUB instead of GOTO to make your programs easier to follow and maintain.
146.4 Examples
In the following example, the program statement transfers program control to the statement label 2510:
In the next example, the program statement transfers control to the statement label START if the variable RETRY
is true:
147 GROUP
Enter topic text here.
147.1 Syntax
GROUP(str, delim, start, rtn.num)
162
147.2 Description
The OASYS Basic GROUP function extracts the number of continuous groups you specify from the given string.
GROUP functions similar to option G of the OCONV Group (G) function (group extraction conversion), but allows
any single character, including a system delimiter, null value, number, or minus sign (-) as a delimiter. Another
difference is that the start parameter of the GROUP function specifies the starting group to return, while OCONV
specifies the number of leading groups to skip.
147.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str
delim
start
rtn.num
147.4 Examples
In the following example, the program statement assigns 1231 to the variable A:
In the next example, the program segment prints Boulder because it is the second group separated by :, and
only one group is returned:
148 GROUPSTORE
Enter topic text here.
148.1 Syntax
GROUPSTORE substr IN str USING start.num,replace.num [,delimiter]
GROUPSTORE
163
148.2 Description
The OASYS Basic GROUPSTORE command inserts a given substring or portion of a substring into a string, and
replaces all, part, or none of the string. The string can be delimited by the single character delimiter. The unit of
replacement is called an element in this section.
148.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
substr
Specifies the substring you want to insert into the string. substr can contain
any combination of numeric, alphabetic, or special characters.
Specifies the target string into which substr is inserted.
GROUPSTORE Parameters
str
Parameter
Description
start.num
Specifies the position from which to begin replacing elements of the string.
start.num must be at least 1. If you specify a value of less than 1, start.num
defaults to 1. If start.num is negative and replace.num is not negative,
OASYS Basic uses the absolute value of start.num.
If start.num is greater than the number of elements in the target string,
OASYS Basic appends the substr to the end of the string with the
appropriate number of delimiters in between.
Specifies the number of elements in the string to replace with elements of
substr.
Refer to the next table for values for replace.num.
Specifies a single ASCII character to use as a delimiter. The default delimiter
is @AM . If you specify more than one character for delimiter, OASYS
Basic uses the first character.
GROUPSTORE Parameters (continued)
replace.num
,delimiter
The replace.num option controls whether GROUPSTORE replaces all, part, or none of the substring. The
following table describes these options.
replace.num Value
Description
>0
The first replace.num elements of the substr replaces elements of the string
starting from the position specified by start.num. If the string contains fewer
than replace.num elements starting from start.num, the replacement stops
after the string is exhausted.
The entire substr is inserted before the start.num position in the string.
The number of elements specified in replace.num are deleted starting at start.
num, and substr replaces them.
If both start.num and replace.num are less than 0, replacement does not take
place. Only the number of elements specified in replace.num are deleted,
starting at start.num.
GROUPSTORE Replace Number Values
0
<0
164
148.4 Examples
In the following example, the program segment assigns the value stored in string SUB in string A. Because the
starting number is 2, and no delimiter is specified, OASYS uses the attribute mark (@AM) as the delimiter.
In the next example, the program segment replaces both values in the third attribute in A with SUB. Though the
replacement number is 2, OASYS replaces only one attribute because SUB has only one element.
In the next example, the program segment inserts SUB before position 1 in A:
In the next example, the program segment replaces the first two attributes and their associated subvalues with
SUB using @VM as the delimiter:
This next example compiles and runs only with null value handling turned on. The program segment replaces the
third element with three asterisks. This program segment calls the externally cataloged subroutine PRINT.SETUP,
which converts the null value and OASYS delimiters to printable characters, and then prints the converted string.
GROUPSTORE
165
149 GT
Enter topic text here.
149.1 Syntax
expr1 GT expr2
149.2 Synonym
>
149.3 Description
The OASYS Basic relational operator GT tests whether expression expr1 is greater than expr2.
expr1 and expr2 can be any valid OASYS Basic expressions, variables, strings, or literals.
Relational operators make the comparisons that direct program flow in conditional statements such as the
following:
149.4 Example
In the following example, the program segment tests whether A is greater than B. Because A is greater than B, the
message Greater Than prints.
166
150 GTS
Enter topic text here.
150.1 Syntax
GTS(array1,array2)
150.2 Description
The OASYS Basic GTS function compares each value in array1 to its corresponding value in array2. OASYS
returns an array with 1 in each position where the value in array1 is greater than the value in the corresponding
position in array2, and 0 in each position for values that are less than array2.
150.3 Example
In the following example, the program segment compares ARRAY1 to ARRAY2 and returns ARRAY3. ARRAY3
then contains 1}1}0}0}0.
151 HASH
151.1 Syntax
HASH(rec.key,modulo,type)
151.2 Description
The OASYS Basic HASH function determines to which group a particular record key is hashed, depending on the
modulo and the file type. HASH returns the group number in which a record with a key of rec.key is stored.
HASH includes a file type parameter.
When rec.key, modulo, and type are passed to the function, HASH returns the group number to which the record
key will hash.
HASH
167
151.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
rec.key
modulo
type
152 HEADING
152.1 Syntax
HEADING [ON expr] str.expr ['option']...
152.2 Description
The OASYS Basic HEADING command prints a string you specify at the top of each report page on the current
print device.
Note: The HEADING command clears the screen before displaying a report.
152.3 Parameters
The following table describes each parameter of the syntax.
Parameter
ON expr
str.expr
Description
Directs OASYS to send output to print file expr. As many as 31 print files
can be active at a time. The print files can have identifiers of 0254.
Specifies a string to print at the top of each report page. You can use special
characters, such as unmatched single and double quotation marks, in str.expr.
168
'option'
option must be enclosed in single quotation marks. You can place option(s)
anywhere in the heading expression. option can be any of the following:
ASCII code Passes code controlling paging characteristics.
P or S Prints current page number.
N Suppresses the pagination prompt after each page.
L Advances one line. Used for multiline headings.
D Prints date in M M -DD-YY format.
T Prints time/date in M M -DD-YY HH:M M :SS format.
C Centers the heading text.
G Forces the line to fill the width of the page.
W Causes a page to fill completely before breaking and printing the heading
when the HEADING statement is first encountered. If you do not specify
W, OASYS creates a new page break when it first encounters the HEADING
statement.
HEADING Parameters
152.4 Examples
In the following example, the HEADING statement sends a heading to print file 3: current page number
Shareholders Report current date.
In the next example, the HEADING statement prints the current page number, and the current date and time, on
the top of the default print device. The N code causes the report to print continuously, not requiring a carriage
return after each page.
OASYS
SETPTR For information, see the OASYS Commands Reference.
153 HUSH
Enter topic text here.
153.1 Syntax
HUSH {ON | OFF | expr} [SETTING pre.status.var]
HUSH
169
153.2 Description
The OASYS Basic HUSH command enables or disables terminal output.
153.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
ON
OFF
expr
SETTING pre.
status.var
HUSH Parameters
153.4 Example
In the following example, the program segment prints 1 and -1 on the terminal screen because the HUSH
command enables the terminal (A + B evaluates to 0). The second PRINT statement produces nothing on the
screen because HUSH ON is set. The third PRINT command prints C = 1 on the screen because terminal output is
enabled.
154 ICONV
Enter topic text here.
154.1 Syntax
ICONV(expr,conv.code.expr)
154.2 Description
The OASYS Basic ICONV function converts string or numeric data to internal representation format based on
conversion codes. ICONV supports multibyte languages. If the input value or conversion code is invalid, OASYS
returns the input value.
With null value handling turned on, the presence of the null value in data produces a result of the null value, and
the STATUS function return value is set to 5.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
2012 Onsystex Corp.
170
154.3 Parameters
Parameters
The following table describes each parameter of the syntax.
Parameter
expr
conv.code.expr
Description
Specifies the expression (a string or numeric data) to convert.
Specifies an internal representation format to use when converting expr.
ICONV Parameters
The following table summarizes the valid conversion codes. A detailed discussion of each follows under separate
headings.
Code
Format
D
G
L
MB
MC
MD
ME
ML
MP
M P1
System date.
Extracts one or more strings separated by a delimiter.
Length.
Binary.
M asked character.
M asked decimal.
M asked extended.
Left justify.
Packed decimal.
Convert to packed decimal without truncating at the first CHAR(0) or altering
this character.
Octal.
Right justify.
System time.
Hexadecimal.
Pattern match.
Range.
SOUNDEX.
Text extraction.
File translation.
ICONV Codes
MO
MR
MT
MX
P
R
S
T
Tfile
Description
Successful conversion.
Invalid input data.
Invalid conversion specification.
Invalid date for D conversion code only.
Null value if null value handling is turned on.
STATUS Function Return Values
ICONV
171
154.5 Examples
The following program segment demonstrates the date and time conversions:
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. It demonstrates the alternate syntax that does not use the ICONV
function name. This code right-justifies a string of 10 characters so that the data lines up on the right.
155.1 Syntax
ICONV(ext.date, "D [y] [c]")
155.2 Description
The ICONV date (D) function converts display representations of dates into simple integer internal format.
Internal date format is the number of days before or since December 31, 1967. If the input value or conversion
code is invalid, OASYS returns the input value.
Note: OASYS ignores leading and trailing spaces around the input date.
In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or conversion
code is invalid.
155.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
ext.date
Specifies the date, in display format, to convert to internal format. Valid
delimiters include the slash, comma, hyphen, and period.
D
Indicates a date conversion.
yc
The ICONV function does not use y and c, but they are accepted to maintain
consistency with the OCONV Date (D) function.
ICONV Date Parameters
172
The first ICONV returns a value of 10010. OCONV correctly returns the external format. The date matches the
initial entry. However, the second ICONV accepts the internal format, 10010, as input; OASYS translates this as
October 1, 2000, and ICONV returns an internal format of 11963. The final OCONV returns 01 OCT 2000.
Note: To prevent the preceding scenario, you can make all numeric input of fewer than six characters invalid
by turning CUST.OPTIONS 82 on. However, your applications will no longer be able to process the
abbreviated input dates.
Description
Successful conversion of a valid date.
Invalid input date.
Invalid conversion specification.
Date was converted correctly, but month and day were inverted in input value.
STATUS Function Return Values
Note: After you execute the ICONV D function, the STATUS function returns a code indicating the execution
status of the conversion of the last array element only.
2012 Onsystex Corp.
155.5 Examples
The following table describes common date conversions and their results.
Value
Code
Result
09/15/85
D
6468
12/31/67
D
0
December 31, 1967
D
0
01/29/1988
D
7334
Common Date Conversions
In the following example, the program segment prints the date in internal and display format:
The following table describes various dates you can input in the previous program and their conversions.
In_Date
Internal
Output
1
8402
01/01/1991
11
8706
11/01/1991
011
8402
01/01/1991
12
8736
12/01/1991
121
8736
12/01/1991
110389
8709
11/03/1989
1/1
8402
01/01/1991
1/1/89
8402
01/01/1989
1/1/02
12420
01/01/2002
Example Date Conversions
156.2 Description
The ICONV group (G) function extracts one or more strings separated by a delimiter. If the input value or
conversion code is invalid, OASYS returns the input value.
173
174
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
156.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
G
m
*
n
156.4 Example
In the following example, the program segment prints (303):
157.2 Description
The ICONV length (L) function extracts a string of a specified length or that falls within a range of acceptable
lengths. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
175
157.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
L
n
157.4 Example
In the following example, the program segment prints 123 and an empty string because the value of X has fewer
than five characters and more than three:
158.1 Syntax
ICONV(expr, "MC [A | /A | B | /B | C | U | L | T | N | /N | P| X[D] | D | D[X] | X]")
158.2 Description
The ICONV masked character (MC) function provides many conversion functions that retrieve and/or convert
values in strings and arrays. This function performs the same conversions and extractions as OCONV Masked
Character (MC). OASYS returns the input value if either the value to be converted or the conversion code is
invalid.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
158.3 Parameters
The following table describes each parameter of the syntax.
Parameters
2012 Onsystex Corp.
Description
176
expr
A
/A
B
/B
C;x;y
U
L
Parameters
T
N
/N
P
X[D] or D
D[X] or X
Description
Converts to initial cap style. The first letter of each word is uppercase, and
all other letters are lowercase. Space and tab are word separators.
Extracts all numeric characters (09).
Extracts all nonnumeric characters.
Converts all nonprinting characters to tildes (~).
Assumes input is in decimal; converts to hexadecimal.
Assumes input is in hexadecimal; converts to decimal.
ICONV Masked Character (MC) Parameters (continued)
158.4 Example
You can use ICONV to remove special characters in a formatted price. For example, the following program
segment extracts 1234 from $12.34:
159.1 Syntax
ICONV(num.expr, "MDn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] [-| < | E | C | D] [P] [Z] [T] [xc
]")
159.2 Description
The ICONV masked decimal (MD) function converts a decimal number to internal format after rounding, as
specified by f. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
177
The ICONV MD, ML, and MR functions have the same result. They exist separately to maintain consistency with
the OCONV MD, ML, and MR functions, which produce different results.
159.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
num.expr
Parameter
Description
Scales the input value num.expr by moving the decimal point f places to the
right. If omitted, f defaults to the value assigned to n (for example, if you
specify M D2, OASYS reads it as M D22, and then ignores the first 2).
dec_symbl
You can specify a symbol to represent the decimal point in the input number
by including dec_symbl. An example is provided in the following section.
[prefix], [
The ICONV function ignores these options, but they are included in the
thsnd_mark], [ syntax to maintain consistency with the OCONV M asked Decimal (M D)
suffix]] ] [,] [$] function.
[-| < | E | C | D]
[P] [Z] [T] [(xc
)]
ICONV Masked Decimal (MD) Parameters (continued)
f
159.4 Examples
In the following example, OASYS converts the value 12.339 to 1234 by rounding to two decimal places and
converting to internal format:
The following example demonstrates how to specify that an alternate symbol is used to represent the decimal
point in the input number. This example prints 12350.
178
160.1 Syntax
ICONV(num.expr, "MLn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] [C] [Z] [(mask)]")
160.2 Description
The ICONV left justify (ML) function converts a decimal number to internal format after rounding, as specified
by f. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
The ICONV MD, ML, and MR functions have the same result. They exist separately to maintain consistency with
the OCONV MD, ML, and MR functions, which produce different results.
160.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
num.expr
Parameter
Description
Scales the input value expr by moving the decimal point f places to the right.
If omitted, f defaults to the value assigned to n (for example, if you specify
M L2, OASYS reads it as M L22, and then ignores the first 2).
dec_symbl
You can specify a symbol to represent the decimal point in the input
number by including dec_symbl. For an example, see the following section.
[prefix], [
The ICONV function ignores these options, but they are included in the
thsnd_mark], [ syntax to maintain consistency with the OCONV Left Justify (M L)
suffix]] ] [,] [$] function.
[C] [Z] [(mask)]
ICONV Left Justify (ML) Parameters (continued)
f
160.4 Example
In the following example, OASYS converts the value 12.339 to 12339 based on the ML3 conversion code:
179
The following example demonstrates how specify an alternate symbol to represent the decimal point in the input
number. This example prints 12350.
161.1 Syntax
ICONV(expr, "MP")
161.2 Description
The ICONV packed decimal (MP) function converts an integer expr into packed decimal representation by
compressing two digits of the integer into one byte. OASYS returns the input value if either the value to be
converted or the conversion code is invalid.
Tip: Use this function to conserve disk space.
In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or conversion
code is invalid.
162.1 Syntax
ICONV(expr, "MP1")
162.2 Description
The ICONV packed decimal (MP1) function converts an integer expr in packed decimal representation into its
display format without truncating at the first CHAR(0) character or altering CHAR(0). If the input value or
2012 Onsystex Corp.
180
163.2 Description
The ICONV right-justify (MR) function converts a decimal number to internal format after rounding, as specified
by f. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
The ICONV MD, ML, and MR functions have the same result. They exist separately to maintain consistency with
the OCONV MD, ML, and MR functions, which produce different results.
163.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
num.expr
Parameter
Description
Scales the input value expr by moving the decimal point f places to the right.
If omitted, f defaults to the value assigned to n (for example, if you specify
M R2, OASYS reads it as M R22, and then ignores the first 2).
You can specify a symbol to represent the decimal point in the input
number by including dec_symbl. An example is provided in the following
section.
dec_symbl
181
[prefix], [
The ICONV function ignores these options, but they are included in the
thsnd_mark], [ syntax to maintain consistency with the OCONV Right Justify (M R)
suffix] [,] [$] [C] function.
[Z] [(mask)]
ICONV Right Justify (MR) Parameters (continued)
163.4 Example
In the following example, OASYS converts the value 12.339 to 1234 based on the MR2 conversion code:
The following example demonstrates how to specify that an alternate symbol is used to represent the decimal
point in the input number. This example prints 12350.
164.2 Description
The ICONV time (MT) function converts the time of day from display format into internal format. The value of the
internal format is the number of seconds since midnight (00:00:01 as 1, and 24 as 86400).
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
164.3 Parameters
The following table describes each parameter of the syntax.
Parameter
str.expr
Description
Time input must be in the form HH:M M :SS.
MM and SS are not required and, if you do not specify them, OASYS
assumes the values to be zero. You must use a separating character (any
nonnumeric character, such as a colon or comma) between units (for
182
H Sc
164.4 Example
The following table describes the time conversion code and the resulting value.
Value
Code Specification
Result
12:30
12AM
12PM
MT
MT
MT
45000
0
43200
165.1 Syntax
ICONV(num.expr, ["HEX | MX [0C] | MO [0C] | MB [0C]"])
165.2 Description
The ICONV hex (MX), octal (MO), and binary (MB) functions convert a number from one of three numbering
systems to decimal value. OASYS returns the input value if either the value to be converted or the conversion
code is invalid.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
165.3 Parameters
The following table describes each parameter of the syntax.
Parameter
num.expr
Description
Specifies the decimal value, in display format, to convert to an alternate
numbering system.
HEX |
M X [0C]
183
M O [0C]
M B [0C]
The following table lists conversion codes to be used with ICONV to convert from other numbering systems to
decimal value or ASCII character.
From
To
Function
Binary
Binary
Octal
Octal
Hexadecimal
Hexadecimal
Decimal value
ASCII character
Decimal value
ASCII character
Decimal value
ASCII character
ICONV M B
ICONV M B0C
ICONV M O
ICONV M O0C
ICONV M X
ICONV M X0C
ICONV HEX
ICONV Options for Converting from Alternate Numbering Systems
ICONV conversions into other numbering systems produce multiple characters in the target numbering system:
Hexadecimal One ASCII character produces two hexadecimal characters. For example, ASCII character 0 is
equal to hexadecimal 30.
Octal One ASCII character produces three octal characters. For example, ASCII character 0 is equal to octal
060.
Binary One ASCII character produces eight binary characters. For example, ASCII character 0 is equal to
octal 00110000.
165.4 Examples
The following table demonstrates some ICONV MO, MX, and MB conversion codes and their results.
Input
123123
123123 (octal)
Code
MO
M O0C
Result
42579 (decimal)
SS (ASCII characters)
Input
Code
Result
100 (hexadecimal)
MX
256 (decimal)
101010101010 (binary) M B
170 (decimal)
4B (hexadecimal)
MX
75 (ASCII characters)
Examples of Numbering System Conversions (continued)
184
166.1 Syntax
ICONV(str.expr, "P(op)[;(op).....]")
166.2 Description
ICONV pattern match (P) function performs the same function as the OCONV pattern match (P) function. For
information, see OCONV Pattern Match (P).
167.1 Syntax
ICONV(num.expr, "Rndm[;ndm.....]")
167.2 Description
The ICONV range (R) function returns only those data values that fall within a specified range of decimal values.
When including a negative range, you must specify the highest negative number first. If range specifications are
not met, OASYS returns an empty string. If the input value or conversion code is invalid, OASYS returns the
input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
167.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
num.expr
n
d
185
167.4 Example
In the following example, the program segment prints 123 and a blank line because X is within the range and Y
is not:
168.1 Syntax
ICONV(str.expr, "S")
168.2 Description
The ICONV SOUNDEX (S) function converts string or numeric data specified by str.expr to phonetic format
based on SOUNDEX conversion codes. The S conversion code can be used in an ICONV virtual attribute
formula. If the input value or conversion code is invalid, OASYS returns the input value.
For more information about SOUNDEX conversion codes, see the SOUNDEX command.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
168.3 Example
The following example is virtual attribute, SDX_LNAME, that converts the value of the variable LNAME to its
SOUNDEX expression:
186
169.1 Syntax
ICONV(str.expr, "T[m,]n")
169.2 Description
The ICONV text extraction (T) function extracts a substring from a string. If the input value or conversion code is
invalid, OASYS returns the input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
169.3 Parameters
The following table describes each parameter of the syntax.
Parameter
str.expr
m
n
Description
Indicates a string to be searched.
Extracts a contiguous string of characters starting from character m.
Extracts a contiguous string of characters of length n.
ICONV Text Extraction (T) Parameters
169.4 Examples
The following table describes some ICONV text extraction codes and their results.
Input
Code
Result
QRSTUV
DAM N THE
TORPEDOES
CONVERSION IS THE
KEY
457 COLORADO BLVD
T3
T3,5
TUV
M N TH
T1,9
CONVERSIO
T4,7
[space]COLORA
187
170.1 Syntax
ICONV(rec.id, "T[DICT] [filename;cn;I-Attribute;O-Attribute]")
170.2 Description
The ICONV file translation (Tfile) function performs the same action as OCONV file translation (Tfile). For
information, see OCONV File Translation (Tfile).
171 ICONVS
Enter topic text here.
171.1 Syntax
ICONVS(dyn.array.expr, conv.code.expr)
171.2 Description
The OASYS Basic ICONVS function converts string or numeric data from display format to internal format,
based on a conversion code, for each element of a dynamic array. If the input value or conversion code is invalid,
OASYS returns the input value.
Note: In BASICTYPE P, ICONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
171.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.expr
conv.code.expr
Description
Specifies a dynamic array, each element of which to convert.
Specifies a code to use in converting each element of the dynamic array.
ICONVS Parameters
Description
Successful conversion.
Invalid input data.
188
2
3
5
171.5 Example
In the following example, the program segment converts each element of ARR1 to internal format:
Note: The blanks in the number are value marks, which are nonprinting characters. The value marks could
display as some other character on your terminal screen.
172 IF/THEN/ELSE
Enter topic text here.
172.1 Syntax
IF expr THEN statements [ELSE statements]
IF expr THEN
statements...
END [ELSE
statements...
END]
IF expr ELSE statements
IF expr ELSE statements
END
172.2 Description
based on a conditional expression. If expr is true, OASYS executes the first group of statements. If expr is false,
OASYS executes the second group of statements.
IF/THEN/ELSE
189
To correct this problem, enter each clause of the statement on a separate line, or use the IN() function to obtain
input from theterminal or input queue.
With null value handling turned on, a test on expr that is the null value returns false. For an overview of how the
null value affects OASYS Basic, see Developing OASYS Basic Applications.
Tip: You can nest IF/THEN/ELSE statements, but a CASE statement might be more efficient.
172.3 Examples
In the following example, the program statement tests if the variable SUPPLY is less than the variable DEMAND.
If the comparison is true, program control is transferred to the statement labeled REORDER.
In the next example, the program segment compares INCOME to TARGET. OASYS executes the first branch if the
comparison is true, or executes the second group of statements if the comparison is false.
173 IN
Enter topic text here.
173.1 Syntax
IN( )
190
173.2 Description
The OASYS Basic IN function captures raw data from an input queue or from a terminal.
Tip: IN can capture function, arrow, and other special keys from the keyboard.
173.3 Example
In the following example, the program segment assigns the value y to ANSWER:
174 INDEX
Enter topic text here.
174.1 Syntax
INDEX(str.expr1,str.expr2,num.expr)
174.2 Description
The OASYS Basic INDEX function returns the starting position of the num.expr occurrence of str.expr2 within
str.expr1. INDEX supports multibyte languages.
174.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr1
str.expr2
num.expr
174.4 Examples
In the following example, the program segment searches STR.VAR for the second occurrence of the letter t and
returns that location in the variable LOC. In this example, it returns a value of 8.
INDEX
191
In the next example, the INDEX function operates like the COL() functions used in conjunction with the FIELD
function. It returns the beginning position of the string 212 within the string variable STR. The result stored in
the variable NY.STR is 15.
175 INDICES
Enter topic text here.
175.1 Syntax
INDICES(file.var[, index.name.expr])
175.2 Description
The OASYS Basic INDICES function returns one of the following:
Names of alternate key indexes.
Information about a particular alternate key index.
192
175.3 Parameters
The following table describes each parameter of the syntax.
Parameter
file.var
, index.name.expr
Description
Specifies the file about which to return index information.
Specifies an alternate key index about which to return
information.
INDICES Parameters
OASYS
BUILD.INDEX, CREATE.INDEX For information, see the OASYS Commands Reference.
176 INMAT
Enter topic text here.
176.1 Syntax
INMAT( )
INMAT(array.name)
176.2 Description
The OASYS Basic INMAT function, in the first form, returns the number of elements (rows) in a dimensioned
array. The second form returns the current dimension of the dimensioned array array.name. If the dimensioned
array has two dimensions, the bounds are separated by value marks.
After you open a file, the value of INMAT contains the number of modulos that make up the file. Subsequent file
operations using dimensioned array commands also set the value returned by INMAT.
Meaning
2012 Onsystex Corp.
INMAT
DIM
Command
Meaning
M ATREAD
M ATREADL
M ATREADU
M ATPARSE
OPEN
OSBWRITE
193
176.4 Examples
In the following example, the program segment fills the array MAIN.MAT with values from REC. If a sufficient
number of elements are available in the target array, the value of INMAT is set to the number of elements filled. If
the number of values exceeds the number of elements in the target array, excess data is lumped in the 0 position,
and the value of INMAT is set to 0.
In the next example, the program segment dimensions two arrays and then prints the dimensions using the PRINT
statement and INMAT function:
177 INPUT
Enter topic text here.
194
177.1 Syntax
INPUT var [,length [ _ ]] [:] [{FOR | WAITING} time.expr] [UNFILTERED] [THEN statements | ELSE statements]
INPUT var [,-l] [{FOR | WAITING} time.expr] [UNFILTERED] [THEN statements | ELSE statements]
177.2 Description
The OASYS Basic INPUT command requests data from an input queue or from the terminal screen. INPUT
supports multibyte languages.
If INPUT is successful, OASYS sets @SYSTEM.RETURN.CODE to 0. If unsuccessful (the INPUT statement with
a FOR or WAITING clause timed out), OASYS sets @SYSTEM.RETURN.CODE to -1.
One variable is read by each INPUT statement. If you press ENTER in response to an INPUT statement, an empty
string is assigned to the variable.
Tip: Precede INPUT with a PRINT statement to display a prompt.
CUST.OPTIONS 83 enables the escape character (usually ASCII code 27) to be accepted by INPUT while
screening out or converting other control characters.
THEN | ELSE is associated with the WAITING clause except in the case described in the following warning note.
Warning: Processing differs when you include INPUT within a single-line IF/THEN/ELSE statement, which is
illustrated by the following program segment:
This program produces no output because OASYS interprets the ELSE as being a part of the INPUT statement,
even though no WAITING clause is included. To avoid this, place the INPUT statement on its own line, as
shown in the following example:
177.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
,length
Description
Specifies a variable to receive the input. In the first form, if data (received
by a DATA statement) is present in an input queue, INPUT assigns the
next value to the variable var. If a DATA statement was not executed,
INPUT prompts the user for input by displaying a question mark on the
terminal.
Specifies the maximum number of characters accepted.
2012 Onsystex Corp.
INPUT
OASYS waits for the user to press ENTER before processing data input
at the keyboard. If the underscore is not included, OASYS stops
accepting input when the user enters the maximum number of characters.
Use the underscore parameter to allow the user to backspace after
entering the maximum number of characters. For example, if you specify
INPUT X,5_, the user can backspace to modify the entry after entering
five characters.
INPUT Parameters
Parameter
Description
195
177.4 Examples
In the following example, the program segment reads the first value established by the DATA statement and
assigns it to the variable TEST. In this case, the value 10 is read.
In the next example, the program statement prints the prompt Enter name:. The INPUT statement then enables
the user to enter any number of characters, stopping only when the user presses ENTER. The first 10 characters
the user enters are assigned to the variable NAME.
In the next example, the INPUT statement with the -1 parameter checks the type-ahead buffer. If S.FLAG is 0, the
buffer is empty. If it is 1, the buffer contains data. In the latter case, OASYS prints the current value of RECS.
PROCESSED.
In the next example, the user has 30 seconds to input data. Otherwise, the program prints No input within 30
2012 Onsystex Corp.
196
seconds.
178 INPUT @
Enter topic text here.
178.1 Syntax
INPUT @ (col,row | option) [ , | : ] var [,length] [ _ ] [mask] [{FOR | WAITING} time.expr] [UNFILTERED]
[THEN statements | ELSE statements]
178.2 Description
The OASYS Basic INPUT @ command places the cursor at a specific location on the terminal screen and prompts
the user for input. INPUT @ supports multibyte languages.
Tip: The OASYS Basic @ function also positions the cursor on the terminal screen, but does not accept input as
does INPUT @.
If INPUT @ is successful, OASYS sets @SYSTEM.RETURN.CODE to 0. If unsuccessful (the INPUT @
statement with a FOR or WAITING clause timed out), OASYS sets @SYSTEM.RETURN.CODE to -1.
178.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
col,row
Specifies the column and row on the screen at which the cursor is to be
placed for input.
Normally, when you type a value and press ENTER in response to an
INPUT statement, OASYS issues a line feed. The : parameter inhibits
this line feed.
Specifies a variable to receive the input data.
Specifies the maximum number of characters accepted.
INPUT @ Parameters
var
,length
Parameter
_
Description
OASYS waits for you to press ENTER before processing data input at
the keyboard. If you do not use the underscore parameter, OASYS
stops accepting input when you exceed the maximum number of
characters.
INPUT @
mask
FOR | WAITING
time.expr
UNFILTERED
THEN statements |
ELSE statements
197
178.4 Examples
The following example is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. Notice that the DISPLAY command is combined with the OASYS Basic @ function
to clear the screen and display messages. Then INPUT @ accepts the users response (a corrected price).
Later in the same sample program, the @ function is again combined with DISPLAY to paint the screen with
prompts. After all prompts have been displayed, INPUT @ returns the cursor to the end of the first line,
accepting input on that line before moving to the end of the next. In this manner, it accepts input at the end of
each line in turn.
198
OASYS
TIMEOUT For information, see the OASYS Commands Reference.
179 INPUTCLEAR
INPUTCLEAR is a synonym for the CLEARINPUT command. For more information, see CLEARINPUT.
179.1 Synonym
CLEARINPUT
180 INPUTERR
Enter topic text here.
180.1 Syntax
INPUTERR error.expr
180.2 Description
The OASYS Basic INPUTERR command displays an error message at the bottom line of the terminal screen.
error.expr can be any valid OASYS Basic statement, including a literal string enclosed in quotation marks.
INPUTERR
199
Tip: Use INPUTERR to prompt for errors when soliciting data with an INPUT statement.
The next INPUT command erases previous error messages printed on the bottom line of the screen. The OASYS
Basic program must control the movement of the cursor so it does not enter the bottom line.
Note: INPUTERR sends output to the screen regardless of PRINTER on/off status.
180.3 Example
In the following example, the program segment prints an error message at the bottom of the screen if the input
does not match the pattern mask:
181 INPUTIF
Enter topic text here.
181.1 Syntax
INPUTIF var [THEN statements] [ELSE statements]
181.2 Description
The OASYS Basic INPUTIF command retrieves input from the type-ahead buffer and assigns the input to a
variable.
181.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
THEN statements
ELSE statements
Description
Specifies the target variable for input data.
Executes statements if data is available in the type-ahead buffer.
Executes statements if data is not available in the type-ahead
buffer.
200
INPUTIF Parameters
182 INPUTNULL
Enter topic text here.
182.1 Syntax
INPUTNULL 'expr'
182.2 Description
The OASYS Basic INPUTNULL command enables you to change the default INPUTNULL character from the
default, underscore, to any other single character. When you enter the INPUTNULL character in response to an
INPUT or INPUT @ prompt, OASYS stores an empty string in place of the character entered. expr specifies the
character to serve as the INPUTNULL character for this session.
Note: You must enclose expr in quotation marks.
182.3 Example
In the following example, the pound sign (#) is set as the new INPUTNULL character:
The preceding program segment results in the following output when user input is an underscore character:
183 INPUTTRAP
Enter topic text here.
INPUTTRAP
201
183.1 Syntax
INPUTTRAP string.expr GOSUB label [:] [,label [:]]
INPUTTRAP string.expr GOTO label [:] [,label [:]]
183.2 Description
The OASYS Basic INPUTTRAP command sets a trap for a particular character or characters in a program.
INPUTTRAP enables you to specify characters which, if entered at an INPUT or INPUT @ statement, will branch
to another statement label.
183.3 Parameters
The following table describes each parameter of the syntax.
Parameter
string.expr
GOSUB
GOTO
label
Description
Specifies the user input upon which to branch to another statement label. To
set a trap for both uppercase and lowercase characters, use the following
pattern INPUTTRAP Xx, as in the following: INPUTTRAP Aa GOSUB
10,10.
These keywords direct program execution to execute or branch to a specified
label in the program.
GOSUB ensures that program execution returns to the statement below the
subroutine call.
GOTO is a branch only, and does not return processing to the calling routine.
These keywords operate just like the commands of the same names. For
more information about the GOTO and GOSUB commands, see their entries
in this manual.
Specifies the label to which to branch.
INPUTTRP Parameters
183.4 Example
In the following example, the program statement performs a GOSUB to label ASUB if the user enters H or to label
BSUB if the user enters B:
184 INS
Enter topic text here.
202
184.1 Syntax
INS expr BEFORE dyn.array<attrib.expr[,val.expr [,subval.expr]]>
184.2 Description
The OASYS Basic INS command inserts an expression with the appropriate delimiter before the specified
attribute, value, or subvalue mark in a dynamic array.
Note: OASYS does not insert a delimiter at the end of the array.
184.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
dyn.array<attrib.
expr,val.expr,
subval.expr>
184.4 Examples
In the following example, the program segment inserts Zelda, with a new attribute mark, before the second
attribute:
In the next example, the program segment inserts Stephen at the end of the array because val.expr is -1:
INSERT
203
185 INSERT
Enter topic text here.
185.1 Syntax
INSERT(dyn.array.expr,attrib.expr,val.expr, subval.expr, insert.expr)
185.2 Description
The OASYS Basic INSERT function inserts an expression (with its delimiter) before or after the specified
attribute, value, or subvalue mark in a dynamic array.
There is no short form for the INSERT function. However, you can append data by using the short version of the
REPLACE function.
185.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.expr,
Specifies a dynamic array and attribute, value, and subvalue of that
attrib.expr, val.expr dynamic array at which to insert the expression. For more information
, subval.expr,
about the type of insertions available, see the following table.
insert.expr
Specifies the string to insert.
INSERT Parameters
Elements in dyn.array.expr,attrib.expr,val.expr, and subval.expr can be any of the following three types.
If the element is:
then insert expr:
a positive number
after delimiter, before data.
-1 (attrib.expr,val.expr, subval.expr)
after the position indicated.
0 (val.expr, subval.expr)
at the next higher level.
Determining Insertion Points
185.4 Examples
In the following example, the program statement inserts HARRY at the end of the values in attribute 2:
In the next example, the program statement inserts HARRY in the first value of attribute 2:
In the next example, the program statement inserts HARRY in the first subvalue of the first value of attribute 2:
In the next example, the program segment specifies Alias in the second attribute position:
204
When you execute this program segment, OASYS inserts Alias in the second attribute position:
186 INT
Enter topic text here.
186.1 Syntax
INT(num.expr)
186.2 Description
The OASYS Basic INT function returns the integer value of numeric expression num.expr.
Note: This function does not round num.expr, but truncates decimals.
186.3 Example
In the following example, the program segment prints 1, which is the integer part of the number 1.734:
187 ISMB
Enter topic text here.
187.1 Syntax
ISMB()
187.2 Description
The OASYS Basic ISMB function returns a code indicating whether the currently installed language is made up
of a single-byte or multibyte character set.
This function returns 0 to indicate a single-byte character set, or 1 for a multibyte character set. For example, if
you execute the ISMB function in a OASYS session for which the language is English, the function returns 0. If
2012 Onsystex Corp.
ISMB
205
you execute this function in a OASYS session for which the language is Japanese, the function returns 1.
188 ISNV
Enter topic text here.
188.1 Syntax
ISNV(expr)
188.2 Description
The OASYS Basic ISNV function tests an expression for the null value. If expr is the null value, this function
returns a code of 1. If the expression is not null, or if it contains a null value as well as other characters, this
function returns a code of 0.
Note: The oasconfig parameter NULL_FLAG must be on for a program that contains ISNV to compile. With this
flag on, the null value represents an unknown value (represented by @NULL in OASYS Basic programs), as
opposed to an empty string (represented as ). Onsystex recommends that you use @ variables to represent
OASYS delimiters and the null value because the ASCII value used to represent these characters can vary with
language group.
188.3 Examples
The following program example demonstrates testing for the null value in a variable:
The following program uses the function ISNV to determine if a string consists of the null value:
This program produces the following results. Notice that ISNV executed on a string containing the null value and
other characters produces a negative result (0).
206
189 ISNVS
Enter topic text here.
189.1 Syntax
ISNVS(dynamic.array)
189.2 Description
The OASYS Basic ISNVS function tests dynamic array elements to see if any of them is the null value. This
function is meaningful only when null value handling is on. It returns an array with 0 or 1 in each element. If the
array element is the null value, this function returns a code of 1. If the element is not null, or if it contains the null
value as well as other characters, this function returns a code of 0.
Note: The oasconfig parameter NULL_FLAG must be on for a program that contains ISNVS to compile. With
this flag on, the null value represents an unknown value (represented BY @NULL in OASYS Basic programs),
as opposed to an empty string (represented as ). Onsystex recommends that you use @ variables to represent
OASYS delimiters and the null value because the ASCII value used to represent these characters can vary with
language group.
189.3 Example
ISNVS
207
190 ITYPE
Enter topic text here.
190.1 Syntax
ITYPE(itype.expr)
190.2 Description
The OASYS Basic ITYPE function enables a OASYS Basic program to execute a OASYS virtual attribute from the
dictionary of a OASYS file. The value of the function is the same as if it were run using UniQuery or OASYS SQL.
Note: ITYPE generally requires you to open both the dictionary and data portions of the file. Before you use
this function, you must compile the dictionary of the file by using the ECL COMPILE.DICT or CD command.
In most cases, you also must assign the @ID and @RECORD variables. These variables resolve the value of the
ITYPE function. However, if neither the ID of the file nor the data from the record is used in the ITYPE, you do
not need to assign these variables.
Note: Conversion or formatting codes in the dictionary record of the virtual attribute does not affect the value
ITYPE returns.
190.3 Examples
The following virtual attribute exists in the dictionary file of the demonstration database file ORDERS:
The following program segment opens both the ORDERS file and the dictionary of the ORDERS file, then reads
the compiled virtual attribute into the program variable GRAND_TOTAL. After prompting for an order number
and reading the record, the virtual attribute is evaluated with the ITYPE function. In this case, it performs a
summation on the value of GRAND_TOTAL in @RECORD. ITYPE does not invoke the conversion and format
2012 Onsystex Corp.
208
OASYS
COMPILE.DICT For information, see the OASYS Commands Reference.
Virtual attributes For information, see Using OASYS.
191 LE
Enter topic text here.
191.1 Syntax
expr1 LE expr2
191.2 Synonyms
#>, =<, <=,
191.3 Description
The OASYS Basic LE relational operator tests whether expression expr1 is less than or equal to expr2.
expr1 and expr2 can be any valid OASYS Basic expressions, variables, strings, or literals.
Relational operators make the comparisons that direct program flow in conditional statements like the following:
LE
209
191.4 Example
In the following example, the program segment tests whether A is less than or equal to B. Because A is less than
B, the message Less than or equal to prints.
192 LEN
Enter topic text here.
192.1 Syntax
LEN(str.expr)
192.2 Description
The OASYS Basic LEN function returns the length of character expression str.expr. LEN supports multibyte
languages.
With null value handling on, the null value has a length of one byte.
192.3 Examples
In the following example, the program segment displays 14, the length of the string NAME:
The following figure illustrates a string that indicates below each character the number of bytes required to
store that character. The string contains eight bytes. Therefore, LEN would return 8 for this string.
210
193 LENS
Enter topic text here.
193.1 Syntax
LENS(dyn.array)
193.2 Description
The OASYS Basic LENS function returns the length of the values within each element of a dynamic array. LENS
supports multibyte languages.
With null value handling on, the null value has a length of one byte.
193.3 Example
In the following example, the program segment creates a new array ARRAY1, which contains the length of each
element of ARRAY:
194 LES
Enter topic text here.
194.1 Syntax
LES(array1,array2)
LES
211
194.2 Description
The OASYS Basic LES function compares each value in array1 to its corresponding value in array2. OASYS
returns an array with 1 in each position where the value in array1 is less than or equal to the value in the
corresponding value in array2, and 0 in each position when the value in array1 is greater than that in array2.
194.3 Example
In the following example, the program segment compares ARRAY1 to ARRAY2 and returns ARRAY3. ARRAY3
then contains 1}1}1}0}0.
195 LISTUSER
Syntax
LISTUSER()
Description
The LISTUSER function returns information about OASYS processes currently running in a dynamic array.
In the event a OASYS user session aborts through a power failure or other abnormal circumstance, OASYS
registers the aborted process as an active user, and it appears as such in the LISTUSER array. Eventually, the
cleanupd daemon will detect these processes and remove the aborted process from the user list.
Description
Sequential number OASYS assigns to each user.
System-level process ID (pid) assigned to a OASYS session.
System-level ID assigned to a user.
Login name of the user.
Type of process the user is running.
Device ID.
Time the user process started.
Date the user process started.
LISTUSER Array
Example
The following example displays the output from the LISTUSER function on UNIX:
212
Parameter
OASNO
USRNBR
UID
USRNAM E
USRTYPE
TTY
TIM E
DATE
Description
Sequential number OASYS assigns to each user.
System-level process ID (pid) assigned to a OASYS session.
System-level ID assigned to a user.
Login name of the user.
Type of process the user is running.
Device ID.
Time the user process started.
Date the user process started.
LISTUSER Array
Example
The following example displays the output from the LISTUSER function on UNIX:
Description
Sequential number OASYS assigns to each user.
Process ID of the OASYS session.
Windows ID of the user.
Login name of the user.
Type of process the user is running.
Session identifier, formed by concatenating the string pts/ and the
OASNO.
Location where the session is logged in; either Console or a valid IP
address.
The time at which the user process started.
The date on which the user process started.
LISTUSER Display Attributes
196 LN
Enter topic text here.
196.1 Syntax
LN(num.expr)
196.2 Description
The OASYS Basic LN function returns the natural base logarithm of numeric expression num.expr. This function
is the inverse of the EXP function.
196.3 Example
In the following example, the program statement assigns the natural logarithm of 12 to the variable VAL. The
result is 2.4849.
LN
213
197 LOCATE
197.1 Syntax
LOCATE element IN dyn.array<[attribute.expr [,val.expr [,subval.expr]]]>[,var] [BY search.type] SETTING
location [THEN statements END] ELSE statements END
For backward compatibility, OASYS supports the following alternate syntax:
LOCATE(element,dyn.array [,attrib.expr[,val.expr[,subval.expr]]];location [;search.type]) [THEN statements]
[END] ELSE statements
197.2 Description
The OASYS Basic LOCATE command locates an element within a dynamic array. For LOCATE to be successful,
the search string, element, must match the entire array element (including any associated lower-level elements).
LOCATE does not modify the data in the array.
Note: CUST.OPTIONS 85 changes the sort order for an array of mixed negative and positive numbers. With
CUST.OPTIONS 85 on, negative and positive numbers are sorted in numeric order regardless of sign. This is
effective for the first form of the syntax only.
197.3 Parameters
The following table describes each parameter of the syntax.
Parameter
element
dyn.array <attrib.expr ,
val.expr,subval.expr>
Description
Specifies the string to search for. element can be a variable, array
element, function, or literal.
Specifies a dynamic array and level (attribute, value, or subvalue)
to search. The search operates as follows:
The search begins at the lowest level specified.
Only the specified level is searched.
Returns the position of the located string relative to the beginning
of the search.
1 in attrib.expr causes a search starting with the first attribute in
the file.
0 in any expression is treated as 1.
If the arguments cause the search to begin beyond the end of the
dynamic array, the ELSE clause executes.
See also the LOCATE in BASICTYPEs U, P, and M table.
214
,var
BY search.type
Parameter
Description
SETTING location
Note: The syntax for BASICTYPEs P and M differs in the number of array elements you can include and the
search driven by those elements. Syntax variants for P and M are as follows:
LOCATE element IN dyn.array<attribute.expr [,val.expr]> [BY search.type] SETTING location [THEN
statements END] ELSE statements END and LOCATE(element,dyn.array [,attrib.expr[,val.expr]];location [;
search.type]) [THEN statements] [END] ELSE statements
in BASICTYPE U
no expr
attrib.expr
val.expr
in BASICTYPEs P and M
LOCATE
subval.expr
215
197.4 Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. LOCATE returns the position of the order number to be deleted.
In the following example, the program statement searches the entire array, FILMS, element by element, for the
literal string BATMAN. If the search is successful, OASYS assigns the location of the element to the variable
NDX. If OASYS does not find the string, it sets NDX to the location of the last value plus 1, and it executes the
STOP command. The LOCATE command performs the search on the attribute level.
Because the LOCATE statement compares the entire element (including associated lower-level elements), a match
will not be successful on either of the following arrays:
or
In the next example, the program segment prints BATMAN IS IN POSITION 2 IN THE ARRAY:
In the next example, the program segment searches the array FILMS, starting at attribute 2, value 2, for the
contents of the variable DEVITO. OASYS assumes the array elements are in ascending order and left-justified.
When executed on the following array, DEVITO is located in position 3 in the array at the value level, and OASYS
2012 Onsystex Corp.
216
However, in the following array, the LOCATE command does not find DEVITO, and OASYS executes the second
PRINT statement:
198 LOCK
Enter topic text here.
198.1 Syntax
LOCK resource.num {THEN statements [END] | ELSE statements [END]}
198.2 Description
The OASYS Basic LOCK command reserves a computer resource (such as a device or file) for the current user
process.
The lock is associated with resource.num, not the resource itself. Therefore, a command that does not check for
locks against the resource number will access the resource even if it is locked. For example, an installation might
assign locks 1 through 4 to four system printers. When an application needs to reserve printer 1, the application
executes LOCK 1. For lock effectiveness, all other applications must check for locks before accessing the
resource.
Resources are not automatically unlocked by the termination of the locking program. The OASYS Basic UNLOCK
or ECL QUIT commands must release them. Otherwise, you can release resources by executing the ECL CLEAR.
LOCKS command at OASYS level.
For more information about OASYS locks, see Developing OASYS Basic Applications.
198.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
resource.num
LOCK
217
198.4 Examples
In the following example, the program statement reserves resource 12 if another program is not using it. If
resource 12 is already in use, the current program suspends execution and waits until OASYS unlocks resource
12.
In the next example, the program segment locks resource 44 if it is available. If it has already been locked, the
program attempts to lock resource 45. If both resources are unavailable, the program stops.
OASYS
CLEAR.LOCKS, LIST.LOCKS, SUPERCLEAR.LOCKS, DEFAULT.LOCKED.ACTION For information, see the
OASYS Commands Reference.
199 LOOP/REPEAT
Enter topic text here.
199.1 Syntax
LOOP [statements][UNTIL expr [DO] statements][WHILE expr [DO] statements]REPEAT
LOOP {WHILE | UNTIL} expr DO statementsREPEAT
LOOP statements{WHILE | UNTIL} expr DO REPEAT
199.2 Description
The OASYS Basic LOOP/REPEAT command repeats any contained statements while or until a specified
condition is met, depending on whether you use the WHILE or UNTIL clause. statements can precede and/or
218
follow the test condition. If space permits, you can write the structure on one line. Otherwise, you can extend the
structure on as many lines as necessary. REPEAT is required and finishes the LOOP operation.
OASYS executes the first set of statements on the first entry into the loop, and then evaluates the WHILE or
UNTIL clause. If expr is true (using the WHILE keyword) or false (using the UNTIL keyword), OASYS executes
the second set of statements. If you have statements after a WHILE or UNTIL clause, the DO clause is required.
Otherwise, it is optional. When the program execution reaches REPEAT, it returns to the first set of statements.
Tip: Onsystex recommends that you construct loops that terminate based on the WHILE or UNTIL condition.
The LOOP statement is flexible enough to incorporate almost any logical progression. Use the CONTINUE
keyword to transfer control to the beginning of the next loop.
199.3 Parameters
The following table describes each parameter of the syntax.
Parameter
expr
statements
WHILE statements
UNTIL statements
Description
Specifies an expression to check to for the UNTIL or WHILE
clause.
expr can be any valid statement that includes a READNEXT
statement or LOCATE statement.
Specifies statements to execute each time the loop statement
repeats.
Specifies statements to execute if the expression in the WHILE
clause is true.
Specifies statements to execute if the expression in the UNTIL
clause is false.
LOOP/REPEAT Parameters
199.4 Examples
The following example is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. This subroutine loops until the user enters a valid order number, or Q (the prompt for
order number is already displayed on the screen).
In the next example, the program segment prints and increments POS until it reaches the value of 10:
LOOP/REPEAT
219
In the next example, the program segment prints Counting and then increments C. It then evaluates C to see if it
is less than eight, and if so, executes the second statement. On the eighth iteration, the program executes the top
statement and the loop stops because the condition (C > 8) is met. The program continues execution at the
statement following REPEAT. The program does not execute the second statement on the final iteration.
200 LOWER
200.1 Syntax
LOWER(dyn.array.expr)
200.2 Description
The OASYS Basic LOWER function converts all attribute marks to value marks, and, in a dynamic array, it
converts all value marks to subvalue marks.
200.3 Example
In the following example, the program segment lowers the dynamic array D.STR:
220
201 LT
Enter topic text here.
201.1 Syntax
expr1 LT expr2
201.2 Synonym
<
201.3 Description
The OASYS Basic LT relational operator tests whether expression expr1 is less than expr2.
expr1 and expr2 can be any valid OASYS Basic expressions, variables, strings, or literals.
Relational operators make the comparisons that direct program flow in conditional statements such as the
following:
201.4 Example
In the following example, the program segment tests whether A is less than B. Because A is less than B, the
message Less than prints.
LT
221
202 LTS
Enter topic text here.
202.1 Syntax
LTS(array1,array2)
202.2 Description
The OASYS Basic LTS function compares each element in array1 to its corresponding value in array2. OASYS
returns an array with 1 in each position where the value in array1 is less than the value in the corresponding
position in array2, and 0 in each position for values in array1 that are greater than those in array2.
202.3 Example
In the following example, the program segment compares ARRAY1 to ARRAY2 and returns ARRAY3. ARRAY3
then contains 1}1}0}0}0.
203 MAT
203.1 Syntax
MAT dim.array = expr
MAT dim.array = MAT dim.array2
203.2 Description
The first form of the OASYS Basic MAT command assigns new values to all elements of a dimensioned array
based on an expression.
The second form assigns the contents of a dimensioned array to another dimensioned array.
If you assign a dimensioned array the values of a second dimensioned array, the assignment proceeds from
element to element in consecutive order. The program assigns the first element of the first array to the first
element of the second array, then assigns the second element to the second element of the second array, and so
on. The two arrays do not have to match in configuration of dimensions, but must contain the same number of
elements. OASYS does not alter the second dimensioned array in the assignment process.
2012 Onsystex Corp.
222
Use the DIM command to dimension all arrays before you assign new values to the elements. You can place
MAT in any looping structure and assign the elements with a variable or function.
203.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dim.array
expr
dim.array2
Description
Specifies a dimensioned array to receive new values.
Specifies the value to assign to the array elements. expr can be any OASYS
Basic expression.
expr can be an empty string, a formula, a single value, a literal string, or a
function.
Specifies a dimensioned array from which to assign values.
MAT Parameters
203.4 Examples
In the following example, the program segment assigns 1.5 to all elements of the array FEES:
In the next example, the program segment assigns the values in dimensioned array FEE2 to the dimensioned array
FEE1. Note the differing dimensions but the same number of elements in the two matrices.
MAT
223
204 MATBUILD
Enter topic text here.
204.1 Syntax
MATBUILD dyn.array FROM dim.array [,start.num [,end.num [USING delim]]]
204.2 Description
The OASYS Basic MATBUILD command generates a dynamic array from a dimensioned array based on specified
starting and ending positions and the delimiter given. The dimensioned array can be multidimensional. The
statement retrieves elements from the multidimensional array according to the order in which its elements are
stored.
204.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array
FROM dim.array
Description
Specifies the dynamic array to be created.
Specifies the dimensioned array from which to build the dynamic
array.
MATBUILD Parameters
Parameter
Description
,start.num
,end.num
USING delim
224
204.4 Examples
In the following example, A is a dimensioned array with five elements:
205 MATCH
Enter topic text here.
205.1 Syntax
var MATCH "[~] len [X, A, N] [text]"
205.2 Synonym
MATCHES
205.3 Description
The OASYS Basic MATCH or MATCHES function determines if a variable matches a specific pattern of
characters, numbers, or a literal string. If var matches the pattern, MATCH or MATCHES returns 1. If var does
not match the pattern, MATCH or MATCHES returns 0.
Tip: You can mix codes and literal strings. To differentiate between the two, enclose the literal in single
quotation marks within the larger pattern, which is enclosed in double quotation marks.
MATCH
225
205.4 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
~
len
X
Parameter
Description
text
Specifies a literal string to search for. Enclose this literal text within single
quotation marks if combined with a pattern (made up of X, A, and N).
MATCH Parameters (continued)
205.5 Examples
In the following example, the program segment determines if the variable SSN is a valid social security number:
The following program accepts as input a pattern to match and a string to search:
In the following test executions of the preceding program, the user tests for a string that consists of three
alphabetic characters followed by the literal 3A. The literal (3A) is enclosed in quotation marks to differentiate
it from the pattern 3A.
226
206 MATCHFIELD
Enter topic text here.
206.1 Syntax
MATCHFIELD(str.expr,"[~] {len [X | ,A | ,N]} [text]", field.expr)
206.2 Description
The OASYS Basic MATCHFIELD function returns a substring that matches a pattern or literal. If no match is
made, OASYS returns an empty string. MATCHFIELD supports multibyte languages.
You can mix the codes and a text string to search for specific patterns separated by characters.
With null value handling on, if a function encounters the null value in a parameter when a number is expected (
field.expr), a warning message displays and OASYS Basic uses 0.
206.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
str.expr
Specifies the variable to compare with the M ATCH expression.
~
Inverses the pattern. To match 4N, a string must contain four numeric
characters. To match ~4N, a string must contain four characters that are not
numeric.
len
Specifies the number of characters to match.
X
Specifies that characters can be of any data type.
A
Specifies that only alphabetic characters match the pattern.
MATCHFIELD Parameters
Parameter Description
N
text
field.expr
MATCHFIELD
227
206.4 Examples
In the following example, the program segment returns the value 56 because the entire string matches the
specified criteria, and the third field contains the number 56:
In the next example, the program segment searches the string and returns the second and fourth fields and prints
99922:
207 MATPARSE
Enter topic text here.
207.1 Syntax
MATPARSE dim.array FROM str.expr, delim.expr
207.2 Description
The OASYS Basic MATPARSE command distributes elements of a delimited string or dynamic array to
consecutive elements of a dimensioned array. Delimiters can be the standard OASYS delimiters or any other
ASCII character.
When you specify an alternate delimiter, OASYS returns a two-dimensional array. The delimited string is placed
in the first dimensioned array element, and the delimiter is placed in the second element. When OASYS
encounters two delimiters in a row, both are placed in the first element.
Note: BASICTYPEs P and R do not support the 0,0 element in dimensioned arrays. If more elements are
delimited in the string than can be placed in the dimensioned array, a runtime error results and data is lost.
207.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dim.array
str.expr
delim.expr
Description
Specifies the target dimensioned array.
Specifies a delimited string to place in the dimensioned array.
Specifies the delimiter to use for parsing str.expr. You can use any ASCII
character including commas or spaces.
MATPARSE Parameters
228
Description
n
0
207.4 Examples
In the following example, the program segment fills the dimensioned array ALPHA with consecutive characters
from a literal string. An empty string is the delimiter, causing one character to be assigned to each dimensioned
array cell. In this case, the value returned by the INMAT function would be 7.
In the next example, the program segment dimensions the dimensioned array T and then fills it with data from a
dynamic array. The delimiter specified is the attribute mark, so each attribute is assigned to consecutive elements
of the array. Note that the string ITEM has five elements, but the array is dimensioned with four elements.
After the MATPARSE command, the INMAT function is 0 and the value of the zero element T(0) is 443.
MATREAD
229
208 MATREAD
Enter topic text here.
208.1 Syntax
MATREAD dim.array [FROM [file.var,]record.ID.expr [ON ERROR statements] {THEN statements [END] | ELSE
statements [END]}
208.2 Description
The OASYS Basic MATREAD command assigns the values found in successive attributes of a record to
corresponding elements of a dimensioned array - regardless of lock status.
You must use the DIM command to create a dimensioned array before you execute MATREAD.
Note: This command does not check for locks. If you are operating in a multiuser environment, you must use
record locks to prevent users from overlaying data updated by others. For more information about the OASYS
Basic record locking, see Developing OASYS Basic Applications.
208.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dim.array
FROM file.var,
record.ID.expr
Parameter
Description
Specifies the dimensioned array into which the values are read.
Specifies the file from which to read.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal READ error occurs.
A default file is one for which no file variable is assigned in the
OPEN statement.
Specifies the record from which to read.
MATREAD Parameters
Description
ON ERROR statements
230
Value
Meaning
n
0
Note: BASICTYPEs P and R do not support the 0,0 element. If more attributes are read from the file than can be
placed in the dimensioned array, a runtime error results and data is lost.
208.4 Examples
In the following example, the program segment reads the record with ID NAMES from the CUSTFILE, and assigns
the elements to the dimensioned array TEST. If the program does not find the record, it assigns the value 0 to the
variable FOUND.
In the next example, the program segment reads the record with ID NAMES and assigns the data from the record
to the dimensioned array TEST:
In the next example, the MATREAD statement includes multiline THEN and ELSE clauses:
209 MATREADL
Enter topic text here.
209.1 Syntax
MATREADL dim.array FROM [file.var,]record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
statements [END] | ELSE statements [END]}
MATREADL dim.array FROM [file.var,]record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
statements [END] | ELSE statements [END]}
MATREADL
231
209.2 Description
The OASYS Basic MATREADL command assigns the values found in successive attributes of a record to
corresponding elements of a dimensioned array. MATREADL checks for locks and will not read a record locked
with an exclusive (U) lock. If the record is available, MATREADL reads and sets a shared (L) lock on it.
Note: OASYS Basic locks are advisory only. They prevent access by other lock-checking commands only. For
more information about OASYS Basic locks, see Developing OASYS Basic Applications.
209.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dim.array
FROM file.var,
Specifies the dimensioned array into which the values are read.
Specifies the file from which to read.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal READ error occurs.
A default file is one for which no file variable is assigned in the
OPEN statement.
Specifies the record from which to read the attributes.
record.ID.expr
MATREADL Parameters
Parameter
Description
ON ERROR statements
Description
The number of attributes loaded into the array.
The array was too small to contain all attributes in the record. The excess data
(including delimiters) is placed in the zero element.
INMAT Function Return Values
232
Note: BASICTYPEs P and R do not support the 0,0 element. If OASYS reads more attributes from the file than it
can place in the dimensioned array, a runtime error results and data is lost.
209.4 Example
In the following example, the program segment reads a tape record with the ID specified in TAPE.ID from the
TAPES.FILE. If the program finds the record, it transfers control to the subroutine TAPE.PROCESS. Otherwise,
the program displays a message and aborts. If the record is locked with an exclusive lock, the program does not
execute the subroutine. Instead, it displays the message RECORD LOCKED and waits for the lock to be
released.
OASYS
DEFAULT.LOCKED.ACTION For more information, see the OASYS Commands Reference.
210 MATREADU
Enter topic text here.
210.1 Syntax
MATREADU dim.array FROM [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
statements [END] | ELSE statements [END]}
MATREADU dim.array FROM [file.var,] record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
statements [END] | ELSE statements [END]}
210.2 Description
The OASYS Basic MATREADU command assigns the values found in successive attributes of a record to
corresponding elements of a dimensioned array. MATREADU checks for locks and will not read a locked record.
If the record is available, MATREADU reads and sets an exclusive (U) lock on it.
Note: OASYS Basic locks are advisory only. They prevent access by other lock-checking commands only. For
more information about OASYS Basic locks, see Developing OASYS Basic Applications.
BASICTYPEs P and R do not support the 0,0 element. If OASYS reads more attributes from the file than it can
place in the dimensioned array, a runtime error results and data is lost.
2012 Onsystex Corp.
MATREADU
233
210.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dim.array
FROM file.var
Specifies the dimensioned array into which the values are read.
Specifies the file from which to read.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal READ error occurs.
A default file is one for which no file variable is assigned in the
OPEN statement.
Specifies the record from which to read the attributes.
Specifies statements to execute if the M ATREADU statement
fails with a fatal error because the file is not open, an I/O error
occurs, or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
Specifies statements to execute if the record is locked by another
user. If you do not specify a LOCKED clause, the program waits
until the lock on the record is released. You can place the
LOCKED clause after the FROM clause.
Use the ECL command DEFAULT.LOCKED.ACTION BELL
to beep the terminal while waiting for the record to be unlocked.
THEN executes if the read is successful. END is required to
terminate multiline THEN statements.
ELSE executes if the read is not successful or the record (or ID)
does not exist. END is required to terminate multiline ELSE
statements.
MATREADU Parameters
record.ID.expr
ON ERROR statements
LOCKED statements
Description
n
0
210.4 Examples
In the following example, the program segment reads the record with ID NAMES from the CUST file. Because
no LOCKED clause is provided, the program waits for access if the record is locked by another user.
In the next example, the program segment reads the record with the ID CUST.ID and assigns each attribute to
successive elements in the dimensioned array CUST.REC. If the record is found, OASYS executes the THEN
clause. If the record is locked, OASYS displays RECORD LOCKED and waits for the lock to be released. If the
2012 Onsystex Corp.
234
record is not found, OASYS displays RECORD NOT FOUND FOR CUSTOMER and the customer ID.
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
211 MATWRITE
Enter topic text here.
211.1 Syntax
MATWRITE dim.array {ON | TO file.var,} record.ID.expr [ON ERROR statements]
211.2 Description
The OASYS Basic MATWRITE command writes successive elements of a dimensioned array to the
corresponding attributes of a record.
If the dimensioned array size exceeds the number of attributes in the target record, the MATWRITE command
does not write the trailing spaces. If the 0 element is not empty, the command writes the contents of the element
after the final element in the record (as element N+1).
Note: This command must be preceded by MATREADU or another locking command to prevent the type of
inconsistency that results when multiple users access files at the same time. For more information, see
Developing OASYS Basic Applications.
211.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dim.array
Description
Specifies the dimensioned array from which to assign the values
read to the successive attributes of the record record.ID.expr.
You must name and dimension an array before you can use it in
the M ATWRITE statement.
2012 Onsystex Corp.
MATWRITE
235
MATWRITE Parameters
Parameter
Description
ON | TO file.var,
Specifies the file on which to write the record. You must specify
an ON or TO clause.
record.ID.expr
Specifies the record on which to write the attributes.
ON ERROR statements Specifies statements to execute if M ATWRITE fails with a fatal
error because the file is not open, an I/O error occurs, or OASYS
cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
MATWRITE Parameters (continued)
Description
The record was locked before M ATWRITE executed. You are in danger of simultaneously updating a record being updated by another user.
The record was not locked before M ATWRITE executed.
-2
211.4 Example
In the following example, the program segment writes the dimensioned array RECEIPTS to the file REC87 as a
record with ID RENTALS:
212 MATWRITEU
Enter topic text here.
212.1 Syntax
MATWRITEU dim.array {ON | TO} [file.var,] record.ID.expr [ON ERROR statements]
212.2 Description
The OASYS Basic MATWRITEU command writes successive elements of a dimensioned array to the
corresponding attributes of a specified record. MATWRITEU does not release locks set by READU, READVU,
or MATREADU statements.
236
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
212.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dim.array
Specifies the dimensioned array from which to assign the values read
to the successive attributes of the record record.ID.expr.
You must name and dimension an array before you can use it in the
M ATWRITE statement.
Specifies the target file. You must specify an ON or TO clause.
Specifies the target record.
Specifies statements to execute if M ATWRITEU fails with a fatal
error because the file is not open, an I/O error occurs, or OASYS
cannot find the file.
If you do not specify the ON ERROR clause and a fatal error occurs,
the program terminates.
MATWRITEU Parameters
ON | TO file.var,
record.ID.exp
ON ERROR
statements
Meaning
The record was locked before M ATWRITEU executed. You are in danger of
simultaneously updating a record being updated by another user.
The record was not locked before M ATWRITEU executed.
STATUS Function Return Values
-2
212.4 Example
In the following example, the program statement writes the dimensioned array NEW.CLIENTS to the file CLIENTS
as a record with an ID of 050887. If the record is locked, OASYS maintains the lock.
213 MAXIMUM
Enter topic text here.
MAXIMUM
237
213.1 Syntax
MAXIMUM(dyn.array.var)
213.2 Description
The OASYS Basic MAXIMUM function returns the largest numeric value found in a dynamic array. This function
ignores nonnumeric elements. If the array you specify contains only nonnumeric elements, MAXIMUM returns
an empty string. If an element is empty, OASYS treats it as 0.
OASYS treats all system marks (attribute, value, and subvalue marks) indiscriminately. That is, any value between
two marks of any kind is taken as an element with respect to this function.
213.3 Examples
In the following example, the program segment prints 22:
In the next example, the program segment prints 0 because W contains an empty element and no other numeric
elements exist:
214 MBLEN
Enter topic text here.
214.1 Syntax
MBLEN (str.expr)
214.2 Description
The OASYS Basic MBLEN function returns the number of bytes in the first character of a string.
214.3 Example
The following figure illustrations a string that indicates below each character the number of bytes required to
display that character. MBLEN returns 2 for this string, which indicates that the first character is made up of two
bytes.
238
215 MDPERFORM
Enter topic text here.
215.1 Syntax
MDPERFORM str.expr [CAPTURING, dyn.array.var] [RETURNING, dyn.array.var] [RTNLIST int.expr]
[PASSLIST int.expr] [PASSCOM]
MDPERFORM str.expr [RETURNING, dyn.array.var] [CAPTURING, dyn.array.var] [RTNLIST int.expr]
[PASSLIST int.expr] [PASSCOM]
215.2 Description
The OASYS Basic MDPERFORM command executes various OASYS commands, sentences, or paragraphs
within a OASYS Basic program while transferring lists to and from the executed commands.
You can nest MDPERFORM. For example, in program A an MDPERFORM statement, which has a CAPTURING
var1 clause, invokes program B. Program B contains a second MDPERFORM statement that also has a
CAPTURING var2 clause. The output of programs A and B is sent to var1 and var2 respectively.
You can nest only two MDPERFORM statements. To increase the number of nested levels:
For the entire system Enter a higher number for the oasconfig file variable MAX_CAPT_LEVEL.
For this process only Enter a higher number for the environment variable MAX_CAPT_LEVEL.
Note: MDPERFORM does not pass select lists unless you explicitly specify them. In this way, you maintain full
control and protection over them.
STACKCOMMON
The ECL STACKCOMMON command makes use of common areas more flexible, although it requires additional
memory. STACKCOMMON settings have the following effects:
If STACKCOMMON is off when one program executes another, the unnamed common is passed to the
executed program and back to the executing program.
If STACKCOMMON is on when one program executes another program, unnamed common is not passed to
the program you execute. Instead, unnamed common is saved, and the unnamed common of the called program
is initialized to 0. When control is passed back to the calling program, unnamed common is restored to its value
before the program call. Unnamed common is never passed to a phantom program.
Note: STACKCOMMON is always on in BASICTYPEs P and M. The default setting for STACKCOMMON is off
in BASICTYPEs R and U.
2012 Onsystex Corp.
MDPERFORM
239
215.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
Parameter
Description
RTNLIST int.expr The RTNLIST clause must evaluate to an integer 09, designating the
list to return to the calling program. You can use the resulting list with
subsequent READNEXT statements or in the PASSLIST clause of a
M DPERFORM statement. If you do not include an expression after
RTNLIST, the generated list replaces the contents of list 0. If you do
not specify RTNLIST, the M DPERFORM command does not return a
list.
PASSLIST int.expr The PASSLIST clause must evaluate to an integer 0, 1, or 2, designating
the select list to be sent to the called program. If you do not specify int.
expr, OASYS assumes list 0.
The passed list can be the result of previous SELECT or GETLIST
commands, or the RTNLIST clause of an M DPERFORM statement.
PASSCOM
This parameter is provided for backward compatibility for releases
before 3.1.
MDPERFORM Parameters (continued)
215.4 Examples
In the following example, the program segment lists all the items in the VOC file and returns the result in select list
2:
In the next example, the program segment performs a selection on the CUSTOMER file, passes the result back in
select list 1, and then sorts the result:
240
In the next example, the program segment builds different commands based on conditions generated by
MDPERFORM. According to the value of input_var, one of three UniQuery commands is executed.
In the next example, the program segment performs the command stored in cmd3, passing the list specified by
list_var, and sends output to a dynamic array cpt_var:
OASYS
STACKCOMMON For more information, see the OASYS Commands Reference.
216 MINIMUM
Enter topic text here.
216.1 Syntax
MINIMUM(dyn.array.var)
216.2 Description
The OASYS Basic MINIMUM function returns the smallest numeric element found in a dynamic array.
OASYS ignores nonnumeric elements with this function. If dyn.array.var contains only nonnumeric elements, the
function returns an empty string. If an array element is empty, it is treated as 0.
All system marks (attribute, value, and subvalue marks) are treated indiscriminately. That is, any value between
two marks is taken as an element.
MINIMUM
241
216.3 Examples
In the following example, the program segment prints 2:
In the next example, the program segment assigns U an empty string because V contains only nonnumeric
elements:
217 MOD
Enter topic text here.
217.1 Syntax
MOD(num.expr1, num.expr2)
217.2 Synonym
REM
217.3 Description
The OASYS Basic MOD and REM functions return the remainder of the division of num.expr2 into num.expr1.
These functions divide integers and decimals. The sign of the result is the same as that of num.expr1.
The formula used by MOD and REM is:
where x and y are numeric expressions. The first expression, x, is divided by y, and INT truncates the result.
OASYS multiplies the resulting integer by y, and subtracts the result from the value of x.
Note: The value of num.expr2 cannot be 0.
217.4 Example
In the following example, the program segment assigns to Z the remainder of the division of Y into X. In this case,
the remainder is 2.
242
218 NE
Enter topic text here.
218.1 Syntax
expr1 NE expr2
218.2 Synonyms
#, <>, ><
218.3 Description
The OASYS Basic NE relational operator tests whether expression expr1 is not equal to expr2.
expr1 and expr2 can be any valid OASYS Basic expressions, variables, strings, or literals.
Tip: You can also use the # symbol to negate other relational operators. For example, the following statement
uses the # symbol to negate the > symbol. In this case, if X is not greater than Y, the program branches to label
1000 .
218.4 Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. In the first statement, if the variable NEW.PRICE is not equal to an
empty string, the variable is written to the seventh element in array ORDER.REC.
219 NEG
Enter topic text here.
NEG
243
219.1 Syntax
NEG(expr)
219.2 Description
The OASYS Basic NEG function changes the value of expr to its opposite sign. If the value of expr is positive,
NEG returns a negative value. If the value of expr is negative, NEG returns a positive value.
219.3 Example
In the following example, the program segment changes the value of variable A to a negative number and prints 1:
220 NES
Enter topic text here.
220.1 Syntax
NES(array1, array2)
220.2 Description
The OASYS Basic NES function compares each value in array1 to its corresponding value in array2. OASYS
returns an array with a one in each position where the value in array1 is not equal to the value in the
corresponding position in array2, and a zero in each position for values that are equal to array2.
220.3 Example
In the following example, the program segment compares ARRAY1 to ARRAY2 and returns ARRAY3. ARRAY3
now contains 0}0}0}1}1.
221 NOCONVERT
Enter topic text here.
244
221.1 Syntax
NOCONVERT {OFF | ON}
221.2 Description
The OASYS Basic NOCONVERT command controls the conversion of the special character CHAR(0). The
following OASYS Basic commands read and write non-OASYS files or tapes and convert CHAR(0) to CHAR(128)
on input. They also convert CHAR(128) to CHAR(0) on output. This can cause problems under some circumstances, especially if you use the character CHAR(128) in an application or in stored data. NOCONVERT
provides a way of switching
the conversion OFF or ON. The default is OFF.
The following OASYS Basic commands convert CHAR(0) and CHAR(128) when NOCONVERT is turned on:
OSBREAD, OSBWRITE, OSREAD, OSWRITE, READT, WRITET
Note: The PRINT and CRT functions do not work with strings that contain CHAR(0).
Warning: Do not use OASYS Basic READ and WRITE commands to open or modify binary data in DIR-type files
(for example, BP). Doing so can corrupt data in the file. Instead, use OSREAD or OSBREAD after executing the
OASYS Basic NOCONVERT command.
The following functions work with strings containing CHAR(0), regardless of the setting of the NOCONVERT
command:
Assignment (X = Y)
Bracket function ([])
Substring assignment (A[1,3] = B)
String concatenation (A:B)
CHAR
CONVERT
COUNT
DCOUNT
INDEX
LEN
SEQ
SWAP
222 NOT
Enter topic text here.
222.1 Syntax
NOT(expr)
222.2 Description
The OASYS Basic NOT Boolean operator inverts the logical result of the argument expr. If the expression is true,
the function returns 0 (false). If the expression is not true, the function returns 1 (true).
NOT
245
222.3 Example
In the following example, the program segment compares X to Y (false because X is not greater than Y) and
inverts the result, evaluating to true instead. Next, the THEN statement executes, sending program control to the
label specified by RETRY.
223 NOTS
Enter topic text here.
223.1 Syntax
NOTS(dyn.array)
223.2 Description
The OASYS Basic NOTS Boolean operator inverts the logical result of each element of a dynamic array. If the element is true, the
corresponding position of the new array. If the expression is not true, the operator returns 1 (true) in the
corresponding position of the new array.
223.3 Example
In the following example, the program segment evaluates the dynamic array A, inverts each result of the
evaluation, and returns the results in a corresponding array. B now contains 0}1}0}0.
224 NULL
Enter topic text here.
224.1 Syntax
NULL
246
224.2 Description
The OASYS Basic NULL command acts as a dummy statement. You can use the NULL statement anywhere a
statement is required.
Tip: Use NULL when a statement or command clause is mandatory, but you do not want to initiate any action.
224.3 Example
In the following example, if the length of the variable NAME$ is zero, the program prints nothing:
225 NUM
225.1 Syntax
NUM(expr)
225.2 Description
The OASYS Basic NUM function determines if an expression is numeric. If expr is numeric, NUM returns 1.
Otherwise, it returns 0. expr can be any valid OASYS Basic expression. The NUM function returns 0 for any
multibyte character.
With null value handling on, this function returns 1 for the null value.
The nonnumeric characters in the following table produce a result of 1.
Character
+
.
Nonprinting
Description
Plus sign
Negative sign
Decimal point
Null value
Nonnumeric Characters
225.3 Examples
In the following example, the program segment prints 0 because VAR contains alphabetic characters:
NUM
247
In the next example, the program segment prints 1 because VAR contains an integer:
226 NUMS
Enter topic text here.
226.1 Syntax
NUMS(dyn.array)
226.2 Description
The OASYS Basic NUMS function determines, for each element of an array, if that element is numeric. If the
element is numeric, NUM returns 1 in the corresponding position of the new array. For nonnumeric and multibyte
characters, it returns 0.
With null value handling on, this function returns 1 for the null value.
The nonnumeric characters in the following table produce a result of 1.
Character
+
.
Nonprinting
Description
Plus sign
Negative sign
Decimal point
Null value
Nonnumeric Characters
226.3 Example
In the following example, the program segment determines whether each element of array CHARACTERS is
numeric. The resulting array B contains 1}1}1}0}0.
248
227 OCONV
Enter topic text here.
227.1 Syntax
OCONV(expr, conv.code.expr)
227.2 Description
The OASYS Basic OCONV function converts string or numeric data from internal format to display format based
on conversion codes. If the input value or conversion code is invalid, OASYS returns the input value. OCONV
supports multibyte languages.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
227.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
conv.code.expr
The following table summarizes the valid conversion codes. A detailed discussion of each follows under separate
headings.
Code
D
G
L
MB
Format
System date.
Extracts one or more strings separated by a delimiter.
Length.
Binary.
OCONV Codes
Code
MC
MD
ML
MP
M P1
Format
M asked character.
M asked decimal.
Left-justify.
Packed decimal.
Convert to packed decimal without truncating at the first CHAR(0) or
altering this character.
Octal.
Right-justify.
System time.
Hexadecimal.
Pattern match.
Range.
SOUNDEX.
Text extraction.
MO
MR
MT
MX
P
R
S
T
OCONV
Tfile
249
File translation.
OCONV Codes (continued)
228.1 Syntax
OCONV(integer.exp, "D [y] [c] [fmt]")
228.2 Description
The OCONV date (D) function converts an integer in internal date format to date display format. If the input
value or conversion code is invalid, OASYS returns the input value. OASYS ignores leading zeros in the input
date.
Note: The internal format of the date is the number of days before or after December 31, 1967. Days before are
represented as negative numbers.
With CUST.OPTIONS 4 on, this command converts the text of dates to uppercase. For example, May 13 is
converted to MAY 13.
With CUST.OPTIONS 29 on, this command converts Sunday to 7 instead of 0. For information about CUST.
OPTIONS, see the CUST.OPTIONS Commands Reference.
In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
228.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
integer.exp
Indicates a date in internal format.
OCONV Date (D) Parameters
Parameter Description
y
Number of digits to represent the year in the formatted date.
c
Delimiter separating day, month, and year. Can be a space, slash, period,
comma, hyphen, or asterisk.
250
fmt
Format Codes
The following table describes the valid output format codes.
Code
D
M
Y
Q
QA
W
WA
Description
Includes day in the output date.
Includes month in the output date.
Includes year in the output date.
Converts to quarter numeric format.
Converts to quarter alphabetic format.
Valid for day only. Specifies numeric format.
Valid for day only. Specifies alphabetic format.
OCONV Date Output Format Codes
Code
An
Zn
Description
Valid for day, quarter, and month only (WAn, QAn, and
M An respectively). A specifies alphabetic format, and n
indicates number of characters.
Valid for month and day only. Z specifies numeric format;
and n indicates number of digits. Z without a digit and Z0
suppress zeros.
Displays the Julian date (the number of days since January
1).
OCONV Date Output Format Codes (continued)
Note: Following SMA standards, Monday is the first day of the week (1). If CUST.OPTIONS 29 is on, Sunday
converts to 7 instead of 0.
Description
0
1
2
228.4 Examples
The following statements are taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. It converts the date stored in internal format in the ORDERS file. The formatted date
is in MM/DD/YYYY format.
251
In the following example, the program statement prints a three-character month name, a numeric day, and a fourdigit year (suppressing zeros if necessary):
Conversion Code
Output
744
744
1006
1006
1006
0
7334
7334
7334
7334
7334
7334
7334
7334
7334
7334
7334
DDM Y
DM DY
D
DDM Y
DDM YZ0,Z,Z
D4/
D
DDM Y,A,Z4
DDM Y,A3
DDM Y
DD
DM
DW
DWA
DQ
DQA
DJY
13 Jan 1970
01 13 1970
02 Oct 1970
02 10 1970
2 10 1970
12/31/1967
29 Jan 1988
29 January 1988
29 Jan 1988
29 01 1988
29
01
5
Friday
1
Winter
029 1988
OASYS
DATE, DATE.FORMAT, SET.TIME For information, see the OASYS Commands Reference.
229.1 Syntax
OCONV(str.expr, "G[m]x n")
252
229.2 Description
The OCONV group (G) function extracts one or more strings separated by a delimiter. If the input value or
conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
229.3 Parameters
The following table describes each parameter of the syntax.
Parameter
str.exp
m
x
n
Description
Indicates a string separated by a delimiter.
Indicates the number of strings to skip. If m is omitted, no strings are skipped.
Specifies any single nonnumeric character to be the delimiter. OASYS system
delimiters are valid. Hyphen or minus sign is not valid.
The number of strings to be extracted.
OCONV Group (G) Parameters
229.4 Example
In the following example, the program segment prints (303):
230.1 Syntax
OCONV(str.expr, "Ln[,m]")
230.2 Description
The OCONV length (L) function extracts a string of a specified length or that falls within a range of acceptable
lengths. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
253
230.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
str.exp
n
m
230.4 Example
In the following example, the program segment prints 123 and an empty string because X has fewer than five
characters and more than three:
231.1 Syntax
OCONV(str.expr, "MC [A | /A | B | /B | C;x;y | U | L | T | N | /N | P | X[D] | D | D[X] | X]")
231.2 Description
The OCONV mask character (MC) function converts alphabetic characters to uppercase or lowercase, or extracts
alphabetic or numeric characters from strings. This function performs the same conversions and extractions as
ICONV MC. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
231.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
254
str.expr
A
/A
B
/B
C;x;y
U
L
Parameter
Description
Converts to initial cap style. First letter of each word is uppercase, and all
other letters are lowercase. Space and tab are considered word separators.
/N
X[D] or D
D[X] or X
231.4 Examples
The following subroutine is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. The subroutine converts user input to uppercase, then compares that input with Q to
determine if the user is ready to quit the application. The user can enter any string starting with Q or q, or an
order number.
The following statement, taken from the same sample program, extracts the numbers from user input. This use of
2012 Onsystex Corp.
255
OCONV removes the special characters the user might have entered in a formatted date. For example, the
statement extracts 1234 from $12.34.
232.1 Syntax
OCONV(num.expr, "MDn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] [- | < | E | C | D] [P] [Z] [T] [xc
]")
232.2 Description
The OCONV masked decimal (MD) function scales, rounds, and formats a number for display with up to nine
decimal places. num.expr can be any numeric value. If the input value or conversion code is invalid, OASYS
returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or the
conversion code is invalid.
232.3 Parameters
The following table describes each parameter of the syntax.
Some parameters set the same values. Results are unpredictable if you make conflicting assignments.
Parameter
Description
num.expr
n
Parameter
Description
256
prefix], [
thsnd_mark], [
dec_symbl], [
suffix]
,
$
< or E
C
D
P
Z
T
xc
232.4 Examples
The following table describes some OCONV masked decimal conversion codes and their results.
Input
Code
Result
12.339
M D3
0.012
12.339
M D32
0.123
1234
M D2,$
$12.34
-1234
M D2$,<12.34>
912391
M D2$,D
$9,123.91DB
456789
M D2$,11*
$**4,567.89
123.456
M D24P
123.46
11111112339
M D12[@,*,,%]
@111*111*123.4%
OCONV Masked Decimal (MD) Examples
The following statement is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. It converts the price stored in internal format in the ORDERS file for display,
including two decimal places, commas separating thousands of dollars, preceded by a dollar sign.
257
233.1 Description
The OCONV left justify (ML) function scales, rounds, and formats a number, or left-justifies it in a mask. str.expr
can be any valid text or a numeric value with or without a decimal. If the input value or conversion code is invalid,
OASYS returns the input value.
Note: The OCONV ML and MR functions produce the same output. However, formatting differs slightly in the
following way: if a mask is specified that is larger than the formatted number, OASYS left- or right-justifies the
number within a column the width of the mask.
In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
233.2 Parameters
The following table describes each parameter of the syntax.
Note: Some parameters set the same values. Results are unpredictable if you make conflicting assignments
Parameter
Description
str.expr
n
Parameter
Description
[ [prefix], [
thsnd_mark], [
dec_symbl], [suffix]
]
thsnd_mark Nonnumeric character(s) to delimit thousands. To specify
a comma, enclose it in single quotation marks, and then use double
quotation marks to enclose the conversion code. For example, " M L2
[,',' ]" produces "...,nnn,nnn".
258
Suppresses zeros.
mask
233.3 Examples
In the following statement, OASYS moves the decimal three places to the left (0.012339), rounds to three decimal
places, and then prints 0.012:
In the following statement, OASYS moves the decimal two places to the left (0.12339), rounds to three decimal
places, and then prints 0.123:
In the following example, OASYS converts the value 123456789 to 1234-56-789 because it left-justifies it in the
mask ####-##-####:
In the following example, OASYS converts the value 12.339 to 0.012 based on the ML3 external conversion:
259
234.1 Syntax
OCONV(expr, "MP")
234.2 Description
The OCONV packed decimal (MP) function converts an integer from packed decimal representation into display
format. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
235.1 Syntax
OCONV(expr, MP1)
235.2 Description
The OCONV packed decimal (MP1) function converts an integer from packed decimal representation into its
display format without truncating at the first CHAR(0) character or altering CHAR(0). If the input value or
conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
260
236.1 Syntax
OCONV(str.expr, "MRn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] [C] [Z] [(mask)]")
236.2 Description
The OCONV right justify (MR) function scales, rounds, and formats a number, or right-justifies it in a mask. str.
expr can be any valid text or a numeric value with or without a decimal. If the input value or conversion code is
invalid, OASYS returns the input value.
Note: The OCONV ML and MR functions produce the same output. However, formatting differs slightly in the
following way: if you specify a mask that is larger than the formatted number, OASYS left- or right-justifies the
number within a column the width of the mask.
In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
236.3 Parameters
The following table describes each parameter of the syntax.
Some parameters set the same values. Results are unpredictable if you make conflicting assignments.
Parameter
Description
str.exp
n
If the conversion to display format is unsuccessful, OASYS returns the original value.
2012 Onsystex Corp.
261
236.4 Examples
In the following statement, OASYS moves the decimal three places to the left (0.012339), rounds to three decimal
places, and then prints 0.012:
In the following statement, OASYS moves the decimal two places to the left (0.12339), rounds to three decimal
places, and then prints 0.123:
In the following example, OASYS converts the value 123456789 to 123-45-6789 because it right-justifies it into the
mask ####-##-####:
The following example is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. It converts a price stored in internal format in the ORDERS file to display format,
including two decimal places, commas separating thousands of dollars, and a preceding $.
The following statement is taken from the same sample program. This statement displays the price right-justified
and formatted with commas separating thousands of dollars and a preceding $ as in $12,386.34. The right
justification aligns data on the right.
237.1 Syntax
OCONV(num.expr, "MT [H] [S] [c]")
237.2 Description
The OCONV time (MT) function converts the internal time of day from an integer between 0 and 86400 (the
number of seconds in a day) to display format. Time is output in the following form:
2012 Onsystex Corp.
262
HH MM [SS]
If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
237.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
num.expr
H
S
c
Note: A program that you can use to try out ICONV and OCONV conversion codes is provided in Developing
OASYS Basic Applications..
238.1 Syntax
OCONV(str.expr, ["HEX | MX [0C] | MO [0C] | MB [0C]"])
238.2 Description
The OCONV hex (MX), octal (MO), and binary (MB) functions convert from decimal or ASCII characters into
other numbering systems. If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
238.3 Parameters
The following table describes each parameter of the syntax.
Parameter
str.exp
HEX |
M X [0C]
M O [0C]
M B [0C]
263
Description
Specifies the number to convert to an alternate numbering system.
Indicates conversion to hexadecimal (base 16). The optional 0C converts
from ASCII character rather than decimal value. HEX is equivalent to
M X0C.
Indicates conversion to octal (base 8). The optional 0C converts from ASCII
character rather than decimal value.
Indicates conversion to binary (base 2). The optional 0C converts from
ASCII character rather than decimal value.
OCONV Numbering System Conversion Parameters
The following table indicates which parameters to use with OCONV to convert from decimal value or ASCII
character to other numbering systems.
From
Decimal value
Decimal value
Decimal value
ASCII character
ASCII character
ASCII character
To
Function
Binary
Octal
Hexadecimal
Binary
Octal
Hexadecimal
OCONV M B
OCONV M O
OCONV M X
OCONV M B0C
OCONV M O0C
OCONV M X0C
OCONV HEX
OCONV Options for Converting to Alternate Numbering Systems
238.4 Examples
The following table demonstrates some OCONV MX, MO, and MB conversion codes and their results.
Input
SS (ASCII character)
256 (decimal)
0 (ASCII character)
5 (decimal)
33288 (decimal)
Qat (ASCII character)
Code
M O0C
MX
MX
MB
MO
M X0C
Result
123123 (octal)
100 (hexadecimal)
4F (hexadecimal)
00000101 (binary)
101010 (octal)
516174 (hexadecimal)
U (ASCII character)
M B0C
01010101 (binary)
OCONV Hex, Octal, and Binary Examples
264
239.1 Syntax
OCONV(str.expr, "P(op)[;(op).....]")
239.2 Description
The OCONV pattern match (P) function checks a string for a match with one of the patterns or strings specified
in op. If the entire string does not match one of the patterns or strings, OASYS returns an empty string. If the
input value or conversion code is invalid, OASYS returns the input value. OCONV pattern match performs the
same function as the ICONV pattern match function.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
239.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
str.expr
op
239.4 Examples
The following statement prints an empty string because the entire input string does not match a pattern or string
specified in op:
The following statement prints abc because the input string matches the string provided in op:
240.1 Syntax
OCONV(num.expr, "Rndm[;ndm.....]")
265
240.2 Description
The OCONV range (R) function returns only those data values that fall into a specified range of decimal values.
When including a negative range, you must specify the highest negative number first. If range specifications are
not met, OASYS returns an empty string. If the input value or conversion code is invalid, OASYS returns the
input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
240.3 Parameters
The following table describes each parameter of the syntax.
Parameter
num.expr
n
d
m
;
Description
Indicates a string to be searched.
Specifies the smallest number to be extracted.
Specifies a delimiter separating numbers in a range. Any character except
system delimiters can be used to separate the numbers in a range.
Do not use the minus sign (-) as a delimiter because it refers to a negative
number in the range.
Specifies the longest string to be extracted.
Separates multiple ranges.
OCONV Range (R) Parameters
240.4 Example
In the following example, the program segment prints 123 and a blank line because X is within the range and Y
is not:
241.1 Syntax
OCONV(str.expr, "S")
266
241.2 Description
The OCONV SOUNDEX (S) function converts string or numeric data to phonetic format based on SOUNDEX
conversion codes. You can use the S conversion code in a virtual attribute formula. If the input value or
conversion code is invalid, OASYS returns the input value.
For more information on SOUNDEX conversion codes, see the SOUNDEX command.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
241.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
Indicates a string to be converted.
OCONV SOUNDEX (S) Parameters
241.4 Example
The following example is a virtual attribute (SDX_LNAME) that converts the value of the variable LNAME to its
SOUNDEX expression:
242.1 Syntax
OCONV(str.expr, "T[m,]n")
242.2 Description
The OCONV text extraction (T) function extracts a substring from a string. If you omit m, extraction begins from
the rightmost character, and n characters to the left are extracted. If you include m, extraction begins with the
position specified, and n characters to the right are extracted.
If the input value or conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
2012 Onsystex Corp.
267
242.3 Parameters
The following table describes each parameter of the syntax.
Parameter
str.expr
m
n
Description
Indicates a string to be searched.
Extracts a contiguous string of characters starting from character m.
Extracts a contiguous string of characters of length n.
OCONV Text Extraction (T) Parameters
242.4 Examples
The following table describes some OCONV text extraction codes and their results.
Input
Code
Result
1234567890
T3
1234567890
"T1,3"
890
Three characters are extracted, counting to
the left from 0.
123
Three characters are extracted, counting to
the right from 1.
M N TH
CONVERSIO
[space]COLORA
243.1 Syntax
OCONV(rec.id, "T[DICT] [filename;cn;I-Attribute;O-Attribute]")
243.2 Description
The OCONV file translation (Tfile) function retrieves attributes from a file without the file being explicitly opened
first. This function performs the same conversion as the ICONV file translation function. If the input value or
conversion code is invalid, OASYS returns the input value.
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
268
243.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
rec.id
DICT
filename
c
Parameter Description
n
I-Attribute
O-Attribute
243.4 Examples
The first line of the following program segment reads the demo database file ORDERS, accessing the record with
@ID 912, and retrieving the second attribute. OCONV T also converts the internal date to display format. The
second line prints the value in that attribute.
In the next example, the program statement translates the TAPE_ID to the TAPES file and returns the name of the
tape:
269
244 OCONVS
Enter topic text here.
244.1 Syntax
OCONVS(dyn.array.expr, conv.code.expr)
244.2 Description
The OASYS Basic OCONVS function converts string or numeric data from internal format to output format,
based on a conversion code, for each element of a dynamic array. If the input value or conversion code is invalid,
OASYS returns the input value.
Note: In BASICTYPE P, OCONVS returns an empty string if CUST.OPTIONS 56 is on and the input value or
conversion code is invalid.
OCONVS conversion codes are the same as OCONV conversion codes. For information about conversion
codes, see OCONV.
244.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.expr
conv.code.expr
244.4 Examples
In the following example, the program segment converts each element of ARR1 to output format:
270
245 ON/GOSUB
Enter topic text here.
245.1 Syntax
ON expr GOSUB label[:][, label[:]...]
245.2 Description
The OASYS Basic ON/GOSUB command transfers program control to a subroutine label based on the value of
expr.
ON GOSUB can appear on one line, or it can be spread over as many successive lines as necessary. Labels must
be separated by commas.
When the program encounters a RETURN statement in the called subroutine, OASYS transfers control to the
statement immediately following ON GOSUB. If the subroutine contains a RETURN TO label statement, control
resumes at the label specified in the RETURN statement.
Note: In BASICTYPE M or P, if expr is nonnumeric or less than 1, OASYS bypasses the GOSUB clause and the
next program statement executes.
245.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
expr
label
:
ON/GOSUB
271
245.4 Examples
In the following example, the program segment divides the variable BALANCE by 100. If the result is less than or
equal to 1, the program transfers control to subroutine U100. If the value is 2 or 3, it transfers control to U200 or
U300 respectively. If the value is greater than or equal to 4, OASYS transfers control to subroutine U400.
In the next example, the program segment transfers control to a subroutine after prompting the user for a screen
item to modify. In this case, depending on the number the user enters, OASYS transfers control to one of the five
subroutines in the GOSUB clause. If the user response is nonnumeric or less than 1, OASYS transfers control to
the first subroutine. If the user enters a value greater than 5, OASYS transfers control to the last subroutine (500).
246 ON/GOTO
Enter topic text here.
246.1 Syntax
ON expr GOTO label1[:] [, label2[:] ...]
246.2 Description
The OASYS Basic ON/GOTO command transfers program control to a statement label based on a numeric
expression.
The ON GOTO statement, like the GOTO statement, is one-way branch. If you use an ON GOTO statement to
transfer control to a subroutine with a RETURN statement, the subroutines RETURN statement works if a
previous GOSUB statement is still waiting for a RETURN statement in the subroutine. Otherwise, the program
aborts with a runtime error.
Tip: Use ON/GOSUB instead of ON/GOTO to make your programs easier to follow and maintain.
246.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
272
expr
label
:
Note: In BASICTYPE M or P, if expr is nonnumeric or less than 1, OASYS bypasses the GOTO clause and the
next program statement executes.
246.4 Example
In the following example, the program statement transfers program control to the statement label TEST if the
variable X is less than or equal to 1. If X is 2, OASYS transfers control to statement label 2500. If X is greater than
or equal to 3, OASYS transfers control to statement label YESNO.
247 OPEN
Enter topic text here.
247.1 Syntax
OPEN ["expr",] "filename" [READONLY] [TO file.var] [ON ERROR statements] {THEN statements [END] | ELSE
statements [END]}
247.2 Description
The OASYS Basic OPEN command opens a OASYS hashed data or dictionary file, so you can read, write, or
delete records from it. The number of files you can open is determined by operating system and OASYS
configuration parameters. For information about file performance, see Administering OASYS on UNIX or
Administering OASYS on Windows Platforms.
Warning: Do not use OASYS Basic READ commands to open or modify binary data in DIR-type files (for
example, BP). Doing so could corrupt data in the file. Instead, use OSREAD or OSBREAD after executing the
OASYS Basic NOCONVERT command.
OPEN
247.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
filename
READONLY
Parameter
Description
TO file.var
ON ERROR
statements
THEN statements
END
ELSE statements
END
Description
The number of modulos for the file.
The file opened is a directory.
INMAT Function Return Values
273
274
247.4 Examples
In the following statement, OASYS moves the decimal three places to the left (0.012339), rounds to three decimal
places, and then prints 0.012:
In the following statement, OASYS moves the decimal two places to the left (0.12339), rounds to three decimal
places, and then prints 0.123:
In the following example, OASYS converts the value 123456789 to 123-45-6789 because it right-justifies it into the
mask ####-##-####:
The following example is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. It converts a price stored in internal format in the ORDERS file to display format,
including two decimal places, commas separating thousands of dollars, and a preceding $.
The following statement is taken from the same sample program. This statement displays the price right-justified
and formatted with commas separating thousands of dollars and a preceding $ as in $12,386.34. The right
justification aligns data on the right.
248 OPENSEQ
248.1 Syntax
OPENSEQ [absolutepath | seq.filename,record.id] [READONLY] TO seq.file.var [ON ERROR statements]
[LOCKED statements] {THEN statements [END] | ELSE statements [END]}
OPENSEQ [absolutepath | seq.filename,record.id] [READONLY] TO seq.file.var [LOCKED statements] [ON
ERROR statements] {THEN statements [END] | ELSE statements [END]}
OPENSEQ
275
248.2 Description
The OASYS Basic OPENSEQ command opens a sequential file for access, starting at the specified record.
OASYS limits to 150 the number of sequential files you can open in a OASYS Basic program.
Tip: Use OPENSEQ to open files that use CHAR(10) as a delimiter. You can then use READSEQ to read the
next line delimited by CHAR(10), or WRITESEQ to write a line delimited by CHAR(10). You also can use
OSBREAD to read a block of data from the file, or OSBWRITE to write a block of data to the file.
Note: For OASYS for Windows Platforms only: When you use OPENSEQ, OASYS uses the fopen function to open
files in Text mode and converts NEWLINE [CHAR (10)] line delimiters to CARRIAGE RETURNNEWLINE
pairs [CHAR(13) and CHAR(10)].
248.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
absolutepath
seq.filename
record.id
READONLY
Opens the file for reading only. If the program attempts to write
to a file opened in READONLY mode, OASYS displays a
runtime error message and does not update the file. For
information about security procedures, see Administering OASYS
on UNIX or Administering OASYS on Windows Platforms.
Specifies a file variable to contain a pointer to the opened file.
Specifies statements to execute if the OPENSEQ statement fails
with a fatal error because the file is not open, an I/O error occurs,
or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
Specifies statements to execute if the record is locked by another
user. If you do not specify a LOCKED clause, the program waits
until the lock on the record is released. You can place the
LOCKED clause after the FROM clause.
Use the ECL command DEFAULT.LOCKED.ACTION BELL
to make the terminal beep while you wait for OASYS to unlock
the record.
THEN executes if the read is successful. END is required to
terminate multiline THEN statements.
ELSE executes if the read is not successful or the record (or ID)
does not exist. END is required to terminate multiline ELSE
statements.
OPENSEQ Parameters
TO seq.file.var
ON ERROR statements
LOCKED statements
248.4 Example
In the following example, the program statement opens the sequential file INV.SOURCES in the directory
PRINTERS, and assigns the file variable PRNT:
276
OASYS
DEFAULT.LOCKED.ACTION For information, see OASYS Commands Reference.
249 OR
Enter topic text here.
249.1 Syntax
expr1 OR expr2
249.2 Synonym
!
249.3 Description
The OR Boolean operator combines a set of expressions. If expr1 or expr2 is true, the combined expression is
true. Either expression must be true for a true condition.
249.4 Example
In the following example, the program segment combines expressions (X < Y) and (Y < Z). If either expression is
true, the program calls subroutine RETRY.
250 OSBREAD
Enter topic text here.
OSBREAD
277
250.1 Syntax
OSBREAD var FROM file.var [AT byte.expr] LENGTH length.expr [NODELAY] [ON ERROR statements]
250.2 Description
The OASYS Basic OSBREAD command reads data from a file starting at a specified byte location for a certain
length of bytes, and assigns the data to a variable. OSBREAD performs an operating system block read on a
UNIX, or Windows platform file.
Note: Before you use OSBREAD, you must open the file by using the OSOPEN or OPENSEQ command.
OASYS uses the ASCII 0 character [CHAR(0)] as a string-end delimiter. Therefore, ASCII 0 cannot be used in
any string variable within OASYS Basic. OSBREAD converts CHAR(0) to CHAR(128) when reading a block of
data.
250.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
FROM file.var
AT byte.expr
LENGTH length.expr
NODELAY
278
Description
0
1
2
3
4
250.5 Examples
In the following example, the program statement reads 10,000 bytes of the file RFILE starting from the beginning
of the file. The program assigns the data it reads to the variable TEST.
In the next example, the program segment reads 15,000 bytes from an NTFS or UNIX file, starting at the first byte.
It then converts ASCII value 10 (a line feed) to a value mark and processes each line sequentially.
251 OSBWRITE
Enter topic text here.
OSBWRITE
279
251.1 Syntax
OSBWRITE expr {ON | TO} file.var [AT byte.expr] [NODELAY] [ON ERROR statements]
251.2 Description
The OASYS Basic OSBWRITE command writes an expression to a sequential file starting at a specified byte
location. OSBWRITE immediately writes a file segment out to the UNIX, or Windows platform file.
You do not have to specify a length expression because the number of bytes in expr is written to the file.
Note: Before you use OSBWRITE, you must open the file by using the OSOPEN or OPENSEQ command.
OASYS uses the ASCII 0 character [CHAR(0)] as a string-end delimiter. Therefore, ASCII 0 cannot be used in
any string variable within OASYS Basic. If OASYS Basic reads a string that contains CHAR(0) characters by
using OSBREAD, those characters are converted to CHAR(128). OSBWRITE converts CHAR(128) back to
CHAR(0) when writing a block of characters.
251.3 Parameters
The following table describes each parameter of the syntax.
Parameter
expr
ON | TO file.var
AT byte.expr
NODELAY
ON ERROR statements
Description
Specifies the expression to write to the file.
Specifies the file on which to write the expression.
If byte.expr is 0, the write begins at the beginning of the file.
Forces an immediate write.
Include NODELAY to write to a named pipe immediately
regardless of whether the pipe contains data. If you do not
specify NODELAY, the process attempting to write waits until
the pipe is opened for reading.
Specifies statements to execute if the OSBWRITE statement
fails with a fatal error because the file is not open, an I/O error
occurs, or OASYS cannot find the file.
280
Description
0
1
2
4
251.5 Examples
In the following example, the program statement writes the data in TEST to the RFILE starting from the beginning
of the file:
In the next example, the program segment reads REC.ID from a select list, reads the associated record from the
CLIENT file, and appends the record onto a variable (BLOCK), terminating each record with an ASCII 10 (line
feed). When it is complete, the code writes the block to the NTFS or UNIX file name opened to the variable
CLIENT.SEQ.
252 OSCLOSE
Enter topic text here.
OSCLOSE
281
252.1 Syntax
OSCLOSE file.var [ON ERROR statements]
252.2 Description
The OASYS Basic OSCLOSE command closes a sequential file that you opened with the OSOPEN or OPENSEQ
command.
252.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var
ON ERROR
statements
Description
0
5
252.5 Example
In the following example, the program statement closes the file UNDEF:
253 OSDELETE
Enter topic text here.
282
253.1 Syntax
OSDELETE filename [ON ERROR statements]
253.2 Description
The OASYS Basic OSDELETE command deletes an NTFS or UNIX sequential file.
Warning: The OASYS Basic OSDELETE command is intended for use on OS-type files (not OASYS hashed files).
If you execute the command against a recoverable hashed file, OASYS could crash immediately or at the next
Recoverable File System (RFS) checkpoint. If you execute the command against a nonrecoverable hashed file,
OASYS will not crash, but other unpredictable problems could occur
253.3 Parameters
The following table describes each parameter of the syntax.
Parameter
filename
Description
Specifies the file to delete. filename must include the file path. If you do
not specify a path, OASYS searches the current directory.
Specifies statements to execute if the OSDELETE statement fails with a
fatal error because the file is not open, an I/O error occurs, or OASYS
cannot find the file.
If you do not specify the ON ERROR clause and a fatal error occurs, the
program terminates.
OSDELETE Parameters
ON ERROR
statements
Description
The file was deleted.
The directory name is invalid.
OASYS cannot access the file (such as user
does not have permission).
The file does not exist.
STATUS Function Return Values
253.5 Examples
In the following example, the program statement deletes the file NAMES in the current directory:
In the next example, the program statement deletes the file client.rec in the UNIX subdirectory /u/trans:
OSDELETE
283
254 OSOPEN
Enter topic text here.
254.1 Syntax
OSOPEN filename [READONLY | WRITEONLY] TO file.var [NODELAY] [ON ERROR statements] {THEN |
ELSE} statements [END]
254.2 Description
The OASYS Basic OSOPEN command opens a sequential file that does not use CHAR(10) as the line delimiter.
Read/write access mode is the default. Specify this access mode by omitting READONLY and WRITEONLY.
Tip: After opening a sequential file with OSOPEN, use OSBREAD to read a block of data from the file, or
OSBWRITE to write a block of data to the file. You also can use READSEQ to read a record from the file, or
WRITESEQ or WRITESEQF to write a record to the file, if the file is not a named pipe. (READSEQ, WRITESEQ,
and WRITESEQF are line-oriented commands that use CHAR(10) as the line delimiter.)
Note: On OASYS for Windows Platforms only: When you use OSOPEN, OASYS uses the open function to open
files in binary mode, but does not convert NEWLINE [CHAR(10)] delimiters to CARRIAGE RETURN
NEWLINE pairs [CHAR(13) and CHAR(10)] as the OPENSEQ command does.
254.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
filename
Specifies the file to open. filename must include the entire path
name unless the file resides in the current directory.
Directs OASYS to open the file for reading only. If the program
attempts to write to a file opened in READONLY mode, OASYS
displays a runtime error message and does not update the file. For
information about security procedures, see Administering OASYS
on UNIX or Administering OASYS on Windows Platforms.
Specifies that the pipe or file is open for write access only.
Specifies a variable to contain a pointer to the file.
Forces a pipe to be opened immediately. This enables a process
to continue even when the pipe is not open in the opposite
access mode. The application must then manage access to the
pipe to ensure that it is opened for the opposite process before
reading from or writing to it.
If filename is not a named pipe, NODELAY has no effect.
Specifies statements to execute if the OSOPEN statement fails
with a fatal error because the file is not open, an I/O error occurs,
READONLY
WRITEONLY
TO file.var
NODELAY
ON ERROR statements
284
254.4 Example
In the following example, the program statement opens the file INVENTORY as INVENT unless OASYS cannot
access the file.
255 OSREAD
Enter topic text here.
255.1 Syntax
OSREAD var FROM filename [ON ERROR statements] {THEN statements [END] | ELSE statements [END]}
255.2 Description
The OASYS Basic OSREAD command reads an entire sequential file and assigns the contents of the file to a
variable.
Warning: Do not use OSREAD on large files. If the file is too large for the program memory, the program aborts
and a runtime error message is generated. On large files, use OSBREAD or READSEQ.
Note: OASYS uses the ASCII 0 character [CHAR(0)] as a string-end delimiter. ASCII 0 cannot be used in any
string variable within OASYS Basic. OSREAD converts CHAR(0) to CHAR(128) when reading a block of data.
255.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
Description
Specifies the variable to which to assign the data from the file.
2012 Onsystex Corp.
OSREAD
FROM filename
The filename must include the entire path to the file unless
filename exists in the current directory.
OSREAD Parameters
Parameter
Description
ON ERROR statements
ELSE executes if the read is not successful or the record (or ID)
does not exist. END is required to terminate multiline ELSE
statements.
OSREAD Parameters (continued)
255.4 Example
In the following example, the program segment reads the data stored in the UNIX file BILLING in the
subdirectory disk1 and assigns it to the variable BILL.REC:
256 OSWRITE
Enter topic text here.
256.1 Syntax
OSWRITE expr {ON | TO} filename [ON ERROR statements]
285
286
256.2 Description
The OASYS Basic OSWRITE command writes the contents of an expression to a sequential file.
Note: OASYS uses the ASCII 0 character [CHAR(0)] as a string-end delimiter. For this reason, you cannot use
ASCII 0 in any string variable in OASYS Basic. If OASYS Basic reads a string with a CHAR(0) character, and
then the character is converted to CHAR(128), OSWRITE converts CHAR(128) to CHAR(0) when writing a
block of characters.
256.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
ON | TO filename
ON ERROR statements
256.4 Example
In the following example, the program segment writes the contents of MAIL.LIST to the file called mergefile in
the UNIX subdirectory /u/maildir:
257 PAGE
Enter topic text here.
257.1 Syntax
PAGE [ON num.expr] [expr]
257.2 Description
The OASYS Basic PAGE command prints the current output page. OASYS prints the page with any specified
header or footer.
If you do not specify any parameters, the result depends on the last PRINTER command executed:
2012 Onsystex Corp.
PAGE
287
257.3 Parameters
The following table describes each parameter of the syntax.
Parameter
ON num.expr
expr
Description
Specifies the page number of the next output page. Each subsequent
page is incremented by one.
Specifies a target print file for the completed page where num.expr is the
number assigned to the file. When you specify a num.expr, the
PRINTER command setting is disregarded.
For assistance assigning print files, see your system administrator.
PAGE Parameters
257.4 Examples
In the following example, the program statement completes the current page with footings, then advances to a
new page. The PRINTER command setting determines where the page is printed.
In the next example, the program statement sends the completed page to the file assigned to print unit 5. If
OASYS cannot find the print unit specified, the program prints nothing.
OASYS
SETPTR For information, see the OASYS Commands Reference.
258 PAUSE
Enter topic text here.
258.1 Syntax
PAUSE [wait_time]
288
258.2 Description
The OASYS Basic PAUSE command suspends the OASYS process that issues the command for the amount of
time you specify with wait_time, or until a OASYS Basic WAKE command is executed for this process. Keep in
mind the
following points when executing PAUSE:
PAUSE has no effect if wait_time is a negative number, or if another OASYS process has previously issued a
WAKE command for this process.
To pause a process indefinitely, omit wait_time, or specify a wait_time of 2.
PAUSE must be executed by the process to be paused.
258.3 Examples
The following sample program executes the OASYS Basic PAUSE command to pause the current session:
The following example executes the preceding program. In this execution, the user does not enter an amount of
time to pause the session, so it is paused indefinitely. (The cursor rests on the line following the prompt.)
From another OASYS session, the user executes the LIST.PAUSED command to obtain the process ID for the
paused process, and then wakes it up by specifying WAKE 1052:
OASYS
LIST.PAUSED, PAUSE, SLEEP, WAKE For information, see the OASYS Commands Reference.
PCPERFORM
289
259 PCPERFORM
Enter topic text here.
259.1 Syntax
PCPERFORM str.expr [CAPTURING, dyn.array.var]
259.2 Description
The OASYS Basic PCPERFORM command executes an operating system command from within a OASYS Basic
program.
PCPERFORM is similar to the EXECUTE and PERFORM commands except that PCPERFORM executes an
operating system command.
If PCPERFORM is successful, OASYS sets @SYSTEM.RETURN.CODE to 0. If unsuccessful, OASYS sets
@SYSTEM.RETURN.CODE to -1.
Note: The settings of CUST.OPTIONS affect the way ECL commands execute. For information about these
options, see the CUST.OPTIONS Commands Reference. For information about CUST.OPTIONS that could
affect that command, see the appropriate ECL command in OASYS Commands Reference.
259.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
Specifies a string to execute as a host operating system command.
CAPTURING, dyn. Specifies a target dynamic array to capture the output of the host
array.var
operating system command.
PCPERFORM Parameters
259.4 Example
In the following example, the program statement executes the operating system date command:
260 PERFORM
PERFORM is a synonym for the EXECUTE command. For more information, see EXECUTE.
290
260.1 Synonym
EXECUTE
261 PRECISION
Enter topic text here.
261.1 Syntax
PRECISION num.expr
261.2 Description
The OASYS Basic PRECISION command rounds numbers to the number of decimal places indicated in num.expr
. num.expr can be a number from 0 to 14. If the number is not within this range, OASYS does not change the
setting. The default is four decimal places.
Tip: OASYS converts the operands in numeric operations from string to numeric data type, performs the
operations, and then converts the results back to string data type. When making calculations for which you
require a high degree of precision, use the PRECISION command to force OASYS to represent a particular
level of decimal representation.
Set the OASYS FLOAT.PRECISION to 4 to truncate rather than round at the PRECISION setting.
Examples
In the following example, the program statement results in all numeric variables being truncated to eight decimal
places:
In the next example, the program statement truncates all digits to the right of the decimal point:
In the next example, the program statement sets precision based on the variable DEC:
262 PRINT
Enter topic text here.
291
262.1 Syntax
PRINT [ON num.expr] [print.expr]
262.2 Description
The OASYS Basic PRINT command prints data on the display terminal or the system printer, or sends data to a
print file.
Separate multiple items in a single PRINT statement with commas or colons. A comma directs the printer to
execute a tab. Tab stops are set to 10 spaces. If you use a colon to separate statements, OASYS concatenates the
items.
Unless a PRINT expression ends with a colon, OASYS executes a carriage return after printing the line. If the
output from the PRINT statement exceeds the current page width, it wraps to the next line.
Tip: You can use the OASYS Basic @ function with the PRINT command to place the cursor and/or direct the
terminal to take some action. Execute the ECL REUSE.ROW command to determines whether a line feed is
executed when the OASYS Basic PRINT @ function references column only. For example, PRINT @(10) rather
than PRINT @(3,10).
Note: The PRINT statement interprets two consecutive nonprinting ASCII characters (such as CHAR(192):
CHAR(192)) as one character when displaying data.
To suppress the line feed at the end of displayed text, place a colon at the end of the PRINT or DISPLAY
statement.
262.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
ON num.expr
Specifies a target print file. If you do not use the ON clause, the data is
printed based on the last PRINTER command executed:
PRINTER OFF The data prints on the display terminal.
PRINTER ON The data prints on the system printer.
Specifies an expression to print. It can be any valid OASYS Basic
expression. If you do not specify a print.expr, a PRINT statement sends
a line feed character to the printer or file.
PRINT Parameters
print.expr
262.4 Examples
In the following example, the program segment prints HI THERE on the system printer:
In the next example, the program statement sends the value of variable X concatenated to "X = " to the file
specified by unit 10:
292
In the next example, the @ function is included with a terminal option. -1 clears the screen before printing.
In the next example, the comma separation character prints X, Y, a string separated by tabs, X+Y, tabs twice, then
prints another string, and finally print the average of X and Y using the INT function:
Each item is separated by tabs as the result of the comma separation character. A colon causes all data items to
be concatenated.
The following program demonstrates the use of the colon at the end of the PRINT statement to suppress the line
feed issued by OASYS Basic at the end of displayed text. The first PRINT statement does not end in a colon.
Therefore,
OASYS Basic issues a carriage return and prints a question mark (the default prompt character). The second
PRINT statement ends in a colon. In this case, OASYS Basic displays the default prompt character and waits on
the same line with the PRINT statement.
OASYS
SETPTR For information, see the OASYS Commands Reference.
263 PRINTER
Enter topic text here.
PRINTER
293
263.1 Syntax
PRINTER {ON | OFF}
263.2 Description
The OASYS Basic PRINTER command directs output of PRINT, FOOTING, HEADING, and PAGE statements
not sent to a file (those executed without the ON clause). If you specify ON, OASYS directs all output to the
system printer. If you specify OFF, OASYS directs all output to the terminal screen.
PRINTER ON causes runtime error messages to print on the system printer.
Note: If the printer and your computer are not communicating properly when you execute a print command (for
example, a PRINT statement after a PRINTER ON command), OASYS generates an error.
263.3 Example
In the following example, the program statement sends all future report output (data from PRINT, FOOTER,
HEADER, and PAGE commands) to the printer:
264.1 Syntax
PRINTER CLOSE [ON num]
264.2 Description
The OASYS Basic PRINTER CLOSE command sends data stored in either a print file or a print buffer to the print
queue. The ON clause does not physically close the print file. Instead, it sends its contents to a print buffer,
leaving the file empty. Then you can send additional data to the same print file to begin a new set of data to be
printed. As many as 31 print files can be open at the same time. The PRINTER CLOSE statement does not
generate a new line at the end of a page. OASYS Basic is in control of page feeds or generating new line
equivalents.
Note: Data in a print file is automatically sent to the print queue if the program ends or issues a PRINTER
CLOSE statement.
264.3 Example
In the following example, the program statement sends the current contents of print file 5 to the print queue:
294
265 PRINTERR
Enter topic text here.
265.1 Syntax
PRINTERR expr [FROM file.var]
265.2 Description
The OASYS Basic PRINTERR command prints error messages stored in the OASYS system message file or in a
user-defined file.
To obtain a message from a user-defined error message file, you must open the file first.
The OASYS Basic commands ABORT and PRINTERR return the system message you specify by ID in the
command. You can also retrieve system messages using a OASYS Basic program by opening the system
message file and reading a message record by ID.
Note: ENGLISH.MSG is the default system message file that is activated when you install OASYS. If you execute
oaslang.config to select a language group, a different system message file could be activated. To find out which
language is installed on your system, execute the ECL command SET.LANG CURRENT. For more information,
see OASYS International.
265.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
FROM file.var
Code
A
Description
Extracts the next element in expr.
PRINTERR
A(n)
C
D
E literal
H literal
L
L(n)
R(n)
S(n)
295
Code
T
W(n)
X
Description
Enters the time in internal format.
Pauses for n seconds before continuing to display the message.
Skips the next parameter passed to the OASYS message printing routine.
PRINTERR Error Message Codes (continued)
265.4 Examples
In the following example, the OASYS oaslang.MSG file contains error message 4432 and a user-defined file
(S_ERR) contains error message E009. These messages contain the following:
The following code segment produces an error message if the file you enter for FNAME cannot be found or you
enter 12 for VAR1:
If you enter file_test for FNAME and file_test cannot be found, the program segment produces the following
error message:
296
If you enter 12 for VAR1, the program segment produces the following error message:
266 PROCREAD
Enter topic text here.
266.1 Syntax
PROCREAD var {THEN statements [END] | ELSE statements [END]}
266.2 Description
The OASYS Basic PROCREAD command assigns the string value of the primary input buffer of the calling Proc
to a variable. PROCREAD can be used to access the primary input buffer of a calling proc.
Note: A proc is a PQ-type VOC record.
266.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
266.4 Examples
In the following example, the program segment assigns the string value in the primary input buffer to
ARGUMENTS. If the program had been called by something other than a proc, the program prints a two-line error
message.
PROCREAD
297
The following sample Proc loads the OASYS Basic program name proc.test into the data stack (Hproc.test), turns
on that stack (STON), and loads ONE into the primary output buffer (HONE). The next command (P) executes
the data stack entry, which runs proc.basic. Finally, D0 displays the contents of the active input buffer.
The program proc.test prints after the proc, and a sample execution of the proc follows the program:
The following globally cataloged program, proc.test, is executed by the preceding proc. The INPUT statement
reads from the currently active output buffer, which the proc loaded with ONE.
298
PROCREAD
299
267 PROCWRITE
Enter topic text here.
267.1 Syntax
PROCWRITE expr
267.2 Description
The OASYS Basic PROCWRITE command writes data to the primary input buffer of the calling Proc.
PROCWRITE overlays any data in the primary input buffer with the new data in PROCWRITE.
267.3 Example
In the following example, the program segment writes the contents of ANSWER to the primary input buffer:
300
268 PROGRAM
Enter topic text here.
268.1 Syntax
PROGRAM prog.name
268.2 Description
The OASYS Basic PROGRAM command defines the name of the current main program. This statement is
optional. It is used for documentation purposes only. The PROGRAM statement must be the first noncomment
statement in the program.
268.3 Example
In the following example, the program segment declares the program name as BOOKS:
OASYS
BASIC, CATALOG For information, see the OASYS Commands Reference.
269 PROMPT
Enter topic text here.
PROMPT
301
269.1 Syntax
PROMPT str.expr
269.2 Description
The OASYS Basic PROMPT command sets the prompt displayed by the INPUT command to a specified singlebyte character. If str.expr is longer than one character, OASYS uses the first character as the prompt. You cannot
set the prompt to a multibyte character.
Data received from a DATA statement displays after the prompt.
If you want to suppress the default prompt character, set the prompt to an empty string. The default prompt
character is the question mark.
Tip: Setting the prompt to an empty string also suppresses display of input from a DATA statement on the
terminal screen. For example:
will not echo mypassword to the terminal screen. The PROMPT statement must precede the DATA statement.
Data input from the keyboard will still echo on the display terminal.
When you want to display text on the screen and have the cursor remain at the end of the displayed text
awaiting user input, place a colon at the end of the PRINT or DISPLAY statement.
269.3 Example
In the following example, the contents of variable PSTRING (in this case, an asterisk) become the new prompt.
When an INPUT command is used in the program, an asterisk appears at the current cursor position on the
display terminal.
270 PWR
Enter topic text here.
270.1 Syntax
PWR(num.expr1, num.expr2)
302
270.2 Description
The OASYS Basic PWR function raises expr1 to the power of expr2.
Note: PWR is synonymous with two asterisks (**) or ^.
270.3 Example
In the following example, the program segment raises variable X to the power of 3, first using exponentiation
operator **, then using the PWR function, and finally using the exponentiation operator ^. The results are
identical.
271 QUOTE
Enter topic text here.
271.1 Syntax
QUOTE(str.expr)
271.2 Synonym
DQUOTE
271.3 Description
The OASYS Basic QUOTE function encloses a string expression in double quotation marks.
271.4 Examples
In the following example, the program segment encloses the string stored in VAR2 with double quotation marks,
and then stores that string (STRING2) in VAR3:
In the following example, the program statement uses DQUOTE to print This is a test:
QUOTE
303
In the next example, the program segment prints This is another test:
272 RAISE
Enter topic text here.
272.1 Syntax
RAISE(str.expr)
272.2 Description
The OASYS Basic RAISE function raises all OASYS delimiters to the next level. OASYS raises attribute marks to
record marks, value marks to attribute marks, and subvalue marks to value marks.
272.3 Example
In the following example, the program segment raises all delimiters to the next level:
273 READ
Enter topic text here.
273.1 Syntax
READ dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] {THEN statements [END] | ELSE
statements [END]}
304
273.2 Description
The OASYS Basic READ command reads a record from a file and assigns its contents to a dynamic array. OASYS
assigns the first attribute of the record to the first position of the array, the second attribute to the second
position, and so on. If OASYS cannot find the record you specify, it executes the ELSE clause and returns dyn.
array.var empty.
Note: This command does not check for locks. If you are operating in a multiuser environment, you must use
record locks to prevent more than one user from accessing the same record at the same time. For more
information about OASYS Basic record locking, see Developing OASYS Basic Applications.
Warning: Do not use OASYS Basic READ commands to open or modify binary data in DIR-type files (for
example, BP). Doing so could corrupt data in the file. Instead, use OSREAD or OSBREAD after executing the
OASYS Basic NOCONVERT command.
273.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.var
FROM file.var,
record.ID.expr
ON ERROR statements
Description
Successful read.
A read error occurred.
273.5 Example
In the following example, the program segment reads a record from the CLIENTS file with ID CLIENT.ID. If the
record ID is found, OASYS executes the subroutine PROCESS.CLIENT. Otherwise, OASYS prints a message and
2012 Onsystex Corp.
READ
305
274 READBCK
Enter topic text here.
274.1 Syntax
READBCK dyn.array.var [FROM file.var] [ON ERROR statements] {THEN statements [END] | ELSE statements
[END]}
274.2 Description
The first READBCK command retrieves the alternate key set by SETINDEX, then each subsequent READBCK
retrieves the previous alternate key value in the index. The corresponding record is read into a dynamic array, and
the record ID is assigned to the @ID variable.
Note: This command does not check for locks. If you are operating in a multiuser environment, you must use
record locks to prevent more than one user from accessing the same record at the same time. For more
information about OASYS Basic record locking, see Developing OASYS Basic Applications.
Using this command in a loop, a OASYS Basic program retrieves records in descending order based on an
indexed attribute.
Before executing READBCK, you must set the alternate key value with the SETINDEX command. The SETINDEX
parameters BUFFER.KEYS and VALIDATE.KEY determine, respectively, whether the buffering mechanism is
used and whether keys are validated when READBCK executes. For details, see SETINDEX.
READBCK sets the STATUS function return value to 10 if OASYS Basic detects a duplicate alternate index key
value and you have executed the ECL command DUP.STATUS ON during the current session.
274.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
Description
Specifies a dynamic array to which to assign the values read.
Specifies a file variable from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
306
The default file is one for which no file variable is assigned in the
OPEN statement.
ON ERROR statements
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL
DUP.STATUS is on.
STATUS Function Return Values
274.5 Example
In the following example, the program segment sets the index to the first record that contains Smith, and then
reads that record and the previous four:
Note: This program reads the records even if the records are locked by another user
READBCK
307
SELECTINDEX, SETINDEX
OASYS
BUILD.INDEX, CREATE.INDEX, DUP.STATUS For information, see the OASYS Commands Reference.
275 READBCKL
Enter topic text here.
275.1 Syntax
READBCKL dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
[END] | ELSE statements [END]}
READBCKL dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
[END] | ELSE statements [END]}
275.2 Description
The first READBCKL command retrieves the alternate key set by SETINDEX, and then each subsequent
READBCKL retrieves the previous alternate key in the index. The corresponding record is read into a dynamic
array, and the record ID is assigned to the @ID variable. READBCKL checks for locks. If the record is available, it
sets a shared (L) lock before reading the record.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Using this command in a loop, a OASYS Basic program retrieves records in descending order based on an
indexed attribute.
Before executing READBCKL, you must set the pointer in the alternate key file with the SETINDEX command.
The SETINDEX parameters BUFFER.KEYS and VALIDATE.KEY determine, respectively, whether the buffering
mechanism is used and whether keys are validated when READBCKL executes. For details, see SETINDEX.
READBCKL sets the STATUS function return value to 10 if OASYS Basic detects a duplicate alternate index key
value and you have executed the ECL command DUP.STATUS ON during the current session.
275.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
ON ERROR statements
Description
Specifies a target dynamic array to receive the data read.
Specifies a file variable from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in
the OPEN statement.
Specifies statements to execute if the READBCKL statement
fails with a fatal error because the file is not open, an I/O error
occurs, or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
308
LOCKED statements
Description
0
10
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL
DUP.STATUS is on.
STATUS Function Return Values
275.5 Example
This example uses the following program to lock the CLIENT file for two minutes:
Notice that execution halts on the second program until the first program unlocks the CLIENTS file. This is
because commands that set shared locks cannot access files locked with exclusive locks (FILELOCK sets an
exclusive
lock).
Note: If the first program had set a shared lock, the second program would have been able to read the records.
READBCKL
309
OASYS
BUILD.INDEX, CREATE.INDEX, DEFAULT.LOCKED.ACTION, DUP.STATUS For information, see the OASYS
Commands Reference.
276 READBCKU
Enter topic text here.
276.1 Syntax
READBCKU dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
[END] | ELSE statements [END]}
READBCKU dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
[END] | ELSE statements [END]}
276.2 Description
The first READBCKU command retrieves the alternate key set by SETINDEX, and then each subsequent
READBCKU retrieves the previous alternate key value in the index. The corresponding record is read into a
dynamic array, and the record ID is assigned to the @ID variable. READBCKU checks for locks. If the record is
available, it sets an exclusive (U) lock before reading the record.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Using this command in a loop, a OASYS Basic program retrieves records in descending order based on an
indexed attribute.
Before executing READBCKU, you must set the alternate key value with the SETINDEX command. The
SETINDEX parameters BUFFER.KEYS and VALIDATE.KEY determine, respectively, whether the buffering
mechanism is used and whether keys are validated when READBCKU executes. For details, see SETINDEX.
READBCKU sets the STATUS function return value to 10 if OASYS Basic detects a duplicate alternate index key
value and you have executed the ECL command DUP.STATUS ON during the current session.
276.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
Description
Specifies a target dynamic array to receive the data read.
Specifies a file variable from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
310
ON ERROR statements
LOCKED statements
Description
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL
DUP.STATUS is on.
STATUS Function Return Values
276.5 Example
This example uses the following program to lock the CLIENT file for two minutes:
Notice that execution halts on the second program until the first program unlocks the record associated with
Smith. This is because commands that set exclusive locks cannot access records lock with any kind of lock.
READBCKU
311
OASYS
BUILD.INDEX, CREATE.INDEX, DEFAULT.LOCKED.ACTION, DUP.STATUS For information, see the OASYS
Commands Reference.
277 READFWD
Enter topic text here.
277.1 Syntax
READFWD dyn.array.var [FROM file.var] [ON ERROR statements] {THEN statements [END] | ELSE statements
[END]}
277.2 Description
The first READFWD command retrieves the alternate key set by SETINDEX, and then each subsequent
READFWD retrieves the next alternate key value in the index. OASYS reads the corresponding record into a
dynamic array, and then assigns the record ID to the @ID variable.
Note: This command does not check for locks. If you are operating in a multiuser environment, you must use
record locks to prevent more than one user from accessing the same record at the same time. For more
information about the OASYS Basic record locking, see Developing OASYS Basic Applications.
Using this command in a loop, a OASYS Basic program retrieves records in ascending order based on an indexed
attribute.
Before executing READFWD, you must set a pointer to an alternate key value with the SETINDEX command. The
SETINDEX parameters BUFFER.KEYS and VALIDATE.KEY determine, respectively, whether the buffering
mechanism is used and whether keys are validated when READFWD executes. For details, see SETINDEX.
READFWD sets the STATUS function return value to 10 if OASYS Basic detects a duplicate alternate index key
value and you have executed the ECL command DUP.STATUS ON during the current session.
277.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.var
FROM file.var
312
ON ERROR statements
Description
0
10
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL
DUP.STATUS is on.
STATUS Function Return Values
277.5 Example
In the following example, the program segment sets the index to the first record that contains Smith, and then
reads that record and the next four:
Note: This program reads the records even if the records are locked by other users.
READFWD
313
277.7 UniData
BUILD.INDEX, CREATE.INDEX, DUP.STATUS For information, see the OASYS Commands Reference.
278 READFWDL
Enter topic text here.
278.1 Syntax
READFWDL dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
[END] | ELSE statements [END]}
READFWDL dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
[END] | ELSE statements [END]}
278.2 Description
The first READFWDL command retrieves the alternate key set by SETINDEX, and then each subsequent
READFWDL retrieves the next alternate key value in the index. OASYS reads the corresponding record into a
dynamic array, and then assigns the record ID to the @ID variable. READFWDL checks for locks. If the record is
available, it sets a shared (L) lock.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Using this command in a loop, a OASYS Basic program retrieves records in ascending order based on an indexed
attribute.
Before executing READFWDL, you must set a pointer to an alternate key value with the SETINDEX command.
The SETINDEX parameters BUFFER.KEYS and VALIDATE.KEY determine, respectively, whether the buffering
mechanism is used and whether keys are validated when READFWDL executes. For details, see SETINDEX.
READFWDL sets the STATUS function return value to 10 if OASYS Basic detects a duplicate alternate index key
value and you have executed the ECL command DUP.STATUS ON during the current work session.
278.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.var
FROM file.var
ON ERROR statements
314
LOCKED statements
Description
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL DUP.
STATUS is on.
STATUS Function Return Values
278.5 Example
This example uses the following program to lock the CLIENT file for two minutes:
Notice that execution halts on the second program until the first program unlocks the CLIENTS file. This is
because commands that set shared locks cannot access files locked with exclusive locks (FILELOCK sets an
exclusive lock).
Note: If the first program had set a shared lock, the second program would have been able to read the records.
READFWDL
315
SETINDEX
OASYS
BUILD.INDEX, CREATE.INDEX, DEFAULT.LOCKED.ACTION, DUP.STATUS For information, see the OASYS
Commands Reference.
279 READFWDU
Enter topic text here.
279.1 Syntax
READFWDU dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
[END] | ELSE statements [END]}
READFWDU dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
[END] | ELSE statements [END]}
279.2 Description
The first READFWDU command retrieves the alternate key set by SETINDEX, and then each subsequent
READFWDU retrieves the next alternate key value in the index. OASYS reads the corresponding record into a
dynamic array, and then assigns the record ID to the @ID variable. READFWDU checks for locks. If the record is
available, READFWDU sets an exclusive (U) lock before reading the record.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Using this command in a loop, a OASYS Basic program retrieves records in ascending order based on an indexed
attribute.
Before executing READFWDU, you must set a pointer to the alternate key value with the SETINDEX command.
READFWDU sets the STATUS function return value to 10 if OASYS Basic detects a duplicate alternate index
key value and you have executed the ECL command DUP.STATUS ON during the current work session.
279.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
ON ERROR statements
Description
Specifies a dynamic array to contain the record.
Specifies a file from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
Specifies statements to execute if the READFWDU statement
fails with a fatal error because the file is not open, an I/O error
occurs, or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
316
LOCKED statements
Description
0
10
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL
DUP.STATUS is on.
STATUS Function Return Values
279.5 Example
This example uses the following program to lock the CLIENT file for two minutes:
Notice that execution halts on the second program until the first program unlocks the record associated with
Smith. This is because commands that set exclusive locks cannot access records lock with any kind of lock.
READFWDU
317
SETINDEX
OASYS
BUILD.INDEX, CREATE.INDEX, DEFAULT.LOCKED.ACTION, DUP.STATUS For information, see the OASYS
Commands Reference.
280 READL
Enter topic text here.
280.1 Syntax
READL dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
statements [END] | ELSE statements [END]}
READL dyn.array.var FROM [file.var,] record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
statements [END] | ELSE statements [END]}
280.2 Description
The OASYS Basic READL command reads the specified record from a file and assigns its contents to a dynamic
array. OASYS assigns the first attribute of the record to the first position of the array, the second attribute to the
second position, and so on. READL checks for locks. If the record is available, it sets a read-only lock on the
record, preventing other lock-checking commands from updating it.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Warning: Do not use OASYS Basic READ and WRITE commands to open or modify binary data in DIR-type files
(for example, BP). Doing so could corrupt data in the file. Instead, use OSREAD or OSBREAD after executing
the OASYS Basic NOCONVERT command.
280.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
ON ERROR statements
LOCKED statements
Description
Specifies a dynamic array to receive the record.
Specifies a file from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
Specifies statements to execute if the READL statement fails
with a fatal error because the file is not open, an I/O error occurs,
or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
Specifies statements to execute if the record is locked by another
user (with an exclusive lock). If you do not specify a LOCKED
clause, the program waits until the lock on the record is released.
Use the ECL command DEFAULT.LOCKED.ACTION BELL
to make the terminal beep while you wait for OASYS to unlock
the record.
318
Description
0
1
n
Successful read.
OASYS was unable to read the record.
The record is locked. The user number of the user who locked the
record.
STATUS Function Return Values
280.5 Examples
This example uses the following program to lock the ORDERS file for two minutes:
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
281 READLIST
Enter topic text here.
READLIST
319
281.1 Syntax
READLIST dyn.array.var [FROM list.num] {THEN statements [END] | ELSE statements [END]}
281.2 Synonym
READSELECT (BASICTYPE P only)
281.3 Description
The OASYS Basic READLIST command assigns the values in an active select list to a dynamic array. Each select
list element becomes an attribute in the dynamic array.
Note: Use the following syntax in BASICTYPE M:
READLIST dyn.array.var FROM list.num [, acct.name] [SETTING count.var] {THEN statements [END] | ELSE
statements [END]}
If you create a list under an account other than the current one, you can specify the account with acct.name.
The SETTING clause sets the number of elements in the list to count.var.
In BASICTYPE P, use the READSELECT command with the following syntax:
READSELECT dyn.array.var [FROM list.name] {THEN statements [END] | ELSE statements [END]}
281.4 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.var
FROM list.num
281.5 Example
In the following example, the program segment selects the IDs in the INVENTORY file to select list 0, and then
builds a dynamic array of the items for which quantity in stock is greater than 10. The last program statement
prints the select list to show its contents.
320
UniQuery
DELETE.LIST, GET.LIST, SELECT, SAVE.LIST, SSELECT For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
282 READNEXT
Enter topic text here.
282.1 Syntax
READNEXT id.var [, val.var[, subval.var]] [FROM list.num.expr] [ON ERROR statements] {THEN statements
[END] | ELSE statements [END]}
282.2 Description
The OASYS Basic READNEXT command assigns the next record ID from an active select list to a variable.
Note: READNEXT does not actually read the record, but assigns it to a variable. After the variable is assigned,
you can use it within a READ statement to access it.
As an example, a customer transaction might require that data be read in a particular sequence. The sequence is
determined by using a sorted SELECT statement to select IDs in the appropriate order and then using the
READNEXT statement to assign an ID to a variable.
Note: READNEXT performs differently with BASICTYPEs M and P as shown in the following syntax:
READNEXT var FROM list.name {, acct.name}[SETTING count.var] {THEN statements [END] | ELSE
statements [END]}
The SETTING clause assigns the number of elements in the list to the variable count.var.
READNEXT
321
282.3 Parameters
The following table describes each parameter of the syntax.
Parameter
id.var
,val.var,subval.var
FROM list.num.expr
Description
Specifies a variable to contain the value of the next record ID.
Specifies a value and subvalue to read.
Specifies which select list (0-9) you want to use. If you do not
specify list.num, the default (0) list is used. If no items are
available in the list, OASYS executes the ELSE clause.
READNEXT Parameters
Parameter
Description
ON ERROR statements
322
282.4 Examples
In the following example, the program segment reads 10 IDs from select list 1, and then reads the records
associated with those IDs. If a record ID is not found in the default system file, the program displays the message
NOT FOUND.
In the next example, the program selects all Canadian clients, and then executes READNEXT to read and display
the records for the first 22:
UniQuery
DELETE.LIST, GET.LIST, SAVE.LIST, SELECT, SSELECT For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
283 READNEXTTUPLE
Enter topic text here.
283.1 Syntax
READNEXTTUPLE dyn.array.var FROM file.name.expr {THEN statements [END] | ELSE statements [END]}
READNEXTTUPLE
323
283.2 Description
The OASYS Basic READNEXTTUPLE command assigns the next entire record to a variable. The record ID is
obtained from an active select list that was created by a OASYS SQL SELECT statement during the current work
session.
READNEXTTUPLE creates a dynamic array delimited by attribute marks (@AM). The attribute marks are entered
by the OASYS SQL SELECT statement.
Tip: Do not use the OASYS SQL UNNEST command in the SQL statement that creates the ID list. OASYS might
not return the entire record with attribute marks, value marks, and/or subvalue marks if you use UNNEST.
283.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.var
FROM file.name.expr
283.4 Example
In the following example, the program segment executes a OASYS SQL statement and stores the output in an
internal result file called SQL_INPUT. The READNEXTTUPLE statement then reads the records stored in
SQL_INPUT until the last record item is read. The process converts the attribute marks to spaces and prints each
record read.
324
OASYS SQL
SELECT For information, see Using OASYS SQL.
284 READSELECT
READSELECT is a synonym for the READLIST command. For more information, see READLIST.
284.1 Synonym
READLIST
285 READSEQ
Enter topic text here.
285.1 Syntax
READSEQ var FROM seq.file.var {THEN statements [END] | ELSE statements [END]}
285.2 Description
The OASYS Basic READSEQ command reads the next record from a sequential file and assigns the data read to a
variable.
Note: Before you use READSEQ, you must open the file by using the OSOPEN or OPENSEQ command.
If the file is a named pipe, you cannot use READSEQ to read it. You must use the OSBREAD command.
Each read from the sequential file searches for a line feed character [CHAR(10)] to determine the end of the
2012 Onsystex Corp.
READSEQ
325
record. READSEQ maintains a pointer to the current position in the file (where the last record terminated).
285.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
Description
Specifies a variable to which to assign the record.
READSEQ Parameters
285.4 Example
In the following example, the program statement reads the next record in the file PORT.FILE and assigns it to the
variable TAX.REC:
286 READT
Enter topic text here.
286.1 Syntax
READT [UNIT (mu.expr)] var {THEN statements [END] | ELSE statements [END]}
286.2 Description
The OASYS Basic READT command reads the next record from a tape and assigns it to a variable.
Note: Before you use the READT command, you must attach a tape drive with the T.ATT command. For
information about tape commands, see the OASYS Commands Reference. You must use the TAPELEN option for
the T.
ATT command and specify the length of the tape in megabytes. This command is intended for use with OASYS
tapes only.
OASYS uses the ASCII 0 character (CHAR(0)) as an end-of-record mark. Therefore, you cannot use ASCII 0 in
any string variable in OASYS Basic. READT converts (CHAR(0)) to CHAR(128).
286.3 Parameters
The following table describes each parameter of the syntax.
Parameter
2012 Onsystex Corp.
Description
326
UNIT (mu.expr)
var
THEN statements END
ELSE statements END
Specifies the conversion code (first digit), and the unit number
(second digit). OASYS allows unit numbers from 0 through 9.
mu.expr is optional. The default value is 00, indicating tape unit 0
and no conversion:
0 No conversion (ASCII assumed)
1 EBCDIC conversion
2 Invert high bit
3 Swap bytes
Specifies a variable to contain the record.
THEN executes if the read is successful. END is required to
terminate multiline THEN statements.
ELSE executes if the read is not successful or the record does not
exist. END is required to terminate multiline ELSE statements.
READT Parameters
Description
0
1
2
3
Successful read.
End of file encountered.
End of tape encountered.
Tape not assigned.
STATUS Function Return Values
Value
Description
4
Parity error.
5
Unknown hardware error.
6
Other unspecified error.
STATUS Function Return Values (continued)
286.4 Example
In the following example, the program segment first uses the ECL T.ATT command to reserve tape unit 0 and
perform no conversion. Then the program segment reads all the records on the tape (until the end of the file or
tape) and calls an internal subroutine that processes the record.
OASYS
SETTAPE, T.ATT, T.DET For information, see the OASYS Commands Reference.
2012 Onsystex Corp.
READT
327
287 READU
Enter topic text here.
287.1 Syntax
READU dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
statements [END] | ELSE statements [END]}
READU dyn.array.var FROM [file.var,] record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
statements [END] | ELSE statements [END]}
287.2 Description
The OASYS Basic READU command reads a record from a file and assigns its contents to a dynamic array.
READU checks for locks. If the record is available, it sets an exclusive lock and reads the record.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Warning: Do not use OASYS Basic READ and WRITE commands to open or modify binary data in DIR-type files
(for example, BP). Doing so could corrupt data in the file. Instead, use OSREAD or OSBREAD after executing
the OASYS Basic NOCONVERT command.
287.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var,
record.ID.expr
ON ERROR statements
LOCKED statements
Description
Specifies a dynamic array to contain the record.
Specifies the file variable from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
Specifies the record ID to use to retrieve the record.
Specifies statements to execute if the READU statement fails
with a fatal error because the file is not open, an I/O error occurs,
or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
Specifies statements to execute if the record is locked by another
user. If you do not specify a LOCKED clause, the program waits
until the lock on the record is released.
Use the ECL command DEFAULT.LOCKED.ACTION BELL
to make the terminal beep while you wait for OASYS to unlock
the record.
THEN executes if the read is successful. END is required to
terminate multiline THEN statements.
ELSE executes if the read is not successful or the record (or ID)
does not exist. END is required to terminate multiline ELSE
statements.
READU Parameters
328
Description
0
1
n
Successful read.
OASYS was unable to read the record.
The record is locked. The user number of the user who locked
the file is returned in n.
STATUS Function Return Values
287.5 Examples
The following program segment is taken from the sample program in Appendix A, Sample Programs, in
Developing OASYS Basic Applications. READU checks for locks. If the record is available, it sets an exclusive
lock and reads the record into ORDER.REC.
The record remains locked until the following program executes, which releases locks:
In the following example, the program segment assigns the record, read from the default file, to the variable INFO,
and sets an exclusive lock on that record. OASYS prints Record locked if the record is locked by another
program, or prints File not found if the record does not exist. If the default file is not found, the program ends.
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
288 READV
Enter topic text here.
READV
329
288.1 Syntax
READV var FROM [file.var,] record.ID.expr, attribute.expr [ON ERROR statements] {THEN statements [END] |
ELSE statements [END]}
288.2 Description
The OASYS Basic READV command assigns the data from an attribute of a record to a variable.
Note: READV ignores locks. To update a record, you should use the READVU command, which checks for
locks. For an explanation of OASYS locks, see Developing OASYS Basic Applications..
Tip: To improve efficiency, use READV when only one or two attributes are needed from a record. If access to
more attributes is needed, READ or MATREAD is more efficient.
288.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var
FROM file.var,
record.ID.expr
attribute.expr
Parameter
Description
ON ERROR statements
288.4 Examples
In the following example, the program segment reads CLIENT.NAME from the CLIENTS file, record ID 10034,
attribute 2. If the record exists, OASYS appends the attribute to string NAME.ARRAY1 using the short form of
the replace command. Otherwise, OASYS executes the ELSE clause.
330
n the next example, you can use the READV command with an attribute.expr of 0 to verify that a record exists (for example, if you
ID, you need to verify that the ID you selected is not in use. The following code accomplishes this task, incrementing the ID until an ID is available.
289 READVL
Enter topic text here.
289.1 Syntax
READVL var FROM [file.var,] record.ID.expr, attribute.expr [ON ERROR statements] [LOCKED statements]
{THEN statements [END] | ELSE statements [END]}
READVL var FROM [file.var,] record.ID.expr, attribute.expr [LOCKED statements] [ON ERROR statements]
{THEN statements [END] | ELSE statements [END]}
289.2 Description
The OASYS Basic READVL command assigns the data from an attribute of a record to a variable. READVL
checks for locks. If the record is available, it sets a shared lock before it reads the record.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications
You generally use the READVL command when only one or two attributes are needed from a record. If access to
more attributes is needed, READ or MATREAD is more efficient.
289.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
Description
Specifies the variable to contain the attribute.
READVL
FROM file.var,
record.ID.expr
attribute.expr
ON ERROR statements
LOCKED statements
331
289.4 Example
In the following example, READVL checks for locks on the record CARS in the default file. If the record is
available, it sets a shared lock and reads the third attribute of the record. If the data is not found, OASYS displays
the message NOT FOUND.
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
290 READVU
Enter topic text here.
290.1 Syntax
READVU var FROM [file.var,] record.ID.expr, attribute.expr [ON ERROR statements] [LOCKED statements]
{THEN statements [END] | ELSE statements [END]}
332
READVU var FROM [file.var,] record.ID.expr, attribute.expr [LOCKED statements] [ON ERROR statements]
{THEN statements [END] | ELSE statements [END]}
290.2 Description
The OASYS Basic READVU command assigns the data from an attribute of a record to a variable. READVU
checks for locks. If the record is available, it sets an exclusive lock before it reads the record.
Tip: You can improve efficiency by using the READVU command when you need only one or two attributes from
a record. If more attributes are necessary, or if you need to update more attributes, use the READU or
MATREADU commands.
OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
290.3 Examples
The following program segment is taken from Appendix A, Sample Programs, in Developing OASYS Basic
Applications. READVU checks for locks. If the record is available, it sets an exclusive lock and reads the
multivalued attribute containing the order number the user wants to delete.
In the next example, the program segment reads the seventh attribute of the record named in the variable ID from
the INV file and stores the attribute in the variable SUPPL. If the record is locked, or if the default file cannot be
found, OASYS displays a read-error message.
290.3.1 Parameters
The following table describes each parameter of the syntax.
Parameter
var
FROM file.var,
record.ID.expr
attribute.expr
ON ERROR statements
Description
Specifies a variable to contain the data read from the attribute.
Specifies the file from which to read the attribute.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
Specifies a record in the file from which to read the data.
Specifies an attribute within the file from which to read the data.
Specifies statements to execute if the READVU statement fails
with a fatal error because the file is not open, an I/O error occurs,
or OASYS cannot find the file.
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
READVU
LOCKED statements
333
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
291 READXBCK
Enter topic text here.
291.1 Syntax
READXBCK dyn.array.var [FROM file.var] [ON ERROR statements] {THEN statements [END] | ELSE statements
[END]}
291.2 Description
The OASYS Basic READXBCK command reads the previous key in an alternate key index in much the same
manner as the READBCK command, but does not read the associated record. READXBCK enables a program to
read alternate keys without incurring the overhead of retrieving a record every time.
291.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
Description
Specifies a dynamic array to which to assign the values read.
Specifies the file from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
READXBCK Parameters
334
Parameter
Description
ON ERROR statements
OASYS
BUILD.INDEX, CREATE.INDEX For information, see the OASYS Commands Reference.
292 READXFWD
Enter topic text here.
292.1 Syntax
READXFWD dyn.array.var [FROM file.var] [ON ERROR statements] {THEN statements [END] | ELSE statements
[END]}
292.2 Description
The OASYS Basic READXFWD command reads the next value in an alternate key index in much the same manner
as the READFWD command, but does not read the associated record. READXFWD enables a program to read
alternate keys without incurring the overhead of retrieving a record every time.
292.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
FROM file.var
Description
Specifies a dynamic array to which to assign the values read.
Specifies the file from which to read the record.
If you do not specify a file.var, OASYS reads from the default
file. If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
READXFWD Parameters
READXFWD
Parameter
335
Description
ON ERROR statements
OASYS
BUILD.INDEX, CREATE.INDEX For information, see the OASYS Commands Reference.
293 RECORDLOCKED
Enter topic text here.
293.1 Syntax
RECORDLOCKED (file.var, rec.id.expr)
293.2 Description
The OASYS Basic RECORDLOCKED function returns the lock status of the specified record or file. For an
explanation of OASYS locks, and for a sample program you can use to test this command, see Developing OASYS
Basic Applications.
293.3 Parameters
The following table describes each parameter of the syntax.
Parameter
file.var
Description
Specifies the file on which to check lock status. The null value in file.var
336
Lock Type
exclusive
Lock Owner
you
shared
you
exclusive
you
shared
you
0
-1
-2
exclusive
-3
shared
-4
exclusive
Locking Command
FILELOCK, SQL LOCK TABLE,
implicit SQL TP lock escalation.
FILELOCK, SQL LOCK TABLE,
implicit SQL TP lock escalation.
READU, RECORDLOCKU, SQL
TP implicit record locking.
READL, RECORDLOCKL, SQL
TP implicit record locking.
Note: When CUST.OPTIONS 35 is on, this function returns a value of -2 when another user has a READU lock
on the record or file.
0
-1
RECORDLOCKED
Return Value
A number between -1 and 4.
0
-11
-2
-12
-3
-13
Meaning
The record is locked. The user number of the user
who owns the lock is returned in n.
The record is not locked.
The file is NFA. Currently, RECORDLOCKED
does not support NFA files.
Invalid file type. file.var can contain the null
value.
System error: unknown user.
RECORDLOCKED
337
294 RECORDLOCKL
Enter topic text here.
294.1 Syntax
RECORDLOCKL [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements]
294.2 Description
The OASYS Basic RECORDLOCKL command checks for record locks. If the record is available, it sets a shared
lock on the record. For an explanation of OASYS locks, and for a sample program that you can use to test this
command, see Developing OASYS Basic Applications.
294.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var,
Parameter
Description
record.ID.expr
ON ERROR statements
LOCKED statements
338
294.4 Examples
In the following example, the program statement sets a shared lock on the record HOLLY in the default file. If the
record is already locked by another user, the program waits until the record is released.
In the next example, the program segment sets a lock on the record with the ID Smith from file CLIENT.FILE. If the
record is locked, OASYS displays the message THE RECORD IS ALREADY LOCKED.
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
295 RECORDLOCKU
Enter topic text here.
295.1 Syntax
RECORDLOCKU [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements]
295.2 Description
The OASYS Basic RECORDLOCKU command checks for record locks. If the record is available, it sets an
exclusive lock on the record. For an explanation of OASYS locks, and for a sample program that you can use to
test this command, see Developing OASYS Basic Applications.
RECORDLOCKU
295.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var,
Parameter
Description
record.ID.expr
ON ERROR statements
LOCKED statements
OASYS
DEFAULT.LOCKED.ACTION For information, see OASYS Commands Reference.
339
340
296 RELEASE
Enter topic text here.
296.1 Syntax
RELEASE [file.var [, record.ID.expr]] [ON ERROR statements]
296.2 Description
The OASYS Basic RELEASE command unlocks records and files locked by the same user process. If no files or
records are locked, RELEASE has no effect.
Tip: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
296.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var
,record.ID.expr
ON ERROR statements
296.4 Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, of
Developing OASYS Basic Applications. In this program, the WRITE statement unlocks records so that locks are
retained only as long as required. However, some error conditions could result in processing returning to the
main routine with a record still locked. For this reason, the program segment includes a RELEASE statement.
RELEASE
341
In the next example, the program statement releases the record COLO in the file CONTACTS. Other locked
records in this file remain locked.
297 REM
Enter topic text here.
297.1 Syntax
REM [comment text]
297.2 Synonyms
!, *
Note: REM is also a synonym for the MOD function. For more information, see MOD.
297.3 Description
The OASYS Basic REM command enables you to enter remarks in a program. You can enter the comment on a
line by itself by entering the comment command followed by text. You also can enter a comment on a line that
contains another OASYS Basic command by preceding the comment command with a semicolon.
Tip: In structured programming, a single command is entered on each line. This makes programs easier to read
and maintain.
297.4 Example
In the following example, comments describe the subroutines functionality. The program uses !, *, and REM.
342
298 REMOVE
Enter topic text here.
298.1 Syntax
REMOVE var FROM dyn.var [AT col.pos] SETTING delim.var
298.2 Description
The OASYS Basic REMOVE command extracts an element from a dynamic array and assigns the removed
element to a variable. REMOVE does not change the value of the dynamic array. REMOVE supports multibyte
languages.
REMOVE searches a dynamic array for system delimiters. When OASYS finds a delimiter, it assigns the contents
of the array element and the delimiter to the variable. OASYS maintains a pointer to the last substring you remove
so that successive REMOVE statements move progressively through a dynamic array.
Tip: Use REMOVE to sequentially process the elements of a dynamic array.
298.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
Description
Specifies the element to contain the extracted array element.
REMOVE Parameters
Parameter
Description
FROM dyn.var
AT col.pos
REMOVE
343
elements.
This position is the number of characters, including system
delimiters, from the beginning of the array. To process the entire
array, set col.pos to 1 (0 defaults to 1). The value of col.pos
changes as the array is processed, indicating the current position of
the pointer.
SETTING delim.var
The SETTING clause assigns the variable delim.var a value based on the type of delimiter encountered. The
following table describes the values of the delimiter codes.
Delimieter
Code
0
1
2
3
4
5
6
7
Description
ASCII Value*
array end
record mark
attribute mark
value mark
subvalue mark
text mark
not used; nonprinting
not used; nonprinting
255
254
253
252
251
250
249
298.4 Examples
In the following example, the program segment processes the dynamic array CLIENT:
Notice that each element in the array VAR contains the extracted array element and the associated delimiter.
2012 Onsystex Corp.
344
In the next example, the program segment starts at the beginning of the array AMOUNTS, successively removes
each element from the array, calculates a 3.5 percent tax amount, and adds it into the variable TAX.AMT. When
MARK = 0 (delim.var is 0), processing terminates.
In the next example, the program segment demonstrates the difference between OASYS Basic and other
implementations of BASIC:
In the next example, the program segment compares processing time for the REMOVE statement versus the
EXTRACT statement:
REMOVE
345
299 REMOVE
Enter topic text here.
299.1 Syntax
REMOVE(dyn.array.var, delim.var)
299.2 Description
The OASYS Basic REMOVE function extracts an element from a dynamic array and assigns the removed element
to a variable. REMOVE does not change the value of the dynamic array.
346
REMOVE searches a dynamic array for system delimiters. When OASYS finds a delimiter, it assigns the contents
of the array element and the delimiter to the variable. OASYS maintains a pointer to the last substring you remove
so that successive REMOVE statements move progressively through a dynamic array.
The REMOVE function performs the same action as the REMOVE command, but you cannot use it to specify a
starting position.
Tip: Use REMOVE to sequentially process the elements of a dynamic array.
299.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array.var
delim.var
Description
Specifies a dynamic array from which to remove elements.
Specifies the delimiter code. When the end of the array is encountered,
delim.var is set to 0.
REMOVE Parameters
The variable delim.var is assigned a value based on the type of delimiter encountered. The following table
describes the values of the delimiter codes.
Delimiter
Code
0
1
2
3
4
5
6
7
Description
ASCII Value*
array end
record mark
attribute mark
value mark
subvalue mark
text mark
nonprinting; not used
nonprinting; not used
255
254
253
252
251
250
249
300 REPLACE
Enter topic text here.
300.1 Syntax
REPLACE(dyn.array.expr, attrib.expr, val.expr, subval.expr, replace.expr)
dyn.array.expr<attrib.expr, val.expr, subval.expr> = replace.expr
REPLACE
347
300.2 Description
The OASYS Basic REPLACE function replaces data in a dynamic array with an expression.
If an attribute, value, or subvalue is less than 0, the replacement string is placed after the last attribute, value, or
subvalue as appropriate. If the position given does not exist (for example, attribute 6 specified in an array with
two attributes), the necessary number of attribute, value, and subvalue marks are added to create the specified
position.
300.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array.expr
attrib.expr
val.expr
subval.expr
replace.expr
REPLACE Parameters
300.4 Examples
In this example, the program statement replaces the first value of attribute 2 with the value 220 W. 44TH:
In the next example, the program segment replaces Blue with the null value in STG, prints STG, then replaces
the null value with Blue in STG, and prints STG again. The subroutine PRINT.SETUP converts attribute marks,
value marks, and the null value to characters that can be displayed and printed.
348
In the next example, the first REPLACE places Harry Smith in the first attribute position. The second REPLACE
places an array with two values in the fifth attribute
In the following example, the program uses the short form of the REPLACE command to append CLIENT.NAME
to NAME.ARRAY1:
301 RESIZET
Enter topic text here.
RESIZET
349
301.1 Syntax
RESIZET [UNIT(mu.expr)] expr {THEN statements [END] | ELSE statements [END]}
301.2 Description
The OASYS Basic RESIZET command changes the block size the WRITET command uses. When OASYS
processes a variable length record, the record length is less than the block length and OASYS fills the remaining
portion of the block with blanks.
Tip: Use this command when the block size in a file is not the same as the block size in T.ATT.
301.3 Parameters
The following table describes each parameter of the syntax.
Paragraph
Description
UNIT(mu.expr)
expr
THEN statements END
ELSE statements END
301.4 Example
In the following example, the program segment changes the block size the WRITET statement uses for the length
of REC:
OASYS
SETTAPE, T.ATT, T.DET For information, see the OASYS Commands Reference.
350
302 RETURN
Enter topic text here.
302.1 Syntax
RETURN [TO label[:]]
302.2 Description
The OASYS Basic RETURN command transfers program control from a subroutine back to the calling program or
subroutine.
The optional TO clause returns to a statement label. This clause is valid only for internal subroutine returns. If
you do not specify a TO clause, control passes to the statement immediately following the GOSUB or CALL
statement in the calling program or subroutine.
302.3 Example
The following externally cataloged subroutine is called by the sample program in Appendix A, Sample Program,
of Developing OASYS Basic Applications. The RETURN statement returns control to UPDATE_ORDERS.
303 REUSE
Enter topic text here.
303.1 Syntax
REUSE(dyn.array.expr)
303.2 Description
The OASYS Basic REUSE function affects the application of arithmetic operations on dynamic arrays.
REUSE
351
Array and constant When you apply an arithmetic operation to an array and a constant, the operation is
executed against only the first element of the array. If you want the operation to execute on every element in
the array, apply REUSE to the constant.
Two arrays When you execute an arithmetic operation on arrays of different lengths, the operation is
performed on the number of elements in the shortest array only. The remaining elements are each filled with 1
or 0, depending on the operation performed:
Division 1.
Addition, subtraction, and multiplication 0.
If you apply REUSE to the shorter array, the last element in this array is used to perform the operation on the
remaining elements in the longer array.
303.3 Examples
In the following example, the program segment multiplies the arrays without using the REUSE function:
VCOST takes its length from VIEWERS, the longest of the two arrays, but multiplication is performed on only the
first two elements of each array because the other array, COST, has only two elements. The final element in the
result array (VCOST) is filled with 0. 0 is used to fill because the arithmetic operation is multiplication.
However, if you apply the REUSE function to the shorter array:
The final element in COST (1) is used to multiply with the final element of VIEWERS and fill the final element of
the result array, VCOST.
304 REWIND
Enter topic text here.
304.1 Syntax
REWIND [UNIT(mu.expr)] {THEN statements [END] | ELSE statements [END]}
304.2 Description
The OASYS Basic REWIND command rewinds a tape.
352
Note: Before you can use the REWIND command, you must reserve a tape drive for use with the T.ATT
command. For information about ECL T.ATT, see the OASYS Commands Reference.
304.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
UNIT(mu.expr)
Specifies the conversion code (first digit), and the unit number
(second digit). OASYS allows unit numbers from 0 through 9.
The mu.expr is optional and the default value is UNIT (00) for
tape unit 0 with no conversion (ASCII assumed).
0 No conversion (ASCII assumed).
1 EBCDIC conversion.
2 Invert high bit.
3 Swap bytes.
THEN executes if the rewind is successful. END is required to
terminate multiline THEN statements.
ELSE executes if the rewind is not successful. END is required
to terminate multiline ELSE statements.
REWIND Parameters
304.4 Example
In the following example, the program segment first uses the ECL T.ATT command to reserve tape unit 0 and
specifies no conversion code. Then a routine reads all the records on the tape (until the end of the file or tape)
and calls an internal subroutine that processes the record. After the process is finished, the REWIND command
rewinds the tape.
OASYS
SETTAPE, T.ATT, T.DET For information, see the OASYS Commands Reference.
305 RND
Enter topic text here.
RND
353
305.1 Syntax
RND(num.expr)
305.2 Description
The OASYS Basic RND function returns a random integer from 0 through num.expr minus 1.
305.3 Example
In the following example, the program statement prints a random number from 0 through 9:
306 RNDSEED
Enter topic text here.
306.1 Syntax
RNDSEED expr
306.2 Description
The OASYS Basic RNDSEED command enables you to seed the pseudo random number generator. The RND
function gives you a different sequence of numbers each time. RNDSEED generates the same sequence of
random numbers each time you run a program with the same seed.
expr is a numeric seed point. Each time you use the same expr, RND generates the same sequence of random
numbers.
306.3 Example
In the following program segment, RND produces an array of random numbers to replace the values in VCOST.
Because RNDSEEN is a constant, this program always produces the same series of random numbers. Without
this statement, the program produces a different set of random numbers each time it is run.
354
307 RQM
RQM is a synonym for the SLEEP function. For more information, see SLEEP.
307.1 Synonym
SLEEP
308 SADD
Enter topic text here.
308.1 Syntax
SADD(x, y)
308.2 Description
The OASYS Basic SADD function adds two string numbers and returns the result as a string number. SADD is
the string addition function. Arguments can be any valid numbers or string numbers of any magnitude or
precision.
Tip: Processing string data type numbers rather than numeric data type numbers degrades processing speed.
Numbers specified in quotation marks are string data type. Numbers specified without quotation marks are
numeric data type. The data type in a variable is determined by the data first loaded into it.
If x or y contains nonnumeric data, OASYS displays an error message and returns a result of 0.
The SADD function results in a string number, so you can use the function in any expression in which a string
number is valid. Because string numbers can exceed the range of numbers that standard arithmetic operators can
accommodate, you might not want to use the SADD function in any expression in which a standard number is
valid.
Note: The result of the SADD function cannot exceed the maximum allowable number determined by your
hardware.
308.3 Example
In the following example, the program statement assigns to variable B the sum of the string constant (1.4149) and
variable A:
SCMP
355
309 SCMP
Enter topic text here.
309.1 Syntax
SCMP(x, y)
309.2 Description
The OASYS Basic SCMP function compares two string numbers and returns a value depending on the result of
the comparison. Arguments can be any valid numbers or string numbers of any magnitude or precision. If x or y
contains nonnumeric data, OASYS displays an error message, and the comparison returns 0.
Tip: Processing string data-type numbers rather than numeric data-type numbers degrades processing speed.
Numbers specified in quotation marks are string data type. Numbers specified without quotation marks are
numeric data type. The data type in a variable is determined by the data first loaded into it.
309.4 Example
In the following example, the program segment compares FA to FB. If the result of the IF statement is true (the
SCMP function returns 1), OASYS executes the PRINT statement.
310 SDIV
Enter topic text here.
310.1 Syntax
SDIV(x, y)
310.2 Description
The OASYS Basic SDIV function divides two string numbers and returns the result as a string number. SDIV
divides x by y. Arguments can be any valid numbers or string numbers of any magnitude or precision. However,
result precision is limited to 14 significant digits.
2012 Onsystex Corp.
356
Tip: Processing string data type numbers rather than numeric data type numbers degrades processing speed.
Numbers specified in quotation marks are string data type. Numbers specified without quotation marks are
numeric data type. The data type of a variable is determined by the data first loaded into it.
If x or y contains nonnumeric data, OASYS displays an error message, and the operation results in 0. If y is 0,
OASYS displays an error message that indicates you cannot divide by 0 and returns a result of 0.
The SDIV function results in a string number, so you can use the function in any expression in which a string is
required. Because the resulting string numbers can be longer than the arithmetic operator can accommodate, you
might not want to use the SDIV function in expressions requiring numeric data type.
310.3 Example
In the following example, the program statement divides the constant (1.4149) by variable A and assigns the
result to variable B:
311 SELECT
Enter topic text here.
311.1 Syntax
SELECT file.var [TO {list.num.expr | list.var.expr}] [ON ERROR statements]
SELECT dyn.array [TO {list.num.expr | list.var.expr}] [ON ERROR statements]
311.2 Description
The OASYS Basic SELECT command creates an active select list of all record IDs in a file. Records appear in the
list in the order in which they are stored in the file.
You can access the select list with a READNEXT statement.
The OASYS Basic SELECT command differs from EXECUTE "SELECT ...", which executes the UniQuery SELECT
command. The OASYS Basic SELECT command immediately makes available to READNEXT one group of IDs at
a time. The program does not have to wait for the entire ID list to be constructed.
If changes occur in a group that has not been selected yet, those changes are reflected in the select list that is
being read by the program. If an ID is deleted before the group is selected by the OASYS Basic program, that ID
does not appear in the list.
Record IDs are truncated at 96 characters when they are copied into the select list.
When using the UniQuery SELECT command, SYSTEM(11) returns the number of items remaining in the list.
With the OASYS Basic SELECT command, SYSTEM(11) returns the number of items remaining in the group.
Note: You can specify named or numbered lists (using list.num.expr or list.var.expr) in BASICTYPEs R and U.
Only named lists (list.var.expr) are supported in BASICTYPEs M and P.
SELECT
357
311.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
file.var
dyn.array
TO list.num.expr
TO list.var.expr
ON ERROR
statements
311.4 Examples
The following program segment places in select list 1 all record IDs in the CLIENTS file, and then prints the ID of
the first record:
The following sample program creates a select list that is named rather than numbered. This program is compiled
in BASICTYPE P, but compiles and runs in all BASICTYPEs.
358
In the following example, the program statement creates a list of all record IDs in the INVENTORY file in active
select list 0:
In the next example, the program segment first creates a list of all IDs in the ORDERS file and assigns the ID list to
list 1. It then uses the READNEXT command to read the IDs from the list sequentially, executing a subroutine,
PROCESS.ORDERS, each time.
UniQuery
DELETE.LIST, GET.LIST, SAVE.LIST, SELECT, SSELECT For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
SELECTINDEX
359
312 SELECTINDEX
Enter topic text here.
312.1 Syntax
SELECTINDEX index.name.expr[, key.val.expr] FROM file.var [TO list.num.expr]
312.2 Description
The OASYS Basic SELECTINDEX command creates a select list based on an alternate key index.
Note: SELECTINDEX is not supported with EDA files.
312.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
index.name.expr
, key.val.expr
FROM file.var
TO list.num.expr
SELECTINDEX Parameters
Description
The select list is loaded with alternate key values or record IDs for the specified file.
No alternate index key exists for this attribute using the name specified. The select
list is empty.
STATUS Function Return Values
312.5 Examples
The following program creates a select list based on alternate index LNAME, and then reads the record using the
first ID retrieved from that list:
360
In the following example, SELECTINDEX uses the alternate key index LNAME and creates a list of all the last
names contained in the CLIENTS file:
In the next example, SELECTINDEX uses the alternate key value Smith and creates a list of all occurrences of
Smith contained in the CLIENTS file:
UniQuery
DELETE.LIST, GET.LIST, SELECT, SSELECT, SAVE.LIST For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
313 SELECTINFO
Enter topic text here.
313.1 Syntax
SELECTINFO([list.num.expr,] 1)
313.2 Description
The OASYS Basic SELECTINFO function returns the state of a select list. list.num.expr is an expression
evaluating to the number of the select list (0-9).
313.3 Parameters
The following table describes each parameter of the syntax.
SELECTINFO
Parameter
list.num.expr
1
361
Description
The select list number (0-9).
The only code.expr currently implemented is 1, which returns the values
described in the following table.
SELECTINFO Parameters
Description
The select list you specify is active.
The select list you specify is not active.
The select list does not exist, or code.expr is not valid, or (in BASICTYPE P)
list.num.expr is not a list variable.
SELECTINFO Function Return Values
UniQuery
DELETE.LIST, GET.LIST, SAVE.LIST, SELECT, SSELECT For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
314 SEND
Enter topic text here.
314.1 Syntax
SEND[X] expr[:expr2...] [:] TO line.expr {THEN | ELSE} statements [END]
314.2 Description
The OASYS Basic SEND command sends output data to a specified line. You usually use SEND after a line is
attached.
314.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
362
Note: SEND with the X option suppresses the output of return/line feed. However, you cannot include both
quotation marks and the colon (:) in the same statement.
314.4 Examples
In the following example, the program statement sends the string to line 0 unless line 0 is not attached. If line 0 is
not attached, OASYS displays the message Line not attached.
In the next example, the program statement converts the string to HELLO WORLD before sending it to line 0:
315 SEQ
Enter topic text here.
315.1 Syntax
SEQ("char.expr")
315.2 Description
The OASYS Basic SEQ function converts a single character to its ASCII code value. The SEQ function is the
complement of the CHAR function. SEQ supports multibyte languages.
2012 Onsystex Corp.
SEQ
363
Tip: Use SEQ(@NULL) to determine the ASCII code that represents the null value on your system.
315.3 Example
In the following example, the program statement prints the ASCII code corresponding to the character # (in this
case, 35):
316 SEQS
Enter topic text here.
316.1 Syntax
SEQS("char.expr")
316.2 Description
The OASYS Basic SEQS function converts the first character in each element of a dynamic array to its ASCII
code value. SEQS supports multibyte languages.
316.3 Example
In the following example, the program statement prints the ASCII code corresponding to the value in each
element of the dynamic array ARR1. The result is 65}66}67}68.
317 SETENV
Syntax
SETENV(var_name, value)
2012 Onsystex Corp.
364
Description
Use the SETENV function to set an environment variable from OASYS Basic.
Parameters
The following table describes each parameter of the syntax.
Parameter
Description
var_name
value
Return Codes
The following table describes the SETENV return codes.
Return Code
0
-1
Description
Setting the environment variable was successful.
Setting the environment variable was not successful.
SETENV Return Codes
318 SETINDEX
Enter topic text here.
318.1 Syntax
SETINDEX index.name.expr [, [rop] key.val.expr [, id.expr]] [ON file.var] [BUFFER.KEYS {ON | OFF}]
[VALIDATE.KEY {ON | OFF}]
318.2 Description
The OASYS Basic SETINDEX command sets a pointer to a key in an alternate key index.
Note: The FILEINFO function, specifically FILEINFO(file.var,21), returns the current alternate key value.
OASYS Basic maintains index.name.expr for READBCK or READFWD, and related statements. Normally, you
should use the following relational (rop) operators:
Before READBCK statements: LT, LE, LAST_ALT_KEY
Before READFWD statements: GT, GE, EQ, FIRST_ALT_KEY, NULLVAL_ALT_KEY
Note: You can point to only one alternate index at a time. Each time you use SETINDEX, the current value is
reset and the subsequent READFWD/READBCK statement reads the record associated with the newly selected
index.
318.3 Parameters
The following table describes each parameter of the syntax.
SETINDEX
Parameter
365
Description
index.name.expr
rop Operators
The following table describes the valid rop operators.
Operator
EQ
GT
GE
LT
LE
FIRST_ALT_KEY
366
0
1
2
318.5 Examples
In the following example, the program segment sets the pointer at the first occurrence of the data element
containing Miller in the alternate index LNAME:
The following series of examples demonstrates the use of SETINDEX to set the record pointer to the first null key
in the PROD_NAME alternate key index:
This program produces the following result when no null values exist in the PROD_NAME index:
After the null value is inserted into the PROD_NAME attribute for records 10008 and 56060, this same program
produces the following results:
The following program demonstrates the use of SETINDEX to set the record pointer to the first non-null key in
the PROD_NAME alternate key index by specifying rop operator FIRST_ALT_KEY:
SETINDEX
367
Next, run this program using the INVENTORY file that you modified to contain null values in the PROD_NAME
attribute for records 10015 and 10238. The following output results.
Tip: You would obtain this same output if the INVENTORY file contained no null values in PROD_NAME and
you specified rop NULLVAL_ALT_KEY.
OASYS
BUILD.INDEX, CREATE.INDEX For information, see the OASYS Commands Reference.
319 SIN
Enter topic text here.
319.1 Syntax
SIN(num.expr)
319.2 Description
The OASYS Basic SIN function returns the trigonometric sine of the numeric expression num.expr.
319.3 Examples
In the following example, the program segment assigns the sine of the number 25 to the variable SIN.X. The result
is 0.4226.
In the next example, the program statement prints 1.0000, the sine of 90:
368
320 SLEEP
Enter topic text here.
320.1 Syntax
SLEEP [hh:mm[:ss]] [seconds]
320.2 Synonym
RQM
320.3 Description
The OASYS Basic SLEEP and RQM commands halt program execution for the time specified in seconds, or until
the time specified.
Tip: You can use SLEEP or RQM if you want a processing or reporting program to wait until midnight before
running to better use system resources. SLEEP is also useful when waiting for the release of locked system
resources.
Note: The original purpose of RQM was to release remaining execution time reserved for a program, allowing
other programs to use the time. If a particular program is very computation-intensive, RQM could improve
overall system performance.
320.4 Parameters
The following table describes each parameter of the syntax.
Parameter
hh:mm:ss
seconds
Description
Specifies the time to end sleep in hours, minutes, and (optional) seconds.
You must surround the time in quotation marks.
Specifies the number of seconds to sleep.
SLEEP Parameters
320.5 Examples
In the following example, the program statement halts program execution for 10 seconds:
In the next example, the program statement suspends program execution until 11:45 PM:
SLEEP
369
In the next example, the program statement halts program execution for one second:
321 SMUL
Enter topic text here.
321.1 Syntax
SMUL(x, y)
321.2 Description
The OASYS Basic SMUL function multiplies two string numbers and returns the result as a string number.
Arguments can be any valid numbers or string numbers of any magnitude or precision. Using string numbers
rather than standard numbers degrades processing speed.
If x or y contains nonnumeric data, OASYS displays an error message and returns a result of 0.
Tip: Processing string data type numbers rather than numeric data type numbers degrades processing speed.
Numbers specified in quotation marks are string data type. Numbers specified without quotation marks are
numeric data type. The data type of a variable is determined by the data first loaded into it.
The SMUL function results in a string number, so you can use the function in any expression in which a string
number is valid. Because string numbers can exceed the range of numbers that standard arithmetic operators can
accommodate, you might not want to use the SMUL function in any expression in which a standard number is
valid.
321.3 Example
In the following example, the program statement multiplies the constant (1.4149) by variable A and assigns the
result to variable B:
322 SORT
Syntax
SORT(var)
Description
The SORT function enables you to sort a dynamic array.
The elements in the dynamic array are sorted in ascending order, left-justified. OASYS Basic sorts the dynamic
array by the highest system delimiter in the array.
If the dynamic array contains any attribute marks, the sort is by attribute. Values and subvalues remain with
2012 Onsystex Corp.
370
Parameter
The following table describes the parameter of the syntax.
Parameter
Description
var
323 SOUNDEX
Enter topic text here.
323.1 Syntax
SOUNDEX(expr)
323.2 Description
The OASYS Basic SOUNDEX function converts an expression into a phonetic code. This function can return
unpredictable results with multibyte characters.
Tip: Use SOUNDEX to compare alphabetic strings, such as names, when an alternate spelling or misspelling
should not cause a mismatch. expr is an expression evaluating to a string value.
SOUNDEX evaluates the expression by:
Returning the first alphabetic letter.
Converting the remainder of the string to uppercase.
Ignoring letters A, E, H, I, O, U, W, Y, and nonalphabetic characters.
Converting each valid letter to a phonetic code.
Testing for duplication. If a character is next to another character that has the same phonetic code, it is not
included.
Adjusting the length of the code to four characters by truncating codes longer than four characters or padding
with zeros any expression less than four characters.
Letters
1
BFPV
2
CG J K Q SX Z
3
DT
4
L
5
MN
6
R
OASYS Basic SOUNDEX Phonetic Codes
SOUNDEX
323.3 Examples
The following table shows SOUNDEX sample output values.
Expression
SOUNDEX
STEPHEN
S315
STEVEN
S315
TERM INATE
T655
RRR
R600
SOUNDEX Sample Output Values
324 SPACE
Enter topic text here.
324.1 Syntax
SPACE(expr)
324.2 Description
The OASYS Basic SPACE function returns a string containing the specified number of spaces.
Note: Functions can be concatenated within a PRINT statement.
324.3 Example
In the following example, the program statement prints HI and THERE separated by 15 spaces:
371
372
325 SPACES
Enter topic text here.
325.1 Syntax
SPACES(dyn.array.expr)
325.2 Description
The OASYS Basic SPACES function returns the number of spaces specified in each element of the dynamic
array dyn.array.expr.
325.3 Example
In the following example, the program segment prints the number of spaces specified in each element of the
dynamic array ARR1:
This results in ARR2 containing one space in the first element, two spaces in the second element, and so forth.
326 SPLICE
Enter topic text here.
326.1 Syntax
SPLICE(expr1,"expr", expr2)
326.2 Description
The OASYS Basic SPLICE function concatenates two strings or arrays and inserts an expression between them.
326.3 Parameters
The following table describes each parameter of the syntax:
Parameter
Description
expr1
expr
SPLICE
373
nating them.
expr2
326.4 Examples
In the following example, the program segment concatenates PHONE to NUMBER and inserts a dash (-) between
the two strings:
The following program inserts the null value between PHONE and NUMBER. The CALLED subroutine, PRINT.
SETUP, converts OASYS delimiters and the null value to printable characters (this subroutine is printed in the
entry for CHANGE in this manual).
In the following example, the program segment concatenates each element of array ARR1 to array ARR2 and
inserts a plus sign (+) between the two elements:
374
327 SQRT
Enter topic text here.
327.1 Syntax
SQRT(num.expr)
327.2 Description
The OASYS Basic SQRT function returns the square root of a positive numeric argument.
327.3 Example
In the following example, the program statement prints SQUARE ROOT OF 16 IS 4:
328 SQUOTE
Enter topic text here.
328.1 Syntax
SQUOTE(str.expr)
328.2 Description
The OASYS Basic SQUOTE function encloses a string with single quotation marks.
328.3 Examples
In the following example, the program statement prints This is a test on the screen:
In the next example, the program segment prints This is another test on the screen:
SSUB
375
329 SSUB
Enter topic text here.
329.1 Syntax
SSUB(x, y)
329.2 Description
The OASYS Basic SSUB function subtracts the second string number from the first string number and returns
the result as a string number. Arguments can be any valid numbers or string numbers of any magnitude or
precision.
Tip: Processing string data type numbers rather than numeric data type numbers degrades processing speed.
Numbers specified in quotation marks are string data type. Numbers specified without quotation marks are
numeric data type. The data type of a variable is determined by the data first loaded into it.
If x or y contains nonnumeric data, OASYS displays an error message and returns a result of 0.
The SSUB function results in a string number, so you can use the function in any expression in which a string
number is valid. Because string numbers can exceed the range of numbers that standard arithmetic operators can
accommodate, you might not want to use the SSUB function in any expression in which a standard number is
valid.
329.3 Example
In the following example, the program statement assigns to B the result of subtracting 1.4149 from A, and then
prints the answer 98.5851:
330 STATUS
Enter topic text here.
330.1 Syntax
STATUS( )
330.2 Description
The OASYS Basic STATUS function returns a code indicating the condition of the command or function just
executed.
Several OASYS Basic commands and functions set STATUS function return values. For information about the
return values set by a particular command or function, see Appendix F, Commands That Set STATUS() Return
Values.
2012 Onsystex Corp.
376
330.3 Example
In the following example, the STATUS function returns a value of 0, indicating a successful conversion of a valid
date by OCONV. STATUS would return 1 if 7334 were an invalid input date or 2 if D were an invalid conversion
specification.
331 STOP
Enter topic text here.
331.1 Syntax
STOP [expr]
331.2 Description
The OASYS Basic STOP command halts execution of the current program. If you specify an expression, OASYS
prints the expression on the display terminal before halting the program. expr can contain variables, functions,
and arithmetic or string operators.
STOP returns the cursor to the OASYS prompt, a calling menu, or a calling paragraph, depending on how the
program was executed.
Tip: The ABORT command returns the cursor to OASYS level regardless of what process initiated the program.
Note: The STOP command performs differently with BASICTYPE P. The following syntax is valid in BASICTYPE
P:
STOP [message-id]
STOP [expr,...]
message-id must evaluate to a key contained in OASYS error message file
ERRMSG. expr can contain variables, functions, and arithmetic or string operators.
331.3 Examples
In the following example, the program segment attempts to read a record from a file. If the record does not exist,
the program aborts and prints the message RECORD IS MISSING at line 10, column 10 on the terminal.
STOP
377
In the next example, the segment prints a prompt if an error flag ERR.FLAG has been set, and reads the users
input into the variable ANS. If ANS equals Y, the program stops.
In the next example, in BASICTYPE P, the program segment prints an error message from record 10075 in the
ERRMSG file if the program aborts:
332 STR
Enter topic text here.
332.1 Syntax
STR(str.expr, num.expr)
332.2 Description
The OASYS Basic STR function returns a string composed of a number of repetitions of a string.
332.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
str.expr
num.expr
378
332.4 Example
In the following example, the program statement prints a string of 25 hyphens on the terminal screen:
333 STRS
Enter topic text here.
333.1 Syntax
STRS(dyn.array, expr)
333.2 Description
The OASYS Basic STRS function returns each element of dyn.array the number of times specified in expr.
333.3 Example
In the following example, the program segment prints the each element of the ARR1 dynamic array 10 times:
334 SUBROUTINE
Enter topic text here.
SUBROUTINE
379
334.1 Syntax
SUBROUTINE sub.name[(argument1 [, argument2] ...)]
334.2 Description
The OASYS Basic SUBROUTINE command determines the beginning of an external subroutine.
The SUBROUTINE statement must be the first noncomment line in a subroutine.
You can specify arguments to pass data between the main program and the subroutine. If you pass arguments,
the number of arguments in the CALL statement and the SUBROUTINE statement must match, although variable
names do not need to be the same. Changes made to arguments in the subroutine retain their new values when
OASYS exits the subroutine and control reverts to the calling program.
When calling a subroutine from OASYS ODBC, the subroutine name cannot contain any special characters.
Note: All subroutines must be cataloged using the ECL CATALOG command before being called. For more
information about the CATALOG command, see the OASYS Commands Reference.
334.3 Parameters
The following table describes each parameter of the syntax.
Parameter
sub.name
(argument1 ,argument2 ...)
Description
Specifies the subroutine name.
Specifies arguments to pass to the subroutine. The
arguments can be simple variables, dynamic arrays, or
dimensioned arrays.
SUBROUTINE Parameters
334.4 Examples
In the following example, the main program prompts the user for two numbers. These are sent to the subroutine
COMP, together with an empty variable C. The subroutine, COMP, renames the passed arguments, calculates
their average, and returns the result in the third variable.
This is the main program:
380
The sample program in Appendix A, Sample Program, in Developing OASYS Basic Applications includes the
following subroutine, which is called by the main program to display messages on the screen:
OASYS
BASIC, CATALOG For information, see the OASYS Commands Reference.
335.1 Syntax
SUBROUTINE trigname(execstat, dictflag, filename, record.ID.expr, recordval)
FUNCTION trigname(dictflag, filename, record.ID.expr, recordval)
335.2 Description
Triggers enforce user-defined constraints that must be met before data can be updated. The trigger is associated
with the data file, so it verifies any access to the data. A OASYS Basic trigger subroutine or function serves as an
UPDATE trigger. The SUBROUTINE or FUNCTION definition must be the first line in the OASYS Basic trigger.
You must include a RETURN statement in the function:
Points to Remember
When you attempt to update a record, OASYS calls the trigger, passing the file name, DICT if dictionary file,
record ID, and the input value. The subroutine returns the execution status and the new record value.
If the update request fails, the subroutine must return an execstat value of 0. If the request passes, the return
value must be 1.
Tip: You can call a C routine from the OASYS Basic subroutine or function that is called from a trigger.
335.3 Parameters
The following table describes each parameter of the syntax.
Paragraph
trigname
execstat
dictflag
filename
record.ID.expr
recordval
381
Description
Name of the globally cataloged subroutine.
Execution status returned by the trigger subroutine:
0 No updates allowed.
1 Update is allowed.
2 Update is allowed; uses the return recordval.
DICT Indicates that the trigger is operating on the dictionary file.
Indicates that the trigger is operating on the data file.
The quotation marks are required.
The name of the file on which the trigger is operating.
The record to be updated.
The input record value submitted to the UPDATE trigger. recordval is
both an input and output parameter. The trigger can change this value
(for example, by performing a conversion). Then, if the trigger sets
execstat to 2, this value is passed back in recordval and updates the data
record. Only strings and numbers are valid.
If the value returned in recordval is invalid, the record is not updated,
even if the trigger subroutine sets execstat to 2. In this case, the OASYS
Basic STATUS function returns 3 when executed immediately after the
command that calls the trigger. Only strings and numbers are valid.
SUBROUTINE Update Trigger Parameters
Description
0
1
2
No error.
System error, such as a damaged file.
Constraint violation. In this case, the OASYS Basic trigger subroutine
returns a value of 0 in the parameter execstat, indicating that the
update or delete is not allowed.
Trigger execution error or unexpected return from trigger routine (for
example, the trigger subroutine is not cataloged).
STATUS Function Return Values
335.4 Examples
The following example begins with an UPDATE trigger subroutine called TRIG1. Because the return status is
always 0, no record in the file can be updated.
Next, we create the trigger, associate it with the ORDERS file, and list the triggers associated with the ORDERS
file:
2012 Onsystex Corp.
382
Finally, we attempt to copy record 969 into record 970 in the ORDERS file, and the trigger prevents the copy:
336.1 Syntax
SUBROUTINE trigname(execstat, dictflag, filename, record.ID.expr)
FUNCTION trigname(dictflag, filename, record.ID.expr)
336.2 Description
A OASYS Basic subroutine or function serves as the DELETE trigger that is executed when you attempt to delete
a record in the subject file. The SUBROUTINE or FUNCTION definition must be the first line in the OASYS Basic
trigger subroutine.
You must include a RETURN statement in the function:
Points to Remember
Remember the following items when writing a subroutine that is triggered by a user attempting to delete a record:
When you attempt to delete a record, OASYS calls the trigger, passing the file name, DICT if
dictionary file, record ID, and the input value. The subroutine returns the execution status.
If the delete request fails the constraint, the subroutine must return a status of 0. If the request
passes, the return must be 1.
Tip: You can call a C routine from the OASYS Basic subroutine or function that is called from a trigger.
336.3 Parameters
The following table describes each parameter of the syntax.
Parameter
trigname
execstat
Description
Name of the globally cataloged subroutine.
Execution status returned by the trigger subroutine. Valid values for this
include:
0 Delete is not allowed.
1 Delete is allowed.
dictflag
filename
record.ID.expr
383
Description
No error.
System error, such as a damaged file.
Constraint violation. In this case, the OASYS Basic trigger subroutine
returns a value of 0 in the parameter execstat, indicating that the update
or delete is not allowed.
Trigger execution error or unexpected return from trigger routine (for
example, the trigger subroutine is not cataloged).
STATUS Function Return Values
336.5 Example
The following example begins with a DELETE trigger subroutine called DEL_TRIG. This subroutine always
returns 1 and always allows records to be deleted:
Note: After creating and compiling the subroutine, you must catalog it globally.
Next, we create the trigger and associate it with the ORDERS file:
Finally, we delete records in the ORDERS file. The trigger always allows the deletion because the subroutine sets
the execution status to 1.
384
337 SUBSTRINGS
Enter topic text here.
337.1 Syntax
SUBSTRINGS(dyn.array, num.expr1, num.expr2)
337.2 Description
The OASYS Basic SUBSTRINGS function extracts strings from elements within a dynamic array. SUBSTRINGS
supports multibyte languages.
337.3 Parameters
The following table describes each parameter of the syntax.
Parameter
dyn.array
num.expr1
num.expr2
Description
Specifies the dynamic array from which to extract the substring.
Specifies a starting position for the extraction operation.
Specifies the number of characters to return.
SUBSTRINGS Parameters
337.4 Example
In the following example, the program segment extracts the first character of each element of the dynamic array
LASTNAMES. This results in S}J}J}H.
338 SUM
Enter topic text here.
338.1 Syntax
SUM(dyn.array [, <attribute.expr [, value.expr]>] [, start.expr [, stop.expr]])
SUM
385
338.2 Description
The OASYS Basic SUM function adds the numeric values in the dynamic array dyn.array according to dynamic
array delimiters. SUM begins with the lowest level of delimiter and sums all values to the next level. You can input
a range, starting position, and level at which to perform the sum.
Note: The SUM function can contain a maximum of 1621 characters.
338.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
dyn.array
Specifies a dynamic array of numeric values to sum.
, <attribute.expr value.expr> Specifies a range within the dynamic array to sum. The range is
, start.expr , stop.expr
specified as an attribute, a value, a starting point, and a
stopping point.
SUM Parameters
Tip: To sum all elements in an array, execute SUM twice. The first execution sums each group of subvalues and
returns a string of numeric values; the second SUM returns a single value.
338.4 Examples
In the following example, the program segment begins with an array of two values, each with two subvalues. The
SUM function sums the subvalues and returns a string with two numeric values.
In the next example, the program statement sums VAL1 and returns the numeric value 52 with no dynamic array
delimiters:
339 SWAP
Enter topic text here.
339.1 Syntax
SWAP str.expr1 WITH str.expr2 IN var
386
339.2 Description
The OASYS Basic SWAP command replaces all occurrences of one substring with a second substring. The
search string does not have to be the same length as the replacement string. SWAP supports mulitbyte
languages.
Tip: CONVERT compares and replaces substrings on a character-by-character basis. CONVERT cannot
exchange strings of different lengths.
339.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
str.expr1
str.expr2
IN var
339.4 Examples
In the following example, the program segment replaces all occurrences of the string AB with the string AZ
in the variable VAR. The new string assigned to VAR is THE TAZ WAS GRAZBED.
In the next example, SWAP does not replace a character with a character, but it replaces a string with a string. The
program segment prints HARRY BELAFONTE.
The following program first creates a string that contains the null value, then calls a subroutine that converts
OASYS delimiters and the null value to characters that can be displayed or printed. Next, the program swaps the
null value for another string (def), calls the conversion subroutine again, and prints the string again.
SWAP
387
340 SYSTEM
Enter topic text here.
340.1 Syntax
SYSTEM(expr)
340.2 Description
The OASYS Basic SYSTEM function retrieves certain system-level parameters set by OASYS Basic statements
or by ECL commands such as SETPTR, TERM, and query statements.
Note: The SYSTEM function is similar to the STATUS function and several of the @variables featured in
Appendix B, OAS Basic@variables. The SYSTEM and STATUS functions return the same values after
execution of OASYS Basic commands and functions.
340.3 Parameters
expr must be a number from 0 through 16. If you specify 0, the value of SYSTEM is determined by a previously
executed OASYS Basic command. If you specify a number from 1 through 16, OASYS returns predefined system
parameters as described in the following table. OASYS Basic returns the original value when expr is invalid.
Parameter
Description
2
3
4
5
388
Parameter
Description
6
7
8
9
10
11
12
13
14
15
16
17
18-29
30
31
32
Parameter
Description
33
34
35
36
37
38
39
40
41
42
43
44
45
48
SYSTEM
389
Returns the calling stack for the OASYS Basic program at runtime. The
calling stack is stored in a dynamic array with each line represented as a
separate field. Each field is separated into three values (the sequence
number, the object name, and the line number), and the values are separated
by value marks.
SYSTEM Parameters (continued)
Parameter
Description
50
The OASYS Basic SYSTEM (50) function returns a list of files open in
OASYS Basic as a dynamic array. The first field is multivalued, and contains
the following information:
Value 1 The maximum number of files that can be opened system-wide.
Value 2 The current number of hashed files open in OASYS Basic.Value 3
The current number of dynamic hashed files open in OASYS Basic.Value 4
The current number of recoverable hashed files open in OASYS Basic.
Value 5 The current number of sequential and OS-level files open in
OASYS Basic.Value 6 The current number of index files open in OASYS
Basic.Value 7 The current number of temporarily closed files in OASYS
Basic.
Returns information about device licensing. If you are not using device
licensing, SYSTEM (51) returns a null string.
Returns the entire command stack for the OASYS Basic program at runtime.
The command stack is stored in a dynamic array. Commands are separated
by attribute marks (@FM ).
In a OASTelnet session, returns the IP address. In a console session, returns
the word Console.
51
52
512
(Windows
platforms only)
513
Returns the current OASYS version and build number.
514
Returns the number of OASYS users currently logged in. SYSTEM (514)
does not include phantoms.
515
Returns the localized name of the Administrators group. The group name
(Windows NT differs based on the localized version of Windows.
or Windows Note - SYSTEM (515) lets OASYS SQL create privilege table records for
2000 only)
items owned by the Administrators group, even if the Windows version is
not an English-language version.
516
Returns 1 if the user is a member of the local Administrators group.
(Windows
Otherwise, returns 0.
only)
9010
Returns the type of database. This function returns UD if the database is
OASYS, or UV if the database is UniVerse. If the database is the OASYS
Personal Edition, the function returns UD.PE.
SYSTEM Parameters (continued)
340.4 Example
In the following example, the program segment turns on the printer if data is currently being sent to the display
terminal:
390
341 TAN
Enter topic text here.
341.1 Syntax
TAN(num.expr)
341.2 Description
The OASYS Basic TAN function returns the trigonometric tangent of a numeric expression, num.expr.
341.3 Example
In the following example, the program statement prints 0.2679, the tangent of the argument 15:
342 TIME
Enter topic text here.
342.1 Syntax
TIME( )
342.2 Description
The OASYS Basic TIME function returns the time of day in internal format, expressed as the number of seconds
elapsed since midnight.
Note: The TIME function has no arguments.
342.3 Examples
In the following example, the program statement prints the time of day in internal format. If the time is 1:01 A.M.,
OASYS prints the value 3660, the number of seconds since midnight in internal format.
In the next example, the TIME function is used in conjunction with the OCONV function for conversion to
external format:
2012 Onsystex Corp.
TIME
391
343 TIMEDATE
Enter topic text here.
343.1 Syntax
TIMEDATE( )
343.2 Description
The OASYS Basic TIMEDATE function returns a string representation of the current time and date in the
following external format:
343.3 Example
In the following example, the program statement assigns the string representation of the current time and date to
the variable TSTRING. If the current time and date were November 1, 1999, at 11:45 A.M., TSTRING would be
11:45:00 01 NOV 1999.
344.1 Syntax
TRANSACTION ABORT
392
344.2 Description
The OASYS Basic TRANSACTION ABORT command cancels the active transaction. OASYS discards the
pending writes. As a result, other users never know that the transaction was in progress, and none of the
updates associated with the transaction take place.
A transaction can abort due to any of the following conditions, in addition to the execution of a TRANSACTION
ABORT statement:
A program finishes before a transaction commit is issued (STOP or END).
A program chains to another program.
An error terminates the program before a transaction commit is issued.
A user breaks out of the program before a transaction commit is issued. This can be controlled
programmatically by disabling the interrupt key during a transaction.
The user is forced to log out or the user process is killed, which terminates a program before a transaction
commit is issued.
OASYS handles the above abort conditions in the same way it does the TRANSACTION ABORT statement, by
canceling the transaction.
Tip: You should be aware of these various abort conditions and control the resulting action from within the
program where possible and appropriate. For example, write statements that fail execute the ON ERROR
clause if it exists. Otherwise the program aborts and the transaction also aborts.
344.3 Example
In the following example, the transaction process aborts if var is 0:
345.1 Syntax
TRANSACTION COMMIT {THEN statements [END] | ELSE statements [END]}
TRANSACTION COMMIT
393
345.2 Description
The OASYS Basic TRANSACTION COMMIT command concludes the active transaction. OASYS writes all
pending writes to the appropriate files. You must specify a THEN clause or an ELSE clause. You can specify both
clauses.
OASYS performs the following steps during a transaction commit:
Disables the interrupt key.
Writes all updates.
Releases all record locks locked inside the transaction.
Executes the THEN clause if it exists.
Enables the interrupt key.
Warning: When including WRITE statements within a transaction, you must code an ON ERROR clause that takes appropriate
stop the transaction. If the transaction is not aborted by the ON ERROR clause, processing continues, and the
transaction will commit inappropriately.
345.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
Description
0
1
3
345.4 Examples
The program segment below is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. The segment executes the OASYS Basic function STATUS if the commit is not
successful, but does not abort the transaction. However, when an error occurs, the transaction will never be
committed and will automatically abort when the program terminates.
394
In the following example, the TRANSACTION COMMIT command ends the transaction process and writes the
new record to the database. Otherwise, it prints the return value of the OASYS Basic STATUS function.
346.1 Syntax
TRANSACTION START {THEN statements [END] | ELSE statements [END]}
346.2 Description
The OASYS Basic TRANSACTION START command initiates a new transaction, storing all updates until a
TRANSACTION COMMIT or TRANSACTION ABORT statement executes.
Warning: When you include WRITE statements within a transaction, you must code an ON ERROR clause that
takes action to notify the user and take appropriate action, such as stopping the transaction. If the transaction
is not aborted by the ON ERROR clause, processing continues, and the transaction could commit
inappropriately.
346.3 Parameters
The following table describes each parameter of the syntax.
Parameter
THEN statements END
ELSE statements END
Description
THEN executes if the TRANSACTION START is successful.
END is required to terminate multiline THEN statements.
ELSE executes if the TRANSACTION START is not successful,
the record or ID does not exist, or a transaction is already active.
END is required to terminate multiline ELSE statements.
TRANSACTION START Parameters
TRANSACTION START
395
Description
0
1
346.4 Example
The following program segment displays a message if a transaction is already started when TRANSACTION
START is executed:
347 TRIM
Enter topic text here.
347.1 Syntax
TRIM(str.expr[,char[,type]])
347.2 Description
The OASYS Basic TRIM function removes all spaces or every occurrence of a specified character from a string
expression. If OASYS does not find an occurrence of the specified character, the string remains unchanged.
TRIM removes leading or trailing occurrences of the specified character from a string, and converts embedded
spaces or occurrences of the specified characters in a string to one space or a specified character. OASYS does
not remove single spaces or occurrences of the specified character embedded in the string.
347.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
396
str.expr
,char
,type
Note: Onsystex recommends that you do not use the TRIM function on dynamic arrays. For BASICTYPEs M and
P, some leading and trailing spaces or occurrences of a specified character are not removed from elements in a
dynamic array. For example, for BASICTYPE M or P, the following program segment:
produces the following result (notice the asterisks surrounding the delimiter character):
To get this latter result regardless of BASICTYPE, use the TRIMS function.
347.4 Examples
In the following example, the program segment removes the leading, trailing, and extraneous blanks from the
variable NAME:
In the next example, the program segment removes the asterisks from the variables X and Y:
TRIM
397
348 TRIMB
Enter topic text here.
348.1 Syntax
TRIMB(str.expr)
348.2 Description
The OASYS Basic TRIMB function removes any trailing spaces from a string expression. If OASYS does not find
any trailing spaces, the string remains unchanged.
348.3 Example
In the following example, the program statement removes the trailing spaces from the variable NAME. This
results in NAME = " Zenith, R.".
349 TRIMF
Enter topic text here.
349.1 Syntax
TRIMF(str.expr)
Description
The OASYS Basic TRIMF function removes any leading spaces from the string expression. If OASYS does not
find any leading spaces, the string remains unchanged.
349.2 Example
In the following example, the program segment removes the leading spaces from the variable NAME, storing the
resulting string. This results in "Zenith, R. ".
2012 Onsystex Corp.
398
350 TRIMS
Enter topic text here.
350.1 Syntax
TRIMS(dyn.array[,char[,type]])
350.2 Description
The OASYS Basic TRIMS function removes any spaces from each element of a dynamic array. If OASYS does
not find any spaces, the element remains unchanged.
TRIMS removes any leading or trailing spaces from a string and converts any contiguous spaces in a string to
one space. Single blanks between text are not removed.
350.3 Parameters
The following table describes each parameter of the syntax.
Parameter Description
dyn.array
,char
,type
350.4 Example
In the following example, the program segment removes any spaces from each element of the dynamic array
ARR1:
2012 Onsystex Corp.
TRIMS
399
351 OASEXECUTE
Enter topic text here.
351.1 Syntax
OASEXECUTE str.expr [{ASYNC | SYNC} ON connection] [CAPTURING dyn.array.var] [RETURNING dyn.
array.var] [PASSCOM]
351.2 Description
The OASYS Basic OASEXECUTE command executes a command in ECLTYPE U, regardless of the BASICTYPE
used when the program was compiled.
When you compile a program in BASICTYPE P, EXECUTE or PERFORM passes the string to execute to a
nonstandard OASYS parser. This parser looks for a specific sentence structure common to BASICTYPE P
systems. Standard UniQuery sentences might not be handled correctly in this circumstance. Therefore, when you
want to execute a standard UniQuery statement from within a OASYS Basic program that has been compiled in
BASICTYPE P, use the OASEXECUTE command instead of EXECUTE or PERFORM.
STACKCOMMON
The ECL STACKCOMMON command makes use of common areas more flexible, although it requires additional
memory. STACKCOMMON settings have the following effects:
If STACKCOMMON is off when one program executes another, the contents of unnamed common areas are
passed to the executed program and back to the executing program.
If STACKCOMMON is on when one program executes another program, the contents of unnamed common
areas are not passed to the program you execute. Instead, they are saved, and the unnamed common areas of
the called program are initialized to 0. When control is passed back to the calling program, it is restored to its
value before the program call. Unnamed common areas are never passed to a phantom program.
Note: STACKCOMMON defaults to OFF in BASICTYPEs R and U, but is always on in BASICTYPEs M and P.
351.3 Parameters
The following table describes each parameter of the syntax.
400
Parameter
Description
str.expr
ASYNC | SYNC
ON connection
CAPTURING, dyn.
array.var
RETURNING, dyn.
array.var
PASSCOM
OASYS
STACKCOMMON For information, see the OASYS Commands Reference.
352 UNASSIGNED
Enter topic text here.
352.1 Syntax
UNASSIGNED(var.name)
352.2 Description
The OASYS Basic UNASSIGNED function checks a variable in a program to see if it is currently assigned a
value. If the variable is not assigned a value, the function returns 1. Otherwise, it returns 0.
352.3 Example
In the following example, the program statement returns 0 if FILENAME1 is currently assigned a value. It returns
1 if no value is currently assigned.
UNLOCK
401
353 UNLOCK
Enter topic text here.
353.1 Syntax
UNLOCK [num.expr]
353.2 Description
The OASYS Basic UNLOCK command unlocks predefined computer resources reserved by the LOCK command.
Resource numbers range from 0 through 63. If you do not specify a resource number, the system releases all
locks you have set. If there are no locked resources at the time of execution, the statement does not have any
effect.
The lock is associated with num.expr, not the resource. Therefore, a command that does not check for locks
against the resource number will access the resource even if it is locked. For example, an installation might assign
locks 1 through 4 to four system printers. When an application needs to reserve printer 1, the application
executes LOCK 1. All other programs must check for locks before accessing the resource for the lock to be
effective.
Resources are not automatically unlocked by the termination of the locking program. You must use the OASYS
Basic UNLOCK or ECL QUIT commands to release them. You also can release resources by executing the ECL
CLEAR.LOCKS command at the OASYS level.
353.3 Example
In the following example, the program statement unlocks all computer resources reserved by the current user:
OASYS
CLEAR.LOCKS, LIST.LOCKS, SUPERCLEAR.LOCKS For information, see the OASYS Commands Reference.
354 UPCASE
Enter topic text here.
354.1 Syntax
UPCASE(string.expr)
402
354.2 Description
The OASYS Basic UPCASE function converts lowercase characters to uppercase. Nonalphabetic values are not
changed. Special characters, including the null value, are not converted by this function. UPCASE does not
support multibyte languages.
354.3 Example
In the following example, the program segment converts be bold!! to BE BOLD!!:
355 WAKE
Enter topic text here.
355.1 Syntax
WAKE pid
355.2 Description
The OASYS Basic WAKE command activates a OASYS process (pid) that has been paused with either the ECL
PAUSE command or the OASYS Basic PAUSE command. If the specified process has not already been paused,
OASYS disregards the next PAUSE issued for the process indicated by pid.
355.3 Example
The following program, WAKEUP, lists paused processes, then prompts for the ID of a process to wake up. Next,
the program executes the OASYS Basic WAKE command against that process, and then executes LIST.PAUSED
again to verify that the process was reactivated.
The following example shows the results of executing the preceding program, waking up process 10811:
WAKE
OASYS
LIST.PAUSED, PAUSE, WAKE For information, see the OASYS Commands Reference.
356 WEOF
Enter topic text here.
356.1 Syntax
WEOF [UNIT(mu.expr)] {THEN statements [END] | ELSE statements [END]}
356.2 Description
The OASYS Basic WEOF command writes an EOF (end-of-file) mark to a magnetic tape.
356.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
UNIT(mu.expr)
Specifies the conversion code (first digit), and the unit number
(second digit). OASYS allows unit numbers from 0 through 9.
The mu.expr is optional, and the default value for UNIT is (00)
for tape unit 0 with no conversion performed (ASCII assumed).
Valid options include the following:
0 No conversion (ASCII assumed).
1 EBCDIC conversion.
2 Invert high bit.
3 Swap bytes.
THEN executes if command execution is successful. END is
required to terminate multiline THEN statements.
403
404
Description
0
1
2
3
4
5
6
Successful read.
End of file encountered.
End of tape encountered.
Tape not assigned.
Parity error.
Unknown hardware error.
Other unspecified error.
STATUS Function Return Values
356.5 Example
In the following example, the program statement writes an end-of-file mark to tape 0. If unable to write the end-offile mark, OASYS executes the ELSE clause.
OASYS
SETTAPE, T.ATT, T.DET For information, see the OASYS Commands Reference.
357 WEOFSEQ
Enter topic text here.
357.1 Syntax
WEOFSEQ seq.file.var [ON ERROR statements]
357.2 Description
The OASYS Basic WEOFSEQ command writes an end-of-file mark at the record pointer position in a sequential
file, which results in the file being truncated at the current position.
Tip: Use WEOFSEQ after a series of WRITESEQ operations.
WEOFSEQ
405
357.3 Parameters
The following table describes each parameter of the syntax.
Parameter
seq.file.var
ON ERROR
statements
Description
Specifies a sequential file variable to which to write the end-of-file mark.
Specifies statements to execute if the WEOFSEQ statement fails with a
fatal error because the file is not open, an I/O error occurs, or OASYS
cannot find the file.
If you do not specify the ON ERROR clause and a fatal error occurs, the
program terminates.
WEOFSEQ Parameters
357.4 Example
In the following example, the program statement writes an end-of-file mark to the file TRIAL.RUN at the current
pointer position:
358 WRITE
Enter topic text here.
358.1 Syntax
WRITE expr {ON | TO} [file.var,] record.ID.expr [ON ERROR statements]
358.2 Description
The OASYS Basic WRITE command writes an expression to an opened file and releases locks set by the same
process.
Note: WRITE updates the record and releases OASYS locks regardless of lock status. To check for and retain
record locks, use the WRITEU command. For more information, see Developing OASYS Basic Applications.
To maintain file integrity, OASYS locks records with a nonprogrammable lock during a write. OASYS releases this
lock immediately after the WRITE command executes.
Warning: Do not use OASYS Basic READ and WRITE commands to open or modify binary data in DIR-type files
(for example, BP). Doing so can corrupt data in the file. Instead, use OSREAD or OSBREAD after executing the
OASYS Basic NOCONVERT command.
406
358.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
ON | TO file.var
record.ID.expr
ON ERROR
statements
Meaning
0
1
2
Successful write.
System error, such as a damaged file.
Constraint violation. In this case, the OASYS Basic trigger subroutine
returns a value of 0 in the parameter execstat, indicating that the
WRITE is not allowed.
Trigger execution error or unexpected return from trigger routine (for
example, the trigger subroutine is not cataloged).
Non-RFS files WRITE created a duplicate alternate index key and
ECL DUP.STATUS is on; or WRITE failed because a duplicate value
exists in the index, and NO.DUPS was specified when the index was
3
10
WRITE
407
created.
RFS files WRITE created a duplicate value in the index, and ECL
DUP.STATUS is on.
STATUS Function Return Values
358.5 Examples
The following program segment is taken from the sample program in Appendix A, Sample Program, in
Developing OASYS Basic Applications. The statements update records that were previously locked with READU
and release locks on the records.
In the next example, the program statement writes the contents of the variable OVERSTOCK to the file named in
variable FNAME as a record with ID OS:
OASYS
DUP.STATUS For information, see the OASYS Commands Reference.
359 WRITELIST
Enter topic text here.
359.1 Syntax
WRITELIST var ON list.name
359.2 Description
The OASYS Basic WRITELIST command writes the contents of a variable to a saved list. The values saved can
then be used as item IDs to retrieve the data record.
WRITELIST saves only the first value of the attribute. OASYS saves only the first value in a multivalued or multisubvalued attribute.
359.3 Parameters
The following table describes each parameter of the syntax.
Parameter
var
Description
Specifies a variable to place in a saved list.
408
ON list.name
UniQuery
DELETE.LIST, GET.LIST, SELECT, SSELECT, SAVE.LIST For information, see the UniQuery Commands
Reference.
OASYS SQL
SELECT For information, see the OASYS SQL Commands Reference.
360 WRITESEQ
Enter topic text here.
360.1 Syntax
WRITESEQ expr [APPEND] {ON | TO} seq.file.var [ON ERROR statements] {THEN statements [END] | ELSE
statements [END]}
360.2 Description
The OASYS Basic WRITESEQ command writes an expression as a record on a sequential file at the current
record pointer position.
Note: Before you use WRITESEQ, you must open the file by using the OSOPEN or OPENSEQ command.
Tip: Use the READSEQ command to position the record pointer before using WRITESEQ.If the file is a named
pipe, you cannot use WRITESEQ to write to it. You must use the OSBWRITE command.
WRITESEQ cannot immediately write a record to disk. OASYS stores records in a buffer until the buffer is full.
360.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
APPEND
ON | TO seq.file.var
WRITESEQ Parameters
WRITESEQ
Parameter
409
Description
ON ERROR statements
360.4 Example
In the following example, the program segment writes the expression BAD.ACCOUNTS to the file ACCOUNTS. A
message displays if the record pointer is not at the end of the file.
361 WRITESEQF
Enter topic text here.
361.1 Syntax
WRITESEQF expr [APPEND] {ON | TO} seq.file.var [ON ERROR statements] {THEN statements [END] | ELSE
statements [END]}
361.2 Description
The OASYS Basic WRITESEQF command writes an expression as a record on a sequential file from a current
record pointer position and forces OASYS to immediately write the data to the disk.
Note: Before you use WRITESEQF, you must open the file by using the OSOPEN or OPENSEQ command.
Tip: Use the READSEQ command to position the record pointer before using WRITESEQF.
If the file is a named pipe, you cannot use WRITESEQF to write to it. You must use the OSBWRITE command.
Use the READSEQ command to position the record pointer before using WRITESEQF.
410
361.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
APPEND
ON | TO seq.file.var
WRITESEQF Parameters
Parameter
Description
ON ERROR statements
361.4 Example
In the following example, the program statement writes the variable CHK.WRITE to the file PAYROLL. All records
currently in the output buffer are written to disk along with this record.
WRITESEQF
411
WRITESEQ
362 WRITET
Enter topic text here.
362.1 Syntax
WRITET [UNIT(mu.expr)] expr {THEN statements [END] | ELSE statements [END]}
362.2 Description
The OASYS Basic WRITET command writes the value of an expression as a record onto tape.
Note: Before you can use the WRITET command, you must reserve a tape drive with the ECL T.ATT command.
For detailed information about tape commands, see the OASYS Commands Reference.
OASYS uses the ASCII 0 character (CHAR(0)) as a string-end delimiter. Therefore, you cannot use ASCII 0 in
any string variable in OASYS Basic. When a string is read in a OASYS Basic program, CHAR(0) characters are
converted to CHAR(128), and WRITET converts CHAR(128) back to CHAR(0).
362.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
UNIT(mu.expr)
Specifies the conversion code (first digit) and the unit number
(second digit). Unit numbers range from 0 through 9.
The mu.expr is optional and the default value for UNIT is (00)
for tape unit 0 with no conversion performed (ASCII assumed).
Valid options include the following:
0 No conversion (ASCII assumed).
1 EBCDIC conversion.
2 Invert high bit.
3 Swap bytes.
Specifies an expression to write.
THEN executes if command execution is successful. END is
required to terminate multiline THEN statements.
ELSE executes if command execution is not successful or the
record (or ID) does not exist. END is required to terminate
multiline ELSE statements.
WRITET Parameters
expr
THEN statements END
ELSE statements END
412
362.5 Example
In the following example, the T.ATT command is executed, and then OASYS writes the variable TAX.RECORD to
tape:
OASYS
SETTAPE, T.ATT, T.DET For information, see the OASYS Commands Reference.
363 WRITEU
Enter topic text here.
363.1 Syntax
WRITEU expr {ON | TO} [file.var,] record.ID.expr [ON ERROR statements]
363.2 Description
The OASYS Basic WRITEU command writes a record to a file without releasing locks. WRITEU writes regardless
of lock status.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications.
Warning: Do not use OASYS Basic READ and WRITE commands to open or modify binary data in DIR-type files
(for example, BP). Doing so can corrupt data in the file. Instead, use OSREAD or OSBREAD after executing the
OASYS Basic NOCONVERT command.
WRITEU
413
Remember the following points about alternate key indexes when you code WRITEU statements:
Alternate key indexes that are currently enabled are automatically updated when you write a record.
If you execute the ECL command DUP.STATUS ON, and then write a record that creates a duplicate alternate
key, WRITEU sets the STATUS return value to 10.
If the NO.DUPS keyword was specified when the alternate key index was created, OASYS Basic will not write a
record that would create a duplicate index key. Instead, the ON ERROR clause executes (or the program aborts
if ON ERROR is not coded) and the STATUS function returns a value of 10. RFS does not support NO.DUPS.
363.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
ON | TO file.var,
record.ID.expr
ON ERROR statements
3
10
414
363.5 Example
In the following example, the program statement writes the variable IDEA.57 to the file IDEAS as a record with the
ID LAST. The lock remains in place if the record was locked before executing WRITEU.
OASYS
DUP.STATUS For information, see the OASYS Commands Reference.
364 WRITEV
Enter topic text here.
364.1 Syntax
WRITEV expr {ON | TO} [file.var,] record.ID.expr, attrib.expr [ON ERROR statements]
364.2 Description
The OASYS Basic WRITEV command updates a specified attribute in a file regardless of lock status.
Note: The WRITEV command releases locks set by the same process. OASYS Basic locks are advisory only. For
more information, see Developing OASYS Basic Applications..
364.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
expr
WRITEV
ON | TO file.var,
record.ID.expr
attrib.expr
ON ERROR statements
415
3
10
Description
Successful write.
System error, such as a damaged file.
Constraint violation. In this case, the OASYS Basic trigger subroutine returns
a value of 0 in the parameter execstat, indicating that the WRITEV is not
allowed.
Trigger execution error or unexpected return from trigger routine (for example,
trigger subroutine is not cataloged).
Non-RFS files WRITEV created a duplicate alternate index key and ECL
DUP.STATUS is on; or WRITEV failed because a duplicate value exists in
the index and NO.DUPS was specified when the index was created.
RFS files WRITEV created a duplicate value in the index, and ECL DUP.
STATUS is on.
STATUS Function Return Values
364.5 Examples
In the following example, the program statement writes the variable NAME to the first attribute in the customer
record with CLIENT.ID in the file CLIENTS:
The following example is taken from the sample program in Appendix A, Sample Program, in Developing
OASYS Basic Applications. It demonstrates using WRITEV to write an attribute. Notice that the attribute is read
and the record locked. Then LOCATE is used to determine the position (within the attribute) of the value to be
deleted. After that value is deleted, the attribute is written back to the record.
416
OASYS
DUP.STATUS For information, see the OASYS Commands Reference.
365 WRITEVU
Enter topic text here.
365.1 Syntax
WRITEVU expr {ON | TO} [file.var,] record.ID.expr, attrib.expr [ON ERROR statements]
365.2 Description
The OASYS Basic WRITEVU command writes an expression to an attribute of a record regardless of lock status.
This command retains locks. As with the WRITEV statement, the record ID and attribute number are mandatory.
Note: OASYS Basic locks are advisory only. For more information, see Developing OASYS Basic Applications..
365.3 Parameters
The following table describes each parameter of the syntax.
WRITEVU
Parameter
expr
ON | TO file.var,
record.ID.expr
attrib.expr
ON ERROR statements
Description
Specifies an expression to write to an attribute of a record.
Specifies a file to receive the expression.
If you do not specify a file.var, OASYS writes to the default file.
If no default file is open, a fatal error occurs.
The default file is one for which no file variable is assigned in the
OPEN statement.
Specifies a record to receive the expression.
Specifies an attribute to receive the expression.
Specifies statements to execute if the WRITEVU statement fails
with a fatal error (such as the file is not open, an I/O error occurs
in the write process, or the record contains a duplicate alternate
index key).
If you do not specify the ON ERROR clause and a fatal error
occurs, the program terminates.
When including WRITEVU statements within a transaction, you
must code an ON ERROR clause that notifies the user and takes
appropriate action, such as stopping the transaction. If the
transaction is not aborted by the ON ERROR clause, processing
continues, and the transaction could commit inappropriately.
WRITEVU Parameters
Description
0
1
2
Successful write.
System error, such as a damaged file.
Constraint violation. In this case, the OASYS Basic trigger subroutine
returns a value of 0 in the parameter execstat, indicating that the
WRITEVU is not allowed.
Trigger execution error or unexpected return from trigger routine (for
example, trigger subroutine is not cataloged).
Non-RFS files WRITEVU created a duplicate alternate index key and
ECL DUP.STATUS is ON; or WRITEVU failed because a duplicate
value exists in the index, and NO.DUPS was specified when the index
was created.
RFS files WRITEVU created a duplicate value in the index, and ECL
DUP.STATUS is ON.
STATUS Function Return Values
3
10
OASYS
DUP.STATUS For information, see the OASYS Commands Reference.
417
418
366 XLATE
Enter topic text here.
366.1 Syntax
XLATE(filename, rec.id.expr, attrib.expr, "code")
366.2 Description
The OASYS Basic XLATE function returns the contents of an attribute, and takes additional action if the record
does not exist or the attribute is empty.
This function performs the same action as the TRANS virtual attribute function.
366.3 Parameters
The following table describes each parameter of the syntax.
Parameter
Description
filename
rec.id.expr
attrib.expr
"code"
Character
Hex Character
000
001
002
003
004
005
006
NUL
SOH
STX
ETX
EOT
ENQ
ACK
0
1
2
3
4
5
6
007
008
009
010
011
012
013
014
BEL
BS
HT
LF
VT
FF
CR
SO
7
8
9
A
B
C
D
E
ASCII Value
015
016
017
018
019
020
021
022
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
Hex Character
SI
F
DLE
10
DC1
11
DC2
12
DC3
13
DC4
14
NAK
15
SYN
16
ETB
17
CAN
18
EM
19
SUB
1A
ESC
1B
FS
1C
GS
1D
RS
1E
US
1F
(space)
20
!
21
"
22
#
23
$
24
%
25
ASCII Character Codes (continued)
ASCII Value
038
039
040
041
042
043
044
045
046
047
048
049
050
051
052
053
054
055
2012 Onsystex Corp.
Character
Character
&
(
)
*
+
,
.
/
0
1
2
3
4
5
6
7
Hex Character
26
27
28
29
2A
2B
2C
2D
2E
2F
30
31
32
33
34
35
36
37
419
420
056
057
058
059
060
8
38
9
39
:
3A
;
3B
<
3C
ASCII Character Codes (continued)
ASCII Value
061
062
063
064
065
066
067
068
069
070
071
072
073
074
075
076
077
078
079
080
081
082
083
Character
Hex Character
=
3D
>
3E
?
3F
@
40
A
41
B
42
C
43
D
44
E
45
F
46
G
47
H
48
I
49
J
4A
K
4B
L
4C
M
4D
N
4E
O
4F
P
50
Q
51
R
52
S
53
ASCII Character Codes (continued)
ASCII Value
Character
Hex Character
084
085
086
087
088
089
090
091
092
093
094
095
096
097
098
099
100
101
102
103
104
T
U
V
W
X
Y
Z
[
\
]
^
_
a
b
c
d
e
f
g
h
54
55
56
57
58
59
5A
5B
5C
5D
5E
5F
60
61
62
63
64
65
66
67
68
105
106
i
69
j
6A
ASCII Character Codes (continued)
ASCII Value
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
Character
Hex Character
k
6B
l
6C
m
6D
n
6E
o
6F
p
70
q
71
r
72
s
73
t
74
u
75
v
76
w
77
x
78
y
79
z
7A
{
7B
|
7C
}
7D
~
7E
DEL
7F
80
81
ASCII Character Codes (continued)
ASCII Value
Character
Hex Character
130
82
131
83
132
84
133
85
134
86
135
87
136
88
137
89
138
8A
139
8B
140
8C
141
8D
142
8E
143
8F
144
90
145
91
146
92
147
93
148
94
149
95
150
96
151
97
152
98
ASCII Character Codes (continued)
421
422
ASCII Value
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
Hex Character
99
9A
9B
9C
9D
9E
9F
A0
A1
A2
A3
A4
A5
A6
A7
A8
A9
AA
AB
AC
AD
AE
AF
ASCII Character Codes (continued)
ASCII Value
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
Character
Character
Hex Character
B0
B1
B2
B3
oe
B4
OE
B5
B6
B7
B8
B9
BA
BB
BC
BD
BE
BF
C0
C1
C2
C3
C4
C5
C6
ASCII Character Codes (continued)
ASCII Value
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
Hex Character
C7
C8
C9
CA
CB
CC
CD
CE
CF
D0
D1
D2
nonprinting
D3
nonprinting
D4
D5
D6
D7
D8
D9
nonprinting
DA
nonprinting
DB
nonprinting
DC
nonprinting
DD
ASCII Character Codes (continued)
ASCII Value
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
Character
Character
Hex Character
nonprinting
DE
nonprinting
DF
nonprinting
E0
nonprinting
E1
nonprinting
E2
nonprinting
E3
nonprinting
E4
nonprinting
E5
nonprinting
E6
nonprinting
E7
nonprinting
E8
nonprinting
E9
nonprinting
EA
nonprinting
EB
nonprinting
EC
nonprinting
ED
nonprinting
EE
nonprinting
EF
nonprinting
F0
nonprinting
F1
nonprinting
F2
nonprinting
F3
nonprinting
F4
ASCII Character Codes (continued)
423
424
ASCII Value
245
246
247
248
249
250
251
252
253
254
255
Character
nonprinting
nonprinting
nonprinting
nonprinting
nonprinting
nonprinting
text mark
subvalue mark
Hex Character
F5
F6
F7
F8
F9
FA
FB
FC
value mark
FD
attribute mark FE
record mark
FF
ASCII Character Codes (continued)
368.1 @variables
The following table describes the valid @variables.
@variable
Description
@ACCOUNT
@AM
@COM M AND
@CONV
@CRTHIGH
@CRTWIDE
@DATA
@DATE
@DAY
@DICT
@FORM AT
@GID
@variable
Description
@HEADER
@ID
@LASTVERB
@LEVEL
@LOGNAM E
@LPTRHIGH
@LPTRWIDE
@M ONTH
@PARASENTENCE
@PATH
@RECORD
@RECUR0
@RECUR1
@RECUR2
@RECUR3
@RECUR4
@RM
@variable
Description
@SENTENCE
@SM
@SVM
@SYS.BELL
@SYSTEM .RETURN.
CODE
@TIM E
@TM
425
426
@UID
@variable
Description
@USER0
@USER1
@USER2
@USER3
@USER4
@USERNO
@USER.RETURN.
CODE
@USER.TYPE
@VM
@WHO
@YEAR
Description
Attribute mark
Value mark
Subvalue mark
Record mark
Text mark
Subvalue mark (same as @SM )
Delimiter @variables
427
BSELECT
BUILD.INDEX
COM PILE.DICT
CREATE.INDEX
DELETE.INDEX
ESEARCH
FORM .LIST
GET.LIST
LIST
LIST.INDEX
LIST.ITEM
LIST.LABEL
Command
LOCK
M ERGE.LIST
M ODIFY
NSELECT
-1 if you specify an
invalid lock number.
-2 if the resource is
locked by another user.
The number of items in the select -1
list.
The number of records modified. -1
428
GETQUEUE
Action
ABS
Action
Example
M ultiplies the value to VAR1 *= VAR2
the left of the operator
by the value to the right
Related Function
+
*
/
** or ^
:, CAT
+=
-=
Operator
*=
Example
Related Function
NEG
SADD, SUM
SSUB
SM UL
SDIV
PWR
429
of the operator.
/=
:=
Note: You must include the REUSE function to apply arithmetic operations to all elements of a dynamic array.
Action
AND, &
OR, !
NOT
NOTS
Example
Boolean Operators
Description
=, EQ
Multivalued
Equivalent
EQS
#, <>, ><, NE
NES
>, GT
GTS
Greater than.
Equal to.
Example
430
<, LT
LTS
Less than.
GES
LES
Relational Operators
$DEFINE
$FALSE
$IFNDEF
$INSERT
$TRUE
@
@COM M AND
@CRTHIGH
@DATA
@DAY
@FALSE
@GID
@ID
@LEVEL
@LPTRHIGH
Reserved Words
Reserved Words
@LPTRWIDE
@NULL
@PATH
@RECORD
@RECUR1
@RECUR3
@SENTENCE
@SYSTEM .RETURN.
CODE
@TRANSACTION
@TTY
@OASNO
@USER.RETURN.CODE
@USER0
@USER2
@M ONTH
@PARASENTENCE
@PROCTYPE
@RECUR0
@RECUR2
@RECUR4
@SYS.BELL
@TIM E
@TRUE
@TUPLE
@UID
@USER.TYPE
@USER1
@USER3
2012 Onsystex Corp.
Reserved Words
@USER4
@USERNO
@WHO
@YEAR
ABORT
ABS
ABSOLUTE
ACOS
ALPHA
AND
APPEND
AS
ASCII
ASIN
ASSIGN
ASYNC
AT
ATAN
Reserved Words (continued)
Reserved Words
BEFORE
BEGIN
BITAND
BITNOT
BITOR
BITXOR
BPIOCP
BPIOCPN
BREAK
BUFFER.KEYS
BY
BYTELEN
CALCULATE
CALL
CALLC
CALLING
CAPTURING
CASE
CAT
CATS
CHAIN
CHANGE
CHAR
CHARLEN
CHARS
CHECKSUM
CLEAR
CLEARCOM
CLEARCOM M ON
CLEARDATA
CLEARFILE
CLEARINPUT
CLEARSELECT
CLEARSQL
CLOSE
CLOSESEQ
COL1
COL2
COM
COM M IT
COM M ON
COM PILE.DICT.ITEM
CONNECT
CONTINUE
CONVERT
COS
COUNT
COUNTS
Reserved Words (continued)
Reserved Words
CRT
DATA
DCOUNT
DECLARE
DEL
DELETELIST
DIM
DIR
DISPLAY
DO
DQUOTE
DTX
ECHO
END
EQ
EQU
CURRENT
DATE
DEBUG
DEFFUN
DELETE
DELETEU
DIM ENSION
DISCONNECT
DISPLAYWIDTH
DOWNCASE
DROUND
EBCDIC
ELSE
ENTER
EQS
EQUATE
431
432
EXECUTE
EXECUTESQL
EXIT
EXP
EXTRACT
FIELD
FIELDS
FIELDSTORE
FILEINFO
FILELOCK
FILEUNLOCK
FIND
FINDSTR
FIRST_ALT_KEY
FLUSH
FM T
Reserved Words (continued)
Reserved Words
FM TS
FOOTING
FOR
FORM LIST
FROM
FUNCTION
GARBAGECOLLECT
GE
GES
GET
GETCOLUM NDATA
GETCOLUM NNAM E
GETENV
GETERRM SG
GETLIST
GETM SG
GETNEXTTUPLE
GETPTR
GETPU
GETQUEUE
GETREADU
GETUSERGROUP
GETUSERID
GETUSERNAM E
GETX
GO
GOSUB
GOTO
GROUP
GROUPSTORE
GT
GTS
HASH
HEADING
HELP
HUSH
ICONV
ICONVS
IF
IN
INCLUDE
INDEX
INDEXS
INDICES
INM AT
INPUT
INPUTCLEAR
INPUTERR
Reserved Words (continued)
Reserved Words
INPUTIF
INPUTTRAP
INSERT
ISM B
ISNVS
ITYPE
LAST_ALT_KEY
LEN
LENS
LINEM ARK
LOCATE
LOCKED
LOWER
LTS
M ATBUILD
M ATCHES
M ATPARSE
INPUTNULL
INS
INT
ISNV
ISOLATION
JRNL_STATUS
LE
LENGTH
LES
LN
LOCK
LOOP
LT
M AT
M ATCH
M ATCHFIELD
M ATREAD
Reserved Words
M ATREADL
M ATREADU
M ATWRITE
M ATWRITEU
M AXIM UM
M BLEN
M DPERFORM
M INIM UM
M OD
NE
NEG
NES
NEXT
NOCONVERT
Reserved Words (continued)
Reserved Words
NODELAY
NOT
NOTS
NULL
NULLVAL_ALT_KEY
NUM
NUM S
OCONV
OCONVS
OFF
ON
OPEN
OPENSEQ
OR
OSBREAD
OSBWRITE
OSCLOSE
OSDELETE
OSOPEN
OSREAD
OSWRITE
PAGE
PASSCOM
PASSCOM M ON
PASSLIST
PAUSE
PCPERFORM
PERFORM
PRECISION
PREVIOUS
PRINT
PRINTER
PRINTERR
PRIOR
PROCREAD
PROCWRITE
PROGRAM
PROM PT
PWR
QUOTE
RAISE
READ
READBCK
READBCKL
READBCKU
READFWD
READFWDL
READFWDU
Reserved Words (continued)
Reserved Words
READL
READNEXT
READONLY
READT
READV
READVU
READXBCK
RECORDLOCKED
RECORDLOCKU
RELEASE
REM OVE
REPLACE
RETURN
REUSE
RND
RQM
SADD
SDIV
READLIST
READNEXTTUPLE
READSEQ
READU
READVL
READWRITE
READXFWD
RECORDLOCKL
RELATIVE
REM
REPEAT
RESIZET
RETURNING
REWIND
RNDSEED
RTNLIST
SCM P
SELECT
433
434
SELECTINDEX
SELECTINFO
SEND
SENDX
SEQ
SEQS
SETINDEX
SETM ARK
SETROW
SETTABLE
SETTING
SIN
Reserved Words (continued)
Reserved Words
SLEEP
SM UL
SOUNDEX
SPACE
SPACES
SPLICE
SQRT
SQUOTE
SSUB
STATUS
STEP
STOP
STR
STRS
SUBROUTINE
SUBSTRINGS
SUM
SWAP
SYNC
SYSTEM
TAN
THEN
TIM E
TIM EDATE
TIM EOUT
TO
TRANSACTION
TRIM
TRIM B
TRIM F
TRIM S
OASEXECUTE
UNASSIGNED
UNFILTERED
UNLOCK
UNTIL
UPCASE
USE
USING
VALIDATE.KEY
VERB
WAIT
WAITING
WAKE
WEOF
WEOFSEQ
WHILE
WITH
Reserved Words (continued)
Reserved Words
WRITE
WRITELIST
WRITEONLY
WRITESEQ
WRITESEQF
WRITET
WRITEU
WRITEV
WRITEVU
XLATE
XTD
Reserved Words (continued)
Command or Function
$INCLUDE
Command or Function
DISPLAY
DIM
EBCDIC
ECHO
ENTER
EXECUTE
EXECUTESQL
FLUSH
FM T
FOOTING
HEADING
ICONV
CUST.OPTIONS
5, 46
N/A
N/A
99
78
11, 27, 35, 46, 93,
105
35
46
N/A
34, 64
32, 34
56 (for ICONV D,
also 60 and 82; for
ICONV M C, also
62)
ICONVS
Whether the ICONVS function returns an empty 56
string if CUST.OPTIONS 56 is on and the input
value or conversion code is invalid.
IN
N/A
46
INPUT
N/A
12, 18, 46, 65, 83
Commands and Functions Affected by BASICTYPEs and CUST.OPTIONS (continued)
435
436
Command or Function
CUST.OPTIONS
INPUT @
LOCATE
N/A
101
The number of array elements you can include in a 85
search and the search driven by those elements.
M ATPARSE
Whether excess data (including delimiters)
N/A
resulting from executing the M ATPARSE
command can be placed in position 0,0 of the dimensioned array.
M ATREAD
Whether excess data (including delimiters)
N/A
resulting from executing the M ATREAD command
can be placed in position 0,0 of the dimensioned
array.
M ATREADL
Whether excess data (including delimiters)
N/A
resulting from executing the M ATREADL
command can be placed in position 0,0 of the
dimensioned array.
M ATREADU
Whether excess data (including delimiters)
N/A
resulting from executing the M ATREADU
command can be placed in position 0,0 of the
dimensioned array.
M DPERFORM
N/A
35
OCONV
Whether the OCONV function returns an empty 56 (for OCONV
string if CUST.OPTIONS 56 is on and the input D, also 4 and 29;
value or conversion code is invalid.
for OCONV M D,
also 13 and 63)
OCONVS
Whether the OCONVS function returns an empty 56
string if CUST.OPTIONS 56 is on and the input
value or conversion code is invalid.
Commands and Functions Affected by BASICTYPEs and CUST.OPTIONS (continued)
Command or Function
ON/GOSUB
ON/GOTO
PCPERFORM
PERFORM
PRINT
PROCREAD
PROCWRITE
READLIST
CUST.OPTIONS
437
CUST.OPTIONS
READNEXT
FM T
GETPTR
ICONV
438
ICONV D
READ
READBCK
0 Successful read.
10 OASYS Basic found and read a duplicate alternate index key
value, and ECL DUP.STATUS is on.
READBCKL
0 Successful read.
10 OASYS Basic found and read a duplicate alternate index key
value, and ECL DUP.STATUS is on.
READBCKU
0 Successful read.
10 OASYS Basic found and read a duplicate alternate index key
value, and ECL DUP.STATUS is on.
READFWD
0 Successful read.
10 OASYS Basic found and read a duplicate alternate index key
value, and ECL DUP.STATUS is on.
READFWDL
0 Successful read.
10 OASYS Basic found and read a duplicate alternate index key
value, and ECL DUP.STATUS is on.
READFWDU
0 Successful read.
10 OASYS Basic found and read a duplicate alternate index key
value, and ECL DUP.STATUS is on.
READL
0 Successful read.
1 OASYS was unable to read the record.
n The record is locked. The user number of the user who locked
the record.
Commands and Functions That Set STATUS() Return Values (continued)
0 Successful read.
1 End of file encountered.
2 End of tape encountered.
3 Tape not assigned.
4 Parity error.
5 Unknown hardware error.
6 Other unspecified error.
READU
0 Successful read.
1 OASYS was unable to read the record.
n The record is locked. The user number of the user who locked
the file is returned in n.
RECORDLOCKED
n The record is locked. The user number of the user who owns
the lock is returned in n.
0 The record is not locked.
-1 The file is NFA. Currently, RECORDLOCKED does not
support NFA files.
-2 Invalid file type. file.var can contain the null value.
-3 System error: unknown user.
SELECTINDEX
0 The select list is loaded with alternate key values or record
IDs for the specified file.
1 No alternate index key exists for this attribute using the name
specified. The select list is empty.
SETINDEX
0 The alternate key specified exists.
1 Error.
2 The alternate key specified does not exist.
Commands and Functions That Set STATUS() Return Values (continued)
439
440
0 Successful write.
1 System error, such as a damaged file.
2 Constraint violation. In this case, the OASYS Basic trigger
subroutine returns a value of 0 in the parameter execstat,
indicating that the WRITE is not allowed.
3 Trigger execution error or unexpected return from trigger
routine (for example, the trigger subroutine is not cataloged).
10 Non-RFS files: WRITE created a duplicate alternate index
key and ECL DUP.STATUS is on; or WRITE failed because a
duplicate value exists in the index, and NO.DUPS was specified
when the index was created. RFS files: WRITE created a
duplicate value in the index, and ECL DUP.STATUS is on.
WRITET
0 Successful read.
1 End of file encountered.
2 End of tape encountered.
3 Tape not assigned.
4 Parity error.
5 Unknown hardware error.
6 Other unspecified error.
Commands and Functions That Set STATUS() Return Values (continued)
WRITEU
0 Successful write.
1 System error, such as a damaged file.
2 Constraint violation. In this case, the OASYS Basic trigger
subroutine returns a value of 0 in the parameter execstat,
indicating that the WRITEU is not allowed.
3 Trigger execution error or unexpected return from trigger
routine (for example, trigger subroutine is not cataloged).
10 Non-RFS files: WRITEU created a duplicate alternate index
key and ECL DUP.STATUS is ON; or WRITEU failed because a
duplicate value exists in the index, and NO.DUPS was specified
when the index was created. RFS files: WRITEU created a
duplicate value in the index, and ECL DUP.STATUS is ON.
WRITEV
0 Successful write.
1 System error, such as a damaged file.
2 Constraint violation. In this case, the OASYS Basic trigger
subroutine returns a value of 0 in the parameter execstat,
indicating that the WRITEV is not allowed.
3 Trigger execution error or unexpected return from trigger
routine (for example, trigger subroutine is not cataloged).
10 Non-RFS files: WRITEV created a duplicate alternate index
key and ECL DUP.STATUS is on; or WRITEV failed because a
duplicate value exists in the index and NO.DUPS was specified
when the index was created. RFS files: WRITEV created a
duplicate value in the index, and ECL DUP.STATUS is on.
Commands and Functions That Set STATUS() Return Values (continued)
0 Successful write.
1 System error, such as a damaged file.
2 Constraint violation. In this case, the OASYS Basic trigger
subroutine returns a value of 0 in the parameter execstat,
indicating that the WRITE VU is not allowed.
3 Trigger execution error or unexpected return from trigger
routine (for example, trigger subroutine is not cataloged).
10 Non-RFS files: WRITEVU created a duplicate alternate
index key and ECL DUP.STATUS is ON; or WRITEVU failed
because a duplicate value exists in the index, and NO.DUPS was
specified when the index was created. RFS files: WRITEVU
created a duplicate value in the index, and ECL DUP.STATUS is
ON.
Commands and Functions That Set STATUS() Return Values (continued)
441