OAS Basic Commands Reference

OASYS Basic
Commands Reference
2012 Onsystex Corp.
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.
OASYS Basic Commands Reference Manual

Introduction
by Onsystex Corp.
Welcome to OASYS, the most advanced, high performance transactional business application server built
to leverage the best capabilities of MultiValue and Relational technologies.
If you are look ing to create, extend or migrate multiuser business applications to the cloud in a SAAS
model, OASYS is the right product for you.
OASYS offers a sophisticated and robust core environment ideal to create and host business rules that can
be accessed natively or through any of the built in multipurpose data provider connectors to interface with
web, client/server and/or terminal based applications that utilize multi-discipline software technlogy including
Java and .NET
For ultimate flexibility, application data can be stored, accessed and managed on OASYS' hybrid
multidimensional data store which supports relational databases including Oracle, SQL Server, Postgres,
DB2, MySQL. As a result applications can seamlessly integrate with external data sources mak ing a reality
the ability to "write once and deploy anywhere" software applications.
Thank you for using our products.
This document is property of Onsystex, Inc and should not be copied, altered or reproduced without the
express written authorization of Onsystex, Inc.
Please note that all references to vendors and their respective third party products in this document are in
most cases protected by trademark s, patents and/or copyrights. Any references made on this document
were solely used for illustration purposes.
OASYS Basic Commands Reference

2012 Onsystex Corp.
All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or
mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the
written permission of the publisher.
Products that are referred to in this document may be either trademarks and/or registered trademarks of the
respective owners. The publisher and the author make no claim to these trademarks.
While every precaution has been taken in the preparation of this document, the publisher and the author assume no
responsibility for errors or omissions, or for damages resulting from the use of information contained in this
document or from the use of programs and source code that may accompany it. In no event shall the publisher and
the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused
directly or indirectly by this document.
Printed: August 2012 in Atlanta, Georgia
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
Special thanks to:

All the team members of Onsystex and Beta customers who
contributed to this document.
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
...................................................................................................................................
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
...................................................................................................................................
156
141 GETREADU
157
1 Syntax
................................................................................................................................... 157
2 Description
................................................................................................................................... 157
3 GETREADU
...................................................................................................................................
157
142 GETUSERGROUP
158
1 Syntax
................................................................................................................................... 158
2 Description
................................................................................................................................... 158
3 Examples
................................................................................................................................... 158
4 Related
...................................................................................................................................
Commands
158
2012 Onsystex Corp.
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
2012 Onsystex Corp.
13
14

2 Synonym
................................................................................................................................... 165
3 Description
................................................................................................................................... 165
4 Example
................................................................................................................................... 165
5 Related
...................................................................................................................................
Command
166
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
...................................................................................................................................
170
5 Examples
................................................................................................................................... 171
6 Related
...................................................................................................................................
Command
171
155 ICONV Date (D)
171
1 Syntax
................................................................................................................................... 171
2 Description
................................................................................................................................... 171
3 Parameters
................................................................................................................................... 171
4 STATUS
...................................................................................................................................
172
2012 Onsystex Corp.
Contents
15
5 Examples
................................................................................................................................... 173
6 Related
...................................................................................................................................
Commands
173
156 ICONV Group (G)
173
1 Syntax
................................................................................................................................... 173
2 Description
................................................................................................................................... 173
3 Parameters
................................................................................................................................... 174
4 Example
................................................................................................................................... 174
5 Related
...................................................................................................................................
Command
174
157 ICONV Length (L)
174
1 Syntax
................................................................................................................................... 174
2 Description
................................................................................................................................... 174
3 Parameters
................................................................................................................................... 175
4 Example
................................................................................................................................... 175
5 Related
...................................................................................................................................
Command
175
158 ICONV Masked Character (MC)
175
1 Syntax
................................................................................................................................... 175
2 Description
................................................................................................................................... 175
3 Parameters
................................................................................................................................... 175
4 Example
................................................................................................................................... 176
5 Related
...................................................................................................................................
Commands
176
159 ICONV Masked Decimal (MD)
176
1 Syntax
................................................................................................................................... 176
2 Description
................................................................................................................................... 176
3 Parameters
................................................................................................................................... 177
4 Examples
................................................................................................................................... 177
5 Related
...................................................................................................................................
Command
177
160 ICONV Left Justify (ML)
178
1 Syntax
................................................................................................................................... 178
2 Description
................................................................................................................................... 178
3 Parameters
................................................................................................................................... 178
4 Example
................................................................................................................................... 178
5 Related
...................................................................................................................................
Command
179
161 ICONV Packed Decimal (MP)
179
1 Syntax
................................................................................................................................... 179
2 Description
................................................................................................................................... 179
2012 Onsystex Corp.
15
16

3 Related
...................................................................................................................................
Command
179
162 ICONV Packed Decimal (MP1)
179
1 Syntax
................................................................................................................................... 179
2 Description
................................................................................................................................... 179
3 Related
...................................................................................................................................
Command
180
163 ICONV Right Justify (MR)
180
1 Syntax
................................................................................................................................... 180
2 Description
................................................................................................................................... 180
3 Parameters
................................................................................................................................... 180
4 Example
................................................................................................................................... 181
5 Related
...................................................................................................................................
Command
181
164 ICONV Time (MT)
181
1 Syntax
................................................................................................................................... 181
2 Description
................................................................................................................................... 181
3 Parameters
................................................................................................................................... 181
4 Example
................................................................................................................................... 182
5 Related
...................................................................................................................................
Commands
182
165 ICONV Hex (MX | HEX), Octal (MO), Binary

(MB)
182
1 Syntax
................................................................................................................................... 182
2 Description
................................................................................................................................... 182
3 Parameters
................................................................................................................................... 182
4 Examples
................................................................................................................................... 183
5 Related
...................................................................................................................................
Commands
184
166 ICONV Pattern Match (P)
184
1 Syntax
................................................................................................................................... 184
2 Description
................................................................................................................................... 184
167 ICONV Range (R)
184
1 Syntax
................................................................................................................................... 184
2 Description
................................................................................................................................... 184
3 Parameters
................................................................................................................................... 184
4 Example
................................................................................................................................... 185
5 Related
...................................................................................................................................
Command
185
168 ICONV SOUNDEX (S)
185
2012 Onsystex Corp.
Contents
17
1 Syntax
................................................................................................................................... 185
2 Description
................................................................................................................................... 185
3 Example
................................................................................................................................... 185
4 Related
...................................................................................................................................
Commands
185
169 ICONV Text Extraction (T)
186
1 Syntax
................................................................................................................................... 186
2 Description
................................................................................................................................... 186
3 Parameters
................................................................................................................................... 186
4 Examples
................................................................................................................................... 186
5 Related
...................................................................................................................................
Commands
186
170 ICONV File Translation (Tfile)
186
1 Syntax
................................................................................................................................... 187
2 Description
................................................................................................................................... 187
171 ICONVS
187
1 Syntax
................................................................................................................................... 187
2 Description
................................................................................................................................... 187
3 Parameters
................................................................................................................................... 187
4 STATUS
...................................................................................................................................
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

5 Related
...................................................................................................................................
Commands
191
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
...................................................................................................................................
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
19
20

2 Description
................................................................................................................................... 205
3 Examples
................................................................................................................................... 205
4 Related
...................................................................................................................................
Command
206
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
23
24

1 Syntax
................................................................................................................................... 237
2 Description
................................................................................................................................... 237
3 Example
................................................................................................................................... 237
4 Related
...................................................................................................................................
Commands
238
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
228 OCONV Date (D)
249
1 Syntax
................................................................................................................................... 249
2 Description
................................................................................................................................... 249
2012 Onsystex Corp.
25
26

3 Parameters
................................................................................................................................... 249
4 Examples
................................................................................................................................... 250
5 Related
...................................................................................................................................
Commands
251
229 OCONV Group (G)
251
1 Syntax
................................................................................................................................... 251
2 Description
................................................................................................................................... 252
3 Parameters
................................................................................................................................... 252
4 Example
................................................................................................................................... 252
5 Related
...................................................................................................................................
Command
252
230 OCONV Length (L)
252
1 Syntax
................................................................................................................................... 252
2 Description
................................................................................................................................... 252
3 Parameters
................................................................................................................................... 253
4 Example
................................................................................................................................... 253
5 Related
...................................................................................................................................
Command
253
231 OCONV Masked Character (MC)
253
1 Syntax
................................................................................................................................... 253
2 Description
................................................................................................................................... 253
3 Parameters
................................................................................................................................... 253
4 Examples
................................................................................................................................... 254
5 Related
...................................................................................................................................
Commands
255
232 OCONV Masked Decimal (MD)
255
1 Syntax
................................................................................................................................... 255
2 Description
................................................................................................................................... 255
3 Parameters
................................................................................................................................... 255
4 Examples
................................................................................................................................... 256
5 Related
...................................................................................................................................
Command
256
233 OCONV Left Justify (ML)
257
1 Description
................................................................................................................................... 257
2 Parameters
................................................................................................................................... 257
3 Examples
................................................................................................................................... 258
4 Related
...................................................................................................................................
Command
258
234 OCONV Packed Decimal (MP)
259
1 Syntax
................................................................................................................................... 259
2 Description
................................................................................................................................... 259
2012 Onsystex Corp.
Contents
27
3 Related
...................................................................................................................................
Command
259
235 OCONV Packed Decimal (MP1)
259
1 Syntax
................................................................................................................................... 259
2 Description
................................................................................................................................... 259
3 Related
...................................................................................................................................
Command
259
236 OCONV Right Justify (MR)
259
1 Syntax
................................................................................................................................... 260
2 Description
................................................................................................................................... 260
3 Parameters
................................................................................................................................... 260
4 Examples
................................................................................................................................... 261
5 Related
...................................................................................................................................
Command
261
237 OCONV Time (MT)
261
1 Syntax
................................................................................................................................... 261
2 Description
................................................................................................................................... 261
3 Parameters
................................................................................................................................... 262
4 Related
...................................................................................................................................
Commands
262
238 OCONV Hex (MX | HEX), Octal (MO), Binary

(MB)
262
1 Syntax
................................................................................................................................... 262
2 Description
................................................................................................................................... 262
3 Parameters
................................................................................................................................... 262
4 Examples
................................................................................................................................... 263
5 Related
...................................................................................................................................
Commands
263
239 OCONV Pattern Match (P)
263
1 Syntax
................................................................................................................................... 264
2 Description
................................................................................................................................... 264
3 Parameters
................................................................................................................................... 264
4 Examples
................................................................................................................................... 264
240 OCONV Range (R)
264
1 Syntax
................................................................................................................................... 264
2 Description
................................................................................................................................... 265
3 Parameters
................................................................................................................................... 265
4 Example
................................................................................................................................... 265
5 Related
...................................................................................................................................
Command
265
2012 Onsystex Corp.
27
28
241 OCONV SOUNDEX (S)
265
1 Syntax
................................................................................................................................... 265
2 Description
................................................................................................................................... 266
3 Parameters
................................................................................................................................... 266
4 Example
................................................................................................................................... 266
5 Related
...................................................................................................................................
Commands
266
242 OCONV Text Extraction (T)
266
1 Syntax
................................................................................................................................... 266
2 Description
................................................................................................................................... 266
3 Parameters
................................................................................................................................... 267
4 Examples
................................................................................................................................... 267
5 Related
...................................................................................................................................
Commands
267
243 OCONV File Translation (Tfile)
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
...................................................................................................................................
278
5 Examples
................................................................................................................................... 278
6 Related
...................................................................................................................................
Command
278
251 OSBWRITE
278
1 Syntax
................................................................................................................................... 279
2 Description
................................................................................................................................... 279
3 Parameters
................................................................................................................................... 279
4 STATUS
...................................................................................................................................
280
5 Examples
................................................................................................................................... 280
6 Related
...................................................................................................................................
Commands
280
252 OSCLOSE
280
1 Syntax
................................................................................................................................... 281
2012 Onsystex Corp.
29
30

2 Description
................................................................................................................................... 281
3 Parameters
................................................................................................................................... 281
4 STATUS
...................................................................................................................................
281
5 Example
................................................................................................................................... 281
6 Related
...................................................................................................................................
Command
281
253 OSDELETE
281
1 Syntax
................................................................................................................................... 282
2 Description
................................................................................................................................... 282
3 Parameters
................................................................................................................................... 282
4 STATUS
...................................................................................................................................
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
264 PRINTER CLOSE
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

2 Description
................................................................................................................................... 294
3 Parameters
................................................................................................................................... 294
4 Examples
................................................................................................................................... 295
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
...................................................................................................................................
304
5 Example
................................................................................................................................... 304
6 Related
...................................................................................................................................
Commands
305
274 READBCK
305
1 Syntax
................................................................................................................................... 305
2 Description
................................................................................................................................... 305
3 Parameters
................................................................................................................................... 305
4 STATUS
...................................................................................................................................
306
5 Example
................................................................................................................................... 306
6 Related
...................................................................................................................................
Commands
306
275 READBCKL
307
1 Syntax
................................................................................................................................... 307
2 Description
................................................................................................................................... 307
3 Parameters
................................................................................................................................... 307
4 STATUS
...................................................................................................................................
308
5 Example
................................................................................................................................... 308
6 Related
...................................................................................................................................
Commands
309
276 READBCKU
309
1 Syntax
................................................................................................................................... 309
2 Description
................................................................................................................................... 309
3 Parameters
................................................................................................................................... 309
4 STATUS
...................................................................................................................................
310
5 Example
................................................................................................................................... 310
6 Related
...................................................................................................................................
Commands
311
277 READFWD
311
1 Syntax
................................................................................................................................... 311
2012 Onsystex Corp.
33
34

2 Description
................................................................................................................................... 311
3 Parameters
................................................................................................................................... 311
4 STATUS
...................................................................................................................................
312
5 Example
................................................................................................................................... 312
6 Related
...................................................................................................................................
Commands
312
7 UniData
................................................................................................................................... 313
278 READFWDL
313
1 Syntax
................................................................................................................................... 313
2 Description
................................................................................................................................... 313
3 Parameters
................................................................................................................................... 313
4 STATUS
...................................................................................................................................
314
5 Example
................................................................................................................................... 314
6 Related
...................................................................................................................................
Commands
314
279 READFWDU
315
1 Syntax
................................................................................................................................... 315
2 Description
................................................................................................................................... 315
3 Parameters
................................................................................................................................... 315
4 STATUS
...................................................................................................................................
316
5 Example
................................................................................................................................... 316
6 Related
...................................................................................................................................
Commands
316
280 READL
317
1 Syntax
................................................................................................................................... 317
2 Description
................................................................................................................................... 317
3 Parameters
................................................................................................................................... 317
4 STATUS
...................................................................................................................................
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
...................................................................................................................................
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

4 Examples
................................................................................................................................... 329
5 Related
...................................................................................................................................
Commands
330
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
...................................................................................................................................
336
5 STATUS
...................................................................................................................................
336
6 Related
...................................................................................................................................
Commands
337
294 RECORDLOCKL
337
1 Syntax
................................................................................................................................... 337
2 Description
................................................................................................................................... 337
3 Parameters
................................................................................................................................... 337
2012 Onsystex Corp.
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
...................................................................................................................................
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
...................................................................................................................................
359
5 Examples
................................................................................................................................... 359
6 Related
...................................................................................................................................
Commands
360
313 SELECTINFO
360
1 Syntax
................................................................................................................................... 360
2 Description
................................................................................................................................... 360
3 Parameters
................................................................................................................................... 360
4 SELECTINFO
...................................................................................................................................
361
5 Related
...................................................................................................................................
Commands
361
314 SEND
361
1 Syntax
................................................................................................................................... 361
2 Description
................................................................................................................................... 361
3 Parameters
................................................................................................................................... 361
2012 Onsystex Corp.
39
40

4 Examples
................................................................................................................................... 362
5 Related
...................................................................................................................................
Commands
362
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
...................................................................................................................................
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
2012 Onsystex Corp.
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

2 Description
................................................................................................................................... 375
3 Example
................................................................................................................................... 375
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
335 SUBROUTINE (Update Trigger)
380
1 Syntax
................................................................................................................................... 380
2 Description
................................................................................................................................... 380
3 Parameters
................................................................................................................................... 380
4 Examples
................................................................................................................................... 381
2012 Onsystex Corp.
Contents
336 SUBROUTINE (Delete Trigger)
43
382
1 Syntax
................................................................................................................................... 382
2 Description
................................................................................................................................... 382
3 Parameters
................................................................................................................................... 382
4 STATUS
...................................................................................................................................
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
2012 Onsystex Corp.
43
44

1 Syntax
................................................................................................................................... 390
2 Description
................................................................................................................................... 390
3 Examples
................................................................................................................................... 390
4 Related
...................................................................................................................................
Commands
391
343 TIMEDATE
391
1 Syntax
................................................................................................................................... 391
2 Description
................................................................................................................................... 391
3 Example
................................................................................................................................... 391
4 Related
...................................................................................................................................
Commands
391
344 TRANSACTION ABORT
391
1 Syntax
................................................................................................................................... 391
2 Description
................................................................................................................................... 392
3 Example
................................................................................................................................... 392
4 Related
...................................................................................................................................
Commands
392
345 TRANSACTION COMMIT
392
1 Syntax
................................................................................................................................... 392
2 Description
................................................................................................................................... 393
3 Parameters
................................................................................................................................... 393
4 Examples
................................................................................................................................... 393
5 Related
...................................................................................................................................
Commands
394
346 TRANSACTION START
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
2012 Onsystex Corp.
45
46

3 Example
................................................................................................................................... 402
4 Related
...................................................................................................................................
Commands
403
356 WEOF
403
1 Syntax
................................................................................................................................... 403
2 Description
................................................................................................................................... 403
3 Parameters
................................................................................................................................... 403
4 STATUS
...................................................................................................................................
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
...................................................................................................................................
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
...................................................................................................................................
412
5 Example
................................................................................................................................... 412
6 Related
...................................................................................................................................
Commands
412
363 WRITEU
412
1 Syntax
................................................................................................................................... 412
2 Description
................................................................................................................................... 412
3 Parameters
................................................................................................................................... 413
4 STATUS
...................................................................................................................................
413
5 Example
................................................................................................................................... 414
6 Related
...................................................................................................................................
Commands
414
364 WRITEV
414
1 Syntax
................................................................................................................................... 414
2 Description
................................................................................................................................... 414
3 Parameters
................................................................................................................................... 414
4 STATUS
...................................................................................................................................
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
367 ASCII Character Codes
418
368 OAS Basic @variables
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
369 Operators in OAS Basic
428
1 Arithmetic
...................................................................................................................................
Operators
428
2 Boolean
...................................................................................................................................
Operators
429
3 Relational
...................................................................................................................................
Operators
429
370 Reserved Words
430
371 Commands Affected by BASICTYPEs and

oas.OPTIONS
434
372 Commands That Set STATUS() Return

Values
437
Index
2012 Onsystex Corp.
Elements of Syntax Statements
49
Elements of Syntax Statements

This reference manual uses a common method to present syntax for OASYS commands. The syntax statement
includes the command name, required arguments, and options you can use with the command. Italics represents a
variable you can replace with any valid option. The following figure illustrates the elements of a syntax statement.
!
! 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.
2012 Onsystex Corp.
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
Parameter
Description
var
Specifies variable to check to determine whether to compile statements1 or

statements2.
Specifies statements to compile if var is defined.
Specifies optional statements to compile if var is not defined.
$IFDEF Parameters
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:
2012 Onsystex Corp.
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
Parameter
Description
var
Specifies variable to check to determine whether to compile statements1 or

statements2.
Specifies statements to compile if var is not defined.
Specifies optional statements to compile if var is defined.
$IFNDEF Parameters
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.
2012 Onsystex Corp.
$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
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
2012 Onsystex Corp.
53
54
seq.filename
Specifies the name of an operating system sequential file.

$INCLUDE Parameters
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
+=
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.
2012 Onsystex Corp.
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:
2012 Onsystex Corp.
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
Parameter
2012 Onsystex Corp.
Description
62
col.expr
,row.expr
-num.expr
Specifies the column position to place the cursor.

Can be a literal value or variable.
M ust be a positive numeric value.
Value 0 is the leftmost column on the screen. For most terminals, col.expr
can range from 0 to 79 (the right-hand side of the screen).
Specifies the row at which to place the cursor. Defaults to the current row.
Can be either a literal value or variable.
M ust be a positive value.
Value 0 is the top of the screen. For most terminals, row.expr can range
from 0 to 23 (the last row on the screen).
Specifies an @ terminal function. For valid @ terminal functions and their
effects, see the next table.
@ Parameters
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
Clear screen, home cursor.

Home cursor.
Clear from cursor to end of screen.
@ Function Options
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)
2012 Onsystex Corp.
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
End alternate character set.

Reserved for color combinations.
Sent by the backspace key.
Sent by the clear screen or erase key.
Sent by the delete character key.
Sent by the insert character key.
Sent by the delete line key.
Sent by the insert line key.
Sent by the home key.
Sent by the left arrow key.
Sent by the up arrow key.
Sent by the down arrow key.
Sent by the right arrow key.
Sent by the clear-to-end-of-line key.
Sent by the clear-to-end-of-screen key.
Sent by function key F0.
Option
-72
-73
-74
-75
-76
-77
-78
-79
-80
-81
-82
-83
-84
Description
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.
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:
2012 Onsystex Corp.
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.
Null Value Handling

With null value handling on, when OASYS Basic encounters the null value in a command parameter where a
number is expected (num.expr1, num.expr2), it displays a warning message and uses 0.
Note: In BASICTYPE M and P, the [] (square brackets) function can remove a substring entirely and can also
remove parts of the substring.
Parameters
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
2012 Onsystex Corp.
[]
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:
In BASICTYPE U, system output is as follows:
In BASICTYPEs M and P, the substring is extracted as follows:
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:
This program prints the following text:
37
{}
{} is a synonym for the CALCULATE function. For more information, see CALCULATE.
Synonym
CALCULATE
2012 Onsystex Corp.
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:
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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.
2012 Onsystex Corp.
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.
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
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.
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
BITAND Function Operation Results
Example
In the following example, the program statement prints a 0:
47
BITNOT
Syntax
BITNOT(num.expr)
2012 Onsystex Corp.
72
Description
The OASYS Basic BITNOT function performs the bit-wise NOT logical function on the argument num.expr.
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
BITNOT Function Operation Results
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.
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:
2012 Onsystex Corp.
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.
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
2012 Onsystex Corp.
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
BPIOCP User Responses
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.
2012 Onsystex Corp.
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
Parameter Description
KEY
2012 Onsystex Corp.
KEY is optional and has no effect. It is included for backward compatibility
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
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.
2012 Onsystex Corp.
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.
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
Parameter
Description
sub.name
@var
argument1, argument2
M AT array1,M AT
array2
ASYNC | SYNC
The name of the called subroutine.

A variable that contains the name of the subroutine to call.
Any valid argument passed to the subroutine.
Any valid array passed to the subroutine.
ON connection
OASYS no longer supports this parameter, but it remains for

syntax compatibility.
CALL Parameters
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.
Calling a C Program in UNIX

You must link the C program to OASYS before calling it from a OASYS Basic program. Perform the following
procedure to prepare OASYS for CALLC:
1.Write and compile the C program.
2.Define the C program call interface.
3.Build the runtime version of OASYS (containing the linked C program).
4.Write, compile, and execute the OASYS Basic program.
For more information about this procedure, see Developing OASYS Basic Applications.
Calling a Function on Windows Platforms

The CALLC implementation in OASYS for Windows Platforms uses the Microsoft Windows Dynamic Link
Library (DLL) facility. This facility allows separate pieces of code to call one another without being permanently
bound together. Linking between the separate pieces is accomplished at runtime (rather than compile time)
through a DLL interface.
For CALLC, developers create a DLL and then call that DLL from OASYS. E-type VOC entries for each function
called from a DLL communicate interface information to OASYS. For additional information and examples, see
Administering OASYS on UNIX or Administering OASYS on Windows Platforms.
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:
2012 Onsystex Corp.
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
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
2012 Onsystex Corp.
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:
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
Parameter
Description
string
Specifies the original text string.
2012 Onsystex Corp.
CHANGE
old.substring
new.substring
85
Specifies the text string to replace with new.substring.

Specifies the text string with which to replace old.substring.
CHANGE Parameters
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.
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
Tip: CLEAR can be used at any point within a program.

Note: CLEAR performs differently with BASICTYPEs M and P. All variables in unnamed common areas are also
set to 0.
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:
2012 Onsystex Corp.
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.
2012 Onsystex Corp.
90
Parameters
Parameter
Description
file.var
Optional. Specifies a dictionary or data file to clear.

The file must have been opened previously with an OPEN
statement.
If you do not specify a file.var, the system 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 statements to execute if a fatal error occurs because the
file is not open or is read-only.
If you do not specify the ON ERROR clause, the program
terminates under fatal error conditions.
CLEARFILE Parameters
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:
2012 Onsystex Corp.
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
Parameter
Description
file.var
Specifies a dictionary or data file to close. If you do not specify

file.var, the default file is closed. If no default file is open, the
command has no effect.
A default file is created by omitting the file variable in the OPEN
statement.
file is not open.
terminates under fatal error conditions.
CLOSE Parameters
ON ERROR statements
Example
In the following example, the program segment opens and closes the file INVENTORY:
Related Command
OASYS Basic
OPEN
2012 Onsystex Corp.
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
Parameter
Description
seq.file.var
Specifies a sequential access file to close.

The file must have been opened previously with an OPENSEQ
or OSOPEN statement.
file is not open.
terminates under such fatal error conditions.
CLOSESEQ Parameters
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.
Constraints and Considerations

Keep the following points in mind when writing programs that use common to pass variables:
Common variables are not passed when you execute CHAIN to another OASYS Basic program.
Unnamed common is removed when you return to the ECL prompt, but named common remains in memory until
deleted with the ECL DELETECOMMON command, even if the program aborts.
COMMON must be the first noncomment statement in the called program.
CLEARCOMMON sets the common variable to 0. DELETECOMMON removes common variables.
Variables in a common area must be declared the same type, dimension, and in the same order by all programs
accessing them. Programs can declare more or fewer variables, and can change the name of the variables. The
order of the names in a programs COMMON statement determines which names go with which values.
Common names are limited to a length of seven characters. No error message is returned when longer names
are truncated during compilation. In the following example, STRING2 overwrites STRING1 because both
names, commons1 and commons2, are truncated to commons:
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
Declares COM M ON as:A,B(5)
Declares COM M ON as:U,V,W,X,

Y,Z
Assigns values of:A = 4 and B(3) = 5 Therefore:U = 4 and X = 5
Example Renaming COMMON Variables
STACKCOMMON defaults to OFF in BASICTYPEs R and U, but is always ON in BASICTYPEs P and M.

You can use the PASSCOM option for compatibility purposes, but its use is not needed to pass common
variables.
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
2012 Onsystex Corp.
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
Parameter
Description
/common.name/
Specifies a name for a named common variable. common.name can have

any valid variable name no longer than seven characters. Default (no
common name provided) stores the variable in unnamed common.
A variable to place in the named or unnamed common.
A second variable to place in the named or unnamed common areas.
An array to place in the named or unnamed common area. Do not
declare common arrays with a DIM statement. Arrays in a common
cannot be dynamically redimensioned.
You can enter a COM M ON statement on several lines by terminating
each line to be continued with a comma.
COMMON Parameters
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.
2012 Onsystex Corp.
COMMON
97
Here is the output from these programs:
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.
The preceding code produces the following output:
2012 Onsystex Corp.
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
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
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
2012 Onsystex Corp.
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
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
2012 Onsystex Corp.
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
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.
2012 Onsystex Corp.
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
The name of the XM L document to create.

A flag defining the type of xml_document. Valid values are:
nXM L.FROM .FILE - xml_document is a file name.
nXM L.FROM .STRING -xml_document is the name of variable
containing the XM L document.
The name of the U2XM AP file to use to produce the XM L
document.
u2xmap_file
2012 Onsystex Corp.
104
u2xmap_location
The location of the U2XM AP file.

nXM L.FROM .FILE - u2xmap_file is a file name.
nXM L.FROM .STRING - is u2xmap_file the name of variable
containing the mapping rules.
condition
A query condition for selecting data from the OASYS file,

for example, WHERE SCHOOL = "CO002"
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
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:
The following example prints 3:
Related Commands
OASYS Basic
COUNT, COUNTS
2012 Onsystex Corp.
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
DEFFUN func.name(arg, arg,...)

DEFFUN name(arg, arg,...) CALLING func.name
Within the calling program, the name used in the DEFFUN statement and the name used to call the function must
be the same. This does not need to be the same name as the cataloged program file or the name used in the
FUNCTION statement.
Parameters
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:
2012 Onsystex Corp.
DEFFUN
The following example calls a user-defined function named CALC.SALES.TAX:
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
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
2012 Onsystex Corp.
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
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.
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
the program terminates.

DELETE Parameters
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.
2012 Onsystex Corp.
110
The DELETE function and the DEL command perform the same action.
Parameters
Parameter
Description
dyn.array.var
attrib.expr
Specifies the dynamic array from which to delete.

Specifies which attribute of the dynamic array to delete. If val.expr is
omitted, DELETE deletes the entire attribute, including all values and
subvalues.
Specifies which value of the dynamic array attribute to delete. If subval.
expr is omitted, DELETE deletes the entire value, including all subvalues.
Specifies which subvalue of the dynamic array attribute value to delete.
,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.
2012 Onsystex Corp.
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
Parameter
Description
file.var,
Specifies the file from which to delete the record.

file. If no default file is open, a fatal DELETE error occurs.
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,
DELETEU Parameters
record.ID.expr
ON ERROR statements
2012 Onsystex Corp.
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
name1
Specifies the name of the array.

2012 Onsystex Corp.
DIM
rows
,cols
113
Specifies the number of rows in the array.

Specifies the number of columns in the array. If cols is omitted, the array is
one-dimensional.
DIM Parameters
INMAT Function Return Values

After you execute DIM, the OASYS Basic INMAT function returns one of the values described in the following
table.
Value
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:
In contrast, the following statement is valid:
2012 Onsystex Corp.
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
A string containing the digest algorithm name (either M D5 or SHA1).

DIGEST Parameters
Parameter
Description
data
dataLoc
Data or the name of the file containing the data to be digested.

1 - Data in a string2 - Data in a file
result
A string to store the digest result.

DIGEST Parameters (continued)
The following table describes the status of each return code.
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
2012 Onsystex Corp.
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.
2012 Onsystex Corp.
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:
DSTRING now contains why am i happy?.
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
Parameter
Description
val.expr
,precision.expr
Specifies the value to round.

Specifies the precision for the rounding. The valid range is 0 to 14. Default
precision is four places.
DROUND Parameters
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:
2012 Onsystex Corp.
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
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,
2012 Onsystex Corp.
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
Parameter
Description
algorithm
action
A string containing the encode method name. OASYS currently only

supports the Base64 method.
1 - Encode2 - Decode
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
ENCODE Parameters (continued)

Return Code
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
Return Code Status
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
A string containing the cipher name.

1 - Encrypt2 - Base64 encode after encryption3 - Decrypt4 - Base64
decode before encryption
data
dataLoc
Data or the name of the file containing the data to be processed.

key
keyLoc
The actual key (password) or file name containing the key.

1 - Key in data2 - Key in file
keyAction
1 - Use actual key2 - Derive key from pass phrase
Salt
IV
result
resultLoc
A string containing the Salt value.

A string containing IV.
The result buffer or the name of the file storing the result.
1 - Result in a string2 - Result in a file.
ENCRYPT Parameters

Return Code
0
1
2
Success.
Invalid cipher.
Invalid parameters (location/action value is
out of range, etc.).
ENCRYPT Return Codes
Return Code
3
4
5
6
Status
Status
The data cannot be read.

The key cannot be derived.
Base 64 encoding/decoding error.
Encryption/decryption error.
ENCRYPT Return Codes (continued)
2012 Onsystex Corp.
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:
2012 Onsystex Corp.
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
Parameter
Description
variable
expr
Specifies the variable to which to assign the contents of expr.

Specifies a value, string, expression, or variable the value of which variable
is assigned to.
EQ Parameters
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.
2012 Onsystex Corp.
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.
2012 Onsystex Corp.
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
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:
2012 Onsystex Corp.
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
Parameter
Description
expression
substring
The expression in which you want to replace substring.

The substring you want to replace. If substring is an empty string,
replacement is prefixed to expression. If replacement is an empty string, all
occurrences of substring are removed.
The replacement value for substring.
Specifies the number of occurrences of substring to replace. To replace all
occurrences, specify occurrence as a number less than 1.
Specifies the first occurrence of substring to replace. If you omit begin, or
specify a value less than 1, it defaults to 1.
EREPLACE Parameters
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
2012 Onsystex Corp.
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
Parameter
Description
str.expr
Specifies a OASYS command with appropriate parameters. If

you pass a file name to PERFORM , you must use the actual file
name, not a file variable (which is assigned in the OPEN
statement).
ASYNC | SYNC
ON connection
ON ERROR statements OASYS no longer supports this parameter, but it remains for
CAPTURING, dyn.array. The CAPTURING clause stores the output in a dynamic array
var
instead of on the display terminal. Each line of the text becomes
an attribute in the array. Output sent to the printer is not affected
by this clause.
The order of CAPTURING and RETURNING is
interchangeable.
RETURNING, dyn.array. The RETURNING clause captures error messages resulting from
var
the command executed with PERFORM . This variable contains a
string of error message numbers separated by spaces. If the
executed command creates a spooler hold file, OASYS also
returns the hold file number in the same variable.
EXECUTE Parameters
Parameter
Description
2012 Onsystex Corp.
EXECUTE
RTNLIST int.expr
PASSLIST int.expr
PASSCOM
127
The RTNLIST clause must be an integer from 09, designating

the select list to return to the calling program. You can use the
resulting list with subsequent READNEXT statements or in the
PASSLIST clause of an EXECUTE statement. If an expression is
not given after RTNLIST, the generated select list replaces the
contents of list 0. If RTNLIST is not specified, no list is
returned.
If you use EXECUTE to call a OASYS Basic program, no select
list is returned even though you specify RTNLIST. On the other
hand, PASSLIST is always effective and transfers a select list to
the called program.
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, list 0 is assumed.
The passed list can be the result of previous SELECT or
GETLIST commands, or the result of the RTNLIST clause of a
PERFORM statement.
This parameter is provided for backward compatibility for
releases before 3.1.
EXECUTE Parameters (continued)
Reminder: The error message numbers you capture with RETURNING will vary, depending upon which version
of OASYS you are running.
The ECL STACKCOMMON Command

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, the 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. STACKCOMMON is off by default in
BASICTYPEs R and U.
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.
2012 Onsystex Corp.
128
In the next example, the program segment executes a paragraph from within a OASYS Basic program using the
EXECUTE statement:
This paragraph displays the word HELLO on the terminal screen.
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

Parameter
Description
str.expr
Specifies a valid OASYS SQL statement for OASYS to execute.

EXECUTESQL Parameters
Parameter
Description
ASYNC | SYNC

ON connection
ON ERROR statements OASYS no longer supports this parameter, but it remains for
EXECUTESQL Parameters (continued)
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.)
This program produces the following results:
2012 Onsystex Corp.
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.
The program output is:
Related Commands
OASYS Basic
EXECUTE, READNEXT, READNEXTTUPLE
OASYS SQL
For more information about OASYS SQL commands, see the OASYS SQL Commands Reference.
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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
Parameter
Description
dyn.array.expr
attrib.expr
Specifies a dynamic array from which to retrieve the data.

Specifies an attribute of the dynamic array from which to retrieve the
data. If the value of attrib.expr is less than 1, OASYS uses 1.
Specifies a value of attrib.expr from which to extract the data. If the
values of val.expr and subval.expr are 0, or if they do not appear in the
EXTRACT function, OASYS retrieves an attribute.
Specifies a subvalue of the value specified by val.expr in the attribute
specified by attrib.expr, from which to retrieve data.
If the values of val.expr and subval.expr are 0, OASYS retrieves an
attribute. If the value of subval.expr is 0, or if it does not appear in the
EXTRACT function, OASYS retrieves a value.
EXTRACT Parameters
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:
2012 Onsystex Corp.
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
Parameter
Description
string.expr
delim.expr
field.expr
,rep.expr
Specifies the string expression to search.

Specifies the field delimiter.
Specifies the field at which to begin the search.
Specifies the number of fields to return. If you do not specify rep.expr, or it
is less than 1, OASYS returns a default of 1 substring.
FIELD Parameters
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
2012 Onsystex Corp.
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
Parameter
Description
str.expr
delimiter
b.pos
Specifies the target string.

Specifies the character that delimits fields in str.expr.
Specifies the occurrence of the delimiter at which to insert.
If the number of delimiters is less than b.pos, OASYS inserts the appropriate number of spaces and delimiters.
Specifies whether FIELDSTORE will insert before, insert after, or replace
the field at b.pos. Refer to the following FIELDSTORE Options table for
further details.
Specifies the expression (with its associated delimiter) to insert before or
after the specified delimiter.
FIELDSTORE Parameters
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
This program prints the following:
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
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.
2012 Onsystex Corp.
136
Code
Information Requested File Type
Return Value
File open status
ALL
2
3
Full path name of file

File type
Hashing file type
M odulo of file
M inimum modulo 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)
Group size of file
Block size of file
M erge factor percentage
10
Split factor percentage
11
Current load percentage
13
17
Does file contain

alternate key indexes?
Next line number to
read or write
Filename
18
Block size of file
19
Access permissions
20
Index to which the last

SETINDEX statement
was applied
ALL
Permissions the person

running the program has
expressed as total
UNIX values
(r=4,w=2,x=1, so rw=
6)
VOC entry name
21
Index record read by

last browsing
statement, such as
ALL
Key value
14
HASH & DYN

OTHERS
HASH & DYN
OTHERS
DYNAM IC
OTHERS
DYNAM IC
OTHERS
DYNAM IC
OTHERS
HASH & DYN

OTHERS
SEQUENTIAL
OTHERS
HASH & DIR&
DYNAM IC
OTHERS
HASH & DIR&
DYNAM IC
OTHERS
ALL
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
2012 Onsystex Corp.
FILEINFO
137
READFWD and
READBCK.
22
File type: recoverable

or nonrecoverable
ALL
1 Recoverable
0 Nonrecoverable
24
Type of Replication file
ALL
0 File is not a replication object

1 File is a publishing
object
2 File is a subscribing
object
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
Parameter
file.var
ON ERROR statements
LOCKED statements
Description
Specifies the file to lock.
file. If no default file is open, a fatal error occurs.
OPEN statement.
Specifies statements to perform if the FILELOCK statement
fails with a fatal error condition because the file is not open.
terminates abnormally.
Specifies statements to execute if the file is already locked.
FILELOCK Parameters
STATUS Function Return Values

After you execute of the FILELOCK command, the OASYS Basic STATUS function returns 0 if the file was
locked successfully. If the file was already locked, and if the LOCKED clause was included in the FILELOCK
statement, STATUS returns the user number of the process that locked the file.
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
Parameter
Description
file.var
Specifies the file to unlock.

OPEN statement.
Specifies statements to perform if the FILEUNLOCK statement
fails with a fatal error condition because the file is not open.
terminates.
FILEUNLOCK Parameters
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
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.
2012 Onsystex Corp.
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
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
Specifies variables in which to place the position of substr:

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.
THEN
Specifies statements to execute if the substr is found in the array. Either a
statements
THEN statement or an ELSE statement is required.
ELSE statements Specifies statements to execute if the substr is not found in the array. Either
a THEN statement or an ELSE statement is required.
FINDSTR Parameters (continued)
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
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
Specifies a single-byte fill character to be used if the formatted string is not

long enough to fill len; the default is a space. Cannot be a multibyte character.
Prefix a numeric f.char with \ to indicate it is the fill character.
Specifies left-justification in a string of len spaces. If the text is longer than len
, the text is broken in len intervals. Has no effect in multibyte languages.
Specifies right-justification in a string of len spaces. Has no effect in multibyte
languages.
Specifies centered text in the column of width len. Has no effect in multibyte
languages.
Specifies text justification. If data must be broken to fit in a column, it is
justified on a word basis (from space to space). Has no effect in multibyte
languages.
Specifies the maximum number of decimal places allowed, rounding as
necessary. If n = 0, the number is rounded to an integer.
Prints a dollar sign before the formatted string. Valid for numeric data only.
Prints numbers with commas separating each level of thousands. Valid for
numeric data only.
Specifies the suppression of leading zeros.
Specifies a pattern mask composed of numbers and other characters. Numeric
data is placed sequentially in the mask before justification.
FMT Parameters

After you execute FMT, the STATUS function returns one of the values described in the following table.
Value
Description
0
1
2
Successful completion.
String expression is invalid or exceeds the allowable string size.
Conversion code is invalid.
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:
2012 Onsystex Corp.
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
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:
2012 Onsystex Corp.
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.
128.2 Related Commands

OASYS Basic
GETPTR, HEADING, PRINTER
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
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:
2012 Onsystex Corp.
FORMLIST
145
This program segment produces the following results:

OASYS Basic
DELETELIST, READLIST, SELECT, SELECTINDEX, SELECTINFO, WRITELIST
UniQuery
DELETE.LIST, GET.LIST, SELECT, SSELECT, SAVE.LIST For information, see the UniQuery Commands
Reference.
OASYS SQL
130 FOR/NEXT
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.
2012 Onsystex Corp.
146
130.3 Parameters
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
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.
2012 Onsystex Corp.
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.

OASYS Basic
CASE, LOOP/REPEAT
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
2012 Onsystex Corp.
Parameter
Description
function.name
Specifies the name of the function (for documentation purposes

only). It need not be the same as the name used to call the
function.
You must include this functions cataloged file name in the
148
DEFFUN statement in the calling program.
(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.
The program runs and prints out the following text:
131.5 Related Command

OASYS Basic
DEFFUN
2012 Onsystex Corp.
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.
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.
2012 Onsystex Corp.
150

OASYS Basic
GES
134 GES
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
OASYS has read the number of characters specified in length.

After a single character is read (when length and UNTIL are not coded).
When any character you specify in term.exp is encountered in input.
When OASYS reads the record mark character, @RM, and the number of seconds has elapsed.
Note: OASYS never executes the ELSE clause if you include UNTIL without WAITING or length.
If you code the WAITING clause, OASYS executes the ELSE clause only after the number of seconds specified
for timeout. If the input is terminated for any other reason, OASYS executes the THEN clause.
In special cases, OASYS executes the ELSE clause if the line has not been attached before executing the GET
statement.
135.3 Parameters
Parameter
Description
Specifies that GET return var as hexadecimal. This feature

allows binary data to contain a 255 value (hexadecimal FF). For
instance, if a user enters HELLO, the input data variable
contains 48454C4C4F.
Specifies a variable to receive input.
Specifies the number of characters to accept as input from the
attached line. The default is one character unless you use
UNTIL in the statement.
count.var is the number of characters received from the attached
line.
line.expr is the attached line receiving input.
term.expr is a string of characters, any of which terminate input.
The terminating character does not appear in the returned text
variable.
If you use UNTIL and do not specify term.expr, any number of
characters is accepted. Characters often used for the UNTIL
clause are carriage return and line feed.
Assigns the character that terminates the input to term.var.
Input terminates due to:
Reaching the maximum number of characters.
Timeout.
Record mark encountered in input. In this case, term.var
contains an empty string.
Specifies the number of seconds to wait before OASYS times
out.
If the line is not attached, OASYS performs the ELSE clause. If
the line is not attached and there is not an ELSE clause, a
runtime error displays and the user enters the OASYS Basic
debugger.
GET Parameters
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
received, and performs the ELSE clause.

Related Commands
OASYS Basic
SEND
OASYS
PROTOCOL For information, see the OASYS Commands Reference.
136 GETENV
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]
2012 Onsystex Corp.
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
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.
2012 Onsystex Corp.
154

OASYS Basic
DELETELIST, FORMLIST, READLIST, READNEXT, SELECT, SELECTINDEX, SELECTINFO, WRITELIST
UniQuery
Reference.
OASYS SQL
138 GETPTR
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.
138.3 GETPTR Function Return Values

The GETPTR function returns a string containing the same set of values as specified in the ECL SETPTR
function, including the print unit and the options. The following table describes these values.
Return
Description
unit
The number assigned to a given printer through OASYS, from 0 through

255. (The default is 0.)
The number of characters per line, from 0 to 256 characters.
The number of lines per page, from 1 to 32,767 lines.
The number of lines to leave blank at the top of each page, from 0 to 25.
The number of lines to leave blank at the bottom of each page, from 0 to
25.
Destination of output. For mode values, see SETPTR in the OASYS
Commands Reference.
Print options such as BANNER, COPIES, NHEAD, and FORM . For
option values, see SETPTR in the OASYS Commands Reference.
GETPTR Function Return Values
width
length
topmargin
bottommargin
mode
options
2012 Onsystex Corp.
GETPTR
155
138.4 STATUS Function Return Values

After you execute GETPTR, the STATUS function returns one of the values described in the following table.
Value
0
1
2
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:

OASYS
139 GETPU
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 Basic
GETPTR
OASYS
2012 Onsystex Corp.
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.
140.3 GETQUEUE Function Return Values

The GETQUEUE function returns the values described in the following table.
Value
OASNO
USERNBR
UID
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
The name of the locked file.
INBR
The i-node number used by the locked file.
2012 Onsystex Corp.
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
The device number used by the locked file.
RECORD ID
The ID of the record in the file that is being updated.
M ODE
The mode of the command that locked the file.

GETQUEUE Function Return Values (continued)
141 GETREADU
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.
141.3 GETREADU Function Return Values

The GETREADU function returns the values described in the following table.
Value
Description
OASNO
USERNBR
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.
The user name of the user who ran the OASYS application that locked
the file.
The terminal ID of the user who ran the OASYS application that locked
the file.
UID
USERNAM E
TTY
2012 Onsystex Corp.
158
FILE NAM E
INBR
DNBR
RECORD ID
M ODE
TIM E
DATE
The name of the locked file.

The i-node number used by the locked file.
For Windows platforms, this value consists of the high integer and low
integer of the inode used by the locked file. The high integer and the low
integer are separated by a space.
The device number used by the locked file.
The ID of the record in the file that is being updated.
The mode of the command that locked the file.
The time the lock was set.
The date the lock was set.
GETREADU Function Return Values
142 GETUSERGROUP
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:

OASYS Basic
GETUSERID, GETUSERNAME
143 GETUSERID
143.1 Syntax
GETUSERID(user.name)
2012 Onsystex Corp.
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:

OASYS Basic
GETUSERGROUP, GETUSERNAME
144 GETUSERNAME
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:

OASYS Basic
GETUSERGROUP, GETUSERID
2012 Onsystex Corp.
160
145 GOSUB
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
Developing OASYS Basic Applications. This is an example of subroutines used in structured programming style.
In the next example, the program segment prints:

Now we go to the subroutine.
Now in subroutine BRANCHOUT.
Back from subroutine BRANCHOUT.

OASYS Basic
GOTO, ON/GOSUB, RETURN
2012 Onsystex Corp.
GOSUB
161
146 GOTO
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:

OASYS Basic
GOSUB, ON/GOTO
147 GROUP
147.1 Syntax
GROUP(str, delim, start, rtn.num)
2012 Onsystex Corp.
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
Parameter
Description
str
delim
start
rtn.num
Specifies the string from which to extract groups.

Specifies any ASCII character that delimits groups in the string.
Specifies the first of the groups to return.
Specifies the number of continuous groups included in the result.
If the rtn.num is greater than the number of groups remaining in the string,
the function finishes after the entire remaining string is exhausted.
GROUP Parameters
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:

OASYS Basic
FIELD, OCONV Group (G)
148 GROUPSTORE
148.1 Syntax
GROUPSTORE substr IN str USING start.num,replace.num [,delimiter]
2012 Onsystex Corp.
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
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
2012 Onsystex Corp.
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.
This results in:
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.
This results in:
In the next example, the program segment inserts SUB before position 1 in A:
This results in:
In the next example, the program segment replaces the first two attributes and their associated subvalues with
SUB using @VM as the delimiter:
This results in:
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.
2012 Onsystex Corp.
GROUPSTORE
165
149 GT
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.
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.
2012 Onsystex Corp.
166

OASYS Basic
GTS
150 GTS
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
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.
2012 Onsystex Corp.
HASH
167
151.3 Parameters
Parameter
Description
rec.key
modulo
Specifies the record key to hash.

Specifies the file modulo, the number of groups specified when the file was
created.
For the file being tested, specifies static or dynamic and hash type, as determined when the file was created. You can use the following types:
0 Test a static file with hash type 0
1 Test a static file with hash type 1
64 Test a dynamic file with hash type 0
65 Test a dynamic file with hash type 1
HASH Parameters
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
Parameter
ON expr
str.expr
2012 Onsystex Corp.
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.
This results in the following heading: 1207-21-11 12:13:00.

OASYS Basic
FOOTING, GETPTR, PRINTER
OASYS
153 HUSH
153.1 Syntax
HUSH {ON | OFF | expr} [SETTING pre.status.var]
2012 Onsystex Corp.
HUSH
169
153.2 Description
The OASYS Basic HUSH command enables or disables terminal output.
153.3 Parameters
Parameter
Description
ON
OFF
expr
Disables the terminal output.

Enables the terminal output.
Disables the terminal output if expr is not 0. Enables terminal output if
expr is 0. expr must be a numeric value.
The SETTING clause sets the previous terminal status (1 for ON and 0
for OFF) to pre.status.var.
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
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
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

After you execute ICONV, the STATUS function returns one of the values described in the following table.
Value
0
1
2
3
5
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.
2012 Onsystex Corp.
ICONV
171
154.5 Examples
The following program segment demonstrates the date and time conversions:
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.

OASYS Basic
OCONV
155 ICONV Date (D)

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
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
2012 Onsystex Corp.
172
Points to Remember When Entering Dates

To avoid unexpected results when you convert dates into internal date format by using ICONV, be aware of the
following:
If you do not enter a year, OASYS defaults to the current year. For example, if you enter 12/1 and the year is
1996, OASYS stores 10563 (12/1/96).
If you enter a number between 1 and 12 for month, OASYS defaults to the first day of the month in the current
year. For example, if you enter just 12 during 1996, OASYS stores 10563 (12/1/96).
Any two-digit year entered in the range 0029 defaults to the twenty-first century. For example, OASYS
interprets 12/31/29 as December 31, 2029. Any two-digit year entered in the range 3099 is considered to be
19301999.
Converting More Than Once

Depending on the date range, if an application performs ICONV on an already converted date, OASYS could
produce unexpected results. Dates that convert into four- or five-digit internal formats and meet the following
conditions fall into this category:
The first two digits are 10, 11, or 12.
The second two digits are 01 through 31.
The fifth digit is any number from 0 through 9. Where there is no fifth digit, OASYS assigns the current year.
For example, assuming 5/28/95 is the input, the code segment shown on the left results in the displays on the
right:
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.

After you execute ICONV D, the STATUS function returns one of the values described in the following table.
Value
0
1
2
3
Description
Successful conversion of a valid date.
Invalid input date.
Date was converted correctly, but month and day were inverted in input value.
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.
ICONV Date (D)
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

OASYS Basic
DATE, OCONV Date (D), TIMEDATE
156 ICONV Group (G)

156.1 Syntax
ICONV(str.expr, "G[m]*n")
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.
2012 Onsystex Corp.
173
174
156.3 Parameters
Parameter
Description
str.expr
G
m
Indicates a string separated by a delimiter.

Group extraction code.
Indicates the number of strings to skip. If m is omitted, no strings are
skipped.
Specifies any single nonnumeric character that is the delimiter. A minus sign
(-) is not valid. OASYS system delimiters are valid also.
The number of strings to be extracted.
ICONV Group (G) Parameters
*
n
156.4 Example
In the following example, the program segment prints (303):

OASYS Basic
OCONV Group (G)
157 ICONV Length (L)

157.1 Syntax
ICONV(str.expr, "Ln[,m]")
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.
2012 Onsystex Corp.
ICONV Length (L)
175
157.3 Parameters
Parameter
Description
str.expr
L
n
Indicates a string to be searched.

Length conversion code.
Specifies the number of characters the string must match to be extracted.
When m is present, n is the shortest string to be extracted.
Specifies the longest string to be extracted.
ICONV (L) Conversion Parameters
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:

OASYS Basic
OCONV Length (L)
158 ICONV Masked Character (MC)

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.
158.3 Parameters
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
The expression to be searched or converted.

Extracts all alphabetic characters.
Extracts all nonalphabetic characters.
Extracts all alphabetic and numeric characters.
Extracts all special characters (not alphabetic nor numeric).
Converts all occurrences of substring x to substring y.
Converts data to uppercase.
Converts characters to lowercase.
ICONV Masked Character (MC) Parameters
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:

OASYS Basic
ALPHA, CONVERT, DOWNCASE, NUM, OCONV Masked Character (MC), UPCASE
159 ICONV Masked Decimal (MD)

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.
2012 Onsystex Corp.
ICONV Masked Decimal (MD)
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
Parameter
Description
num.expr
The decimal number to be converted. num.expr can be any numeric value

with or without a decimal.
The ICONV function ignores n (for example, if you specify M D32, OASYS
ignores the 3), but it is included in the syntax to maintain consistency with
the OCONV M asked Decimal (M D) function.
ICONV Masked Decimal (MD) Parameters
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.

OASYS Basic
OCONV Masked Decimal (MD)
2012 Onsystex Corp.
178
160 ICONV Left Justify (ML)

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.
160.3 Parameters
Parameter
Description
num.expr
Decimal number to be converted. num.expr can be any numeric value with or

without a decimal.
The ICONV function ignores n (for example, if you specify M L32, OASYS
the OCONV Left Justify (M L) function.
ICONV Left Justify (ML) Parameters
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], [
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:
2012 Onsystex Corp.
ICONV Left Justify (ML)
179
The following example demonstrates how specify an alternate symbol to represent the decimal point in the input
number. This example prints 12350.

OASYS Basic
OCONV Left Justify (ML)
161 ICONV Packed Decimal (MP)

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.

OASYS Basic
OCONV Packed Decimal (MP)
162 ICONV Packed Decimal (MP1)

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


OASYS Basic
OCONV Packed Decimal (MP1)
163 ICONV Right Justify (MR)

163.1 Syntax
ICONV(num.expr, "MRn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] [C] [Z] [(mask)]")
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.
163.3 Parameters
Parameter
Description
num.expr
Decimal number to be converted. num.expr can be any numeric value with or

without a decimal.
The ICONV function ignores n (for example, if you specify M R32, OASYS
the OCONV Right Justify (M R) function.
ICONV Right Justify (MR) Parameters
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
2012 Onsystex Corp.
ICONV Right Justify (MR)
181
[prefix], [
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.

OASYS Basic
OCONV Right Justify (MR)
164 ICONV Time (MT)

164.1 Syntax
ICONV(str.expr, "MT [H] [S] [c]")
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).
164.3 Parameters
Parameter
str.expr
2012 Onsystex Corp.
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
example, HH, M M , SS). The suffixes AM , PM , A, and P also are accepted

at the end of the string. OASYS hours are the same as standard hours, with
12PM as noon (12:00:00) and 12AM as midnight (00:00:00).
A value greater than 24:00:00 (for example, 24:00:01) results in an invalid
conversion.
The remaining options are ignored but are allowed to maintain consistency
with the OCONV Time (M T) function.
ICONV Time (MT) Parameters
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
ICONV Time Examples

OASYS Basic
DATE, OCONV Time (MT), TIME, TIMEDATE
165 ICONV Hex (MX | HEX), Octal (MO), Binary (MB)

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.
165.3 Parameters
Parameter
num.expr
Description
Specifies the decimal value, in display format, to convert to an alternate
numbering system.
2012 Onsystex Corp.
ICONV Hex (MX | HEX), Octal (MO), Binary (MB)
HEX |
M X [0C]
183
Indicates conversion from hexadecimal (base 16). The optional 0C specifier

converts into ASCII character rather than decimal value. HEX is equivalent to
M X0C.
Indicates conversion from octal (base 8). The optional 0C converts to ASCII
character rather than decimal value.
Indicates conversion from binary (base 2). The optional 0C converts to
ASCII character rather than decimal value.
ICONV Numbering System Conversion Parameters
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)
Examples of Numbering System Conversions
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)
2012 Onsystex Corp.
184

OASYS Basic
CHAR; OCONV Hex (MX | HEX), Octal (MO), Binary (MB); SEQ
166 ICONV Pattern Match (P)

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 ICONV Range (R)

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.
167.3 Parameters
Parameter
Description
num.expr
n
d

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. However,
the minus sign (-) should not be used as a delimiter because it refers to a
negative number in the range.
2012 Onsystex Corp.
ICONV Range (R)
185
Separates multiple ranges.

ICONV Range (R) Parameters
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:

OASYS Basic
OCONV Range (R)
168 ICONV SOUNDEX (S)

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.
168.3 Example
The following example is virtual attribute, SDX_LNAME, that converts the value of the variable LNAME to its
SOUNDEX expression:

OASYS Basic
OCONV SOUNDEX (S), SOUNDEX
2012 Onsystex Corp.
186
169 ICONV Text Extraction (T)

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.
169.3 Parameters
Parameter
str.expr
m
n
Description
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
ICONV Text Extraction Examples

OASYS Basic
[], FIND, FINDSTR, OCONV Text Extraction (T)
170 ICONV File Translation (Tfile)

2012 Onsystex Corp.
ICONV File Translation (Tfile)
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
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.
Null Value Handling

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: ICONVS conversion codes are the same as ICONV conversion codes. For information about conversion
codes, refer to ICONV.
171.3 Parameters
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

After you execute ICONVS, the STATUS function returns one of the values described in the following table.
Value
0
1
2012 Onsystex Corp.
Description
Successful conversion.
Invalid input data.
188
2
3
5

Invalid date for D conversion code only.
Null value if null value handling is turned on.
171.5 Example
In the following example, the program segment converts each element of ARR1 to internal format:
This program segment prints the following converted array elements:
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.

OASYS Basic
ICONV, OCONVS
172 IF/THEN/ELSE
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.
2012 Onsystex Corp.
IF/THEN/ELSE
189
Points to Remember when Writing IF/THEN/ELSE Statements

The ELSE clause is optional.
An IF/THEN/ELSE structure can occupy either a single line or several lines. When coding single- line and
multiline statements:
The single-line form does not require an END before the ELSE.
In the multiline form, each clause must contain at least one statement. If you do not want to take any action,
use the NULL command. THEN and ELSE clauses must be delimited by END..
A single-line statement that includes the INPUT command as a part of the THEN clause might not produce the
results you expect. For example, the following statements produce no output:
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.

OASYS Basic
CASE, LOOP/REPEAT, NULL
173 IN
173.1 Syntax
IN( )
2012 Onsystex Corp.
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:

OASYS Basic
DATA, INPUT, INPUT @, INPUTTRAP, SYSTEM
174 INDEX
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
Parameter
Description
str.expr1
str.expr2
num.expr
Specifies the string to search.

Specifies the string for which to search in str.expr1.
Specifies which occurrence of str.expr2 to return.
INDEX Parameters
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.
2012 Onsystex Corp.
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.

OASYS Basic
COL1, COL2, FIELD
175 INDICES
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.
Retrieving Names of Alternate Key Indexes

If you specify only file.var, the INDICES function returns a dynamic array containing the alternate key index
names for all indexes in the file you specify. The index names are not returned in any particular order. Index names
are
separated by attribute marks.
Note: If the index you specify does not exist, the function returns an empty string.
Retrieving Information About Indexes

If you specify the name of an alternate key index (indexname.expr), the INDICES function returns information
about that index in a dynamic array, which consists of six attributes:
Attribute 1 Four values representing the following information in this order:
Type of key (I or D).
Build required (1 or ).
No meaning.
Automatic update enabled (1 or ).
Attribute 2 Location of the alternate key in the record.
Attribute 3 An ASCII string with the time stamp of the last time the index was built (updated by BUILD.
INDEX).
2012 Onsystex Corp.
192
Attributes 4 and 5 Empty.

Attribute 6 Type of attribute:
S for singlevalued.
M for multivalued.
MS for multi-subvalued.
175.3 Parameters
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 Basic
SELECTINDEX, SETINDEX
OASYS
BUILD.INDEX, CREATE.INDEX For information, see the OASYS Commands Reference.
176 INMAT
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.
176.3 INMAT Function Return Values

INMAT is set by the dimensioned array-oriented commands, as shown in the following table.
Command
Meaning
2012 Onsystex Corp.
INMAT
DIM
0 The array was created.

1 Not enough memory was available to create the array.
Command
Meaning
M ATREAD
M ATREADL
M ATREADU
M ATPARSE
n The number of attributes loaded into the array.

0 M ore attributes existed in the record than elements existed in the array.
Excess data is stored in the 0,0 element.
OPEN
n The number of modulos in the file.

0 The file opened is a directory (DIR type).
OSBWRITE
n The number of bytes written to a file or named pipe.

INMAT Function Return Values (continued)
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:
This results in the following:

OASYS Basic
DIM, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATREADU, MATWRITE, MATWRITEU
177 INPUT
2012 Onsystex Corp.
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
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
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
Normally, when a user types something and presses ENTER in response

to an INPUT statement, OASYS issues a line feed. The : parameter
inhibits this line feed.
,-l
OASYS checks the type-ahead buffer. The following values are returned
in var:
1 Data is present in the buffer.
0 No data is present in the type-ahead buffer.
Use the -1 parameter to periodically check for input in an application that
runs continuously.
FOR |
Specifies the length of time to wait for input. If you do not enter the
WAITING time. input before the wait period expires, var does not change, and the ELSE
expr
clause executes. If no ELSE nor THEN clause exists, the session
terminates at the end of the wait period.
UNFILTERED Sets INPUT to capture raw characters (such as backspace, up arrow,
down arrow, or ENTER) from the keyboard.
THEN statements Specifies statements to execute when input is received within the time
specified in the FOR | WAITING clause and input is not an empty string.
ELSE statements Specifies statements to execute if no input is received by the time
specified in the FOR | WAITING clause or if the input is an empty
string.
INPUT Parameters (continued)
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.

OASYS Basic
CLEARINPUT, DATA, IN, INPUT @, INPUTERR, INPUTIF, INPUTNULL, INPUTTRAP, PROMPT, SYSTEM
178 INPUT @
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
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.
2012 Onsystex Corp.
INPUT @
mask
FOR | WAITING
time.expr
UNFILTERED
THEN statements |
ELSE statements
197
Use the underscore parameter you want the capability of backspacing

after entering the maximum number of characters. For example, if you
specify INPUT X,5_, you can backspace to modify the entry after
entering five characters.
Specifies a format or conversion mask. For format options and instructions about building a conversion mask, see OCONV M asked Decimal
(M D).
Specifies the amount of time to wait for input. If the input is not
entered when this period expires, var does not change, and the ELSE
clause executes. If no ELSE nor THEN clause exists, the session
terminates at the end of the wait time.
Sets INPUT @ to capture raw characters (such as backspace, up
arrow, down arrow, or RETURN) from the keyboard.
If the ECL TIM EOUT command has been executed:
THEN executes if the input variable contains at least one character.
ELSE executes if the input variable contains an empty string. If no
ELSE clause is coded, OASYS logs you out and displays the ECL
prompt.
If the ECL TIM EOUT command has not been executed, the program
waits indefinitely for input.
INPUT @ Parameters (continued)
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.
2012 Onsystex Corp.
198

OASYS Basic
CLEARINPUT, DATA, IN, INPUT, INPUTERR, INPUTIF, INPUTNULL, INPUTTRAP, PROMPT, SYSTEM
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
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.
2012 Onsystex Corp.
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:

OASYS Basic
INPUT, INPUT @
181 INPUTIF
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
Parameter
var
THEN statements
ELSE statements
2012 Onsystex Corp.
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

OASYS Basic
CLEARINPUT, INPUT, INPUT @, PROMPT, SYSTEM
182 INPUTNULL
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
2012 Onsystex Corp.
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
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:

OASYS Basic
IN, INPUT, INPUT @, INPUTERR
184 INS
2012 Onsystex Corp.
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
Parameter
Description
expr
dyn.array<attrib.
expr,val.expr,
subval.expr>
Specifies an expression to insert.

Specifies a dynamic array and attribute, value, and subvalue at which to
insert the expression. If any one of these expressions is -1, OASYS inserts
the expr as the last element in the array position.
INS Parameters
184.4 Examples
In the following example, the program segment inserts Zelda, with a new attribute mark, before the second
attribute:
This results in:
In the next example, the program segment inserts Stephen at the end of the array because val.expr is -1:
This results in:

OASYS Basic
FIELDSTORE, INSERT
2012 Onsystex Corp.
INSERT
203
185 INSERT
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
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:
2012 Onsystex Corp.
204
When you execute this program segment, OASYS inserts Alias in the second attribute position:

OASYS Basic
DEL, FIELDSTORE, INS, REMOVE, REPLACE, SUBSTRINGS
186 INT
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
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.

OASYS Basic
BYTELEN, CHARLEN, DISPLAYWIDTH, LEN, MBLEN
188 ISNV
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:
This program results in the following output:
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).
2012 Onsystex Corp.
206

OASYS Basic
ISNVS
189 ISNVS
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
2012 Onsystex Corp.
ISNVS
207
This program results in the following output:

OASYS Basic
ISNV
190 ITYPE
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
functions in the dictionary item.

OASYS Basic
CALCULATE
OASYS
COMPILE.DICT For information, see the OASYS Commands Reference.
Virtual attributes For information, see Using OASYS.
191 LE
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.
2012 Onsystex Corp.
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.

OASYS Basic
LES
192 LEN
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.
2012 Onsystex Corp.
210

OASYS Basic
BYTELEN, CHARLEN, DISPLAYWIDTH, ISMB, LENS, MBLEN
193 LENS
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
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:
ARRAY1 now contains 1}2}3}4}5.

OASYS Basic
BYTELEN, CHARLEN, DISPLAYWIDTH, ISMB, LEN, MBLEN
194 LES
194.1 Syntax
LES(array1,array2)
2012 Onsystex Corp.
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
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.
LISTUSER Dynamic Array (UNIX)

The following table describes the information in the LISTUSER array, by position.
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:
LISTUSER Dynamic Array (Windows Platforms)

The following table lists the LISTUSER command display attributes.
2012 Onsystex Corp.
212
Parameter
OASNO
USRNBR
UID
USRNAM E
USRTYPE
TTY
TIM E
DATE
Description
System-level process ID (pid) assigned to a OASYS session.
System-level ID assigned to a user.
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:
LISTUSER Dynamic Array (Windows Platforms)

The following table lists the LISTUSER command display attributes.
Parameter
OASNO
USRNBR
UID
USRNAM E
USRTYPE
TTY
IP-ADDRESS
TIM E
DATE
Description
Process ID of the OASYS session.
Windows ID of the user.
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
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.
2012 Onsystex Corp.
LN
213

OASYS Basic
EXP
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
Parameter
element
dyn.array <attrib.expr ,
val.expr,subval.expr>
2012 Onsystex Corp.
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
Specifies the attribute, value, or subvalue in the array at which to

begin the search.
Selects a type of search appropriate for the physical arrangement
of a sorted array.
AL Ascending, contents left-justified.
AR Ascending, contents right-justified.
DL Descending, contents left-justified.
DR Descending, contents right-justified.
When OASYS first retrieves the data, it sorts the data in the
requested order.
Do not use a BY clause in a LOCATE statement on an unsorted
array. The search could terminate before checking all elements.
CUST.OPTIONS 85 modifies the sort to place negative numbers
first rather than sort them in ASCII order.
LOCATE Parameters
Parameter
Description
SETTING location
Returns the location of the string. If the search is not successful,

execution depends on the presence of the BY clause:
If the BY clause is included, the array is assumed to be sorted,
and a location is returned indicating where the element should be
inserted to maintain the array in sorted order.
If the BY clause is not included, the array is assumed to be
unsorted, and the location returned is of the last element plus one.
THEN (optional) is executed when the search is successful.
M ultiple line THEN or ELSE statements require an END
keyword.
ELSE (required) is executed if the search is unsuccessful.
M ultiple line THEN or ELSE statements require an END
keyword.
LOCATE Parameters (continued)
THEN statements END
ELSE statements END
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
LOCATE in BASICTYPEs U, P, and M

The following table compares the searches performed in BASICTYPEs U, P, and M.
LOCATE Parameter
in BASICTYPE U
no expr
Performs no search; invalid

syntax.
attrib.expr
val.expr
in BASICTYPEs P and M
Searches all attributes; match

must include associated values
and subvalues.
Searches the attribute
Searches values associated with
specified; match must include the specified attribute; match
associated values and
must include associated
subvalues.
subvalues.
Searches the value specified; Searches subvalues associated
match must include associated with the specified value.
subvalues.
2012 Onsystex Corp.
LOCATE
subval.expr
215
Searches subvalues associated Performs no search; invalid

with the specified value;
syntax.
begins with the specified
subvalue.
Comparison of BASICTYPEs U, P, and M
197.4 Examples
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
executes the first PRINT statement:
However, in the following array, the LOCATE command does not find DEVITO, and OASYS executes the second
PRINT statement:

OASYS Basic
FIND, FINDSTR
198 LOCK
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
Parameter
Description
resource.num
Specifies a number associated with a resource. resource.num can

be any number from 0 through 63.
For assistance in assigning resource numbers, see your system
administrator.
2012 Onsystex Corp.
LOCK
THEN statements END

ELSE statements END
217
Specifies statements to execute if the LOCK statement executes

successfully.
Specifies statements to execute if another user has reserved the
resource (using the same resource number) so that the LOCK
statement fails to lock it.
If you do not specify an ELSE clause and the requested resource
has already been locked, the current program waits until that
resource is released.
Use the ECL command DEFAULT.LOCKED.ACTION BELL
to make the terminal beep while you wait for OASYS to release
the lock.
LOCK Parameters
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 Basic
UNLOCK
OASYS
CLEAR.LOCKS, LIST.LOCKS, SUPERCLEAR.LOCKS, DEFAULT.LOCKED.ACTION For information, see the
OASYS Commands Reference.
199 LOOP/REPEAT
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
2012 Onsystex Corp.
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
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
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:
2012 Onsystex Corp.
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.
The result of this program:

OASYS Basic
CASE, CONTINUE, FOR/NEXT
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:
2012 Onsystex Corp.
220
The dynamic array D.STR now contains the string:

OASYS Basic
RAISE
201 LT
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.
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.
2012 Onsystex Corp.
LT
221

OASYS Basic
LTS
202 LTS
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
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
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.
If the arrays contain the following values before the assignment:
the values assigned to FEE1 would be:
2012 Onsystex Corp.
MAT
223

OASYS Basic
DIM, INMAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATREADU, MATWRITE,
MATWRITEU
204 MATBUILD
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
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
Specifies the starting position in the dimensioned array. If start.num

is less than or equal to 0, OASYS defaults to 1. The dynamic array is
not generated if start.num is greater than end.num.
Specifies the ending position in the dimensioned array.
If end.num is less than or equal to 0, or if it is beyond the end of the
dimensioned array, OASYS retrieves data to the end of the
dimensioned array.
The USING clause specifies the delimiter delim in the dyn.array
generation. If you do not specify delim, or if you specify an empty
string, delim defaults to @AM (attribute mark). If you specify more
than one character, only the first character is used. OASYS inserts
delim between the elements if dyn.array.
MATBUILD Parameters (continued)
,end.num
USING delim
2012 Onsystex Corp.
224
204.4 Examples
In the following example, A is a dimensioned array with five elements:
The following program statement:
generates the following dynamic array:
The next program statement:
generates the following dynamic array:

OASYS Basic
DIM, INMAT, MAT, MATPARSE, MATREAD, MATREADL, MATREADU, MATWRITE, MATWRITEU
205 MATCH
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.
2012 Onsystex Corp.
MATCH
225
205.4 Parameters
Parameter
Description
var
~
Specifies the variable to compare with the M ATCH expression.

Reverses the pattern. To match 4N, a string must contain four numeric
characters. To match ~4N, a string must contain four characters that are not
all numeric.
Specifies the number of characters to match.
Specifies that characters can be of any type.
MATCH Parameters
len
X
Parameter
Description
Specifies that only alphabetic characters match the pattern.
Specifies that only numbers match the pattern.
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.
2012 Onsystex Corp.
226
206 MATCHFIELD
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
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
N
Specifies that only numbers match the pattern.
text
Specifies a literal string to search for.
field.expr
Specifies a portion of the str.expr to return. Each code segment is considered to
2012 Onsystex Corp.
MATCHFIELD
227
be a field for the purposes of field.expr.

MATCHFIELD Parameters (continued)
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
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
Parameter
dim.array
str.expr
delim.expr
2012 Onsystex Corp.
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

After you execute MATPARSE, the INMAT function returns one of the values described in the following table.
Value
Description
n
0
The number of elements loaded into the array.

The array was too small to contain all elements in the string. All excess data
(including delimiters) is placed in the 0,0 element.
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.
The preceding program segment produces the following dimensioned array:
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.
The preceding program segment produces the following dimensioned array:

OASYS Basic
DIM, INMAT, MAT, MATBUILD, MATREAD, MATREADL, MATREADU, MATWRITE, MATWRITEU
2012 Onsystex Corp.
MATREAD
229
208 MATREAD
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
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.
file. If no default file is open, a fatal READ error occurs.
OPEN statement.
Specifies the record from which to read.
MATREAD Parameters
Description
ON ERROR statements
Specifies statements to execute if the M ATREAD 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.
THEN statements END THEN executes if the read is successful. END is required to
terminate multiline THEN statements.
ELSE statements END
ELSE executes if the read is not successful or the record (or ID)
does not exist. END is required to terminate multiline ELSE
statements.
MATREAD Parameters (continued)

After you execute MATREAD, the INMAT function returns one of the values described in the following table.
2012 Onsystex Corp.
230
Value
Meaning
n
0
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 0,0 element.
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:

OASYS Basic
DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREADL, MATREADU, MATWRITE, MATWRITEU
209 MATREADL
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
2012 Onsystex Corp.
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
Parameter
Description
dim.array
FROM file.var,
OPEN statement.
Specifies the record from which to read the attributes.
record.ID.expr
MATREADL Parameters
Parameter
Description
ON ERROR statements
Specifies statements to execute if the M ATREADL statement

fails with a fatal error because the file is not open, an I/O error
occurs, or OASYS cannot find the file.
LOCKED statements
Specifies statements to execute if the record is locked by another
user. If you do not specify a LOCKED clause, the program waits
until OASYS releases the lock on the record. You can place the
LOCKED clause after the FROM clause.
to make the terminal beep while you wait for OASYS to unlock
the record.
ELSE statements END
statements.
MATREADL Parameters (continued)

After you execute MATREADL, the INMAT function returns one of the values described in the following table.
Value
n
0
2012 Onsystex Corp.
Description
The array was too small to contain all attributes in the record. The excess data
(including delimiters) is placed in the zero element.
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 Basic
DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADU, MATWRITE, MATWRITEU
OASYS
DEFAULT.LOCKED.ACTION For more information, see the OASYS Commands Reference.
210 MATREADU
210.1 Syntax
MATREADU dim.array FROM [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
MATREADU dim.array FROM [file.var,] record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
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
Parameter
Description
dim.array
FROM file.var
OPEN statement.
Specifies the record from which to read the attributes.
Specifies statements to execute if the M ATREADU statement
until the lock on the record is released. You can place the
to beep the terminal while waiting for the record to be unlocked.
THEN executes if the read is successful. END is required to
statements.
MATREADU Parameters
record.ID.expr
ON ERROR statements
LOCKED statements
THEN statements END

ELSE statements END

After you execute MATREADU, the INMAT function returns one of the values described in the following table.
Value
Description
n
0

The array was too small to contain all attributes in the record. All excess data
(including delimiters) is placed in the zero element.
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 Basic
DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATWRITE, MATWRITEU
OASYS
DEFAULT.LOCKED.ACTION For information, see the OASYS Commands Reference.
211 MATWRITE
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
211.3 Parameters
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.
MATWRITE Parameters (continued)

After you execute MATWRITE, the STATUS function returns one of the values described in the following table.
Value
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:

OASYS Basic
DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATREADU, MATWRITEU
212 MATWRITEU
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.
2012 Onsystex Corp.
236
212.3 Parameters
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
If you do not specify the ON ERROR clause and a fatal error occurs,
MATWRITEU Parameters
ON | TO file.var,
record.ID.exp
ON ERROR
statements

After you execute MATWRITEU, the STATUS function returns one of the values described in the following
table.
Value
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.
-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.

niBasic
DIM, INMAT, MAT, MATBUILD, MATPARSE, MATREAD, MATREADL, MATREADU, MATWRITE
213 MAXIMUM
2012 Onsystex Corp.
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:

OASYS Basic
MINIMUM
214 MBLEN
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.
2012 Onsystex Corp.
238

OASYS Basic
BYTELEN, CHARLEN, DISPLAYWIDTH, ISMB, LEN
215 MDPERFORM
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
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
Parameter
Description
str.expr
Specifies a OASYS command with appropriate parameters. If you pass

a file name to M DPERFORM , you must use the actual file name, not a
file variable (which is assigned in the OPEN statement).
CAPTURING, dyn. The CAPTURING clause stores the output in a dynamic array instead
array.var
of on the display terminal. Each line of the text becomes an attribute in
the array. Output sent to the printer is not affected by this clause.
RETURNING, dyn. The RETURNING clause captures error messages resulting from the
array.var
command executed with M DPERFORM . This variable contains a string
of error message numbers separated by spaces. If the executed command
creates a spooler hold file, OASYS also returns the hold file number in
the same variable.
MDPERFORM Parameters
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:
2012 Onsystex Corp.
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 Basic
COMMON, EXECUTE, EXECUTESQL, PCPERFORM, OASEXECUTE
OASYS
STACKCOMMON For more information, see the OASYS Commands Reference.
216 MINIMUM
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.
2012 Onsystex Corp.
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:

OASYS Basic
MAXIMUM
217 MOD
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.
2012 Onsystex Corp.
242
218 NE
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.
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
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.

OASYS Basic
NES
219 NEG
2012 Onsystex Corp.
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:

OASYS Basic
ABS
220 NES
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
now contains 0}0}0}1}1.
221 NOCONVERT
2012 Onsystex Corp.
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
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).
2012 Onsystex Corp.
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.

OASYS Basic
#, NOTS
223 NOTS
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
224.1 Syntax
NULL
2012 Onsystex Corp.
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:
2012 Onsystex Corp.
NUM
247
In the next example, the program segment prints 1 because VAR contains an integer:

OASYS Basic
ALPHA, ICONV Masked Character (MC), NUMS, OCONV Masked Character (MC)
226 NUMS
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.

OASYS Basic
ICONV Masked Character (MC), OCONV Masked Character (MC)
2012 Onsystex Corp.
248
227 OCONV
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
Note: In BASICTYPE P, OCONV returns an empty string if CUST.OPTIONS 56 is on and the input value or
227.3 Parameters
Parameter
Description
expr
conv.code.expr
Specifies the expression, a string or numeric data, to convert.

Specifies an internal representation format to use when converting expr.
OCONV Parameters
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
2012 Onsystex Corp.
OCONV
Tfile
249
File translation.
OCONV Codes (continued)

OASYS Basic
ICONV
228 OCONV Date (D)

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
228.3 Parameters
integer.exp
Indicates a date in internal format.
OCONV Date (D) Parameters
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.
2012 Onsystex Corp.
250
fmt
Format for date display. The following formats are available:

mm dd yy[yy]
day month year
yy[yy] mm dd
Combine the output format codes in the following table to format the date.
The syntax for format codes is the following:
[D | W | WA] [ [M ] [Y] | Q | QA]] [J] [[,] {An | Zn} [[,] {An | Zn}...]
OCONV Date (D) Parameters (continued)
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.

After you execute OCONV D, the STATUS function returns one of the values described in the following table.
Value
Description
0
1
2
Successful conversion of a valid date.

The input date was invalid.
The conversion code was invalid.
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.
2012 Onsystex Corp.
OCONV Date (D)
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):
In the following example, the program statement prints J 1970 4:
Some sample format codes are applied in the following table.

Input Value
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
OCONV Date Examples

OASYS Basic
DATE, ICONV Date (D), TIMEDATE
OASYS
DATE, DATE.FORMAT, SET.TIME For information, see the OASYS Commands Reference.
229 OCONV Group (G)

229.1 Syntax
OCONV(str.expr, "G[m]x n")
2012 Onsystex Corp.
252
229.2 Description
The OCONV group (G) function extracts one or more strings separated by a delimiter. If the input value or
229.3 Parameters
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):

OASYS Basic
ICONV Group (G)
230 OCONV Length (L)

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.
2012 Onsystex Corp.
OCONV Length (L)
253
230.3 Parameters
str.exp
n
m

Specifies the number of characters the string must match to be extracted.
When m is present, n is the shortest string to be extracted.
OCONV Length (L) Parameters
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:

OASYS Basic
ICONV Length (L)
231 OCONV Masked Character (MC)

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.
231.3 Parameters
Parameter
2012 Onsystex Corp.
Description
254
str.expr
A
/A
B
/B
C;x;y
U
L
The expression to be searched or converted.

Extracts all alphabetic characters.
Extracts all nonalphabetic characters.
Extracts all alphabetic and numeric characters.
Extracts all special characters (not alphabetic nor numeric).
Converts all occurrences of substring x to substring y.
Converts data to uppercase.
Converts characters to lowercase.
OCONV Masked Character (MC) Parameters
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.
Extracts all numeric characters (0-9).
/N
Extracts all nonnumeric characters.
Converts all nonprinting characters to tildes (~).
X[D] or D
Assumes input is in hexadecimal; converts to decimal.
D[X] or X
Converts input to hexadecimal.

OCONV Masked Character (MC) Parameters (continued)
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.
OCONV Masked Character (MC)
255
OCONV removes the special characters the user might have entered in a formatted date. For example, the
statement extracts 1234 from $12.34.

OASYS Basic
ALPHA, CONVERT, DOWNCASE, ICONV Masked Character (MC), NUM, UPCASE
232 OCONV Masked Decimal (MD)

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
232.3 Parameters
Some parameters set the same values. Results are unpredictable if you make conflicting assignments.
Parameter
Description
num.expr
n
Indicates a number to be formatted.

Sets precision (the number of decimal places represented). It can be a number
between 0 and 9. If n is less than the number of decimal points in the input
data, the resulting value is rounded.
Scales the input value num.expr by moving the decimal point f places to the
left. If omitted, f defaults to the value assigned to n (for example, if you
specify M D2, OASYS reads it as M D22).
OCONV Masked Decimal (MD) Parameters
Parameter
2012 Onsystex Corp.
Description
256
prefix], [
thsnd_mark], [
dec_symbl], [
suffix]
,
$
< or E
C
D
P
Z
T
xc
The square brackets enclosing these parameters are required.

prefix Nonnumeric character(s) to precede the formatted number. For
example, M D2[**] produces "**nnn...".
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 D2[,',' ]" produces
"...,nnn,nnn".
dec_symbl Alternate symbol to represent the decimal point.
suffix Nonnumeric character(s) to follow the formatted number. For
example, M D2[, , ,**] produces "...nnn**".
Inserts commas to separate thousands, millions, and so forth.
Precedes the output with a dollar sign ($).
Specifies the negative sign (for negative data) to precede negative numbers.
Specifies that negative data is surrounded by brackets.
Specifies that negative data is followed by CR, indicating a credit.
Specifies that negative data is followed by DB, indicating a debit.
Specifies that no scaling is performed if a decimal is present in the input
value.
Specifies that zeros are to be suppressed.
Specifies that the number is to be truncated, not rounded to the number of
decimal places specified in n.
Specifies that the character c is used to fill spaces left to the left of the
number after output data is formatted. x indicates the size of the mask.
OCONV Masked Decimal (MD) Parameters (continued)
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.

OASYS Basic
ICONV Masked Decimal (MD)
2012 Onsystex Corp.
OCONV Left Justify (ML)
257
233 OCONV Left Justify (ML)

Syntax
OCONV(str.expr, "MLn [f] [ [ [prefix], [thsnd_mark], [dec_symbl], [suffix] ] ] [,] [$] [C] [Z] [(mask)]")
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,
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.
233.2 Parameters
Note: Some parameters set the same values. Results are unpredictable if you make conflicting assignments
Parameter
Description
str.expr
n
Indicates a text string or number to be left-justified and formatted.

Sets precision (number of decimal places represented). It can be a number
from 0 through 9. If n is less than the number of decimal points in the
input data, the resulting value is rounded.
Scales the input value num.expr by moving the decimal point f places to
the left. If omitted, f defaults to the value assigned to n (for example, if
you specify M L2, OASYS reads it as M L22).
OCONV Left Justify (ML) Parameters
Parameter
Description
[ [prefix], [
thsnd_mark], [
dec_symbl], [suffix]

example, M L2[**] produces "**nnn...".
]
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".
2012 Onsystex Corp.
258

example, M L2[, , ,**] produces "...nnn**".
,
Inserts commas to separate thousands.
Precedes the number with a dollar sign ($).
Specifies negative data to be followed by CR indicating a credit.
Suppresses zeros.
mask
Specifies a mask to be used for formatting. Use # to represent number

placement. Include special characters as desired.
Results are adversely affected if the mask contradicts other parameters.
For example, placement of the decimal in the mask overrides n.
OCONV Left Justify (ML) Parameters (continued)
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
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:

OASYS Basic
ICONV Left Justify (ML)
2012 Onsystex Corp.
OCONV Packed Decimal (MP)
259
234 OCONV Packed Decimal (MP)

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.

OASYS Basic
ICONV Packed Decimal (MP)
235 OCONV Packed Decimal (MP1)

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

OASYS Basic
ICONV Packed Decimal (MP1)
236 OCONV Right Justify (MR)

2012 Onsystex Corp.
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.
236.3 Parameters
Some parameters set the same values. Results are unpredictable if you make conflicting assignments.
Parameter
Description
str.exp
n
Indicates a text string or number to be right-justified and formatted.

Sets precision (number of decimal places represented). It can be a
number from 0 through 9. If n is less than the number of decimal points
in the input data, the resulting value is rounded.
f
Scales the input value num.expr by moving the decimal point f places to
the left. If omitted, f defaults to the value assigned to n (for example, if
you specify M R2, OASYS reads it as M R22).
[prefix], [
thsnd_mark], [
dec_symbl], [suffix] example, M R2[**] produces "**nnn...".
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 R2[,','
]" produces "...,nnn,nnn".
example, M R2[, , ,**] produces "...nnn**".
,
Inserts commas to separate thousands.
$
Precedes the formatted number with a dollar sign ($).
C
Specifies that a negative number is to be followed by CR, indicating a
credit.
Z
Suppresses zeros.
mask
Specifies a mask to be used for formatting. Use # to represent number
placement. Include special characters as desired.
Results are adversely affected if the mask contradicts other parameters.
For example, placement of the decimal in the mask overrides n.
OCONV Right Justify (MR) Parameters
If the conversion to display format is unsuccessful, OASYS returns the original value.
2012 Onsystex Corp.
OCONV Right Justify (MR)
261
236.4 Examples
In the following example, OASYS converts the value 123456789 to 123-45-6789 because it right-justifies it into the
mask ####-##-####:
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.
In the following example, OASYS converts the value 123456 to 1,234.56:

OASYS Basic
237 OCONV Time (MT)

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.
237.3 Parameters
Parameter
Description
num.expr
H
Indicates a number to be converted.

Indicates that hours are to be formatted in 12-hour format with a.m. or p.m.
suffixes.
Indicates that seconds are to be included in the output.
Specifies a delimiter to be placed between hours, seconds, and fractions of
seconds.
OCONV Time Conversion (MT) Parameters
S
c
Note: A program that you can use to try out ICONV and OCONV conversion codes is provided in Developing
OASYS Basic Applications..

OASYS Basic
DATE, ICONV Time (MT), TIME, TIMEDATE
238 OCONV Hex (MX | HEX), Octal (MO), Binary (MB)

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.
238.3 Parameters
2012 Onsystex Corp.
OCONV Hex (MX | HEX), Octal (MO), Binary (MB)
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

OASYS Basic
CHAR, ICONV Hex (MX | HEX), Octal (MO), Binary (MB), SEQ
239 OCONV Pattern Match (P)

2012 Onsystex Corp.
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.
239.3 Parameters
str.expr
op

Specifies the pattern to search for in str.expr.
nN Integer followed by N tests for that number of numeric characters.
nA Integer followed by A tests for that number of alpha characters.
nX Integer followed by X tests for that number of alphanumeric characters.
lit.str Indicates a literal string to be searched for in str.expr.
Separates multiple patterns.
OCONV Pattern Match (P) Parameters
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 OCONV Range (R)

240.1 Syntax
OCONV(num.expr, "Rndm[;ndm.....]")
2012 Onsystex Corp.
OCONV Range (R)
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.
240.3 Parameters
Parameter
num.expr
n
d
m
;
Description
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.
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:

OASYS Basic
ICONV Range (R)
241 OCONV SOUNDEX (S)

241.1 Syntax
OCONV(str.expr, "S")
2012 Onsystex Corp.
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
For more information on SOUNDEX conversion codes, see the SOUNDEX command.
241.3 Parameters
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:

OASYS Basic
ICONV SOUNDEX (S), SOUNDEX
242 OCONV Text Extraction (T)

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.
2012 Onsystex Corp.
OCONV Text Extraction (T)
267
242.3 Parameters
Parameter
str.expr
m
n
Description
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
DAM N THE TORPEDOES T3,5

CONVERSION IS THE KEY T1,9
457 COLORADO BLVD
T4,7
OCONV Text Extraction (T) Examples

OASYS Basic
[], FIND, FINDSTR, ICONV Text Extraction (T)
243 OCONV File Translation (Tfile)

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
2012 Onsystex Corp.
268
243.3 Parameters
rec.id
DICT
filename
c
Specifies the ID of the record to be accessed. Can be a literal or a variable.

Include to access the dictionary file.
Specifies the name of the file to be accessed (any valid OASYS file in your
VOC file containing the required attribute or data).
One of the following translate subcodes:
V If the record does not exist, or if the attribute is an empty string, return an
empty string and print an error message.
C If the record does not exist, or if the attribute is an empty string,
substitute id.expr for the value of the function.
X If the record does not exist, or if the attribute is an empty string, return an
empty string.
OCONV File Translation (Tfile) Parameters
n
Indicates the number of the value of a multivalued attribute to retrieve. If n is

not included, OASYS retrieves all values of the attribute.
I-Attribute
Specifies the number of the attribute to be retrieved during input conversion.

If I-Attribute is omitted, OASYS retrieves the record ID.
O-Attribute
Number of the attribute to be retrieved during output conversion (OCONV).

If the O-Attribute is omitted, OASYS retrieves the record ID.
OCONV File Translation (Tfile) Parameters (continued)
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.
The following output is obtained by running the preceding program:
In the next example, the program statement translates the TAPE_ID to the TAPES file and returns the name of the
tape:
2012 Onsystex Corp.
OCONV File Translation (Tfile)
269

ICONV File Translation (Tfile)
244 OCONVS
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,
Note: In BASICTYPE P, OCONVS returns an empty string if CUST.OPTIONS 56 is on and the input value or
OCONVS conversion codes are the same as OCONV conversion codes. For information about conversion
codes, see OCONV.
244.3 Parameters
Parameter
Description
dyn.array.expr
conv.code.expr
Specifies a dynamic array, each element of which to convert.

Specifies a code to use in converting each element of the dynamic
array.
OCONVS Parameters
244.4 Examples
In the following example, the program segment converts each element of ARR1 to output format:
The preceding program segment prints the following output:
2012 Onsystex Corp.
270

OASYS Basic
OCONV, ICONVS
245 ON/GOSUB
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
expr
label
:
Specifies a numeric expression. OASYS evaluates the expression, and then

truncates it to an integer. Control passes to a subroutine based on the
following rules.
If expr is less than or equal to 1, OASYS transfers program control to the
subroutine starting at the first label in the list. If the number is 2, OASYS
transfers control to the subroutine starting at the second label, and so forth.
If expr is higher than the number of labels, OASYS transfers control to the last
label in the list.
If expr is nonnumeric, control transfers to the first label.
Specifies a subroutine label or multiple subroutine labels.
Optional. A colon is required to identify a nonnumeric label in the statement
label itself only, not in the reference to it in the ON/GOSUB statement.
ON/GOSUB Parameters
2012 Onsystex Corp.
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).

OASYS Basic
GOSUB, GOTO, ON/GOTO, RETURN
246 ON/GOTO
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
2012 Onsystex Corp.
272
expr
label
:
Specifies a numeric expression. OASYS evaluates the expression, and then

truncates it to an integer. Control passes to a statement label based on the
following rules:
If expr is less than or equal to 1, OASYS transfers program control to the label
starting at the first label in the list. If the number is 2, OASYS transfers control
to the label starting at the second label, and so forth.
If expr is higher than the number of labels, OASYS transfers control to the last
label in the list.
If expr is nonnumeric, control transfers to the first label.
Specifies a statement label or multiple statement labels.
Optional. A colon is required to identify a nonnumeric label in the statement
label itself only, not in the reference to it in the ON/GOTO statement.
ON/GOTO Parameters
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.

OASYS Basic
GOSUB, GOTO, ON/GOSUB
247 OPEN
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
2012 Onsystex Corp.
OPEN
247.3 Parameters
Parameter
Description
expr
Specifies the portion of file type to open:

OASYS opens a data file.
DICT OASYS open a dictionary file.
Specifies the name of the file to open.
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.
OPEN Parameters
filename
READONLY
Parameter
Description
TO file.var
Specifies a file variable in which to place a pointer to the opened file.

If you do not specify file.var, the file you open becomes the default file.
OASYS performs all default file operations on this file. (Default file
statements include all types of read, write, or delete when no file
variable specified).
A single default file can be declared in each OASYS Basic program or
subroutine, and the default file is specific to the program or subroutine
in which it is defined. If a main program opens a default file, and then
calls an display subroutine that also opens a default file, OASYS
restores the original default file when returning to the main program.
The ON ERROR clause enables the program to continue to perform
when a fatal error occurs such as when the file is not open, an I/O error
If a VOC entry exists for a file that does not exist, the ON ERROR
clause executes. However, if no VOC entry exists, the ELSE statement
executes.
THEN executes if the open is successful. END is required to terminate
multiline THEN statements.
ELSE executes if the OPEN is not successful or the record does not
exist.
If the file exists, but some other error occurs, the ELSE statement
executes. However, if a file does not exist and no VOC entry exists, the
ELSE statement executes.
END is required to terminate multiline ELSE statements.
OPEN Parameters (continued)
ON ERROR
statements
THEN statements
END
ELSE statements
END

After you execute OPEN, the INMAT function returns one of the values described in the following table.
Value
n
0
2012 Onsystex Corp.
Description
The number of modulos for the file.
The file opened is a directory.
273
274
247.4 Examples
In the following example, OASYS converts the value 123456789 to 123-45-6789 because it right-justifies it into the
mask ####-##-####:
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.
In the following example, OASYS converts the value 123456 to 1,234.56:

OASYS Basic
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]}
2012 Onsystex Corp.
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
Parameter
Description
absolutepath
seq.filename
record.id
The operating system path and sequential file name.

Specifies a OASYS directory type file name.
Specifies a record in the sequential file at which to start accessing.
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
until the lock on the record is released. You can place the
the record.
statements.
OPENSEQ Parameters
TO seq.file.var
ON ERROR statements
LOCKED statements
THEN statements END

ELSE statements END
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:
2012 Onsystex Corp.
276

OASYS Basic
CLOSESEQ, OPEN, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, OSOPEN, OSREAD, OSWRITE, READSEQ,
WEOFSEQ, WRITESEQ, WRITESEQF
OASYS
DEFAULT.LOCKED.ACTION For information, see OASYS Commands Reference.
249 OR
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.

OASYS Basic
AND, NOTS, OR
250 OSBREAD
2012 Onsystex Corp.
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.
Reading from a Named Pipe

Keep these points in mind when you write programs that read from named pipes:
Unlike a typical read, reading a named pipe removes the data.
Your application should check the length of var after reading a pipe. The value returned could be shorter than
length.expr.
OASYS truncates the data if it is longer than length.expr.
Reading Other Types of Files

Processing of files that are not named pipes is determined by the presence or absence of the AT clause:
If the AT clause is included, OASYS Basic begins reading from the file at the offset specified by byte.expr.
If the AT clause is not included, OASYS Basic begins reading from the current location of the file pointer.
Because named pipes must be read from the beginning, the AT clause is not appropriate for accessing them. If
the AT clause is specified, the ON ERROR executes, and the OASYS Basic STATUS function is set to 2. If the
ON ERROR clause is not included, the program aborts.
After successful execution of OSBREAD against a file that is not a named pipe, the file pointer remains at the
next byte after the data read.
250.3 Parameters
Parameter
Description
var
FROM file.var
AT byte.expr
Specifies a variable to which to assign the data read.

Specifies a file from which to read the data.
Specifies a location in the file from which to begin reading data.
If byte.expr is 0, the read begins at the beginning of the file.
When reading a named pipe, do not specify an AT clause. Pipes
are always read with no offset.
Specifies a length of data to read from the file, starting at byte.
expr.
length.expr cannot be longer than the maximum string length
determined by your system configuration.
Forces an immediate read of a named pipe regardless of whether
the pipe contains data. If you do not specify NODELAY, the
process attempting to read waits until the pipe is opened for
LENGTH length.expr
NODELAY
2012 Onsystex Corp.
278
writing and data is written to it.

If filename is not a named pipe, NODELAY has no effect.
ON ERROR statements
Specifies statements to execute if a fatal error occurs (if the file is

not open, or if the file is a read-only file). If you do not specify
the ON ERROR clause, the program terminates under such fatal
error conditions.
OSBREAD Parameters

After you execute OSBREAD, the STATUS function returns one of the values described in the following table.
Value
Description
0
1
2
3
4
The read was successful.

The file name is invalid.
Access is denied by the operating system.
The file does not exist.
An unknown error occurred.
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.

OASYS Basic
CLOSESEQ, OPENSEQ, OSBWRITE, OSCLOSE, OSDELETE, OSOPEN, READSEQ, WRITESEQ, WRITESEQF
251 OSBWRITE
2012 Onsystex Corp.
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.
Writing to Named Pipes

The combination of the following conditions and command options determine the action taken by OASYS Basic
when OSBWRITE is executed against a named pipe:
Presence and length of data in the pipe
Open/closed status of the pipe
Presence or absence of the AT and NODELAY command options
For information about writing applications that access named pipes, see the Developing OASYS Basic
Applications manual.
Writing to Other Types of Files

For files that are not named pipes, processing is determined by the presence or absence of the AT clause:
AT clause specified OASYS Basic begins writing to the file at the offset specified by byte.expr.
AT clause not specified OASYS Basic begins writing to the current location of the file pointer.
After successful execution of OSBWRITE against a file that is not a named pipe, the file pointer remains at the
next byte after the data is written.
251.3 Parameters
Parameter
expr
ON | TO file.var
AT byte.expr
NODELAY
ON ERROR statements
2012 Onsystex Corp.
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
280

OSBWRITE Parameters

After you execute OSBWRITE, the STATUS function returns one of the values described in the following table.
Value
Description
0
1
2
4
The write was successful.

The file name is invalid.
You do not have permission to access the file.
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.

OASYS Basic
CLOSESEQ, OPENSEQ, OSBREAD, OSCLOSE, OSDELETE, OSOPEN, READSEQ, WRITESEQ, WRITESEQF
252 OSCLOSE
2012 Onsystex Corp.
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
Parameter
Description
file.var
ON ERROR
statements
Specifies the file to close.

Specifies statements to execute if the OSCLOSE 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.
OSCLOSE Parameters

After you execute OSCLOSE, the STATUS function returns one of the values described in the following table.
Value
Description
0
5
The file is closed successfully.

The file did not close.
252.5 Example
In the following example, the program statement closes the file UNDEF:

OASYS Basic
CLOSE, CLOSESEQ, OPENSEQ, OSOPEN
253 OSDELETE
2012 Onsystex Corp.
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
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
program terminates.
OSDELETE Parameters
ON ERROR
statements

After you execute OSDELETE, the STATUS function returns one of the values described in the following table.
Value
0
1
2
4
Description
The file was deleted.
The directory name is invalid.
OASYS cannot access the file (such as user
does not have permission).
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:
2012 Onsystex Corp.
OSDELETE
283

OASYS Basic
CLOSESEQ, DELETE, OPENSEQ, OSOPEN, OSCLOSE
254 OSOPEN
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
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
READONLY
WRITEONLY
TO file.var
NODELAY
ON ERROR statements
2012 Onsystex Corp.
284
THEN statements END

ELSE statements END

statements.
OSOPEN Parameters
254.4 Example
In the following example, the program statement opens the file INVENTORY as INVENT unless OASYS cannot
access the file.

OASYS Basic
CLOSESEQ, OPEN, OPENSEQ, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, READSEQ, WRITESEQ,
WRITESEQF
255 OSREAD
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
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
Specifies statements to execute if the OSREAD statement fails

THEN statements END

ELSE statements END
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:

OASYS Basic
OSWRITE
256 OSWRITE
256.1 Syntax
OSWRITE expr {ON | TO} filename [ON ERROR statements]
2012 Onsystex Corp.
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
Parameter
Description
expr
ON | TO filename
ON ERROR statements
Specifies the expression to write to filename.

Specifies the name of a sequential file to which to write.
Specifies statements to execute if the OSWRITE statement fails
OSWRITE Parameters
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:

OASYS Basic
OSREAD
257 PAGE
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
PRINTER OFF The new page is generated on the users terminal.

PRINTER ON The new page is generated on the system printer.
257.3 Parameters
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 Basic
PRINTER
OASYS
258 PAUSE
258.1 Syntax
PAUSE [wait_time]
2012 Onsystex Corp.
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 Basic
WAKE
OASYS
LIST.PAUSED, PAUSE, SLEEP, WAKE For information, see the OASYS Commands Reference.
2012 Onsystex Corp.
PCPERFORM
289
259 PCPERFORM
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
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:

OASYS Basic
EXECUTE, EXECUTESQL, MDPERFORM, OASEXECUTE
260 PERFORM
PERFORM is a synonym for the EXECUTE command. For more information, see EXECUTE.
2012 Onsystex Corp.
290
260.1 Synonym
EXECUTE
261 PRECISION
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:

OASYS
FLOAT.PRECISION For information, see the OASYS Commands Reference.
262 PRINT
2012 Onsystex Corp.
PRINT
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
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:
2012 Onsystex Corp.
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:
The result is:
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 Basic
@, CRT, GETPTR, INPUTERR, PRINTER, PRINTER CLOSE
OASYS
263 PRINTER
2012 Onsystex Corp.
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 PRINTER CLOSE

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:
2012 Onsystex Corp.
294

OASYS
265 PRINTERR
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
Parameter
Description
expr
Specifies a dynamic array that consists of two elements. The first

element is the key for a record in the error message file. The second
element is a parameter that some of the format codes use. For format
codes, see the following table. Attribute marks (@AM or @FM ) delimit
elements.
Specifies a file from which to extract a user-defined error message. The
default is the OASYS error message file.
PRINTERR Parameters
FROM file.var
Creating a User-Defined Error Message

Error messages in the OASYS error message file consist of format codes and literal strings. The following table
describes the codes you can include in error messages.
Code
A
Description
Extracts the next element in expr.
2012 Onsystex Corp.
PRINTERR
A(n)
C
D
E literal
H literal
L
L(n)
R(n)
S(n)
295
Extracts the next element in expr, left-justified in a string of length n.

Clears the screen.
Enters the date in internal format.
Enters the message ID at the beginning of the message enclosed in brackets,
followed by an optional literal string.
Prints literal.
Prints a carriage return/line feed. You must specify L (carriage return/line feed)
explicitly.
Prints n carriage returns/line feeds.
Extracts the next element in expr, right-justified in an attribute of n blanks.
Prints n spaces.
PRINTERR Error Message Codes
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:
2012 Onsystex Corp.
296
If you enter 12 for VAR1, the program segment produces the following error message:
266 PROCREAD
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
Parameter
Description
var
Specifies variable to which to assign the string value of the

primary input buffer of the calling proc.
THEN executes if this program was called by a proc. END is
required to terminate multiline THEN statements.
ELSE executes if this program was not called by a proc. END is
required to terminate multiline ELSE statements.
PROCREAD Parameters
THEN statements END

ELSE statements END
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.
2012 Onsystex Corp.
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.
2012 Onsystex Corp.
298
2012 Onsystex Corp.
PROCREAD
299

OASYS Basic
PROCWRITE
267 PROCWRITE
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:
2012 Onsystex Corp.
300
Note: Another example is provided with PROCREAD.

OASYS Basic
PROCREAD
268 PROGRAM
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
SUBROUTINE
OASYS
BASIC, CATALOG For information, see the OASYS Commands Reference.
269 PROMPT
2012 Onsystex Corp.
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.

OASYS Basic
IN, INPUT, INPUT @, INPUTIF, INPUTTRAP
270 PWR
270.1 Syntax
PWR(num.expr1, num.expr2)
2012 Onsystex Corp.
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
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:
2012 Onsystex Corp.
QUOTE
303
In the next example, the program segment prints This is another test:

OASYS Basic
SQUOTE
272 RAISE
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:
This results in the following array:

OASYS Basic
LOWER
273 READ
273.1 Syntax
READ dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] {THEN statements [END] | ELSE
statements [END]}
2012 Onsystex Corp.
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.
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
273.3 Parameters
Parameter
Description
dyn.array.var
FROM file.var,
Specifies a target dynamic array for the data being read.

Specifies a file variable from which to read the record.
The default file is one for which no file variable is assigned in the
OPEN statement.
Specifies a record to read.
Specifies statements to execute if the READ statement fails with
a fatal error because the file is not open, an I/O error occurs, or
OASYS cannot find the file.
statements.
READ Parameters
record.ID.expr
ON ERROR statements
THEN statements END

ELSE statements END

After you execute READ, the STATUS function returns one of the values described in the following table.
Value
0
2
Description
Successful read.
A read error occurred.
STATUS Function Values
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
the program performs the subroutine REPROMPT.

OASYS Basic
CLOSE, DELETE, OPEN, READL, READU, READV, READVL, READVU, WRITE
274 READBCK
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.
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
Parameter
dyn.array.var
FROM file.var
2012 Onsystex Corp.
Description
Specifies a dynamic array to which to assign the values read.
306
OPEN statement.
ON ERROR statements
THEN statements END

ELSE statements END
Specifies statements to execute if the READBCK statement fails

ELSE executes if the read is not successful or the record does not
exist. END is required to terminate multiline ELSE statements.
READBCK Parameters

After you execute READBCK, the STATUS function returns one of the values described in the following table.
0
10
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL
DUP.STATUS is on.
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:
The preceding program produces the following results:
Note: This program reads the records even if the records are locked by another user

OASYS Basic
READBCKL, READBCKU, READFWD, READFWDL, READFWDU, READXBCK, READXFWD,
2012 Onsystex Corp.
READBCK
307
SELECTINDEX, SETINDEX
OASYS
BUILD.INDEX, CREATE.INDEX, DUP.STATUS For information, see the OASYS Commands Reference.
275 READBCKL
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
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.
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
275.3 Parameters
Parameter
dyn.array.var
FROM file.var
ON ERROR statements
2012 Onsystex Corp.
Description
Specifies a target dynamic array to receive the data read.
The default file is one for which no file variable is assigned in
the OPEN statement.
Specifies statements to execute if the READBCKL statement
308
LOCKED statements
THEN statements END

ELSE statements END
Specifies statements to execute if the record is already locked. If

you do not specify the LOCKED clause, and if the record is
locked, OASYS waits until the record is available.
the record.
THEN executes if the read is not successful. END is required to
ELSE executes if the read is not successful, the current alternate
key value is not set by the SETINDEX command, or OASYS
cannot locate the current alternate key value (for example, when
OASYS reaches the end of the alternate index). END is required
to terminate multiline ELSE statements.
READBCKL Parameters

After you execute READBCKL, the STATUS function returns one of the values described in the following table.
Value
Description
0
10
Successful read.
DUP.STATUS is on.
275.5 Example
This example uses the following program to lock the CLIENT file for two minutes:
If you execute the following program:
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.
2012 Onsystex Corp.
READBCKL
309

OASYS Basic
READBCK, READBCKU, READFWD, READFWDL, READFWDU, READXBCK, READXFWD, SELECTINDEX,
SETINDEX
OASYS
BUILD.INDEX, CREATE.INDEX, DEFAULT.LOCKED.ACTION, DUP.STATUS For information, see the OASYS
Commands Reference.
276 READBCKU
276.1 Syntax
READBCKU dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
READBCKU dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
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.
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
276.3 Parameters
Parameter
dyn.array.var
FROM file.var
2012 Onsystex Corp.
Description
Specifies a target dynamic array to receive the data read.
OPEN statement.
310
ON ERROR statements
LOCKED statements
THEN statements END

ELSE statements END
Specifies statements to execute if the READBCKU statement

Specifies statements to execute if the record is already locked. If
you do not specify the LOCKED clause, and if the record is
locked, OASYS waits until the record is available.
the record.
THEN executes if the read is not successful. END is required to
ELSE executes if the read is not successful, the current alternate
key value is not set by the SETINDEX command, or OASYS
cannot locate the current alternate key value (for example, when
OASYS reaches the end of the alternate index). END is required
READBCKU Parameters

After you execute READBCKU, the STATUS function returns one of the values described in the following table.
Value
0
10
Description
Successful read.
DUP.STATUS is on.
276.5 Example
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.
2012 Onsystex Corp.
READBCKU
311

OASYS Basic
READBCK, READBCKL, READFWD, READFWDL, READFWDU, READXBCK, READXFWD, SELECTINDEX,
SETINDEX
OASYS
Commands Reference.
277 READFWD
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.
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
277.3 Parameters
2012 Onsystex Corp.
Parameter
Description
dyn.array.var
FROM file.var
Specifies a dynamic array to contain the record.

Specifies a file from which to read the record.
OPEN statement.
312
ON ERROR statements
THEN statements END

ELSE statements END
Specifies statements to execute if the READFWD statement fails

READFWD Parameters

After you execute READFWD, the STATUS function returns one of the values described in the following table.
Value
Description
0
10
Successful read.
DUP.STATUS is on.
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:
This program produces the following results:
Note: This program reads the records even if the records are locked by other users.

OASYS Basic
READBCK, READBCKL, READBCKU, READFWDL, READFWDU, READXFWD, READXBCK, SELECTINDEX,
SETINDEX
2012 Onsystex Corp.
READFWD
313
277.7 UniData
BUILD.INDEX, CREATE.INDEX, DUP.STATUS For information, see the OASYS Commands Reference.
278 READFWDL
278.1 Syntax
READFWDL dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
READFWDL dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
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.
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
Parameter
Description
dyn.array.var
FROM file.var

OPEN statement.
Specifies statements to execute if the READFWDL statement
ON ERROR statements
2012 Onsystex Corp.
314
LOCKED statements
THEN statements END

ELSE statements END

user. If you do not specify a LOCKED clause, the program
waits until the lock on the record is released.
the record.
READFWDL Parameters

After you execute READFWDL, the STATUS function returns one of the values described in the following table.
Value
0
10
Description
Successful read.
OASYS Basic found and read a duplicate alternate index key value, and ECL DUP.
STATUS is on.
278.5 Example
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.

OASYS Basic
READBCK, READBCKL, READBCKU, READFWD, READFWDU, READXBCK, READXFWD, SELECTINDEX,
2012 Onsystex Corp.
READFWDL
315
SETINDEX
OASYS
Commands Reference.
279 READFWDU
279.1 Syntax
READFWDU dyn.array.var [FROM file.var] [ON ERROR statements] [LOCKED statements] {THEN statements
READFWDU dyn.array.var [FROM file.var] [LOCKED statements] [ON ERROR statements] {THEN statements
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.
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
Parameter
dyn.array.var
FROM file.var
ON ERROR statements
2012 Onsystex Corp.
Description
OPEN statement.
Specifies statements to execute if the READFWDU statement
316
LOCKED statements
THEN statements END

ELSE statements END

the record.
READFWDU Parameters

After you execute READFWDU, the STATUS function returns one of the values described in the following table.
Value
Description
0
10
Successful read.
DUP.STATUS is on.
279.5 Example
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.

OASYS Basic
READBCK, READBCKL, READBCKU, READFWD, READFWDL, READXBCK, READXFWD, SELECTINDEX,
2012 Onsystex Corp.
READFWDU
317
SETINDEX
OASYS
Commands Reference.
280 READL
280.1 Syntax
READL dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
READL dyn.array.var FROM [file.var,] record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
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.
(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
Parameter
dyn.array.var
FROM file.var
ON ERROR statements
LOCKED statements
2012 Onsystex Corp.
Description
Specifies a dynamic array to receive the record.
OPEN statement.
Specifies statements to execute if the READL statement fails
user (with an exclusive lock). If you do not specify a LOCKED
clause, the program waits until the lock on the record is released.
the record.
318
THEN statements END

ELSE statements END

READL Parameters

After you execute READL, the STATUS function returns one of the values described in the following table.
Value
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.
280.5 Examples
This example uses the following program to lock the ORDERS file for two minutes:
If you immediately execute the following program:
the second program prints Record locked, try again later.

OASYS Basic
CLOSE, DELETE, OPEN, READ, READU, READV, READVL, READVU, WRITE
OASYS
281 READLIST
2012 Onsystex Corp.
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
Parameter
Description
dyn.array.var
Specifies a dynamic array to contain the values removed from

the select list.
Specifies which select list (0-9) you want to use. If you do not
specify a list.num, OASYS reads the default list (0). If no items
are available in the list, OASYS executes the ELSE clause.
ELSE executes if the read is not successful or the list does not
READLIST Parameters
FROM list.num
THEN statements END

ELSE statements END
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.
2012 Onsystex Corp.
320

OASYS Basic
DELETELIST, FORMLIST, GETLIST, READNEXT, SELECT, SELECTINDEX, SELECTINFO, WRITELIST
UniQuery
DELETE.LIST, GET.LIST, SELECT, SAVE.LIST, SSELECT For information, see the UniQuery Commands
Reference.
OASYS SQL
282 READNEXT
282.1 Syntax
READNEXT id.var [, val.var[, subval.var]] [FROM list.num.expr] [ON ERROR statements] {THEN statements
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.
2012 Onsystex Corp.
READNEXT
321
READNEXT and Multivalued Attributes

Select lists used by READNEXT can contain an optional value and subvalue positions (if you create the list
using the BY.EXP keyword). The select list created by using this keyword is sorted based on a multivalued or
subvalued attribute. The select list contains, in each of two attributes, the record ID and position of the sorted
value or subvalue. The READNEXT command passes the value or subvalue positions to val.var and subval.var.
A subsequent READ statement might access the appropriate value using val.var (and subval.var).
Note: When you create a select list using the BY.EXP keyword against a multivalued or multi-subvalued
attribute, the resulting select list contains the multivalue position in the second value of the attribute and the
multi-subvalue position in the third value of the attribute. If a BY.EXP select statement is executed against an
attribute with a value code specifier of MV, the third value in each attribute in the resulting select list is -5 as
the following shows:
001: 785}1}-5
002: 796}1}-5
003: 812}1}-5...
READNEXT assigns the values and subvalues of each record ID to val.var and subval.var. The val.var and
subval.var each can contain more than one data value (separated by value or subvalue marks) if you use more
than one BY.EXP keyword when you create the select list. In this case, the first subvalue in val.var and in subval.
var corresponds to the value and subvalue position of the attribute in the first BY.EXP expression. The second
subvalue in val.var and in subval.var corresponds to the value and subvalue position of the attribute in the
second BY.EXP clause, and so forth for each successive BY.EXP clause.
282.3 Parameters
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
Specifies statements to execute if the READNEXT statement

occurs, the user enters the debugger.
ELSE statements END
READNEXT Parameters (continued)
2012 Onsystex Corp.
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:

OASYS Basic
DELETELIST, FORMLIST, GETLIST, READLIST, SELECT, SELECTINDEX, SELECTINFO, WRITELIST
UniQuery
Reference.
OASYS SQL
283 READNEXTTUPLE
283.1 Syntax
READNEXTTUPLE dyn.array.var FROM file.name.expr {THEN statements [END] | ELSE statements [END]}
2012 Onsystex Corp.
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
Parameter
Description
dyn.array.var
FROM file.name.expr
Specifies the dynamic array to contain the record.

Specifies the file from which to read the next record ID.
file.name.expr must have been created during the current session
by:
An EXECUTESQL statement with a TO clause in the OASYS
Basic program.
A OASYS SQL statement executed at the ECL prompt before the
program was run.
ELSE executes if the read is not successful, the record does not
exist, or the last record has been read. END is required to
terminate multiline ELSE statements.
READNEXTTUPLE Parameters
THEN statements END

ELSE statements END
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.
2012 Onsystex Corp.
324

OASYS Basic
EXECUTE, EXECUTESQL
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
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
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:

OASYS Basic
CLOSESEQ, OPENSEQ, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, OSOPEN, WRITESEQ, WRITESEQF
286 READT
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
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.
READT Parameters

After you execute READT, the STATUS function returns one of the values described in the following table.
Value
Description
0
1
2
3
Successful read.
End of file encountered.
End of tape encountered.
Tape not assigned.
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 Basic
RESIZET, REWIND, WEOF, WRITET
OASYS
SETTAPE, T.ATT, T.DET For information, see the OASYS Commands Reference.
2012 Onsystex Corp.
READT
327
287 READU
287.1 Syntax
READU dyn.array.var FROM [file.var,] record.ID.expr [ON ERROR statements] [LOCKED statements] {THEN
READU dyn.array.var FROM [file.var,] record.ID.expr [LOCKED statements] [ON ERROR statements] {THEN
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.
(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
Parameter
dyn.array.var
FROM file.var,
record.ID.expr
ON ERROR statements
LOCKED statements
THEN statements END

ELSE statements END
2012 Onsystex Corp.
Description
Specifies the file variable from which to read the record.
OPEN statement.
Specifies the record ID to use to retrieve the record.
Specifies statements to execute if the READU statement fails
until the lock on the record is released.
the record.
statements.
READU Parameters
328

After you execute READU, the STATUS function returns one of the values described in the following table.
Value
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.
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 Basic
CLOSE, DELETE, OPEN, READ, READL, READV, READVL, READVU, WRITE
OASYS
288 READV
2012 Onsystex Corp.
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
Parameter
Description
var
FROM file.var,
Specifies a dynamic array to contain the attribute.

Specifies the file from which to read the record.
OPEN statement.
Specifies the record to read.
Specifies the attribute to read.
READV Parameters
record.ID.expr
attribute.expr
Parameter
Description
ON ERROR statements
Specifies statements to execute if the READV statement fails

READV Parameters (continued)
THEN statements END

ELSE statements END
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.
2012 Onsystex Corp.
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.

OASYS Basic
CLOSE, DELETE, OPEN, READ, READL, READU, READVL, READVU, WRITE
289 READVL
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]
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
Parameter
var
Description
Specifies the variable to contain the attribute.
2012 Onsystex Corp.
READVL
FROM file.var,
record.ID.expr
attribute.expr
ON ERROR statements
LOCKED statements
THEN statements END

ELSE statements END
331
Specifies the file from which to read the attribute.

If you do not specify a file with file.var, the data is read from the
most recently opened default file.
Specifies a record from which to read an attribute.
OPEN statement.
Specifies an attribute from which to read.
Specifies statements to execute if the READVL statement fails
the record.
statements.
READVL Parameters
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 Basic
CLOSE, DELETE, OPEN, READ, READL, READU, READV, READVU, WRITE
OASYS
290 READVU
290.1 Syntax
READVU var FROM [file.var,] record.ID.expr, attribute.expr [ON ERROR statements] [LOCKED statements]
2012 Onsystex Corp.
332
READVU var FROM [file.var,] record.ID.expr, attribute.expr [LOCKED statements] [ON ERROR statements]
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
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.
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
2012 Onsystex Corp.
READVU
LOCKED statements
THEN statements END

ELSE statements END
333

the record.
statements.
READVU Parameters

OASYS Basic
CLOSE, DELETE, OPEN, READ, READL, READU, READV, READVL, WRITE
OASYS
291 READXBCK
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
Parameter
dyn.array.var
FROM file.var
2012 Onsystex Corp.
Description
OPEN statement.
READXBCK Parameters
334
Parameter
Description
ON ERROR statements
Specifies statements to execute if the READXBCK statement

ELSE statements END
READXBCK Parameters (continued)

OASYS Basic
READBCK, READBCKL, READBCKU, READFWD, READFWDL, READFWDU, READXFWD, SELECTINDEX,
SETINDEX
OASYS
292 READXFWD
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
Parameter
dyn.array.var
FROM file.var
Description
OPEN statement.
READXFWD Parameters
2012 Onsystex Corp.
READXFWD
Parameter
335
Description
ON ERROR statements
Specifies statements to execute if the READXFWD statement

ELSE statements END
READXFWD Parameters (continued)

OASYS Basic
READBCK, READBCKL, READBCKU, READFWD, READFWDL, READFWDU, READXBCK, SELECTINDEX,
SETINDEX
OASYS
293 RECORDLOCKED
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.
Null Value Handling

With null value handling on, the null value in file.var results in a RECORDLOCKED return value of -2 and a
STATUS function return value of -12. The null value is a valid record ID and can be passed to the function in rec.
id.expr.
293.3 Parameters
Parameter
file.var
2012 Onsystex Corp.
Description
Specifies the file on which to check lock status. The null value in file.var
336
results in a RECORDLOCKED return value of -2.

rec.id.expr
Specifies the record on which to check lock status.

RECORDLOCKED Parameters
293.4 RECORDLOCKED Function Return Values

The RECORDLOCKED function returns one of the values described in the following table.
Value
4
Lock Type
exclusive
Lock Owner
you
shared
you
exclusive
you
shared
you
0
-1
The record is not locked.

shared
another user
-2
exclusive
-3
shared
-4
exclusive
Locking Command
FILELOCK, SQL LOCK TABLE,
implicit SQL TP lock escalation.
READU, RECORDLOCKU, SQL
TP implicit record locking.
READL, RECORDLOCKL, SQL
READL, RECORDLOCKL, SQL

another user
READU, RECORDLOCKU, SQL
another user
another user
RECORDLOCKED Return Values
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.

After you execute RECORDLOCKED, the STATUS function returns one of the values described in the following
table.
Value
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.
2012 Onsystex Corp.
RECORDLOCKED
337

OASYS Basic
FILELOCK, FILEUNLOCK, RECORDLOCKL, RECORDLOCKU, RELEASE
294 RECORDLOCKL
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
Parameter
Description
file.var,

OPEN statement.
RECORDLOCKL Parameters
Parameter
Description
record.ID.expr
Specifies a record to lock.
ON ERROR statements
Specifies statements to execute if the RECORDLOCKL

statement fails with a fatal error because the file is not open, an I/
O error occurs, or OASYS cannot find the file.
LOCKED statements
Specifies statements to execute if another user has an exclusive

lock on the record. If you do not specify a LOCKED clause, the
2012 Onsystex Corp.
338
program waits until the lock on the record is released.

the record.
RECORDLOCKL Parameters (continued)
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 Basic
FILELOCK, FILEUNLOCK, RECORDLOCKED, RECORDLOCKU, RELEASE
OASYS
295 RECORDLOCKU
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.
2012 Onsystex Corp.
RECORDLOCKU
295.3 Parameters
Parameter
Description
file.var,

OPEN statement.
RECORDLOCKU Parameters
Parameter
Description
record.ID.expr
Specifies a record to lock.
ON ERROR statements
Specifies statements to execute if the RECORDLOCKU

statement fails with a fatal error because the file is not open, an
I/O error occurs, or OASYS cannot find the file.
LOCKED statements

the record.
RECORDLOCKU Parameters (continued)

OASYS Basic
FILELOCK, FILEUNLOCK, RECORDLOCKED, RECORDLOCKL, RELEASE
OASYS
DEFAULT.LOCKED.ACTION For information, see OASYS Commands Reference.
2012 Onsystex Corp.
339
340
296 RELEASE
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
Parameter
Description
file.var
Specifies a file to unlock. If you do not specify a file or a record,

OASYS releases all locks set by the same user process.
Specifies a record ID to unlock. If you do not specify a record
with record.ID.expr, OASYS releases all locked records within
the file.
Specifies statements to execute if the RELEASE statement fails
RELEASE Parameters
,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.
2012 Onsystex Corp.
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.

OASYS Basic
FILELOCK, FILEUNLOCK, RECORDLOCKED, RECORDLOCKL, RECORDLOCKU
297 REM
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.
2012 Onsystex Corp.
342
298 REMOVE
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
Parameter
var
Description
Specifies the element to contain the extracted array element.
REMOVE Parameters
Parameter
Description
FROM dyn.var
Specifies a dynamic array from which to remove elements.
AT col.pos
Specifies the position in the array at which to start removing
2012 Onsystex Corp.
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
Specifies the delimiter code. When the end of the array is

encountered, delim.var is set to 0.
REMOVE Parameters (continued)
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
REMOVE Delimiter Codes
*ASCII value is language-dependent and can be reassigned.
298.4 Examples
In the following example, the program segment processes the dynamic array CLIENT:
After the loop terminates, VAR contains the following:
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 OASYS Basic, the result is the following:
In some implementations, the values are different:
In the next example, the program segment compares processing time for the REMOVE statement versus the
EXTRACT statement:
2012 Onsystex Corp.
REMOVE
345

OASYS Basic
DEL, EXTRACT, INSERT, REMOVE, REPLACE, SUBSTRINGS
299 REMOVE
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.
2012 Onsystex Corp.
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
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
REMOVE Delimiter Codes
*ASCII value is language-dependent and can be reassigned.

OASYS Basic
DEL, EXTRACT, INSERT, REMOVE, REPLACE, SUBSTRINGS
300 REPLACE
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
2012 Onsystex Corp.
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.
Null Value Handling

With null value handling on, when OASYS Basic encounters the null value in a command parameter when a
number is expected (attrib.expr, val.expr, subval.expr,), it displays a warning message and uses 0.
300.3 Parameters
Parameter
Description
dyn.array.expr
attrib.expr
Specifies the dynamic array to modify.

Specifies the attribute to replace. The following rules also apply:
If attrib.expr is a negative number, replace.expr is appended to the
existing value instead of replacing it.
If attrib.expr is 0, the preceding level (attribute, value, subvalue) is
replaced by replace.expr.
Specifies the value of the attribute to replace. The following rules also
apply:
Specifies the subvalue of the value of the attribute to replace. The
following rules also apply:
Specifies the replacement value.
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.
2012 Onsystex Corp.
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
This results in:
In the following example, the program uses the short form of the REPLACE command to append CLIENT.NAME
to NAME.ARRAY1:

OASYS Basic
DEL, DELETE, EXTRACT, INSERT, REMOVE, REPLACE
301 RESIZET
2012 Onsystex Corp.
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
Paragraph
Description
UNIT(mu.expr)
Specifies the conversion code and unit number. The mu.expr is

optional. 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.
Specifies the block size to which to resize.
THEN executes if the resize is successful. END is required to
ELSE executes if the resize is not successful. END is required to
terminate multiline ELSE statements.
RESIZET Parameters
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 Basic
READT, REWIND, WRITET
OASYS
2012 Onsystex Corp.
350
302 RETURN
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.

OASYS Basic
CALL, GOSUB, ON/GOSUB
303 REUSE
303.1 Syntax
REUSE(dyn.array.expr)
303.2 Description
The OASYS Basic REUSE function affects the application of arithmetic operations on dynamic arrays.
When REUSE Is Not Used

When you execute an arithmetic operation on an array and you do not include the REUSE function, one of the
following happens:
2012 Onsystex Corp.
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:
This results in:
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:
This results in:
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
304.1 Syntax
REWIND [UNIT(mu.expr)] {THEN statements [END] | ELSE statements [END]}
304.2 Description
The OASYS Basic REWIND command rewinds a tape.
2012 Onsystex Corp.
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
Parameter
Description
UNIT(mu.expr)
The mu.expr is optional and the default value is UNIT (00) for
tape unit 0 with no conversion (ASCII assumed).
2 Invert high bit.
3 Swap bytes.
THEN executes if the rewind is successful. END is required to
ELSE executes if the rewind is not successful. END is required
REWIND Parameters
THEN statements END

ELSE statements END
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 Basic
READT, RESIZET, WRITET
OASYS
305 RND
2012 Onsystex Corp.
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:

OASYS Basic
RNDSEED
306 RNDSEED
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.
2012 Onsystex Corp.
354

OASYS Basic
RND
307 RQM
RQM is a synonym for the SLEEP function. For more information, see SLEEP.
307.1 Synonym
SLEEP
308 SADD
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:
2012 Onsystex Corp.
SCMP
355
309 SCMP
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.
309.3 SCMP Function Return Values

The SCMP function returns one of the values described in the following table.
Comparison
Returning Value
x< y
-1
x= y
0
x> y
1
SCMP Function Return Values
Tip: Processing string data-type numbers rather than numeric data-type numbers degrades processing speed.
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
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
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
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.
2012 Onsystex Corp.
SELECT
357
311.3 Parameters
Parameter
Description
file.var
Specifies a file variable from which to read record IDs.

If you do not specify a file.var, OASYS reads from the default file. If
no default file is open, a fatal error occurs.
OPEN statement.
Specifies a dynamic array from which to select a list of attributes.
Supported in BASICTYPEs R and U only. Specifies a numbered
select list, 09, to contain record IDs. If you do not specify a list,
SELECT creates list 0.
Supported in all BASICTYPEs. Specifies a named select list to contain
record IDs.
Initialize list.var.expr with a statement like
list.name = ''
before using it in the SELECT statement to avoid a compiler warning
for an uninitialized variable.
Specifies statements to execute if the SELECT statement fails with a
SELECT Parameters
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.
2012 Onsystex Corp.
358
Here is the output for this program:
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.

OASYS Basic
DELETELIST, FORMLIST, READLIST, SELECTINDEX, SELECTINFO, WRITELIST
UniQuery
Reference.
OASYS SQL
2012 Onsystex Corp.
SELECTINDEX
359
312 SELECTINDEX
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
Parameter
Description
index.name.expr
Specifies an alternate key index from which to select all key

values if the key.val.expr is not specified.
Specifies a key value expression for SELECTINDEX to create a
select list of record IDs (associated with the alternate key value)
found in the alternate key index.
Specifies a file variable from which to select the list.
Specifies the list to which to select keys.
, key.val.expr
FROM file.var
TO list.num.expr
SELECTINDEX Parameters

After you execute SELECTINDEX, the STATUS function returns one of the values described in the following
table.
Value
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.
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:
2012 Onsystex Corp.
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:

OASYS Basic
DELETELIST, FORMLIST, READLIST, SELECT, SELECTINFO, SETINDEX, WRITELIST
UniQuery
Reference.
OASYS SQL
313 SELECTINFO
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
2012 Onsystex Corp.
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
313.4 SELECTINFO Function Return Values

The SELECTINFO function returns one of the values described in the following table.
Value
1
0
-1
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

OASYS Basic
DELETELIST, FORMLIST, READLIST, SELECT, SELECTINDEX, WRITELIST
UniQuery
Reference.
OASYS SQL
314 SEND
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
Parameter
2012 Onsystex Corp.
Description
362
Directs OASYS to convert expr from an exploded ASCII hexadecimal

representation string to its binary equivalent, and then transmit it on the
specified line. The conversion process ends when OASYS reads the first
nonhexadecimal character.
expr:expr2...
A string that contains data formatting expressions. You can specify more
than one string to send.
:
Suppresses the sending of a terminating carriage return and line feed.
TO line.expr
Specifies a line number. line.expr must be valid or an error message
displays and the user enters the OASYS Basic debugger.
If the line is attached, the process has exclusive use of it. If the line is not
attached, OASYS performs the ELSE clause.
THEN statements THEN executes if the SEND is successful. END is required to terminate
END
multiline statements.
ELSE statements ELSE executes if the SEND is not successful. END is required to terminate
END
multiline statements.
SEND Parameters
X
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:

OASYS Basic
GETOASYS
PROTOCOL For information, see the OASYS Commands Reference.
315 SEQ
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):

OASYS Basic
ASCII, CHAR, CHARS, EBCDIC
316 SEQS
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.

OASYS Basic
ASCII, CHAR, CHARS, EBCDIC, SEQ
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
Parameter
Description
var_name
value
The name of the environment variable.

The value of the environment variable.
SETENV Parameters
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
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
2012 Onsystex Corp.
SETINDEX
Parameter
365
Description
index.name.expr
Specifies the alternate key index to use in subsequent READFWD/

READBCK statements.
rop
One of several valid operators (see the following table). The default
rop operator is EQ.
, key.val.expr
Specifies the key value to initialize. If you do not specify this value,
OASYS sets the internal pointer to the first key value in the index.
If you specify FIRST_ALT_KEY, LAST_ALT_KEY, or
NULLVAL_ALT_KEY as rop, you cannot specify key.val.expr.
, id.expr
Specifies the @ID associated with the key value to position the
pointer in the index.
When the id.expr entered does not exist, SETINDEX sets the
position to the key value following the expected location of id.expr.
ON file.var
Specifies the file to act on.
BUFFER.KEYS ON | Directs READFWD/READBCK to use or not use a buffering
OFF
mechanism.
ON improves performance, but you could miss some newly added
key values.
OFF (the default) slows performance, but you will not miss any key
values added after the one you just read.
VALIDATE.KEY ON Directs READFWD/READBCK to validate or not validate the key
| OFF
value just read against what is in the tuple. Because reading a key
value and its tuple is not an atomic action, a tuple could be deleted
after it is read. ON prevents this, but could degrade performance.
SETINDEX Parameters
rop Operators
The following table describes the valid rop operators.
Operator
EQ
GT
GE
LT
LE
FIRST_ALT_KEY
Resulting Current Alternate Key Value

First value equal to the specified value (default).
First value greater than that specified.
First value greater than or equal to that specified.
Last value less than that specified.
Last value less than or equal to that specified.
First non-null alternate key value. Keys that are an empty string
are sorted before keys containing values. If you specify
FIRST_ALT_KEY as rop, you cannot specify key.val.expr.
LAST_ALT_KEY
Last alternate key value. If you specify LAST_ALT_KEY as
rop, you cannot specify key.val.expr.
NULLVAL_ALT_KEY First null alternate key value. Keys that are empty strings are
sorted after null value keys, followed by keys containing values.
If you specify NULLVAL_ALT_KEY as rop, you cannot
specify key.val.expr.
rop Operators

After you execute SETINDEX, the STATUS function returns one of the values described in the following table.
Status Value Description
2012 Onsystex Corp.
366
0
1
2
The alternate key specified exists.

Error.
The alternate key specified does not exist.
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:
2012 Onsystex Corp.
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 Basic
READBCK, READBCKL, READBCKU, READFWD, READFWDL, READFWDU, READXBCK, READXFWD,
SELECTINDEX
OASYS
319 SIN
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:
2012 Onsystex Corp.
368

ACOS, ASIN, ATAN, COS, TAN
320 SLEEP
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
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:
2012 Onsystex Corp.
SLEEP
369
In the next example, the program statement halts program execution for one second:
321 SMUL
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.
The SMUL function results in a string number, so you can use the function in any expression in which a string
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
the original attribute.

If the dynamic array contains value marks and no attribute marks, the sort is by value. Subvalues are
unaffected and remain with the original value.
If the dynamic array contains subvalue marks and neither attribute marks nor value marks, the sort is by
subvalue.
Parameter
The following table describes the parameter of the syntax.
Parameter
Description
var
The name of the dynamic array to sort.

SORT Parameter
323 SOUNDEX
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.
SOUNDEX Phonetic Codes

The following table displays the phonetic code for each letter that OASYS evaluates.
Code
Letters
1
BFPV
2
CG J K Q SX Z
3
DT
4
L
5
MN
6
R
OASYS Basic SOUNDEX Phonetic Codes
2012 Onsystex Corp.
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

OASYS Basic
ICONV SOUNDEX (S), OCONV SOUNDEX (S)
324 SPACE
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:
This results in:

OASYS Basic
SPACES
2012 Onsystex Corp.
371
372
325 SPACES
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.

OASYS Basic
SPACE
326 SPLICE
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
Specifies the first string or array to concatenate.

Specifies the expression to insert between expr1 and expr2 when concate-
2012 Onsystex Corp.
SPLICE
373
nating them.
expr2
Specifies the second string or array to concatenate.

SPLICE s arameter
326.4 Examples
In the following example, the program segment concatenates PHONE to NUMBER and inserts a dash (-) between
the two strings:
This results in:
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:

OASYS Basic
CAT, CATS
2012 Onsystex Corp.
374
327 SQRT
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
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:

OASYS Basic
QUOTE
2012 Onsystex Corp.
SSUB
375
329 SSUB
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.
The SSUB function results in a string number, so you can use the function in any expression in which a string
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
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.

OASYS Basic
SYSTEM
@variables For information, see Appendix B, OASYS Basic@variables.
331 STOP
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.
2012 Onsystex Corp.
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:

OASYS Basic
ABORT
332 STR
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.
Null Value Handling

If a function encounters the null value in a parameter when a number is expected (num.expr), a warning message
displays, and OASYS Basic uses 0.
332.3 Parameters
Parameter
Description
str.expr
num.expr
Specifies a string expression to concatenate num.expr times.

Specifies the number of repetitions of the string expression to concatenate.
STR Parameters
2012 Onsystex Corp.
378
332.4 Example
In the following example, the program statement prints a string of 25 hyphens on the terminal screen:

OASYS Basic
STRS
333 STRS
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.
Null Value Handling

If a function encounters the null value in a parameter when a number is expected (expr), a warning message
displays, and OASYS Basic uses 0.
333.3 Example
In the following example, the program segment prints the each element of the ARR1 dynamic array 10 times:

OASYS Basic
STR
334 SUBROUTINE
2012 Onsystex Corp.
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
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:
This is the subroutine:
2012 Onsystex Corp.
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
CALL, PROGRAM, SUBROUTINE (Update Trigger), SUBROUTINE (Delete Trigger)
OASYS
BASIC, CATALOG For information, see the OASYS Commands Reference.
335 SUBROUTINE (Update Trigger)

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
2012 Onsystex Corp.
SUBROUTINE (Update Trigger)
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

After you execute a trigger subroutine, the STATUS function returns one of the values described in the following
table.
Tip: The OASYS Basic STATUS function returns the status of the preceding command. You can place it within
the trigger subroutine to learn about the status of individual commands executed within the trigger. If you
place it immediately after the statement that calls the trigger, it returns the status of the OASYS Basic command
as determined by the trigger. The trigger subroutine also returns a value indicating its status in the parameter
execstat. These values returned in execstat are listed in the Parameters section.
Return Value
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).
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 SUBROUTINE (Delete Trigger)

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
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.
2012 Onsystex Corp.
SUBROUTINE (Delete Trigger)
dictflag
filename
record.ID.expr
383
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.
Name of the file the trigger is operating on.
Record to be deleted.
SUBROUTINE Delete Trigger Parameters

After you execute a trigger subroutine, the STATUS function returns one of the values described in the following
table.
Tip: The OASYS Basic STATUS function returns the status of the preceding command. You can place it within
the trigger subroutine to learn about the status of individual commands executed within the trigger. If you
place it immediately after the statement that calls the trigger, it returns the status of the OASYS Basic command
as determined by the trigger. The trigger subroutine also returns a value indicating its status in the parameter
execstat. These values returned in execstat are listed in the Parameters section.
Return Value
0
1
2
Description
No error.
returns a value of 0 in the parameter execstat, indicating that the update
or delete is not allowed.
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.
2012 Onsystex Corp.
384
337 SUBSTRINGS
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
337.3 Parameters
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.

OASYS Basic
DEL, INSERT, REMOVE, REPLACE
338 SUM
338.1 Syntax
SUM(dyn.array [, <attribute.expr [, value.expr]>] [, start.expr [, stop.expr]])
2012 Onsystex Corp.
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
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.
This results in:
In the next example, the program statement sums VAL1 and returns the numeric value 52 with no dynamic array
delimiters:
339 SWAP
339.1 Syntax
SWAP str.expr1 WITH str.expr2 IN var
2012 Onsystex Corp.
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
str.expr1
str.expr2
IN var
Specifies the string expression to replace with str.expr2.

Specifies the string expression with which to replace str.expr1.
Specifies the variable in which to replace str.expr1 with str.expr2.
SWAP Parameters
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.
The called subroutine is:
2012 Onsystex Corp.
SWAP
387
This program prints:

OASYS Basic
CONVERT
340 SYSTEM
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
1 PRINTER ON or (P) option is specified. Output is printed on the

system printer.
0 Output is printed to the terminal.
Current terminal or page size (width).
Current terminal or page length (number of lines on page).
Number of lines remaining on current page.
Current printer page number.
SYSTEM Parameters
2
3
4
5
2012 Onsystex Corp.
388
Parameter
Description
6
7
8
9
10
Current number of lines printed on the terminal or printer page.

Terminal type.
Current tape block size.
Current CPU millisecond count from the start of the program.
1 The current stack (STON) condition is enabled.
0 Current stack is inactive.
n A SELECT list is active. n = # of items selected.
0 No SELECT list is active.
Current time in milliseconds (local time).
Sleeps one second.
Number of characters in the type-ahead buffer. If the number of characters
in the internal buffer exceeds 511 bytes, this parameter returns 511.
Returns command options as a character string.
Run level, same as @LEVEL.
Indicates where OASYS transfers control of a OASYS Basic program when
the next RETURN statement executes.
0 Program has no called subroutine or internal subroutine GOSUB to
return to.
1 Returning from a CALL.
2 Returning from a GOSUB.
Not currently used.
Shows the level to which the interrupt key is set. If the value is 0, the
interrupt key is enabled. For all other values, the interrupt key is disabled.
To enable the interrupt key, you must match the number of BREAK OFF
statements in a program with an equal number of BREAK ON statements to
bring the value of SYSTEM (30) to 0.
Not currently used.
Returns current BASICTYPE.
SYSTEM Parameters (continued)
11
12
13
14
15
16
17
18-29
30
31
32
Parameter
Description
33
Returns the implementation of OASYS that is currently running, such as

UNIX or a Windows platform.
Not currently used.
The language.
Shows the current setting for DATE.FORM AT:
0 Date format is M M /DD/YY.
1 Date format is DD/M M /YY.
The character used to separate thousands.
The character used as the decimal point.
The character used for the dollar sign.
Returns the name of the program being run.
Returns the OASYS product serial number.
Returns the ASCII value of @RM .
Returns the ASCII value of the print control character. (Default print
control character is 192.)
Returns the ASCII value of @NULL.
Returns the version, including patch number, of OASYS currently running.
If it is different from the version number stored in the VOC file, an asterisk
is appended to the version number.
The ECL UPDATE.VOC command updates the VOC file from the latest
installation or patch.
Returns the name of the COM O file automatically created by a
PHANTOM process. This function is available to the process the
34
35
36
37
38
39
40
41
42
43
44
45
48
2012 Onsystex Corp.
SYSTEM
389
PHANTOM process spawned, not to the parent process.

49
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.
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.
340.4 Example
In the following example, the program segment turns on the printer if data is currently being sent to the display
terminal:
2012 Onsystex Corp.
390
341 TAN
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:

ACOS, ASIN, ATAN, COS, SIN
342 TIME
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

OASYS Basic
DATE, ICONV Date (D), OCONV Date (D), TIMEDATE
343 TIMEDATE
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.

OASYS Basic
DATE, ICONV Date (D), OCONV Date (D), TIME
344 TRANSACTION ABORT

344.1 Syntax
TRANSACTION ABORT
2012 Onsystex Corp.
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:

OASYS Basic
TRANSACTION COMMIT, TRANSACTION START
345 TRANSACTION COMMIT

345.1 Syntax
TRANSACTION COMMIT {THEN statements [END] | ELSE statements [END]}
2012 Onsystex Corp.
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
Parameter
Description
THEN statements END
THEN executes if the commit is successful. END is required to

ELSE statements END
ELSE executes if the commit is not successful because no transaction is active or the record (or ID) does not exist. END is
required to terminate multiline ELSE statements.
OASYS performs the following steps when a commit fails:
Aborts the transaction.
Executes the ELSE clause if it exists.
Releases all record locks inside the transaction.
TRANSACTION COMMIT Parameters

After you execute TRANSACTION COMMIT, the STATUS function returns one of the values described in the
following table.
Value
Description
0
1
3
The commit completed successfully.

Transaction not started.
Transaction cannot commit.
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.
2012 Onsystex Corp.
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.

OASYS Basic
TRANSACTION ABORT, TRANSACTION START
346 TRANSACTION START

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
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
2012 Onsystex Corp.
TRANSACTION START
395

After you execute TRANSACTION START, the STATUS function returns one of the values described in the
following table.
Value
Description
0
1
The transaction was started.

The transaction was not started.
346.4 Example
The following program segment displays a message if a transaction is already started when TRANSACTION
START is executed:

OASYS Basic
TRANSACTION COMMIT, TRANSACTION COMMIT
347 TRIM
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
Parameter
2012 Onsystex Corp.
Description
396
str.expr
,char
,type
Specifies a string from which to remove spaces or the specified character.

Specifies a character to remove from str.expr. The default is a space.
Specifies the type of removal to perform. If char is an empty string, OASYS
does not perform the operation.
L Removes all leading occurrences of char.
T Removes all trailing occurrences of char.
B Removes leading and trailing occurrences of char.
A Removes all occurrences of char.
R (Default) Removes all leading, trailing, and contiguous occurrences of
char.
TRIM Parameters
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):
For BASICTYPE R or U, the program segment produces the following result:
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:
2012 Onsystex Corp.
TRIM
397

OASYS Basic
TRIMB, TRIMF, TRIMS
348 TRIMB
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.".

OASYS Basic
TRIM, TRIMF, TRIMS
349 TRIMF
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

OASYS Basic
TRIM, TRIMB, TRIMS
350 TRIMS
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
dyn.array
,char
,type
Specifies a dynamic array from which to remove spaces or the specified

character.
Specifies a character to remove from elements in dyn.array. The default is a
space.
Specifies the type of removal to perform. If char is an empty string, OASYS
does not perform the operation.
L Removes all leading occurrences of char.
T Removes all trailing occurrences of char.
B Removes leading and trailing occurrences of char.
A Removes all occurrences of char.
R (Default) Removes all leading, trailing, and contiguous occurrences of char
.
TRIMS Parameters
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

OASYS Basic
TRIM, TRIMB, TRIMF
351 OASEXECUTE
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
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
2012 Onsystex Corp.
400
Parameter
Description
str.expr
ASYNC | SYNC
Specifies a command to execute.

OASYS no longer supports this parameter, but it remains for syntax
compatibility.
OASYS no longer supports this parameter, but it remains for syntax
compatibility.
The CAPTURING clause stores the output in a dynamic array
instead of on the display terminal. Each line of the text becomes an
attribute in the array. Output sent to the printer is not affected by
this clause.
The order of CAPTURING and RETURNING is interchangeable.
The RETURNING clause captures error messages resulting from the
command executed with OASEXECUTE. This variable contains a
string of error message numbers separated by spaces. If the executed
command creates a spooler hold file, OASYS also returns the hold file
number in the same variable.
This parameter is provided for backward compatibility for releases
before 3.1.
OASEXECUTE Parameters
ON connection
CAPTURING, dyn.
array.var
RETURNING, dyn.
array.var
PASSCOM

OASYS Basic
COMMON, EXECUTE, EXECUTESQL, MDPERFORM, PCPERFORM
OASYS
STACKCOMMON For information, see the OASYS Commands Reference.
352 UNASSIGNED
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.
2012 Onsystex Corp.
UNLOCK
401
353 UNLOCK
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 Basic
LOCK
OASYS
CLEAR.LOCKS, LIST.LOCKS, SUPERCLEAR.LOCKS For information, see the OASYS Commands Reference.
354 UPCASE
354.1 Syntax
UPCASE(string.expr)
2012 Onsystex Corp.
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!!:

OASYS Basic
DOWNCASE, ICONV Masked Character (MC), OCONV Masked Character (MC)
355 WAKE
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:
2012 Onsystex Corp.
WAKE

OASYS Basic
PAUSE
OASYS
LIST.PAUSED, PAUSE, WAKE For information, see the OASYS Commands Reference.
OASYS Paragraph Command

SLEEP For information, see Using OASYS.
356 WEOF
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
Parameter
Description
UNIT(mu.expr)
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:
2 Invert high bit.
3 Swap bytes.
THEN executes if command execution is successful. END is
THEN statements END
2012 Onsystex Corp.
403
404
ELSE statements END
ELSE executes if command execution is not successful or the

record (or ID) does not exist. END is required to terminate
multiline ELSE statements.
WEOF Parameters

After you execute WEOF, the STATUS function returns one of the values described in the following table.
Value
Description
0
1
2
3
4
5
6
Successful read.
Tape not assigned.
Parity error.
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 Basic
READT, RESIZET, REWIND, WRITET
OASYS
357 WEOFSEQ
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.
2012 Onsystex Corp.
WEOFSEQ
405
357.3 Parameters
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
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:

OASYS Basic
CLOSESEQ, OPENSEQ, OSCLOSE, OSOPEN, READSEQ, WRITESEQ, WRITESEQF
358 WRITE
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.
2012 Onsystex Corp.
406
Updating Alternate Key Indexes

Remember the following points about alternate key indexes when you code WRITE 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, WRITE 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.
358.3 Parameters
Parameter
Description
expr
ON | TO file.var
Specifies an expression to write to the record.

Specifies a file to which to write 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.
A default file is one for which no file variable is assigned in the OPEN
statement.
Specifies a record to receive the expression. If the record already
exists, the new expression you specify with expr replaces the existing
information. If the record you specify does not exist, OASYS creates
the record.
Specifies statements to execute in the event of a fatal error condition
(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, the program terminates under fatal
error conditions.
When including WRITE 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.
WRITE Parameters
record.ID.expr
ON ERROR
statements

After you execute WRITE, the STATUS function returns one of the values described in the following table.
Return Value
Meaning
0
1
2
Successful write.
WRITE is not allowed.
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
2012 Onsystex Corp.
WRITE
407
created.
RFS files WRITE created a duplicate value in the index, and ECL
DUP.STATUS is on.
358.5 Examples
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 Basic
CLOSE, DELETE, OPEN, READL, READU, READV, READVL, READVU, WRITEU, WRITEV, WRITEVU
OASYS
DUP.STATUS For information, see the OASYS Commands Reference.
359 WRITELIST
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
Parameter
var
2012 Onsystex Corp.
Description
Specifies a variable to place in a saved list.
408
ON list.name
Specifies a saved list to contain the retrieved list.

WRITELIST Parameters

OASYS Basic
DELETELIST, FORMLIST, READLIST, SELECT, SELECTINDEX, SELECTINFO
UniQuery
Reference.
OASYS SQL
360 WRITESEQ
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
Parameter
Description
expr
APPEND
Specifies an expression to write as a record.

Use the APPEND option to start the WRITESEQ process at
the end-of-file mark. When APPEND is included, and no file
exists, OASYS creates a new file.
Specifies a sequential file to receive the expression.
ON | TO seq.file.var
WRITESEQ Parameters
2012 Onsystex Corp.
WRITESEQ
Parameter
409
Description
ON ERROR statements
Specifies statements to execute if the WRITESEQ statement

THEN statements END THEN executes if the WRITESEQ is successful. END is
ELSE statements END
ELSE executes if the WRITESEQ is not successful or the record
(or ID) does not exist. END is required to terminate multiline
ELSE statements.
WRITESEQ Parameters (continued)
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.

OASYS Basic
CLOSESEQ, OPENSEQ, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, OSOPEN, READSEQ, WEOFSEQ,
WRITESEQF
361 WRITESEQF
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.
2012 Onsystex Corp.
410
361.3 Parameters
Parameter
Description
expr
APPEND
Specifies an expression to write as a record.

Use the APPEND option to start the WRITESEQF process at
the end-of-file mark. If you use the APPEND option in a file
that does not contain data, OASYS creates a new file.
Specifies a sequential file variable to receive the expression.
ON | TO seq.file.var
WRITESEQF Parameters
Parameter
Description
ON ERROR statements
Specifies statements to execute if the WRITESEQF statement

If you specify the ON ERROR clause and OASYS cannot find
the end-of-file mark, the ELSE clause executes.
THEN statements END
THEN executes if the WRITESEQF is successful. END is

ELSE statements END
ELSE executes if the WRITESEQF is not successful or the

WRITESEQF Parameters (continued)
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.

OASYS Basic
CLOSESEQ, OPENSEQ, OSBREAD, OSBWRITE, OSCLOSE, OSDELETE, OSOPEN, READSEQ, WEOFSEQ,
2012 Onsystex Corp.
WRITESEQF
411
WRITESEQ
362 WRITET
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
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:
2 Invert high bit.
3 Swap bytes.
Specifies an expression to write.
THEN executes if command execution is successful. END is
ELSE executes if command execution is not successful or the
WRITET Parameters
expr
THEN statements END
ELSE statements END
Multireel Tape Processing

You must use the TAPELEN option for the T.ATT command and specify the tape length. This command is
intended for use with OASYS tapes only. For information about the ECL T.ATT command, see the OASYS
Commands Reference.
2012 Onsystex Corp.
412

After you execute WRITET, the STATUS function returns one of the values described in the following table.
Value
Description
0
Successful read.
1
2
3
Tape not assigned.
4
Parity error.
5
6
362.5 Example
In the following example, the T.ATT command is executed, and then OASYS writes the variable TAX.RECORD to
tape:

OASYS Basic
READT, RESIZET, REWIND, WEOF
OASYS
363 WRITEU
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.

2012 Onsystex Corp.
WRITEU
413
Remember the following points about alternate key indexes when you code WRITEU statements:
key, WRITEU sets the STATUS return value to 10.
363.3 Parameters
Parameter
Description
expr
ON | TO file.var,
Specifies an expression to write to the file.

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 WRITEU error occurs.
OPEN statement.
Specifies a record to receive the expression.
Specifies statements to execute if the WRITEU 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 the transaction is not aborted by the ON ERROR
clause, processing continues, and the transaction could commit
inappropriately.
WRITEU Parameters
record.ID.expr
ON ERROR statements

After you execute WRITEU, the STATUS function returns one of the values described in the following table.
Return Value Description
0
Successful write.
1
Return Value Description

2
3
10
2012 Onsystex Corp.

returns a value of 0 in the parameter execstat, indicating that the WRITEU
is not allowed.
example, trigger subroutine is not cataloged).
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.
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 Basic
CLOSE, DELETE, OPEN, READL, READU, READV, READVL, READVU, WRITE, WRITEV, WRITEVU
OASYS
364 WRITEV
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..

Remember the following points about alternate key indexes when you code WRITEV statements:
key, WRITEV sets the STATUS return value to 10.
364.3 Parameters
Parameter
Description
expr
Specifies an expression to write to an attribute of a record.
2012 Onsystex Corp.
WRITEV
ON | TO file.var,
record.ID.expr
attrib.expr
ON ERROR statements
415

If no default file is open, a fatal WRITEV error occurs.
OPEN statement.
Specifies an attribute to receive the expression.
Specifies statements to execute if the WRITEV statement fails
index key).
When including WRITEV 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.
WRITEV Parameters

After you execute WRITEV, the STATUS function returns one of the values described in the following table.
Value
0
1
2
3
10
Description
Successful write.
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.
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:
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.
2012 Onsystex Corp.
416

OASYS Basic
CLOSE, DELETE, OPEN, READL, READU, READV, READVL, READVU, WRITE, WRITEU, WRITEVU
OASYS
365 WRITEVU
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..

Remember the following points about alternate key indexes when you code WRITEVU statements:
If you execute the ECL command DUP.STATUS ON, then write a record that creates a duplicate alternate key,
WRITEVU sets the STATUS return value to 10.
365.3 Parameters
2012 Onsystex Corp.
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.
If no default file is open, a fatal error occurs.
OPEN statement.
Specifies an attribute to receive the expression.
Specifies statements to execute if the WRITEVU statement fails
index key).
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
365.4 STATUS Function Return Value

After you execute WRITEVU, the STATUS function returns one of the values in the following table.
Return Value
Description
0
1
2
Successful write.
WRITEVU is not allowed.
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.
3
10

OASYS Basic
CLOSE, DELETE, OPEN, READL, READU, READV, READVL, READVU, WRITE, WRITEU, WRITEV
OASYS
2012 Onsystex Corp.
417
418
366 XLATE
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
Parameter
Description
filename
Specifies the name of a file from which to return the contents of an

attribute. file.expr must be the name of a valid OASYS file, not the value of
a file variable, even if the same file was opened within the program.
Specifies a record ID in file.expr.
Specifies a valid attribute in file.expr.
Enter a code specifying action to be taken if the record does not exist or
the attribute is empty:
C Substitutes the id.expr for the value of the function.
V Returns an empty string and prints an error message.
X Returns an empty string.
XLATE Parameters
rec.id.expr
attrib.expr
"code"

OASYS
TRANS For information, see Using OASYS.
367 ASCII Character Codes

This appendix describes each ASCII (American Standard Code for Information Interchange) code.
ASCII Value
Character
Hex Character
000
001
002
003
004
005
006
NUL
SOH
STX
ETX
EOT
ENQ
ACK
0
1
2
3
4
5
6
2012 Onsystex Corp.
ASCII Character Codes
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 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 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
2012 Onsystex Corp.
105
106
i
69
j
6A
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 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
2012 Onsystex Corp.
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 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
2012 Onsystex Corp.
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
2012 Onsystex Corp.
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 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
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
368 OAS Basic @variables

This appendix lists the @variables available in OASYS Basic, the delimiter @variables, and the codes returned
by @SYSTEM.RETURN.CODE.
368.1 @variables
The following table describes the valid @variables.
@variable
Description
@ACCOUNT
Returns the operating system path where you first entered

OASYS. Note that the value of @ACCOUNT does not change
when a LOGTO statement is executed.
Inserts an attribute mark at compile time.
For information about other system delimiter @ variables, see
Delimiter @variables in this appendix.
Last OASYS command executed. Changes the value for each
statement executed at the OASYS ECL prompt ( : ) and in the
OASYS Basic EXECUTE statement.
Used with CALCULATE and the braces {} function. Returns
the conversion code from a dictionary item.
Height of the CRT screen.
Width of the CRT screen.
DATA statements used in conjunction with INPUT statements
are stored in a data stack or input queue. This stack is accessible
in the @DATA variable. Data elements are delimited by ASCII
013 (CR). @DATA is a READ ONLY variable.
System date, in internal format, when the program began
executing.
Two-digit day of the month.
Current dictionary (must perform an assignment).
the format code from a dictionary item.
For UNIX, returns the group ID assigned to a user. For
Windows NT or Windows 2000, returns a string that contains all
the group names (separated by value marks) to which the user
belongs.
@variables
@AM
@COM M AND
@CONV
@CRTHIGH
@CRTWIDE
@DATA
@DATE
@DAY
@DICT
@FORM AT
@GID
2012 Onsystex Corp.
OAS Basic @variables
@variable
Description
@HEADER

the column heading from a dictionary item.
Current record ID.
Stores the last executed command.
Current PERFORM or EXECUTE level.
Returns the users login name.
Page length (height) of the system line printer.
Page width of the system line printer.
Two-digit representation of the current month.
The last paragraph or sentence entered. It retains the name and
parameters of the current executing paragraph. If no paragraph is
being executed, an empty string is returned. If another paragraph
is called within the first paragraph executed, the returned value is
of the called paragraph until control is returned to the calling
paragraph.
Current operating system path for the directory where the user
resides. The value of @PATH changes with the LOGTO
command.
Current record (must be assigned).
Recursive user defined. @RECUR# variables are reset at the
ECL prompt.
@ID
@LASTVERB
@LEVEL
@LOGNAM E
@LPTRHIGH
@LPTRWIDE
@M ONTH
@PARASENTENCE
@PATH
@RECORD
@RECUR0
@RECUR1
@RECUR2
@RECUR3
@RECUR4
@RM
@variable
Description
@SENTENCE
The statement that invoked the current OASYS Basic program in

progress. Reflects the last command entered at the ECL prompt
or in a paragraph or sentence executed by a OASYS Basic
program. Each OASYS Basic EXECUTE and CHAIN statement
also resets @SENTENCE.
Inserts a subvalue mark (same as @SVM ) at compile time.
For information about other delimiter variables, see Delimiter
@variables in this appendix.
Inserts a subvalue mark (same as @SM ) at compile time.
Enables or disables a users terminal bell.
Returns a value indicating a condition or error after the execution
of an ECL command. For most commands, 0 indicates the
command was completed correctly, and -1 indicates that the
command was not completed correctly.
For more information, see @SYSTEM .RETURN.CODE
Values in this appendix.
The time (in internal format) when the first program in the call
string program.
Inserts a text mark at compile time. The text mark has no direct
effect, but can be used by OASYS Basic programs.
@SM
@SVM
@SYS.BELL
@SYSTEM .RETURN.
CODE
@TIM E
@TM
2012 Onsystex Corp.
Inserts a record mark at compile time.

@variables (continued)
425
426

@TRANSACTION
@TTY
@OASNO
@UID
Returns 1 if there is a transaction occurring, and returns 0 if there

is no transaction occurring.
Returns the terminal port name, such as tty01, tty1a, or console.
Returns an integer between 1 and the maximum number of users
allowed on the system. Numbers are assigned sequentially based
on the sequence of entry into OASYS. Phantom processes are
counted.
The operating system user ID number for the user.
@variable
Description
@USER0
@USER1
@USER2
@USER3
@USER4
@USERNO
@USER.RETURN.
CODE
@USER.TYPE
User-defined. @USER# variables retain their value throughout a

user session unless the values are explicitly changed.
@VM
@WHO
@YEAR
Current oas process ID number.

User-defined.
Returns the type of process currently running. OASYS Basic
has three types of processes:
0 Normal terminal processes.
1 Background (phantom) processes.
2 Redirected standard input.
Inserts a value mark at compile time.
For information about other delimiter @variables, see Delimiter
@variables in this appendix.
Retrieves your current directory. For example, if you are in
UNIX directory /u/ud/AP, the value of @WHO is AP.
Two-digit representation of the year.
368.2 Delimiter @variables

The following @variables are replaced by the compiler with dynamic arrays delimiters. Use the same @variables
to place delimiters in OASYS hashed files.
@variable
@AM
@VM
@SM
@RM
@TM
@SVM
Description
Attribute mark
Value mark
Subvalue mark
Record mark
Text mark
Subvalue mark (same as @SM )
Delimiter @variables
2012 Onsystex Corp.
OAS Basic @variables
427
368.3 @SYSTEM.RETURN.CODE Values

@SYSTEM.RETURN.CODE returns various values based on the last command executed. @SYSTEM.RETURN.
CODE is available in OASYS Basic, and is set by many commands, both OASYS Basic and ECL.
368.3.1 ECL @SYSTEM.RETURN.CODE Values

The following table describes the possible @SYSTEM.RETURN.CODE values for various ECL commands.
Command
Success Return Value
BSELECT
The number of items in the select -1

list.
The number of indexes built.
-1
0
-1
The number of indexes created. -1
The number of indexes deleted. -1
list.
list.
list.
The number of items listed.
-1
The number of indexes listed.
-1
-1
-1
BUILD.INDEX
COM PILE.DICT
CREATE.INDEX
DELETE.INDEX
ESEARCH
FORM .LIST
GET.LIST
LIST
LIST.INDEX
LIST.ITEM
LIST.LABEL
Error Return Value
ECL @SYSTEM.RETURN.CODE Values
Command
LOCK
M ERGE.LIST
M ODIFY
NSELECT
Error Return Value
-1 if you specify an
invalid lock number.
-2 if the resource is
locked by another user.
list.
The number of records modified. -1
The number of items in the select 0

list.
QSELECT
list.
SAVE.LIST
The number of items saved.
-1
SELECT
list.
SORT
-1
SORT.ITEM
-1
SORT.LABEL
-1
SSELECT
list.
STACKCOM M ON
1 On
N/A
0 Off
2012 Onsystex Corp.
428
368.3.2 OAS Basic @SYSTEM.RETURN.CODE Values

The following table describes the possible @SYSTEM.RETURN.CODE values for OASYS Basic commands..
Command
Error Return Value
GETQUEUE
The number of locks waiting to -1

be released.
GETREADU
The number of locks set.
-1
INPUT (with FOR or
0
-1 (used if timeout
WAITING clause
option is set; INPUT
included)
timed out)
INPUT @ (with FOR or 0
-1 (used if timeout
WAITING clause
option is set; INPUT
included)
timed out)
PCPERFORM
0
-1
369 Operators in OAS Basic

This appendix describes the arithmetic, Boolean, and relational operators available you can use in OASYS Basic.
369.1 Arithmetic Operators

The following table describes the arithmetic operators for OASYS Basic.
Operator
Action
Unary plus (same as VAR = +VAR

multiplying by +1).
Unary minus (changes VAR = -VAR
to the opposite sign,
same as multiplying by
-1).
Addition.
X = VAR1 + VAR2
VAR = VAR + 1
Subtraction.
X = VAR1 - VAR2
VAR = VAR - 1
M ultiplication.
X = VAR1 * VAR2
Division.
QUANTITY = PRICE/
COST
Exponentiation.
X = VAR^2
Concatenation.
X = VAR1:VAR2
Increments the value of LINES += 1
a variable.
Decrements the value ofLINES -= 1
a variable.
Arithmetic Operators
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
2012 Onsystex Corp.
Operators in OAS Basic
429
of the operator.
/=
Divides the value to the VAR1 /= VAR2

left of the operator by
the value to the right of
the operator.
Concatenates the value VAR1 := VAR2
to the left of the
operator by the value to
the right of the
operator.
Arithmetic Operators (continued)
:=
369.2 Boolean Operators

The following table describes the Boolean operators for OASYS Basic.
Operator
Action
AND, &
When both expressions

are true, the result is
true.
When either expression
is true, the result is true.
Inverts the result of
conditional statements.
Inverts the logical result
of each element of a
dynamic array.
OR, !
NOT
NOTS
Example
Boolean Operators
369.3 Relational Operators

The following table describes the relational operators for OASYS Basic.
Operator
2012 Onsystex Corp.
Description
=, EQ
Multivalued
Equivalent
EQS
#, <>, ><, NE
NES
Not equal to. The # can

be used to negate other
operators.
>, GT
GTS
Greater than.
Equal to.
Example
430
<, LT
LTS
Less than.
>=, =>, #<, GE
GES
Greater than or equal

to.
<=, =<, #>, LE
LES
Less than or equal to.
Relational Operators
370 Reserved Words

This appendix lists the reserved keywords, commands, functions, and @variables. Do not use any of them for
subroutine names or for OASYS Basic variable names.
Reserved Words
$BASICTYPE
$F
$IFDEF
$INCLUDE
$T
$UNDEFINE
@ACCOUNT
@CONV
@CRTWIDE
@DATE
@DICT
@FORM AT
@HEADER
@LASTVERB
@LOGNAM E
$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
CRT
DATA
DCOUNT
DECLARE
DEL
DELETELIST
DIM
DIR
DISPLAY
DO
DQUOTE
DTX
ECHO
END
EQ
EQU
2012 Onsystex Corp.
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
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
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
2012 Onsystex Corp.
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
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
READL
READNEXT
READONLY
READT
READV
READVU
READXBCK
RECORDLOCKED
RECORDLOCKU
RELEASE
REM OVE
REPLACE
RETURN
REUSE
RND
RQM
SADD
SDIV
2012 Onsystex Corp.
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
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
WRITE
WRITELIST
WRITEONLY
WRITESEQ
WRITESEQF
WRITET
WRITEU
WRITEV
WRITEVU
XLATE
XTD
371 Commands Affected by BASICTYPEs and oas.OPTIONS

This appendix lists the OASYS Basic commands and functions that behave differently or have different syntax
depending on the BASICTYPE or CUST.OPTIONS you have set at the time you compile the program. For detailed
information about how BASICTYPEs or CUST.OPTIONS affect a particular command or function, see the documentation for that
this manual. For descriptions of BASICTYPEs, see the OASYS Basic $BASICTYPE command in this manual. For
more detailed information about CUST.OPTIONS, see the CUST.OPTIONS Commands Reference.
2012 Onsystex Corp.
Commands Affected by BASICTYPEs and oas.OPTIONS
Command or Function
$INCLUDE
The BASICTYPE Setting Determines...

CUST.OPTIONS
Whether you can use INCLUDE for the
N/A
$INCLUDE command.
[]
Whether the [] (square brackets) function can N/A
entirely remove parts or all of a substring.
ABORT
Whether you can specify multiple messages to 8
display when the program aborts. The
BASICTYPE setting also determines whether
you can specify a message ID that evaluates to a
key in the OASYS error message file.
CALLC
N/A
88
CHAIN
N/A
6, 11, 27, 40, 54
CLEAR
Whether the CLEAR command can set all
N/A
variables in unnamed common areas to 0.
COM M ON
Whether zero elements are maintained in arrays. N/A
The BASICTYPE setting also determines
whether you can use the PASSCOM option.
COUNT
Whether the COUNT function can find
N/A
overlapping character substrings in a string.
COUNTS
Whether the COUNTS function can find
N/A
overlapping character substrings in an array of
strings.
CRT
N/A
5, 46
DATA
N/A
11, 27
DEBUG
N/A
14
Commands and Functions Affected by BASICTYPEs and CUST.OPTIONS
Command or Function
DISPLAY
DIM
EBCDIC
ECHO
ENTER
EXECUTE
EXECUTESQL
FLUSH
FM T
FOOTING
HEADING
ICONV

N/A
Whether excess data (including delimiters)
resulting from redimensioning an array can be
placed in position 0,0 of the dimensioned array.
Whether ASCII data is converted to EBCDIC
before it is written to tape.
N/A
N/A
Whether commands are parsed by using the
standard OASYS parser or the P-type parser.
N/A
N/A
How the data is formatted (in cases for which the
BASICTYPE setting can produce different
results).
N/A
N/A
Whether the ICONV function returns an empty
string if CUST.OPTIONS 56 is on and the input
value or conversion code is invalid.
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
IN
N/A
46
INPUT
N/A
12, 18, 46, 65, 83
Commands and Functions Affected by BASICTYPEs and CUST.OPTIONS (continued)
2012 Onsystex Corp.
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
N/A
resulting from executing the M ATPARSE
command can be placed in position 0,0 of the dimensioned array.
M ATREAD
N/A
resulting from executing the M ATREAD command
can be placed in position 0,0 of the dimensioned
array.
M ATREADL
N/A
resulting from executing the M ATREADL
command can be placed in position 0,0 of the
dimensioned array.
M ATREADU
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;
for OCONV M D,
also 13 and 63)
OCONVS
Whether the OCONVS function returns an empty 56
Command or Function
ON/GOSUB
Whether OASYS bypasses the GOSUB clause N/A

and executes the next program statement
(contingent on whether the expression in the ON/
GOSUB command is nonnumeric or less than 1).
Whether OASYS bypasses the GOTO clause and N/A
executes the next program statement (contingent
on whether the expression in the ON/GOTO
command is nonnumeric or less than 1).
N/A
35
Whether commands are parsed by using the
11, 27, 35, 46, 93,
standard OASYS parser or the P-type parser.
105
N/A
5, 46
N/A
75, 102
N/A
75
Whether you should use the READLIST or
N/A
READSELECT command to assign values in an
active select list to a dynamic array. The
BASICTYPE setting also determines whether
you can assign values in a select list, based on an
account other than the current one, to a dynamic
array. It also determines whether you can use the
SETTING clause to set the number of elements in
the select list to a variable.
ON/GOTO
PCPERFORM
PERFORM
PRINT
PROCREAD
PROCWRITE
READLIST
CUST.OPTIONS
2012 Onsystex Corp.
Commands Affected by BASICTYPEs and oas.OPTIONS
437
Command or Function The BASICTYPE Setting Determines...
CUST.OPTIONS
READNEXT
Whether you can assign the next record ID from an 23, 71

active select list, based on an account other than the
current one, to a variable. It also determines whether
you can use the SETTING clause to set the number
of elements in the select list to a variable.
RECORDLOCKED
N/A
35
RELEASE
N/A
78
SELECT
Whether you can specify a numbered select list (0 N/A
9) in the SELECT command.
SELECTINFO
What the -1 SELECTINFO function return value N/A
means.
SLEEP
N/A
46
STOP
Whether you can specify multiple messages to
8, 46
display when the program stops. The BASICTYPE
setting also determines whether you can specify a
message ID that evaluates to a key in the OASYS
error message file.
SYSTEM
N/A
100
TRIM
Whether all leading and trailing spaces or
N/A
occurrences of a specified character are removed
from each element in a dynamic array. For a simple
string expression, any BASICTYPE setting
produces the same result.
OASEXECUTE
N/A
35
372 Commands That Set STATUS() Return Values

This appendix lists the OASYS Basic commands and functions that set STATUS function return values and
describes each value.
Command or Function STATUS() Return Values
FILELOCK
FM T
GETPTR
ICONV
2012 Onsystex Corp.
0 File locked successfully.

usernum If the file was already locked, and if the LOCKED
clause was included in the FILELOCK statement, STATUS()
returns the user number of the process that locked the file.
0 Successful completion.
1 String expression is invalid or exceeds the allowable string
size.
2 Conversion code is invalid.
0 Successful completion.
1 No more rows exist.
2 Other error.
0 Successful conversion.
1 Invalid input data.
2 Invalid conversion specification.
3 Invalid date for D conversion code only.
5 Null value if null value handling is turned on.
438
ICONV D
0 Successful conversion of a valid date.

1 Invalid input date.
3 Date was converted correctly, but month and day were
inverted in input value.
ICONVS
0 Successful conversion.
1 Invalid input data.
3 Invalid date for D conversion code only.
5 Null value if null value handling is turned on.
Commands and Functions That Set STATUS() Return Values

M ATWRITE
0 The record was locked before M ATWRITE executed. You are

in danger of simultaneously updating a record being updated by
another user.
-2 The record was not locked before M ATWRITE executed.
M ATWRITEU
0 The record was locked before M ATWRITEU executed. You
are in danger of simultaneously updating a record being updated
by another user.
-2 The record was not locked before M ATWRITEU executed.
OCONV D
0 Successful conversion of a valid date.
1 The input date was invalid.
2 The conversion code was invalid.
OPENSEQ
0 The record does not exist.
1 The file you specify is not a sequential-access file.
2 The file does not exist.
3 The READONLY clause was included in the command
statement and the record does not exist.
4 An unknown error occurred (such as having too many files
open or permission problems).
OSBREAD
0 The read was successful.
1 The file name is invalid.
2 Access is denied by the operating system.
4 An unknown error occurred.
OSBWRITE
0 The write was successful.
1 The file name is invalid.
2 You do not have permission to access the file.
OSCLOSE
0 The file has closed successfully.
5 The file did not close.
Commands and Functions That Set STATUS() Return Values (continued)

OSDELETE
READ
0 The file was deleted.

1 The directory name is invalid.
2 OASYS cannot access the file (such as user does not have
permission).
0 Successful read.
2 A read error occurred.
2012 Onsystex Corp.
Commands That Set STATUS() Return Values
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.
READBCKU
0 Successful read.
READFWD
0 Successful read.
READFWDL
0 Successful read.
READFWDU
0 Successful read.
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.

READT
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.
2012 Onsystex Corp.
439
440
SUBROUTINE (Update 0 No error.

Trigger)
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 update or delete is not allowed.
3 Trigger execution error or unexpected return from trigger
routine (for example, the trigger subroutine is not cataloged).
SUBROUTINE (Delete 0 No error.
Trigger)
indicating that the update or delete is not allowed.
TRANSACTION
0 The commit completed successfully.
COM M IT
1 Transaction not started.
3 Transaction cannot commit.
TRANSACTION
0 The transaction was started.
START
1 The transaction was not started.
WEOF
0 Successful read.
4 Parity error.

WRITE
0 Successful write.
indicating that the WRITE is not allowed.
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.
4 Parity error.
2012 Onsystex Corp.
Commands That Set STATUS() Return Values
WRITEU
0 Successful write.
indicating that the WRITEU is not allowed.
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.
indicating that the WRITEV is not allowed.
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.

WRITEVU
0 Successful write.
indicating that the WRITE VU is not allowed.
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.
2012 Onsystex Corp.
441

OAS Basic Commands Reference

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

OAS Basic Commands Reference

Hochgeladen von

Copyright:

Verfügbare Formate

OASYS Basic

2012 Onsystex Corp.

OASYS Basic Commands Reference Manual

OASYS Basic Commands Reference

Special thanks to:

2012 Onsystex Corp.

OASYS Basic Commands Reference

2012 Onsystex Corp.

OASYS Basic Commands Reference

2012 Onsystex Corp.

OASYS Basic Commands Reference

2012 Onsystex Corp.

OASYS Basic Commands Reference

2012 Onsystex Corp.

2012 Onsystex Corp.

OASYS Basic Commands Reference

155 ICONV Date (D)

156 ICONV Group (G)

157 ICONV Length (L)

158 ICONV Masked Character (MC)

159 ICONV Masked Decimal (MD)

160 ICONV Left Justify (ML)

161 ICONV Packed Decimal (MP)

OASYS Basic Commands Reference

162 ICONV Packed Decimal (MP1)

163 ICONV Right Justify (MR)

164 ICONV Time (MT)

165 ICONV Hex (MX | HEX), Octal (MO), Binary

166 ICONV Pattern Match (P)

167 ICONV Range (R)

168 ICONV SOUNDEX (S)

169 ICONV Text Extraction (T)

170 ICONV File Translation (Tfile)

OASYS Basic Commands Reference

2012 Onsystex Corp.

2012 Onsystex Corp.

OASYS Basic Commands Reference

2012 Onsystex Corp.

OASYS Basic Commands Reference

2012 Onsystex Corp.

OASYS Basic Commands Reference

228 OCONV Date (D)

OASYS Basic Commands Reference

229 OCONV Group (G)

230 OCONV Length (L)

231 OCONV Masked Character (MC)

232 OCONV Masked Decimal (MD)

233 OCONV Left Justify (ML)

234 OCONV Packed Decimal (MP)

235 OCONV Packed Decimal (MP1)

236 OCONV Right Justify (MR)

237 OCONV Time (MT)

238 OCONV Hex (MX | HEX), Octal (MO), Binary

239 OCONV Pattern Match (P)

240 OCONV Range (R)

2012 Onsystex Corp.

OASYS Basic Commands Reference

241 OCONV SOUNDEX (S)

242 OCONV Text Extraction (T)

243 OCONV File Translation (Tfile)

OASYS Basic Commands Reference

264 PRINTER CLOSE

OASYS Basic Commands Reference

OASYS Basic Commands Reference