Sirius Functions Reference Manual

Transcription

———————————————————
———————————————————
Sirius Software, Inc.
875 Massachusetts Avenue, Suite 21
Cambridge, MA 02139
Telephone: (617) 876-6677
FAX: (617) 234-1200
E-mail: [email protected]
World Wide Web: http://sirius-software.com
November 17, 2010
© 2010 Sirius Software, Inc.
——————————————————————————————————————————
——————————————————————————————————————————
——————————————————————————————————————————
ii
——————————————————————————————————————————
Proprietary Notices
——————————————————————————————————————————
——————
Proprietary Notices
The following products:
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
Fast/Unload
Fast/Unload User Language Interface
Janus Open Client
Janus Open Server
Janus Sockets
Janus Specialty Data Store
Janus Web Server
Japanese Functions
SirDBA
Sirius Functions
Sirius Mods
SirLib
SirMon
SirPro
SirScan
Sir2000 Field Migration Facility
Sir2000 User Language Tools
UL/SPF
are proprietary products of Sirius Software, Inc.:
Sirius Software, Inc.
875 Massachusetts Avenue, Suite 21
Cambridge, Massachusetts 02139
USA
Model 204® is a proprietary product of Computer Corporation of America, a whollyowned subsidiary of Rocket Software, Inc., which owns the trademark:
Rocket Software Corporate Office
M204 Division
275 Grove Street
Suite 3-410
Newton, Massachusetts 02466-2272
USA
——————————————————————————————————————————
iii
——————————————————————————————————————————
Proprietary Notices
——————————————————————————————————————————
——————————————————————————————————————————
iv
——————————————————————————————————————————
Contents
——————————————————————————————————————————
———————
Contents
Proprietary Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iii
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Summary of Changes . . .
Sirius Mods Version 7.3
Chapter 1:
Introduction
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
xv
xv
xv
xvi
xvi
xvii
xvii
xviii
xix
xix
xix
xx
xxi
xxii
xxii
xxiii
xxiii
xxiv
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Versions, Compatibility, and Installation . . . . . . . . . . . . . . . . . . . . . . 1
Related manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Chapter 2:
Sdaemons
Chapter 3:
$lists
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
$lists and ECF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 4:
Longstrings
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Truncation . . . . . . . . . . . . . . . .
Longstrings in expressions . . . . . . .
Longstrings and $functions . . . . . . .
Longstrings and complex subroutines . .
Changing Longstring truncation behavior
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
12
13
16
18
19
——————————————————————————————————————————
v
——————————————————————————————————————————
Contents
——————————————————————————————————————————
Longstrings and the Print, Html, and Text statements . . . . . . . . . . . . . .
Longstring performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
21
Chapter 5:
Sessions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
Chapter 6:
Procedure Processing $Functions . . . . . . . . . . . . . . . .
29
Chapter 7:
Description of $Functions . . . . . . . . . . . . . . . . . . . . .
31
CALLing Sirius Mods functions . . . . . . . . . . . . . . . . . . . . . .
$A2E: Translate ASCII to EBCDIC . . . . . . . . . . . . . . . . . . . .
$ABBREV: Determine if string is abbreviation within list of words . . . .
$ARR_FIND: Find value within array . . . . . . . . . . . . . . . . . . .
$ARR_INIT: Initialize every element of array to specific value . . . . . .
$ARR_MAX: Find maximum value in array . . . . . . . . . . . . . . . .
$ARR_MIN: Find minimum value in array . . . . . . . . . . . . . . . . .
$BASE64_DECODE: Convert from base 64 to byte string . . . . . . . .
$BASE64_ENCODE: Convert byte string to base 64 . . . . . . . . . . .
$BGPURGE: Cancel "long" sdaemon request initiated with $COMMBG .
$BGQUERY: List of "long" sdaemon requests initiated via $COMMBG .
$BIND: Fast, easy synchronization of system wide resource . . . . . . .
$BIND_LIST: Return list of bound semaphores onto a $list . . . . . . .
$BITAND: Bitwise AND of two integers . . . . . . . . . . . . . . . . . .
$BITOR: Bitwise OR of two integers . . . . . . . . . . . . . . . . . . .
$BUMP: Bump a user . . . . . . . . . . . . . . . . . . . . . . . . . . .
$CENTER: Center string . . . . . . . . . . . . . . . . . . . . . . . . .
$CFSTATL: List of statistics for users holding critical file resources . . .
$CLOSE: Close file or group in User Language request . . . . . . . . .
$CMS: Determine if online is running under CMS . . . . . . . . . . . .
$COMMAND: Execute Model 204 command on sdaemon, results to
image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$COMMBG: Execute Model 204 commands on sdaemon . . . . . . . .
$COMMNDL: Execute Model 204 command on sdaemon, results to $list
$CONTEXT: Determine if string is name of open file or group . . . . . .
$C2D: Convert binary byte string to integer . . . . . . . . . . . . . . . .
$DAEMONMASTERNUMBER: Get user number of master thread . . .
$DAEMONPARENTNUMBER: Get user number of parent thread . . . .
$DB_xxx: Janus Open Client $functions . . . . . . . . . . . . . . . . .
$DEFLATE: Compress a longstring with Deflate . . . . . . . . . . . . .
$DELCH: Remove characters from string, compress and strip blanks . .
$DELG_SUBSYS: Delete subsystem-wide global . . . . . . . . . . . . .
$DELG_SYS: Delete system-wide global . . . . . . . . . . . . . . . . .
$DELIMR: Insert delimiter string into input string at regular positions . .
$D2C: Binary byte representation of integer . . . . . . . . . . . . . . .
$D2X: Hex representation of integer . . . . . . . . . . . . . . . . . . .
$E2A: Translate EBCDIC to ASCII . . . . . . . . . . . . . . . . . . . .
$EDSCAN: Scan list of entities in online . . . . . . . . . . . . . . . . .
$ENT: Do character entity substitution . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
32
33
34
36
38
39
41
43
45
47
48
49
51
53
54
55
56
58
60
62
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
63
66
69
71
73
75
76
77
78
80
82
84
85
86
88
89
90
93
——————————————————————————————————————————
vi
——————————————————————————————————————————
Contents
——————————————————————————————————————————
$ENT_PRINT: Set automatic character entity substitution . . . . . . . .
$ENT_TAB: retrieve/modify character entity substitution table . . . . . .
$ERRSET: Increment or clear number of counting errors, set $ERRMSG
$FAKEENT: Prepare fake ENTER to automatically satisfy next full
screen read . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$FIELD_IMAGE: Return field values into an image . . . . . . . . . . . .
$FIELD_LIST: Return field values into a $list . . . . . . . . . . . . . . .
$FIELD_LISTI: Return field values into a $list mapped to an image . . .
$FINITIM: File initialization YYDDDMMHHSSTH . . . . . . . . . . . . .
$FISTAT: Retrieve file's statistics into string . . . . . . . . . . . . . . .
$FISTATL: Retrieve set of files' statistics into list . . . . . . . . . . . . .
$FREEOPT: Free optional file or group from subsystem . . . . . . . . .
$FUNFORC: Cancel running or waiting Fast/Unload request . . . . . .
$FUNIMG: Retrieve data from active Fast/Unload request into image . .
$FUNLIST: $list of active and enqueued Fast/Unload requests . . . . .
$FUNLOAD: Fast/Unload records in Model 204 list or found set . . . . .
Syntax and error codes . . . . . . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$FUNPURG: Purge running or waiting Fast/Unload request . . . . . . .
$FUNSKIP: Skip to next output record for $FUNIMG, $FUNSSTR . . . .
$FUNSSTR: Retrieve data from active Fast/Unload request into string .
$FUNWAIT: Wait until asynchronous Fast/Unload request completes . .
$GUNZIP: Decompress a longstring with GUNZIP . . . . . . . . . . . .
$GZIP: Compress a longstring with GZIP . . . . . . . . . . . . . . . . .
$HEXA: Convert hexadecimal string to EBCDIC equivalent . . . . . . .
$IHEXA: Convert EBCDIC string to hexadecimal equivalent . . . . . . .
$IMGINF: Retrieve image item by variable name . . . . . . . . . . . . .
$IMGOVL: Replace image item value . . . . . . . . . . . . . . . . . . .
$INCSTAT: Increment local system statistic . . . . . . . . . . . . . . .
$INFLATE: Decompress a longstring with inflate . . . . . . . . . . . . .
$JOBAUTH: Determine if user has authorization for USE $JOB . . . . .
$LIST_ADD_ORDERED: Add an item to an ordered $list . . . . . . . . .
$LIST_ADD_UNIQUE: Conditionally add an item to a $list . . . . . . . .
$LIST_ADD_UNIQUE_ORDERED: Conditionally add an item to an
ordered $list . . . . . . . . . . . . . . . . . . . . . . . . . . .
$LIST_CAPTURE: Capture print data to $list . . . . . . . . . . . . . . .
Print capturing hierarchy and other considerations . . . . . . . . . .
Message capture and MSGCTL . . . . . . . . . . . . . . . . . . .
$LIST_CONV_ITEM: Convert $list to single delimited $list item . . . . .
$LIST_COPY_ITEMS: Copy items between $lists . . . . . . . . . . . .
$LIST_DIFF_ITEM: Differences between $list and delimited $list item . .
$LIST_GLOBAL and $LIST_SESSION: Access/create global/session
$list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$LIST_GLOBAL_DEL and $LIST_SESSION_DEL: Delete global/session
$lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$LIST_GLOBAL_LIST and $LIST_SESSION_LIST: List global/session
$lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$LIST_MAXIL: Return maximum $list item length . . . . . . . . . . . . .
. . .
. . .
. . .
95
97
99
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
100
101
105
108
113
114
116
118
120
121
123
125
127
128
131
132
134
136
137
139
141
142
143
145
147
148
149
150
152
.
.
.
.
.
.
.
.
.
.
.
.
.
.
154
156
157
159
161
164
166
. .
169
. .
173
. .
. .
175
177
——————————————————————————————————————————
vii
——————————————————————————————————————————
Contents
——————————————————————————————————————————
$LIST_PRINT: Display contents of a $list . . . . . . . . . . . . . . . . .
$LISTADD: Add string as new $list item . . . . . . . . . . . . . . . . .
$LISTADD_LSTR: Add longstring as new $list item . . . . . . . . . . .
$LISTADDI: Add image as new $list item . . . . . . . . . . . . . . . . .
$LISTADJ: Adjust length of $list item . . . . . . . . . . . . . . . . . . .
$LISTCHK: Validate a $list identifier . . . . . . . . . . . . . . . . . . .
$LISTCMP: Compare two $lists and produce $list describing differences
$LISTCNT: Number of items in $list . . . . . . . . . . . . . . . . . . .
$LISTCPY: Copy $list . . . . . . . . . . . . . . . . . . . . . . . . . . .
$LISTDEL: Release CCATEMP storage used for $list . . . . . . . . . .
$LISTFIND: Find string in $list . . . . . . . . . . . . . . . . . . . . . .
$LISTFINDI and $LISTFINDI_UP: Find image item in $list . . . . . . . .
$LISTFINDI_SUB: Build $list subset based on image item . . . . . . . .
$LISTILN: Length of $list item . . . . . . . . . . . . . . . . . . . . . . .
$LISTIMG: Associate an image with a $list . . . . . . . . . . . . . . . .
$LISTIMG_COPY: Copy a $list's image association . . . . . . . . . . .
$LISTINF: Retrieve $list item into string . . . . . . . . . . . . . . . . .
$LISTINF_LSTR: Retrieve $list item into longstring . . . . . . . . . . .
$LISTINFI: Retrieve $list item into image . . . . . . . . . . . . . . . . .
$LISTINS: Insert string into a $list . . . . . . . . . . . . . . . . . . . .
$LISTINS_LSTR: Insert string into a $list . . . . . . . . . . . . . . . . .
$LISTINSI: Insert image into a $list . . . . . . . . . . . . . . . . . . . .
$LISTLOC: Locate string in $list . . . . . . . . . . . . . . . . . . . . .
$LISTLUP: Locate string in $list, searching backwards . . . . . . . . . .
$LISTMOVE: Move a $list . . . . . . . . . . . . . . . . . . . . . . . . .
$LISTNEW: Create empty $list . . . . . . . . . . . . . . . . . . . . . .
$LISTNEWA: Create array of empty $lists . . . . . . . . . . . . . . . .
$LISTNEWAI: Create array of empty $lists associated with image . . . .
$LISTNEWI: Create empty $list associated with image . . . . . . . . . .
$LISTOVL: Overlay part of $list item with string . . . . . . . . . . . . .
$LISTOVLI: Overlay part of $list item with image item . . . . . . . . . .
$LISTREM: Remove item from $list . . . . . . . . . . . . . . . . . . . .
$LISTREP: Replace a $list item with a string . . . . . . . . . . . . . . .
$LISTREP_LSTR: Replace a $list item with a longstring . . . . . . . . .
$LISTREPI: Replace $list item with an image . . . . . . . . . . . . . .
$LISTRST: Restore global $list . . . . . . . . . . . . . . . . . . . . . .
$LISTSAV and $LISTSAVE: Save global $list . . . . . . . . . . . . . .
$LISTSAVL: Count and names of available global $lists . . . . . . . . .
$LISTSORT and $LISTSRT : Sort $list . . . . . . . . . . . . . . . . . .
$LISTSUB: Create $list that is subset of input $list . . . . . . . . . . . .
$LISTUPD: Produce $list from input $list using $list of updates . . . . .
$LSTR: Treat a string as longstring . . . . . . . . . . . . . . . . . . . .
$LSTR_ADD_USERBUFFER: Add longstring to user buffer . . . . . . .
$LSTR_BASE64_DECODE: Convert from base 64 to byte string . . . . .
$LSTR_BASE64_ENCODE: Convert byte string to base 64 . . . . . . .
$LSTR_C2X: Convert byte string to hexadecimal . . . . . . . . . . . . .
$LSTR_GET_IMAGE and $LSTR_SET_IMAGE: Longstring to/from
image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
178
180
182
184
187
189
190
192
193
194
195
196
199
202
203
205
206
208
209
211
214
216
219
222
225
228
229
232
234
235
238
241
243
245
247
250
252
255
257
260
263
265
266
267
269
270
. .
271
——————————————————————————————————————————
viii
——————————————————————————————————————————
Contents
——————————————————————————————————————————
$LSTR_GET_USERBUFFER: Get user buffer contents to a longstring .
$LSTR_GLOBAL and $LSTR_SESSION: Bind to global/session
longstring . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$LSTR_GLOBAL_DEL and $LSTR_SESSION_DEL . . . . . . . . . .
$LSTR_GLOBAL_GET and $LSTR_SESSION_GET . . . . . . . . . .
$LSTR_GLOBAL_SET and $LSTR_SESSION_SET . . . . . . . . . .
$LSTR_INDEX: Find a string inside a longstring . . . . . . . . . . . .
$LSTR_LEFT: Leftmost characters of a longstring . . . . . . . . . . .
$LSTR_LEN: Length of a longstring . . . . . . . . . . . . . . . . . . .
$LSTR_PARSE: Part of longstring preceding character in delimiter set
$LSTR_PARSEX: Part of longstring following character in delimiter set
$LSTR_RIGHT: Rightmost characters of a longstring . . . . . . . . . .
$LSTR_SET_USERBUFFER: Set user buffer to longstring value . . . .
$LSTR_SUBSTR: Substring of a longstring . . . . . . . . . . . . . . .
$LSTR_SUBWORD: Substring of a longstring using word counts . . .
$LSTR_TRANSLATE: Translate longstring . . . . . . . . . . . . . . .
$LSTR_UNBLANK: Remove extraneous blanks from longstring . . . .
$LSTR_WINDEX: Return the position of a word within a long string . .
$LSTR_WORD: Return a word from a long string . . . . . . . . . . . .
$LSTR_WORDS: Return the number of words in a long string . . . . .
$LSTR_X2C: Convert from hexadecimal to byte string . . . . . . . . .
$PARSE: Part of string preceding character in delimiter set . . . . . .
$PARSEX: Part of string following character in delimiter set . . . . . .
$PRCLEX: $list of information about procedures in file . . . . . . . . .
$PRCLEXG: $list of information about procedures in group or file . . .
$PRIORTY: Change a user's priority . . . . . . . . . . . . . . . . . .
$PROC_LIST: $list of information about procedures in file . . . . . . .
$PROC_LISTG: $list of information about procedures in group or file .
$PROC_TOUCH: Change a procedure's last-update date and user . .
$PROCCLS: Close procedure before reaching end . . . . . . . . . .
$PROCDAT: Add lines from procedure to $list . . . . . . . . . . . . .
$PROCGET: Next line of procedure . . . . . . . . . . . . . . . . . .
$PROCLOC: Locate any of set of strings in procedure . . . . . . . . .
$PROCOPN: Open procedure for $PROCDAT, $PROCGET,
$PROCLOC . . . . . . . . . . . . . . . . . . . . . . . . . .
$RANDOM: Get next random number . . . . . . . . . . . . . . . . .
$RANDOM_SEED: Build seed specifying series of $RANDOM results
$REGEXMATCH: Whether string matches regex . . . . . . . . . . . .
$REGEXREPLACE: Replace matching strings . . . . . . . . . . . . .
$RESETN: Reset or view M204 parameter . . . . . . . . . . . . . . .
$SCRHIDE: Hide lines in SCREEN . . . . . . . . . . . . . . . . . . .
$SCRSIZE: Change size of field on SCREEN . . . . . . . . . . . . .
$SCRWIDE: Allow SCREEN to accept fields wider than 79 . . . . . .
$SESSION, $SESSION_ID, $SESSION_OWNER and
$SESSION_TIMEOUT . . . . . . . . . . . . . . . . . . . . .
$SESSION_CLOSE: Close an open session . . . . . . . . . . . . . .
$SESSION_CREATE: Create a new session . . . . . . . . . . . . . .
$SESSION_DELETE: Delete a session . . . . . . . . . . . . . . . .
. . .
272
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
273
276
278
280
282
284
286
287
288
290
292
293
295
297
301
303
305
307
308
310
311
313
315
317
319
321
323
325
326
328
329
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
331
333
335
336
339
344
347
349
350
.
.
.
.
.
.
.
.
.
.
.
.
351
352
354
356
——————————————————————————————————————————
ix
——————————————————————————————————————————
Contents
——————————————————————————————————————————
$SESSION_LIST: Get list of sessions . . . . . . . . . . . . . . .
$SESSION_OPEN: Open a session . . . . . . . . . . . . . . . .
$SETG_SUBSYS: Set subsystem-wide global . . . . . . . . . . .
$SETG_SUBSYS_LIST: Get list of subsystem-wide globals . . . .
$SETG_SYS: Set system-wide global . . . . . . . . . . . . . . .
$SETG_SYS_LIST: Get list of system-wide globals . . . . . . . . .
$SETSTAT: Set local system statistic . . . . . . . . . . . . . . . .
$SIR_DATE: Get current datetime . . . . . . . . . . . . . . . . .
$SIR_DATEFMT: Validate datetime format . . . . . . . . . . . . .
$SIR_DATEN: Current date and time as number of seconds/300 .
$SIR_DATEND: Current date as number of days . . . . . . . . . .
$SIR_DATENM: Current date and time as number of milliseconds
$SIR_DATENS: Current date and time as number of seconds . . .
$SIR_DATE2N: Convert datetime string to number of seconds/300
$SIR_DATE2ND: Convert datetime string to number of days . . .
$SIR_DATE2NM: Convert datetime string to number of milliseconds
$SIR_DATE2NS: Convert datetime string to number of seconds . .
$SIR_DATExxx: Sir2000 User Language Tools $functions . . . . .
$SIR_ND2DATE: Convert datetime number of days to string . . .
$SIR_NM2DATE: Convert datetime number of milliseconds to string
$SIR_NS2DATE: Convert datetime number of seconds to string . .
$SIR_N2DATE: Convert datetime number of seconds/300 to string
$SIR_WILD: Test string against a wildcard string . . . . . . . . . .
$SIRFIELDxxx: Sir2000 Field Migration Facility $functions . . . . .
$SIRJGET: Place audit trail data on $list . . . . . . . . . . . . . .
$SIRMSG: Line of current $SIRMSGP procedure . . . . . . . . .
$SIRMSGP: Load procedure for retrieval via $SIRMSG . . . . . .
$SIRPARM: Set user-specific value, controlling Sirius products . .
$SIRPROD: Determine availability of Sirius product or capability .
$SIRSITE: Current Sirius customer site ID . . . . . . . . . . . . .
$SIRTIME: Current time as YYDDDHHMISSXX . . . . . . . . . .
$SIRVER: Current version number of Sirius product . . . . . . . .
$SIRWARN: Send warning or message to user(s) . . . . . . . . .
$SOCK_xxx: Janus Sockets $functions . . . . . . . . . . . . . . .
$SRV_xxx: Janus Open Server $functions . . . . . . . . . . . . .
$SSSTAT: Retrieve subsystem's statistics into string . . . . . . .
$SSSTATL: Retrieve statistics for set of subsystems into $list . . .
$STATD: Calculate differences and rates for statistics strings . . .
$STATLD: Calculate differences and rates for statistics $lists . . .
$STR: Treat a longstring as string . . . . . . . . . . . . . . . . . .
$STRAND: Bit-wise AND two strings . . . . . . . . . . . . . . . .
$STROR: Bit-wise OR two strings . . . . . . . . . . . . . . . . . .
$STRXOR: Bit-wise exclusive OR two strings . . . . . . . . . . . .
$SUBCNT: Count occurrences of one string in another . . . . . .
$SUBERS: Remove occurrence of one string from another . . . .
$SUBINS: Insert string inside another string . . . . . . . . . . . .
$SUBREP: Replace occurrences of string . . . . . . . . . . . . .
$SYSTAT: Retrieve system statistics into string . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
358
360
362
366
369
372
374
375
376
377
378
379
380
381
383
385
387
389
390
392
394
396
398
399
400
406
407
409
412
414
415
416
417
419
420
421
423
425
427
430
431
433
435
437
438
440
441
443
——————————————————————————————————————————
x
——————————————————————————————————————————
Contents
——————————————————————————————————————————
$TABLEC: Information provided by TABLEC command . . . . . . . . .
$TERMID: Terminal ID of current user thread . . . . . . . . . . . . . .
$TKSTAT: Retrieve task's statistics into string . . . . . . . . . . . . . .
$TKSTATL: Retrieve statistics for all tasks into $list . . . . . . . . . . .
$TSOATT: Attach program in user's TSO address space . . . . . . . .
$TSOCALL: Call program in user's TSO address space . . . . . . . . .
$TSOCAN: Cancel program invoked via $TSOATT . . . . . . . . . . .
$TSOCMD: Invoke command in user's TSO address space . . . . . . .
$TSOEXEC: Invoke CLIST in user's TSO address space . . . . . . . .
$TSOEXIT: Terminate TSO full screen interface session, stack command
$TSOID: TSO userid user's thread . . . . . . . . . . . . . . . . . . . .
$TSOSTAT: Status of program invoked via $TSOATT . . . . . . . . . .
$TSOWAIT: Wait for program invoked via $TSOATT to complete . . . .
$UNBIND and $UNBINDW: Unbind resource previously bound via
$BIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
$UNSPACE: Normalize spaces and quotes . . . . . . . . . . . . . . . .
$USEASA: Prevent carriage control in USE output . . . . . . . . . . . .
$USSTAT: Retrieve user's statistics into string . . . . . . . . . . . . . .
$USSTATL: Retrieve statistics for set of users into $list . . . . . . . . .
$WAKEUP: Pause user until specified time . . . . . . . . . . . . . . . .
$WEBxxx: Janus Web Server $functions . . . . . . . . . . . . . . . . .
$WINDEX: Word number of first occurrence of word in phrase . . . . . .
$XMLxxx: Janus SOAP $functions . . . . . . . . . . . . . . . . . . . .
$X2D: Convert hex string to integer . . . . . . . . . . . . . . . . . . . .
Chapter 8:
User Language Statements for Sirius Functions
Assert statement . . . . . . . . . . . . . .
Html or Text statement . . . . . . . . . . .
Options: Html or Text block options . .
Data, Print, Audit, or Trace . . . .
Ent_print . . . . . . . . . . . . .
LiteralsToTemp . . . . . . . . . .
Nocom or Nocomments . . . . .
Nocont or Nocontinuations . . . .
Nodum or Nodummy . . . . . . .
Noell or Noellipses . . . . . . . .
Noexpr or Noexpressions . . . .
Raw . . . . . . . . . . . . . . . .
Noend . . . . . . . . . . . . . .
Exprs or Exprstart . . . . . . . .
Expre or Exprend . . . . . . . . .
End . . . . . . . . . . . . . . . .
To %stringlist | Audit | Print | Trace
Body: Html or Text block body . . . .
block_end_line: Html or Text block end
Printing of expression results . . . . .
Character entity substitution . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. .
. .
. .
445
447
448
450
452
454
456
458
460
462
463
464
466
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
468
470
473
474
476
479
481
482
483
484
. . . . . . .
485
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
485
488
491
491
492
493
493
494
494
494
494
494
495
495
496
496
496
498
498
499
499
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
——————————————————————————————————————————
xi
——————————————————————————————————————————
Contents
——————————————————————————————————————————
The {~} directive . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loop Next statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 9:
Chapter 10:
TSO $Functions
Chapter 11:
. . . . . . . . . . . . .
503
. . . . . . . . . . . . . . . . . . . . . . . . .
505
Mathematical $Functions . . . . . . . . . . . . . . . . . . . .
507
$ABS: Absolute value . . . . . . . . . . . . . . .
$ARCCOS: Inverse cosine . . . . . . . . . . . .
$ARCSIN: Inverse sine . . . . . . . . . . . . . .
$ARCTAN: Inverse tangent . . . . . . . . . . . .
$ARCTAN2: Inverse tangent of ratio of arguments
$COS: Cosine . . . . . . . . . . . . . . . . . . .
$COSH: Hyperbolic cosine . . . . . . . . . . . .
$COTAN: Cotangent . . . . . . . . . . . . . . .
$ERF: Error function . . . . . . . . . . . . . . .
$ERFC: Error function complement . . . . . . . .
$EXP: Exponential function . . . . . . . . . . . .
$EXP2: Two's exponent function . . . . . . . . .
$EXP10: Ten's exponent function . . . . . . . . .
$GAMMA: Gamma function . . . . . . . . . . . .
$IXPI: Integer base raised to integer exponent . .
$LGAMMA: Lgamma function . . . . . . . . . . .
$LOG: Log function . . . . . . . . . . . . . . . .
$LOG2: Log base 2 function . . . . . . . . . . .
$LOG10: Log base 10 function . . . . . . . . . .
$MAX: Return maximum value . . . . . . . . . .
$MIN: Return minimum value . . . . . . . . . . .
$PI: Value of pi . . . . . . . . . . . . . . . . . .
$RXPI: Real base raised to integer exponent . . .
$RXPR: Real base raised to real exponent . . . .
$SIN: Sine . . . . . . . . . . . . . . . . . . . . .
$SINH: Hyperbolic sine . . . . . . . . . . . . . .
$SQRT: Square root . . . . . . . . . . . . . . .
$TAN: Tangent . . . . . . . . . . . . . . . . . .
$TANH: Hyperbolic tangent . . . . . . . . . . . .
Chapter 12:
499
500
500
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
508
508
508
508
508
508
509
509
509
509
509
509
510
510
510
510
511
511
511
511
512
512
512
512
513
513
513
513
513
Regex Processing . . . . . . . . . . . . . . . . . . . . . . . .
515
Regex rules . . . . . . . . . . . . . . . . .
Expression constituents . . . . . . . . .
Features that affect the whole expression
Common regex options . . . . . . . . . . .
XML Schema mode . . . . . . . . . . . . .
User Language programming considerations
. . .
. . .
. .
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
516
516
521
522
523
525
——————————————————————————————————————————
xii
——————————————————————————————————————————
Contents
——————————————————————————————————————————
Chapter 13:
Datetime Processing Considerations
. . . . . . . . . . . . .
527
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
529
533
534
534
535
536
537
541
542
542
543
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
545
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
547
Datetime Formats . . . . . . . . . . . . . . . .
Valid Datetimes . . . . . . . . . . . . . . . . .
Processing Dates With Two-Digit Year Values .
CENTSPAN . . . . . . . . . . . . . . . . .
SPANSIZE . . . . . . . . . . . . . . . . .
Strict and non-strict format matching . . . . . .
Datetime and format examples . . . . . . . . .
Datetime Error Handling . . . . . . . . . . . . .
$SIR_DATExxx Functions CENTSPAN Argument
Other $functions using date values . . . . . . .
Benefits of Sirius datetime processing . . . . . .
Chapter 14:
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
——————————————————————————————————————————
xiii
——————————————————————————————————————————
Contents
——————————————————————————————————————————
——————————————————————————————————————————
xiv
——————————————————————————————————————————
Summary of Changes
——————————————————————————————————————————
——————
Summary of Changes
This section describes significant changes to the documentation. Usually, these
changes correspond to enhancements made to the underlying product, although at least
one revision below contains mostly changes to the format and structure used in the
documentation. Note that new product/capability numbers for $SIRPROD are not shown
in this section, but rather are listed at the end of “$SIRPROD: Determine availability of
Sirius product or capability” on page 412.
When a version of the Sirius Functions is no longer supported, references to that version
will be removed from this manual.
The following changes correspond to changes in the Sirius Functions since version 7.2:
●
FUNCOPTS parameter bit settings affect allow greater access to $PRIORTY use.
See “$PRIORTY: Change a user's priority” on page 317.
●
Support is added for the \b and \B multi-character escape sequences. See “Escape
sequences” on page 517.
●
NOURGMSG is an optional argument added to $Wakeup (“$WAKEUP: Pause user
until specified time” on page 479) that prevents a paused user's waiting time from
being cancelled by BROADCAST URGENT.
●
$Lstr_Word now can return a result longer than 255 bytes. This was added in
version 7.2 (and version 7.1) as maintenance.
——————————————————————————————————————————
xv
——————————————————————————————————————————
Summary of Changes
——————————————————————————————————————————
●
The options arguments of $Field_Image, $Field_List, and $Field_ListI may now be
in any combination of uppercase and lowercase letters.
●
$ListFindI_Up, a variation of $ListFindI, is added (see “$LISTFINDI and
$LISTFINDI_UP: Find image item in $list” on page 196).
●
Enhancements to support for regex methods (see “$REGEXMATCH” on page 336,
“$REGEXREPLACE” on page 339, and “Regex rules” on page 516):
▪
“Lazy,” or “non-greedy,” matching (the lazy quantifiers like *?, +?, ?? etc.) is
now supported.
▪
As in Perl, \w and \W multi-character escape sequences are supported
(allowed outside of character classes and replacement strings).
▪
The handling of square bracket characters ([, ]) is now supported in Sirius
regex as it is in Perl, except when Sirius $functions use the Options='C'
argument (XML Schema mode).
▪
Multi-character escape sequences (for example, \s, \c) are now legal within a
character class — but not as either side in a range.
▪
A character class may now contain an unescaped hyphen (-) as a simple
character, if it occurs as the first character (or the second, if the first is ˆ) or as
the last character. An escaped hyphen (\-) remains legal.
▪
The PDL space requirement recommended when using Sirius regex $functions
is reduced from a minimum LPDLST setting of 8000 to one of 3000.
▪
For those $functions that support the XML Schema mode option,
“charClassSubtraction” is now supported in that mode only. You can exclude a
subset of characters from the characters already designated to be in the class.
▪
The Status argument return value for a regex expression compilation error is
changed from -1 to -1nnn, where the last three digits indicate the 1-based
position of the character where the error occurred.
——————————————————————————————————————————
xvi
——————————————————————————————————————————
——————————————————————————————————————————
●
Updated versions of the User Language mathematical functions are available
(“Mathematical $Functions” on page 507).
●
New regular expression functions are now available:
▪
▪
●
“$REGEXMATCH: Whether string matches regex” on page 336
“$REGEXREPLACE: Replace matching strings” on page 339
$BIND has a new wait time argument (“$BIND: Fast, easy synchronization of
system wide resource” on page 49).
●
The following functions are now callable (“CALLing Sirius Mods functions” on page
32):
▪
▪
▪
▪
▪
▪
▪
▪
▪
$errSet
$fakeEnt
$procCls
$procOpn
$sirMsgP
$scrWide
$scrHide
$scrSize
$wakeUp
●
Improvements to the “deflate” compression algorithm used by $GZIP processing
(“$GZIP” on page 139) provide significantly better compression in Sirius Mods
version 6.8, without any noticeable increase in CPU requirements. Compression is
likely to improve from 5 to 15 percent, especially for streams greater than 6184
bytes, and regardless of whether fixed-code or dynamic-code compression is used.
Additional improvements to dynamic compression may yield an additional 2 to 4
percent.
●
New ASCII to EBCDIC and EBCDIC to ASCII translation functions are now available
(“$A2E: Translate ASCII to EBCDIC” on page 33 and “$E2A: Translate EBCDIC to
ASCII” on page 89).
●
New longstring base 64 encoding and decoding functions are now available
(“$LSTR_BASE64_ENCODE: Convert byte string to base 64” on page 269 and
“$LSTR_BASE64_DECODE: Convert from base 64 to byte string” on page 267).
——————————————————————————————————————————
xvii
——————————————————————————————————————————
Summary of Changes
——————————————————————————————————————————
●
New longstring hexadecimal encoding and decoding functions are now available
(“$LSTR_C2X: Convert byte string to hexadecimal” on page 270 and “$LSTR_X2C:
Convert from hexadecimal to byte string” on page 308).
●
Methods to get an sdaemon's parent and master user number are now available
(“$DAEMONPARENTNUMBER: Get user number of parent thread” on page 76 and
“$DAEMONMASTERNUMBER: Get user number of master thread” on page 75).
●
Sdaemons running on behalf of other threads, via the $comm functions or Janus
SOAP Daemon objects, no longer suffer most record locking conflicts with other
threads in the same thread family (“Sdaemons” on page 5).
●
$PROC_TOUCH is introduced (see “$PROC_TOUCH: Change a procedure's lastupdate date and user” on page 323).
●
New longstring $functions for working with Large Object (LOB) data are introduced:
▪
▪
▪
“$LSTR_ADD_USERBUFFER: Add longstring to user buffer” on page 266
“$LSTR_GET_USERBUFFER: Get user buffer contents to a longstring” on
page 272
“$LSTR_SET_USERBUFFER: Set user buffer to longstring value” on page 292
●
The new $GZIP and $GUNZIP functions allow compression and decompression of
longstrings (“$GZIP: Compress a longstring with GZIP” on page 139 and
“$GUNZIP: Decompress a longstring with GUNZIP” on page 137).
●
New time limit argument on $FUNLOAD, and FUNPARM parameter controls
whether $FUNLOAD allowed in updating transactions (“$FUNLOAD: Fast/Unload
records in Model 204 list or found set” on page 125).
●
$SIRJGET (“$SIRJGET: Place audit trail data on $list” on page 400) formatting is
modified slightly: long user audit entries that had been split into a US line and one
or more XX lines are now displayed as a single US line. Also, $SIRJGET retrievals
no longer strip all blanks at the start of an audited line.
●
Messages are now sent to the Model 204 journal/audit trail on every Fast/Unload
request made and completed by the Fast/Unload User Language Interface. See
“$FUNLOAD: Fast/Unload records in Model 204 list or found set” on page 125.
——————————————————————————————————————————
xviii
——————————————————————————————————————————
——————————————————————————————————————————
●
The $list item length limit of 6124 has been lifted. See “$LISTADD_LSTR: Add
longstring as new $list item” on page 182, “$LISTINF_LSTR: Retrieve $list item into
longstring” on page 208, “$LISTINS_LSTR: Insert string into a $list” on page 214,
and “$LISTREP_LSTR: Replace a $list item with a longstring” on page 245.
●
New comparison operator argument on $LISTFINDI and $LISTFINDI_SUB. See
“$LISTFINDI and $LISTFINDI_UP: Find image item in $list” on page 196 and
“$LISTFINDI_SUB: Build $list subset based on image item” on page 199.
●
New $LSTR_TRANSLATE function. See “$LSTR_TRANSLATE: Translate
longstring” on page 297.
●
Ability to invoke many of the Sirius $functions using a User Language CALL
statement instead of assigning the function result to a %variable. See “CALLing
Sirius Mods functions” on page 32.
●
Changed authorization of the following $functions:
▪ “$CLOSE: Close file or group in User Language request” on page 60
▪ “$LISTCMP: Compare two $lists and produce $list describing differences” on
page 190
▪ “$PRCLEX: $list of information about procedures in file” on page 313
▪ “$PRCLEXG: $list of information about procedures in group or file” on page
315
▪ “$PROC_LIST: $list of information about procedures in file” on page 319
▪ “$PROC_LISTG: $list of information about procedures in group or file” on page
321
▪ “$STATD: Calculate differences and rates for statistics strings” on page 425
▪ “$STATLD: Calculate differences and rates for statistics $lists” on page 427
●
New compression $functions $DEFLATE and $INFLATE allow compression and
decompression of long strings using the "deflate" algorithm described by RFC 1951
(“$DEFLATE: Compress a longstring with Deflate” on page 78 and “$INFLATE:
Decompress a longstring with inflate” on page 148).
——————————————————————————————————————————
xix
——————————————————————————————————————————
Summary of Changes
——————————————————————————————————————————
●
$LIST_CAPTURE now ignores the Model 204 OUTCCC and OUTMRL parameter
settings and no longer wraps a long print line into multiple $list items. The
Model 204 LOBUFF parameter setting is still respected for line truncation
(“$LIST_CAPTURE: Capture print data to $list” on page 156).
●
Since versions 5.3 and older of Sirius Mods are not supported, any references to
those versions have been removed.
●
Fieldname prefix and null value argument now available for $FIELD_IMAGE and
$FIELD_LISTI (“$FIELD_IMAGE: Return field values into an image” on page 101
and “$FIELD_LISTI: Return field values into a $list mapped to an image” on page
108).
●
$Lists can be passed as input to ECF programs (“$lists and ECF” on page 8).
●
“$LIST_ADD_ORDERED: Add an item to an ordered $list” on page 150,
“$LIST_ADD_UNIQUE_ORDERED: Conditionally add an item to an ordered $list”
on page 154 and “$LIST_ADD_UNIQUE: Conditionally add an item to a $list” on
page 152.
●
New session $functions (“Sessions” on page 25, “$SESSION, $SESSION_ID,
$SESSION_OWNER and $SESSION_TIMEOUT” on page 351,
“$SESSION_CREATE: Create a new session” on page 354, “$SESSION_OPEN:
Open a session” on page 360, “$SESSION_CLOSE: Close an open session” on
page 352, “$SESSION_DELETE: Delete a session” on page 356 and
“$SESSION_LIST: Get list of sessions” on page 358).
●
Session $list functions (“$LIST_GLOBAL and $LIST_SESSION: Access/create
global/session $list” on page 169, “$LIST_GLOBAL_DEL and
$LIST_SESSION_DEL: Delete global/session $lists” on page 173 and
“$LIST_GLOBAL_LIST and $LIST_SESSION_LIST: List global/session $lists” on
page 175).
●
Global and session longstring functions (“$LSTR_GLOBAL and $LSTR_SESSION:
Bind to global/session longstring” on page 273, “$LSTR_GLOBAL_GET and
$LSTR_SESSION_GET” on page 278 and “$LSTR_GLOBAL_DEL and
$LSTR_SESSION_DEL” on page 276).
●
“$SIR_WILD: Test string against a wildcard string” on page 398.
●
Output line width enhancements for $COMMxx functions (“$COMMAND: Execute
Model 204 command on sdaemon, results to image” on page 63, “$COMMBG:
——————————————————————————————————————————
xx
——————————————————————————————————————————
——————————————————————————————————————————
Execute Model 204 commands on sdaemon” on page 66 and “$COMMNDL:
Execute Model 204 command on sdaemon, results to $list” on page 69).
●
“$LSTR_GET_IMAGE and $LSTR_SET_IMAGE: Longstring to/from image” on
page 271.
●
Maximum $list item length increased to 6124 bytes.
●
Maximum $list size increased to about 3.5 gigabytes.
●
LONGSTRING support and new $STR, $LSTR, $LSTR_LEN, $LSTR_SUBSTR,
$LSTR_RIGHT, $LSTR_LEFT, $LSTR_INDEX, $LSTR_UNBLANK,
$LISTINF_LSTR, $LISTADD_LSTR, $LISTINS_LSTR, $LISTREP_LSTR and
$LIST_MAXIL functions. See “Longstrings” on page 11, “$STR: Treat a longstring
as string” on page 430, “$LSTR: Treat a string as longstring” on page 265,
“$LSTR_LEN: Length of a longstring” on page 286, “$LSTR_RIGHT: Rightmost
characters of a longstring” on page 290 “$LSTR_LEFT: Leftmost characters of a
longstring” on page 284, “$LSTR_INDEX: Find a string inside a longstring” on page
282, “$LSTR_UNBLANK: Remove extraneous blanks from longstring” on page 301
“$LISTINF_LSTR: Retrieve $list item into longstring” on page 208,
“$LISTADD_LSTR: Add longstring as new $list item” on page 182,
“$LISTINS_LSTR: Insert string into a $list” on page 214 “$LISTREP_LSTR:
Replace a $list item with a longstring” on page 245 and “$LIST_MAXIL: Return
maximum $list item length” on page 177.
●
New $ENT, $ENT_TAB and $ENT_PRINT functions. See “$ENT: Do character
entity substitution” on page 93, “$ENT_TAB: retrieve/modify character entity
substitution table” on page 97 and “$ENT_PRINT: Set automatic character entity
substitution” on page 95.
●
New $FIELD_LISTI and $FIELD_IMAGE functions. See “$FIELD_LISTI: Return
field values into a $list mapped to an image” on page 108 and “$FIELD_IMAGE:
Return field values into an image” on page 101.
●
New $LISTNEWI and $LISTNEWAI functions. See “$LISTNEWI: Create empty
$list associated with image” on page 234 and “$LISTNEWAI: Create array of empty
$lists associated with image” on page 232.
●
New $LIST_PRINT function. See “$LIST_PRINT: Display contents of a $list” on
page 178.
——————————————————————————————————————————
xxi
——————————————————————————————————————————
Summary of Changes
——————————————————————————————————————————
●
New SEQ parameter for $SIRJGET. See “$SIRJGET: Place audit trail data on
$list” on page 400.
●
New $STRAND, $STROR and $STRXOR functions. See “$STRAND: Bit-wise AND
two strings” on page 431, “$STROR: Bit-wise OR two strings” on page 433 and
“$STRXOR: Bit-wise exclusive OR two strings” on page 435.
●
$COMMxx available with Janus Sockets and Janus Web Server.
●
$FUNLOAD operates correctly with non-0 FNVMASK parameter.
●
$SIRPROD may return a non-zero number different from 1 if the product or
capability is available.
●
New $UNBINDW function.
●
New $UNSPACE function.
●
New $BASE64_DECODE and $BASE64_ENCODE functions.
●
New $BIND_LIST function.
●
New $C2D and $D2C functions.
●
New $FIELD_LIST function.
●
New $LIST_CAPTURE function.
●
New $RESETN function.
●
New HTML/TEXT block.
——————————————————————————————————————————
xxii
——————————————————————————————————————————
——————————————————————————————————————————
●
$LISTCPY, $LISTSORT, $LISTSUB, and $LISTSRT now set the output $list image
association to be the same as the input $list image association.
●
$LISTSORT and $LISTSRT can now do non-character format sorts for fixed point,
floating point, packed decimal and zoned decimal formats.
●
New $IMGINF and $IMGOVL functions.
●
New $LISTADJ function.
●
New $LISTCHK function.
●
New $LISTFINDI function.
●
New $LISTFINDI_SUB function.
●
New $LISTIMG_COPY function.
●
New $LISTOVLI function.
●
New $LISTREP and $LISTREPI functions.
●
New $DELG_SUBSYS and $DELG_SYS functions.
●
New $LISTNEWA function.
●
New $SETG_SUBSYS and $SETG_SYS functions.
●
New $SETG_SUBSYS_LIST and $SETG_SYS_LIST functions.
●
New parameters 'DUMMYSYS' and 'GETGSYS' for the $SIRPARM function.
——————————————————————————————————————————
xxiii
——————————————————————————————————————————
Summary of Changes
——————————————————————————————————————————
Versions of Sirius Mods older than this are no longer supported.
——————————————————————————————————————————
xxiv
——————————————————————————————————————————
Introduction
——————————————————————————————————————————
——————
CHAPTER 1
Introduction
The Sirius Functions is a collection of $functions for User Language. These functions
are distributed as part of the Sirius Mods, which is a group of products link-edited with
your Model 204 ONLINE and BATCH204 load modules to enhance performance and
add function.
Many of the Sirius Functions are used internally in the UL/SPF products of Sirius
Software (products such as SirMon, SirPro, and SirScan). In addition, many of these
$functions can be used in your own User Language applications. The Sirius Functions
can be purchased for your use directly as a product from Sirius Software, Inc., and as
such, the term Sirius Functions is the proper name of that product. In addition, subsets
of the $functions are available for your own User Language applications when you
purchase other Sirius Mods products, such as Fast/Unload User Language Interface and
Janus Web Server.
Finally, there are some $functions that are part of some Sirius Mods products and that
are only available when you have purchased those products. Again, Fast/Unload User
Language Interface and Janus Web Server are examples. Most of these $functions are
not described in this manual, but rather are described in the specific product manual.
For example, the $WEBxxx functions are described in the Janus Web Server
Reference Manual. As a notable exception, the Fast/Unload User Language Interface
functions ($FUNxxx) are described in this manual, since the Fast/Unload product family
has no other Sirius Mods component.
For each of the $functions described in this manual, there is a list of Sirius Software
products, any of which authorize the use of the $function in your own User Language
applications. When the term Sirius Functions is used in one of these lists, it refers to the
product by that name which can be purchased from Sirius Software, Inc.. In other
contexts, the term Sirius Functions refers either to the set of $functions documented in
this manual, or to all $functions delivered by Sirius Software Inc. as part of the Sirius
Mods.
1.1
Versions, Compatibility, and Installation
Sirius Software is committed to providing backward compatibility in all releases of its
$functions. While new functionality may be added to the Sirius Functions in future
releases, no current functionality will be removed or changed. This ensures that an
application written using the current release of the Sirius Functions, will not have to be
changed after installing a later release of the Sirius Functions.
——————————————————————————————————————————
1
——————————————————————————————————————————
Introduction
——————————————————————————————————————————
Backward compatibility is especially important when you are using any Sirius Software
product which utilizes the Sirius Functions. Whenever you receive a product tape for
one of these products, you will receive the latest version of the Sirius Functions. You
should always install this latest version. If you do so, backward compatibility will ensure
that any other Sirius Software products that you have installed will continue to operate
correctly.
The Sirius Functions are delivered as object code enhancements to Model 204 as part
the Sirius Mods which also includes products such as Fast/Backup and Fast/Reload that
do not require the Sirius Functions. To install Sirius Functions the Sirius Mods must be
installed. When the Sirius Mods are installed, all other products owned by the installing
site that are part of the Sirius Mods will also be (re)installed.
Since the Sirius Functions is part of the Sirius Mods the version number of the Sirius
Functions is considered to be the version of the Sirius Mods in which it is contained.
The current document describing the Sirius Functions was first available in version 4.6 of
the Sirius Mods and that version of Sirius Functions was called version 4.6. This
document, the Sirius Functions Reference Manual, assumes that a site is running
Sirius Mods version 4.6 or later. Any documented feature or facility that requires a later
version of the Sirius Mods will be clearly marked to indicate this. For example, a
$function that is only available in versions 6.2 and later of the Sirius Mods will have a
sentence such as “This $function is only available in version 6.2 or later of the Sirius
Mods” in its documentation. If a feature or $function is not indicated as requiring any
specific version of the Sirius Mods, it can be assumed that it is available in all versions of
the Sirius Functions since version 4.6.
1.2
Related manuals
Since the Sirius Functions requires the installation of the Sirius Mods, the person
responsible for the installation of Sirius Functions should refer to the Sirius Mods
Installation Guide. The Sirius Messages Manual contains documentation on Sirius
Mods error messages and so might be useful to application programmers as well as
installers. As noted in “Introduction” on page 1, several Sirius Software products contain
$functions which are only documented in the product-specific manual. Pointers to such
functions are contained as brief sections in the chapter “Description of $Functions” on
page 31, with section titles containing the string xxx.
If you are using the Fast/Unload User Language Interface, you should refer to the
Fast/Unload Reference Manual for information about setting up the Fast/Unload User
Language Interface environment.
——————————————————————————————————————————
2
——————————————————————————————————————————
System requirements
——————————————————————————————————————————
1.3
System requirements
The current release of Sirius Functions requires the following components to run:
●
Mainframe operating systems:
MVS/SP Version 1.3 or later (including MVS/XA and MVS/ESA) or
CMS (releases currently supported by IBM) running under
VM/ESA or
z/VM
●
Model 204 Version 5.1 or later
——————————————————————————————————————————
3
——————————————————————————————————————————
Introduction
——————————————————————————————————————————
——————————————————————————————————————————
4
——————————————————————————————————————————
Sdaemons
——————————————————————————————————————————
——————
CHAPTER 2
Sdaemons
Many Sirius Functions interact with a facility provided with the Sirius Mods called an
sdaemon. Sdaemons are threads which do work on behalf of another user. They
accomplish this by automatically logging onto a requesting user's ID (under the covers),
then issuing standard Model 204 commands as if the user was issuing the commands
himself. This makes it possible to have Model 204 commands executed on behalf of a
user while that user is running a User Language procedure.
Associated with sdaemons is the concept of family: Two threads are in the same family
if one is a synchronous child sdaemon of the other via a $COMM function or a Janus
SOAP Daemon object. In addition, all families with common threads are considered to
be a single family. So, if thread A is a synchronous parent of thread B, which is a
synchronous parent of thread C, threads A, B, and C are all considered part of the same
family. Furthermore, if in this example, thread B had two other synchronous children (via
Daemon objects), threads D and E, then threads A, B, C, D, and E would all be
considered part of the same family.
Before Sirius Mods 6.8, threads in a family could get record locking conflicts with each
other. This greatly limited what could be done on sdaemon threads. As of Sirius Mods
6.8, the one condition under which two threads in the same family can still suffer a
record locking conflict is if they both try to update the same record, which would require
both threads to have an exclusive pending update lock on the record being updated.
This possible conflict is eliminated if the sdaemon is a Janus SOAP transactional
daemon (described in the Janus SOAP Reference Manual).
For more information on setting up sdaemons, see the Sirius Mods Installation Guide.
——————————————————————————————————————————
5
——————————————————————————————————————————
Sdaemons
——————————————————————————————————————————
——————————————————————————————————————————
6
——————————————————————————————————————————
$lists
——————————————————————————————————————————
——————
CHAPTER 3
$lists
Many Sirius $functions manipulate a data structure called a $list. A $list is a collection
of variable length strings stored in CCATEMP. Each item in a $list has an associated
item number and, as of Sirius Mods version 6.6, no length limit (previously, as of version
6.2, $list items had a length limit of 6124 bytes, and before that, 4096 bytes).
$lists are always cleaned up (that is, their CCATEMP pages are released, hence they
can no longer be accessed) at request termination, except in the case of global $lists.
Global $lists are $lists that were saved with $LISTSAV or $LISTSAVE (and have not
been restored with $LISSTRST) or those that were created with $LIST_GLOBAL. All
non-global $lists, except those created with the NOREL attribute on $LISTNEW, are also
cleaned up with the execution of the RELEASE ALL RECORDS statement.
Every $list has associated with it an integer called a $list identifier. This $list identifier
is guaranteed to be greater than 0. Other than this, applications should not depend on
the actual values for $list identifiers, because Sirius Software reserves the right to
change these as needed.
Any function that creates a $list returns a $list identifier as its result. The following
functions create $lists:
$LISTCPY
$LIST_GLOBAL
$LISTNEW
$LISTNEWI
$LISTRST
$LISTSORT
$LISTSRT
$LISTSUB
$PRCLEX
$PRCLEXG
$PROC_LIST
$PROC_LISTG
Before Sirius Mods version 6.2, $lists had an internal limitation that allowed them to hold
approximately 4 megabytes of data. With Sirius Mods version 6.2 and later, this
limitation is lifted so it is possible to store up to 3 gigabytes of data on a single $list. An
attempt to store more data into a $list will return an error code identical to a CCATEMP
full condition, or it will result in request cancellation, depending on the setting of the
$SIRPARM LISTFC flag.
——————————————————————————————————————————
7
——————————————————————————————————————————
$lists
——————————————————————————————————————————
$lists provide several advantages over arrays:
●
Data is stored in CCATEMP, so less server space is used. You can also store
much more data in a $list than in an array.
●
You do not have to know the size of your $list ahead of time.
●
$list items are variable length, thus use only as much space as the data requires.
●
$functions are provided to sort, search, and subset $lists.
●
You can delete or insert items into a $list.
The one disadvantage of $lists relative to arrays is that they require disk buffer pool
access, hence they require a little more CPU to access than array elements. Also, for
$lists that haven't been accessed in a while, disk writes might be performed and then a
disk read might be required for each page that has been written out.
The data associated with a $list identifier can be assigned to a different $list identifier
with the $LISTMOVE function (“$LISTMOVE: Move a $list” on page 225).
3.1
$lists and ECF
Under Sirius Mods version 6.3 and later, a $list identifier can be passed to an ECF
program as in
EXTERNAL CALL COBPROG WITH $LIST inlist outlist
where
inlist
is the $list identifier to be passed to the ECF program as input.
outlist is the $list identifier to receive the data as modified by the ECF program. The
contents of this $list are replaced with the ECF program output. The length of
the $list items are made to match that of the input $list, and if the output $list is
the same identifier as the input $list, the output data simply replaces the original
input data. For PARMTYPE=INPUT ECF programs, the output $list is ignored.
The input $list is copied into the ECF parameter area before the ECF program is called.
The $list items are concatenated and there is no way to determine where one ends and
the next begins, so presumably the $list items would all have the same length, or some
$list items have the length or number of occurrences of a following set of $list items
(which can be used in the ECF program to determine the structure of the data). More
likely, the structure for passing data from a $list to an ECF program will be a $list where
all $list items have the same length. To facilitate use of such a structure, the $list ECF
interface automatically places a one word (four byte) binary number of occurrences
——————————————————————————————————————————
8
——————————————————————————————————————————
$lists and ECF
——————————————————————————————————————————
before the copied $list items in the ECF parameter area. This makes it possible, if the
ECF program is written in COBOL, to refer to the $list as a DEPENDING array where the
number of occurrences can vary at run-time. To refer to the $list, the COBOL program
would look something like this:
LINKAGE SECTION.
01 STUBB.
03 NUM-HARPOONS
03 HARPOON-INFO
PIC 9(9) BINARY
OCCURS 0 TO 25000 TIMES
DEPENDING ON NUM-HARPOONS.
...
PROCEDURE DIVISION USING STUBB.
If for some reason, this count is deemed undesirable in the linkage structure, it can be
suppressed via the NOCOUNT keyword in the EXTERNAL CALL statement as in
EXTERNAL CALL COBPROG WITH $LIST %LIST NOCOUNT
Multiple $lists and images can be passed in a single ECF call as in
EXTERNAL CALL COBPROG WITH $LIST %LIST, INIMAGE, $LIST %LIST2
——————————————————————————————————————————
9
——————————————————————————————————————————
$lists
——————————————————————————————————————————
——————————————————————————————————————————
10
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
——————
CHAPTER 4
Longstrings
The Longstring datatype was introduced in Sirius Mods version 6.2. Longstrings
appear as a native Model 204 datatype and are defined in the same way as other
variable datatypes:
%name
is longstring
Longstrings are largely interchangeable with String variables, with the exception that
Longstrings can have a length up to 2**31-1 bytes while String variables have a
maximum length of 255 bytes. The Variables Are statement and the VTYPE
parameter do not allow Longstring to be set as a default type, so all Longstring
variables must be explicitly declared as such. Longstring variables can be defined as
Common and as subroutine parameters, but there is currently no support for Static
longstring variables. Sirius Mods version 7.2 introduced support for the Initial clause for
longstrings.
Like other %variables, Longstrings cannot be declared as Global on their declarations.
However, as of Sirius Mods version 6.3, a Longstring %variable can be dynamically
bound to a global longstring with the $lstr_global function, and it can be dynamically
bound to a session global Longstring with the $lstr_session function (“$LSTR_GLOBAL
and $LSTR_SESSION: Bind to global/session longstring” on page 273).
The value of a global or session Longstring can also be retrieved with $lstr_global_get
and $lstr_session_get, and it can be updated with $lstr_global_set and
$lstr_session_set.
Longstrings can also be declared as arrays:
%heaps
is longstring array(10)
The Longstring datatype is not supported inside images. However, Sirius Mods version
7.2 introduced support for image items with length greater than 255:
image foo
bar
is string len 300
end image
While such image items can't have arbitrary lengths up to 2**31-1 like other longstring
variables, they exhibit the same behavior as other longstring variables in request
cancellation in the case of truncation and in upgrading With operations to longstring With
operations.
——————————————————————————————————————————
11
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
While it might be tempting to redefine many or all String Len 255 variables as
Longstring, there are a few subtle issues discussed in this chapter that might result in
problems should this be done. This is not to say that many such variables shouldn't be
converted to Longstring, but it might not be as simple as a one-line editing change.
4.1
Truncation
One key difference between Longstrings and regular Strings is the default behavior of
Longstring truncation: any truncation on assignment from a Longstring, Longstring
$function, or longstring With operation causes request cancellation. Two examples of
the application of this rule follow:
●
An assignment to a String variable from a Longstring results in request cancellation
if the value of the Longstring exceeds the declared String length. This cancellation
can happen even if the Longstring is less than 255 bytes long: If, say, variable
%short were defined as String Len 55, and a Longstring variable called %long
contained 60 bytes of data, an assignment like the following results in request
cancellation:
%short = %long
Yet, you can successfully use an intermediate assignment to a String Len 255
variable (called %medium in the following example) followed by the assignment of
that variable to %short:
%medium = %long
%short = %medium
As a result, the last five bytes of the value originally held in %long are silently
truncated and assigned to %short.
Of course, since regular Strings can never be longer than 255 bytes, any
assignment from a Longstring longer than 255 bytes to a regular String will result in
request cancellation. There are several ways around this “problem”, but the
simplest is to use the $str function (“$STR” on page 430) to silently truncate a
Longstring at 255 bytes or whatever is required for assignment to its target.
Effectively, the $str function tells Model 204 to treat the Longstring as it would a
regular String for truncation purposes, and the assignment succeeds:
%short = $str(%long)
●
Although the Longstring datatype is not supported inside images, you can assign
from a Longstring to an image item. However, assigning to an image item a
Longstring variable that has a value that ends with one or more of the target image
item's Pad character (which defaults to the space character) where the target image
item is not NoStrip results in an implicit truncation — the trailing pad characters are
——————————————————————————————————————————
12
——————————————————————————————————————————
Truncation
——————————————————————————————————————————
effectively removed. Since implicit truncation of a Longstring value on assignment is
not allowed, this results in request cancellation.
For example, the following request, which prints the result They're different,
shows the image item truncation for an assignment from a String:
b
%str
is string len 8
image foo
x
is string len 8
end image
prepare image foo
%str = 'Blank '
%foo:x = %str
if %foo:x ne %str then
print 'They''re different'
end if
end
If %str is declared as a Longstring above, however, the request is cancelled by a
Longstring truncation error. But if %str is declared as a Longstring, and if %foo:x
= %str is replaced by %foo:x = $str(%str), the request succeeds.
Using $str to correct for this Longstring truncation behavior is not always appropriate,
though. The use of $str might be viewed as a continuation of the dubious Model 204
programming practice of truncation by assignment, so it might be avoided or at least
used as a last result as a matter of policy. In fact, converting many String variables to
Longstring might be viewed as a way of detecting possible unintentional truncation in
existing applications, although there are some subtle issues one should be aware of
before embarking on such an enterprise.
For additional discussion of these truncation issues, see “Changing Longstring
truncation behavior” on page 19.
4.2
Longstrings in expressions
Like Strings, a Longstring variable can be used in User Language expressions, as
operands or as input to $functions.
User Language expressions can have embedded sub-expressions or simply
expressions. For example, in
%x = %a with %b with %c
——————————————————————————————————————————
13
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
the expression %a with %b is evaluated and an intermediate result is produced. This
intermediate result is then used as the first operand in a With operation with %c. With
no Longstrings involved, string expressions are silently truncated at 255 bytes, including
when producing an intermediate result. So, in the above example, if %a and %b were
each 200 bytes long, the intermediate result of %a with %b would be truncated at the
55th byte of %b and the with %c would simply drop %c since the intermediate result
that was the first operand of the with %c would already be 255 bytes long. In this
case, %x would end up containing all of %a, the first 55 bytes of %b and none of %c.
Fortunately, the results would be the same even if the expression were written
%x = %a with (%b with %c)
though it's worth working this out mentally to develop a good feel for how intermediate
expression results are processed in User Language.
In any case, the WITH operation behaves differently in the presence of Longstrings.
Specifically, if either operand of a With operation is a Longstring, the intermediate result
of the operation is also a Longstring. If, in the above example, %a was a Longstring and
%b and %c were regular Strings, the result of %a with %b would be a 400-byte
Longstring. When this 400-byte intermediate result Longstring is then concatenated
using the With operation on %c, the result will be a Longstring of length 400 plus the
length of %c. If the target of this expression, %x, was a regular String, this would cause
a request-cancelling truncation error.
In addition, if the target of a With operation is a Longstring, the With operation produces
a Longstring result, even if none of the operands are themselves Longstrings. For
example, if %x is a Longstring, and %a and %b are String Len 255, each with 200 bytes
of data:
%x = %a with %b
%x will be 400 bytes long, containing all of %a concatenated with all of %b. If either of
the operands of such a With clause is itself an expression, that expression is treated as
if its target were also a Longstring. For example, if in
%x = %a with (%b with %c)
%x is a Longstring, and %a, %b, and %c are String Len 255, each with 200 bytes of
data, %x will end up being 600 bytes long, containing all of %a concatenated with all of
%b with all of %c. This works the same way if the assignment is written as either of the
following:
%x = (%a with %b) with %c
%x = %a with %b with %c
Expression processing is the same for string literals, so if %x is a Longstring, and %a is
a String Len 255 with 255 bytes of data, the following assigns 258 bytes to %x:
%x = %a with '...'
——————————————————————————————————————————
14
——————————————————————————————————————————
Longstrings in expressions
——————————————————————————————————————————
Another way of looking at this is that in the presence of Longstring variables, whether as
the target or as one of the operands, all concatenation operations are “upgraded” to be
Longstring concatenations. One side-effect of this is that if an operand of a
concatenation is a Longstring, Longstring truncation rules apply to the ultimate target of
the assignment. For example, %long is a Longstring containing 'Testing...', and
%short is a String Len 12:
%short = (%long with '123') with '456'
The result is a request-cancelling truncation error, because the result of all the
concatenation operations is treated as a Longstring, albeit one with less than 255 bytes
of data. The cancellation can be avoided with the use of the $str function, as in the
following:
%short = $str((%long with '123') with '456')
Though, again, this is simply carrying on the dubious User Language programming
practice of truncation by assignment.
Note that the “upgrading” of With operations to longstring With operations is not induced
by a Longstring variable or expression inside a $function call. For example, %long is a
Longstring with 30 bytes of data, and %short is String Len 10:
%short = '*' with $substr(%long, 1, 20)
%short ends up containing an asterisk followed by the first 9 bytes of %long. The
assignment is made with silent truncation, because the result of a non-longstringcapable $function is always treated as a regular String for the purposes of assignment
and With processing.
In a context where a Longstring is automatically converted to a numeric datatype, a
request-cancelling truncation error occurs if the Longstring variable is longer than 255
bytes, even if most or all of these bytes are leading zeros. For example, %long is a
Longstring with 300 zeros followed by a one:
%a = %long + 1
The result is a request-cancelling truncation error. Fortunately, it's not likely that one is
likely to encounter numbers with greater than 255 digits in them. Longstring data used
in a numeric context will undergo the dubious automatic conversion of invalid numeric
data into a zero in the same way as String data.
——————————————————————————————————————————
15
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
Note: One case of automatic conversion to numeric where String and Longstring
behaviors differ is index loop control variables. For example, as of Sirius Mods version
6.7, the following loop is valid if %s is a String, but it results in a compilation error if %s is
a Longstring:
for %s from 1 to 2
print %s
end for
If the result of a numeric operation on a Longstring is then used in a With operation, the
With operation is not upgraded to a longstring With operation, because the intermediate
result of the numeric operation is not a Longstring but a numeric, which is then
automatically converted to a String intermediate result. For example, %long is a
Longstring containing 99 and %short is String Len 2:
%short = %long + 1
The result is not a request cancellation; instead, a M204.0552: VARIABLE TOO
SMALL FOR RESULT message is issued, and an asterisk ( * ) is assigned to %short.
Similarly, with these definitions and values
%short = (%long + 1) with '*'
results in a 10 being assigned to %short with no warnings, exactly the behavior if %long
were a String Len 255.
Comparison operations such as Eq, Lt, Le, >, <, etc. will perform longstring comparisons
if either of the operands is a Longstring, that is, comparison operations involving
Longstring operands behave pretty much “as expected.”
One important point to keep in mind is that Model 204's expression processing behavior
is not changed at all unless Longstring variables or $functions are used, and then only
changed in the statements where they are actually used. So there is no backward
compatibility problem in installing Sirius Mods version 6.2 or later, and the effect of any
use of Longstring variables or $functions will be limited to the statements that use them.
4.3
Longstrings and $functions
Longstrings can be used as inputs to $functions. As mentioned before, if a Longstring
expression is assigned to a regular String, a request-cancelling truncation error will
occur if the target String variable is not big enough to hold the source Longstring.
Request-cancelling truncation errors also occur if a Longstring that is longer than 255
bytes is passed to a non-Longstring-capable $function. For example,
print $substr(%long, 1, 50)
——————————————————————————————————————————
16
——————————————————————————————————————————
Longstrings and $functions
——————————————————————————————————————————
would result in request cancellation if %long was longer than 255 bytes. One way
around this would be to use the $str function to tell User Language to treat the
Longstring as a String in this case as in
print $substr($str(%long), 1, 50)
though a better approach in this case would be to use the Longstring-capable substringing function, $lstr_substr, as in:
print $lstr_substr(%long, 1, 50)
The Longstring-capable $functions in this manual typically start with “$lstr”, end in “_lstr”
(such as $listinf_lstr), or belong to a family of $functions (such as the $regex family) that
are completely longstring-capable. Longstring-capable $functions specific to other Sirius
products (like the Janus Web Server and Janus Sockets $functions) typically do not use
an “lstr” prefix or suffix, but they are identified in their documentation as longstringcapable.
In addition to their ability to process more than 255-byte long strings, longstring-capable
$functions have some special characteristics pertaining to expression handling:
●
A longstring-capable $function that returns a string result (as opposed to one that
returns a numeric result such as $lstr_index) is treated as a Longstring expression
for the purposes of truncation and for the upgrading of With operations to longstring
With operations. For example if %short is String Len 5 and %junk contains Some
text,
%short = $lstr_substr(%junk, 1, 7)
would result in a request-cancelling truncation error. This is true whether %JUNK
was a Longstring or a regular String, though the latter illustrates the point that
regular String variables (or expressions) can be used as input to Longstring-capable
$functions. If %junk contained 300 bytes of data
%out = $lstr_substr(%junk, 1, 255) with '*'
would result in a request-cancelling truncation error if %out were a regular String
variable, and would result in 256 bytes, the last byte being an asterisk, being
assigned to %out if %out were a Longstring.
●
All string arguments to longstring-capable $functions are treated as longstring
targets for the purpose of upgrading With operations to longstring With operations.
For example, since $lstr_right is longstring-capable, With in its string argument is
upgraded to longstring. So, if %medium is a string containing 252 or more
characters, then
$lstr_right(%medium with '****', 256)
returns the right-most 252 bytes of %medium, concatenated with four asterisks.
——————————————————————————————————————————
17
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
Note that this behavior does not imply that longstring-capable $functions will always
accept strings longer than 255 bytes as their arguments. For example, $lstr_index
will not accept strings longer than 255 bytes as its second argument (the string
being searched for), and $lstr_right and $lstr_left won't accept any strings longer
than a single byte for their third argument (the pad character). This $functionspecific behavior does not affect the treatment of the $function results or arguments
as longstring data for expression handling purposes.
4.4
Longstrings and complex subroutines
Complex subroutine parameters, both Input and Output (or Inout, which means the same
thing as Output) can be defined as Longstring, as in either of the following:
subroutine chop(%x is longstring input)
subroutine chop(%x is longstring output)
In addition, Longstring variables and expressions can be passed as parameters to
complex subroutines. For Output parameters, longstring issues are fairly
straightforward. There are two restrictions:
●
You cannot pass a Longstring as a parameter to a subroutine that defines the
parameter as String Output.
●
You cannot pass a regular String as a parameter to a subroutine that defines the
parameter as Longstring Output.
For Input parameters, things are somewhat more complex, because:
●
Mismatches in String and Longstring datatypes are allowed between passed value
and declared parameter.
●
Input parameters can actually receive the results of expressions as their inputs.
While for Input parameters, Strings and Longstrings may be passed interchangeably as
Longstring and String parameters, subroutine declaration statements (Declare
Subroutine) must exactly match the parameter types on the actual subroutine definitions.
That is, given a declaration like this:
declare subroutine tender(longstring)
One cannot later specify the subroutine as
subroutine tender(%mercy is string len 255)
If a Longstring parameter is passed to a subroutine with the parameter defined as String
——————————————————————————————————————————
18
——————————————————————————————————————————
Longstrings and complex subroutines
——————————————————————————————————————————
Input, the request is cancelled if the Longstring value is longer than the length of the
String Input parameter (as always, this will happen even if the Longstring value is shorter
than 255 bytes). This mimics the behavior of an assignment of a Longstring variable to
a regular String variable.
If a Longstring array is passed to a subroutine with the parameter defined as a String
Array, the request is cancelled if any element of the Longstring array is longer than 255
bytes, whether or not that element is ever referenced in the complex subroutine.
Outside the functionality issues raised by this limitation, it also suggests an inefficiency
in passing a Longstring array to a String parameter: the inefficiency of scanning the
array for values longer than 255 bytes. Because of both the functionality and efficiency
issues, it is probably best to avoid passing a Longstring array to a String array parameter
if at all possible.
Because a String variable or a literal can always fit into a Longstring parameter, there
are no truncation or other issues associated with passing String variables and literals as
parameters defined as Longstring.
If a call to a complex subroutine contains a With operation for a Longstring parameter,
that With operation is “upgraded” to a longstring With operation, whether or not any of
the operands are themselves Longstrings, exactly as if the target of a With operation
were a Longstring variable. As everywhere else, a With operation involving a Longstring
in a subroutine call will also be upgraded to a longstring With operation, meaning that no
truncation will occur at 255 bytes, and that if the result is longer than the length of the
target String parameter, the request will be cancelled.
4.5
Changing Longstring truncation behavior
While it is sometimes convenient that Model 204 silently truncates string data on
assignment to a variable or intermediate result, it has also been the source of a vast
number of incorrect User Language programs. Because of this history and the higher
chance of unintentional truncation from a Longstring source, the default behavior for
Longstrings is that any truncation on assignment from a Longstring, longstring $function,
or longstring With operation causes request cancellation. This behavior should facilitate
“cleaner” and more robust code: where truncation is intended, it is explicitly indicated (for
example, with $lstr_substr, $lstr_left, or $str).
Nevertheless, since this cancellation on truncation behavior is inconsistent with
Model 204's behavior for strings, it might be viewed as undesirable. If you want to
prevent request continuation on truncation of a Longstring source in an Online, you can
MSGCTL the error message for Longstring truncation to NOCAN.
The three messages that you might need to MSGCTL are MSIR.0680, MSIR.0681, and
MSIR.0682. MSIR.0680 is issued if the SIRFACT system parameter X'01' bit is set, or if
the DEBUGUL user parameter is set to a non-zero value. MSIR.0681 is issued for
requests entered at command level rather than run from a procedure. MSIR.0682 is
issued otherwise.
——————————————————————————————————————————
19
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
Issuing MSGCTL for these messages to NOCAN might prevent request cancellation
from the occasional Longstring truncation, but if silent truncation of Longstrings is heavily
used as a programming “technique” inside a request, the user running the request will
quickly be restarted with a “TOO MANY ERRORS” message. To prevent this, MSGCTL
the indicated messages to NOCOUNT.
Even then, a large number of these messages might be viewed as being annoying, at
best, if the intent is to simply ignore silent truncation of Longstrings. In that case,
MSGCTL the indicated messages to NOTERM and maybe even NOAUDIT (if this latter
is available). Even then, there will be a little Model 204 processing overhead in
producing the messages that are everywhere suppressed, so it would still generally be
more efficient to truncate Longstrings explicitly using $str or $lstr_substr or $lstr_left.
If you use the default Longstring behavior, at least in the development and test
environments, you should find it will rapidly catch potential problems and so produce
more bug-free code. The request cancellation due to longstring truncation should
therefore be a benefit. In those places that “truncation by assignment” is used in the
code, if you change any of the types in the source expression and discover request
cancellation, you will probably decide it is better to use an explicit truncation construct,
rather than to retain this dubious coding practice.
If there is concern about request cancellation in a production region, you can MSGCTL
the indicated messages to NOCAN in production. However, such a switch allows a
production request to continue after an unanticipated longstring truncation, so it could
result in data corruption or a more subtle error later in the request that will cause request
cancellation anyway, but be more difficult to diagnose.
4.6
Longstrings and the Print, Html, and Text
statements
Using Longstring expressions in the Print statement works largely “as expected”: given
the constraints of LOBUFF, OUTCCC, and OUTMRL, and other output target specific
parameters, the values of Longstrings are simply displayed to the output target. One
minor exception to this is that the To and At clauses on the PRINT statement are not
supported for Longstrings.
It should also be kept in mind that the With keyword in Print statements is not the With
concatenation operator, although the result is usually the same as if it were. Specifically,
the With keyword results in the part before the With being printed, followed by the part
after. This means that if two regular String variables, each with 255 bytes of data in
them, are printed as follows:
print %a with %b
——————————————————————————————————————————
20
——————————————————————————————————————————
Longstrings and the Print, Html, and Text statements
——————————————————————————————————————————
510 bytes of data would be printed, which is different from the With operator in an
assignment like the following, which will result in %c simply containing the contents of
%a, because the With operation results in truncation at 255 bytes:
%c = %a with %b
This difference between the With keyword in the Print statement and the With operator in
expressions predates Longstrings and is, in fact, more significant with regular Strings
than with Longstrings.
The Html and Text statements allow variable values or expression results to be
embedded inside the expression start and end characters (defaults: { and }). As with the
Print statement, this works pretty much “as expected” for Longstrings: the contents of the
Longstring variable or the result of a Longstring expression will be displayed in their
entirety within display parameter constraints. The only Longstring related issue for Html
statement expressions is that if an expression is not a Longstring variable, a longstring
$function, or a With operation involving one or more of these, the expression is assumed
to be a regular String expression that undergoes silent truncation at 255 bytes. For
example, if %a and %b were regular String variables both containing 200 bytes of data,
the following would truncate the concatenation of %a and %b at 255 bytes:
text data The result is {%a with %b}
To get around this, one can force the With operation to be upgraded to a Longstring With
operation, using:
text data The result is {$lstr(%a with %b)}
However, the use of With operations in Html statements is generally silly, since the same
result can be obtained by simply entering each operand in the With expression as a
separate expression as in
text data The result is {%a}{%b}
4.7
Longstring performance
The first 255 bytes of Longstrings are always kept in STBL, so the code path for
manipulating a Longstring variable with a value that is shorter than 256 bytes is usually
identical to or only slightly greater than the code path for manipulating a regular String
variable. A Longstring variable always has 257 bytes of STBL allocated for it at compile
time, and it requires somewhat more VTBL space than a regular String variable.
Longstring arrays require 257 bytes of STBL per element and some VTBL space per
element. This is unlike regular String variables, which require no per-element VTBL
space.
——————————————————————————————————————————
21
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
Yet because of the minor code path issues and the table space issues just mentioned, it
is probably not a good idea to use Longstring variables in contexts where the values are
never expected to exceed 255 bytes, unless performance is not a major concern, or
unless the extra error detection for Longstring truncation is desired.
Of course, variables that need to hold more than 255 bytes of data must be declared as
Longstrings, and any data beyond 255 bytes gets stored in CCATEMP. This means
manipulation of very long Longstring variables could result in significant logical and even
physical CCATEMP I/O and higher CCATEMP utilization. In addition, very long
Longstring values means large quantities of data need to be scanned or copied, which in
itself could be a source of CPU overhead. This is not to say that long values should not
be used in Longstrings in applications; quite the contrary. Longstrings are designed for
applications that require long values, and the performance of Longstring manipulation,
even for very long values, will generally be pretty good.
Nevertheless, it is a good idea to avoid unnecessary, very long, Longstring operations —
unnecessary because the application does not require it, or because the operation has
already been performed once. Regarding the latter, if a very long Longstring operation
occurs in a loop, it would be better to move the operation outside the loop if possible, or
to only do it conditionally if it's really required and hasn't already been performed in a
previous iteration of the loop.
There is relatively little space overhead for the part of a Longstring that resides in
CCATEMP — 6124 of the 6144 bytes on each CCATEMP page actually hold data. So
the first 255 bytes of a 60,000 byte long Longstring value are stored in STBL, and the
remaining 60,000-255 bytes are stored on (60,000-255)/6124, or 10 CCATEMP pages.
Intermediate results will also use some CCATEMP space, though this usage will typically
be short-lived — the space being released as soon as the statement completes. So, for
example, if %a and %b are Longstring variables each with 90,000 bytes of data, and %c
is a Longstring variable, the following statement will temporarily require an extra 120,000
bytes of space (255 of them in STBL) to hold the result of the %a with %b operation:
%c = $lstr_substr(%a with %b, 60000, 60000)
Because concatenation of one string to another is such a common operation,
assignment of the concatenation of a Longstring variable and another string to the first
Longstring variable is highly optimized. For example, if %long is a longstring with 50,000
bytes of data:
%long = %long with '!'
would simply tack an exclamation mark on the end of %long rather than copying all of
%long and an exclamation mark and then assigning that string to %long. Note,
however, that this optimization is only performed if a single string is being concatenated
with the current value of the target variable. That is, in the following:
%long = %long with '+' with $time
——————————————————————————————————————————
22
——————————————————————————————————————————
Longstring performance
——————————————————————————————————————————
an intermediate Longstring containing the concatenation of %long and a plus sign will be
created. That intermediate Longstring will then be concatenated with the current time
(as returned by $time) and then assigned to %long. This means that the current
contents of %long end up being copied twice in such a case which, if %long contains
50,000 bytes, is 100,000 bytes worth of data movement which will be quite expensive,
by any standard. Fortunately, it is easy to “help out” the compiler to make this operation
more efficient:
%long = %long with ('+' with $time)
In this case, the concatenation of the plus sign and the current time are assigned to an
intermediate work Longstring. Then, because this intermediate value is simply being
concatenated with %long and then assigned back to %long, the concatenation
optimization results in the intermediate work Longstring simply being tacked on to the
end of %long, requiring almost no data movement, at all. Even in cases where the
concatenation can't be optimized to an append operation, it is usually a good idea to
isolate concatenations involving relatively small values from a preceding one involving a
(potentially) very long one.
For example, if a longstring with a potentially large value is being bracketed by the date
and time, using a greater-than and less-than symbol as separators, the following:
%long = $date with '>' with %long with ('<' with $time)
will be more efficient than
%long = $date with '>' with %long with '<' with $time
——————————————————————————————————————————
23
——————————————————————————————————————————
Longstrings
——————————————————————————————————————————
——————————————————————————————————————————
24
——————————————————————————————————————————
Sessions
——————————————————————————————————————————
——————
CHAPTER 5
Sessions
Sirius Mods version 6.3 and later provide several $functions to support sessions. A
session is a workstream that might extend beyond a Model 204 login session and might
even be transferred among multiple Model 204 threads or users. Sessions are
especially useful for web applications that require some context to be maintained over
multiple web requests, each of which requires a login and logout. Sessions do not, of
course, survive the cycling of the Online in which they were established, and they cannot
be passed between Onlines.
Sessions are a collection of data structures that are accessible while the session is open
and that persist as long as the session persists. These data structures include session
$lists, session longstrings, and session XMLDocs. Under Sirius Mods version 6.6 and
later, sessions can also contain objects, that is, instances of a class.
Sessions can be created with $session_create, re-opened with $session_open, closed
with $session_close and deleted with $session_delete. Only a single session may be
open at a time on a thread, and any session that is open when a user logs off is
automatically closed. A session can only be open on a single thread at any given time.
Sessions are owned by a specific user, or they are public (in which case they are
considered to be “owned by *,” that is, owned by all users). Non-privileged users can
only create, access, and delete public sessions and those owned by themselves, that is,
by their own userids. Privileged, that is system manager or system administrator users,
can create, access, and delete public sessions and those owned by any user.
To reestablish a session between logins (or within a login), each session requires an
identifier called a session id. The session id is established when the session is created,
and it can be changed as needed. A session id must be unique for a userid, or for an
entire Online if the session is public.
Inactive sessions, that is, those that haven't been opened in a long time, are considered
timed out and are eligible for deletion. The inactivity time for a timeout can be set at
session creation time and changed whenever the session is closed.
There are several system parameters that control the availability and behavior of the
session feature:
SESNPRV
The maximum number of private sessions that can be active. Setting
this value allocates about 160 bytes of virtual storage for each possible
session. The default value for SESNPRV is 0, which means that no
private sessions can be created.
——————————————————————————————————————————
25
——————————————————————————————————————————
Sessions
——————————————————————————————————————————
SESNPUB
The maximum number of public sessions that can be active. Setting this
value allocates about 160 bytes of virtual storage for each possible
session. The default value for SESNPUB is 0, which means that no
public sessions can be created.
SESUMAX
The maximum number of private sessions that can be active for a single
owener (userid). The default value for SESUMAX is 0, which means
that a given userid can only have one session active at a time.
SESOPT
A bitmask parameter that controls the behavior of the session feature.
The meaning of the bits are:
X'01'
Clean up timed out sessions. If this bit is on and the X'02' bit is
off, every $session_create, $session_open, $session_close, and
$session_delete call cleans up timed out sessions. This cleanup
could occur well after the timeout occurred if $SESSIONxxx calls
are relatively infrequent.
Use this option if timed-out session cleanup is desired but it is
not worth incurring the overhead of having a PST to do the
cleanups. Under Sirius Mods 6.6 and later, timed out sessions
are always immediately cleaned up, so this bit is irrelevant under
Sirius Mods version 6.6 and later.
X'02'
Create a PST to clean up timed out sessions. If this bit is on, a
PST is attached in the Online whenever there is an active but not
open session. If a session times out, the PST immediately
deletes the session, freeing up the CCATEMP pages used by
the session.
Use this option if cleaning up sessions very quickly is worth the
(probably slight) cost of having a PST to do the cleanup.
The default value for SESOPT is 0, which means that timed out
sessions are not cleaned up and, in fact, can still be opened after
timeout, if they have yet to be deleted. Under the default settings,
sessions are only deleted when they are timed out, a new private or
public sessions is being created, and the maximum like-typed (private or
public) sessions are active. In this case, the oldest like-typed session is
deleted.
Under Sirius Mods 6.6 and later, a PST is attached whenever there are
any active sessions in an Online, so this bit is irrelevant under Sirius
Mods version 6.6 and later. The attached PST always actively deletes
any timed-out sessions immediately.
SESDEFTO
Sets the default timeout value for a session if one is not specified in the
$session_create call. The default value for SESDEFTO is 900, which
——————————————————————————————————————————
26
——————————————————————————————————————————
Sessions
——————————————————————————————————————————
indicates a default timeout of 900 seconds, or 15 minutes. If a session
is not re-opened within the timeout value of the $session_close, it is
considered timed-out and liable to deletion under control of the SESOPT
flags, or immediately under Sirius Mods 6.6 and later. The SESDEFTO
setting can be overridden in many of the $SESSIONxxx functions.
SESDEFOW
Sets the default open wait time value for a session if one is not specified
in the $session_open call. The default value for SESDEFTO is 0, which
means a $session_open call will not wait if the request session is in-use,
that is, open by another thread. If a session is still in-use after the open
wait time, a return code of 2 is set by $session_open to indicate the
problem. The SESDEFOW setting can be overridden in the
$session_open call.
Under Sirius Mods version 6.6 and later, sessions can contain both system and User
Language objects. When a session is closed, any objects associated with a session
name, either via the Session keyword on a variable declaration or via a SetSession
method in the object class, “follow the closed session” and become logically owned by
the session PST.
In addition, any objects accessible indirectly from a session name also “follow the
session.” That is, if an object can be accessed via a session name and that object
contains a reference to another object, the latter object also “follows the session” when
the session is closed. Because determining which objects can be accessed directly or
indirectly from a session name is very much like object garbage collection, a
$session_close causes garbage collection to be performed for the invoking thread. For
more information about session objects and garbage collection, see the Janus SOAP
Reference Manual.
Many of the data structures associated with sessions are also associated with systemwide resources such as CCATEMP pages, virtual storage, record locks, Janus threads,
file locks, and so on. When a session is closed but not deleted, these resources are
considered to be “owned” by the session PST, and so, where possible, SirMon tries to
indicate this ownership.
——————————————————————————————————————————
27
——————————————————————————————————————————
Sessions
——————————————————————————————————————————
——————————————————————————————————————————
28
——————————————————————————————————————————
Procedure Processing $Functions
——————————————————————————————————————————
——————
CHAPTER 6
Certain Sirius $functions allow a User Language request to read the source lines of a
saved User Language procedure. The $PROCOPN function "opens" a procedure, while
the $PROCGET and $PROCDAT functions sequentially retrieve the lines from a
procedure previously opened by $PROCOPN. The $PROCLOC function locates
specific strings in the currently "open" procedure.
Calls to $PROCOPN may be nested up to the system maximum of five procedures.
Each call to $PROCGET returns the next line of the procedure associated with the
current nesting level. Each call to $PROCDAT returns the next several lines of the
procedure associated with the current nesting level and places them into a specified
$list. If $PROCOPN is called before the end of the current procedure is reached, the
current procedure is pushed on the include stack and the next procedure is opened.
Subsequent $PROCGET, $PROCDAT and $PROCLOC calls will retrieve lines from the
new procedure.
After each procedure has been entirely processed, $PROCGET returns a null string,
$PROCDAT simply adds nothing to the input $list and $PROCLOC returns a -2. Each of
these then pops back to the previous nesting level, if any. The next $PROCGET,
$PROCDAT or $PROCLOC call will operate on the procedure opened by the previous
$PROCOPN call, if any. Null lines contained in a procedure are returned by
$PROCGET as one blank character to avoid confusion with the "end of file" case.
——————————————————————————————————————————
29
——————————————————————————————————————————
——————————————————————————————————————————
——————————————————————————————————————————
30
——————————————————————————————————————————
Description of $Functions
——————————————————————————————————————————
——————
CHAPTER 7
This chapter lists $functions delivered as part of the Sirius Mods. Each $function is
shown with its argument list and returned value, and with an example of using the
$function.
At the end of each $function description is a figure listing the Sirius Mods products which
authorize the $function. If your site is not authorized for any of these products, an
attempt to compile a request using the $function will generate an M204.0723:
FUNCTION NOT DEFINED error message, compilation will fail, and the request will not
run.
As noted in “Introduction” on page 1, some $functions that are part of some Sirius Mods
products are not described in this manual. To help locate descriptions for these
$functions, this chapter includes sections for “families” of $functions: for example, the
$WEB_xxx section (“$WEBxxx: Janus Web Server $functions” on page 481) is a
placeholder for the Janus Web Server $functions, which are described in the Janus
Web Server Reference Manual.
Although Sirius Mods version 6.5 made mixed-case User Language available for use
with Sirius Janus products, the Sirius Functions Reference Manual retains the alluppercase presentation for $function names and User Language entities. For more
information about mixed-case User Language, see the Janus SOAP Reference
Manual.
——————————————————————————————————————————
31
——————————————————————————————————————————
——————————————————————————————————————————
7.1
CALLing Sirius Mods functions
As of version 6.5 of the Sirius Mods, you can invoke many of the Sirius $functions using
a User Language CALL statement instead of assigning the function result to a
%variable. For example:
%L = $LISTNEW
$LISTADD(%L, 'Once upon a midnight dreary')
$LISTADD(%L, 'As I pondered weak and weary')
CALL $LIST_PRINT(%L)
You can CALL such $functions and still test for their return code, if necessary. For
example:
CALL $LIST_PRINT(%L)
IF $LIST_PRINT(%L) THEN
This "callability" is an optional approach; it does not replace %variable assignment.
The callable $functions are indicated as such in their individual function descriptions in
this document. Typically they are $functions that do more than simply return a value,
and the value they return is primarily an indicator of whether the function completed
successfully. $LISTCNT, for example, is a (non-callable) $function that just returns a
value.
——————————————————————————————————————————
32
——————————————————————————————————————————
$A2E: Translate ASCII to EBCDIC
——————————————————————————————————————————
7.2
$A2E: Translate ASCII to EBCDIC
The $A2E function returns a string which is the EBCDIC equivalent of the (presumed)
ASCII input string. $A2E is longstring capable, that is, it can receive an input longstring
and will produce an output longstring.
$A2E accepts one required argument and returns a string value.
The first argument is the string to be translated from ASCII to EBCDIC.
The returned result is a string which is the EBCDIC equivalent of the (presumed) ASCII
input string.
%EBCDIC = $A2E(ascii_val)
$A2E Function
%RESULT is set to the ASCII-to-EBCDIC translation of ascii_val.
The inverse of $A2E is $E2A (“$E2A: Translate EBCDIC to ASCII” on page 89).
$A2E uses the “standard” ASCII-to-EBCDIC translation tables provided by Sirius, and it
provides no mechanism for overriding these tables.
$A2E is available only in Sirius Mods version 6.8 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $A2E
——————————————————————————————————————————
33
——————————————————————————————————————————
——————————————————————————————————————————
7.3
$ABBREV: Determine if string is abbreviation
within list of words
This function makes it possible to determine if a string is a valid abbreviation of one of a
list of words.
$ABBREV accepts two arguments and returns a numeric code.
The first argument is a list of blank-delimited words.
The second argument is the word to be compared with the blank-delimited word list in
the first argument.
%RESULT = $ABBREV(word_list, string)
$ABBREV Function
%RESULT indicates the relative position in word_list of the first word for which
string is a valid abbreviation.
>0
0
-1
-2
-
Number of matching word
No matches found
First parameter missing or null
Second parameter missing or null
$ABBREV return codes
In the following example
%NUM = $ABBREV('TOP BOTTOM MIDDLE MUDDLE', 'B')
%NUM is set to 2.
%NUM = $ABBREV('TOP BOTTOM MIDDLE MUDDLE', 'M')
%NUM is set to 3.
%NUM = $ABBREV('TOP BOTTOM MIDDLE MUDDLE', 'MU')
%NUM is set to 4.
%NUM = $ABBREV('TOP BOTTOM MIDDLE MUDDLE', 'TOP')
——————————————————————————————————————————
34
——————————————————————————————————————————
$ABBREV: Determine if string is abbreviation within list of words
——————————————————————————————————————————
%NUM is set to 1.
%NUM = $ABBREV('TOP BOTTOM MIDDLE MUDDLE', 'MAD')
%NUM is set to 0.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ABBREV
——————————————————————————————————————————
35
——————————————————————————————————————————
——————————————————————————————————————————
7.4
$ARR_FIND: Find value within array
$ARR_FIND can be used to find an array element with a specific value. $ARR_FIND
accepts three arguments and returns a numeric code.
The first argument is an array of string, float, or fixed values. This array must be a single
dimensional array and must not be an array in an image.
The second argument is the value to be located in the array. If this value is found in
multiple array elements, $ARR_FIND always returns the first (lowest element number)
array element containing this value.
The third argument is the lowest array element number to check. This argument can be
used to skip the first "N" array elements where N is a positive integer.
%RESULT = $ARR_FIND (array, value, minnum)
$ARR_FIND Function
%RESULT is set to the array element number containing the indicated value, or
it is set to a -1 if the value was not found or if the array or minnum is invalid.
%FXARRAY IS FIXED ARRAY(5)
%FXARRAY(1) = 2
%FXARRAY(2) = 3
%FXARRAY(3) = 5
%FXARRAY(4) = 8
%NUM = $ARR_FIND(%FXARRAY,5)
%NUM is set to 3.
%STARRAY IS STRING LEN 20 ARRAY(6)
%STARRAY(1) = 'ONE'
%STARRAY(2) = 'TWO'
%STARRAY(3) = 'THREE'
%STARRAY(4) = 'FOUR'
%STARRAY(5) = 'ONE'
%STARRAY(6) = 'TWO'
%NUM = $ARR_FIND(%STARRAY, 'ONE', 2)
%NUM is set to 5.
——————————————————————————————————————————
36
——————————————————————————————————————————
$ARR_FIND: Find value within array
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ARR_FIND
——————————————————————————————————————————
37
——————————————————————————————————————————
——————————————————————————————————————————
7.5
$ARR_INIT: Initialize every element of array to
specific value
$ARR_INIT can be used to initialize every element of an array to a specific value.
$ARR_INIT accepts two arguments and returns a numeric code.
The first argument is an array of string, float, or fixed values. This array can be a single
or multi-dimensional array and must not be an array in an image.
The second argument is the value with which the array is to be initialized. If this
argument is not specified, it defaults to a null string if the first argument is a string array
and 0 if the first argument is either a fixed or float array.
%RESULT = $ARR_INIT (array, value)
$ARR_INIT Function
%RESULT returns a 0 or, if the array is invalid, a -1.
%RC = $ARR_INIT(%FXARRAY)
every element of %FXARRAY is set to 0.
%RC = $ARR_INIT(%STARRAY, '*** UNKNOWN ***')
every element of %STARRAY is set to '*** UNKNOWN ***'.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ARR_INIT
——————————————————————————————————————————
38
——————————————————————————————————————————
$ARR_MAX: Find maximum value in array
——————————————————————————————————————————
7.6
$ARR_MAX: Find maximum value in array
$ARR_MAX can be used to find the maximum value in an array. $ARR_MAX accepts
two arguments and returns a numeric code.
The second argument is the highest array element number to check. This argument can
be used to limit the search to the first "N" elements in an array where N is a positive
integer.
If the maximum value occurs in multiple array elements, $ARR_MAX always returns the
lowest array element number containing that value.
%RESULT = $ARR_MAX (array, maxnum)
$ARR_MAX Function
%RESULT indicates the element number of the maximum value in the array, or
indicates a -1 if array or maxnum is invalid.
%FXARRAY(1) = 81
%FXARRAY(2) = 49
%FXARRAY(3) = 121
%FXARRAY(4) = 25
%NUM = $ARR_MAX(%FXARRAY)
%NUM is set to 3.
%STARRAY(1) = 'HOMER'
%STARRAY(2) = 'MARGE'
%STARRAY(3) = 'BART'
%STARRAY(4) = 'KRUSTY'
%STARRAY(5) = 'SELMA'
%NUM = $ARR_MAX(%STARRAY, 4)
%NUM is set to 2.
——————————————————————————————————————————
39
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ARR_MAX
——————————————————————————————————————————
40
——————————————————————————————————————————
$ARR_MIN: Find minimum value in array
——————————————————————————————————————————
7.7
$ARR_MIN: Find minimum value in array
$ARR_MIN can be used to find the minimum value in an array. $ARR_MIN accepts two
arguments and returns a numeric code.
The second argument is the highest array element number to check. This argument can
be used to limit the search to the first "N" elements in an array where N is a positive
integer.
If the minimum value occurs in multiple array elements, $ARR_MIN always returns the
lowest array element number containing that value.
%RESULT = $ARR_MIN (array, maxnum)
$ARR_MIN Function
%RESULT indicates the element number of the minimum value in the array, or
indicates a -1 if array or maxnum is invalid.
%FXARRAY(1) = 81
%FXARRAY(2) = 49
%FXARRAY(3) = 121
%FXARRAY(4) = 25
%NUM = $ARR_MIN(%FXARRAY)
%NUM is set to 4.
%STARRAY(1) = 'HOMER'
%STARRAY(2) = 'MARGE'
%STARRAY(3) = 'KRUSTY'
%STARRAY(4) = 'BART'
%STARRAY(5) = 'SELMA'
%NUM = $ARR_MIN(%STARRAY, 3)
%NUM is set to 1.
——————————————————————————————————————————
41
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ARR_MIN
——————————————————————————————————————————
42
——————————————————————————————————————————
$BASE64_DECODE: Convert from base 64 to byte string
——————————————————————————————————————————
7.8
$BASE64_DECODE: Convert from base 64 to byte
string
This function converts from a base 64 encoded string to the decoded byte string. It is
identical to $LSTR_BASE64_DECODE (“$LSTR_BASE64_DECODE: Convert from
base 64 to byte string” on page 267) with the (hopefully obvious) exception that it is not
longstring capable. As such, $LSTR_BASE64_DECODE is recommended over
$BASE64_DECODE as it is a more flexible version of the latter.
The $BASE64_DECODE function accepts one argument and returns a string result
whose base 64 encoding is that argument.
The first argument is a string which is a base 64 encoding.
The returned value is the base 64 decoding of the argument string. If the argument is
not a valid base 64 encoding, the null string is returned.
%DECODED = $BASE64_DECODE(string)
$BASE64_DECODE Function
%DECODED is set to the base 64 decoding of string.
For example, given the argument of length 4:
%JUNK = $BASE64_DECODE('ABCD')
%JUNK would be set to the byte string (of length 3) represented in hexadecimal as
X'001083'.
Because the maximum length of the argument is 255 bytes, if you have a longer stream
to decode, you can do it in pieces, where any piece is a multiple of 4 bytes long (3 bytes
are evenly packed into 4 bytes of a base 64 encoding). For example, if you have a valid
base 64 string which is the concatenation of items in a Sirius $list and you wish to print
that string, possibly producing multiple lines of length 60, you can use the following
approach:
%S = ''
FOR %I FROM 1 TO $LISTCNT(%L)
%T = $LISTINF(%L, %I)
REPEAT WHILE $LEN(%S) + $LEN(%T) > 80
%X = 80 - $LEN(%S)
%U = %S WITH $SUBSTR(%T, 1, %X)
PRINT $BASE64_DECODE(%U)
%T = $SUBSTR(%T, %X + 1)
%S = ''
END REPEAT
%S = %S WITH %T
END FOR
PRINT $BASE64_DECODE(%S)
——————————————————————————————————————————
43
——————————————————————————————————————————
——————————————————————————————————————————
As of Sirius Mods version 6.8, you can do base 64 decoding of strings longer than 255
bytes using $LSTR_BASE64_DECODE, but if, as in the example above, the intent is to
break the result into smaller chunks, anyway, there probably wouldn't be a marked
difference between using $BASE64_DECODE or its longstring equivalent.
You may wish to check for an invalid base 64 encoding by checking for the null string
return value from $BASE64_DECODE. Of course, if it is possible that the argument is
null, the null string is a valid returned value. If you need to check for errors, and the null
string is a possible argument value, you can use an approach such as the following:
%STR = $BASE64_DECODE(%IN)
IF %STR EQ ''
IF %IN NE '' THEN
error code ...
END IF
END IF
$BASE64_ENCODE is the inverse of $BASE64_DECODE.
This $function is new in version 6.0 of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $BASE64_DECODE
——————————————————————————————————————————
44
——————————————————————————————————————————
$BASE64_ENCODE: Convert byte string to base 64
——————————————————————————————————————————
7.9
$BASE64_ENCODE: Convert byte string to base 64
This function converts a byte string into its base 64 encoding. It is identical to
$LSTR_BASE64_ENCODE (“$LSTR_BASE64_ENCODE: Convert byte string to base
64” on page 269) with the (hopefully obvious) exception that it is not longstring capable.
As such, $LSTR_BASE64_ENCODE is recommended over $BASE64_ENCODE as it is
a more flexible version of the latter.
The $BASE64_ENCODE function accepts one argument and returns a string result
which is the base 64 encoding of that argument.
The first argument is a byte string of length 189 or less. If this argument is longer than
189 bytes, the request is cancelled.
The returned value is the base 64 encoding of the argument string.
%CODED = $BASE64_ENCODE(string)
$BASE64_ENCODE Function
%CODED is set to the base 64 encoding of string.
For example, given the argument of length 3:
%JUNK = $BASE64_ENCODE($X2C('001083'))
%JUNK would be set to the byte string (of length 4) represented in character as 'ABCD'.
Because the maximum length of the argument is 189 bytes, if you have a longer stream
to encode, you can do it in pieces, where any piece is a multiple of 3 bytes long (3 bytes
are evenly packed into 4 bytes of a base 64 encoding). For example, if you have a byte
string which is the concatenation of items in a Sirius $list and you wish to print the base
64 encoding of that string, possibly producing multiple lines of length 80, you can use the
following approach:
%S = ''
FOR %I FROM 1 TO $LISTCNT(%L)
%T = $LISTINF(%L, %I)
REPEAT WHILE $LEN(%S) + $LEN(%T) > 60
%X = 60 - $LEN(%S)
%U = %S WITH $SUBSTR(%T, 1, %X)
PRINT $BASE64_ENCODE(%U)
%T = $SUBSTR(%T, %X + 1)
%S = ''
END REPEAT
%S = %S WITH %T
END FOR
PRINT $BASE64_ENCODE(%S)
——————————————————————————————————————————
45
——————————————————————————————————————————
——————————————————————————————————————————
As of Sirius Mods version 6.8, you can do base 64 encoding of strings longer than 255
bytes using $LSTR_BASE64_ENCODE, but if, as in the example above, the intent is to
break the result into smaller chunks, anyway, there probably wouldn't be a marked
difference between using $BASE64_DECODE or its longstring equivalent.
$BASE64_DECODE is the inverse of $BASE64_ENCODE.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $BASE64_ENCODE
——————————————————————————————————————————
46
——————————————————————————————————————————
$BGPURGE: Cancel "long" sdaemon request initiated with $COMMBG
——————————————————————————————————————————
7.10
$BGPURGE: Cancel "long" sdaemon request
initiated with $COMMBG
This function is obsolete and does nothing but return a value of 6.
●
Sirius Functions
Products authorizing $BGPURGE
——————————————————————————————————————————
47
——————————————————————————————————————————
——————————————————————————————————————————
7.11
$BGQUERY: List of "long" sdaemon requests
initiated via $COMMBG
This function is obsolete and has done nothing but return a value of 0 if a valid $list
identifier is specified as a parameter and 6 otherwise.
●
Sirius Functions
Products authorizing $BGQUERY
——————————————————————————————————————————
48
——————————————————————————————————————————
$BIND: Fast, easy synchronization of system wide resource
——————————————————————————————————————————
7.12
$BIND: Fast, easy synchronization of system
wide resource
The $BIND function provides a fast and convenient way of synchronizing access to
system wide resources.
$BIND accepts two arguments and returns a numeric code.
The first argument is the name of the resource to be bound. This resource name can be
any string up to 255 bytes long. Only one user can have a resource bound at a time.
The second argument is the number of milliseconds to wait for the resource if it is not
immediately available. This argument is only available in Sirius Mods version 6.9 and
later. If it is not specified, $BIND returns immediately, indicating that the resource was
not avalable.
%RESULT = $BIND(res_name, wait_time)
$BIND Function
%RESULT is set to indicate the success of the function.
>=0
-1
-2
-10
-20
-
User number that currently has resource bound
Resource name missing
Insufficient storage to do the bind
Resource already bound by current user
Resource successfully bound
$BIND return codes
It is the responsibility of each programming team to establish resource naming
conventions appropriate to its site. A resource remains bound until it is either explicitly
unbound with the $UNBIND or $UNBINDW function or the binding user logs off or is
restarted.
The following program binds the resource called 'SMITHERS'.
b
%rc = $bind('SMITHERS')
end
——————————————————————————————————————————
49
——————————————————————————————————————————
——————————————————————————————————————————
The following program binds the resource called 'BURNS', waiting up to 10 seconds
(10,000 milliseconds) for the resource to become available.
b
%rc = $bind('BURNS', 10000)
end
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $BIND
——————————————————————————————————————————
50
——————————————————————————————————————————
$BIND_LIST: Return list of bound semaphores onto a $list
——————————————————————————————————————————
7.13
$BIND_LIST: Return list of bound semaphores
onto a $list
This function retrieves semaphores bound with $BIND by a specific or all users.
The $BIND_LIST function accepts three arguments and returns a number indicating the
success of the function.
The first argument is the output $list identifier. If the output $list is not empty data is
added to the end of the output $list. This is a required argument.
The second argument is the name of the semaphore for which information is to be
returned. This argument can contain a single specific semaphore name or it can contain
a wildcard string that matches a number of semaphores. This is an optional argument
and defaults to “*” which means to return all semaphores bind by all or a specific user.
The third argument is the user number of the user for which bound semaphores are to
be returned. This is an optional argument and defaults to -1 which means return
semaphores bound by all users.
%RC = $BIND_LIST(olist, sem_name, user_num)
$BIND_LIST Function
%RC is a number of items added to %OLIST, or is a negative error code.
>= 0 - Number of bound semaphores returned
-3 - $list full or out of CCATEMP
All other errors result in request cancellation
$BIND_LIST return codes
Offset
Contents
0-4
The user number of the user that has the semaphore
bound represented as a string with leading zeros
included.
5 - 14
The userid of the user that has the semaphore bound
represented as a string padded with trailing blanks.
15 - end
The name of the bound semaphore.
Output $list format
——————————————————————————————————————————
51
——————————————————————————————————————————
——————————————————————————————————————————
The semaphore name specified in the second argument can be an explicit name or it
can contain the following wildcard characters:
*
Matches any number of characters including none
?
Matches any single character
"
Indicates that the next character must be treated literally even if it is a wildcard
character.
For example, “C*D” matches “CUSTID”, “COD” or “CLOD”. “S??T” matches “SALT”,
“SLOT” or “SORT”. “E"*CONCRETE” matches “E*CONCRETE”.
The following code fragment retrieves all semaphores bound by the current user where
the semaphore name ends with the letters “_TEMP” into a $list and sorts the $list by
semaphore name.
%RC = $BIND_LIST(%OLIST, '*_TEMP', $USER)
%SLIST = $LISTSORT(%OLIST, '16,255, A')
$BIND_LIST is only available in version 6.0 and later of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $BIND_LIST
——————————————————————————————————————————
52
——————————————————————————————————————————
$BITAND: Bitwise AND of two integers
——————————————————————————————————————————
7.14
$BITAND: Bitwise AND of two integers
The $BITAND function returns an integer which is the bitwise AND of two integers.
$BITAND accepts two arguments and returns a numeric value.
The first and second arguments are both integers. The default values are 0.
%RESULT = $BITAND(int_1, int_2)
$BITAND Function
%RESULT is set to the bitwise AND of the two arguments.
The following program will print the value 2:
B
PRINT $BITAND(-2, 3)
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $BITAND
——————————————————————————————————————————
53
——————————————————————————————————————————
——————————————————————————————————————————
7.15
$BITOR: Bitwise OR of two integers
The $BITOR function returns an integer which is the bitwise OR of two integers.
$BITOR accepts two arguments and returns a numeric value.
The first and second arguments are both integers. The default values are 0.
%RESULT = $BITOR(int_1, int_2)
$BITOR Function
%RESULT is set to the bitwise OR of the two arguments.
The following program will print the value 7:
B
PRINT $BITOR(6, 3)
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $BITOR
——————————————————————————————————————————
54
——————————————————————————————————————————
$BUMP: Bump a user
——————————————————————————————————————————
7.16
$BUMP: Bump a user
The $BUMP function allows a privileged user (system manager or system administrator)
to bump another user as with the BUMP command.
$BUMP accepts one or two arguments and returns a numeric code.
The first argument is the number of the user to be bumped.
The second argument is an optional userid. If this argument is provided, the user
number indicated by argument one will only be bumped if the userid matches the second
argument. This helps prevent accidentally bumping a user that just logged onto a thread
previously occupied by another user.
%RESULT = $BUMP(user_num, userid)
$BUMP Function
The behavior of $BUMP is affected by the FUNCOPTS system parameter: If the
FUNCOPTS X'01' bit is set, a caller of $BUMP can bump any thread that has the same
user ID as that of the caller, whether or not the caller is a system administrator or system
manager.
0 - User bumped
1 - User not found
2 - Not privileged to issue BUMP command
$BUMP return codes
The following program bumps userid 'HOMER' with user number 13.
B
%RC = $BUMP( 13, 'HOMER' )
END
●
Sirius Functions
Products authorizing $BUMP
——————————————————————————————————————————
55
——————————————————————————————————————————
——————————————————————————————————————————
7.17
$CENTER: Center string
This function builds a string of an indicated length containing a centered input string.
The $CENTER function accepts three arguments and returns a string result that
contains the first argument string, centered in an area with leading and trailing pad
characters.
The first argument is the string to be centered.
The second argument is the length of the output string. If this argument is negative or
greater than 255, the request is cancelled. Omitting this argument invokes a special
usage of $CENTER, as described at the end of this section.
The third argument is a pad character to be used for centering the result string. This is
an optional argument and defaults to blank.
%STRING = $CENTER(string, length, pad)
$CENTER Function
%STRING is a string containing the first argument string.
For example
%JUNK = $CENTER('PAGE TITLE', 12)
sets %JUNK to ' PAGE TITLE ' and
%JUNK = $CENTER('PAGE', 5)
sets %JUNK to 'PAGE ' and
sets %JUNK to 'A' and
sets %JUNK to 'AG' and
%JUNK = $CENTER('PAGE TITLE', 17, '-')
sets %JUNK to '---PAGE TITLE----'.
There is also an alternate usage for $CENTER, if the second argument (length) is
omitted. In this case, the third argument is ignored, and the first argument must be of
the form:
lenpstring
——————————————————————————————————————————
56
——————————————————————————————————————————
$CENTER: Center string
——————————————————————————————————————————
Where:
len
The first three bytes of the argument must be a decimal number which is at
least as long as the string (trailing) portion of the argument. This number is
used as the result length, containing the centered string.
p
The fourth byte of the argument is the pad character for the output. The pad
characters just before and just after the centered string in the output are each
replaced by a blank.
string
The string to be centered; this can be from 1 to 251 bytes in length.
If this form of $CENTER is used and any of the above restrictions are not met, the value
returned by $CENTER is a single digit '1'. Note that this error return value is
indistinguishable only to the valid invocation $CENTER('001p1'), where p is any pad
character.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $CENTER
——————————————————————————————————————————
57
——————————————————————————————————————————
——————————————————————————————————————————
7.18
$CFSTATL: List of statistics for users holding
critical file resources
This function allows retrieval of statistics for all users holding critical file resources in a
given file into a $list.
The $CFSTATL function accepts three arguments and returns a numeric error code.
The first argument is the indentifier of the $list that is to receive the results. The current
contents of the $list are deleted and replaced with the requested statistics. The format
of each $list item is:
Byte 1-10
Blank padded userid
Byte 11-12
Binary user number
Byte 13-
Returned statistics
The second argument is a string of blank-delimited words indicating the statistics to be
returned. All standard user statistics can be returned, as well as extra critical file
resource held statistics. The length of each returned statistic is always a multiple of 4
bytes. This facilitates the use of $STATLD with the returned $list. For more information
on available statistics see the SIRMON User's Guide.
The third argument is the file number of the file in which the returned list of users hold
critical file resources. Unlike selection criterion for $USSTATL, users not holding critical
file resources in the indicated file are not placed on the output $list. This could prevent
them from being placed on the difference $list by a $STATLD call if rates or differences
are calculated.
%RESULT = $CFSTATL(list_identifier, stat_list, file_num)
$CFSTATL Function
%RESULT is a either a positive number which is the number of milliseconds
since the online was brought up, or is a negative error code.
-3
-5
-6
-12
-13
-16
-
CCATEMP is full
Required parameter not specified
Invalid $list identifier
Invalid name in stat_list
STAT not linked in
Invalid file number
$CFSTATL return codes
The following program displays users and resources for users holding critical file
resources in file number 13.
——————————————————————————————————————————
58
——————————————————————————————————————————
$CFSTATL: List of statistics for users holding critical file resources
——————————————————————————————————————————
B
%DATA IS STRING LEN 255
%LIST = $LISTNEW
%DATA = $CFSTATL(%LIST, 'HDDIRCT HDINDEX HDEXIST HDRECNQ', 13)
IF %DATA < 0 THEN
PRINT '$CFSTATL ERROR... RC = ' WITH %DATA
STOP
END IF
FOR %I FROM 1 TO $LISTCNT(%LIST)
%DATA = $LISTINF(%LIST, %I)
PRINT 'USERID
= ' WITH $SUBSTR(%DATA,
PRINT 'USERNUM = ' WITH $UNBIN( $SUBSTR(%DATA, 11, 2) )
PRINT 'HDDIRCT = ' WITH $SUBSTR(%DATA,
PRINT 'HDINDEX = ' WITH $SUBSTR(%DATA,
PRINT 'HDEXIST = ' WITH $SUBSTR(%DATA,
PRINT 'HDRECNQ = ' WITH $SUBSTR(%DATA,
PRINT
END FOR
1, 10)
13,
17,
21,
25,
4)
4)
4)
4)
END
●
Sirius Functions
Products authorizing $CFSTATL
——————————————————————————————————————————
59
——————————————————————————————————————————
——————————————————————————————————————————
7.19
$CLOSE: Close file or group in User Language
request
The $CLOSE function allows a user to close a file or group from within a User Language
request.
$CLOSE accepts one argument and returns a numeric code. It is also callable
(“CALLing Sirius Mods functions” on page 32).
The only argument is the name of the file or group to be closed. This name can be
either an unqualified name, in which case the standard 204 search order (TEMP
GROUP, PERM GROUP, FILE) will be used to try to identify the file or group; or it can
be a qualified name that explicitly indicates whether $CLOSE is to act on a file or group.
Some examples of qualified names are :
'TEMP GROUP FOO'
'FILE HOHO'
'PERM GROUP CHUCKLES'
'GROUP KRUSTY'
Note that the last example is not fully qualified so that $CLOSE will first look for a
temporary group and then a permanent group.
%RESULT = $CLOSE(fgname)
$CLOSE Function
0
1
2
3
4
5
6
-
File/group closed
File/group name missing
File/group not open
Can't close because of INCLUDE'd proc
Can't close because compiled code accesses file/group
Can't close required subsystem member
Can't close member of open temp group
$CLOSE return codes
The following program closes file 'KRUSTY'.
B
%RC = $CLOSE( 'KRUSTY' )
END
——————————————————————————————————————————
60
——————————————————————————————————————————
$CLOSE: Close file or group in User Language request
——————————————————————————————————————————
●
●
Sirius Functions
SirLib
Products authorizing $CLOSE
——————————————————————————————————————————
61
——————————————————————————————————————————
——————————————————————————————————————————
7.20
$CMS: Determine if online is running under CMS
This function can be used to determine if the online is running under CMS.
The $CMS function accepts no arguments and returns either a 1 if the online is running
under CMS or a 0 otherwise.
%CMS = $CMS
$CMS Function
%CMS is set to either 0 or 1.
This function can be used to test if running under CMS before running any operating
system specific code. For example, the program
IF $CMS THEN
%RC = $SETG('NEXTPROC', 'PROC.CMS')
ELSE
%RC = $SETG('NEXTPROC', 'PROC.MVS')
END IF
would set global variable NEXTPROC to 'PROC.CMS' if running under CMS and to
'PROC.MVS', otherwise.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $CMS
——————————————————————————————————————————
62
——————————————————————————————————————————
$COMMAND: Execute Model 204 command on sdaemon, results to image
——————————————————————————————————————————
7.21
$COMMAND: Execute Model 204 command on
sdaemon, results to image
This function allows a Model 204 command to be executed on an sdaemon with the
results returned to an image. $COMMAND performs the same function as $COMMNDL
except that data is returned to an image rather than a $list. $COMMNDL and
$COMMBG are recommended over $COMMAND, as they run with less overhead, are
simpler to use, and return their output in a $list.
The $COMMAND function accepts five arguments and returns a number indicating the
success of the function. It is also callable (“CALLing Sirius Mods functions” on page 32).
%rc = $COMMAND(cmd, msgctl, image_name, file, width)
$COMMAND Function
%rc is set to 0 or an error code.
cmd
A string containing the Model 204 command to be executed. This is a
required argument.
msgctl
A number indicating the setting to be used for MSGCTL when issuing
the command in the sdaemon. This is an optional parameter, and it
defaults to the user's current MSGCTL setting.
image_name
The name of an image to receive the command output. This image
should have the following format:
IMAGE CMD_OUT
ARRAY_SIZE
DISC_NUM
NEXT_OUT
LINES_OUT
ARRAY OCCURS n
OUT_ARRAY
END ARRAY
END IMAGE
IS
IS
IS
IS
BINARY
BINARY
BINARY
BINARY
LEN
LEN
LEN
LEN
4
4
4
4
IS STRING LEN x
Where:
●
●
●
●
●
ARRAY_SIZE is the number of entries in OUT_ARRAY. This must
be set prior to calling the function.
DISC_NUM is the number of output lines to be discarded before
capturing starts.
NEXT_OUT is the array item number of the next entry to be set.
LINES_OUT is a return parameter and is set to the number of lines
captured.
OUT_ARRAY is a string array that contains the captured data. The
length, x, should be set to the value of the fifth parameter passed to
the function as described below.
——————————————————————————————————————————
63
——————————————————————————————————————————
——————————————————————————————————————————
●
The value of n, in OCCURS n, indicates the number of lines of
output expected.
The image_name argument is optional. If it is omitted, command output
is printed to the output stream of the current user (the user invoking
$COMMAND).
file
A string indicating the name of a file that is to be automatically opened
by the sdaemon and made the current file before cmd is executed. The
file is opened with the same access privileges the user currently has for
the file. This is an optional parameter.
width
A number indicating the line width to be used for output lines. This is an
optional argument, and it defaults to 80.
Under Sirius Mods version 6.2 and earlier: if this value is not in the
range 1-256, the default is used. Under Sirius Mods version 6.3 and
later: this value can be specified as any value between 1 and the
minimum LOBUFF value for any sdaemon thread in the Online, and if
the value is not a valid number or not in this range, the request is
cancelled.
0
4
8
12
16
20
24
28
32
36
40
-
Command successfully executed
Command processed, errors produced
sdaemon restarted
sdaemon required more input
No sdaemons are running
Out of storage
Specified output image not found
Image not active
Image too short
Image contains invalid data
Invalid file identifier
$COMMAND return codes
——————————————————————————————————————————
64
——————————————————————————————————————————
$COMMAND: Execute Model 204 command on sdaemon, results to image
——————————————————————————————————————————
The following program issues a VIEW command and displays the result at the user's
terminal.
B
IMAGE CMD_OUT
ARRAY_SIZE IS BINARY LEN 4
DISC_NUM
IS BINARY LEN 4
NEXT_OUT
IS BINARY LEN 4
LINES_OUT IS BINARY LEN 4
ARRAY OCCURS 10
OUT_ARRAY IS STRING LEN 80
END ARRAY
END IMAGE
%I IS FIXED DP 0
%RC IS FIXED DP 0
PREPARE IMAGE CMD_OUT
%CMD_OUT:ARRAY_SIZE = 10
%RC = $COMMAND('VIEW',,'CMD_OUT')
FOR %I FROM 1 TO 10
PRINT %CMD_OUT:OUT_ARRAY(%I)
END FOR
END
●
●
●
PRINT '10 lines printed. RC= ' AND %RC
Janus Sockets - as of version 6.1
Janus Web Server - as of version 6.1
Sirius Functions
Products authorizing $COMMAND
——————————————————————————————————————————
65
——————————————————————————————————————————
——————————————————————————————————————————
7.22
$COMMBG: Execute Model 204 commands on
sdaemon
This function allows one or more Model 204 commands to be executed on an sdaemon.
It has two basic modes of operation:
●
“asynchronous” mode is used when the output from the Model 204 commands are
not to be returned into a $list. This is indicated by the absence of the fourth
parameter (the output $list identifier). When a request is initiated in "asynchronous"
mode, $COMMBG returns immediately, before the commands in the input $list are
executed.
●
“synchronous” mode is used when the output from the Model 204 commands are to
be returned into a $list. When a request is initiated in "synchronous" mode,
$COMMBG does not return until all commands in the input $list have been
executed.
The $COMMBG function accepts five arguments and returns a number indicating the
%rc = $COMMBG(inlist, file, descriptor, outlist, msgctl)
$COMMBG Function
inlist
The identifier of a $list that contains the Model 204 commands to be
executed in the sdaemon. If the request is an "asynchronous" request
(outlist argument missing), the contents of this $list are passed to the
sdaemon, and they become no longer available to the invoking program.
This is a required argument. After execution of $COMMBG, this list is
empty.
file
A string indicating the name of a file that is to be automatically opened by
the sdaemon and made the current file before commands in inlist are
executed. This file is opened with the same access privileges the user
currently has for the file. This is an optional parameter.
descriptor
A string identifying the background task. This information used to be
examined via the $BGQUERY function which is now obsolete, so this
parameter is also obsolete — and ignored. This is an optional argument.
outlist
The identifier of a $list to receive the printed output from the Model 204
commands in the input $list. If this optional argument is present,
$COMMBG works in "synchronous" mode: it does not return until all the
Model 204 commands in the input $list have been executed. If this
argument is not present, $COMMBG works in "asynchronous" mode: it
——————————————————————————————————————————
66
——————————————————————————————————————————
$COMMBG: Execute Model 204 commands on sdaemon
——————————————————————————————————————————
returns before any of the Model 204 commands in the input $list are
executed, and the output lines of the background task are placed on the
audit trail as “AD” lines.
Under Sirius Mods version 6.2 and earlier, the output line width was always
set to 255. Under Sirius Mods version 6.3 and later, the output line width is
set to the minimum LOBUFF value for any sdaemon thread in the Online.
msgctl
A number indicating the setting to be used for MSGCTL when running the
commands in the sdaemon. This is an optional parameter, and it defaults
to the user's current MSGCTL setting.
0
4
6
7
8
12
16
20
24
40
-
Request successfully created
Counting errors in sdaemon (synchronous only)
Input $list is empty
sdaemon was restarted (synchronous only)
Insufficient input for sdaemon (synchronous only)
Out of storage
Output $list or CCATEMP full (synchronous only)
$COMMBG return codes
The following program does a PAI dump of file COMPSON in an sdaemon.
B
%LIST
%RC
%RC
%RC
%RC
%RC
%RC
%RC
%RC
END
=
=
=
=
=
=
=
=
$LISTNEW
$LISTADD(%LIST,
$LISTADD(%LIST,
$LISTADD(%LIST,
$LISTADD(%LIST,
$LISTADD(%LIST,
$LISTADD(%LIST,
$LISTADD(%LIST,
'USE OUTFILE')
'B')
'FOR EACH RECORD')
' PRINT ''*''')
' PAI')
'END FOR')
'END')
= $COMMBG(%LIST, 'COMPSON', 'PAI UNLOAD')
——————————————————————————————————————————
67
——————————————————————————————————————————
——————————————————————————————————————————
The following program creates a permanent group called SNOPES and then opens that
group.
B
%ILIST = $LISTNEW
%OLIST = $LISTNEW
%RC
= $LISTADD(%ILIST, 'CREATE PERM GROUP SNOPES FROM FLEM,IKE')
%RC
= $LISTADD(%ILIST, 'PARAMETER PROCFILE=*')
%RC
= $LISTADD(%ILIST, 'END')
%RC
= $COMMBG(%ILIST, , ,%OLIST)
OPEN PERM GROUP SNOPES
END
●
●
●
Sirius Functions
Products authorizing $COMMBG
——————————————————————————————————————————
68
——————————————————————————————————————————
$COMMNDL: Execute Model 204 command on sdaemon, results to $list
——————————————————————————————————————————
7.23
$COMMNDL: Execute Model 204 command on
sdaemon, results to $list
This function allows a Model 204 command to be executed on an sdaemon with the
results captured into a $list. $COMMNDL performs the same function as $COMMAND
except that data is returned to a $list rather than an image.
The $COMMNDL function accepts five arguments and returns a number indicating the
%rc = $COMMNDL(cmd, msgctl, list_id, file, width)
$COMMANDL Function
cmd
A string containing the Model 204 command to be executed. This is a
required argument.
msgctl
A number indicating the setting to be used for MSGCTL when issuing the
command in the sdaemon. This is an optional parameter, and it defaults to
the user's current MSGCTL setting.
list_id
The identifier of the $list that is to receive the command output. This is an
optional parameter; if omitted, command output is placed on the audit trail as
“AD” lines.
file
A string indicating the name of a file that is to be automatically opened by the
sdaemon and made the current file before cmd is executed. This file is
opened with the same access privileges the user currently has for the file.
This is an optional parameter.
width
A number indicating the line width to be used for output lines. This is an
optional argument, and it defaults to 256.
Under Sirius Mods version 6.2 and earlier: if this value is not in the range
1-256, the default is used. Under Sirius Mods version 6.3 and later: this value
can be specified as any value between 1 and the minimum LOBUFF value for
any sdaemon thread in the Online, and if the value is not a valid number or not
in this range, the request is cancelled.
——————————————————————————————————————————
69
——————————————————————————————————————————
——————————————————————————————————————————
0
4
8
12
16
20
36
40
-
Command successfully executed
Command processed, errors produced
sdaemon restarted
sdaemon required more input
Out of storage
Line control settings invalid
Return codes from $COMMNDL
The following program issues a VIEW command and displays the result at the user's
terminal.
B
%LIST = $LISTNEW
%RC = $COMMNDL('VIEW', ,%LIST)
PRINT $LISTINF(%LIST, %I)
END FOR
END
●
●
●
Sirius Functions
Products authorizing $COMMNDL
——————————————————————————————————————————
70
——————————————————————————————————————————
$CONTEXT: Determine if string is name of open file or group
——————————————————————————————————————————
7.24
$CONTEXT: Determine if string is name of open
file or group
The $CONTEXT function allows a user to determine if a string contains the name of an
open file or group.
$CONTEXT accepts one argument and returns a numeric code.
The only argument is the name to be tested. This name can be either:
●
An unqualified name, in which case the standard Model 204 search order (TEMP
GROUP, PERM GROUP, FILE) is used to identify the file or group.
●
A qualified name that explicitly indicates whether $CONTEXT is to act on a file or
group.
If this name is not specified, the default file or group at compile time is used.
Some examples of qualified names follow:
'TEMP GROUP FOO'
'FILE HOHO'
'GROUP KRUSTY'
Note that the last example is not fully qualified, so $CONTEXT first looks for a temporary
group and then a permanent group. If the specified entity is a file that is only open as a
member of a group, $CONTEXT returns a 0 indicating that the file is not open as an
individual file.
%RESULT = $CONTEXT(fgname)
$CONTEXT Function
0 - String does not specify an open file or group
1 - String specifies an open group
2 - String specifies an open file
$CONTEXT return codes
In the following example, %RC is set to 1 if file KRUSTY is open:
%RC = $CONTEXT( 'FILE KRUSTY' )
——————————————————————————————————————————
71
——————————————————————————————————————————
——————————————————————————————————————————
In the following example, %RC is set to 1 if BURNS identifies an open file, 2 if BURNS
identifies an open group, and 0 if it identifies neither:
%RC = $CONTEXT( 'BURNS' )
In the following example, %RC is set to 2 if NUKEM is open as a temporary group, and
set to 0 otherwise:
%RC = $CONTEXT( 'TEMP GROUP NUKEM' )
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $CONTEXT
——————————————————————————————————————————
72
——————————————————————————————————————————
$C2D: Convert binary byte string to integer
——————————————————————————————————————————
7.25
$C2D: Convert binary byte string to integer
The $C2D function returns the integer which is represented by a binary byte string
argument.
$C2D accepts one required and one optional argument and returns a numeric value.
The first argument is the binary byte string to be converted to an integer. If it is omitted
or is the null string, zero is the result.
The second argument is the number of bytes to use from argument one. If this is longer
than argument one, argument one is padded with leading zeroes to this length;
otherwise the rightmost bytes of argument one are used. The default is 5.
The returned result is the integer represented, in binary, by the byte string value of
argument one. This is obtained from the rightmost bytes of the first argument, after any
padding or truncating to the length specified by argument 2. If the length of argument
one is 4 or more, or if argument two is less than or equal to the length of argument one,
these bytes are treated as a signed number; otherwise they are treated as an unsigned
number. A zero is returned for invalid arguments.
%VALUE = $C2D (byte_string, width)
$C2D Function
%VALUE is set to the integer represented by the byte string.
The following program will print the value -1:
B
PRINT $C2D($X2C('FF'), 1)
END
Here are some other results, with the input shown using hexadecimal representation, or
as “''” to indicate the null string:
$C2D(X'09')
$C2D(X'81')
$C2D(X'FF81')
$C2D('')
$C2D(X'81')
$C2D(X'81', 1)
$C2D(X'81', 2)
$C2D(X'FF81', 2)
$C2D(X'FF81', 1)
$C2D(X'FF7F', 1)
$C2D(X'F081', 2)
$C2D(X'F081', 1)
$C2D(X'0031', 0)
$C2D(X'FFFFFFFF')
$C2D(X'FFFFFF')
->
9
->
129
->
65409
->
0
->
129
->
-127
->
129
->
-127
->
-127
->
127
->
-3967
->
-127
->
0
->
-1
-> 16777215
——————————————————————————————————————————
73
——————————————————————————————————————————
——————————————————————————————————————————
$C2D is similar to the standard $UNBIN function (described in the Model 204 User
Language Manual), with some differences, such as being able to specify the input
length in bytes rather than bits, and being able to specify input lengths other than 2 or 4
bytes in length.
The inverse of $C2D is $D2C. See also the $D2X and $X2D functions (in this manual)
and the $C2X and $X2C functions (in the Model 204 User Language Manual).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $C2D
——————————————————————————————————————————
74
——————————————————————————————————————————
$DAEMONMASTERNUMBER: Get user number of master thread
——————————————————————————————————————————
7.26
$DAEMONMASTERNUMBER: Get user number of
master thread
This function can be used to get the user number of an sdaemon's master thread.
The $DAEMONMASTERNUMBER function accepts no arguments. The
$DAEMONMASTERNUMBER function returns the same value as the
$DAEMONPARENTNUMBER function (“$DAEMONPARENTNUMBER: Get user
number of parent thread” on page 76), except in the case where the parent thread, itself,
has a parent. In such a case, the $DAEMONMASTERNUMBER method follows the
chain of parents to the highest level, that is, to the parent that does not, itself, have a
parent.
If the thread issuing $DAEMONMASTERNUMBER is not an sdaemon, or is an sdaemon
but is not performing work for another thread via a Daemon object or a $COMMxx
function, or is an asynchronous daemon, the $DAEMONMASTERNUMBER function
returns a -1 value.
%USERN = $DAEMONMASTERNUMBER
$DAEMONMASTERNUMBER Function
%USERN is set to master's user number, or to -1 if not called from a daemon
The following code audits a thread's master user number:
audit 'My master''s user number is ' $daemonMasterNumber
The $DAEMONMASTERNUMBER method has a Daemon class method equivalent:
MasterNumber (see the Janus SOAP Reference Manual). The $function and method
can be used interchangeably, whether the daemon was created with a $COMMxx
function or a Daemon object, so the decision of which to use is largely a matter of taste.
For more information about sdaemons, see “Sdaemons” on page 5.
●
Sirius Functions
Products authorizing $DAEMONMASTERNUMBER
——————————————————————————————————————————
75
——————————————————————————————————————————
——————————————————————————————————————————
7.27
$DAEMONPARENTNUMBER: Get user number of
parent thread
This function can be used to get the user number of an sdaemon's parent thread.
The $DAEMONPARENTNUMBER function accepts no arguments.
%USERN = $DAEMONPARENTNUMBER
$DAEMONPARENTNUMBER Function
%USERN is set to parent's user number, or to -1 if not called from a daemon
The $DAEMONPARENTNUMBER function returns the user number of the thread that
created the daemon thread, whether the daemon is associated with a Daemon object or
with a $COMMxx function.
If the thread issuing $DAEMONPARENTNUMBER is not an sdaemon, or is an sdaemon
but is not performing work for another thread via a Daemon object or a $COMMxx
function, or is an asynchronous daemon, the $DAEMONPARENTNUMBER function
returns a -1 value. The following code audits a thread's parent user number:
audit 'My parent''s user number is ' $daemonParentNumber
The $DAEMONPARENTNUMBER method has a Daemon class method equivalent:
ParentNumber (see the Janus SOAP Reference Manual). The $function and method
can be used interchangeably, whether the daemon was created with a $COMMxx
function or a Daemon object, so the decision of which to use is largely a matter of taste.
For more information about sdaemons, see “Sdaemons” on page 5.
●
Sirius Functions
Products authorizing $DAEMONPARENTNUMBER
——————————————————————————————————————————
76
——————————————————————————————————————————
$DB_xxx: Janus Open Client $functions
——————————————————————————————————————————
7.28
$DB_xxx: Janus Open Client $functions
There is a set of $functions which are only available with Janus Open Client. Their
names begin with the characters “$DB_” and they are described in the Janus Open
Client Reference Manual.
——————————————————————————————————————————
77
——————————————————————————————————————————
——————————————————————————————————————————
7.29
$DEFLATE: Compress a longstring with Deflate
This function compresses a longstring using the "deflate" algorithm. The deflate
algorithm is described completely in RFC 1951. It is very effective with HTML and XML
data.
The $DEFLATE function accepts two arguments and returns a longstring result.
%LSTRC = $DEFLATE(%lstr, option)
$DEFLATE Function
%LSTRC is the returned longstring.
The first argument is the longstring to be compressed, and it is required.
The second argument is a string that describes the type of compression to perform on
the longstring. This argument is optional; if it is not specified, DYNAMIC compression is
used. Valid options and their meanings are:
FIXED
Indicates that compression is done with fixed codes. The fixed code
tables used for compression (defined as part of RFC 1951) are somewhat
optimized for ASCII character data, but slightly decrease the amount of
CPU required to perform compression. Also, since the codes are already
defined as part of the specification, they are not included in the
compressed data.
DYNAMIC
Indicates that the compression code tables are generated based on the
input data. Dynamic tables typically provide somewhat better
compression on most types of data. There is a very slight CPU overhead
in computing the frequencies of byte values in the input data. Also, since
the code tables are dynamic, they are included as part of the compressed
data. This will increase the size of the compressed longstring, but these
tables are small, since they are also stored in a compressed form.
Usage notes:
●
If an invalid option is passed, or compression is not enabled for the current run, the
request is cancelled.
●
The NCMPBUF parameter must be set by User 0 before the $DEFLATE function
can be used. If $DEFLATE is called with NCMPBUF = 0, the request is cancelled.
●
As with any compression scheme, it is possible that a particular string will become
longer after compression. This would happen, for example, if a deflated string were
passed to $DEFLATE.
——————————————————————————————————————————
78
——————————————————————————————————————————
$DEFLATE: Compress a longstring with Deflate
——————————————————————————————————————————
●
Short strings (less than 128 bytes) will typically compress better with the FIXED
option.
In the following example, %LSTRC is set to the compressed version of the given string:
%LSTRC = $DEFLATE('How much wood could a woodchuck chuck',
'FIXED')
Note: No other string or longstring functions can be usefully performed on the
compressed string until it is decompressed with $INFLATE (“$INFLATE: Decompress a
longstring with inflate” on page 148).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $DEFLATE
——————————————————————————————————————————
79
——————————————————————————————————————————
——————————————————————————————————————————
7.30
$DELCH: Remove characters from string,
compress and strip blanks
This function removes specified characters from an input string and performs blank
compression and stripping.
The $DELCH function accepts four arguments and returns a string result that is part of
the first argument string.
The first argument is an arbitrary string.
The second argument is the set of characters to be removed from the first argument
string.
The third argument is a starting position in the first argument string.
The fourth argument is a number indicating the type of blank compression or stripping to
be performed. Valid numbers and their meanings are:
●
1 - delete the specified characters
●
2 - delete the specified characters and strip leading and trailing blanks
●
3 - delete the specified characters, strip leading and trailing blanks and compress
multiple blanks to a single blank.
This is an optional argument and defaults to 1.
%STRING = $DELCH(string, chars, start_pos, option)
$DELCH Function
%STRING is part of the first argument string.
For example, the following statement sets %JUNK to CD:
%JUNK = $DELCH('ABCDAAAABAB', 'AB')
This statement sets %JUNK to W HAV WAITD LONG NOUGH:
%JUNK = $DELCH(' WE HAVE
WAITED LONG ENOUGH ', 'E', , 3)
And this statement sets %JUNK to WE HAV AITD ONG NOUGH:
%JUNK = $DELCH(' WE HAVE
WAITED LONG ENOUGH ', 'WEL', 5, 3)
——————————————————————————————————————————
80
——————————————————————————————————————————
$DELCH: Remove characters from string, compress and strip blanks
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $DELCH
——————————————————————————————————————————
81
——————————————————————————————————————————
——————————————————————————————————————————
7.31
$DELG_SUBSYS: Delete subsystem-wide global
This function allows a user to delete a Model 204 “global variable” which has a
subsystem-wide scope. Doing this will let the value of the $GETG function or dummy
string (“?&”) substitution for the variable default to the current system-wide or user global
variable with the same name (depending on the scope search order). The order in
which the different scopes of global variables are searched can be controlled using
$SIRPARM parameters: for $GETG, with 'GETGSYS', and for dummy strings, with
'DUMMYSYS'.
The $DELG_SUBSYS function accepts two arguments and returns zero, indicating
success, or a number indicating the cause of error, if there is one.
The first argument is the name of the global variable to be deleted. This is an optional
parameter; it defaults to the null string.
The second argument is the name of the subsystem that the variable is associated with.
This is an optional argument if the $function is invoked from within a subsystem; it
defaults to the null string. A non-null subsystem name is required if the $function is
invoked from outside a subsystem. If invoked from a subsystem and the second
argument is null, the name of the subsystem is used.
System administrator privileges are required to invoke this $function, unless the second
argument is omitted or is the null string, and the $function is invoked from a precompiled
procedure; in that case, no privileges are required, and the subsystem name used is the
active subsystem.
%RC = $DELG_SUBSYS(glob_name, subsys_name)
$DELG_SUBSYS Function
%RC is set to 0 or to an error indicator.
0 - No errors
1 - Not system administrator
3 - Subsystem name missing
$DELG_SUBSYS return codes
Retrieval of subsystem global variables is highly efficient; updates, however, are not, so
use this $function appropriately.
For an explanation of the use of subsystem global variables, see “$SETG_SUBSYS:
Set subsystem-wide global” on page 362. For an explanation of $SIRPARM, see
“$SIRPARM: Set user-specific value, controlling Sirius products” on page 409.
——————————————————————————————————————————
82
——————————————————————————————————————————
$DELG_SUBSYS: Delete subsystem-wide global
——————————————————————————————————————————
●
●
Sirius Functions
Janus Web Server
Products authorizing $DELG_SUBSYS
——————————————————————————————————————————
83
——————————————————————————————————————————
——————————————————————————————————————————
7.32
$DELG_SYS: Delete system-wide global
This function allows a user to delete a Model 204 “global variable” which has a systemwide scope. Doing this will let the value of the $GETG function or dummy string (“?&”)
substitution for the variable default to the current user global variable with the same
name, or it may not affect their results, depending on the scope search order. The order
in which the different scopes of global variables are searched can be controlled using
$SIRPARM parameters: for $GETG, with 'GETGSYS', and for dummy strings, with
'DUMMYSYS'.
The $DELG_SYS function accepts one argument and returns zero, indicating success,
or a number indicating the cause of error, if there is one.
The first argument is the name of the global variable to be deleted. This is an optional
argument; it defaults to the null string.
System administrator privileges are required to invoke this $function.
%RC = $DELG_SYS( glob_name )
$DELG_SYS Function
0 - No errors
$DELG_SYS return codes
Retrieval of system global variables is highly efficient; updates, however, are not, so use
this $function appropriately.
For an explanation of the use of system global variables, see “$SETG_SYS: Set
system-wide global” on page 369. For an explanation of $SIRPARM, see “$SIRPARM:
Set user-specific value, controlling Sirius products” on page 409.
●
●
Sirius Functions
Janus Web Server
Products authorizing $DELG_SYS
——————————————————————————————————————————
84
——————————————————————————————————————————
$DELIMR: Insert delimiter string into input string at regular positions
——————————————————————————————————————————
7.33
$DELIMR: Insert delimiter string into input string
at regular positions
This function inserts a delimiter string into an input string at regular positions. The
$DELIMR function accepts three arguments and returns a string result that is made up of
the first argument string and the delimiters.
The second argument is a delimiter string that is truncated at two characters if longer.
The third argument is a number that indicates the intervals at which to insert the
delimiter string. If this argument is omitted, the delimiter string is not inserted.
%STRING = $DELIMR(string, delim, interval)
$DELIMR Function
%STRING is made up of the first argument string and delim.
For example
%JUNK = $DELIMR('070476', '/', 2)
would set %JUNK to 07/04/76 and
%JUNK = $DELIMR('ABCDEFG', ' ', 1)
would set %JUNK to A B C D E F G.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $DELIMR
——————————————————————————————————————————
85
——————————————————————————————————————————
——————————————————————————————————————————
7.34
$D2C: Binary byte representation of integer
The $D2C function returns a byte string which is the binary equivalent of an integer.
$D2C accepts one required and one optional argument and returns a byte string value.
The first argument is the integer to be converted. If it is omitted, or if after conversion to
an integer it is outside the range -2,147,483,647..2,147,483,647, the null string is the
result.
The second argument is the number of output bytes in the string. If it is omitted, the first
argument must be non-negative, and as many bytes as necessary (1, 2, 3, or 4) are
used as the result. If, after conversion to an integer, argument two is not in the range
0..255, the null string is the result.
The returned result is a byte string representing, in binary, the integer part of argument
one. If argument two is omitted, the result has as many bytes needed to represent (the
non-negative) argument one. Otherwise, the result is sign-extended to as many bytes
as specified in argument two, or truncated. A null string is returned for invalid
arguments.
%RESULT = $D2C(int_val, width)
$D2C Function
%RESULT is set to the width-char binary byte representation of int_val.
The following program will print the value AB:
B
PRINT $D2C(256 * $X2D('C1') + $X2D('C2'))
END
Here are some other results, with the result shown as the hexadecimal representation of
the returned byte string, or as “''” to indicate the null string:
$D2C(9)
$D2C(129)
$D2C(129, 1)
$D2C(129, 2)
$D2C(257, 1)
$D2C(-127, 1)
$D2C(-127, 2)
$D2C(-127)
$D2C(-1, 4)
$D2C(12, 0)
->
->
->
->
->
->
->
->
->
->
X'09'
X'81'
X'81'
X'0081'
X'01'
X'81'
X'FF81'
''
X'FFFFFFFF'
''
$D2C is similar to the standard $BINARY function (described in the Model 204 User
Language Manual), with some differences, such as being able to specify the output
——————————————————————————————————————————
86
——————————————————————————————————————————
$D2C: Binary byte representation of integer
——————————————————————————————————————————
length in bytes rather than bits, and being able to specify results of lengths other than 2
or 4 bytes in length.
The inverse of $D2C is $C2D. See also the $D2X and $X2D functions (in this manual)
and the $C2X and $X2C functions (in the Model 204 User Language Manual).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $D2C
——————————————————————————————————————————
87
——————————————————————————————————————————
——————————————————————————————————————————
7.35
$D2X: Hex representation of integer
The $D2X function returns a string which is the hexadecimal equivalent of an integer.
$D2X accepts two optional arguments and returns a string value.
The first argument is the integer to be converted to hexadecimal. If it is omitted, or if
after conversion to an integer it can't be represented as a 32 bit 2's complement value,
the null string is the result.
The second argument is the number of output characters in the string. If it is omitted,
the output is 8 characters. If, after conversion to an integer, it is 0 or less, or can't be
represented as a 31 bit value, the null string is the result. If it is greater than 8, then the
output is 8 characters. If it is less than 8, then the leftmost digits of the hexadecimal
equivalent are dropped.
%RESULT = $D2X(int_val, width)
$D2X Function
%RESULT is set to the width-char hexadecimal representation of int_val.
The following program will print the value 0C1:
B
PRINT $D2X(193, 3)
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $D2X
——————————————————————————————————————————
88
——————————————————————————————————————————
$E2A: Translate EBCDIC to ASCII
——————————————————————————————————————————
7.36
$E2A: Translate EBCDIC to ASCII
The $E2A function returns a string which is the ASCII equivalent of the (presumed)
EBCDIC input string. $E2A is longstring capable, that is, it can receive an input
longstring and will produce an output longstring.
$E2A accepts one required argument and returns a string value.
The first argument is the string to be translated from EBCDIC to ASCII.
The returned result is a string which is the ASCII equivalent of the (presumed) EBCDIC
input string.
%ASCII = $E2A(ebcdic_val)
$E2A Function
%RESULT is set to the EBCDIC-to-ASCII translation of ebcdic_val.
The inverse of $E2A is $E2A (“$E2A: Translate EBCDIC to ASCII”).
$E2A uses the “standard” EBCDIC-to-ASCII translation tables provided by Sirius, and it
provides no mechanism for overriding these tables.
$E2A is available only in Sirius Mods version 6.8 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $E2A
——————————————————————————————————————————
89
——————————————————————————————————————————
——————————————————————————————————————————
7.37
$EDSCAN: Scan list of entities in online
This function scans the list of defined entities in the online region. Entities can be 204
datasets, sequential files or streams, printers, punches or processes.
The $EDSCAN function accepts four arguments and returns a number indicating the
%RESULT = $EDSCAN(image_name, type, scope, name)
$EDSCAN Function
%RESULT is a 0 or to an error code.
●
The first argument is a string identifying an image to receive returned data. This
image must have the following format :
IMAGE EB_IMAGE
LOOP_VAR
IS BINARY LEN 4
NAME
IS STRING LEN 8
SCOPE
IS STRING LEN 6
TYPE
IS STRING LEN 8
* THIS SECTION USED JUST FOR DATASETS + ALLOCATES
DSNAME
IS STRING LEN 44
DSORG
IS STRING LEN 10
ALLOC
IS STRING LEN 4
DISP
IS STRING LEN 5
* THIS SECTION JUST USED FOR PRINTERS + PUNCHES
CLASS
IS STRING LEN 1
ROUTE
IS STRING LEN 8
ID
IS STRING LEN 8
DIST
IS STRING LEN 8
FORMS
IS STRING LEN 8
* THIS SECTION JUST USED FOR LINKS
TRANSPORT
IS STRING LEN 8 AT DSNAME
PROTOCOL
IS STRING LEN 8
* THIS SECTION JUST USED FOR PROCESSES
DESTINATION IS STRING LEN 8 AT DSNAME
PARTNER
IS STRING LEN 10
MODE
IS STRING LEN 4
* THIS SECTION JUST USED FOR PROCESSGROUPS
LINK
IS STRING LEN 8 AT DSNAME
REMOTEID
IS STRING LEN 8
TERMINAL
IS STRING LEN 8
END IMAGE
ALLOC will return either NEW, OLD or COND and DISP returns either SHARE or
EXCL. This is a required argument.
——————————————————————————————————————————
90
——————————————————————————————————————————
$EDSCAN: Scan list of entities in online
——————————————————————————————————————————
●
The second argument is a string indicating the type of entity for which information is
to be returned. Valid types are
ALLOCATE
Files allocated by the ALLOCATE command.
DATASET
Files defined by the DEFINE DATASET command.
PRINTER
Printers defined by the DEFINE PRINTER command.
PUNCH
Punches defined by the DEFINE PUNCH command.
STREAM
Files defined by the DEFINE STREAM command.
PROCESS
Processes defined by the DEFINE PROCESS command.
This is an optional argument.
●
The third argument is a string indicating the scope of the entities for which
information is to be returned. Valid scopes are 'SYSTEM' and 'USER'. This is an
optional argument. If not specified, all entities are returned.
●
The fourth argument is the name of the entity for which information is to be returned.
This is an optional argument but if it is specified, arguments 2 and 3 are also
required.
In the image indicated by argument 1, LOOP_VAR must be set to the number of entries
matching the selection criterion that are to be skipped. Upon return, $EDSCAN will set
LOOP_VAR to the number of entries skipped plus one if an entity is returned and to the
number of entries skipped if not. Thus, multiple invocations of $EDSCAN without setting
LOOP_VAR will return information on all appropriate entities.
0
4
8
12
16
20
-
Entity found, image set
Entity not found, or off end of chain
Invalid argument 1 or argument 2
Argument 4 specified without argument 2 or 3
Image specified by argument 1 not found
Image specified by argument 1 not active, or too short
$EDSCAN return codes
——————————————————————————————————————————
91
——————————————————————————————————————————
——————————————————————————————————————————
The following program prints the DD and DSNAME of all ALLOCATE'd datasets.
B
IMAGE JUNK
LOOP_VAR IS BINARY LEN 4
...
END IMAGE
PREPARE IMAGE JUNK
REPEAT FOREVER
%RC = $EDSCAN('JUNK', 'ALLOCATE', 'SYSTEM')
IF %RC ¬= 0 THEN
STOP
END IF
PRINT %JUNK:NAME AND %JUNK:DSNAME
END REPEAT
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $EDSCAN
——————————————————————————————————————————
92
——————————————————————————————————————————
$ENT: Do character entity substitution
——————————————————————————————————————————
7.38
$ENT: Do character entity substitution
This function performs character entity substitution on an input string using the default
character entity substitution table or one set by the most recent $ENT_TAB call
(“$ENT_TAB: retrieve/modify character entity substitution table” on page 97).
$ENT accepts one argument and returns a string result.
The first argument is the string on which character entity translation is to be performed.
This is an optional argument though the use of $ENT without this argument is somewhat
silly as it simply returns a null.
%RESULT = $ENT(string)
$ENT Function
%RESULT is set to the value of string with character entity substitution
performed.
Character entity substitution replaces characters that have special meaning to an HTML
or XML processor with their character entity representation. For example, the “<” is
represented as the “<;” character entity. A default character entity substitution table is
provided that does the basic required character entity mappings for HTML and XML of
“&” to “&”, “<” to “<;” and the double quote character to “';”. The active character
entity substitution table can be modified with $ENT_TAB (“$ENT_TAB: retrieve/modify
character entity substitution table” on page 97). The following code
PRINT $ENT('This is < "fun"')
would print This is <; ';fun'; if the default character entity substitution tables are
in effect.
Since character entity substitution always produces a string greater than or equal to the
length of the input string, it is quite possible that a $ENT call will produce a string that is
truncated at 255 bytes. If this is a concern, and the $ENT call is in a PRINT statement
or is assigned to a variable that is ultimately PRINT'ed, it is almost certainly better to
have the character entity substitution occur at either of the following places, because in
these cases the result of the character entity translation is not truncated at 255 bytes:
●
The PRINT statement, as a result of the $ENT_PRINT setting (“$ENT_PRINT: Set
automatic character entity substitution” on page 95)
●
The HTML/TEXT statement, as a result of $ENT_PRINT, ENT_PRINT, or the &
special character after an expression start string
If this is not possible and truncation is a concern, another option is to break the string
undergoing character entity substitution into pieces that are small enough that the
resultant string cannot possibly be longer than 255 bytes. For the default substitution
——————————————————————————————————————————
93
——————————————————————————————————————————
——————————————————————————————————————————
table, this would mean pieces no larger than 255/6 or 42 bytes, since the longest
substitution string is “';” which is 6 bytes long.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ENT
——————————————————————————————————————————
94
——————————————————————————————————————————
$ENT_PRINT: Set automatic character entity substitution
——————————————————————————————————————————
7.39
$ENT_PRINT: Set automatic character entity
substitution
This function retrieves or sets the current automatic character entity substitution setting
for PRINT and HTML/TEXT statements. At the start of every request the $ENT_PRINT
setting is OFF meaning no character entity substitution is done for the output from
PRINT or HTML statements.
$ENT accepts one argument and returns a string result.
The first argument is the new setting of automatic character entity substitution and must
be either
OFF
which means no character entity substitution will be done on PRINT or
HTML/TEXT statement output.
ON
which means character entity substitution will be done on all PRINT and
HTML/TEXT statement output.
VAR
which means character entity substitution will be done only on variable PRINT
and HTML/TEXT statement output, that is anything that is not a string literal or
a static variable in a PRINT statement and anything inside a start/end
expression bracket in an HTML statement.
This is an optional argument and if not specified or specified as null, the current
$ENT_PRINT setting is not altered.
%RESULT = $ENT_PRINT(val)
$ENT_PRINT Function
%RESULT is set to the $ENT_PRINT setting before the call.
Specifying an invalid value for $ENT_PRINT causes request cancellation.
The $ENT_PRINT setting can be overridden in an HTML/TEXT statement by the
ENT_PRINT setting on that statement or by the special * or ! characters following the
expression start string in an expression.
provided which does the basic required character entity mappings for HTML and XML of
“&” to “&”, “<” to “<;” and the double quote character to “';”. The active character
entity substitution table can be modified with $ENT_TAB (“$ENT_TAB: retrieve/modify
character entity substitution table” on page 97).
——————————————————————————————————————————
95
——————————————————————————————————————————
——————————————————————————————————————————
The return value for $ENT_PRINT is the $ENT_PRINT setting before the function call
which makes it easy to save the $ENT_PRINT setting and then restore it. In this
example, $ENT_PRINT is set to 'ON' and then restored to its previous setting.
SUBROUTINE HEADER
%ENT_PRINT IS STRING LEN 32
* I'm too lazy to type all those <;'s
%ENT_PRINT = $ENT_PRINT('ON')
PRINT '<<<<<<<<<<<<<< Header >>>>>>>>>>>>>>'
* But shouldn't mess with $ENT_PRINT setting
%ENT_PRINT = $ENT_PRINT('ON')
Generally, the most useful setting for $ENT_PRINT is VAR because it's hard to be sure
that variable data whether it comes from a database field or from user input doesn't
contain special HTML or XML characters. Literal strings, on the other hand, are likely to
contain XML or HTML tags so should not undergo character entity substitution.
Occasionally, it is useful to place HTML or XML tags in a %variable. If possible, that
variable should be STATIC so a VAR setting for $ENT_PRINT will not modify it. If this is
not possible, it is probably best to use the HTML/TEXT statement where a single
character after the expression start character(s) (an & or a !) can explicitly force or
prevent character entity translation.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ENT_PRINT
——————————————————————————————————————————
96
——————————————————————————————————————————
$ENT_TAB: retrieve/modify character entity substitution table
——————————————————————————————————————————
7.40
$ENT_TAB: retrieve/modify character entity
substitution table
This function retrieves or modifies the current active character entity translation table.
This table is used by $ENT and the PRINT and HTML/TEXT statements when
$ENT_PRINT is set to VAR or ON.
$ENT_TAB accepts one argument and returns a string result.
The first argument is the new entity translation table to be used by $ENT and
$ENT_PRINT. It contains a blank-delimited set of token pairs, the first of each pair
being the character to undergo substitution and the second the entity name to be
substituted. The default substitution string which is set at the start of every request is ‘<
lt & amp " quot’. An ampersand (&) is always placed in front of the entity name and a
semicolon (;) after when substitution is performed so these should not be specified in the
entity name. Alphanumerics characters must be specified as the their hexadecimal
EBCDIC value, for example the “A” character must be specified as “C1”. There is almost
never a need to do character entity substitution for alphanumeric characters but this
capability is provided for completeness. The space or blank character must always be
specified as “40”. Occasionally one might blanks to be represented as non-breaking
spaces, generally indicated by “&nobsp;”. All other characters can be specified by the
EBCDIC character or their hexadecimal values. The first parameter is an optional
parameter and, if not specified $ENT_TAB simply returns the current character entity
translation table.
%RESULT = $ENT_TAB(string)
$ENT_TAB Function
%RESULT is set to the character entity substitution table before the call.
Specifying an invalid substitution table for $ENT_TAB causes request cancellation.
The return value from $ENT_TAB contains no leading or trailing spaces, contains only a
single space between tokens, represents any alphanumeric characters as their
hexadecimal values and all other characters as themselves, even if these characters are
non-displayable. This is the most compact possible representation of a character entity
substitution table so there need be no worries about truncation of the result of a
$ENT_TAB call at 255 characters — the result of the $ENT_TAB call will always be the
same length or shorter than the value used to set the substitution table.
provided which does the basic required character entity mappings for HTML and XML of
“&” to “&”, “<” to “<;” and the double quote character to “';”.
——————————————————————————————————————————
97
——————————————————————————————————————————
——————————————————————————————————————————
The return value for $ENT_TAB is the $ENT_TAB setting before the function call which
makes it easy to save the $ENT_TAB setting and then restore it. In addition, the fact
that a $ENT_TAB without parameters simply returns the current substitution table makes
it easy to add entities to the current table. In this example, the “nobsp” character entity
is added to the current substitution table so that blanks in a converted string will be sent
as non-breaking spaces, ensuring that the string will not be split to different lines:
* Add nobsp to table, save old table
%ENT_TAB = $ENT_TAB( $ENT_TAB WITH ' 40 nobsp')
HTML
Thank you {& %NAME} for visiting our web site.
It is always a pleasure serving you and
{& %COMPANY}
END HTML
* Back to old table
%ENT_TAB = $ENT_TAB(%ENT_TAB)
If a character is specified in the substitution string more than once, the last specification
is used — this makes it easy to temporarily override a character entity substitution using
the above save and restore technique. So in the above example the local code does not
need to worry about whether or not blanks were already undergoing character entity
translation.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ENT_TAB
——————————————————————————————————————————
98
——————————————————————————————————————————
$ERRSET: Increment or clear number of counting errors, set $ERRMSG
——————————————————————————————————————————
7.41
$ERRSET: Increment or clear number of counting
errors, set $ERRMSG
This function allows you to set or clear the current error message (which is returned by
$ERRMSG) and to increment or clear the number of “counting” errors.
The $ERRSET function accepts one argument and returns a number indicating the
current number of counting errors. As of Sirius Mods version 6.8, it is a callable
$function (“CALLing Sirius Mods functions” on page 32).
The first argument is a string indicating the message to be returned by the next
$ERRMSG call. If this argument is omitted or null, the current error message is cleared
and the number of counting errors is set to 0; otherwise the number of counting errors is
incremented.
[%COUNT =] $ERRSET(string)
$ERRSET Function
%COUNT is the number of “counting” errors.
For example
%COUNT = $ERRSET('NASTY ERROR')
%JUNK = $ERRMSG
would set %JUNK to 'NASTY ERROR' and would increment the number of counting
errors.
You can also change the number of counting errors (the Sirius ERCNT parameter) with
“$RESETN: Reset or view M204 parameter” on page 344.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $ERRSET
——————————————————————————————————————————
99
——————————————————————————————————————————
——————————————————————————————————————————
7.42
$FAKEENT: Prepare fake ENTER to automatically
satisfy next full screen read
This function can be used to prepare a "fake" ENTER key. That is, the next full screen
read issued by Model 204 will automatically be satisfied as if the user had simply hit the
ENTER key without entering any data.
The $FAKEENT function accepts no arguments. It returns a 1, if the user is on a valid
full screen terminal; otherwise it returns a 0. As of Sirius Mods version 6.8, it is a
callable $function (“CALLing Sirius Mods functions” on page 32).
[%RC =] $FAKEENT
$FAKEENT Function
%RC is set to either 0 or 1.
This function can be used to build an automatic screen refresh facility. In the following
code fragment, 3 screens are automatically displayed for 1 second each.
%RC = $FAKEENT
READ SCREEN SCREEN1
PAUSE 1
%RC = $FAKEENT
READ SCREEN SCREEN2
PAUSE 1
%RC = $FAKEENT
READ SCREEN SCREEN3
PAUSE 1
●
Sirius Functions
Products authorizing $FAKEENT
——————————————————————————————————————————
100
——————————————————————————————————————————
$FIELD_IMAGE: Return field values into an image
——————————————————————————————————————————
7.43
This function retrieves single-occurrence fields or fields in a repeating group into an
image. It provides an alternative to PAI INTO.
The $FIELD_IMAGE function accepts four arguments and returns a number indicating
the success of the function.
%RC = $FIELD_IMAGE(image_id, occ, options, null_value)
$FIELD_IMAGE Function
%RC is 0 (if occurrence not found) or 1.
●
The first argument must be a string containing the name of an image and, optionally,
an item in the image separated from the image name with a colon. The image and
optional item name can be separated with a blank from an optional fieldname prefix.
If an image item name is specified, that item will be set to the occurrence number
retrieved. This is a required argument.
The specified image must have been defined with the NAMESAVE option. The
image is not allowed to have arrays, cannot have more than 255 items, and cannot
be more than the maximum length of $list items (6124 bytes in Sirius Mods version
6.2 and later, and 4096 bytes long before).
The names of the image items in the specified image are mapped to fields in the
current record context, and then the values of those fields are moved into the image.
●
The second argument is the occurrence number of the fields mapped to the image
to return. This is an optional argument, and it defaults to 1, meaning that the first
ocurrence of the fields will be returned.
●
The third argument is a set of blank-delimited options to affect $FIELD_IMAGE
processing. Valid options are:
MissCan
Cancel the request if not all image items map to field names. If an
occurrence count item is specified in argument one, that item does
not have to map to a field name (if it does, the field value will not be
retrieved anyway). This is the default.
NoMissCan
Don't cancel the request if not all image items map to field names.
Specify NoMissCan if there are image items in the image that are not
associated with fields.
PartCan
Cancel the request if not all image items that map to fields return the
same number of occurrences, that is 0 or 1. This is the default.
——————————————————————————————————————————
101
——————————————————————————————————————————
——————————————————————————————————————————
NoPartCan
Don't cancel the request if not all image items that map to fields
return the same number of occurrences.
In group context, the MissCan/NoMissCan setting applies based on whether the
fields are defined in the group, that is, in any file in the group. If some fields that
map to image items are not found in all files in group context, NoPartCan must be
specified if any fields are to be retrieved.
●
The fourth argument is a value to be converted to null when populating the target
image. This argument is only available in Sirius Mods version 6.3 and later, and it is
discussed at the end of this section.
1 - One or more fields extracted
0 - No fields extracted
All errors result in request cancellation
$FIELD_IMAGE return codes
The target image must be PREPARE'd at the time of the $FIELD_IMAGE call. If the
NoPartCan option is specified, the contents of the image items that are not set from
fields will be whatever they are in the image at the time of the $FIELD_IMAGE call.
In the following example a repeating group with 3 fields is extracted into an image and
then processed.
IMAGE CHILD NAMESAVE
LNAME
IS STRING LEN 16
FNAME
IS STRING LEN 16
SSN
IS PACKED LEN 5
END IMAGE
. . . .
PREPARE IMAGE CHILD
IN FILE FAMILIES FRN %RECNO
FOR %I FROM 1 TO 100
%RC = $FIELD_IMAGE('CHILD', %I)
IF %RC NE 1 THEN
LOOP END
END IF
. . . .
END FOR
END FOR
——————————————————————————————————————————
102
——————————————————————————————————————————
——————————————————————————————————————————
And in the following example, the occurrence number of the group is placed into image
item NUMBER:
LNAME IS STRING LEN 16
FNAME IS STRING LEN 16
SSN IS PACKED LEN 5
NUMBER IS BINARY LEN 2
END IMAGE
. . . .
PREPARE IMAGE CHILD
IN FILE FAMILIES FRN %RECNO
FOR %I FROM 1 TO 100
%RC = $FIELD_IMAGE('CHILD:NUMBER', %I)
IF %RC NE 1 THEN
LOOP END
END IF
. . . .
END FOR
END FOR
$FIELD_IMAGE behaves much as if each individual field value were assigned
individually to its corresponding image item. This means that assignments of nonnumeric field values to a numeric target image item cause the target item to be set to 0.
It also means that in certain cases a “M204.0552: VARIABLE TOO SMALL FOR
RESULT” might be issued.
If the image name and possibly the occurrence number item are specified as literals or
static variables the mapping of image item names to field names is performed at
compile-time and so can be considerably more efficient at evaluation time than a
$FIELD_IMAGE call with a variable image name.
Under Sirius Mods version 6.3 and later the first argument to $FIELD_IMAGE can have
a blank after the image name (and optional occurrence item name) followed by a prefix
to be prepended to each image item name in generating field names. For example,
before Sirius Mods version 6.3, if a file had fields in a repeating group called
ORDERDATA.PRODID, ORDERDATA.QUANTITY and ORDERDATA.PRICE an image
definition used with $FIELD_IMAGE would need to look something like
IMAGE ORDERINFO
ORDERDATA.PRODID
IS STRING LEN 8
ORDERDATA.QUANTITY IS BINARY LEN 4
ORDERDATA.PRICE
IS BINARY LEN 4
END IMAGE
so you could do
%RC = $FIELD_IMAGE('ORDERINFO', %OCC)
which means you'd have “ugly” looking image item names like
——————————————————————————————————————————
103
——————————————————————————————————————————
——————————————————————————————————————————
%ORDERINFO:ORDERDATA.PRODID. By specifying a prefix in the $FIELD_IMAGE
call
%RC = $FIELD_IMAGE('ORDERINFO ORDERDATA.', %OCC)
the image definition could be simplified to
IMAGE ORDERINFO
PRODID
IS STRING LEN 8
QUANTITY IS BINARY LEN 4
PRICE
IS BINARY LEN 4
END IMAGE
so that the image item references like %ORDERINFO:PRODID are much “nicer”.
Under Sirius Mods version 6.3 and later, $FIELD_IMAGE has a fourth argument that
indicates a special value to be treated as a null when populating the target image. This
is useful because storing nulls in fields is problematic on many fronts in Model 204, so
most sites have a special value that acts as a placeholder for a null. Without the fourth
argument to $FIELD_IMAGE, an application would have to go through the image items
to find these placeholder values and convert them to real nulls. Obviously, this is
tedious, error-prone, and can be CPU intensive.
By specifying the null_value argument to $FIELD_IMAGE, this function will automatically
convert the null placeholder to a real null. For example, if the string “_NULL_” is used to
indicate a null value in a file, the following will convert all values of “_NULL_” to a null
before populating the target $list:
%RC = $FIELD_IMAGE('ORDERINFO', , , , '_NULL_')
$FIELD_IMAGE is available in version 6.2 and later of the Sirius Mods.
Starting with version 7.1, the options argument can be specified in any combination of
uppercase and lowercase letters; prior to that, it must be specified in all uppercase
letters.
●
Sirius Functions
Products authorizing $FIELD_IMAGE
——————————————————————————————————————————
104
——————————————————————————————————————————
$FIELD_LIST: Return field values into a $list
——————————————————————————————————————————
7.44
This function retrieves field values from the current record into a $list. It provides an
alternative to PAI INTO.
The $FIELD_LIST function accepts four arguments and returns a number indicating the
The first argument is the output $list identifier. If the output $list is not empty data is
added to the end of the output $list. This is a required argument.
The second argument is the length of the output fieldname in the output $list items and
can be any numeric value from 0 to 255. This is an optional argument and defaults to
255.
The third argument is the name of the field to be returned. This argument can contain a
single specific fieldname or it can contain a wildcard string that matches a number of
fields in the file. This is an optional argument and defaults to “*” which means to return
all fields in the record.
The fourth argument is a set of blank-delimited processing options:
TruncLeft
Truncate fieldnames on the left. This is mutually exclusive with the
TruncRight and CanTrunc options.
TruncRight
Truncate fieldnames on the right. This is mutually exclusive with
the TruncLeft and CanTrunc options.
CanTrunc
Cancel request on truncated fieldname, except when argument 2
(the output fieldname length) is 0. This is mutually exclusive with
the TruncRight and TruncLeft options.
TrueLen
Set true fieldname length rather than truncated fieldname length in
the fieldname length byte in the output $list. This is mutually
exclusive with the TruncLen option.
TruncLen
Set truncated fieldname length in the fieldname length byte in the
output $list; this is the default. This is mutually exclusive with the
TrueLen option.
%RC = $FIELD_LIST(olist, fieldname_len, fieldname, options)
$FIELD_LIST Function
%RC is a number of items added to olist, or it is a negative error code.
——————————————————————————————————————————
105
——————————————————————————————————————————
——————————————————————————————————————————
>= 0 - Number of fields values extracted
-3 - $list full or out of CCATEMP
$FIELD_LIST return codes
Offset
Contents
0-3
A binary sequence number (same as the $list item
number when item added).
4-4
Binary length of fieldname (true or truncated depending
on TrueLen).
5 - 5+N-1
Blank padded or truncated field name where N is value of
argument 2.
5+N - 5+N
Binary length of field value.
5+N+1 - end
Field value in string format as it would be displayed in a
PAI.
Output $list format
Most fieldnames are typically much shorter than 255 bytes so a large amount of $list
space is wasted if the third argument is not specified. If neither TruncLeft nor
TruncRight is specified as an option, a truncated fieldname causes request cancellation
except when the fieldname length is 0 in which case TruncLeft, TruncRight and
CanTrunc are meaningless. Note that you can (bizarrely) specify TrueLen and
fieldname length of 0 which means that while the fieldname will not be returned its length
will.
The name specified in the third argument can be an explicit name or it can contain the
following wildcard characters:
*
?
"
character.
For example, C*D matches “CUSTID”, “COD” or “CLOD”. S??T matches “SALT”,
“SLOT” or “SORT”. E"*CONCRETE matches “E*CONCRETE”.
If a non-wildcard fieldname is specified for argument three and the fieldname does not
exist in the file, $FIELD_LIST simply returns a 0 without scanning the record. If a
——————————————————————————————————————————
106
——————————————————————————————————————————
——————————————————————————————————————————
wildcard fieldname is specified for argument three and the wildcard string does not
match any fieldnames in the file, the record is still scanned. Except in the case of a nonwildcard fieldname that does not exist in the file or a request cancellation because of a
truncated fieldname or $list or CCATEMP full the entire record is always scanned.
The following code fragment retrieves all fields in a record where the fieldname begins
with the letters “CHILD_” into a $list and sorts the $list by fieldname.
IN FILE INFILE FRN %RECNO
%RC = $FIELD_LIST(%OLIST, 'CHILD_*', 20)
END FOR
%SLIST = $LISTSORT(%OLIST, '6,20,A')
$FIELD_LIST is only available in version 6.0 and later of the Sirius Mods.
letters.
●
Sirius Functions
Products authorizing $FIELD_LIST
——————————————————————————————————————————
107
——————————————————————————————————————————
——————————————————————————————————————————
7.45
$FIELD_LISTI: Return field values into a $list
mapped to an image
This function retrieves fields in repeating groups into $list items mapped to an IMAGE. It
provides an alternative to PAI INTO.
The $FIELD_LISTI function accepts six arguments and returns a number indicating the
%RC = $FIELD_LISTI(olist, image_id, start, num, options, null_value)
$FIELD_LISTI Function
%RC is the number of items added to olist.
●
The first argument is the output $list identifier or a -1. If the output $list is not empty,
data is added to the end of the output $list. If -1 is specified, the record is scanned
as if data would be added to the $list, but no data is actually added. This can be
useful for validating the integrity of or number of occurrences of a repeating group
without actually loading its values. This is a required argument.
●
The second argument must be a string containing the name of an image and,
optionally an item in the image separated from the image name with a colon. The
image and optional item name can be separated with a blank from an optional
fieldname prefix. If an image item name is specified, that item will be set to the
occurrence number retrieved.
If this parameter is not specified, or is null, or is simply a colon followed by an image
item name, the image bound to the output $list via $LISTIMG is used as the
mapping image. The specified image must have been defined with the NAMESAVE
option. Also, the image is not allowed to have arrays, cannot have more than 255
items, and cannot be more than the maximum length of $list items (6124 bytes long
in Sirius Mods version 6.2 and later, and 4096 bytes long before).
The names of the image items in the specified image are mapped to fields in the
current record context and then the values of those fields are moved into the image.
●
The third argument is the first occurrence number of the repeating group to return.
This is an optional argument, and it defaults to 1, meaning that the first ocurrence of
the repeating group will be returned.
●
The fourth argument is the maximum number of occurrences of the repeating group
to return. This is an optional argument, and it defaults to 0, meaning that all
occurrences of the repeating group, including and after the one specified by
argument three, will be returned.
——————————————————————————————————————————
108
——————————————————————————————————————————
$FIELD_LISTI: Return field values into a $list mapped to an image
——————————————————————————————————————————
●
The fifth argument is a set of blank-delimited options to affect $LIST_FIELDI
processing. The only valid options are:
MissCan
Cancel the request if not all image items map to field names. If an
occurrence count item is specified in the second argument, that item
does not have to map to a field name (if it does the field value will not
be retrieved anyway). This is the default.
NoMissCan
Don't cancel the request if not all image items map to field names.
Specify NoMissCan if there are image items in the image that are not
associated with fields.
PartCan
Cancel the request if not all image items that map to fields return the
same number of occurrences. This is the default.
NoPartCan
Don't cancel the request if not all image items that map to fields
return the same number of occurrences. If NoPartCan is set and
some image items that map to field occurrences return different
numbers of occurrences, the return code from $FIELD_LISTI will be
the negative of the number of occurrences returned minus 100. For
example, if a partial group is found but 55 occurrences were
returned, the return code would be set to -155.
In group context, the MissCan/NoMissCan setting applies based on whether the
fields are defined in the group, that is, in any file in the group. If some fields that
map to image items are not found in all files in group context, NoPartCan must be
specified if any fields are to be retrieved.
●
The sixth argument is a value to be converted to null when populating the target
$list. This argument is only available in Sirius Mods version 6.3 and later, and it is
discussed at the end of this section.
>= 0
- Number of repeating group occurrences extracted
-3
- CCATEMP full
< -100 - Negative number of repeating group occurrences
extracted minus 100 when partial groups found
$FIELD_LISTI return codes
The template image must be PREPARE'd at the time of the $FIELD_LISTI call. If the
NoPartCan or NoMissCan option is specified, the contents of the parts of the $list that
are associated with image items that are not set from fields will be whatever they are in
the actual image at the time of the $FIELD_LISTI call. The actual contents of the
template image are not modified by the $FIELD_LISTI call.
Except in rare cases, NoPartCan is probably a bad idea since it suggests that the fields
being extracted are not really a repeating group and so shouldn't be grouped. One case
——————————————————————————————————————————
109
——————————————————————————————————————————
——————————————————————————————————————————
where NoPartCan might be useful is in validating the integrity of repeating groups, that
is, making sure that all fields in the group have the same number of occurrences. The
most efficient way to do this is to set the output $list identifier to -1, specify the
NoPartCan parameter, and then check for a negative return code from $FIELD_LISTI.
Note: If -1 is specified for the output $list identifier, no data movement or validation is
performed, which means that if the same operation is performed with a valid output $list
identifier, a VARIABLE TOO SMALL FOR RESULT or some other image assignment
type error might occur, even if the call with a -1 $list identifier produced no such errors.
In the following example, a repeating group with 3 fields is extracted into a $list:
LNAME
IS STRING LEN 16
FNAME
IS STRING LEN 16
SSN
IS PACKED LEN 5
END IMAGE
. . . .
%OLIST = $LISTNEW
PREPARE IMAGE CHILD
IN GROUP FAMILIES FRN %RECNO
%RC = $FIELD_LISTI(%OLIST, 'CHILD')
END FOR
$LISTINFI could then be used to extract the individual occurrences of the repeating
group into the image. And in the following example the occurrence number is placed
into the $list at the position of image item NUMBER in each $list item:
LNAME IS STRING LEN 16
FNAME IS STRING LEN 16
SSN IS PACKED LEN 5
NUMBER IS BINARY LEN 4
END IMAGE
%OLIST = $LISTNEW
PREPARE IMAGE CHILD
IN GROUP FAMILIES FRN %RECNO
%RC = $FIELD_LISTI(%OLIST, 'CHILD:NUMBER')
END FOR
$FIELD_LISTI behaves much as if each individual field value were assigned individually
to its corresponding image item. This means that assignments of non-numeric field
values to a numeric target image item cause the target item to be set to 0. It also means
that in certain cases a “M204.0552: VARIABLE TOO SMALL FOR RESULT” might be
issued.
If the image name and possibly the occurrence number item are specified as literals or
static variables the mapping of image item names to field names is performed at
compile-time and so can be considerably more efficient at evaluation time than a
——————————————————————————————————————————
110
——————————————————————————————————————————
$FIELD_LISTI: Return field values into a $list mapped to an image
——————————————————————————————————————————
$FIELD_LISTI call with a variable image name. Unfortunately, since the binding of an
image to a $list is done at evaluation time there is no way to take advantage of compiletime image item to field mapping when using this binding with $FIELD_LISTI.
Under Sirius Mods version 6.3 and later the second argument to $FIELD_LISTI can
have a blank after the image name (and optional occurrence item name) followed by a
prefix to be prepended to each image item name in generating field names. For
example, before Sirius Mods version 6.3, if a file had fields in a repeating group called
ORDERDATA.PRODID, ORDERDATA.QUANTITY and ORDERDATA.PRICE an image
definition used with $FIELD_LISTI would need to look something like
IMAGE ORDERINFO
ORDERDATA.PRODID
IS STRING LEN 8
ORDERDATA.QUANTITY IS BINARY LEN 4
ORDERDATA.PRICE
IS BINARY LEN 4
END IMAGE
so you could do
%RC = $FIELD_LISTI(%OLIST, 'ORDERINFO')
which means you'd have “ugly” looking image item names like
%ORDERINFO:ORDERDATA.PRODID. By specifying a prefix in the $FIELD_LISTI call
%RC = $FIELD_LISTI(%OLIST, 'ORDERINFO ORDERDATA.')
the image definition could be simplified to
IMAGE ORDERINFO
PRODID
IS STRING LEN 8
QUANTITY IS BINARY LEN 4
PRICE
IS BINARY LEN 4
END IMAGE
so that the image item references like %ORDERINFO:PRODID are much “nicer”.
Under Sirius Mods version 6.3 and later, $FIELD_LISTI has argument 6 which indicates
a special value to be treated as a null when populating the target $list. This is useful
because storing nulls in fields is problematic on many fronts in Model 204 so most sites
have a special value that acts as a placeholder for a null. Without the sixth argument to
$FIELD_LISTI, an application would have to go through the $list items to find these
placeholder values and convert them to real nulls. Obviously, this is tedious, error-prone
and can be CPU intensive.
By specifying the null_value argument to $FIELD_LISTI, this function will automatically
convert the null placeholder to a real null. For example, if the string “_NULL_” is used to
indicate a null value in a file, the following will convert all values of “_NULL_” to a null
before populating the target $list.
%RC = $FIELD_LISTI(%OLIST, 'ORDERINFO', , , , '_NULL_')
——————————————————————————————————————————
111
——————————————————————————————————————————
——————————————————————————————————————————
$FIELD_LISTI is only available in version 6.2 and later of the Sirius Mods.
letters.
●
Sirius Functions
Products authorizing $FIELD_LISTI
——————————————————————————————————————————
112
——————————————————————————————————————————
$FINITIM: File initialization YYDDDMMHHSSTH
——————————————————————————————————————————
7.46
$FINITIM: File initialization YYDDDMMHHSSTH
This function returns the date and time a file was initialized, in YYDDDMMHHSSTH
format.
The $FINITIM function accepts one arguments and returns either a null string or a string
in YYDDDHHMMSSTH format.
The first argument is the name of the file for which initialization date and time is to be
returned. The file must be currently opened by the user.
%TIME = $FINITIM(fname)
$FINITIM Function
%TIME is a null string if the file is not open, or it is it is the date and time that
the file was initialized in YYDDDHHMMSSTH format.
The code fragment
OPEN FILE MYFILE
%TIME = $FINITIM('MYFILE')
sets %TIME to the date and time that file MYFILE was initialized.
●
Sirius Functions
Products authorizing $FINITIM
——————————————————————————————————————————
113
——————————————————————————————————————————
——————————————————————————————————————————
7.47
$FISTAT: Retrieve file's statistics into string
This function allows retrieval of a specific file's statistics into a string.
The $FISTAT function accepts two arguments and returns a string made up of an error
code and returned statistics.
The first argument is a string of blank-delimited words indicating the statistics to be
returned. The length of each returned statistic is always a multiple of 4 bytes. This
facilitates the use of $STATD (“$STATD: Calculate differences and rates for statistics
strings” on page 425) with the returned string. For more information on available
statistics, see the SirMon User's Guide.
The second argument is the file number of the file for which data is to be returned.
%STRING = $FISTAT(stat_list, file_num)
$FISTAT Function
%STRING is made up of binary data, the first 4 bytes of which is an error code.
If the error code is negative, %STRING will only be 4 bytes long.
The data returned by $FISTAT is binary, the first 4 bytes of which contain a return code.
If the return code is negative, only 4 bytes are returned. If the return code is positive, it
contains a number of milliseconds that the online has been up. This provides a
convenient number for calculating rates for the statistics.
With a positive return code, the next 10 bytes contain the blank-padded file name,
followed by 2 bytes that contain the binary file number. This means that the actual data
starts at offset 16 (byte number 17) in the result string.
-5 - Required parameter not specified
-12 - Invalid parameter (argument 2 > NUSERS,
or invalid name in stat_list)
-13 - STAT not linked in
-14 - Result string would be longer than 255 bytes
-15 - File no longer open
$FISTAT return codes
——————————————————————————————————————————
114
——————————————————————————————————————————
$FISTAT: Retrieve file's statistics into string
——————————————————————————————————————————
The following program displays some totals for file 0 (always CCATEMP).
B
%DATA = $FISTAT('DKIO CFRCONF CFRQUEU', 0)
IF $LEN(%DATA) = 4 THEN
PRINT '$FISTAT ERROR... RC = ' WITH $UNBIN(%DATA)
STOP
END IF
PRINT 'FILENAME = ' WITH $SUBSTR(%DATA, 5, 10)
PRINT 'DKIO
= ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) )
PRINT 'CFRCONF = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) )
PRINT 'CFRQUEU = ' WITH $UNBIN( $SUBSTR(%DATA, 25, 4) )
END
●
Sirius Functions
Products authorizing $FISTAT
——————————————————————————————————————————
115
——————————————————————————————————————————
——————————————————————————————————————————
7.48
$FISTATL: Retrieve set of files' statistics into list
This function allows retrieval of statistics for a set of files into a $list.
The $FISTATL function accepts three arguments and returns a numeric error code.
The first argument is the identifier of the $list that is to receive the results. The current
Byte 1-10
Blank padded file name
Byte 11-12
Binary file number
Byte 13-
Returned statistics
The second argument is a string of blank-delimited words indicating the statistics to be
facilitates the use of $STATLD (“$STATLD: Calculate differences and rates for statistics
$lists” on page 427) with the returned $list. For more information on available statistics,
see the SirMon User's Guide.
The third argument is a selection criterion that indicates which files, of all those that are
currently open (by some user or by some subsystem), are to be included in the output
$list. The following criteria are allowed:
FILE=fid
include only files with filenames matching fid (wildcards allowed).
SUBSYS=subsysid
include only files opened by subsystem subsysid. Wildcards are
allowed.
USER=usernum
include only files opened by user usernum.
Actually, all files are always included in the output $list, but the excluded files have the
high order bit of their file numbers turned on. This tells $STATLD to exclude the files
from the difference $list.
%RESULT = $FISTATL(list_identifier, stat_list, criterion)
$FISTATL Function
%RESULT is either a positive number which is the milliseconds since the online
was brought up, or it is a negative error code.
——————————————————————————————————————————
116
——————————————————————————————————————————
$FISTATL: Retrieve set of files' statistics into list
——————————————————————————————————————————
-3
-5
-6
-12
-13
-16
-
CCATEMP is full
STAT not linked in
Invalid selection criterion
$FISTATL return codes
The following program displays some statistics for all files.
B
%LIST = $LISTNEW
%DATA = $FISTATL(%LIST, 'DKIO CFRCONF CFRQUEU')
IF %DATA < 0 THEN
PRINT '$FISTATL ERROR... RC = ' WITH %DATA
STOP
END IF
PRINT 'FILENAME = ' WITH $SUBSTR(%DATA, 1, 10)
PRINT 'DKIO
PRINT 'CFRCONF = ' WITH $UNBIN( $SUBSTR(%DATA, 17, 4) )
PRINT 'CFRQUEU = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) )
PRINT
END FOR
END
●
Sirius Functions
Products authorizing $FISTATL
——————————————————————————————————————————
117
——————————————————————————————————————————
——————————————————————————————————————————
7.49
$FREEOPT: Free optional file or group from
subsystem
The $FREEOPT function allows a user to free an optional file or group from a
subsystem. It is intended as a workaround to the problem that once an optional file or
group is opened in a subsystem, the subsystem holds an enqueue on the file until either
the subsystem or the file is STOP'ped.
$FREEOPT accepts one argument and returns a numeric code. It is also callable
(“CALLing Sirius Mods functions” on page 32).
The only argument is the name of the file or group to be freed. This name can be either
an unqualified name, in which case the standard 204 search order (TEMP GROUP,
PERM GROUP, FILE) will be used to try to identify the file or group; or it can be a
qualified name that explicitly indicates whether $FREEOPT is to act on a file or group.
Some examples of qualified names are
'FILE HOHO'
'GROUP KRUSTY'
Note that the last example is not fully qualified so $FREEOPT will first look for a temp
group and then a perm group if passed this string. Note also that $FREEOPT will not
free a temporary group.
%RESULT = $FREEOPT(fgname)
$FREEOPT Function
0
1
2
3
4
5
6
7
8
9
-
File/group freed
File/group name missing
File/group name invalid
Temp group invalid
Function invalid outside of subsystem
Not a subsystem file or group
Can't free required subsystem file or group
File or group already freed
File or group still open by some user in subsystem
Can't close because saved compiled code accesses
file/group
$FREEOPT return codes
$FREEOPT is mainly intended to be used with procedure files or groups. Any saved
compiled requests that reference a file will prevent $FREEOPT from freeing that file. In
addition, because of the difficulties in determining whether any compiled request
references a group, $FREEOPT will not free any group that might have saved requests
——————————————————————————————————————————
118
——————————————————————————————————————————
$FREEOPT: Free optional file or group from subsystem
——————————————————————————————————————————
compiled against it. This is determined by testing the group's privilege bits in each
subsystem SCLASS for bits that would allow compiled request access (such as FIND
statements, STORE RECORD statements, etc..). The X'2DC6' bit must be off in all
SCLASSes for $FREEOPT to be able to free a group.
The following program frees optional file BURNS from a subsystem:
B
%RC = $FREEOPT( 'BURNS' )
END
●
Sirius Functions
Products authorizing $FREEOPT
——————————————————————————————————————————
119
——————————————————————————————————————————
——————————————————————————————————————————
7.50
$FUNFORC: Cancel running or waiting
Fast/Unload request
This cancels a Fast/Unload request which is either running or enqueued to run.
The $FUNFORC function accepts one argument and returns a numeric result.
The only argument is a string that identifies the request number for the request to be
cancelled. To cancel a request, a user must either have initiated the request or have
system manager privileges. For example, the following code creates an asynchronous
unload request, and then immediately cancels it:
%RC = $FUNLOAD('DATA',..,'ASYNC')
IF %RC GE 0 THEN
%RC = $FUNFORC(%RC)
END IF
%RESULT = $FUNFORC(req_num)
$FUNFORC Function
%RESULT is set either to 0, if the request number req_num was found and
cancelled, or to an error code, if the request could not be found or cancelled.
5 - User does not have privilege to cancel request
6 - Request not found
$FUNFORC Error Codes
$FUNFORC immediately DETACH'es a Fast/Unload task while $FUNPURG allows the
Fast/Unload task to do a "clean" termination. Indiscriminate use of $FUNFORC could
result in certain resources (such as sort work files) being left “in use.&COQ.
$FUNFORC should be used when $FUNPURG cannot purge the request cleanly.
●
Products authorizing $FUNFORC
——————————————————————————————————————————
120
——————————————————————————————————————————
$FUNIMG: Retrieve data from active Fast/Unload request into image
——————————————————————————————————————————
7.51
$FUNIMG: Retrieve data from active Fast/Unload
request into image
This retrieves data from an active Fast/Unload request into an image.
The first argument is the request identifier returned by $FUNLOAD for the request from
which data is to be retrieved. This is a required argument.
The second argument is the image item to which data is to be returned. Data is returned
starting at that image item and continuing to the end of the image or until no more
Fast/Unload data is available in the current record.
%RESULT = $FUNIMG(req_num, image_item)
$FUNIMG Function
%RESULT is set either to the number of bytes returned, or to an error code if
no data was returned.
>0
0
-1
-2
<-2
-
Number of bytes in unloaded record
Fast/Unload completed with return code 0; no more data
Request not found
Invalid image item
Fast/Unload completed with non-zero return code, value
returned is negative of return code; no more data
$FUNIMG Error Codes
If Fast/Unload has not unloaded any records yet, $FUNIMG will wait for the first record.
Each invocation of $FUNIMG skips over the record processed so that the next
invocation will retrieve the next unloaded record.
$FUNIMG's can be mixed with $FUNSKIP and $FUNSSTR calls for the same request.
In addition, multiple unloads can be performed simultaneously with $FUNIMG calls for
the different requests mixed freely.
For example
%REQ = $FUNLOAD('DATA', , , '*')
IF %REQ LE 0 THEN
STOP
END IF
%RC = $FUNIMG( %REQ, %IMAGE:ITEM )
starts an unload request and then returns the first record into image 'IMAGE', starting at
item 'ITEM' in the image. If the record is shorter than the rest of the image (starting at
——————————————————————————————————————————
121
——————————————————————————————————————————
——————————————————————————————————————————
'ITEM'), then only as much data as is in the Fast/Unload record is used to overlay the
image. All other data in the image is left unchanged. If the record is longer than the rest
of the image, the record is truncated before overlaying the image. In all cases, when
%RC is positive, it contains the length of the original Fast/Unload record.
●
Products authorizing $FUNIMG
——————————————————————————————————————————
122
——————————————————————————————————————————
$FUNLIST: $list of active and enqueued Fast/Unload requests
——————————————————————————————————————————
7.52
$FUNLIST: $list of active and enqueued
Fast/Unload requests
This requests a list of active and enqueued Fast/Unload requests. The list is returned to
a $list that can be processed with the $list functions.
The $FUNLIST function accepts one argument and returns a numeric result.
The only argument is a destination $list identifier.
%RESULT = $FUNLIST(list_identifier)
$FUNLIST Function
%RESULT is set either to 0, if the information was added to the $list, or to an
error code if not.
3 - CCATEMP is full
6 - Invalid $list identifier
$FUNLIST Error Codes
Each item in the destination $list has the following format :
Col 1-8
Request number
Col 11-18
Task number running request or blank if request still enqueued
Col 21-30
Userid of request originator
Col 33-40
User number of request originator
Col 43-50
Time request originated
Col 53-60
DDNAME of file being unloaded
For example, this statement sequence displays a list of all active and enqueued
requests.
%LIST = $LISTNEW
%RC = $FUNLIST(%LIST)
IF %RC GE 0 THEN
END FOR
A full screen Fast/Unload request display procedure is provided with the Fast/Unload
distribution. It is called FUNLIST CCAIN in the CMS distribution, and it is member
FUNLIST in the MVS distribution library.
——————————————————————————————————————————
123
——————————————————————————————————————————
——————————————————————————————————————————
●
Products authorizing $FUNLIST
——————————————————————————————————————————
124
——————————————————————————————————————————
$FUNLOAD: Fast/Unload records in Model 204 list or found set
——————————————————————————————————————————
7.53
$FUNLOAD: Fast/Unload records in Model 204
list or found set
This requests an unload of the data in a Model 204 list or found set using Fast/Unload.
If Fast/Unload is not installed at your site, this function returns a -1 error code.
The $FUNLOAD function accepts six arguments and returns a numeric result.
●
The first argument is a string that identifies a found set or a list. This is a required
parameter. If you want to unload records in a found set created with a FIND
statement, pass the label of the found set as the first argument. To unload the
records in a list, specify the name of the list as the first argument.
If you have a FIND statement label and a list with the same name, $FUNLOAD will
use the FIND statement label, unless you explicitly specify that you want to unload a
list by preceding the name of the list with the word LIST. For example, in the
following program the unload at label FUN1 unloads all records found in the FIND
statement at label DATA, while the unload at label FUN2 unloads the records on list
DATA:
DECLARE LIST DATA IN BIGFILE
DATA: IN BIGFILE FIND ALL RECORDS FOR WHICH
.....
END FIND
FUN1: %RC = $FUNLOAD('DATA',...)
FUN2: %RC = $FUNLOAD('LIST DATA',..)
Model 204 FIND statement record locking protects the record sets you are
unloading. For jobs where data consistency is critical, reorganizing a file, for
example, this record locking is essential. For jobs that can tolerate some
inconsistent data, like certain report creation, unlocked record sets (FIND WITHOUT
LOCKS) may be suitable.
You cannot unload records that are not in a found set or a list. For example, you
cannot unload a sorted record set (although you can use sorted output in the FUEL
program that $FUNLOAD runs, as described in the Fast/Unload Reference
Manual).
●
The second argument is either the identifier of a $list or the DDname of an input
program. This argument corresponds to FUNIN in batch mode Fast/Unload. This is
a required parameter.
●
The third argument is either the identifier of the $list that is to receive the
Fast/Unload report data or the DDname of a file that is to receive the Fast/Unload
report data. Note that if you specify the ASYNCH parameter, you cannot specify a
$list identifier for this argument. This argument corresponds to FUNPRINT in batch
mode Fast/Unload. If this parameter is not specified, all report data will go to the
Fast/Unload audit trail.
——————————————————————————————————————————
125
——————————————————————————————————————————
——————————————————————————————————————————
●
The fourth argument, which corresponds to FUNOUT in batch mode Fast/Unload,
specifies the destination for the output data. This argument is required, and it may
be one of the following:
▪
A %variable that identifies the $list that is to receive the unloaded data. If you
use a $list for output, you are allowed only one output stream in the FUEL
program you are invoking. The $list you specify will be the sole output
destination, and any destination names specified in the FUEL program are
ignored.
▪
An asterisk (*), indicating that the unloaded data will be processed with
$FUNIMG, $FUNSKIP, and/or $FUNSSTR. Specifying an asterisk for this
argument implies that the unload is asynchronous, whether or not the ASYNCH
parameter is actually specified.
▪
A string (eight characters at most), which indicates that the output data is to be
sent to the one or more data sets specified in the FUEL program.
Prior to Sirius Mods version 6.5, multiple output data sets are not supported by
the Fast/Unload User Language Interface. This fourth argument must be the
DDname of the destination file for the single output stream specified or implied
in the FUEL program. $FUNLOAD will validate the existence and attempt to
obtain an exclusive enqueue on the output data set.
As of Sirius Mods version 6.5, processing of this argument depends on the
Fast/Unload version:
♦
♦
For Fast/Unload versions prior to 4.2, only a single output stream is
supported, and processing is as described above for Sirius Mods prior to
version version 6.5..
For Fast/Unload 4.2 and higher, multiple output data sets are supported,
and this argument string serves as a placeholder only, indicating that the
output data is to be sent to the one or more data sets specified in the FUEL
program. Fast/Unload will validate the existence and attempt to obtain an
exclusive enqueue on all output data sets specified or implied in the FUEL
program.
●
The fifth argument is a string that specifies the Fast/Unload parameters. This string
can contain any of the parameters allowed on the PARM option on the EXEC card
for batch mode Fast/Unload and can, in addition, contain the parameters ASYNCH,
ALLMSG and NOTIFY. The description of parameters in the Fast/Unload
Reference Manual shows the default parameter values, showing any differences
when invoked via the Fast/Unload User Language Interface.
●
The sixth argument is a number indicating the maximum amount of time in seconds
that the request is to be allowed to complete. If the $FUNLOAD request does not
complete within this time, the $FUNLOAD request is immediately cancelled. The
User Language request is not cancelled in such a case, but, for synchronous
——————————————————————————————————————————
126
——————————————————————————————————————————
——————————————————————————————————————————
requests, the $FUNLOAD returns a 32. This is an optional argument and, if not
specified, defaults to the FUNMAXT system parameter setting.
An explicit or default value of 0 means that there will be no time limit placed on the
request. This argument is only available in Sirius Mods version 6.7 and later.
Before that, no time limits were placed on any $FUNLOAD requests.
Note that the time limit includes the time waiting for the request to actually be run by
a Fast/Unload task, so a request could time out because of other long-running
requests tying up the Fast/Unload tasks.
7.53.1 Syntax and error codes
%RESULT = $FUNLOAD(found_set, funin, funprint, funout,
[parms], [timelimit])
-
$FUNLOAD Function
%RESULT is set to the return code from Fast Unload, to the positive request
number for asynchronous requests, or to a negative number if Fast/Unload is
unable to process the request.
-1
-2
-3
-4
-5
-11
-12
-13
-
Fast/Unload PST not available
Input/report/output DDname in use
Ran out of CCATEMP or free storage
Input/report/output DDname not found
Invalid found set specified
Invalid input/report/output descriptor specified
Conflicting parameters
$FUNLOAD Error Codes
In addition to the above error codes, if $FUNLOAD discovers that a required capability is
not supported by the version of Fast/Unload in use, the User Language request is
cancelled with an error message indicating the missing capability. If any missing
capabilities which would prevent successful $FUNLOAD operation are discovered during
Model 204 initialization, an operator warning is issued and saved in the VIEW ERRORS
table, so that corrective action may be taken in advance.
Under Sirius Mods version 6.7 and later, if the X'01' bit is set in the system FUNPARM
parameter, the request will be cancelled if a $FUNLOAD is issued in the middle of an
updating transaction. Whether or not FUNPARM X'01' is set, it is generally best to avoid
$FUNLOAD calls in the middle of an updating transaction, since $FUNLOAD calls can
take a long time to run, even if the specific $FUNLOAD request is relatively small. This
is so because all $FUNLOAD requests share the same FUNTSKN subtasks, and if these
are tied up with relatively long-running requests, all other requests must wait for access
to a Fast/Unload task.
——————————————————————————————————————————
127
——————————————————————————————————————————
——————————————————————————————————————————
To make it easier to diagnose problems where Fast/Unload User Language Interface is
involved, under Sirius Mods version 6.7 and later, messages are also sent to the
Model 204 journal/audit trail at each Fast/Unload request made and at each completed
by the Fast/Unload User Language Interface. The message when the requests are
started look like:
MSIR.0890: Asynchronous request 2 made by $funload
And the message when the requests are completed look like:
MSIR.0891: Asynchronous request 2 completed, RC = 0
●
Products authorizing $FUNLOAD
7.53.2 Examples
In the following example, the Fast/Unload input data is in DDname FUNIN, the report is
to go to DDname FUNPRINT and the data is to be unloaded to DDname FUNOUT.
B
FIND1: FIND ALL RECORDS IN COMICS FOR WHICH
NAME = 'SIMPSON'
END FIND
%RC = $FUNLOAD('FIND1', 'FUNIN', 'FUNPRINT', 'FUNOUT', 'NOBUFF=6')
IF %RC NE 0 THEN
PRINT 'ERROR PERFORMING FAST UNLOAD... RC =' AND %RC
END IF
END
In the following example, we dynamically build the unload input program, have the report
data simply go to the Fast/Unload audit trail, and have the data unloaded to a $list.
——————————————————————————————————————————
128
——————————————————————————————————————————
——————————————————————————————————————————
BEGIN
%LIST1 =
%LIST2 =
%RC
%RC
%RC
%RC
%RC
=
=
=
=
=
$LISTNEW
$LISTNEW
$LISTADD(
$LISTADD(
$LISTADD(
$LISTADD(
$LISTADD(
%LIST1,
%LIST1,
%LIST1,
%LIST1,
%LIST1,
'FOR EACH RECORD' )
' PUT ''*''' )
' OUTPUT' )
' PAI' )
'END FOR' )
FIND1: IN CLOWNS FIND ALL RECORDS FOR WHICH
TRADEMARK = 'PRATFALL'
END FIND
%RC = $FUNLOAD( 'FIND1', %LIST1, , %LIST2)
.
.
.
.
.
.
.
.
.
.
END
In the following example, the input FUEL program is contained in procedure 'UNLOAD1'
in the Model 204 procedure file called 'FUELPROC'. The data is processed with
$FUNIMG calls (not shown).
BEGIN
DECLARE LIST HOHO IN BIGFILE
.
.
.
.
.
.
.
.
.
.
%REPLIST = $LISTNEW
%RECORDS = 'LIST HOHO'
%INLIST = $LISTNEW
%RC = $PROCOPN('UNLOAD1','FUELPROC')
%RC = $PROCDAT(%INLIST)
%OPTIONS = 'NEBUFF=4,NBBUFF=2,UPPER,ALLMSG'
%RC = $FUNLOAD( %RECORDS, %INLIST, , '*', %OPTIONS )
.
.
.
.
.
.
.
.
.
.
END
——————————————————————————————————————————
129
——————————————————————————————————————————
——————————————————————————————————————————
The following is an example of an asynchronous unload request. The input program is
in DDname FUNIN, the report data is to go to the Fast/Unload audit trail, and the data is
to be dumped to DDname OUTFILE.
BEGIN
FINDX: IN MOVIES FIND ALL RECORDS FOR WHICH
DIRECTOR = 'HITCHCOCK'
END FIND
%OPTIONS = 'ASYNCH ALLMSG NOBUFF=8'
%RC = $FUNLOAD( 'FINDX', 'FUNIN', , 'OUTFILE', %OPTIONS )
IF %RC > 0 THEN
PRINT 'FAST UNLOAD REQUEST ACCEPTED,' AND 'REQUEST NUMBER =' WITH %RC
ELSE
PRINT 'FAST UNLOAD REQUEST REJECTED,' AND 'ERROR CODE =' AND %RC
END IF
END
——————————————————————————————————————————
130
——————————————————————————————————————————
$FUNPURG: Purge running or waiting Fast/Unload request
——————————————————————————————————————————
7.54
$FUNPURG: Purge running or waiting
Fast/Unload request
This purges a Fast/Unload request which is either running or enqueued to run.
The $FUNPURG function accepts one argument and returns a numeric result.
The only argument is a string that identifies the request number for the request to be
purged. To purge a request, a user must either have initiated the request or have
system manager privileges. For example, the following code creates an asynchronous
unload request, and then immediately purges it:
%RC = $FUNLOAD('DATA',..,'ASYNC')
IF %RC GE 0 THEN
%RC = $FUNPURG(%RC)
END IF
%RESULT = $FUNPURG(req_num)
$FUNPURG Function
%RESULT is set to 0 if the request number req_num was found and purged, or
it is set to an error code if the request could not be found or purged.
5 - User does not have privilege to purge request
6 - Request not found
$FUNPURG Error Codes
●
Products authorizing $FUNPURG
——————————————————————————————————————————
131
——————————————————————————————————————————
——————————————————————————————————————————
7.55
$FUNSKIP: Skip to next output record for
$FUNIMG, $FUNSSTR
This skips the current Fast/Unload output record for a request so that subsequent
$FUNIMG and $FUNSSTR calls will operate on the next record.
The $FUNSKIP function accepts one argument and returns a numeric result.
The only argument is the request identifier returned by $FUNLOAD for the request from
which data is to be retrieved. This is a required argument.
%RESULT = $FUNSKIP(req_num)
$FUNSKIP Function
%RESULT is set to 1, or it is set to an error code if there is no record to skip.
1
0
-1
<-1
-
Record skipped
Fast/Unload completed with return code 0; no more data
Request not found
Fast/Unload completed with non-zero return code, value
returned is negative of return code; no more data
$FUNSKIP Error Codes
If Fast/Unload has not unloaded any records yet, $FUNSKIP will wait for the first record.
If $FUNSKIP returns a value less than or equal to 0, the request has completed.
$FUNSKIPs can be mixed with $FUNSSTR and $FUNIMG calls for the same request.
In addition, multiple unloads can be performed simultaneously with $FUNSKIP calls for
the different requests mixed freely.
——————————————————————————————————————————
132
——————————————————————————————————————————
$FUNSKIP: Skip to next output record for $FUNIMG, $FUNSSTR
——————————————————————————————————————————
The following example compares the first two bytes of each unloaded record with 'XX'. If
they are equal, the record is copied into image 'IMAGE' and then processed; otherwise
the record is simply skipped.
IF %REQ LE 0 THEN
STOP
END IF
%RC = 1
REPEAT WHILE %RC > 0
%TEST = $FUNSSTR( %REQ, 1, 2)
IF %TEST EQ 'XX' THEN
%RC = $FUNIMG( %REQ, %IMAGE:ITEM )
CALL PROCESS
ELSE
%RC = $FUNSKIP
END IF
END REPEAT
●
Products authorizing $FUNSKIP
——————————————————————————————————————————
133
——————————————————————————————————————————
——————————————————————————————————————————
7.56
$FUNSSTR: Retrieve data from active
Fast/Unload request into string
This retrieves data from an active Fast/Unload request into a string.
The $FUNSSTR function accepts three arguments and returns a string result.
●
The first argument is the request identifier returned by $FUNLOAD for the request
from which data is to be retrieved. This is a required argument.
●
The second argument is the column number in the current Fast/Unload record from
which data is to be retrieved.
●
The third argument is the maximum number of bytes of data to be retrieved from the
current Fast/Unload record.
%STRING = $FUNSSTR(req_num, start, len)
$FUNSSTR Function
%STRING is set to the contents of the current Fast/Unload record for the
request, or to a null if there is some error.
If Fast/Unload has not unloaded any records yet, $FUNSSTR will wait for the first record.
Each invocation of $FUNSSTR (with the same request number) operates on the same
record, so a record longer than 255 bytes long can be split into multiple strings. To
adjust the Fast/Unload record pointer to the next record, $FUNSKIP or $FUNIMG must
be used. If there are no more records left from Fast/Unload, $FUNSSTR will return a
null. In this case, $FUNSKIP or $FUNIMG should be called to obtain the Fast/Unload
return code and clean up after the request.
$FUNSSTRs can be mixed with $FUNSKIP and $FUNIMG calls for the same request.
In addition, multiple unloads can be performed simultaneously, and $FUNSSTR calls for
the different requests can be mixed in freely.
In the following example, the first 20 bytes of each unloaded record is assigned to
%VAR1, the second 20 bytes to %VAR2, and this data is processed with subroutine
PROCESS.
——————————————————————————————————————————
134
——————————————————————————————————————————
$FUNSSTR: Retrieve data from active Fast/Unload request into string
——————————————————————————————————————————
IF %REQ LE 0 THEN
STOP
END IF
%RC = 1
REPEAT WHILE %RC > 0
%VAR1 = $FUNSSTR( %REQ, 1, 20)
%VAR2 = $FUNSSTR( %REQ, 21, 20)
IF %VAR1 EQ '' THEN
CALL PROCESS( %VAR1, %VAR2)
END IF
%RC = $FUNSKIP
END REPEAT
If any record is shorter than 40 bytes in the preceding example, %VAR1 and %VAR2 are
truncated as appropriate. If a record were only 20 bytes long, %VAR1 would be 20
bytes and %VAR2 would be null. If a record were 60 bytes long, both %VAR1 and
%VAR2 would be 20 bytes long. If a record were 10 bytes long, %VAR1 would be 10
bytes long and %VAR2 would be null.
Note that after the last record is processed, $FUNSSTR always returns a null. At that
point, $FUNSKIP should still be called once to obtain the Fast/Unload return code and
clean up after the request.
●
Products authorizing $FUNSSTR
——————————————————————————————————————————
135
——————————————————————————————————————————
——————————————————————————————————————————
7.57
$FUNWAIT: Wait until asynchronous Fast/Unload
request completes
This requests that the user wait until an asynchronous Fast/Unload request is
completed.
The $FUNWAIT function accepts one argument and returns a numeric result.
The only argument is a string that identifies the request number to be waited on. To wait
on a request, the user must have initiated the request.
In the following example, two ASYNCH Fast/Unload requests are placed and then their
completion is waited for. If FUNTSKN is 2 or greater, these requests can run in parallel.
%RNUM1 = $FUNLOAD('DATA1',..,'ASYNC')
IF %RNUM1 < 0 THEN
JUMP TO FUNERR
END IF
%RNUM2 = $FUNLOAD('DATA2',..,'ASYNC')
IF %RNUM2 < 0 THEN
%RC = $FUNPURG(%RNUM1)
JUMP TO FUNERR
END IF
%RC1 = $FUNWAIT(%RNUM1)
%RC2 = $FUNWAIT(%RNUM2)
END IF
%RESULT = $FUNWAIT(req_num)
$FUNWAIT Function
%RESULT is set to the return code from Fast/Unload, or it is set to -1 if the
request cannot be found.
-1 - request not found
$FUNWAIT Error Codes
●
Products authorizing $FUNWAIT
——————————————————————————————————————————
136
——————————————————————————————————————————
$GUNZIP: Decompress a longstring with GUNZIP
——————————————————————————————————————————
7.58
$GUNZIP: Decompress a longstring with GUNZIP
This function extracts information from a GZIP-format longstring.
The $GUNZIP function accepts two arguments and returns a longstring result.
%lstrc = $gunzip(%lstr, type)
$GUNZIP Function
%lstrc is the returned longstring.
The first argument, the longstring to be decompressed, is required. The string must be
in GZIP format.
The second argument is a string indicating what information should be extracted from
the GZIP-format longstring. This argument is optional; if it is not specified, DATA is
assumed, and the longstring is decompressed into the result longstring. Valid options
and their meanings are:
DATA
Indicates that the data in the GZIP longstring is extracted. This is the default.
TIME
Indicates that the date and time, known as the “modification time,” is returned
(in the form YYYY-MM-DD HH:MI:SS).
NAME
Indicates that the internal name of the GZIP entity is returned in the result. If
no internal name is present, the null string is returned.
Usage notes:
●
If an invalid option is passed, or if compression is not enabled for the current run,
the request is cancelled.
●
The NCMPBUF parameter must be set by User 0 before the $GZIP function can be
used. If $GUNZIP is called with NCMPBUF = 0, the request is cancelled.
In the following example, %ls is set to the uncompressed version of the given string
The DATA value default is implied, since no second argument is given.
%ls = $gunzip(%lsgz)
In the following example, %dt is set to the last modification date and time of the file
contained in the GZIP longstring.
%dt = $gunzip(%lsgz, 'TIME')
Note: GZIP-format files can be created with the function $GZIP (“$GZIP: Compress a
longstring with GZIP” on page 139), as well as other file compression utilities.
——————————————————————————————————————————
137
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $GUNZIP
——————————————————————————————————————————
138
——————————————————————————————————————————
$GZIP: Compress a longstring with GZIP
——————————————————————————————————————————
7.59
$GZIP: Compress a longstring with GZIP
This function compresses a longstring using the "deflate" algorithm. The deflate
algorithm is described completely in RFC 1951. The GZIP format is described in RFC
1952. It is very effective with HTML and XML data.
The $GZIP function accepts four arguments and returns a longstring result.
%lstrc = $gzip(%lstr, level, filename, datetime)
$GZIP Function
%lstrc is the returned longstring.
The first argument is the longstring to be compressed, and it is required.
The second argument is a string or integer value that describes the type of compression
to perform on the longstring. This argument is optional; if it is not specified, DYNAMIC
(type 2) compression is used. Valid options and their meanings are:
FIXED
Indicates that compression is done with fixed codes. The fixed code
tables used for compression (defined as part of RFC 1951) are somewhat
optimized for ASCII character data, but slightly decrease the amount of
CPU required to perform compression. Also, since the codes are already
defined as part of the specification, they are not included in the
compressed data.
DYNAMIC
Indicates that the compression code tables are generated based on the
input data. Dynamic tables typically provide somewhat better
compression on most types of data. There is a very slight CPU overhead
in computing the frequencies of byte values in the input data. Also, since
the code tables are dynamic, they are included as part of the compressed
data. This will increase the size of the compressed longstring, but these
tables are small, since they are also stored in a compressed form.
0-6
Indicates the type of compression used. Specifying 0 indicates the
default should be used, which is the same as specifying DYNAMIC.
Values 1 through 6 specify a tradeoff in speed and compression factor:
The value 1 uses the least CPU and compresses the string quickly; the
value 6 uses the most CPU but gets the best compression. Higher
numbers may increase the CPU considerably without significantly
improving the compression.
The third argument, an optional string, contains the internal name of the compressed
string. Decompression programs will use this name for the output file when the string is
un-zipped. The maximum length of the filename is 32 bytes.
——————————————————————————————————————————
139
——————————————————————————————————————————
——————————————————————————————————————————
The fourth argument, an optional string, contains the file modification date and time.
This must be a string in the format YYYY-MM-DD HH:MI:SS or YY-MM-DD HH:MI:SS.
If a two-digit year is supplied, the CENTSPAN (“CENTSPAN” on page 534) value used
is 75.
Usage notes:
●
If an invalid option is passed, or if compression is not enabled for the current run,
the request is cancelled.
●
The NCMPBUF parameter must be set by User 0 before the $GZIP function can be
used. If $GZIP is called with NCMPBUF = 0, the request is cancelled.
●
passed to $GZIP.
●
Short strings (less than 128 bytes) will typically compress better with the FIXED
option.
●
Multiple files are not currently supported.
In the following example, %lsgz is set to the compressed version of the given
string:
%ls = 'I''ve got sunshine on a cloudy day'
%dt = $date and $time
%lsgz = $gzip(%ls, 6, 'mygirl.txt', %dt)
Note: No other string or longstring functions (except copy) can be usefully
performed on the compressed string until it is decompressed with $GUNZIP
(“$GUNZIP” on page 137).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $GZIP
——————————————————————————————————————————
140
——————————————————————————————————————————
$HEXA: Convert hexadecimal string to EBCDIC equivalent
——————————————————————————————————————————
7.60
$HEXA: Convert hexadecimal string to EBCDIC
equivalent
This function converts a hexadecimal string to its EBCDIC equivalent.
The $HEXA function accepts one argument and returns a string result.
The first argument is a string containing the characters 0 - 9 and A - F. All other
characters are treated as 0. If the number of characters in the first argument is odd, the
first argument is considered to begin with an extra 0 character.
%EBCDIC = $HEXA(hex_string)
$HEXA Function
%EBCDIC is set to the EBCDIC equivalent of hex_string.
For example, in
%JUNK = $HEXA('F1F2F3')
%JUNK would be set to the string '123' (EBCDIC X'F1F2F3'), and in
%JUNK = $HEXA('102')
%JUNK would be set to EBCDIC X'0102' which is a non-displayable string.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $HEXA
——————————————————————————————————————————
141
——————————————————————————————————————————
——————————————————————————————————————————
7.61
$IHEXA: Convert EBCDIC string to hexadecimal
equivalent
This function converts an EBCDIC string to its hexadecimal equivalent.
The $IHEXA function accepts one argument and returns a string result that is the
hexadecimal representation of the first argument.
%HEX = $IHEXA(string)
$IHEXA Function
%HEX is set to the hexadecimal equivalent of string.
For example, in
%JUNK = $IHEXA('ABabc')
%JUNK would be set to the string C1C2818283, and in
%JUNK = $IHEXA(' 1 ')
%JUNK would be set to the string 40F140. Because the result string can be at most
255 bytes long and the result string is always twice as long as the input string, any input
string longer than 127 bytes, will produce a 254 byte result string representing the first
127 characters in the input string.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $IHEXA
——————————————————————————————————————————
142
——————————————————————————————————————————
$IMGINF: Retrieve image item by variable name
——————————————————————————————————————————
7.62
$IMGINF: Retrieve image item by variable name
This function returns a string containing the current value of a specified image item. All
errors cause request cancellation.
The $IMGINF function accepts two arguments and returns a string result.
The first argument is either a string that contains an image name or any image item in
the source image. If an image item is specified, only the image portion is relevant for
this function since the second argument indicates the actual item from which data is to
be extracted. Nevertheless, it is more efficient to specify an image item rather than an
image name unless the image name itself is to be variable at run time. This is because
an image name must be hashed and then NTBL must be searched for the hash value,
both moderately expensive operations. This is a required parameter.
The second argument is a string that contains the name of the image item from which
the value is to be retrieved. This is a required parameter.
%RESULT = $IMGINF(image_identifier, item_name)
$IMGINF Function
%RESULT is a string that contains the value of the image item specified by
item_name in the image specified by image_identifier.
$IMGINF is provided to get around the fact that Model 204 has no support for image
name variables in the way it has support for screen name variables. That is, if the image
or image item from which data is to be extracted is unknown at compile time, $IMGINF
can be used to retrieve the image data based on values set at evaluation time. For
example
%NAME = $IMGINF(%RECTYPE, 'NAME')
extracts the value of an image item called “NAME” from the image associated with the
variable %RECTYPE.
%DATA = $IMGINF(%BIGIMG:ID, %FIELD)
extracts the value of an image item whose name is indicated by %FIELD from the image
BIGIMG.
Obviously, if both image and item name are knowd at evaluation time a simple
assignment should be performed as in
%DATA = %BIGIMG:CUSTID
——————————————————————————————————————————
143
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $IMGINF
——————————————————————————————————————————
144
——————————————————————————————————————————
$IMGOVL: Replace image item value
——————————————————————————————————————————
7.63
$IMGOVL: Replace image item value
The $IMGOVL function accepts three arguments and returns a 0. All errors cause
request cancellation.
The first argument is either a string that contains an image name or any image item in
the source image. If an image item is specified, only the image portion is relevant for
this function since the second argument indicates the actual item that is to be updated.
Nevertheless, it is more efficient to specify an image item rather than an image name
unless the image name itself is to be variable at run time. This is because an image
name must be hashed and then NTBL must be searched for the hash value, both
moderately expensive operations. This is a required parameter.
The second argument is a string that contains the name of the image item that is to be
updated. This is a required parameter.
The third argument is a value that is to be assigned to the indicated image item. This is
a required parameter.
%RESULT = $IMGOVL(image_identifier, item_name, value)
$IMGOVL Function
%RESULT is always set to 0.
$IMGOVL is provided to get around the fact that Model 204 has no support for image
name variables like it has support for screen name variables. That is, if the image or
image item that is to be updated is unknown at compile time, $IMGOVL can be used to
update the image data based on values set at evaluation time. For example
%RC = $IMGOVL(%RECTYPE, 'NAME', %NAME)
updates the value of an image item called “NAME” from the image associated with the
variable %RECTYPE.
%RC = $IMGOVL(%BIGIMG:ID, %FIELD, %VALUE)
updates the value of an image item whose name is indicated by %FIELD from the image
BIGIMG.
Obviously, if both image and item name are known at evaluation time a simple
assignment should be performed as in
%BIGIMG:CUSTID = %DATA
——————————————————————————————————————————
145
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $IMGOVL
——————————————————————————————————————————
146
——————————————————————————————————————————
$INCSTAT: Increment local system statistic
——————————————————————————————————————————
7.64
$INCSTAT: Increment local system statistic
This function allows a user to increment the current value of a local system statistic.
There are 10 local system statistics that can be incremented with $INCSTAT. These
stats can be examined via $SYSTAT under the names LOCAL0 through LOCAL9.
The $INCSTAT function accepts two arguments and returns either the new value of the
appropriate local statistic or a 0 if there is an error.
The first argument is a number that indicates the local stat number to be incremented.
This number must be 0 through 9. Otherwise, the $INCSTAT performs no action and
returns a 0.
The second argument is a number that indicates the value that will be added to the local
stat. This is an optional argument and defaults to 1.
%VALUE = $INCSTAT(stat_num, value)
$INCSTAT Function
%VALUE is set to either 0 or value.
For example, the code fragment
%VALUE = $INCSTAT(2)
adds 1 to local stat number 2.
●
●
Sirius Functions
SirMon
Products authorizing $INCSTAT
——————————————————————————————————————————
147
——————————————————————————————————————————
——————————————————————————————————————————
7.65
$INFLATE: Decompress a longstring with inflate
This function takes a deflated longstring input and decompresses it using the "inflate"
algorithm. The inflate algorithm is described as part of the deflate specification in RFC
1951.
The $INFLATE function accepts one argument and returns a longstring result. The
argument is the longstring to be decompressed, and it is required.
%LSTRC = $INFLATE(%lstr, option)
$INFLATE Function
%LSTRC is the returned longstring.
Usage notes:
●
If the input string is not a valid deflated string, the request is cancelled.
●
If compression is not enabled for the current run, the request is cancelled.
●
The NCMPBUF parameter must be set by User 0 before the $INFLATE function can
be used. If $INFLATE is called with NCMPBUF = 0, the request is cancelled.
●
passed to $DEFLATE (“$DEFLATE: Compress a longstring with Deflate” on page
78).
In the following example, %LSTR is set to the uncompressed version of the given string:
%LSTRC = $DEFLATE('How much wood could a woodchuck chuck',
'FIXED')
%LSTR = $INFLATE(%LSTRC)
●
●
●
●
●
●
●
●
-
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $INFLATE
——————————————————————————————————————————
148
——————————————————————————————————————————
$JOBAUTH: Determine if user has authorization for USE $JOB
——————————————————————————————————————————
7.66
$JOBAUTH: Determine if user has authorization
for USE $JOB
This function can be used to determine if the running user has authorization to issue the
USE $JOB command.
The $JOBAUTH function accepts no arguments and returns either a 0 if the user is not
authorized to use $JOB or a 1 if the user is authorized to use $JOB.
%AUTH = $JOBAUTH
$JOBAUTH Function
%AUTH is set to either 0 or 1.
This function can be used in a program that builds JCL to determine if the user is
allowed to use the internal reader. $JOBAUTH works with all security interfaces
supported by Model 204.
For example, the code fragment
IF NOT $JOBAUTH THEN
PRINT 'INVALID ATTEMPT TO USE PRIVILEGED SYSTEM'
STOP
END IF
would STOP if the user was not authorized to use $JOB.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $JOBAUTH
——————————————————————————————————————————
149
——————————————————————————————————————————
——————————————————————————————————————————
7.67
$LIST_ADD_ORDERED: Add an item to an
ordered $list
This function adds an item to a (presumably) ordered $list, inserting the item at the
proper position to maintain the $list's order.
$LIST_ADD_ORDERED accepts two arguments and returns the item number of the
inserted string. It is a callable $function (“CALLing Sirius Mods functions” on page 32).
The first argument is the $list identifier of the $list to which the string is to be added.
This is a required argument.
The second argument is the string to add to the $list. This is a required argument.
[%RC =]
$LIST_ADD_ORDERED(list, string)
$LIST_ADD_ORDERED Function
%RC is the item number of the added string.
All errors in $LIST_ADD_ORDERED result in request cancellation.
$LIST_ADD_ORDERED always adds the indicated string even if that string already
exists on the $list but the new item is inserted so that the $list is in EBCDIC order.
$LIST_ADD_ORDERED assumes that the $list is in EBCDIC order so it does a pseudo
binary search to locate the correct insertion point. $LIST_ADD_ORDERED does not
validate that the $list is in order and, it it isn't, the insertion point is unpredictable.
The following code builds a sorted output $list from an input $list.
FOR %I FROM 1 TO $LISTCNT(%INLIST)
%STRING = $LISTINF(%INLIST, %I)
%RC = $LIST_ADD_ORDERED(%OUTLIST, %STRING)
END FOR
While in general it would be more efficient to simply copy and sort (via $LISTSORT) the
input $list such a technique might be useful if the target $list already as a large number
of items.
Because $LIST_ADD_ORDERED will insert items into the middle of a $list it will be
susceptible to the same page-splitting, sparse $list leaf page issues as $LISTINS
(“$LISTINS: Insert string into a $list” on page 211).
This $function is new in version 6.3.
——————————————————————————————————————————
150
——————————————————————————————————————————
$LIST_ADD_ORDERED: Add an item to an ordered $list
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_ADD_ORDERED
——————————————————————————————————————————
151
——————————————————————————————————————————
——————————————————————————————————————————
7.68
$LIST_ADD_UNIQUE: Conditionally add an item
to a $list
This function adds an item to a $list if an identical item isn't already there, adding the
item to the end of the $list.
$LIST_ADD_UNIQUE accepts two arguments and returns one of the following:
●
●
The item number of the added string.
The negative of the item number that exactly matches the string being added.
$LIST_ADD_UNIQUE is a callable $function (“CALLing Sirius Mods functions” on page
32).
[%RC =]
$LIST_ADD_UNIQUE(list, string)
$LIST_ADD_UNIQUE Function
%RC is the item number of the added string or the negative matching item
number.
All errors in $LIST_ADD_UNIQUE result in request cancellation.
$LIST_ADD_UNIQUE always adds the indicated string to the end of the $list but does
not add it if there's already an identical $list item on the $list. $LIST_ADD_UNIQUE
does not assume any order for the $list so sequentially scans the entire $list for matches
to the string being added. Because of this, it will generally be more expensive to use
than $LIST_ADD_UNIQUE_ORDERED for very large $lists though this latter function
might not be usable in all cases — say, if the target $list starts out unordered.
$LIST_ADD_UNIQUE returns the either the item number added if no match was found
or the negative item number of the matching item if one was found. This return code
makes it easy to maintain a parallel $list that contains say a count of the number of times
a given value occurred, that is was passed as a string to $LIST_ADD_UNIQUE. The
following illustrates such an approach:
%IN = $LIST_ADD_UNIQUE(%OLIST, %DATA)
IF %IN GT 0 THEN
%RC = $LISTINS(%CLIST, %IN, 1)
ELSE
%IN = -%IN
%RC = $LISTREP(%CLIST, %IN, $LISTINF(%CLIST, %IN) +1 )
END IF
——————————————————————————————————————————
152
——————————————————————————————————————————
$LIST_ADD_UNIQUE: Conditionally add an item to a $list
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_ADD_UNIQUE
——————————————————————————————————————————
153
——————————————————————————————————————————
——————————————————————————————————————————
7.69
$LIST_ADD_UNIQUE_ORDERED: Conditionally
add an item to an ordered $list
This function adds an item to a (presumably) ordered $list if an identical item isn't
already there, inserting the item at the proper position to maintain the $lists order.
$LIST_ADD_UNIQUE_ORDERED accepts two arguments and returns one of the
following:
●
●
The item number of the inserted string.
The negative of the item number that exactly matches the string being added.
$LIST_ADD_UNIQUE_ORDERED is a callable $function (“CALLing Sirius Mods
functions” on page 32).
[%RC =]
$LIST_ADD_UNIQUE_ORDERED(list, string)
$LIST_ADD_UNIQUE_ORDERED Function
%RC is the item number of the added string, or it is the negative matching item
number.
All errors in $LIST_ADD_UNIQUE_ORDERED result in request cancellation.
$LIST_ADD_UNIQUE_ORDERED only adds the indicated string to the $list if there isn't
already an identical $list item on the $list. If the there are no matching items, the new
item is inserted so that the $list is in EBCDIC order. $LIST_ADD_UNIQUE_ORDERED
assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate a
match or the correct insertion point. $LIST_ADD_UNIQUE_ORDERED does not
validate that the $list is in order and, it it isn't, the insertion point or detection of a match
is unpredictable.
$LIST_ADD_UNIQUE_ORDERED returns the either the item number added or inserted
if no match was found or the negative item number of the matching item if one was
found. This return code makes it easy to maintain a parallel $list that contains say a
count of the number of times a given value occurred, that is was passed as a string to
$LIST_ADD_UNIQUE_ORDERED. The following illustrates such an approach:
%IN = $LIST_ADD_UNIQUE_ORDERED(%OLIST, %DATA)
IF %IN GT 0 THEN
%RC = $LISTINS(%CLIST, %IN, 1)
ELSE
%IN = -%IN
%RC = $LISTREP(%CLIST, %IN, $LISTINF(%CLIST, %IN) +1 )
END IF
——————————————————————————————————————————
154
——————————————————————————————————————————
$LIST_ADD_UNIQUE_ORDERED: Conditionally add an item to an ordered $list
——————————————————————————————————————————
Because $LIST_ADD_UNIQUE_ORDERED will insert items into the middle of a $list it
will be susceptible to the same page-splitting, sparse $list leaf page issues as $LISTINS
(“$LISTINS: Insert string into a $list” on page 211).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_ADD_UNIQUE_ORDERED
——————————————————————————————————————————
155
——————————————————————————————————————————
——————————————————————————————————————————
7.70
$LIST_CAPTURE: Capture print data to $list
This function, new in Sirius Mods version 6.0., captures print data onto a $list.
$LIST_CAPTURE accepts the two arguments described below. It returns the identifier
of the previous $list that captured print, or it returns 0 if there is no such previous $list. It
is a callable $function (“CALLing Sirius Mods functions” on page 32).
●
The first argument is the $list identifier; 0 sets the print capture function to off. This
argument is optional, and it defaults to 0.
●
The second argument, which is optional, is a blank delimited set of options.
Currently, only the MSGS option, which captures Model 204 messages as well as
print data, is valid. For more information about the MSGS option, see “Message
capture and MSGCTL” on page 159.
[%OLD =]
$LIST_CAPTURE(list_id, options)
$LIST_CAPTURE Function
%OLD is the ID of the previous $list-capturing print.
For example, you can sort an arbitrary set of print lines:
%L = $LISTNEW
%R = $LIST_CAPTURE(%L)
PRINT 'HELLO'
PRINT 'GOODBYE'
%R = $LIST_CAPTURE
%J = $LISTSRT(%L, '1,10,A')
FOR %R FROM 1 TO $LISTCNT(%J)
PRINT $LISTINF(%J, %R)
END FOR
- $List identifier invalid:
- Invalid option:
Request is cancelled
$LIST_CAPTURE Error Conditions
When print data is captured to a $list, each print line is added as an item to the $list.
Note: In versions of Sirius Mods prior to 6.4, the list capture of these lines respects the
Model 204 OUTCCC, OUTMRL, and LOBUFF parameter formatting. That is, a print line
longer than OUTCCC wraps, and it is captured as an additional $list item for each time
that it wraps. A print line longer than OUTMRL or LOBUFF is truncated at OUTMRL or
LOBUFF bytes, respectively.
——————————————————————————————————————————
156
——————————————————————————————————————————
——————————————————————————————————————————
As of version 6.4 of Sirius Mods, the OUTCCC and OUTMRL limits are ignored for
$LIST_CAPTURE, but LOBUFF is still respected. Each print output line is truncated at
LOBUFF bytes. The LOBUFF limit, which is not resettable during the Online run, does
not affect the total length of the $list. Under Sirius Mods version 6.5 or earlier captured
items are truncated at 6124 bytes even if LOBUFF is greater than 6124. Under Sirius
Mods version 6.6 and later, LOBUFF is the only limit on captured $list item size.
For example, a sequence of statements like these below places two items in the $list,
each of which is subject to the above formatting rules:
%X = $LIST_CAPTURE(%LL)
PRINT %S
PRINT %T
However, in the following example, the PRINT statements concatenate, in effect, and
one item only is placed in the $list, subject to the above formatting rules:
%X = $SLIST_CAPTURE(%LL)
PRINT %S ...
PRINT %T
For additional information about $LIST_CAPTURE processing, see “Print capturing
hierarchy and other considerations”.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_CAPTURE
7.70.1 Print capturing hierarchy and other considerations
The User Language PRINT statement and the Sirius HTML statement are a few of many
“print” operations that can produce output lines for an application. These operations
“normally” send their output to the “terminal” for the thread running the application.
Terminal output refers to the print destination defined by the IODEV for the thread. For
example, the terminal output of an IODEV=7 (VTAM) terminal user is the user's
3270-style terminal; the terminal output of an IODEV=29 (IFDIAL, or BATCH2) user is
the MVS batch program that retrieves the output lines.
——————————————————————————————————————————
157
——————————————————————————————————————————
——————————————————————————————————————————
The terminal output of an SDAEMON thread (usually IODEV=15) depends on how the
SDAEMON was started:
$COMMxx
If the thread was started by a Sirius $COMMxx function, the output can be
saved in a Sirius $list that can be processed by the $COMMxx caller.
Janus SDS, OPENSERV, or SRVSOCK
For an SDS, OPENSERV, or SRVSOCK thread, the audit trail is used as the
terminal output. For these port types, messages during compilation are
always sent to the audit trail. For other types of print output, the
AUDTERM/NOAUDTERM parameter controls whether the terminal output is
sent to the audit trail (AUDTERM) or simply discarded (NOAUDTERM).
Janus WEB
For a WEB thread, the terminal output can either be the browser (if
$WEB_ON is in effect) or the audit trail (if $WEB_OFF is in effect), although
NOAUDTERM prevents non-compiler print lines from appearing on the audit
trail, as with other Janus server threads.
As stated, $COMMxx can be used to process print output, since the SDAEMON doing its
work can place print output in a Sirius $list. There are also facilities for processing print
output on any kind of thread, including other SDAEMON threads, and 3270 and
IFDIAL/BATCH204 threads:
●
●
●
The $LIST_CAPTURE function directs print output to a Sirius $list.
The $SOCK_CAPTURE setting directs print output to a Janus Sockets connection.
See the Janus Sockets Reference Manual.
The USE command, as documented in the Model 204 Command Reference
Manual, directs print output to a USE stream.
For the above three facilities, “interactive” output is not sent to the $list, the socket, nor
the USE stream, but instead is sent to the normal terminal output. The types of
interactive output lines are:
——————————————————————————————————————————
158
——————————————————————————————————————————
——————————————————————————————————————————
Type
Description
Messages
Informational or error messages (e.g., M204.nnnn or
MSIR.nnnn), except when $LIST_CAPTURE(id, 'MSGS') is
in effect
Prompts
Password prompts, $READ input, etc.
READ SCREEN
User Language full-screen display for input (note: PRINT
SCREEN statements are subject to redirection)
WRITE IMAGE
ON TERMINAL
User Language statement for sending lines directly to the
normal terminal output
Print lines always sent to normal terminal output
When an output line is redirected from the normal terminal output, it is directed
according to the following hierarchy:
Type
Conditions
$LIST_CAPTURE
Non-interactive print lines captured on $list, if one is
active as specified to $LIST_CAPTURE
$SOCK_CAPTURE
Non-interactive print lines captured on one or more
sockets, if any are specified as ON to
$SOCK_CAPTURE, and if no $list is active as specified
to $LIST_CAPTURE
USE stream
Non-interactive print lines directed to a USE stream, if it
is active and if a) there is no socket specified as ON to
$SOCK_CAPTURE, and b) no $list is active as specified
to $LIST_CAPTURE
Normal terminal
output
Print lines are sent to the normal terminal output if none
of the above print redirections is active
Print redirection hierarchy
For output lines (non SCREEN output/input) that should be forced to go to the terminal,
use WRITE IMAGE ON TERMINAL (on server applications, where the "terminal" output
is the audit trail, use AUDIT instead).
7.70.2 Message capture and MSGCTL
If the MSGS option is specified, LIST_CAPTURE captures the messages that go to the
“terminal.” This is true, however, as long as the messages are not being suppressed.
——————————————————————————————————————————
159
——————————————————————————————————————————
——————————————————————————————————————————
$LIST_CAPTURE does not capture terminal messages that are suppressed by the
MSGCTL system command or the MSGCTL user parameter. The latter is especially
important because many APSY subsystems suppress error and/or informational
messages by setting the MSGCTL X'04' and/or X'02' bits. This is done automatically by
Model 204 when the subsystem is defined to suppress error or informational messages.
If the X'04' and/or X'02' MSGCTL bits are set, they must be cleared for
$LIST_CAPTURE to actually capture error or informational messages. You can clear
these bits with the $RESETN function in a User Language application (“$RESETN:
Reset or view M204 parameter” on page 344).
——————————————————————————————————————————
160
——————————————————————————————————————————
$LIST_CONV_ITEM: Convert $list to single delimited $list item
——————————————————————————————————————————
7.71
$LIST_CONV_ITEM: Convert $list to single
delimited $list item
This function converts the contents of one $list into a separator delimited string which is
overlayed on a single item of a second $list.
$LIST_CONV_ITEM accepts four arguments and returns a numeric result.
The first argument is the identifier of a $list to be converted into a separator delimited
$list item. This is a required argument.
The second argument is the identifier of a $list containing the item to be overlayed by the
delimiter separated string generated from the first $list. This is a required argument.
The third argument is the number of the item from the second $list to be overlayed by
the delimiter separated string generated from the first $list. This is a required argument.
The fourth argument is the delimiter character or characters to be used in the generated
$list item string. It defaults to comma (‘,’,) and can be the null string. Specifying this
argument as a null string is different from not specifying the argument at all since in the
latter case it defaults to a comma.
%RESULT = $LIST_CONV_ITEM(list_id1, list_id2,
list_item2, separator)
$LIST_CONV_ITEM Function
%RESULT is set either to the number of $list items overlayed on a single item
in the output $list, or to a negative error code if an error has occurred.
The target item in the output $list is cleared to blanks before the overlay is done. If the
target item is too short to hold the input $list items, as many items and their trailing
delimiters as will fit will be placed in the target item and the result of the
$LIST_CONV_ITEM function will be the number of items copied. Put another way, no
partial $list items will be placed into the target item. This means that a good test for
success of this function is a comparison of the result of $LIST_CONV_ITEM with a
$LISTCNT of the input $list.
IF $LIST_CONV_ITEM(%LIST1, %LIST, %N) NE $LISTCNT(%LIST1) THEN
( error code )
END IF
For an example of the use of this function, suppose $list %LIST1 contained three items
LLL
MMMMM
NN
and %LIST2 contained two items
——————————————————————————————————————————
161
——————————————————————————————————————————
——————————————————————————————————————————
A,B,C,
123456789012345678901234567890
then
%CNT =
$LIST_CONV_ITEM(%LIST1, %LIST2, 2)
will result in %LIST2 having 2 items
A,B,C,
LLL,MMMMM,NN,
with the second item being blank padded to 30 characters. %CNT would be set to 3.
Suppose $list %LIST1 contained five items
EVERY
GOOD
BOY
DOES
FINE
and $list %LIST2 contained three items each padded to 22 characters.
1234567890123456789012
***JUNK****
THE,ITSY,BITSY,SPIDER,
then
%CNT =
$LIST_CONV_ITEM(%LIST1, %LIST2, 3, '++')
will result in %LIST2 having 3 items with each still padded to 22 characters.
1234567890123456789012
***JUNK****
EVERY++GOOD++BOY++
with the third item only containing three separated entries because there was insufficient
space for the item “DOES” and the item delimiter characters. %CNT would be set to 3 in
this example.
The delimiter separated string generated by $LIST_CONV_ITEM can be longer than 255
bytes up to 6124 bytes in Sirius Mods version 6.2 and later and 4096 bytes before.
-5 - Required argument not specified
-6 - $List identifier invalid
-7 - Invalid item number
$LIST_CONV_ITEM Error Codes
——————————————————————————————————————————
162
——————————————————————————————————————————
$LIST_CONV_ITEM: Convert $list to single delimited $list item
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_CONV_ITEM
——————————————————————————————————————————
163
——————————————————————————————————————————
——————————————————————————————————————————
7.72
$LIST_COPY_ITEMS: Copy items between $lists
This function copies items from one $list to another. Both the input and output $lists can
be created by any of the $list creating functions. The copied items are appended to the
end of the output $list.
The $LIST_COPY_ITEMS function accepts four arguments and returns a numeric result.
It is a callable $function (“CALLing Sirius Mods functions” on page 32).
The first argument is the identifier of the output $list. This is a required argument.
The second argument is the identifier of the input $list. This is a required argument.
The third argument is a number that is the starting item number in the input $list from
which items are to be copied. This is an optional argument and defaults to the first item
in the input $list if not specified.
The fourth argument is a number that is the number of items from the input $list that are
to be copied. This is an optional argument and defaults to the number of items in the
input $list after and including the starting item number. If set to a number greater than
the number of items after and including the starting item number, all items after and
including the starting item number are copied. A zero value for this argument is treated
the same as if it were not specified.
[%RESULT =] $LIST_COPY_ITEMS(list_id_output, list_id_input, start_item, num_items)
$LIST_COPY_ITEMS Function
%RESULT is set either to the number of items in the output $list after the
function is completed, or to a negative error code.
-3
-5
-6
-7
-8
-
No room in CCATEMP
Required argument not specified
$List identifier invalid
Invalid starting item number
Invalid item count
$LIST_COPY_ITEMS Error Codes
$LIST_COPY_ITEMS does an item for item copy so can be used to compress a $list
that has become sparse as the result of heavy $LISTINS, $LISTREP, $LISTADJ and/or
$LISTREM activity. $LISTREP and $LISTADJ will only cause a $list to become sparse if
$list items are replaced with larger $list items or increased in size. The following chunk
of code shows how $list %LIST can be compressed:
%CLIST = $LISTNEW
%RC
= $LIST_COPY_ITEMS(%CLIST, %LIST)
%RC
= $LISTMOVE(%LIST, %CLIST)
——————————————————————————————————————————
164
——————————————————————————————————————————
$LIST_COPY_ITEMS: Copy items between $lists
——————————————————————————————————————————
If copying an entire $list and no compression is required, $LISTCPY is more efficient
than $LIST_COPY_ITEMS because the former does a page for page copy while the
latter does an item for item copy. $LISTCPY is documented in “$LISTCPY: Copy $list”
on page 193.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_COPY_ITEMS
——————————————————————————————————————————
165
——————————————————————————————————————————
——————————————————————————————————————————
7.73
$LIST_DIFF_ITEM: Differences between $list and
delimited $list item
This function determines which items in a $list do not appear as an entry in a separator
delimited item in a second $list and places them on a third $list. In some sense this is
the “difference” between a $list and a separator delimited $list item.
$LIST_DIFF_ITEM accepts five arguments and returns a numeric result. It is a callable
The first argument is the identifier of a $list for which each item is to be compared
against the delimited item in the second $list. This is a required argument.
The second argument is the identifier of a $list containing the item containing a delimiter
separated string that is to be scanned for each item from the first $list. This is a required
argument.
The third argument is the identifier of a $list to contain any items from the first $list that
do not appear as a delimiter separated entry in the indicated item from the second $list.
The $list specified by the third argument is cleared before $LIST_DIFF_ITEM does any
processing. This is a required argument.
The fourth argument is the number of the item from the second $list containing a
delimiter separated string that is to be scanned for each item from the first $list. This is a
required argument.
The fifth argument is the delimiter character or characters to be used in the scanning the
indicated $list item. It defaults to comma (,), and it cannot be the null string. Specifying
this argument as a null string is the same as either not specifying the argument or
specifying it as a comma.
[%RESULT =]
$LIST_DIFF_ITEM(list_id1, list_id2, list_id3,
list_item2, separator)
-
$LIST_DIFF_ITEM Function
%RESULT is set to the number of items added to the output $list, or it is set to
a negative error code if an error has occurred.
For an example of the use of this function, suppose $list %LIST1 contains six items:
BBB
CC
DDDD
AAA
E
FFF
——————————————————————————————————————————
166
——————————————————————————————————————————
$LIST_DIFF_ITEM: Differences between $list and delimited $list item
——————————————————————————————————————————
And $list %LIST2 contains two items:
X,Y,Z,
AAA,DDDD,FFF,
Then this statement:
%CNT = $LIST_DIFF(%LIST1, %LIST2, %LIST3, 2)
results in %LIST3 having three items:
BBB
CC
E
%CNT is set to 3.
If a value occurs multiple times in the first input $list, it will appear either the same
number of times in the output $list or not at all, depending on whether it appears in the
separator- delimited item in the second $list.
For example, if $list %LIST1 contains eight items:
TCP/IP
SNA
CORBA
MQSERIES
SNA
TCP/IP
IPX
TCP/IP
And $list %LIST2 contains three items:
Y2K**SECURITY**PRODUCTIVITY**METRICS**
IND$FILE**LU6.2**SNA**MQSERIES**LU2**
GIF**JPEG**WAV**PDF**HTML**
Then this statement:
%CNT =
$LIST_DIFF_ITEM(%LIST1, %LIST2, %LIST3, , '**')
Results in $list %LIST3 having five items:
TCP/IP
CORBA
TCP/IP
IPX
TCP/IP
——————————————————————————————————————————
167
——————————————————————————————————————————
——————————————————————————————————————————
%CNT is set to 5.
-3
-5
-6
-7
-
No room in CCATEMP
Invalid item number
$LIST_DIFF_ITEM Error Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_DIFF_ITEM
——————————————————————————————————————————
168
——————————————————————————————————————————
$LIST_GLOBAL and $LIST_SESSION: Access/create global/session $list
——————————————————————————————————————————
7.74
$LIST_GLOBAL and $LIST_SESSION:
Access/create global/session $list
This function returns a $list identifier by which one may refer to a global or session $list
in a request. The global or session $list may be one that already exists because of a
previous $LIST_GLOBAL, $LIST-SESSION, or $LISTSAVE function, or it may be
created by the $LIST_GLOBAL or $LIST_SESSION function.
$LIST_GLOBAL and $LIST_SESSION accept two arguments and return a numeric
result.
The first argument is the name of the global or session $list. This is a required
argument.
The second argument indicates the type of processing $LIST_GLOBAL or
$LIST_SESSION is to perform. Valid values are the following:
ANY
If the global or session $list already exists, it is referenced with its current
contents. If it does not exist, a new empty global or session $list is
created.
OLD
The global or session $list must already exist, that is, it must have been
created with a previous $LIST_GLOBAL or $LIST_SESSION or saved
with a $LISTSAVE.
NEW
The global or session $list must not already exist. If it does, it will be
recreated.
PREP
Same as ANY but empties $list if it has data.
PREPANY
PREPOLD
Same as OLD but empties $list if it has data.
PREPNEW
Same as NEW.
ANYPREP
OLDPREP
Same as OLD but empties $list if it has data.
NEWPREP
Same as NEW.
This is an optional argument and defaults to ANY.
——————————————————————————————————————————
169
——————————————————————————————————————————
——————————————————————————————————————————
%RESULT = $LIST_GLOBAL(name, type)
$LIST_GLOBAL Function
%RESULT is set either to the identifier of the global $list, or to a negative error
code if an error has occurred.
%RESULT = $LIST_SESSION(name, type)
$LIST_SESSION Function
%RESULT is set either to the identifier of the session $list, or to a negative
error code if an error has occurred.
A particular instance of $LIST_GLOBAL or $LIST_SESSION always returns the same
$list identifier so it cannot be called multiple times for different global or session $list
names to allow simultaneous reference to these $lists.
The scope of a $LIST_GLOBAL or $LIST_SESSION identifier is the evaluation of the
User Language request in which it was contained. When evaluation is over, global $list
data appears exactly like a $LISTSAVE'd (or $LISTSAV'ed) $list and, in fact, can be
$LISTRST'ed. For a different request to access that same global $list, it must issue a
$LIST_GLOBAL or $LISTRST with the same name. A $LIST_GLOBAL can also be
issued against a $list that was $LISTSAVE'd, even in the same procedure, as in the
following example.
%RC
= $LISTSAVE(%LIST, 'NEW.NAME')
%GLIST = $LIST_GLOBAL('NEW.NAME')
A $LIST_SESSION cannot access a $LISTSAVE'd $list, and $LISTRST cannot access a
session $list.
Separate $LIST_GLOBAL or $LIST_SESSION statements can be issued against the
same name. When this is done, each instance of $LIST_GLOBAL or $LIST_SESSION
will return a separate $list identifier, but they will actually refer to the same underlying
$list. For example, the result of the following $LIST_GLOBAL statements is a single
global $list with name WHATEVER that contains two items: WASTE NOT is the first, and
WANT NOT is the second.
%LIST1 = $LIST_GLOBAL('WHATEVER', 'NEW')
%LIST2 = $LIST_GLOBAL('WHATEVER')
%RC = $LISTADD(%LIST1, 'WASTE NOT')
%RC = $LISTADD(%LIST2, 'WANT NOT')
A $LISTIMG on a global $list identifier is associated with the $list identifier, not the
underlying data, so in the case of multiple $LIST_GLOBALs or $LIST_SESSIONs for the
same name, the $LISTIMG only applies to the $list identifier for which it was issued. For
example, the first $LISTADDI below adds data to the global $list from image MYIMAGE,
while the second $LISTADDI adds data from image YOURIMAGE:
——————————————————————————————————————————
170
——————————————————————————————————————————
$LIST_GLOBAL and $LIST_SESSION: Access/create global/session $list
——————————————————————————————————————————
%LIST1
%LIST2
%RC
%RC
%RC
%RC
=
=
=
=
=
=
$LIST_GLOBAL('WHATEVER', 'NEW')
$LIST_GLOBAL('WHATEVER')
$LISTIMG(%LIST1, %MYIMAGE:COUNT)
$LISTIMG(%LIST2, %YOURIMAGE:COUNT)
$LISTADDI(%LIST1)
$LISTADDI(%LIST2)
Global and session $list names are kept in CCATEMP. For every $LIST_GLOBAL or
$LIST_SESSION call, logical I/O (and possibly physical I/O) must be performed to look
up the name. As such, it is a good practice to avoid $LIST_GLOBALs or
$LIST_SESSIONs for constant names inside a loop, and to make global and session
$list identifier variables COMMON rather than letting each subroutine issue a
$LIST_GLOBAL or $LIST_SESSION function.
If it is uncertain whether the global or session list has been already declared inside a
subroutine (or anywhere for that matter), code like the following can be used to ensure
that the $LIST_GLOBAL or $LIST_SESSION statement is only issued once.
IF NOT %MY.LIST THEN
%MY.LIST = $LIST_GLOBAL('MY.LIST', 'ANY')
END IF
The PREP prefix or suffix for all the types indicates that the returned $list should be
cleared of its contents. For example, after
%LIST1 = $LIST_GLOBAL('WHATEVER', 'NEW')
%RC = $LISTADD(%LIST1, 'WASTE NOT')
%LIST2 = $LIST_GLOBAL('WHATEVER', 'PREPOLD')
%RC = $LISTADD(%LIST2, 'WANT NOT')
the global $list identified by WHATEVER would have a single item with content WANT
NOT. Just as type ANY is the default for $LIST_GLOBAL, PREP is the same as
PREPANY.
Global $lists can only be restored with a $LISTRST if they have not been accessed as
$LIST_GLOBAL in the procedure that issues the $LISTRST. You can clean up any
global $lists with $LIST_GLOBAL_DEL, which can be issued whether or not a name was
referenced in the current procedure with a $LIST_GLOBAL. You can clean up any
session $lists with $LIST_SESSION_DEL, which can be issued whether or not a name
was referenced in the current procedure with a $LIST_GLOBAL.
$LIST_GLOBAL and $LIST_SESSION have independent namespaces. That is, the
same name used for $LIST_GLOBAL and $LIST_SESSION reference different $lists.
A $LIST_SESSION call when there is no session open causes a request cancellation.
For more information about sessions see “Sessions” on page 25.
——————————————————————————————————————————
171
——————————————————————————————————————————
——————————————————————————————————————————
-3 - No room in CCATEMP to add global name
(not possible with OLD)
-14 - No global list for name (for type OLD)
Already a global list for name (for type NOTOLD)
-15 - Invalid type (second parameter)
$LIST_GLOBAL and $LIST_SESSION Error Codes
$LIST_SESSION is new in version 6.3 of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_GLOBAL and $LIST_SESSION
——————————————————————————————————————————
172
——————————————————————————————————————————
$LIST_GLOBAL_DEL and $LIST_SESSION_DEL: Delete global/session $lists
——————————————————————————————————————————
7.75
$LIST_GLOBAL_DEL and $LIST_SESSION_DEL:
Delete global/session $lists
These functions delete one or more global or session $lists that were created with either
$LISTSAV, $LISTSAVE, $LIST_GLOBAL or $LIST_SESSION in the current or any
previous User Language program. It always returns a result of 1.
$LIST_GLOBAL_DEL and $LIST_SESSION_DEL accept one argument and return a
numeric result. Both are callable $functions (“CALLing Sirius Mods functions” on page
32).
The first argument is the name of the global or session $list or $lists to be deleted. If not
specified, only a $list with a null name is deleted. This argument can contain wildcard
characters as described below.
[%RESULT =]
$LIST_GLOBAL_DEL(name)
$LIST_GLOBAL_DEL Function
[%RESULT =]
$LIST_SESSION_DEL(name)
$LIST_SESSION_DEL Function
The name specified for $LIST_GLOBAL_DEL or $LIST_SESSION_DEL can be an
explicit name or it can contain the following wildcard characters:
*
?
"
character.
For example,
%RC = $LIST_GLOBAL_DEL('TYRANNOSAURUS')
would only delete a global $list named ‘TYRANNOSAURUS’.
%RC = $LIST_GLOBAL_DEL('STEG*')
would delete globals $lists named ‘STEG’, ‘STEGOSAURUS’ and ‘STEG.DATA’ if they
existed.
%RC = $LIST_SESSION_DEL('ST??')
——————————————————————————————————————————
173
——————————————————————————————————————————
——————————————————————————————————————————
would delete session $lists named ‘STAN’, ‘STEP’ and ‘STUN.DATA’ if they existed.
%RC = $LIST_GLOBAL_DEL('"**')
would delete globals $lists named ‘*’, ‘*LOOK’ and ‘*ZAP.DATA’ if they existed.
%RC = $LIST_SESSION_DEL('*')
would delete all session $lists.
When a $LIST_GLOBAL_DEL or $LIST_SESSION_DEL is issued against a global or
session $list that has a $list identifier associated with it, that $list identifier becomes
invalid. For example, after
%LISTC = $LIST_GLOBAL('VELOCIRAPTOR')
%RC
= $LIST_GLOBAL_DEL('VEL*')
the $list identifier in %LISTC is no longer valid. $LIST_GLOBAL_DEL does not
distinguish among the manner in which a global $list was created; it will delete any $list
created with $LIST_GLOBAL, $LISTSAVE, or $LISTSAV, whether or not it has been
referred to with any of these $functions in the current request. Since session $lists can
only be created with $LIST_SESSION, $LIST_SESSION_DEL will delete only $lists
created by $LIST_SESSION.
A $LIST_SESSION_DEL call when there is no session open causes a request
cancellation. For more information about sessions see “Sessions” on page 25.
$LIST_SESSION_DEL is new in version 6.3 of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_GLOBAL_DEL and $LIST_SESSION_DEL
——————————————————————————————————————————
174
——————————————————————————————————————————
$LIST_GLOBAL_LIST and $LIST_SESSION_LIST: List global/session $lists
——————————————————————————————————————————
7.76
$LIST_GLOBAL_LIST and $LIST_SESSION_LIST:
List global/session $lists
$LIST_GLOBAL_LIST and $LIST_SESSION_LIST return information about global and
session $lists to a $list.
$LIST_GLOBAL_LIST and $LIST_SESSION_LIST accept one argument and return
either of the following:
●
●
The number of items added to the output $list.
-3, if CCATEMP is full and the LISTFC parameter is not set. All other errors result in
request cancellation.
The first argument is the $list identifier to receive the output from $LIST_GLOBAL_LIST
or $LIST_SESSION_LIST. This is a required argument.
$LIST_GLOBAL_LIST and $LIST_SESSION_LIST are callable $functions (“CALLing
Sirius Mods functions” on page 32).
[%RC =]
$LIST_GLOBAL_LIST(listid)
$GLOBAL_LIST
%RC is set to the number of added items or to -3.
[%RC =]
$LIST_SESSION_LIST(listid)
$SESSION_LIST
%RC is set to the number of added items or to -3.
The format of the data in the output $list is
Col 1-10
The EBCDIC number of items on the $list, right-justified.
Col 11-
The name of the global or session $list.
The following example displays information about all current global and session $lists:
%LIST
%RC =
PRINT
%RC =
%LIST
%RC =
PRINT
%RC =
= $LISTNEW
$LIST_GLOBAL_LIST(%LIST)
'Global $lists:'
$LIST_PRINT(%LIST)
= $LISTNEW
$LIST_SESSION_LIST(%LIST)
'Session $lists:'
$LIST_PRINT(%LIST)
——————————————————————————————————————————
175
——————————————————————————————————————————
——————————————————————————————————————————
A $LIST_SESSION_LIST call when there is no session open causes a request
$LIST_GLOBAL_LIST is new in Sirius Mods version 6.2. $LIST_SESSION_LIST is new
in Sirius Mods version 6.3.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_GLOBAL_LIST and $LIST_SESSION_LIST
——————————————————————————————————————————
176
——————————————————————————————————————————
$LIST_MAXIL: Return maximum $list item length
——————————————————————————————————————————
7.77
$LIST_MAXIL: Return maximum $list item length
This function returns the maximum $list item length.
$LIST_MAXIL accepts no arguments and returns the maximum length of a $list item.
%MAX = $LIST_MAXIL
$LIST_MAXIL Function
%MAX: Maximum length of a $list item.
The chief purpose of $LIST_MAXIL is to avoid having code with a constant (like 6124)
whose value is subject to change. Under Sirius Mods version 6.5, 6124 was the
maximum length of a $list item. Under Sirius Mods version 6.6 and later, some functions
such as $LISTLOC and $LISTLUP still only operate on the first 6124 bytes of $list items.
While Sirius Software is not likely to reduce this value, because of the complex
backward compatibility issues, it might someday increase it, as it eliminated the $list item
length limit in Sirius Mods 6.6.
This $function is new in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_MAXIL
——————————————————————————————————————————
177
——————————————————————————————————————————
——————————————————————————————————————————
7.78
$LIST_PRINT: Display contents of a $list
This function displays the contents of a $list on the user's standard output device,
typically a terminal.
$LIST_PRINT accepts five arguments and returns a numeric result. It is a callable
The first argument is the $list identifier of the input $list. This is a required argument.
The second argument is the number of bytes in the display of each line to use for the
item number. This must be a number between 0 and 10 inclusive and, if greater than 0,
a blank is placed after the item number. Item numbers are right justified in the indicated
number of bytes. and they are truncated on the left if the length of the item number
exceeds the space allocated for it. This is an optional argument and defaults to 0
meaning the item numbers will not be displayed.
The third argument is the number of bytes in the display of each line to use for the item
length. This must be a number between 0 and 4 inclusive and, if greater than 0, a blank
is placed after the item length. Item lengths are right justified in the indicated number of
bytes, and they are truncated on the left if the length of the item length exceeds the
space allocated for it. This is an optional argument and defaults to 0 meaning the item
lengths will not be displayed.
The fourth argument is the first item number to display. This is an optional argument
and defaults to 1.
The fifth argument is the maximum number of items to display. A zero or negative value
means to display all items to the end of the $list. This is an optional argument and
defaults to zero meaning display to the end of the $list.
[%RESULT =]
$LIST_PRINT(listid, num_len, len_len, first_item, max_items)
$LIST_PRINT Function
%RESULT is set to the number of $list items displayed.
0 or greater - Number of items printed
All errors result in request cancellation
$LIST_PRINT return codes
$LIST_PRINT, as its name would suggest, is functionally equivalent to a PRINT
statement with the exception that $list items longer than 255 bytes are displayed in their
entirety. This means that any output redirection or capturing whether it be a USE
command or a $LIST_CAPTURE or a $SOCK_CAPTURE will apply to the output of a
——————————————————————————————————————————
178
——————————————————————————————————————————
$LIST_PRINT: Display contents of a $list
——————————————————————————————————————————
$LIST_PRINT. If the input $list for a $LIST_PRINT is also the current output target via
$LIST_CAPTURE, only the $list items on the $list before the $LIST_PRINT is issued will
be displayed and and appended on to its own end. The following code
%LIST = $LISTNEW
%RC = $LIST_CAPTURE(%LIST)
PRINT 'I will not talk out of turn in class'
FOR %I FROM 1 TO 10
%RC = $LIST_PRINT(%LIST)
END FOR
%RC = $LIST_CAPTURE
would populate the $list %LIST with 1024 $list items that each contain “I will not talk out
of turn in class”.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LIST_PRINT
——————————————————————————————————————————
179
——————————————————————————————————————————
——————————————————————————————————————————
7.79
$LISTADD: Add string as new $list item
This function adds arbitrary string data to a $list. Generally, this $list would have been
created with the $LISTNEW function.
The $LISTADD function accepts three arguments and returns a numeric result. It is a
The first argument is a $list identifier. This is a required argument.
The second argument is a string that is to be added to the $list. This is a required
argument.
The third argument is a number that indicates the length of the new $list item. This is an
optional argument. Its minimum valid value is 0 and the maximum is 6124 under Sirius
Mods version 6.2 and later and 4096 before. If this value is longer than the length of the
second argument, the second argument is padded on the right with blanks. If this value
is shorter than the length of the second argument, the second argument is truncated.
[%RESULT =]
$LISTADD(list_identifier, string, length)
$LISTADD Function
%RESULT is set either to the number of items in the indicated $list after the
string has been added to the $list, or to a negative number if an error has
occurred. Note that in the former case, %RESULT is also the item number
associated with the added string in the $list.
-3 - No room to add item
(if LISTFC $SIRPARM parameter not set)
-7 - Invalid length specified
$LISTADD Error Codes
$LISTADD and $LISTNEW allow a User Language programmer to create arrays in
CCATEMP. The following example demonstrates how such a mechanism might be
used.
FIND1: FIND ALL RECORDS FOR WHICH
NAME = SMITH
END FIND
%LIST = $LISTNEW
FOR EACH RECORD IN FIND1
%STRING = NAME WITH ' ' WITH SSN WITH ' ' WITH AGE
%COUNT = $LISTADD(%LIST, %STRING)
END FOR
——————————————————————————————————————————
180
——————————————————————————————————————————
$LISTADD: Add string as new $list item
——————————————————————————————————————————
The length (third) argument makes it possible to create $list items that are longer than
255 bytes. This can be most easily accomplished in conjuction with the $LISTOVL
function. In the following example, several field values are placed into a $list item with a
length of 512.
NAME = SIMPSON
END FIND
%LIST = $LISTNEW
FOR EACH
%NUM
%RC
%RC
%RC
%RC
%RC
%RC
%RC
%RC
%RC
%RC
END FOR
●
●
●
●
●
●
●
●
RECORD IN FIND1
= $LISTADD(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
SSN, 512)
%NUM, 10,
%NUM, 50,
%NUM, 90,
%NUM, 110,
%NUM, 170,
%NUM, 230,
%NUM, 290,
%NUM, 310,
%NUM, 312,
%NUM, 412,
LNAM)
FNAM)
MNAM)
ADD1)
ADD2)
ADD3)
CITY)
ST)
COMMENT1)
COMMENT2)
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTADD
——————————————————————————————————————————
181
——————————————————————————————————————————
——————————————————————————————————————————
7.80
$LISTADD_LSTR: Add longstring as new $list
item
This function adds longstring data to a $list. Generally, this $list would have been
The $LISTADD_LSTR function accepts two arguments and returns a numeric result. It
The second argument is a longstring that is to be added to the $list. This is a required
argument.
[%RESULT =]
$LISTADD_LSTR(list_identifier, string)
$LISTADD_LSTR Function
All other errors cause request cancellation
$LISTADD_LSTR Error Codes
Before Sirius Mods version 6.6, it was a request cancelling error to try to add a
longstring longer than the size limit of a $list item: 6124 bytes. This limitation was
eliminated in Sirius Mods version 6.6.
$LISTADD_LSTR works almost exactly like $LISTADD except:
1.
It accepts a LONGSTRING input. $LISTADD_LSTR can be used with regular
strings as well to pick up automatic request cancellation on programming errors.
2.
It cancels the request on any errors such as invalid $list identifier or invalid $list item
number.
3.
It does not have an item length argument (argument 3 in $LISTADD).
$LISTADD_LSTR is available in Sirius Mods version 6.2 and later.
——————————————————————————————————————————
182
——————————————————————————————————————————
$LISTADD_LSTR: Add longstring as new $list item
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTADD
——————————————————————————————————————————
183
——————————————————————————————————————————
——————————————————————————————————————————
7.81
$LISTADDI: Add image as new $list item
This function copies data from an image to a $list. Generally, this $list would have been
The $LISTADDI function accepts three arguments and returns a numeric result. It is a
The second argument can either be a string containing the name of an image or any
image item from the required image. This is an optional argument if an image has been
associated with the $list with a $LISTIMG (“$LISTIMG: Associate an image with a $list”
on page 203) function. Otherwise, it is a required argument.
The third argument is a number that indicates the length of the new $list item. This is an
optional argument. Its minimum valid value is 0, and the maximum is 6124 under Sirius
Mods version 6.2 and later, and 4096 in versions before 6.2. If this value is longer than
the length of the image, the image is padded on the right with blanks. If this value is
shorter than the length of the image, the image is truncated.
[%RESULT =]
$LISTADDI(list_identifier, image_id, length)
$LISTADDI Function
-8 - Image not active or not found
$LISTADDI Error Codes
$LISTADDI and $LISTNEW allow a User Language programmer to create arrays in
CCATEMP. The following example demonstrates how such a mechanism might be
used.
——————————————————————————————————————————
184
——————————————————————————————————————————
$LISTADDI: Add image as new $list item
——————————————————————————————————————————
IMAGE CUST
NAME
IS STRING LEN 20
SSN
IS STRING LEN 10
BDATE IS STRING LEN 8
END IMAGE
NAME = SMITH
END FIND
%LIST = $LISTNEW
%CUST:NAME = NAME
%CUST:SSN
= SSN
%CUST:BDATE = BDATE
%COUNT = $LISTADDI(%LIST, 'CUST')
END FOR
The above example can be made more efficient by coding the $LISTADDI as follows.
%COUNT = $LISTADDI(%LIST, %CUST:NAME)
The specific image item is irrelevant in this call but is more efficient than specifying the
image name in quotes, because in the first example, the image name must be hashed
and looked up (in NTBL) in each invocation of $LISTADDI, while in the second example,
the hashing of the image name and lookup happens only once: at compile time.
Here is an even neater and equally efficient way of coding this:
%RC = $LISTIMG(%LIST, %CUST:BDATE)
%CUST:NAME = NAME
%CUST:SSN
= SSN
%CUST:BDATE = BDATE
%COUNT = $LISTADDI(%LIST)
END FOR
In this last example, $LISTIMG associates the image with the $list, eliminating the need
to specify the image name on the $LISTADDI. This association is also useful in many
other function calls, because it provides a structure to be associated with the $list that is
useful for column-oriented functions such as $LISTLOC and $LISTSRT.
——————————————————————————————————————————
185
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTADDI
——————————————————————————————————————————
186
——————————————————————————————————————————
$LISTADJ: Adjust length of $list item
——————————————————————————————————————————
7.82
$LISTADJ: Adjust length of $list item
This function adjusts the length of a $list item. Generally, this $list would have been
The $LISTADJ function accepts three arguments and returns a numeric result. It is a
The second argument is a $list item number. This is a required argument.
The third argument is a number that indicates the new length of the $list item. This is a
required argument. Its minimum valid value is 0; the maximum value is 6124 under
Sirius Mods version 6.5 and earlier, and it is 2**31-1 under Sirius Mods version 6.6 and
later. If this value is smaller than the current length of the $list item, the $list item is
truncated. If this value is larger than the current length of the $list item, the $list item is
padded with blanks to the indicated length.
[%RESULT =]
$LISTADJ(list_identifier, itemnum, length)
$LISTADJ Function
%RESULT is set to 0 if the new item length is the same as the old item length,
1 if it is less, 2 if it is greater, or a negative number if an error has occurred.
$LISTADJ Error Codes
The following example illustrates how $LISTADJ can be used to add an asterisk to the
end of a $list item:
%LEN = $LISTILN(%LIST, %NUM)
%RC = $LISTADJ(%LIST, %NUM, %LEN + 1)
%RC = $LISTOVL(%LIST, %NUM, %LEN + 1, '*')
$LISTADJ is extremely efficient if the $list item size is not being changed (return value
for $LISTADJ of 0), fairly efficient when a $list item is being shortened (return value of 1)
and can be fairly expensive when a $list item is being lengthened (return value of 2).
The latter case can be expensive because such a $LISTADJ can result in the splitting of
a $list leaf page. Once a leaf page is split, it will not be merged back together, even if
subsequent $LISTREMs (or $LISTADJs) makes this possible.
Because split leaf pages remain split, heavy use of $LISADJ calls that increase $list item
size (and $LISTINS and $LISTREM) can result in “sparse” $lists which place an
——————————————————————————————————————————
187
——————————————————————————————————————————
——————————————————————————————————————————
unnecessary burden on the buffer pool and CCATEMP. It can also result in an inability
to add an item to the end of the $list (via $LISTADD) because of a full pointer page,
even though the $list is nowhere near the theoretical capacity for a $list. $List
compression can be done using the $LIST_COPY_ITEMS function, documented in
“$LIST_COPY_ITEMS: Copy items between $lists” on page 164.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTADJ
——————————————————————————————————————————
188
——————————————————————————————————————————
$LISTCHK: Validate a $list identifier
——————————————————————————————————————————
7.83
$LISTCHK: Validate a $list identifier
This function returns either a 0 if a value is not a valid $list identifier and a 1 otherwise.
The $LISTCHK function accepts one argument and returns a numeric result.
The first argument is a potential $list identifier. This is a required argument.
%RESULT = $LISTCHK(list_identifier)
$LISTCHK Function
%RESULT is set either to 1, if the passed value is indeed a valid $list identifier,
or to 0 otherwise.
All errors cause request cancellation
$LISTCHK Error Codes
The only possible error in a $LISTCHK call is not specifying a value for the candidate
$list identifier. This error will cause request cancellation.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTCHK
——————————————————————————————————————————
189
——————————————————————————————————————————
——————————————————————————————————————————
7.84
$LISTCMP: Compare two $lists and produce $list
describing differences
This function compares two $lists and produces a $list describing the differences
between the $lists.
The $LISTCMP function accepts five arguments and returns a numeric result. It is a
The first argument is the identifier of a $list containing data with 8 byte sequence
numbers. This is a required argument.
The second argument is the identifier of a $list containing data without 8 byte sequence
The third argument is the identifier of the output $list. This is a required argument.
The fourth argument is a number indicating a synchronization count. When the two input
$lists are being compared and a difference has been found, this count indicates the
number of lines that must match before they are treated as a true match. This is an
optional argument and defaults to 1.
The fifth argument is a pad character to be used to pad any input line that is too short.
This is an optional argument and defaults to blank.
[%RESULT =]
$LISTCMP(list_id1, list_id2, list_id3,
sync_count, pad)
-
$LISTCMP Function
%RESULT is set either to the number of items in the output $list, or to a
negative error code if an error has occurred.
The output $list produced by $LISTCMP is in a format that is suitable as input to
$LISTUPD. For example, if input $list 1 contains
00010000B
00020000
00030000PRINT 'QUENTIN COMPSON'
00040000
00050000END
and input $list 2 contains
B
PRINT 'QUENTIN COMPSON'
PRINT 'HARVARD DIVING TEAM, 1908'
END
——————————————————————————————————————————
190
——————————————————————————————————————————
$LISTCMP: Compare two $lists and produce $list describing differences
——————————————————————————————————————————
the statement
%RESULT = $LISTCMP(%INLIST1, %INLIST2, %OUTLIST)
would result in the $list identified by %OUTLIST containing
./ I 00030000
$ 00030001 00010000
PRINT 'HARVARD DIVING TEAM, 1908'
The first input $list to $LISTCMP can be most easily created with the $PROCDAT
function using the third $PROCDAT parameter to indicate a sequence number.
-3 - No room to create $list items
-7 - Invalid synchronization count
-8 - Input $list 1 has invalid format
$LISTCMP Error Codes
●
SirLib
Products authorizing $LISTCMP
——————————————————————————————————————————
191
——————————————————————————————————————————
——————————————————————————————————————————
7.85
$LISTCNT: Number of items in $list
This function returns an integer that, if positive, contains the number of items in the
specified $list and if negative indicates an error.
The $LISTCNT function accepts one argument and returns a numeric result.
%RESULT = $LISTCNT(list_identifier)
$LISTCNT Function
%RESULT is set either to the number of items in the indicated $list, or to a
negative number if an error has occurred.
$LISTCNT Error Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTCNT
——————————————————————————————————————————
192
——————————————————————————————————————————
$LISTCPY: Copy $list
——————————————————————————————————————————
7.86
$LISTCPY: Copy $list
This function copies an entire $list, creating a new $list. The input $list can be created
by any of the $list creating functions.
The $LISTCPY function accepts one argument and returns a numeric result.
The first argument is the identifier of the input $list. This is a required argument.
%RESULT = $LISTCPY(list_identifier)
$LISTCPY Function
%RESULT is set to the identifier of the output $list.
-3 - No room in CCATEMP
$LISTCPY Error Codes
All invocations of a particular call to $LISTCPY will always return the same $list
identifier. Each time that call is executed, if the function is successful then any previous
$list created by that call is deleted, and a new list is created.
$LISTCPY's output $list identifier is associated with the same image as the input $list (as
associated with $LISTIMG).
$LISTCPY does a page for page copy of the input $list. As such, it is very efficient
(more efficient than $LIST_COPY_ITEMS) but it is also useless for compressing a list
that has become sparse as the result of heavy $LISTINS, $LISTREP, $LISTADJ and
$LISTREM activity. $LISTREP and $LISTADJ will only cause a $list to become sparse if
$list items are replaced with larger $list items or increased in size. For list compression
use $LIST_COPY_ITEMS which is documented in “$LIST_COPY_ITEMS: Copy items
between $lists” on page 164.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTCPY
——————————————————————————————————————————
193
——————————————————————————————————————————
——————————————————————————————————————————
7.87
$LISTDEL: Release CCATEMP storage used for
$list
This function releases CCATEMP storage containing $list items, which helps reduce
CCATEMP usage and possibly reduce disk I/O. The information contained in the $list is
lost after a $LISTDEL.
Note that while it is not strictly necessary to $LISTDEL any $list since they are cleaned
up at the termination of the current procedure, the processing for $LISTDEL is
considerably more efficient than end of evaluation cleanup and can actually reduce
CCATEMP I/O.
The $LISTDEL function accepts one argument and returns a numeric result. It is a
The only argument is the identifier of the $list that is to be deleted.
[%RESULT =]
$LISTDEL(list_identifier)
$LISTDEL Function
%RESULT is zero, or it is a negative error code if an error has occurred.
$LISTDEL Error Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTDEL
——————————————————————————————————————————
194
——————————————————————————————————————————
$LISTFIND: Find string in $list
——————————————————————————————————————————
7.88
$LISTFIND: Find string in $list
This function locates a $list item that exactly matches a specified string.
The $LISTFIND function accepts three arguments and returns the item number of the
$list item that matches the string or an error code. It is a callable $function (“CALLing
The first argument is the identifier of the $list in which a string is to be located. This is a
required argument.
The second argument is the string to be matched. This is a required argument.
The third argument is a number that indicates the item number at which the search is to
begin. If this argument is not specified searching begins at the first item in the $list.
[%RESULT =]
$LISTFIND(list_identifier, search_string,
start_item)
-
$LISTFIND Function
%RESULT is set either to the item number of the first item in the $list that
matches the search criteria, or to a negative number if an error has occurred.
-5
-6
-7
-8
-
Item number not found in $list
String not found (if $list empty, -7)
$LISTFIND Error Codes
The difference between $LISTFIND and $LISTLOC is that with $LISTFIND, a $list item
must match the search string exactly rather than simply containing the search string.
Moreover, $LISTFIND does not allow specification of a range of columns (or positions)
that are to be searched.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTFIND
——————————————————————————————————————————
195
——————————————————————————————————————————
——————————————————————————————————————————
7.89
$LISTFINDI and $LISTFINDI_UP: Find image item
in $list
These functions locate a $list item that exactly matches, or satisfies a specified
relationship to, either of the following:
●
●
The contents of an image item
A value converted to the image item format at the offset and length of the image
item
The difference between $LISTFINDI and $LISTFINDI_UP is the direction of the search:
$LISTFINDI searches from the starting point in ascending item number order, while
$LISTFINDI_UP searches in descending item number order.
$LISTFINDI_UP is only available in Sirius Mods version 7.1 and later.
The $LISTFINDI and $LISTFINDI_UP functions accept five arguments, and they return
the item number of the $list item that matches the image item, or they returns a 0
indicating that the item was not found. All other errors cause the request to be
cancelled.
The first argument is the identifier of the $list in which the value is to be located. This is
a required argument.
The second argument is the image item to be matched. This is a required argument.
The third argument is the value to be found. This is an optional argument. When this
argument is not specified the current contents of the image item specified by argument
two is used as the match value.
The fourth argument is a number that indicates the item number at which the search is to
begin. If this argument is not specified searching begins at the first item in the $list for
$LISTFINDI, and at the last item for $LISTFINDI_UP.
The fifth argument is a string comparison operator that indicates the required
relationship between the match value and the item in the $list. Valid comparison
operators are EQ, NE, LE, LT, GE, and GT. If this argument is not specified or null, an
equality test (EQ) is done on all $list items. This argument is only available in Sirius
Mods version 6.5 and later.
%RESULT = $LISTFINDI(list_identifier, image_item, search_value, start_item, comp_operator)
$LISTFINDI Function
%RESULT is set to the item number of the first item in the $list that matches
the search criterion, or it is set to a 0 if no $list items matched the search
criterion.
——————————————————————————————————————————
196
——————————————————————————————————————————
$LISTFINDI and $LISTFINDI_UP: Find image item in $list
——————————————————————————————————————————
%RESULT = $LISTFINDI_UP(list_identifier, image_item, search_value, start_item, comp_operator)
$LISTFINDI_UP Function
%RESULT is set to the item number of the first item in the $list (starting from
the end of the list) that matches the search criterion, or it is set to a 0 if no $list
items matched the search criterion.
Since the $list item must match the offset and length of the image item, $LISTFINDI and
$LISTFINDI_UP are especially useful for $lists whose contents map to an image. For
example, in
IMAGE PRODUCT
CODE IS BINARY LEN 2
DESC IS STRING LEN 30
END IMAGE
.
.
.
.
FR PRODUCTS
%PRODUCT:CODE = CODE
%PRODUCT:DESC = DESC
%RC = $LISTADDI(%LIST, %PRODUCT:CODE)
END FOR
.
.
.
.
%PRODUCT:CODE = 983
%NUM = $LISTFINDI(%LIST, %PRODUCT:CODE)
%NUM is set to the item number associated with the product with a code of 983.
If a value is specified in addition to the image item, processing is performed as if the
value were assigned to the image item and then the image item restored to its original
value. Any data type conversions required between the value and the image item are
performed before the search is performed. That is, this function:
%NUM = $LISTFINDI(%LIST, %PRODUCT:CODE, 422)
is identical to this:
%TEMP = %PRODUCT:CODE
%PRODUCT:CODE = 422
%PRODUCT:CODE = %TEMP
For inequality comparisons, the appropriate image-item datatype-specific comparison is
performed. For example:
%N = $LISTFINDI_UP(%LIST, %PRODUCT:CODE, -2, , 'GE')
——————————————————————————————————————————
197
——————————————————————————————————————————
——————————————————————————————————————————
would start from the last %list item and would match a $list item with a product code of
-2, -1, or any number greater than or equal to zero, but would not match one with a
product code of -3 or less.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTFINDI and $LISTFINDI_UP
——————————————————————————————————————————
198
——————————————————————————————————————————
$LISTFINDI_SUB: Build $list subset based on image item
——————————————————————————————————————————
7.90
$LISTFINDI_SUB: Build $list subset based on
image item
This function locates all $list items that exactly match the contents of an image item (or a
value converted to the image item format at the offset and length of the image item) and
places these image items into a new $list that is a subset of the old $list.
The $LISTFINDI_SUB function accepts four arguments and returns the list identifier of
the created subset $list, or it returns -3 if CCATEMP is full and this condition is not being
trapped by the 'LISTFC' parameter set with $SIRPARM. All other errors cause the
request to be cancelled.
The first argument is the identifier of the $list in which the value is to be located. This is
The second argument is the image item to be matched. This is a required argument.
The third argument is the value to be found. This is an optional argument. When this
argument is not specified, the current contents of the image item specified by argument
two is used as the match value.
The fourth argument is a string comparison operator that indicates the required
relationship between the match value and the item in the $list. Valid comparison
operators are EQ, NE, LE, LT, GE, and GT. If this argument is not specified or null, an
equality test (EQ) is done on all $list items. This argument is only available in Sirius
Mods version 6.5 and later.
%RESULT = $LISTFINDI_SUB(list_identifier, image_item,
search_value, comp_operator)
-
$LISTFINDI_SUB Function
%RESULT is set to the $list identifier of the subset $list, or to -3 if the function
encountered a CCATEMP full condition.
——————————————————————————————————————————
199
——————————————————————————————————————————
——————————————————————————————————————————
$LISTFINDI_SUB is especially useful for $lists whose contents map to an image. For
example, in
IMAGE PRODUCT
TYPE IS STRING LEN 8
END IMAGE
.
.
.
.
FR PRODUCTS
%PRODUCT:TYPE = TYPE
END FOR
.
.
.
.
%PRODUCT:TYPE = 'Widget'
%WLIST = $LISTFINDI_SUB(%LIST, %PRODUCT:TYPE)
%WLIST is set to the $list identifier for a $list that contains all items in %LIST with a
product type of “Widget”
performed before the subsetting is performed. That is:
%OLIST = $LISTFINDI_SUB(%LIST, %PRODUCT:CODE, 13)
is identical to
%PRODUCT:CODE = 13
%OLIST = $LISTFINDI_SUB(%LIST, %PRODUCT:CODE)
For inequality comparisons, the appropriate image-item datatype-specific comparison is
performed. For example:
%N = $LISTFINDI_SUB(%LIST, %PRODUCT:CODE, 2, - , 'GE')
would select all $list items with a product code of -2, -1, or any number greater than or
equal to zero, but would not select any with a product code of -3 or less.
——————————————————————————————————————————
200
——————————————————————————————————————————
$LISTFINDI_SUB: Build $list subset based on image item
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTFINDI_SUB
——————————————————————————————————————————
201
——————————————————————————————————————————
——————————————————————————————————————————
7.91
$LISTILN: Length of $list item
This function returns a number containing the length of a specified $list item, or it returns
a negative number indicating that an error has occurred.
The $LISTILN function accepts two arguments and returns a numeric result.
The second argument is a string that specifies the item number in the $list. This is a
required argument.
%RESULT = $LISTILN(list_identifier, item_num)
$LISTILN Function
%RESULT is a string that contains the length of the indicated $list item, or it is
a negative number if an error has occurred.
-7 - Item number not found in $list
$LISTILN Error Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTILN
——————————————————————————————————————————
202
——————————————————————————————————————————
$LISTIMG: Associate an image with a $list
——————————————————————————————————————————
7.92
$LISTIMG: Associate an image with a $list
This function returns a 0 indicating that the image has been associated with the $list or a
negative number indicating that an error has occured.
The $LISTIMG function accepts two arguments and returns a numeric result. It is a
The second argument can be a string containing the name of an image, or it can be any
image item from the required image. This is a required argument.
[%RESULT =]
$LISTIMG(list_identifier, image_id)
$LISTIMG Function
%RESULT is a string that contains a 0, or it contains a negative number if an
error has occurred.
-8 - Image not found
$LISTIMG Error Codes
Suppose there is an image with the following description:
IMAGE SALES
ITEM
IS STRING LEN 16
ID
IS STRING LEN 8
PRICE IS BINARY LEN 4
END IMAGE
One can associate this image with the $list %LIST with
%RC = $LISTIMG(%LIST, 'SALES')
or
%RC = $LISTIMG(%LIST, %SALES:ID)
While the latter is syntactically inefficient (:ID is superfluous), it is more efficient
because the image name hashing and lookup is done at compile time rather than
evaluation time.
Functions that can use the association between an image and a $list are:
$LISTADDI
“$LISTADDI: Add image as new $list item” on page 184
——————————————————————————————————————————
203
——————————————————————————————————————————
——————————————————————————————————————————
$LISTINF
“$LISTINF: Retrieve $list item into string” on page 206
$LISTINFI
“$LISTINFI: Retrieve $list item into image” on page 209
$LISTINSI
“$LISTINSI: Insert image into a $list” on page 216
$LISTLOC
“$LISTLOC: Locate string in $list” on page 219
$LISTLUP
“$LISTLUP: Locate string in $list, searching backwards” on page 222
$LISTOVL
“$LISTOVL: Overlay part of $list item with string” on page 235
$LISTREPI
“$LISTREPI: Replace $list item with an image” on page 247
$LISTSRT
“$LISTSORT and $LISTSRT : Sort $list” on page 257
$LISTSUB
“$LISTSUB: Create $list that is subset of input $list” on page 260
The association between an image and a $list is an association between the image and
the particular $list identifier value. A $LISTMOVE does not change the image
association of the target $list, and the image association of a $list is not saved or
restored with $LISTSAV and $LISTRST.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTIMG
——————————————————————————————————————————
204
——————————————————————————————————————————
$LISTIMG_COPY: Copy a $list's image association
——————————————————————————————————————————
7.93
$LISTIMG_COPY: Copy a $list's image
association
This function always returns a 0 indicating that the target $list is now associated with the
same image as the source $list.
The $LISTIMG_COPY function accepts two arguments and returns a 0. It is a callable
The first argument is the target $list identifier. This is a required argument.
The second argument is the source $list identifier. This is a required argument.
[%RESULT =]
$LISTIMG_COPY(target_list_id, source_list_id)
$LISTIMG_COPY Function
All errors cause request cancellation
$LISTIMG Error Codes
If either the target or source $list identifier is missing or invalid, the request is cancelled.
$LISTIMG_COPY does not affect the contents of either the target or source $list; it
simply changes the current image association of the target $list. If the source $list has
no image association, $LISTIMG_COPY removes any image association from the target
$list.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTIMG_COPY
——————————————————————————————————————————
205
——————————————————————————————————————————
——————————————————————————————————————————
7.94
$LISTINF: Retrieve $list item into string
This function returns a string containing specified bytes of the current contents of a
specified $list item or a negative number indicating that an error has occured.
The $LISTINF function accepts four arguments and returns a string result.
The second argument is the number of the item in the $list. This is a required argument.
The third argument is either a number that specifies the starting column from which data
is to be returned, or it is a string containing the name of an image item in the image
associated with the $list using $LISTIMG (“$LISTIMG: Associate an image with a $list”
on page 203). In the latter case, the start column for returned data is the position of the
image item in the image. This is an optional argument and it defaults to 1.
The fourth argument is a number that indicates the number of columns (characters) to
be returned. This is an optional argument and defaults to one of the following values:
●
●
The length of the image item (if the third argument specifies an image item name).
255 (the maximum bytes that can be returned by a $function).
If the default or explicit length specified by the fourth argument is more than the number
of characters after the start column in the requested $list item, only the characters to the
end of the $list item are returned.
%RESULT = $LISTINF(list_identifier, item_num, start_col, length)
$LISTINF Function
%RESULT is a string that contains the indicated piece of the indicated $list
item, or it is a negative number if an error has occurred.
-5
-6
-7
-9
-
Invalid start column or length
$LISTINF Error Codes
——————————————————————————————————————————
206
——————————————————————————————————————————
$LISTINF: Retrieve $list item into string
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTINF
——————————————————————————————————————————
207
——————————————————————————————————————————
——————————————————————————————————————————
7.95
$LISTINF_LSTR: Retrieve $list item into
longstring
This function returns the current contents of a specified $list item as a LONGSTRING.
The $LISTINF_LSTR function accepts two arguments and returns a longstring result.
%RESULT = $LISTINF_LSTR(list_identifier, item_num)
$LISTINF_LSTR Function
%RESULT is a string that contains the contents of the indicated $list item.
$LISTINF_LSTR works almost exactly like $LISTINF except:
1.
It returns a LONGSTRING result so will cause request cancellation if the target
%variable is not big enough to hold the result.
2.
number.
3.
It does not have item position and length arguments (arguments 3 and 4 in
$LISTINF).
$LISTINF_LSTR is available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTINF_LSTR
——————————————————————————————————————————
208
——————————————————————————————————————————
$LISTINFI: Retrieve $list item into image
——————————————————————————————————————————
7.96
$LISTINFI: Retrieve $list item into image
This function copies data from a specified $list item to an image.
The $LISTINFI function accepts three arguments and returns a numeric result. It is a
The third argument can either be a string containing the name of an image or any image
item from the required image. This is an optional argument if a image has been
[%RESULT =]
$LISTINFI(list_identifier, item_num, image_id)
$LISTINFI Function
%RESULT is a number that indicates whether or not an error has occurred.
One way to extract a $list item into an image called 'HEADSTONE' is as follows :
%RC = $LISTINFI(%LIST, %N, 'HEADSTONE')
A more efficient way of doing this would be
%RC = $LISTINFI(%LIST, %N, %HEADSTONE:ID)
The specific image item is irrelevant (as long as it is valid) in this call but is more efficient
than specifying the image name in quotes because in the first example, the image name
must be hashed and looked up (in NTBL) in each invocation of $LISTINFI while in the
second example, the hashing of the image name and lookup happens only once; at
compile time.
An even neater and equally efficient way of coding this would be
%RC = $LISTIMG(%LIST, %HEADSTONE:FNAME)
.
.
.
.
.
.
%RC = $LISTINFI(%LIST, %N)
to specify the image name on the $LISTINFI. This association is also useful in many
other function calls in that it provides a structure to be associated with the $list that is
useful for column oriented functions such as $LISTFINDI and $LISTSRT.
——————————————————————————————————————————
209
——————————————————————————————————————————
——————————————————————————————————————————
0
-5
-6
-7
-8
-
Data successfully copied
Image not found or not active
$LISTINFI Error Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTINFI
——————————————————————————————————————————
210
——————————————————————————————————————————
$LISTINS: Insert string into a $list
——————————————————————————————————————————
7.97
This function inserts arbitrary string data to a $list. Generally, this $list would have been
The $LISTINS function accepts four arguments and returns a numeric result. It is a
The second argument is the item number before which the string is to be inserted. If this
argument is equal to the number of items in the $list plus one, the string is added to the
end of the $list and so is, in this case, identical to a $LISTADD. Because the string is
inserted before the indicated item number, this item number is also the item number of
the new $list item after $LISTINS returns. This is a required argument.
The third argument is a string that is to be inserted into the $list. This is a required
argument.
The fourth argument is a number that indicates the length of the new $list item. This is
an optional argument. Its minimum valid value is 0 and the maximum is 6124 under
Sirius Mods version 6.2 and later and 4096 before. If this value is longer than the length
of the third argument, the third argument is padded on the right with blanks. If this value
is shorter than the length of the third argument, the third argument is truncated.
[%RESULT =]
$LISTINS(list_identifier, item_num, string, length)
$LISTINS Function
string has been inserted into the $list, or to a negative number if an error has
occurred.
$LISTINS Error Codes
$LISTADD, $LISTINS and $LISTNEW allow a User Language programmer to create
arrays in CCATEMP. The following example demonstrates how such a mechanism
might be used.
——————————————————————————————————————————
211
——————————————————————————————————————————
——————————————————————————————————————————
%I = 1
REPEAT FOREVER
IF %I GT $LISTCNT(%LIST) THEN
LOOP END
END IF
%SSN = $LISTINF(%LIST, %I, 1, 9)
F1:
IN FILE CHILDREN FD
PARENT = %SSN
END FIND
%I = %I + 1
FOR EACH RECORD IN F1
%STRING = SSN WITH 'C' WITH NAME WITH ' ' WITH AGE
%COUNT = $LISTINS(%LIST, %STRING, %I)
%I = %I + 1
END FOR
END REPEAT
The length (fourth) argument makes it possible to create $list items that are longer than
function. In the following example, several field values are placed into a $LIST item with
a length of 512.
NAME = SONDHEIM
END FIND
FOR EACH
%RC
%RC
%RC
%RC
%RC
%RC
%RC
%RC
%RC
END FOR
RECORD IN FIND1
= $LISTINS(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
= $LISTOVL(%LIST,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
SSN,
10,
50,
90,
110,
170,
230,
290,
310,
512)
LNAM)
FNAM)
MNAM)
ADD1)
ADD2)
ADD3)
CITY)
ST)
A $LISTINS can result in the splitting of a $list leaf page. Once a leaf page is split, it will
not be merged back together, even if subsequent $LISTREMs makes this possible.
Because of this, heavy use of $LISTINS and $LISTREM can result in “sparse” $lists
which place an unnecessary burden on the buffer pool and CCATEMP. It can also result
in an inability to add an item to the end of the $list (via $LISTADD) because of a full
pointer page, even though the $list is nowhere near the theoretical capacity for a $list.
To make matters worse, $LISTCPY does a page-for-page copy of a $list so does not
result in any compression of the resultant $list. $List compression can be done using
the $LIST_COPY_ITEMS function, documented in “$LIST_COPY_ITEMS: Copy items
——————————————————————————————————————————
212
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTINS
——————————————————————————————————————————
213
——————————————————————————————————————————
——————————————————————————————————————————
7.98
$LISTINS_LSTR: Insert string into a $list
This function inserts longstring data into a $list. Generally, this $list would have been
The $LISTINS_LSTR function accepts three arguments and returns a numeric result. It
The second argument is the item number before which the longstring is to be inserted. If
this argument is equal to the number of items in the $list plus one, the longstring is
added to the end of the $list and so is, in this case, identical to a $LISTADD_LSTR
Because the string is inserted before the indicated item number, this item number is also
the item number of the new $list item after $LISTINS_LSTR returns. This is a required
argument.
The third argument is a longstring that is to be inserted into the $list. This is a required
argument.
[%RESULT =]
$LISTINS_LSTR(list_id, item_num, longstring)
$LISTINS_LSTR Function
string has been inserted into the $list, or to a negative number if an error has
occurred.
$LISTINS_LSTR Error Codes
Before Sirius Mods version 6.6, it was a request cancelling error to try to insert a
longstring longer than the size limit of a Stringlist item: 6124 bytes. This limitation was
eliminated in Sirius Mods version 6.6.
$LISTINS_LSTR works almost exactly like $LISTINS except:
1.
It accepts a LONGSTRING input. $LISTINS_LSTR can be used with regular strings
as well to pick up automatic request cancellation on programming errors.
2.
number.
3.
It does not have an item length argument (argument 4 in $LISTINS).
——————————————————————————————————————————
214
——————————————————————————————————————————
$LISTINS_LSTR: Insert string into a $list
——————————————————————————————————————————
A $LISTINS_LSTR can result in the splitting of a $list leaf page. Once a leaf page is
split, it will not be merged back together, even if subsequent $LISTREMs makes this
possible. Because of this, heavy use of $LISTINS_LSTR and $LISTREM can result in
“sparse” $lists which place an unnecessary burden on the buffer pool and CCATEMP.
To make matters worse, $LISTCPY does a page-for-page copy of a $list so does not
result in any compression of the resultant $list. $List compression can be done using
$LISTINS_LSTR is available in version 6.2 and later of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTINS_LSTR
——————————————————————————————————————————
215
——————————————————————————————————————————
——————————————————————————————————————————
7.99
$LISTINSI: Insert image into a $list
This function inserts data from an image into a $list. Generally, this $list would have
been created with the $LISTNEW function.
The $LISTINSI function accepts four arguments and returns a numeric result. It is a
The second argument is the item number before which the image is to be inserted. If
this argument is 1, the image is inserted before the first item in the $list. If this argument
equals the number of items in the $list plus one, the image is added after the last $list
item and so is identical to a $LISTADDI. This is a required argument and must have a
value between 1 and the number of items in the $list plus 1, inclusive.
item from the required image. This is an optional argument if a image has been
The fourth argument is a number that indicates the length of the inserted $list item. This
is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under
Sirius Mods version 6.2 and later and 4096 before. If this value is longer than the length
of the image, the image is padded on the right with blanks. If this value is shorter than
the length of the image, the image is truncated.
[%RESULT =]
$LISTINSI(list_id, item_num, image_id, length)
$LISTINSI Function
image has been inserted into the $list, or to a negative number if an error has
-8 - Image not active or not found
$LISTINSI Error Codes
One application of $LISTINSI is to create a large sorted array, although this can also be
achieved (usually more efficiently) with $LISTSRT. The following example demonstrates
how such a mechanism might be used, with the $list items in order by SSN:
——————————————————————————————————————————
216
——————————————————————————————————————————
$LISTINSI: Insert image into a $list
——————————————————————————————————————————
IMAGE CUST
SSN
IS STRING LEN 10
NAME
IS STRING LEN 20
END IMAGE
FIND1:
FIND ALL RECORDS FOR WHICH
NAME = SMITH
END FIND
%CUST:SSN
= SSN
%CUST:NAME = NAME
%CUST:BDATE = BDATE
IF %CUST:SSN LT $LISTINF(%LIST, %I, 1, 10) THEN
LOOP END
END IF
END FOR
%COUNT = $LISTINSI(%LIST, %I, 'CUST')
END FOR
The above example can be made more efficient by coding the $LISTINSI as follows.
%COUNT = $LISTINSI(%LIST, %I, %CUST:NAME)
image name in quotes because in the first example, the image name must be hashed
and looked up (in NTBL) in each invocation of $LISTINSI while in the second example,
the hashing of the image name and lookup happens only once; at compile time.
. . . . . .
%COUNT = $LISTINSI(%LIST, %I)
END FOR
to specify the image name on the $LISTINSI. This association is also useful in many
useful for column oriented functions such as $LISTFINDI and $LISTSRT.
A $LISTINSI can result in the splitting of a $list leaf page. Once a leaf page is split, it will
not be merged back together, even if subsequent $LISTREMs make this possible.
Because of this, heavy use of $LISTINS and $LISTREM can result in “sparse” $lists,
——————————————————————————————————————————
217
——————————————————————————————————————————
——————————————————————————————————————————
which places an unnecessary burden on the buffer pool and CCATEMP. It can also
result in not being able to add an item to the end of the $list (via $LISTADD) because of
a full pointer page, even though the $list is nowhere near the theoretical capacity for a
$list. To make matters worse, $LISTCPY does a page-for-page copy of a $list, so it
results in no compression of the resultant $list. $List compression can be done using
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTINSI
——————————————————————————————————————————
218
——————————————————————————————————————————
$LISTLOC: Locate string in $list
——————————————————————————————————————————
7.100
This function locates a specified string in a $list.
The $LISTLOC function accepts six arguments and returns the item number of the $list
item containing the string or an error code.
The first argument is the identifier of the $list in which a string is to be located. This is a
required argument.
The second argument is a number that indicates the item number at which the search is
to begin. If this argument is not specified searching begins at the first item in the $list.
The third argument is the string to be located. If this argument is not specified, all $list
items are considered to contain the search string.
The fourth argument is either a number that specifies the starting column of a range of
columns in which the search string must be located or a string containing the name of an
image item in the image associated with the $list using $LISTIMG (“$LISTIMG:
Associate an image with a $list” on page 203). In the latter case, the start column for the
search is the position of the image item in the image. This is an optional argument and
defaults to 1.
The fifth argument is a number that specifies the ending column of a range of columns in
which the search string must be located. This is an optional argument and defaults to
one of the following values:
●
●
if the fourth argument specifies an image item name, the position of the end of the
image item in the image
otherwise, 6124 for Sirius Mods version 6.2 and later, and 4096 before.
If the sixth argument is a non-zero integer, then the width of the column range is reduced
to a maximum of 256.
The sixth argument is an indicator for case-insensitive comparisons. If this argument is
a non-zero integer, the string comparisons use $list item data translated to uppercase
(hence your search string should be passed as an uppercase value). This is an optional
argument and defaults to zero. If the sixth argument is 1, then the width of the column
range is reduced to a maximum of 256.
%RESULT = $LISTLOC(list_identifier, start, search_string
start_col, end_col, case_ignore)
-
$LISTLOC Function
%RESULT is set either to the item number of the first item in the $list that
matches the search criteria, or to a negative number if an error has occurred.
——————————————————————————————————————————
219
——————————————————————————————————————————
——————————————————————————————————————————
-5
-6
-7
-8
-9
-
Invalid column range
$LISTLOC Error Codes
The following code locates a string in columns 31 through 39 of a $list.
%NUM = $LISTLOC(%LIST, , 'EUDAEMONIC', 31, 39)
In the following code, an image is associated with the $list, items are added to the $list
from the image and then the $list is searched for an item that contains a particular value
in the columns associated with a specific image item.
IMAGE CUST
LNAME
FNAME
ID
END IMAGE
IS STRING LEN 30
IS STRING LEN 30
IS STRING LEN 9
PREPARE IMAGE CUST
%LIST = $LISTNEW
%RC
= $LISTIMG(%LIST, %CUST:LAME)
.
.
.
.
.
FOR EACH RECORD IN LCUST
.
.
.
.
.
%RC = $LISTADDI(%LIST)
.
.
.
.
.
END FOR
.
.
.
.
.
%ITEMNUM = $LISTLOC(%LIST, , %LOCID, 'ID')
Note that this use of an image item name simply sets the range of columns for a match.
If an entry with an exact match for the image item is required, $LISTFINDI should be
used.
——————————————————————————————————————————
220
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTLOC
——————————————————————————————————————————
221
——————————————————————————————————————————
——————————————————————————————————————————
7.101
$LISTLUP: Locate string in $list, searching
backwards
This function locates a specified string in a $list, searching the $list items in reverse
order.
The $LISTLUP function accepts six arguments and returns a numeric result.
%RESULT = $LISTLUP(list_identifier, start, search_string,
start_col, end_col, case_ignore)
-
$LISTLUP Function
%RESULT is set to the item number of the first item in the $list going
backwards from the starting item number that matches the search criteria, or it
is set to a negative number if an error has occurred.
●
The first argument is the identifier of the $list in which a string is to be located. This
is a required argument.
●
The second argument is the item number at which the search is to begin. If this
argument is not specified searching begins at the last item in the $list.
●
The third argument is the string to be located. If this argument is not specified, all
$list items are considered to contain the search string.
●
The fourth argument is a number that specifies the starting column of a range of
columns in which the search string must be located or a string containing the name
of an image item in the image associated with the $list using $LISTIMG (“$LISTIMG:
Associate an image with a $list” on page 203). In the latter case, the start column
for the search is the position of the image item in the image. This is an optional
argument and defaults to 1.
●
The fifth argument is a number that specifies the ending column of a range of
columns in which the search string must be located. This is an optional argument
and defaults to one of the following values:
▪
if the fourth argument specifies an image item name, the position of the end of
the image item in the image
▪ otherwise, 6124 for Sirius Mods version 6.2 and later, and 4096 before.
If the sixth argument is a non-zero integer, then the width of the column range is
reduced to a maximum of 256.
●
The sixth argument is an indicator for case-insensitive comparisons. If this
argument is a non-zero integer, the string comparisons use $list item data translated
to uppercase (hence your search string should be passed as an uppercase value).
This is an optional argument and defaults to zero. If the sixth argument is 1, then
the width of the column range is reduced to a maximum of 256.
——————————————————————————————————————————
222
——————————————————————————————————————————
$LISTLUP: Locate string in $list, searching backwards
——————————————————————————————————————————
-5
-6
-7
-8
-9
-
$LISTLUP Error Codes
The following code locates a string anywhere in a $list item, searching backwards
starting at item 100.
%NUM = $LISTLUP(%LIST, 100, 'VIETNAMERICA')
In the following code, an image is associated with the $list, items are added to the $list
from the image and then the $list is searched backwards from the last item for an item
that contains a particular value in the columns associated with a specific image item.
IMAGE CUST
LNAME
FNAME
ID
END IMAGE
IS STRING LEN 30
IS STRING LEN 30
IS STRING LEN 9
PREPARE IMAGE CUST
%LIST = $LISTNEW
%RC
= $LISTIMG(%LIST, %CUST:LAME)
.
.
.
.
.
FOR EACH RECORD IN LCUST
.
.
.
.
.
.
.
.
.
.
END FOR
.
.
.
.
.
%ITEMNUM = $LISTLUP(%LIST, , %LOCID, 'ID')
——————————————————————————————————————————
223
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTLUP
——————————————————————————————————————————
224
——————————————————————————————————————————
$LISTMOVE: Move a $list
——————————————————————————————————————————
7.102
This function changes the association of a $list from one $list identifier to another. It is
especially useful for making it possible to repeatedly execute the same set of code that
creates $lists without losing the results of previous executions.
The $LISTMOVE function accepts two arguments and returns a numeric result.
The first argument is the identifier of the target $list. This is a required argument.
The second argument is the identifier of the source $list. This is a required argument.
%RESULT = $LISTMOVE(list_id_target, list_id_source)
$LISTMOVE Function
%RESULT is set either to the number of items in the moved $list, or to an error
code.
-6 - Source or target $list identifier invalid
$LISTMOVE Error Codes
If the target $list for $LISTMOVE is not empty when the function is invoked the current
contents are deleted before the source $list contents replace it. That is,
%RC = $LISTMOVE(%TARGET, %SOURCE)
is equivalent to
%RC = $LISTDEL(%TARGET)
%RC = $LISTMOVE(%TARGET, %SOURCE)
After a $LISTMOVE is completed, the source $list is empty since its former contents are
then associated with the target $list.
$LISTMOVE performs no logical I/O; it simply moves the pointer to the anchor page for a
$list from one area of VTBL to another. Because of this $LISTMOVE is very efficient, no
matter what the size of the $list being moved.
Many $functions, for example $LISTNEW, $LISTCPY, and $LISTSRT, return the same
$list identifier for each particular instance of the $function. Because of this, it can be
inconvenient writing code that uses these functions if the code is to be executed
repeatedly. For example, suppose you have a subroutine that simply sorts an input $list.
A natural way to code this might be
——————————————————————————————————————————
225
——————————————————————————————————————————
——————————————————————————————————————————
SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT)
%OLIST IS FLOAT
%RC
IS FLOAT
%OLIST = $LISTSRT(%LIST, '1,10,A')
%RC
= $LISTDEL(%LIST)
%LIST = %OLIST
RETURN
END SUBROUTINE
The problem with this subroutine is that it always returns the same $list identifier in
%LIST. This means that if it is invoked multiple times with different input $lists, only the
result of the last invocation will ever be saved since all invocations will be associated
with the same $list identifier. $LISTMOVE makes it possible to make such a subroutine
completely reentrant.
SUBROUTINE LSORT(%LIST IS FLOAT)
%OLIST IS FLOAT
%RC
IS FLOAT
%OLIST = $LISTSRT(%LIST, '1,10,A')
%RC
= $LISTMOVE(%LIST, %OLIST)
RETURN
END SUBROUTINE
With $LISTMOVE, the result of subroutine LSORT is associated with the identifier of the
input $list so it can be invoked with different input $lists without interfering with the
results of previous invocations.
Another common problem $LISTMOVE helps with is the problem that occurs in scrolling
applications where an end-user might be allowed to sort a $list based on many different
sort criteria. Intuitively, this would map to a simple chunk of code such as
%SLIST = $LISTSRT(%LIST, %CRITERIA)
%RC
= $LISTDEL(%LIST)
%LIST = %SLIST
Unfortunately, in such an application, the above chunk of code might be executed
multiple times which means that on the second invocation, the $LISTDEL would actually
delete the result of the $LISTSRT. Before the availability of $LISTMOVE, a common
technique for dealing with this was to have two identical $LISTSRT statements that
would get alternately executed on consecutive invocations of the same chunk of code,
as in
——————————————————————————————————————————
226
——————————————————————————————————————————
——————————————————————————————————————————
%SWITCH = 1 - %SWITCH
IF %SWITCH THEN
ELSE
END IF
%RC
%LIST
= $LISTDEL(%LIST)
= %SLIST
Needless to say, this is quite ugly. With $LISTMOVE, the code can be simplified to
%RC
= $LISTMOVE(%LIST, %SLIST)
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTMOVE
——————————————————————————————————————————
227
——————————————————————————————————————————
——————————————————————————————————————————
7.103
$LISTNEW: Create empty $list
This function creates an empty $list.
The $LISTNEW function accepts one argument and returns a numeric result.
The first argument, if set to the string ‘NOREL’, indicates that the contents of the $list are
not to be emptied when a RELEASE ALL RECORDS statement is executed. This is an
optional argument.
%RESULT = $LISTNEW(option)
$LISTNEW Function
%RESULT is set to the identifier of the created empty $list.
There are no error codes associated with $LISTNEW.
All invocations of a particular call to $LISTNEW will always return the same value. Each
time that call is executed, any previous $list created by that call is deleted, and a new list
is created.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTNEW
——————————————————————————————————————————
228
——————————————————————————————————————————
$LISTNEWA: Create array of empty $lists
——————————————————————————————————————————
7.104
This function creates an array of empty $lists.
The $LISTNEWA function accepts eight arguments and returns a numeric result. It is a
[%RC =]
$LISTNEWA(%array, option, start_dim1, size_dim1,
start_dim2, size_dim2, start_dim3, size_dim3)
$LISTNEWA Function
●
The first argument is the array which will contain the identifiers of the $lists which
are created. This is a required argument.
●
The second argument, if set to the string ‘NOREL’, indicates that the contents of the
$lists are not to be emptied when a RELEASE ALL RECORDS statement is
executed. This is an optional argument.
●
The third argument is the start index for the created $list identifiers in the first
dimension of the array. This is an optional argument; its default is 1. It must be
between 1 and the size of the first dimension of the array.
●
The fourth argument is the number of indices for the created $list identifiers in the
first dimension of the array. This is an optional argument; its default is the number
of indices in the first dimension of the array minus the start index, minus 1 (that is,
all of the indices starting with the start index). It must be between 1 and this default
value.
●
The fifth argument is the start index for the created $list identifiers in the second
between 1 and the size of the second dimension of the array.
●
The sixth argument is the number of indices for the created $list identifiers in the
second dimension of the array. This is an optional argument; its default is the
number of indices in the second dimension of the array minus the start index, minus
1 (that is, all of the indices starting with the start index). It must be between 1 and
this default value.
●
The seventh argument is the start index for the created $list identifiers in the third
between 1 and the size of the third dimension of the array.
●
The eighth argument is the number of indices for the created $list identifiers in the
third dimension of the array. This is an optional argument; its default is the number
of indices in the third dimension of the array minus the start index, minus 1 (that is,
——————————————————————————————————————————
229
——————————————————————————————————————————
——————————————————————————————————————————
value.
0 - No errors
1 - Invalid array bound
$LISTNEWA return codes
All invocations of a particular call to $LISTNEWA will always set the same values to
those elements of the array that are being set. Each time that call is executed, any
previous $lists in those elements created by that call are deleted, and a new list is
created.
$LISTNEWA performs the same processing as $LISTNEW, but it allows the creation of
multiple lists in one call, and it allows you to manage the lists in an array. For example:
B
%I
%X
%Y
%L
%X
%Y
IF
FLOAT
FLOAT
FLOAT
FLOAT ARRAY(10)
= $READ('Number of procs to display, up to 10')
= $LISTNEWA(%L, , 1, %X)
%Y NE 0 THEN
PRINT 'Error ' %X ' creating ' %X 'lists'
STOP
END IF
FOR %I FROM 1 TO %X
%Y = $PROCOPN($READ('Enter proc name'))
%Y = $PROCDAT(%L(%I))
END FOR
PRINT 'Here are the procs, last requested first:'
FOR %I FROM %X TO 1 BY -1
PRINT ' '
PRINT 'Proc number ' %I
FOR %Y FROM 1 TO $LISTCNT(%L(%I))
PRINT $LISTINF(%L(%I), %Y)
END FOR
END FOR
——————————————————————————————————————————
230
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTNEWA
——————————————————————————————————————————
231
——————————————————————————————————————————
——————————————————————————————————————————
7.105
$LISTNEWAI: Create array of empty $lists
associated with image
This function creates an array of empty $lists.
The $LISTNEWAI function accepts nine arguments and returns a numeric result. It is a
[%RC =]
$LISTNEWAI(%array, image_id, option, start_dim1,
size_dim1, start_dim2, size_dim2,
start_dim3, size_dim3 )
-
$LISTNEWAI Function
●
The first argument is the array which will contain the identifiers of the $lists which
are created. This is a required argument.
●
The second argument can either be a string containing the name of an image or any
image item from the required image. This is a required argument.
●
The third argument, if set to the string ‘NOREL’, indicates that the contents of the
$lists are not to be emptied when a RELEASE ALL RECORDS statement is
executed. This is an optional argument.
●
The fourth argument is the start index for the created $list identifiers in the first
between 1 and the size of the first dimension of the array.
●
The fifth argument is the number of indices for the created $list identifiers in the first
dimension of the array. This is an optional argument; its default is the number of
indices in the first dimension of the array minus the start index, minus 1 (that is, all
of the indices starting with the start index). It must be between 1 and this default
value.
●
The sixth argument is the start index for the created $list identifiers in the second
between 1 and the size of the second dimension of the array.
●
The seventh argument is the number of indices for the created $list identifiers in the
second dimension of the array. This is an optional argument; its default is the
number of indices in the second dimension of the array minus the start index, minus
1 (that is, all of the indices starting with the start index). It must be between 1 and
this default value.
●
The eighth argument is the start index for the created $list identifiers in the third
between 1 and the size of the third dimension of the array.
——————————————————————————————————————————
232
——————————————————————————————————————————
$LISTNEWAI: Create array of empty $lists associated with image
——————————————————————————————————————————
●
The ninth argument is the number of indices for the created $list identifiers in the
third dimension of the array. This is an optional argument; its default is the number
of indices in the third dimension of the array minus the start index, minus 1 (that is,
value.
0 - No errors
1 - Invalid array bound
$LISTNEWAI return codes
All invocations of a particular call to $LISTNEWAI will always set the same values to
those elements of the array that are being set. Each time that call is executed, any
previous $lists in those elements created by that call are deleted, and a new list is
created.
$LISTNEWAI performs the same processing as $LISTNEWA (“$LISTNEWA: Create
array of empty $lists” on page 229) and a $LISTIMG (“$LISTIMG: Associate an image
with a $list” on page 203) call for each $list maped to the array but does so in a single
call.
$LISTNEWAI is available in version 6.2 and later of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTNEWAI
——————————————————————————————————————————
233
——————————————————————————————————————————
——————————————————————————————————————————
7.106
$LISTNEWI: Create empty $list associated with
image
This function creates an empty $list. The created $list is associated with an image
exactly as if the $LISTNEW call was followed by a $LISTIMG call (“$LISTIMG:
Associate an image with a $list” on page 203).
The $LISTNEWI function accepts two arguments and returns a numeric result.
The first argument can either be a string containing the name of an image or any image
item from the required image. This is a required argument.
The second argument, if set to the string ‘NOREL’, indicates that the contents of the $list
are not to be emptied when a RELEASE ALL RECORDS statement is executed. This is
an optional argument.
%RESULT = $LISTNEWI(image_id, option)
$LISTNEWI Function
%RESULT is set to the identifier of the created empty $list.
There are no error codes associated with $LISTNEWI though the absence of the image
identifier or an invalid image identifier will cause request cancellation.
All invocations of a particular call to $LISTNEWI will always return the same value. Each
time that call is executed, any previous $list created by that call is deleted, and a new list
is created.
$LISTNEWI is available in version 6.2 and later of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTNEWI
——————————————————————————————————————————
234
——————————————————————————————————————————
$LISTOVL: Overlay part of $list item with string
——————————————————————————————————————————
7.107
This function is used to overlay a $list item with a string. This function returns an integer
that indicates whether or not the operation was successful.
The $LISTOVL function accepts four arguments and returns a numeric result. It is a
The first argument is the identifier of the $list in which an item is to be updated. This is a
required argument.
The second argument is the item number which is to be updated. This is a required
argument.
The third argument is the column (or character) number where data is to be overlayed in
the $list item or a string containing the name of an image item in the image associated
with the $list with $LISTIMG (“$LISTIMG: Associate an image with a $list” on page 203).
In the latter case the column where the data is overlayed is the position of the image
item in the image. If this argument is not specified, data is overlayed starting at the first
character in the $list item.
The fourth argument is a string that is to overlay the current contents of the indicated
$list item.
[%RESULT =]
$LISTOVL(list_identifier, item_num, start_col, overlay_string)
$LISTOVL Function
%RESULT is set to a number which indicates whether or not the operation was
successful.
1
0
-5
-6
-7
-9
-
$List item overlayed
$List item overlayed but overlay string truncated
Invalid start column or length
$LISTOVL Completion Codes
A $LISTOVL will never change the length of a $list item. If the overlay string does not
completely overlay a $list item, the characters after the overlay string in the original $list
item remain unchanged. For example, if the original $list item contained
'IT WAS THE BEST OF TIMES, IT WAS THE FIRST TIME'
the function
——————————————————————————————————————————
235
——————————————————————————————————————————
——————————————————————————————————————————
%RESULT = $LISTOVL(%LIST, %ITEM, 38, 'WORST')
would set %RESULT to 1 to indicate that the function was successful and the $list item
would be set to
'IT WAS THE BEST OF TIMES, IT WAS THE WORST TIME'
If the start column plus the length of the overlay string is greater than the current length
of the $list item the overlay string is truncated. For example, if the original $list item
contained
'TIS A FAR BETTER THING I DO THAN YOU EVER DID'
the function
%RESULT = $LISTOVL(%LIST, %ITEM, 39, 'I HAVE EVER DONE BEFORE')
would set %RESULT to 0 to indicate that the function was successful but that the
overlay string was truncated and the $list item would be set to
'TIS A FAR BETTER THING I DO THAN I HAVE EVER '
$LISTOVL acts slightly differently when an image item name is specified rather than a
starting column number. Namely the overlay string will be padded to the length of the
image item if it is shorter and truncated if it is longer. For example, in
IMAGE BOOK
TITLE
IS STRING LEN 22
AUTHOR
IS STRING LEN 8
PAGES
IS STRING LEN 5 JUSTIFY RIGHT
END IMAGE
PREPARE IMAGE BOOK
%LIST = $LISTNEW
%RC = $LISTIMG(%LIST, %BOOK:AUTHOR)
%BOOK:TITLE = 'A TALE OF TWO CITIES'
%BOOK:AUTHOR = 'DICKENS'
%BOOK:PAGES = '511'
a
%RC = $LISTOVL(%LIST, 1, 'AUTHOR', 'TWAIN')
would set %RC to 1 because no truncation occurred, and would result in item 1 in $list
%LIST containing
'A TALE OF TWO CITIES
TWAIN
511'
——————————————————————————————————————————
236
——————————————————————————————————————————
——————————————————————————————————————————
whereas a
%RC = $LISTOVL(%LIST, 1, 'AUTHOR', 'FITZGERALD')
would set %RC to 0 because the overlayed name would be truncated and result in item
1 in $list %LIST containing
'A TALE OF TWO CITIES
●
●
●
●
●
●
●
●
FITZGERA 511'
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTOVL
——————————————————————————————————————————
237
——————————————————————————————————————————
——————————————————————————————————————————
7.108
$LISTOVLI: Overlay part of $list item with image
item
This function is used to overlay a $list item with the contents of an image item or a
specified value at the offset of the image item in the image. This function returns an
integer that indicates whether or not the operation was successful.
The $LISTOVLI function accepts four arguments and always returns a 0. All errors
cause the request to be cancelled. It is a callable $function (“CALLing Sirius Mods
functions” on page 32).
The first argument is the identifier of the $list in which an item is to be updated. This is a
required argument.
The second argument is the item number to be overlayed. This is a required argument.
The third argument is the image item that indicates the overlay offset and length and, if
the third argument is not specified, the value to be overlayed in the $list item. This is a
required argument.
The fourth argument is the value to be place at the image item's offset in the $list item.
This is an optional argument. If this argument is not specified, the contents of the image
item specified by argument three are used to overlay the $list item.
[%RESULT =]
$LISTOVLI(list_identifier, item_num,
image_item, overlay_value)
-
$LISTOVLI Function
%RESULT is set to 0.
A $LISTOVLI will never change the length of a $list item. If the overlay string does not
completely overlay a $list item, the characters after and before the overlay string remain
unchanged.
If the start column plus the length of the image item is greater than the current length of
the $list item the request is cancelled.
——————————————————————————————————————————
238
——————————————————————————————————————————
$LISTOVLI: Overlay part of $list item with image item
——————————————————————————————————————————
$LISTOVLI is especially useful for $lists whose contents map to an image. For example,
in
IMAGE PRODUCT
END IMAGE
.
.
.
.
FR PRODUCTS
END FOR
.
.
.
.
%PRODUCT:CODE = 983
%PRODUCT:DESC = 'Insertion widget'
%NUM = $LISTOVLI(%LIST, %NUM, %PRODUCT:DESC)
The $list item associated with product code 983 has its description overlayed with a new
description.
performed before the overlay is performed. That is
%NUM = $LISTOVLI(%LIST, %NUM, %PRODUCT:CODE, 543)
is identical to
%PRODUCT:CODE = 543
%NUM = $LISTOVLI(%LIST, %NUM, %PRODUCT:CODE)
——————————————————————————————————————————
239
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTOVLI
——————————————————————————————————————————
240
——————————————————————————————————————————
$LISTREM: Remove item from $list
——————————————————————————————————————————
7.109
$LISTREM: Remove item from $list
This function removes an item from a $list, decrementing the item numbers of all items
which follow.
The $LISTREM function accepts two arguments and returns a numeric result. It is a
The second argument is a number that specifies the item number in the $list. This is a
required argument. p. The number of items remaining in the $list after the removal is
returned as the result of this function. If removal of an item makes a CCATEMP $list
page empty, that page is removed from use by the $list. Except for sorted lists which
are only one page in size, space taken up by the removed item is made available on the
$list page. If there are no items remaining after the removal, the $list is deleted.
[%RESULT =]
$LISTREM(list_identifier, item_num)
$LISTREM Function
%RESULT is the number of items remaining in the $list after the removal, or is
a negative number if an error has occurred.
-7 - Item number not found in $list
$LISTREM Error Codes
Consecutive $list leaf pages that are made relatively empty with $LISTREM will not be
merged together. Because of this, heavy use of $LISTINS and $LISTREM can result in
“sparse” $lists which place an unnecessary burden on the buffer pool and CCATEMP. It
can also result in an inability to add an item to the end of the $list (via $LISTADD)
because of a full pointer page, even though the $list is nowhere near the theoretical
capacity for a $list. To make matters worse, $LISTCPY does a page-for-page copy of a
$list so does not result in any compression of the resultant $list. $List compression can
be done using the $LIST_COPY_ITEMS function, documented in
——————————————————————————————————————————
241
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTREM
——————————————————————————————————————————
242
——————————————————————————————————————————
$LISTREP: Replace a $list item with a string
——————————————————————————————————————————
7.110
$LISTREP: Replace a $list item with a string
This function replaces an existing $list item with a string. Generally, this $list would have
been created with the $LISTNEW function.
The $LISTREP function accepts four arguments and returns a numeric result. It is a
The second argument is the item number which is to be replaced. This is a required
argument.
The third argument is a string that is to replace the $list item indicated by the second
argument. This is a required argument.
The fourth argument is a number that indicates the length of the new $list item. This is
an optional argument. Its minimum valid value is 0 and the maximum is 6124 under
Sirius Mods version 6.2 and later, and 4096 before. If this value is longer than the length
of the third argument, the third argument is padded on the right with blanks. If this value
is shorter than the length of the third argument, the third argument is truncated. If this
argument is not specified, the new length of the $list item is the length of the
replacement string.
[%RESULT =]
$LISTREP(list_id, item_num, string, length)
$LISTREP Function
%RESULT is set to 0 if the new item length is the same as the replaced item
length, 1 if it is shorter, 2 if it is longer, or a negative number if an error has
occurred.
$LISTREP Error Codes
The following code illustrates how $LISTREP might be used to insert a number of blanks
in front of a range of $list items, say to do indentation.
%BLANKS = $PAD('', ' ', %INDENT)
FOR %I FROM %START TO %END
%DATA = %BLANKS WITH %DATA
%RC
= $LISTREP(%LIST, %I, %DATA)
END FOR
——————————————————————————————————————————
243
——————————————————————————————————————————
——————————————————————————————————————————
The length (fourth) argument makes it possible to create $list items that are longer than
function. In the following example, several field values are placed into a $LIST item with
a length of 512.
NAME = SONDHEIM
END FIND
%RC
= $LISTREP(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
%RC
= $LISTOVL(%LIST,
END FOR
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
%NUM,
SSN,
10,
50,
90,
110,
170,
230,
290,
310,
512)
LNAM)
FNAM)
MNAM)
ADD1)
ADD2)
ADD3)
CITY)
ST)
$LISTREP is extremely efficient if the $list item size is not being changed (return value
for $LISTREP of 0), fairly efficient when a $list item is being replaced with a shorter
string (return value of 1) and can be fairly expensive when a $list item is being replaced
with a longer string (return value of 2). The latter case can be expensive because such
a $LISTREP can result in the splitting of a $list leaf page. Once a leaf page is split, it will
not be merged back together, even if subsequent $LISTREMs makes this possible.
Because of this, heavy use of $LISREPs that increase $list item size (and $LISTINS and
$LISTREM) can result in “sparse” $lists which place an unnecessary burden on the
buffer pool and CCATEMP. $List compression can be done using the
$LIST_COPY_ITEMS function, documented in “$LIST_COPY_ITEMS: Copy items
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTREP
——————————————————————————————————————————
244
——————————————————————————————————————————
$LISTREP_LSTR: Replace a $list item with a longstring
——————————————————————————————————————————
7.111
$LISTREP_LSTR: Replace a $list item with a
longstring
This function replaces an existing $list item with a longstring. Generally, this $list would
have been created with the $LISTNEW function.
The $LISTREP_LSTR function accepts three arguments and returns a numeric result. It
The second argument is the item number which is to be replaced. This is a required
argument.
The third argument is a string that is to replace the $list item indicated by the second
argument. This is a required argument.
[%RESULT =]
$LISTREP_LSTR(list_identifier, item_num, string)
$LISTREP_LSTR Function
occurred.
$LISTREP_LSTR Error Codes
Before Sirius Mods version 6.6, it was a request cancelling error to try to replace a
Stringlist item with a longstring longer than the size limit of a Stringlist item: 6124 bytes.
This limitation was eliminated in Sirius Mods version 6.6.
$LISTREP_LSTR works almost exactly like $LISTREP except:
1.
It accepts a LONGSTRING input. $LISTREP_LSTR can be used with regular
strings as well to pick up automatic request cancellation on programming errors.
2.
number.
3.
It does not have an item length argument (argument 4 in $LISTREP).
$LISTREP_LSTR is extremely efficient if the $list item size is not being changed (return
value for $LISTREP_LSTR of 0), fairly efficient when a $list item is being replaced with a
shorter string (return value of 1) and can be fairly expensive when a $list item is being
——————————————————————————————————————————
245
——————————————————————————————————————————
——————————————————————————————————————————
replaced with a longer string (return value of 2). The latter case can be expensive
because such a $LISTREP_LSTR can result in the splitting of a $list leaf page. Once a
leaf page is split, it will not be merged back together, even if subsequent $LISTREMs
makes this possible. Because of this, heavy use of $LISREP_LSTRs that increase $list
item size (and $LISTINS and $LISTREM) can result in “sparse” $lists which place an
unnecessary burden on the buffer pool and CCATEMP. $List compression can be done
using the $LIST_COPY_ITEMS function, documented in “$LIST_COPY_ITEMS: Copy
items between $lists” on page 164.
$LISTREP_LSTR is available in version 6.2 and later of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTREP_LSTR
——————————————————————————————————————————
246
——————————————————————————————————————————
$LISTREPI: Replace $list item with an image
——————————————————————————————————————————
7.112
This function replaces a $list item with the contents of an image. Generally, this $list
would have been created with the $LISTNEW function.
The $LISTREPI function accepts four arguments and returns a numeric result. It is a
The second argument is the item number which the image is to replace. This is a
required argument.
item from the required image. This is an optional argument if an image has been
The fourth argument is a number that indicates the length of the $list item after the
replacement. This is an optional argument. Its minimum valid value is 0 and the
maximum is 6124 under Sirius Mods version 6.2 and later, and 4096 before. If this value
is longer than the length of the image, the image is padded on the right with blanks. If
this value is shorter than the length of the image, the image is truncated. If this
argument is not specified, the new length of the $list item is the length of the
replacement image.
[%RESULT =]
$LISTREPI(list_id, item_num, image_id, length)
$LISTREPI Function
occurred.
$LISTREPI Error Codes
The following example demonstrates how $LISTREPI can be used to maintain the last
copy of an image for a particular ID in a $list.
——————————————————————————————————————————
247
——————————————————————————————————————————
——————————————————————————————————————————
IMAGE CUST
SSN
IS STRING LEN 10
NAME
IS STRING LEN 20
END IMAGE
.
.
.
.
%LIST = $LISTNEW
REPEAT FOREVER
READ IMAGE CUST
IF $STATUS THEN
LOOP END
END IF
%N = $LISTLOC(%LIST, ,%CUST:SSN, 'SSN')
IF %N LT 0 THEN
%RC = $LISTADDI(%LIST, 'CUST')
ELSE
%RC = $LISTREPI(%LIST, %N, 'CUST')
END IF
END REPEAT
The above example can be made more efficient by coding the $LISTREPI as follows.
%RC = $LISTREPI(%LIST, %CUST:NAME)
image name in quotes because in the first example, the image name must be hashed
and looked up (in NTBL) in each invocation of $LISTREPI while in the second example,
the hashing of the image name and lookup happens only once; at compile time.
REPEAT FOREVER
. . . . . .
IF %N LT 0 THEN
ELSE
%RC = $LISTREPI(%LIST, %N)
END IF
to specify the image name on the $LISTREPI. This association is also useful in many
useful for column oriented functions such as $LISTLOC and $LISTSRT.
——————————————————————————————————————————
248
——————————————————————————————————————————
——————————————————————————————————————————
$LISTREPI is extremely efficient if the $list item size is not being changed (return value
for $LISTREP of 0), fairly efficient when a $list item is being replaced with a shorter
string (return value of 1), and can be fairly expensive when a $list item is being replaced
with a longer string (return value of 2). The latter case can be expensive because such
a $LISTREPI can result in the splitting of a $list leaf page.
Once a leaf page is split, it will not be merged back together, even if subsequent
$LISTREMs make this possible. Because of this, heavy use of $LISREPIs that increase
$list item size (and $LISTINS and $LISTREM) can result in “sparse” $lists, which places
an unnecessary burden on the buffer pool and CCATEMP. It can also result in an
inability to add an item to the end of the $list (via $LISTADD) because of a full pointer
page, even though the $list is nowhere near the theoretical capacity for a $list. $List
compression can be done using the $LIST_COPY_ITEMS function, documented in
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTREPI
——————————————————————————————————————————
249
——————————————————————————————————————————
——————————————————————————————————————————
7.113
$LISTRST: Restore global $list
This function is used to restore a $list previously saved with either the $LIST_GLOBAL,
$LISTSAV, or $LISTSAVE function. $LISTRST is used with these $functions to pass a
$list between requests.
The $LISTRST function accepts one optional argument and returns a numeric result.
The first argument is a string which is the name which had been used to save the list. If
this argument is omitted, the name is the null string.
%RESULT = $LISTRST(name)
$LISTRST Function
%RESULT is set either to the identifier of the restored $list or to a negative
number if an error has occurred.
All invocations of a particular call to $LISTRST will always return the same $list identifier.
Each time that call is executed, if the function is successful then any previous $list
created by that call is deleted, and a new list is created.
After a $list is restored, it is no longer considered "saved" and will be cleaned up at
procedure termination or RELEASE ALL RECORDS processing unless it is saved again.
If you wish to restore a $list and you know that you want it accessible after the current
User Language request, use $LIST_GLOBAL instead of $LISTRST.
If a non-null global $list name has never been used, the $LISTRST function does not
require any CCATEMP access and hence is highly efficient. For example
B
...
%RESULT = $LISTSAV
END
CLOSE ALL
B
%LIST = $LISTRST
...
END
demonstrates the use of $LISTRST to restore a $list created and saved in a separate
request. Because many Sirius Software products use $LISTSAV/$LISTRST with the null
global $list name, care should be taken of the interaction between global $list names
used by your applications and the null $list name.
——————————————————————————————————————————
250
——————————————————————————————————————————
$LISTRST: Restore global $list
——————————————————————————————————————————
-13 - Specified $list accessed in current request
with $LIST_GLOBAL
-14 - No $list is currently saved with specified name
$LISTRST Completion Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTRST
——————————————————————————————————————————
251
——————————————————————————————————————————
——————————————————————————————————————————
7.114
$LISTSAV and $LISTSAVE: Save global $list
These $functions are used to save a $list to be later retrieved with the $LISTRST
function or the $LIST_GLOBAL function. $LISTSAV and $LISTSAVE are used with
$LISTRST or $LIST_GLOBAL to pass a $list between separate requests.
The $LISTSAV and $LISTSAVE functions accept one required argument and one
optional argument and return a numeric result. Both are callable $functions (“CALLing
The first argument is the identifier of the $list to be saved. This is a required argument.
The second argument is a string which is the name under which to save the $list. If this
argument is omitted, the name is the null string. The $LISTRST function can be given
the name under which the $list was saved.
[%RESULT =]
$LISTSAV(list_identifier, name)
[%RESULT =]
$LISTSAVE(list_identifier, name)
$LISTSAV and $LISTSAVE Functions
%RESULT is set either to 0 or, if an error has occurred, to a negative number.
A $list "saved" via $LISTSAV or $LISTSAVE will be cleaned up at user logoff. After a
$list has been "saved" via $LISTSAV or $LISTSAVE it is no longer accessible in the
current request, but will not be cleaned up at request termination or RELEASE ALL
RECORDS processing. The $list is effectively "hidden" until restored via $LISTRST or
$LIST_GLOBAL.
Only one $list can be saved at a time under a given name. For example:
B
FOR %I FROM 1 TO 4
%LIST1 = $LISTNEW
%RESULT = $LISTADD(%LIST1 , $WORD('HE SHE WE IT', , %I) WITH ' ATE')
%RESULT = $LISTSAVE(%LIST1, $WORD('A', , %I))
END FOR
END
The request above produces three $lists, as follows:
1.
HE ATE, successfully saved via $LISTSAVE under name A
2.
SHE ATE, successfully saved via $LISTSAVE under name ''
3.
IT ATE, not saved, but accessible under $list identifier %RESULT for the duration
of the request
——————————————————————————————————————————
252
——————————————————————————————————————————
$LISTSAV and $LISTSAVE: Save global $list
——————————————————————————————————————————
The string WE ATE is not saved (a list was already saved with the name ''), and since
each invocation of $LISTNEW deletes the list associated with it, the list containing WE
ATE was deleted in the last iteration of the FOR loop.
If $LISTSAV or $LISTSAVE is invoked only with a null name argument, CCATEMP is not
used and processing is very efficient. Because many Sirius Software products use
$LISTSAV/$LISTRST with the null global $list name, care should be taken of the
interaction between global $list names used by your applications and the null $list name.
To ensure that a $LISTSAV or $LISTSAVE is not blocked by a previously "saved" list
under a given name, you can simply issue a $LISTRST to restore any previously saved
list under that name, as in
%RESULT = $LISTDEL($LISTRST)
%RESULT = $LISTSAVE(%LIST)
Another way to address the problem of a global $list name already in use is to use the
$LIST_GLOBAL function.
$Lists saved with $LISTSAVE can also be accessed with $LIST_GLOBAL. For
example,
%RESULT = $LISTSAVE(%ALIST, 'MY.GLOBAL.LIST')
%LIST
= $LIST_GLOBAL('MY.GLOBAL.LIST')
is a valid program. While a name is accessed as a global, however, it is not possible to
save another list to the same name. In
%LIST
%RESULT = $LISTSAVE(%ALIST, 'MY.GLOBAL.LIST')
the $LISTSAVE would fail with a return code of -13. It is possible to $LISTSAVE a
global $list to a separate name. In
%LIST
%RESULT = $LISTSAVE(%LIST, 'OTHER.GLOBAL.LIST')
the contents of global list MY.GLOBAL.LIST would be saved under the name
OTHER.GLOBAL.LIST. MY.GLOBAL.LIST would still be a valid global $list but would
be empty.
The only difference between $LISTSAV and $LISTSAVE is that $LISTSAV will not allow
the saving of an empty $list while $LISTSAVE will and that $LISTSAVE will replace an
existing saved $list by the same name as long as the existing list is not active as a
$LIST_GLOBAL list in the current procedure. For example, in
%RESULT = $LISTSAV(%ALIST, 'A.LITTLE.LIST')
%RESULT = $LISTSAV(%BLIST, 'A.LITTLE.LIST')
——————————————————————————————————————————
253
——————————————————————————————————————————
——————————————————————————————————————————
the second $LISTSAV would fail because a $list is already saved under the name
A.LITTLE.LIST. While in
%RESULT = $LISTSAVE(%ALIST, 'A.LITTLE.LIST')
%RESULT = $LISTSAVE(%BLIST, 'A.LITTLE.LIST')
the second $LISTSAVE would succeed.
0 - $list successfully saved
-3 - No room to add list name
-13 - Another $list has already been saved with the
specified name
-14 - $list is null, is not saved ($LISTSAV only)
$LISTSAV and $LISTSAVE Completion Codes
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTSAV and $LISTSAVE
——————————————————————————————————————————
254
——————————————————————————————————————————
$LISTSAVL: Count and names of available global $lists
——————————————————————————————————————————
7.115
$LISTSAVL: Count and names of available
global $lists
This function retrieves the count of items in, and names of, the $lists that have been
saved by either the $LIST_GLOBAL, $LISTSAV, or $LISTSAVE function and not, in the
current request, restored by $LISTRST.
The $LISTSAVL function accepts one argument and returns a numeric error code. It is a
contents of the $list are deleted and replaced with the item count and names of available
saved $lists. Each $list item contains the 10-digit number of items, followed by a blank,
followed by the name of a global $list not yet restored by $LISTRST in the current User
Language request.
[%RESULT =]
$LISTSAVL(list_identifier)
$LISTSAVL Function
%RESULT is a either zero, indicating success, or a negative error code.
-3 - Not enough room to store list of counts and names
-6 - Invalid $list identifier
$LISTSAVL return codes
The following procedure uses $LISTSAV to save information in various lists, and uses
$LISTSAVL and $LISTRST to display the saved lists:
——————————————————————————————————————————
255
——————————————————————————————————————————
——————————————————————————————————————————
B
...
%RESULT = $LISTSAV(%LIST, 'name')
...
END
CLOSE ALL
B
%SAVED = $LISTNEW
%RESULT = $LISTSAVL(%SAVED)
FOR %I FROM 1 TO $LISTCNT(%SAVED)
%N = $LISTINF(%SAVED, %I, 1, 10)
%NAME = $LISTINF(%SAVED, %I, 12)
PRINT %N ' items in ' %NAME ':'
%LIST = $LISTRST(%NAME)
FOR %J FROM 1 TO %N
PRINT $LISTINF(%LIST, %J)
END FOR
END FOR
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTSAVL
——————————————————————————————————————————
256
——————————————————————————————————————————
$LISTSORT and $LISTSRT : Sort $list
——————————————————————————————————————————
7.116
Each of these functions sorts a $list and builds a new $list containing the sorted data
from the input $list. The difference between $LISTSORT and $LISTSRT is that, if the
input $list is empty, $LISTSORT returns an empty $list while $LISTSRT returns a -11
error code. Because of this, it is generally recommended that $LISTSORT be used,
instead of $LISTSRT. The $list can be sorted in ascending or descending EBCDIC
order for specified ranges of columns.
The $LISTSORT and $LISTSRT functions accept two arguments and return a numeric
result.
%RESULT = $LISTSORT(list_identifier, sort_order)
%RESULT = $LISTSRT(list_identifier, sort_order)
$LISTSORT and $LISTSRT Functions
%RESULT is the identifier of the created $list or is an error code if the new $list
was not created. $List identifiers are always positive integers and error codes
are always negative integers.
●
The first argument is the identifier of the input $list. This is a required argument.
●
The second argument is a string that specifies the sort order. The sort order is a
character string that contains blank separated triplets and/or quadruplets.
The triplets are made up of a start column, length and the letter A for ascending or
D for descending (see below for note about sorting using an implied CENTSPAN of
1975). The quadruplets are made up of a start column, length, format, and the letter
A for ascending or D for descending (see below for note about sorting using an
implied CENTSPAN of 1975).
A format in the quadruplets can be one of these:
CH
Character format. The default.
FI
Fixed point format. Must have length 1, 2, 3 or 4.
FL
Floating point format. Must have length 4, 8 or 16.
PD
Packed decimal format. Must have length between 1 and 16, inclusive.
ZD
Zoned decimal format. Must have length between 1 and 16, inclusive.
The entities in a triplet or quadruplet must be separated by commas. For example,
specifying a sort order of 1,10,A 18,4,FI,D would result in a $list being sorted in
ascending order based on columns 1 through 10 and descending order based on a
signed fixed point comparison of columns 18 through 21.
——————————————————————————————————————————
257
——————————————————————————————————————————
——————————————————————————————————————————
For $lists that have been associated with an image via $LISTIMG (“$LISTIMG:
Associate an image with a $list” on page 203), the start column and length in any
triplet and the start column, length, and format in any quadruplet can be replaced by
the name of an image item in the associated image.
-3 - No room in CCATEMP
-10 - Invalid sort order
-11 - Input $list is empty ($LISTSRT only)
-12 - Sort specification is too complex
$LISTSRT/$LISTSORT Error Codes
All invocations of a particular call to $LISTSORT or $LISTSRT will always return the
same $list identifier. Each time a call is executed, if the function is successful then any
previous $list created by that call is deleted, and a new list is created. For example :
REPEAT 4 TIMES
%A = $LISTSORT(%LIST,'1,24,D 39,255,A')
END REPEAT
Would produce only one valid $list. On the other hand ...
would produce two $lists, though the identifier of the first $list would have been replaced
in %A by the identifier of the second $list.
Following is an example of using an image item name in a sort criterion.
IMAGE SURGERY
PROCEDURE
DEPT
CODE
COST
END IMAGE
IS
IS
IS
IS
STRING LEN 16
STRING LEN 5
STRING LEN 6
BINARY
PREPARE IMAGE SURGERY
%LIST = $LISTNEW
%RC = $LISTIMG(%LIST, %SURGERY:CODE)
.
.
.
.
.
.
.
%OUTLIST = $LISTSORT(%LIST, 'DEPT,A COST,D')
——————————————————————————————————————————
258
——————————————————————————————————————————
——————————————————————————————————————————
Notes:
●
If the input $list was created by the invoked $LISTSORT or $LISTSRT function, the
input $list is not deleted if you get a -3 error code from LISTSORT or $LISTSRT.
●
If you are sorting 2-digit year dates, you can use a CENTSPAN of 1975 to sort the
dates by appending the letter C to the third item (A or D) in the sort field
specification. This could be used, for example, with output of $PRCLEX, based on
the assumption that all procedures were created since 1974. However, a better
approach is to use $PROC_LIST, which returns 4-digit year dates.
●
$LISTSRT and $LISTSORT use any specified image item's format for comparison.
For example, if the image item WEIGHT is specified as part of the sort criteria and
WEIGHT is defined as a FLOAT type image item, a floating point comparison of the
values will be performed. Type specific comparison is done for FLOAT, BINARY,
PACKED, and ZONED image items. Generally, the type specific comparisons
produce the same results as a character comparison unless the some of the values
are negative.
●
$LISTSRT's and $LISTSORT's output $list identifiers are associated with the same
image as their input $lists (as associated with $LISTIMG).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTSORT and $LISTSRT
——————————————————————————————————————————
259
——————————————————————————————————————————
——————————————————————————————————————————
7.117
$LISTSUB: Create $list that is subset of input
$list
This function creates a $list that is a subset of an input $list. The subset is created by
selecting all entries that contain a specified search string.
The $LISTSUB function accepts five arguments and returns a numeric result.
The first argument is the identifier of the $list for which a subset is to be built. This is a
required argument.
The second argument is the string to be located. This argument is called the search
string. If this argument is not specified, all $list items are considered to contain the
search string. The subset $list consists of all items in the source list that contain the
search string in the specified columns.
The third argument is the starting column number of a range of columns in which the
search string must be located or a string containing the name of an image item in the
image associated with the $list using $LISTIMG (“$LISTIMG: Associate an image with a
$list” on page 203). In the latter case, the start column for the search is the position of
the image item in the image. This is an optional argument and defaults to 1.
The fourth argument is the ending column number of a range of columns in which the
search string must be located. This is an optional argument and defaults to one of the
following values:
●
●
if the third argument specifies an image item name, the position of the end of the
image item in the image
otherwise, 6124 for Sirius Mods version 6.2 and later, and 4096 before.
If the fifth argument is a non-zero integer, then the width of the column range is reduced
to a maximum of 256.
The fifth argument is an indicator for case-insensitive comparisons. If this argument is a
non-zero integer, the string comparisons use $list item data translated to uppercase
(hence your search string should be passed as an uppercase value). This is an optional
argument and defaults to zero. If the fifth argument is 1, then the width of the column
range is reduced to a maximum of 256.
%RESULT = $LISTSUB(list_id, search_string, start_col,
end_col, case_ignore)
-
$LISTSUB Function
%RESULT is set either to the identifier of the newly created subset $list, or to a
negative number if an error has occurred.
——————————————————————————————————————————
260
——————————————————————————————————————————
$LISTSUB: Create $list that is subset of input $list
——————————————————————————————————————————
All invocations of a particular call to $LISTSUB will always return the same $list
$list created by that call is deleted, and a new list is created. For example :
REPEAT 4 TIMES
%A = $LISTSUB(%LIST,'SUBSET-DATA',20,50)
END REPEAT
Would produce only one valid $list. On the other hand ...
would produce two $lists, though the identifier of the first $list would have been replaced
in %A by the identifier of the second $list.
Note that if the input $list was created by the invoked $LISTSUB function, the input $list
is not deleted if you get a -3 or -8 error code from $LISTSUB.
-3
-5
-6
-8
-9
-
No room in CCATEMP
String not found
$LISTSUB Error Codes
In the following example, a $list is loaded from the contents of an image and a subset list
is created of all items that had been loaded with a specific value in the source image.
IMAGE PART
ITEMNO
NAME
COST
END IMAGE
IS STRING LEN 6
IS STRING LEN 30
IS BINARY
PREPARE IMAGE PART
%LIST = $LISTNEW
%RC = $LISTIMG(%LIST, %PART:NAME)
.
.
.
.
.
FOR EACH RECORD IN PARTS
.
.
.
.
.
.
.
.
.
.
END FOR
%LIST2 = $LISTSUB(%LIST, 'LUG NUT', 'NAME')
——————————————————————————————————————————
261
——————————————————————————————————————————
——————————————————————————————————————————
$LISTSUB's output $list identifier is associated with the same image as the input $list (as
associated with $LISTIMG).
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LISTSUB
——————————————————————————————————————————
262
——————————————————————————————————————————
$LISTUPD: Produce $list from input $list using $list of updates
——————————————————————————————————————————
7.118
$LISTUPD: Produce $list from input $list using
$list of updates
This function uses a first $list to update a second $list, producing a third $list containing
data from the second $list as modified by the first $list.
The $LISTUPD function accepts three arguments and returns a numeric result. It is a
The first argument is the identifier of a $list containing data with 8 byte sequence
The second argument is the identifier of a $list containing update control statements and
insertion or replacement lines. This is a required argument.
The third argument is the identifier of the output $list. This is a required argument.
[%RESULT =]
$LISTUPD(list_id1, list_id2, list_id3)
$LISTUPD Function
%RESULT is set either to the number of items in the output $list, or to a
negative error code if an error has occurred.
The output $list produced by $LISTUPD contains sequence numbers just as input $list 1.
This makes it possible to use the output $list as input to another $LISTUPD call. In this
way it is possible to apply multiple updates to a single $list.
The first input $list to $LISTUPD can be most easily created with the $PROCDAT
function using the fifth parameter to indicate a sequence number. The second input $list
to $LISTUPD can be most easily created with the $LISTCMP function.
-8 - Input $list 1 has invalid format
$LISTUPD Error Codes
The update $list (input $list 2) contains update control statements and insertion or
replacement lines. The update $list must begin with an update control statement. All
update control statements begin with the './ ' characters followed by a single character
indicating the function and possible sequence numbers indicating the lines in input $list
to which the updates apply. Any items in input $list 1 not updated by the update $list are
simply copied into the output $list. The update control statements are:
——————————————————————————————————————————
263
——————————————————————————————————————————
——————————————————————————————————————————
./ * comment
This is a comment control statement and is ignored. This statement must be
followed by another update control statement or it must be the last item in
the update $list.
./ D seq1 { seq2 } { $ }
This is a deletion control statement indicating a range of input lines to be
deleted. seq1 and seq2 indicate the range of sequence numbers in the
input $list that are to be deleted. If seq2 is not specified, it is assumed to
equal seq1, that is only the single line indicated by seq1 will be deleted.
This statement must be followed by another update control statement or it
must be the last item in the update $list.
./ I seq1 { $ seq2 { seq3 } }
This is an insertion control statement and is followed by lines that are to be
inserted in the output $list. seq1 indicates the sequence number in the input
$list after which the lines are to be inserted. seq2 is the sequence number
to be assigned to the first inserted line and seq3 indicates the increment to
be added to the current sequence number for subsequent inserted lines.
The lines to be inserted are terminated by another update control statement.
./ R seq1 {seq2} { $ seq3 { seq4 } }
This is a replacement control statement and is followed by lines that are to
replace lines from the input $list in the output $list. seq1 and seq2 indicate
the range of sequence numbers in the input $list that are to be replaced. If
seq2 is not specified, it is assumed to equal seq1, that is, only the single line
indicated by seq1 will be replaced. seq3 is the sequence number to be
assigned to the first replacement line and seq4 indicates the increment to be
added to the current sequence number for subsequent replacement lines.
The replacement lines are terminated by another update control statement.
./ S seq1 { seq2 } { $ }
This is an resequence control statement and must be the first non-comment
control statement in the update $list. This statement indicates that the
output $list, after all subsequent updates have been applied, is to be given
sequence numbers starting at seq1 and incremented by seq2.
●
SirLib
Products authorizing $LISTUPD
——————————————————————————————————————————
264
——————————————————————————————————————————
$LSTR: Treat a string as longstring
——————————————————————————————————————————
7.119
$LSTR: Treat a string as longstring
This function takes a string or longstring input and produces a longstring output.
The $LSTR function accepts one argument and returns a longstring result.
The first argument is an arbitrary string or longstring.
%STR = $LSTR(longstring)
$LSTR Function
%STR is a copy of longstring.
The main utility of the $LSTR function is to force a STRING WITH expression that is its
argument to be upgraded to a LONGSTRING WITH expression. For example,
IF %COMEDIANS EQ (%WHO WITH ' Costello')
would truncate (%WHO WITH 'Costello') at 255 bytes before the comparison even if
%COMEDIANS is a LONGSTRING %variable but
IF %COMEDIANS EQ $LSTR(%WHO WITH ' Costello')
would not.
For more information see “Longstrings” on page 11.
$LSTR is only available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR
——————————————————————————————————————————
265
——————————————————————————————————————————
——————————————————————————————————————————
7.120
$LSTR_ADD_USERBUFFER: Add longstring to
user buffer
This callable function, new in Sirius Mods version 6.7, appends the value of its longstring
argument to the contents of the current user buffer. Such a user buffer is a Universal
Buffer or an MQ/204 user buffer, both of which, as of Model 204 V6R1.0, may transfer
Large Object (LOB) data. For versions of Model 204 prior to 6.1, this $function applies
only to the MQ user buffer and requires the MQ/204 feature.
The $LSTR_ADD_USERBUFFER function accepts one argument and returns a numeric
result: the new length of the user buffer contents.
The argument is an arbitrary string or longstring.
[%LEN =]
$LSTR_ADD_USERBUFFER(longstring)
$LSTR_ADD_USERBUFFER Function
%LEN is the resultant length of the user buffer data in bytes, or it is -1 to
indicate an error.
The Universal Buffer is a one-per-user, temporary storage area that, like the MQ buffer,
automatically expands to accommodate its data contents. Unlike prior versions, the MQ
buffer in Model 204 6.1 also becomes a one-per-user buffer.
If the buffer has to be expanded to accommodate the longstring, its length is increased
in increments of 4096 bytes (one page). Any errors during the transfer of the longstring
result in request cancellation.
Data insertions into or deletions from the buffer are not allowed in Model 204 6.1.
Additional functions specifically for working with Large Object data are:
●
●
“$LSTR_GET_USERBUFFER” on page 272
“$LSTR_SET_USERBUFFER” on page 292
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_ADD_USERBUFFER
——————————————————————————————————————————
266
——————————————————————————————————————————
$LSTR_BASE64_DECODE: Convert from base 64 to byte string
——————————————————————————————————————————
7.121
$LSTR_BASE64_DECODE: Convert from base 64
to byte string
This function converts from a base 64 encoded string to the decoded byte string. It is
identical to $BASE64_DECODE (“$BASE64_ENCODE: Convert byte string to base 64”
on page 45), except it is longstring capable.
The $LSTR_BASE64_DECODE function accepts one argument and returns a string
result whose base 64 encoding is that argument.
The first argument is a longstring which is a base 64 encoding.
The returned value is the base 64 decoding of the argument string. If the argument is
not a valid base 64 encoding, the null string is returned.
%DECODED = $LSTR_BASE64_DECODE(string)
$LSTR_BASE64_DECODE Function
%DECODED is set to the base 64 decoding of string.
For example, given the following argument of length 4:
%JUNK = $LSTR_BASE64_DECODE('ABCD')
%JUNK is set to the byte string (of length 3) represented in hexadecimal as X'001083'.
You can check for an invalid base 64 encoding by checking for the null string return
value from $LSTR_BASE64_DECODE. Of course, if it is possible that the argument is
null, the null string is a valid returned value. If you need to check for errors, and the null
string is a possible argument value, you can use an approach such as the following:
%STR = $LSTR_BASE64_DECODE(%IN)
IF %STR EQ ''
IF %IN NE '' THEN
error code ...
END IF
END IF
$LSTR_BASE64_ENCODE (“$LSTR_BASE64_ENCODE: Convert byte string to base
64” on page 269) is the inverse of $LSTR_BASE64_DECODE.
——————————————————————————————————————————
267
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_BASE64_DECODE
——————————————————————————————————————————
268
——————————————————————————————————————————
$LSTR_BASE64_ENCODE: Convert byte string to base 64
——————————————————————————————————————————
7.122
$LSTR_BASE64_ENCODE: Convert byte string
to base 64
This function converts a byte string into its base 64 encoding. It is identical to
$BASE64_ENCODE (“$BASE64_DECODE: Convert from base 64 to byte string” on
page 43), except it is longstring capable.
The $LSTR_BASE64_ENCODE function accepts one argument and returns a string
result which is the base 64 encoding of that argument.
The first argument is a longstring.
The returned value is the base 64 encoding of the argument string.
%CODED = $LSTR_BASE64_ENCODE(string)
$LSTR_BASE64_ENCODE Function
%CODED is set to the base 64 encoding of string.
For example, given the following argument of length 3:
%JUNK = $LSTR_BASE64_ENCODE($X2C('001083'))
%JUNK is set to the byte string (of length 4) represented in character as 'ABCD'.
$LSTR_BASE64_DECODE (“$LSTR_BASE64_DECODE: Convert from base 64 to byte
string” on page 267) is the inverse of $LSTR_BASE64_ENCODE.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_BASE64_ENCODE
——————————————————————————————————————————
269
——————————————————————————————————————————
——————————————————————————————————————————
7.123
$LSTR_C2X: Convert byte string to hexadecimal
This function converts a byte string into its hexadecimal encoding. It is identical to $C2X
(see the Model 204 User Language Manual), except it is longstring capable.
The $LSTR_C2X function accepts one argument and returns a string result which is the
hexadecimal encoding of that argument.
The first argument is a longstring.
The returned value is the hexadecimal encoding of the argument string.
%CODED = $LSTR_C2X(string)
$LSTR_C2X Function
%CODED is set to the hexadecimal encoding of string.
For example, the following code
PRINT $LSTR_C2X('Red rum')
would print D985844099A494, which is the hexadecimal representation of the EBCDIC
characters “Red rum”.
$LSTR_X2C (“$LSTR_X2C: Convert from hexadecimal to byte string” on page 308) is
the inverse of $LSTR_C2X.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_C2X
——————————————————————————————————————————
270
——————————————————————————————————————————
$LSTR_GET_IMAGE and $LSTR_SET_IMAGE: Longstring to/from image
——————————————————————————————————————————
7.124
$LSTR_GET_IMAGE and $LSTR_SET_IMAGE:
Longstring to/from image
$LSTR_GET_IMAGE returns the contents of an image as a longstring.
$LSTR_SET_IMAGE sets the contents of an image from a longstring.
$LSTR_GET_IMAGE accepts one argument and returns a longstring result.
$LSTR_SET_IMAGE accepts two arguments and returns a numeric result.
The first argument to both $LSTR_GET_IMAGE and $LSTR_SET_IMAGE is a string
containing the name of the image to which the function applies. This is a required
argument.
The second argument to $LSTR_SET_IMAGE is the longstring from which the image
indicated by argument 1 is to be set.
%LSTR = $LSTR_GET_IMAGE(image)
$LSTR_GET_IMAGE Function
%LSTR is set to the contents of the image.
%RC = $LSTR_SET_IMAGE(image, value)
$LSTR_SET_IMAGE Function
%RC is set to the bytes set in the image.
$LSTR_GET_IMAGE and $LSTR_SET_IMAGE can be useful for maintaining multiple
copies of or versions of an image in a single request, for maintaining one or more global
copies of an image (using global LONGSTRINGs) without using the GTBL space
required by the standard GLOBAL IMAGE feature and for maintaining copies of an
image associated with a session that survives a logout (using session LONGSTRINGs).
$LSTR_GET_IMAGE and $LSTR_SET_IMAGE are new in version 6.3 of the Sirius
Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_GET_IMAGE and $LSTR_SET_IMAGE
——————————————————————————————————————————
271
——————————————————————————————————————————
——————————————————————————————————————————
7.125
$LSTR_GET_USERBUFFER: Get user buffer
contents to a longstring
This function, new in Sirius Mods version 6.7, retrieves into a longstring the contents of
the current user buffer. Such a user buffer is a Universal Buffer or an MQ/204 user
buffer, both of which, as of Model 204 V6R1.0, may transfer Large Object (LOB) data.
For versions of Model 204 prior to 6.1, this function applies only to the MQ user buffer
and requires the MQ/204 feature.
The $LSTR_GET_USERBUFFER function accepts no arguments and returns a
longstring result.
%LSTR = $LSTR_GET_USERBUFFER
$LSTR_GET_USERBUFFER Function
%LSTR is the longstring for the user buffer contents.
Any errors during the transfer of the buffer contents result in request cancellation.
●
●
“$LSTR_ADD_USERBUFFER” on page 266
“$LSTR_SET_USERBUFFER” on page 292
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_GET_USERBUFFER
——————————————————————————————————————————
272
——————————————————————————————————————————
$LSTR_GLOBAL and $LSTR_SESSION: Bind to global/session longstring
——————————————————————————————————————————
7.126
$LSTR_GLOBAL and $LSTR_SESSION: Bind to
global/session longstring
This function binds a longstring %variable to a global or session longstring. That is, the
longstring %variable assumes the value of the global or session longstring and any
changes to the longstring %variable are reflected in the global or session longstring.
The global or session longstring could be one that already existed because of a previous
$LSTR_GLOBAL, $LSTR_SESSION, $LSTR_GLOBAL_SET or $LSTR_SESSION_SET
call.
$LSTR_GLOBAL and $LSTR_SESSION accept three arguments and return a numeric
result.
%RC = $LSTR_GLOBAL(gname, lstr, options)
$LSTR_GLOBAL Function
%RC is set to 0 or, if CCATEMP is full, to -3.
%RC = $LSTR_SESSION(gname, lstr, options)
$LSTR_SESSION Function
●
The first argument is the name of the global or session longstring. This is an
optional argument and, if not specified, the longstring %variable is unbound from
whatever global or session longstring it's bound to, if any, and then set to null.
●
The second argument is a longstring %variable. It cannot be a complex subroutine
parameter. This is a required argument.
●
The third argument indicates the type of processing $LSTR_GLOBAL or
$LSTR_SESSION is to perform. Valid values of this optional argument are listed
below; the default is ANY.
ANY
If the global or session longstring already exists, it is referenced with
its current contents. If it does not exists, a new null global or session
longstring is created.
OLD
The global or session longstring must already exist, that is, it must
have been created with a previous $LSTR_GLOBAL,
$LSTR_SESSION, $LSTR_GLOBAL_SET, or
$LSTR_SESSION_SET call.
NEW
The global or session longstring must not already exist. The global
or session longstring will be created if this is the case.
PREP
Same as ANY but empties the longstring if it has data.
——————————————————————————————————————————
273
——————————————————————————————————————————
——————————————————————————————————————————
PREPANY
PREPOLD
Same as OLD but empties the longstring if it has data.
PREPNEW
Same as NEW.
ANYPREP
OLDPREP
Same as OLD but empties the longstring if it has data.
NEWPREP
Same as NEW.
$LSTR_GLOBAL and $LSTR_SESSION will automatically unbind a previous bind for its
input longstring %variable. In such a case, the value of the previously bound global or
session longstring is not affected.
Only one %variable in a request can be bound to the same global name. To access the
same global name in multiple complex subroutines, use a COMMON %variable in the
$LSTR_GLOBAL or $LSTR_SESSION call.
In the following example, the global longstring SUNSHINE is set to the value PARAKEET.
%RC
%LONG
= $LSTR_GLOBAL('SUNSHINE', %LONG)
= 'PARAKEET'
$LSTR_GLOBAL and $LSTR_SESSION have independent namespaces. That is, the
same name used for $LSTR_GLOBAL and $LSTR_SESSION references different
longstrings. A $LSTR_SESSION call when there is no session open causes a request
You can clean up any global longstrings with $LSTR_GLOBAL_DEL, which can be
issued whether or not a name was referenced in the current procedure with a
$LSTR_GLOBAL. You can clean up any session longstrings with
$LSTR_SESSION_DEL, which can be issued whether or not a name was referenced in
the current procedure with a $LSTR_GLOBAL.
$LSTR_GLOBAL and $LSTR_SESSION are new in version 6.3 of the Sirius Mods.
——————————————————————————————————————————
274
——————————————————————————————————————————
$LSTR_GLOBAL and $LSTR_SESSION: Bind to global/session longstring
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_GLOBAL and $LSTR_SESSION
——————————————————————————————————————————
275
——————————————————————————————————————————
——————————————————————————————————————————
7.127
$LSTR_GLOBAL_DEL and
$LSTR_SESSION_DEL
These functions delete one or more global or session longstrings that were created with
either $LSTR_GLOBAL_SET, $LSTR_SESSION_SET, $LSTR_GLOBAL, or
$LSTR_SESSION in the current or any previous User Language program. It returns the
number of deleted entries.
$LSTR_GLOBAL_DEL and $LSTR_SESSION_DEL accept one argument and return a
numeric result.
The argument is the name of the global or session longstring or longstrings to be
deleted. This argument can contain wildcard characters as described below. This is a
required argument and cannot be a null string.
%RC = $LSTR_GLOBAL_DEL(name)
$LSTR_GLOBAL_DEL Function
%RC is set to number of deleted global longstrings.
%RC = $LSTR_SESSION_DEL(name)
$LSTR_SESSION_DEL Function
%RC is set to the number of deleted session longstrings.
The name specified for $LSTR_GLOBAL_DEL or $LSTR_SESSION_DEL can be an
explicit name or it can contain the following wildcard characters:
*
?
"
character.
For example,
%RC = $LSTR_GLOBAL_DEL('TYRANNOSAURUS')
would only delete a global longstring named ‘TYRANNOSAURUS’.
%RC = $LSTR_GLOBAL_DEL('STEG*')
would delete globals longstrings named ‘STEG’, ‘STEGOSAURUS’ and ‘STEG.DATA’ if
they existed.
%RC = $LSTR_SESSION_DEL('ST??')
——————————————————————————————————————————
276
——————————————————————————————————————————
$LSTR_GLOBAL_DEL and $LSTR_SESSION_DEL
——————————————————————————————————————————
would delete session longstrings named ‘STAN’, ‘STEP’ and ‘STUN.DATA’ if they
existed.
%RC = $LSTR_GLOBAL_DEL('"**')
would delete globals longstrings named ‘*’, ‘*LOOK’ and ‘*ZAP.DATA’ if they existed.
%RC = $LSTR_SESSION_DEL('*')
would delete all session longstrings.
When a $LSTR_GLOBAL_DEL or $LSTR_SESSION_DEL is issued against a global or
session longstring that is bound to a longstring in the current request, the longstring is
unbound and its contents set to null. For example, after
%RC
= $LSTR_GLOBAL(%DINO, 'VELOCIRAPTOR')
%DINO = 'FLINTSTONES'
%RC
= $LSTR_GLOBAL_DEL('VEL*')
the longstring %DINO is set to null and is no longer bound to a global longstring.
$LSTR_GLOBAL_DEL does not distinguish among the manner in which a global
longstring was created; it will delete any longstring created with $LSTR_GLOBAL or
$LSTR_GLOBAL_SET. Similarly, $LSTR_SESSION_DEL will delete any session
longstring created either by $LSTR_SESSION or $LSTR_SESSION_SET.
A $LSTR_SESSION_DEL call when there is no session open causes a request
$LSTR_GLOBAL_DEL and $LSTR_SESSION_DEL are new in version 6.3 of the Sirius
Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_GLOBAL_DEL and $LSTR_SESSION_DEL
——————————————————————————————————————————
277
——————————————————————————————————————————
——————————————————————————————————————————
7.128
$LSTR_GLOBAL_GET and
$LSTR_SESSION_GET
This function retrieves the value of a global or session longstring. If the global or
session longstring has never been set it returns a null.
$LSTR_GLOBAL_GET and $LSTR_SESSION_GET accept one argument and returns a
string result.
The first argument is a string containing the name of the global or session longstring.
%LSTR = $LSTR_GLOBAL_GET(gname)
$LSTR_GLOBAL_GET Function
%LSTR is set to the value of the global longstring.
%LSTR = $LSTR_SESSION_GET(gname)
$LSTR_SESSION_GET Function
%LSTR is set to the value of the session longstring.
$LSTR_GLOBAL_GET and $LSTR_SESSION_GET are roughly analogous to the
$GETG function for longstrings. $LSTR_GLOBAL_GET and $LSTR_SESSION_GET
will return the current value of a global or session longstring whether or not that
longstring is bound in the current request via $LSTR_GLOBAL or $LSTR_SESSION.
However, if a global or session longstring value is to be retrieved and updated frequently
in a request it is generally better to bind that longstring to a %variable using
$LSTR_GLOBAL or $LSTR_SESSION. In the following example, the value of the global
longstring named “POLLY” is retrieved into the longstring %PARROT.
%PARROT = $LSTR_GLOBAL_GET('POLLY')
$LSTR_GLOBAL_GET and $LSTR_SESSION_GET have independent namespaces.
That is, the same name used for $LSTR_GLOBAL_GET and $LSTR_SESSION_GET
reference different longstrings. A $LSTR_SESSION_GET call when there is no session
open causes a request cancellation. For more information about sessions see
“Sessions” on page 25.
While the $LSTR_GLOBAL_GET and $LSTR_SESSION_GET are longstring capable
the global names themselves cannot be longer than 255 bytes. An attempt to use a
longer name results in a request cancellation truncation error.
You can clean up any global longstrings with $LSTR_GLOBAL_DEL and any session
longstrings with $LSTR_SESSION_DEL.
——————————————————————————————————————————
278
——————————————————————————————————————————
$LSTR_GLOBAL_GET and $LSTR_SESSION_GET
——————————————————————————————————————————
$LSTR_GLOBAL_GET and $LSTR_SESSION_GET are new in version 6.3 of the Sirius
Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_GLOBAL_GET and $LSTR_SESSION_GET
——————————————————————————————————————————
279
——————————————————————————————————————————
——————————————————————————————————————————
7.129
$LSTR_GLOBAL_SET and
$LSTR_SESSION_SET
This function sets the value of a global or session longstring. If the global or session
longstring has never been set or bound to a %variable it is created.
$LSTR_GLOBAL_SET and $LSTR_SESSION_SET accept two arguments and returns a
0 for success or a -3 if CCATEMP is full and the LISTFC parameter is not set.
The first argument is a string containing the name of the global or session longstring.
The second argument is a longstring containing the value to which to set the global or
session longstring. This is a required argument.
%RC = $LSTR_GLOBAL_SET(gname, value)
$LSTR_GLOBAL_SET Function
%RC = $LSTR_SESSION_SET(gname, value)
$LSTR_SESSION_SET Function
$LSTR_GLOBAL_SET and $LSTR_SESSION_SET are roughly analogous to the
$SETG function for longstrings. $LSTR_GLOBAL_SET and $LSTR_SESSION_SET will
set the current value of a global or session longstring whether or not that longstring is
bound in the current request via $LSTR_GLOBAL or $LSTR_SESSION. A longstring
%variable bound to the global or session longstring set by these functions immediately
reflects the new value of the global or session longstring. However, if a global or
session longstring value is to be retrieved and updated frequently in a request it is
generally better to bind that longstring to a %variable using $LSTR_GLOBAL or
$LSTR_SESSION. In the following example, the value of the global longstring named
“POLLY” is set to the value in longstring %CRACKER.
%RC = $LSTR_GLOBAL_SET('POLLY', %CRACKER)
$LSTR_GLOBAL_SET and $LSTR_SESSION_SET have independent namespaces.
That is, the same name used for $LSTR_GLOBAL_SET and $LSTR_SESSION_SET
reference different longstrings. A $LSTR_SESSION_SET call when there is no session
open causes a request cancellation. For more information about sessions see
“Sessions” on page 25.
While the $LSTR_GLOBAL_SET and $LSTR_SESSION_SET are longstring capable the
global names themselves cannot be longer than 255 bytes. An attempt to use a longer
name results in a request cancellation truncation error.
——————————————————————————————————————————
280
——————————————————————————————————————————
$LSTR_GLOBAL_SET and $LSTR_SESSION_SET
——————————————————————————————————————————
You can clean up any global longstrings with $LSTR_GLOBAL_DEL and any session
longstrings with $LSTR_SESSION_DEL.
$LSTR_GLOBAL_SET and $LSTR_SESSION_SET are new in version 6.3 of the Sirius
Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_GLOBAL_SET and $LSTR_SESSION_SET
——————————————————————————————————————————
281
——————————————————————————————————————————
——————————————————————————————————————————
7.130
$LSTR_INDEX: Find a string inside a longstring
This function takes two longstring inputs and produces the position of one input inside
the other.
The $LSTR_INDEX function accepts three arguments and returns a numeric result.
The first argument is an arbitrary longstring. This is a required argument.
The second argument is a longstring whose length, ironically, must be 255 bytes or less.
The third argument is a number indicating the position within the first string that a search
for a match is to being. This is an optional argument and defaults to 1 meaning the first
character.
%RESULT = $LSTR_INDEX(longstring, str, start)
$LSTR_INDEX function
%RESULT is the position in longstring of str, if there's a match after start, or is 0
if not.
$LSTR_INDEX acts very much like $INDEX except
●
It allows a start position other than 1 (argument 3).
●
It cancels the request if the string being searched for (argument 2) is longer than
255 bytes.
●
It can operate on LONGSTRING inputs.
For example
%X = $LSTR_INDEX('Beauxbatons', 'bat')
sets %X to 6 and
%X = $LSTR_INDEX('Dudley Dursley', 'ey', 8)
sets %X to 13.
$LSTR_INDEX is only available in Sirius Mods version 6.2 and later.
——————————————————————————————————————————
282
——————————————————————————————————————————
$LSTR_INDEX: Find a string inside a longstring
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_INDEX
——————————————————————————————————————————
283
——————————————————————————————————————————
——————————————————————————————————————————
7.131
$LSTR_LEFT: Leftmost characters of a
longstring
This function takes a string or longstring input and produces the leftmost characters of
the input, possibly padded to an indicated length.
The $LSTR_LEFT function accepts three arguments and returns a string result.
The first argument is an arbitrary string or longstring. This is a required argument.
The second argument is a number between 1 and 2**31-1 that indicates the result
length. This is a required argument.
The third argument is a string containing a single character to be used as the pad
character if the result length is longer than the string specified by argument one. This is
an optional argument and defaults to a blank.
%RESULT = $LSTR_LEFT(longstring, len, pad)
$LSTR_LEFT function
%RESULT is the leftmost characters of the input longstring, padded with the
pad character if necessary.
$LSTR_LEFT acts very much like $PADR except
●
The target length and pad character arguments are reversed.
●
It cancels the request if the result target is too short to hold the result.
●
It cancels the request if the pad character argument is longer than one byte.
●
●
It produces a LONGSTRING output.
For example
%BIG = $LSTR_LEFT('Voldemort', 3)
sets %BIG to “Vol” and
%BIG = $LSTR_LEFT('Snape', 300, '!')
sets %BIG to “Snape” followed by 295 exclamation marks.
——————————————————————————————————————————
284
——————————————————————————————————————————
$LSTR_LEFT: Leftmost characters of a longstring
——————————————————————————————————————————
$LSTR_LEFT is only available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_LEFT
——————————————————————————————————————————
285
——————————————————————————————————————————
——————————————————————————————————————————
7.132
$LSTR_LEN: Length of a longstring
This function takes a string or longstring input and produces a numeric output that is the
length of the input string or longstring.
The $LSTR_LEN function accepts one argument and returns a numeric result that is the
length of the first argument.
The first argument is an arbitrary string or longstring
%LEN = $LSTR_LEN(longstring)
$LSTR_LEN Function
%LEN is the length of longstring.
$LSTR_LEN can be used wherever $LEN is used but $LEN will cause request
cancellation for an input LONGSTRING of length greater than 255 bytes.
$LSTR_LEN is only available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_LEN
——————————————————————————————————————————
286
——————————————————————————————————————————
$LSTR_PARSE: Part of longstring preceding character in delimiter set
——————————————————————————————————————————
7.133
$LSTR_PARSE: Part of longstring preceding
character in delimiter set
This function returns part of a given string: the characters after a specified or implied
starting position and until a character in a delimiter set.
The $LSTR_PARSE function accepts three arguments and returns a string result that is
a part of the first input string.
The second argument is a string containing a set of delimiter characters.
The third argument is a starting position in the first argument string and has a default of
1.
%PIECE = $LSTR_PARSE(string, delims, start_pos)
$LSTR_PARSE Function
%PIECE is a piece of the first argument string.
For example, the following statement would set %JUNK to WASTE NOT:
%JUNK = $LSTR_PARSE('WASTE NOT(WANT|NOT', '(|')
The statement below would set %JUNK to WASTE NOT(WANT:
%JUNK = $LSTR_PARSE('WASTE NOT(WANT|NOT', '|')
The following statement would set %JUNK to E NOT(WANT:
%JUNK = $LSTR_PARSE('WASTE NOT(WANT|NOT', '|', 5)
$LSTR_PARSE returns the entire first argument longstring if none of the delimiter
characters are found.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_PARSE
——————————————————————————————————————————
287
——————————————————————————————————————————
——————————————————————————————————————————
7.134
$LSTR_PARSEX: Part of longstring following
character in delimiter set
This function returns the part(s) of a longstring that remain after removing the part of the
string that is delimited by a character in a delimiter set.
The $LSTR_PARSEX function accepts three arguments and returns a longstring result
that is a part of the first input long string.
1.
%PIECE = $LSTR_PARSEX(string, delims, start_pos)
$LSTR_PARSEX Function
For example, the following statement would set %JUNK to WANT|NOT:
%JUNK = $LSTR_PARSEX('WASTE NOT(WANT|NOT', '(|')
The statement below would set %JUNK to NOT:
%JUNK = $LSTR_PARSEX('WASTE NOT(WANT|NOT', '|')
The following statement would set %JUNK to WASTENOT:
%JUNK = $LSTR_PARSEX('WASTE NOT(WANT|NOT', '|', 6)
Note that this last result string is a concatenation of the characters that precede the
starting position character in the initial string and the characters that follow the delimiter
character. Also note that the characters that are not in this result string are exactly the
characters that $LSTR_PARSE (“$LSTR_PARSE: Part of longstring preceding
character in delimiter set” on page 287) would return for this same initial string.
$LSTR_PARSEX returns a null string if none of the delimiter characters are found.
——————————————————————————————————————————
288
——————————————————————————————————————————
$LSTR_PARSEX: Part of longstring following character in delimiter set
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_PARSEX
——————————————————————————————————————————
289
——————————————————————————————————————————
——————————————————————————————————————————
7.135
$LSTR_RIGHT: Rightmost characters of a
longstring
This function takes a string or longstring input and produces the rightmost characters of
the input, possibly padded to an indicated length.
The $LSTR_RIGHT function accepts three arguments and returns a string result.
The second argument is a number between 1 and 2**31-1 that indicates the result
length. This is a required argument.
The third argument is a string containing a single character to be used as the pad
%RESULT = $LSTR_RIGHT(longstring, len, pad)
$LSTR_RIGHT function
%RESULT is the rightmost characters of the input longstring, padded with the
pad character if necessary.
$LSTR_RIGHT acts very much like $PAD except
●
The target length and pad character arguments are reversed.
●
●
●
●
For example
%BIG = $LSTR_RIGHT('McGonagall', 3)
sets %BIG to “all” and
%BIG = $LSTR_RIGHT('Dumbledore', 300, '?')
sets %BIG to 290 question marks followed by “Dumbledore”.
——————————————————————————————————————————
290
——————————————————————————————————————————
$LSTR_RIGHT: Rightmost characters of a longstring
——————————————————————————————————————————
$LSTR_RIGHT is only available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_RIGHT
——————————————————————————————————————————
291
——————————————————————————————————————————
——————————————————————————————————————————
7.136
$LSTR_SET_USERBUFFER: Set user buffer to
longstring value
This callable function, new in Sirius Mods version 6.7, sets the contents of the current
user buffer to the longstring argument value. Such a user buffer is a Universal Buffer or
an MQ/204 user buffer, both of which, as of Model 204 V6R1.0, may transfer Large
Object (LOB) data. For versions of Model 204 prior to 6.1, this function applies only to
the MQ user buffer and requires the MQ/204 feature.
The $LSTR_SET_USERBUFFER function accepts one argument and returns a numeric
result: the length of the longstring argument.
[%LEN =]
$LSTR_SET_USERBUFFER(longstring)
$LSTR_SET_USERBUFFER Function
%LEN is the length in bytes of the user buffer contents, or it is -1 to indicate an
error.
The Universal Buffer is a one-per-user, temporary storage area that, like the MQ buffer,
automatically expands to accommodate its data contents. Unlike prior versions, the MQ
buffer in Model 204 6.1 also becomes a one-per-user buffer.
If the user buffer has to be expanded to accommodate the longstring, length is increased
in increments of 4096 bytes (one page).
Any errors during the transfer of the longstring result in request cancellation.
●
●
“$LSTR_ADD_USERBUFFER” on page 266
“$LSTR_GET_USERBUFFER” on page 272
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_SET_USERBUFFER
——————————————————————————————————————————
292
——————————————————————————————————————————
$LSTR_SUBSTR: Substring of a longstring
——————————————————————————————————————————
7.137
$LSTR_SUBSTR: Substring of a longstring
This function takes a string or longstring input and produces a substring of the input,
possibly padded to an indicated length.
The $LSTR_SUBSTR function accepts four arguments and returns a string result.
The second argument is a number between 1 and 2**31-1 that indicates the starting
character in the input string. This is a required argument.
The third argument is a number between 1 and 2**31-1 that indicates the length of the
result string. This is an optional argument and defaults to the number of characters in
the input string starting at the position indicated by the second argument.
The fourth argument is a string containing a single character to be used as the pad
%RESULT = $LSTR_SUBSTR(longstring, start, len, pad)
$LSTR_SUBSTR function
%RESULT is a substring of the input longstring, padded with the pad character
if necessary.
$LSTR_SUBSTR acts very much like $SUBSTR except
●
It pads the result to the length indicated by the third argument if the third argument
is specified.
●
It has a fourth pad character argument.
●
●
●
●
For example
%BIG = $LSTR_SUBSTR('Gryffindor', 5, 4)
sets %BIG to “find.” and
%BIG = $LSTR_SUBSTR('Slytherin', 8, 300, '*')
——————————————————————————————————————————
293
——————————————————————————————————————————
——————————————————————————————————————————
sets %BIG to “in” followed by 298 asterisks.
$LSTR_SUBSTR is only available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_SUBSTR
——————————————————————————————————————————
294
——————————————————————————————————————————
$LSTR_SUBWORD: Substring of a longstring using word counts
——————————————————————————————————————————
7.138
$LSTR_SUBWORD: Substring of a longstring
using word counts
This function takes a string or longstring input and produces a substring of the input
using word counts.
The $LSTR_SUBWORD function accepts four arguments and returns a long string
result.
The second argument is a number between 1 and 2**31-1 that indicates the starting
word number in the input string. This is a required argument.
The third argument is a number between 1 and 2**31-1 that indicates the length in words
of the result string. This is an optional argument and defaults to the number of words left
in the string.
The fourth argument is a string containing from 1 to 255 characters which are the
delimiters for the longstring. This is an optional argument and defaults to a blank.
Leading and trailing delimiters are removed from the resulting string, but all delimiters
within the boundaries of the result are preserved.
%RESULT = $LSTR_SUBWORD(longstring, start, words, delim)
$LSTR_SUBWORD function
%RESULT is a substring of the input longstring.
For example
%RES = $LSTR_SUBWORD('Once upon a time you dressed so fine',
3, 2)
sets %RES to “a time.” and
%RES = $LSTR_SUBWORD('Once upon a time you dressed so fine',
3, 2, ' n')
sets %RES to “upon a”
$LSTR_SUBWORD is only available in Sirius Mods version 6.5 and later.
——————————————————————————————————————————
295
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_SUBWORD
——————————————————————————————————————————
296
——————————————————————————————————————————
$LSTR_TRANSLATE: Translate longstring
——————————————————————————————————————————
7.139
This function takes a string or longstring input and replaces characters indicated by an
“input table” with corresponding characters in an “output table”.
The $LSTR_TRANSLATE function accepts four arguments and returns a string result.
The second argument is the output table; its length must be 256 or less. This is an
optional argument.
The third argument is the input table; its length must be 256 or less. This is an optional
argument.
The fourth argument is a string containing a single character to be used as the pad
character if the input table is longer than the output table. This is an optional argument
and defaults to a blank.
%RESULT = $LSTR_TRANSLATE(lstring, out_tbl, in_tbl, pad_char)
$LSTR_TRANSLATE function
%RESULT is a copy of the first argument, with selected characters replaced as
specified by the output and input tables.
——————————————————————————————————————————
297
——————————————————————————————————————————
——————————————————————————————————————————
The defaults of $LSTR_TRANSLATE are:
●
If only the first argument is present, the result is to translate all lowercase characters
(a-z) with their uppercase equivalents (A-Z); otherwise:
●
If the input table is omitted, its default is all 256 characters, in the order X'00', X'01',
... X'FF'.
●
The default output table is the null string.
●
If the output table is shorter than the input table, it is padded on the right with copies
of the pad character.
●
If a character is specified more than once in the input table, only the first occurrence
is used.
Carefully examine the examples below to understand the consequences of these
defaults; for example, note in the first example that if a pad character (argument four) is
specified but neither input nor output table is, then the default input table is all byte
values (X'00' - X'FF') and the default output table is the null string padded to the length
of the input table (256) with pad characters, resulting in a copy of the first argument with
every character replaced by the pad character.
Examples:
Pad char specified but no tables, input replaced by all pad chars:
PRINT $LSTR_TRANSLATE('pqrst', , , '?')
-> ?????
Pad char specified or not and null output table only, input replaced by all pad chars:
PRINT $X2C($LSTR_TRANSLATE('pqrst', ''))
-> 4040404040
Simple translation, input & output table args same length:
PRINT $LSTR_TRANSLATE('pqrstu', '+!', 'tq')
-> p!rs+u
Upcase:
PRINT $LSTR_TRANSLATE('pqrst')
-> PQRST
Except for the “upcase” case, note that an omitted output table is the same as a null
string output table, and that an omitted input table is the same as all 256 byte values, in
order (X'00'-X'FF').
——————————————————————————————————————————
298
——————————————————————————————————————————
——————————————————————————————————————————
Tables identical (even both null strings), input string unchanged:
PRINT $LSTR_TRANSLATE('pqrst', '', '')
-> pqrst
Input table longer, pad char appended to output table:
PRINT $LSTR_TRANSLATE('pqrstu', '+!', 'purt', '?')
-> +q?s?!
Same case, using default pad char (blank):
PRINT $LSTR_TRANSLATE('pqrst', '', 'qs')
-> p r t
Pad char or output table specified, default input table is X'000102...':
%S = $LSTR_TRANSLATE('pqr WITH $X2C(00)', 'xyz')
PRINT '/' %S '/' WITH $C2X(%S)
-> /
x/404040A7
Same case, using different 4th input char & output table:
%S = $LSTR_TRANSLATE('pqr WITH $X2C(40)', $PAD(, , 63) WITH 'xyz')
-> /
y/404040A8
Note previous cases differ from null string input table, which always causes input string
unchanged:
%S = $LSTR_TRANSLATE('pqr WITH $X2C(40)', $PAD(, , 63) WITH 'xyz', '')
-> /pqr /97989940
Using any disjoint set of n chars as arg 1 and 3 lets you re-order an n char arg 2:
PRINT $LSTR_TRANSLATE('312', 'pqr', '123')
-> rpq
- Omitted first argument:
- Either table longer than 256 bytes:
- Pad character not 1 byte long:
$LIST_TRANSLATE Error Conditions
$LSTR_TRANSLATE is only available in Sirius Mods version 6.5 and later.
——————————————————————————————————————————
299
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_TRANSLATE
——————————————————————————————————————————
300
——————————————————————————————————————————
$LSTR_UNBLANK: Remove extraneous blanks from longstring
——————————————————————————————————————————
7.140
$LSTR_UNBLANK: Remove extraneous blanks
from longstring
This function takes a string or longstring input and produces the a copy with leading
trailing and duplicate internal blanks (or other pad character) removed.
The $LSTR_UNBLANK function accepts two arguments and returns a string result.
The second argument is a string containing a single character that is treated as the
blank character. This is an optional argument and defaults to a blank.
%RESULT = $LSTR_UNBLANK(longstring, char)
$LSTR_UNBLANK function
%RESULT is a copy of longstring with leading, trailing, and extra intermediate
blank characters removed.
$LSTR_UNBLANK acts very much like $UNBLANK except
●
A character other than blank can be specified as the separator character (argument
2).
●
●
It can operate on a LONGSTRING input.
●
For example
%BIG = $LSTR_UNBLANK('
Rubeus
Hagrid ')
sets %BIG to “Rubeus Hagrid” and
%BIG = $LSTR_UNBLANK('!!Avada!!!!Kedavra!', '!')
sets %BIG to “Avada!Kedavra”.
$LSTR_UNBLANK is only available in Sirius Mods version 6.2 and later.
——————————————————————————————————————————
301
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_UNBLANK
——————————————————————————————————————————
302
——————————————————————————————————————————
$LSTR_WINDEX: Return the position of a word within a long string
——————————————————————————————————————————
7.141
$LSTR_WINDEX: Return the position of a word
within a long string
This function takes a string or longstring input and returns a number indicating the word
position of the second argument within the long string. If the word is not present, zero is
returned.
The $LSTR_WINDEX function accepts three arguments and returns a string result.
The second argument is an arbitrary string containing a single word. The word must
have no occurrences of any of the delimiters in argument three, and may not be null.
The third argument is a string containing from 1 to 255 characters which are the
%RESULT = $LSTR_WINDEX(longstring, word, delims)
$LSTR_WINDEX function
%RESULT is the position of word within longstring.
For example
%RES = $LSTR_WINDEX('She sells sea-shells by the sea shore',
'sea')
sets %RES to “6.” and
%RES = $LSTR_WINDEX('She sells sea-shells by the sea shore',
'sea', '- ')
sets %RES to “3”
$LSTR_WINDEX is only available in Sirius Mods version 6.5 and later.
——————————————————————————————————————————
303
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_WINDEX
——————————————————————————————————————————
304
——————————————————————————————————————————
$LSTR_WORD: Return a word from a long string
——————————————————————————————————————————
7.142
$LSTR_WORD: Return a word from a long string
This function takes a longstring input and a word number and returns a longstring
containing a single word. A null string is returned if the word count in the input longstring
is less than the word number.
The $LSTR_WORD function accepts three arguments and returns a longstring result.
The first argument is an arbitrary longstring. This is a required argument.
The second argument is the number of the desired word. The first word in the input
longstring is word 1.
The third argument is a string containing from 1 to 255 characters which are the
%RESULT = $LSTR_WORD(longstring, n, delims)
$LSTR_WORD function
%RESULT is the nth word in the longstring.
For example
%RES = $LSTR_WORD('She sells sea-shells by the sea shore', 7)
sets %RES to “shore.” and
%RES = $LSTR_WORD('She sells sea-shells by the sea shore', 7,
'- ')
sets %RES to “sea”
$LSTR_WORD is only available in Sirius Mods version 6.5 and later. Prior to version
7.3 (or version 7.1 or 7.2, with maintenance applied), if the result of $Lstr_Word was
longer than 255 bytes, either the request was cancelled or the result was truncated at
255 bytes.
——————————————————————————————————————————
305
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_WORD
——————————————————————————————————————————
306
——————————————————————————————————————————
$LSTR_WORDS: Return the number of words in a long string
——————————————————————————————————————————
7.143
$LSTR_WORDS: Return the number of words in
a long string
This function takes a string or longstring input and returns a number indicating the word
position of the second argument within the long string. If the word is not present, zero is
returned.
The $LSTR_WORDS function accepts two arguments and returns a string result.
The second argument is a string containing from 1 to 255 characters which are the
%RESULT = $LSTR_WORDS(longstring, delims)
$LSTR_WORDS function
%RESULT is the count of words in the longstring.
For example, the following statement sets %RES to 8.:
%RES = $LSTR_WORDS('Picture yourself in a boat on a river')
This statement sets %RES to 7:
%RES = $LSTR_WORDS('Picture yourself in a boat on a river', 'a ')
$LSTR_WORDS is only available in Sirius Mods version 6.5 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_WORDS
——————————————————————————————————————————
307
——————————————————————————————————————————
——————————————————————————————————————————
7.144
$LSTR_X2C: Convert from hexadecimal to byte
string
This function converts from a hexadecimal encoded string to the decoded byte string. It
is identical to $X2C (see the Model 204 User Language Manual), except it is longstring
capable.
The $LSTR_X2C function accepts one argument and returns a string result whose
hexadecimal encoding is that argument.
The first argument is a longstring which is a hexadecimal encoding.
The returned value is the hexadecimal decoding of the argument string. If the argument
is not a valid hexadecimal encoding, the null string is returned.
%DECODED = $LSTR_X2C(string)
$LSTR_X2C Function
%DECODED is set to the hexadecimal decoding of string.
For example, the following code
PRINT $LSTR_X2C('D985844099A494')
would print Red rum, which is the character representation of the EBCDIC characters
represented in hexadecimal as “D985844099A494”.
You can check for an invalid hexadecimal encoding by checking for the null string return
value from $LSTR_X2C. Of course, if it is possible that the argument is null, the null
string is a valid returned value. If you need to check for errors, and the null string is a
possible argument value, you can use an approach such as the following:
%STR = $LSTR_X2C(%IN)
IF %STR EQ ''
IF %IN NE '' THEN
error code ...
END IF
END IF
$LSTR_C2X (“$LSTR_C2X: Convert byte string to hexadecimal” on page 270) is the
inverse of $LSTR_X2C.
——————————————————————————————————————————
308
——————————————————————————————————————————
$LSTR_X2C: Convert from hexadecimal to byte string
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $LSTR_X2C
——————————————————————————————————————————
309
——————————————————————————————————————————
——————————————————————————————————————————
7.145
$PARSE: Part of string preceding character in
delimiter set
This function returns part of a given string: the characters after a specified or implied
starting position and until a character in a delimiter set.
The $PARSE function accepts three arguments and returns a string result that is a part
of the first input string.
1.
%PIECE = $PARSE(string, delims, start_pos)
$PARSE Function
For example, the following statement would set %JUNK to WASTE NOT:
%JUNK = $PARSE('WASTE NOT(WANT|NOT', '(|')
The statement below would set %JUNK to WASTE NOT(WANT:
%JUNK = $PARSE('WASTE NOT(WANT|NOT', '|')
The following statement would set %JUNK to E NOT(WANT:
%JUNK = $PARSE('WASTE NOT(WANT|NOT', '|', 5)
$PARSE returns the entire first argument string if none of the delimiter characters are
found.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $PARSE
——————————————————————————————————————————
310
——————————————————————————————————————————
$PARSEX: Part of string following character in delimiter set
——————————————————————————————————————————
7.146
$PARSEX: Part of string following character in
delimiter set
This function returns the part(s) of a string that remain after removing the part of the
string that is delimited by a character in a delimiter set.
The $PARSEX function accepts three arguments and returns a string result that is a part
of the first input string.
1.
%PIECE = $PARSEX(string, delims, start_pos)
$PARSEX Function
For example, the following statement would set %JUNK to WANT|NOT:
%JUNK = $PARSEX('WASTE NOT(WANT|NOT', '(|')
The statement below would set %JUNK to NOT:
%JUNK = $PARSEX('WASTE NOT(WANT|NOT', '|')
The following statement would set %JUNK to WASTENOT:
%JUNK = $PARSEX('WASTE NOT(WANT|NOT', '|', 6)
Note that this last result string is a concatenation of the characters that precede the
starting position character in the initial string and the characters that follow the delimiter
character. Also note that the characters that are not in this result string are exactly the
characters that $PARSE (“$PARSE: Part of string preceding character in delimiter set”
on page 310) would return for this same initial string.
$PARSEX returns a null string if none of the delimiter characters are found, unless the
second argument is the null string (the default), in which case $PARSEX returns the
entire first argument string.
——————————————————————————————————————————
311
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $PARSEX
——————————————————————————————————————————
312
——————————————————————————————————————————
$PRCLEX: $list of information about procedures in file
——————————————————————————————————————————
7.147
$PRCLEX: $list of information about procedures
in file
This function returns information about procedures in a procedure file or group into a
$list.
Also see $PRCLEXG, which gets a list of procedures in a group, and $PROC_LIST and
$PROC_LISTG, which return the date of last update with a 4-digit year.
The $PRCLEX function accepts four arguments and returns a numeric result.
The first argument is the file or group name for which information is to be returned. This
is an optional argument and defaults to the default file/group at compile time.
The second argument is the procedure name that is to be selected. The procedure
name may contain '*' characters to indicate wildcard matches. This is an optional
parameter and defaults to all procedures.
The third argument is the account id of the last modifying user for the procedures to be
selected. The account id may contain '*' characters to indicate wildcard matches. This
is an optional parameter and defaults to all account ids.
The fourth argument is a string indicating the last modification date for the procedures to
be selected. If specified, this parameter must be 6 bytes long and begin with either a '=',
'<' or '>' character to indicate whether the date should be equal to, less than or greater
than the following Julian date which is the last 5 characters. '>89200', for example,
selects procedures last modified after day 200 of 1989. This is an optional parameter
and defaults to all modification dates. Note that this 2-digit year date is interpreted with
a CENTSPAN of 1975, so that values between 00000 and 74365 are considered to be in
the years 2000-2074.
%RESULT = $PRCLEX(file, pname, account, date)
$PRCLEX Function
%RESULT is a either a $list identifier or a negative error code.
All invocations of a particular call to $PRCLEX will always return the same $list identifier.
Each time that call is executed, if the function is successful then any previous $list
created by that call is deleted, and a new list is created.
The output $list produced by $PRCLEX has the following format :
Col 1-10
Account id of last updater.
Col 12-19
Size of procedure in bytes.
Col 21-28
Date of last update (YY/MM/DD).
——————————————————————————————————————————
313
——————————————————————————————————————————
——————————————————————————————————————————
Col 30-37
Time of last update (BH:MI:SS).
Col 39-
Procedure name
-1 - File/group not found
-2 - No procedures match search criteria
-4 - Invalid selection criterion
$PRCLEX Error Codes
The following program displays information for all procedures in file 'HOMER' beginning
with the letter 'S' last updated by a user whose account id begins with the letter 'A'.
B
%LIST = $PRCLEX('HOMER', 'S*', 'A*')
END FOR
END
●
●
●
Sirius Functions
SirPro
Janus Web Server
Products authorizing $PRCLEX
——————————————————————————————————————————
314
——————————————————————————————————————————
$PRCLEXG: $list of information about procedures in group or file
——————————————————————————————————————————
7.148
$PRCLEXG: $list of information about
procedures in group or file
$list. This function is virtually identical to $PRCLEX. The main difference between
$PRCLEX and $PRCLEXG is that $PRCLEXG returns the name of the file containing
the procedure. This is useful if $PRCLEXG is invoked against a procedure group.
Also see $PROC_LISTG and $PROC_LIST, which return the date of last update with a
4-digit year.
The $PRCLEXG function accepts four arguments and returns a numeric result.
%RESULT = $PRCLEXG(file, pname, account, date)
$PRCLEXG Function
All invocations of a particular call to $PRCLEXG will always return the same $list
The output $list produced by $PRCLEXG has the following format :
Col 1-10
Col 12-19
——————————————————————————————————————————
315
——————————————————————————————————————————
——————————————————————————————————————————
Col 21-28
Date of last update (YY/MM/DD).
Col 30-37
Col 39-46
File containing proc.
Col 47-
Procedure name
$PRCLEXG Error Codes
The following program displays information for all procedures in group 'HOMER'
beginning with the letter 'S' last updated by a user whose account id begins with the
letter 'A'.
B
%LIST = $PRCLEXG('HOMER', 'S*', 'A*')
END FOR
END
●
●
●
Sirius Functions
SirPro
Janus Web Server
Products authorizing $PRCLEXG
——————————————————————————————————————————
316
——————————————————————————————————————————
$PRIORTY: Change a user's priority
——————————————————————————————————————————
7.149
$PRIORTY: Change a user's priority
The $PRIORTY function allows a privileged user (system manager or system
administrator) to change another user's priority.
Note: As of Sirius Mods version 7.3, you can open access to $PRIORTY beyond
system managers or system administrators by specifying the FUNCOPTS system
parameter X'40' or X'20' bit settings, as described in the Sirius Mods Command and
Parameter Reference Manual.
The $PRIORTY function accepts four arguments and returns a numeric code.
The first argument is the number of the user whose priority is to be changed.
The second argument is an optional userid. If this argument is provided, the user
number indicated by argument one will only have its priority changed if the userid
matches the second argument. This prevents accidentally changing the priority of a user
that just logged onto a thread previously occupied by another user.
The third argument is a number indicating the user's new minimum priority. This is a
required argument and must be between 0 and 111.
The fourth argument is a number indicating the user's new maximum priority. This is an
optional argument and must be between the minimum priority (argument 3) plus 16 and
127. The default for this argument is the minimum priority plus 47.
%RESULT = $PRIORTY ( user_num, userid, min, max)
$PRIORTY Function
0
1
2
3
-
Priority changed
User not found
Not privileged to issue PRIORITY command
Invalid priority specified
$PRIORTY return codes
$PRIORTY gives you more flexibility in the priorities you can assign to a user than does
the PRIORITY command. The valid priorities with the PRIORITY command and their
corresponding minimum and maximum priority values are
●
LOW - 0 and 47
●
STANDARD - 32 and 79
●
HIGH - 80 and 127
——————————————————————————————————————————
317
——————————————————————————————————————————
——————————————————————————————————————————
The current priority of a user whose priority is reset via $PRIORTY is set to
( ( 2 * min_priority ) + max_priority ) / 3
The following program sets user 0 to low priority.
B
%RC = $PRIORTY( 0, , 0)
END
●
Sirius Functions
Products authorizing $PRIORTY
——————————————————————————————————————————
318
——————————————————————————————————————————
$PROC_LIST: $list of information about procedures in file
——————————————————————————————————————————
7.150
$PROC_LIST: $list of information about
procedures in file
$list.
Also see $PROC_LISTG, which gets a list of procedures in a group, and $PRCLEX and
$PRCLEXG, which return the date of last update with a 2-digit year.
The $PROC_LIST function accepts four arguments and returns a numeric result.
%RESULT = $PROC_LIST(file, pname, account, date)
$PROC_LIST Function
All invocations of a particular call to $PROC_LIST will always return the same $list
The output $list produced by $PROC_LIST has the following format :
Col 1-10
Col 12-19
Col 21-30
Date of last update (YYYY/MM/DD).
——————————————————————————————————————————
319
——————————————————————————————————————————
——————————————————————————————————————————
Col 32-39
Col 41-
Procedure name
$PROC_LIST Error Codes
The following program displays information for all procedures in file 'HOMER' beginning
with the letter 'S' last updated by a user whose account id begins with the letter 'A'.
B
%LIST = $PROC_LIST('HOMER', 'S*', 'A*')
END FOR
END
●
●
●
Sirius Functions
SirPro
Janus Web Server
Products authorizing $PROC_LIST
——————————————————————————————————————————
320
——————————————————————————————————————————
$PROC_LISTG: $list of information about procedures in group or file
——————————————————————————————————————————
7.151
$PROC_LISTG: $list of information about
procedures in group or file
$list. This function is virtually identical to $PROC_LIST. The main difference between
$PROC_LIST and $PROC_LISTG is that $PROC_LISTG returns the name of the file
containing the procedure. This is useful if $PROC_LISTG is invoked against a
procedure group.
Also see $PRCLEXG, which returns the date of last update with a 4-digit year.
The $PROC_LISTG function accepts four arguments and returns a numeric result.
%RESULT = $PROC_LISTG(file, pname, account, date)
$PROC_LISTG Function
All invocations of a particular call to $PROC_LISTG will always return the same $list
The output $list produced by $PROC_LISTG has the following format :
Col 1-10
Col 12-19
——————————————————————————————————————————
321
——————————————————————————————————————————
——————————————————————————————————————————
Col 21-30
Date of last update (YYYY/MM/DD).
Col 32-39
Col 41-48
File containing proc.
Col 49-
Procedure name
$PROC_LISTG Error Codes
The following program displays information for all procedures in group 'HOMER'
beginning with the letter 'S' last updated by a user whose account id begins with the
letter 'A'.
B
%LIST = $PROC_LISTG('HOMER', 'S*', 'A*')
END FOR
END
●
●
●
Sirius Functions
SirPro
Janus Web Server
Products authorizing $PROC_LISTG
——————————————————————————————————————————
322
——————————————————————————————————————————
$PROC_TOUCH: Change a procedure's last-update date and user
——————————————————————————————————————————
7.152
$PROC_TOUCH: Change a procedure's
last-update date and user
$PROC_TOUCH lets you change the last updating date/time, account ID, or both, of a
Model 204 procedure.
Introduced in Sirius Mods version 6.7, $PROC_TOUCH is a callable function (“CALLing
Sirius Mods functions” on page 32) that accepts four string arguments and returns a
numeric completion code.
[%RESULT =] $PROC_TOUCH (filename, procname, datetime, id)
$PROC_TOUCH Function
%RESULT is an integer that indicates the success of the function.
where
filename
Name of file containing the procedure. If this argument is null, blank, or not
specified, the current default file name is used. The file must be open.
procname
Name of the procedure to be “touched,” that is, whose last-updating
information is to be modified.
datetime
Date/time specification in either of the following formats: YYDDDHHMISSXX
or YYYYDDDHHMISSXX. If YY is used, CENTSPAN is 1975. This argument
may be a date and time in the future. If this argument is null or omitted, the
current date and time is used.
For more information about the CENTSPAN mechanism, see
“CENTSPAN” on page 534.
id
Account ID (ten-character maximum) to become the last updator. If id is
not supplied, is null, or is blank, the ID of the $PROC_TOUCH caller is
used.
Note: This need not be the name of a valid user (this value is not
validated, and it may include embedded blanks).
Besides its use internally by SirLib to set more meaningful date/time stamps,
$PROC_TOUCH is also useful for correcting the results of Model 204 COPY PROC
commands (when the old date/time is lost because OLDDATE was not specified).
Note: These restrictions apply to a $PROC_TOUCH operation:
●
●
It must not be issued in the middle of another updating transaction.
It is not part of an update unit and cannot be backed out.
——————————————————————————————————————————
323
——————————————————————————————————————————
——————————————————————————————————————————
●
No roll-forward information is logged (or processed), so the effect of a
$PROC_TOUCH could get lost if recovery is run.
In the following example, procedure COMP in file TESTPROC, last updated by user
JACK, is “touched” to acquire an older date and user JACK3 as the last updating date
and user:
Begin
%RC is float
OPEN FILE TESTPROC
%RC = $PROC_TOUCH('TESTPROC', 'COMP', '200436411111111',
'JACK3')
Print 'TOUCH return code is: ' %RC
End
After this request finishes, the result of a DISPLAY PROC LIST command shows the
modified date of the request and user JACK3 for the last update for procedure COMP:
COMP
0
1
2
3
4
5
6
7
-
12/29/04 11:11:11
136 JACK3
Success
Procedure is in use
Procedure does not exist or is secured
Procedure name missing
File name invalid
No update privileges in file
Invalid touch time
Invalid account ID
$PROC_TOUCH Error Codes
●
SirLib
Products authorizing $PROC_TOUCH
——————————————————————————————————————————
324
——————————————————————————————————————————
$PROCCLS: Close procedure before reaching end
——————————————————————————————————————————
7.153
$PROCCLS: Close procedure before reaching
end
The $PROCCLS function may be used to "close" a procedure before reaching its end.
The $PROCCLS function accepts no arguments and returns a numeric result. As of
Sirius Mods version 6.8, it is a callable $function (“CALLing Sirius Mods functions” on
page 32).
%RESULT = $PROCCLS
$PROCCLS Function
%RESULT is set to indicate the results of the function.
If $PROCCLS is called before the current procedure has been completely processed,
the current procedure is closed and the next $PROCGET, $PROCDAT, or $PROCLOC
call operates on the previous procedure, if any. $PROCCLS will not close an input
stream that was not open via $PROCOPN.
The following instructions close all procedure input streams opened by $PROCOPN.
REPEAT UNTIL %RESULT <= 0
%RESULT = $PROCCLS
END REPEAT
-1 - Current include level not opened by $PROCOPN
0 - Include level closed, no more $PROCOPN levels left
N - Include level close, N $PROCOPN levels left
$PROCCLS Result Codes
●
●
●
Sirius Functions
Janus Web Server
Products authorizing $PROCCLS
——————————————————————————————————————————
325
——————————————————————————————————————————
——————————————————————————————————————————
7.154
$PROCDAT: Add lines from procedure to $list
The $PROCDAT function accepts three arguments, and returns a numeric code.
The first argument identifies the $list to which lines from the currently open procedure
will be added as $list items. This is a required argument.
The second argument is an optional number of lines to be read. If the second argument
is not provided, reading continues from the input procedure to the end of the procedure.
The third argument specifies a sequence number increment for 8 byte sequence
numbers to be placed in front of each line in the output $list. This sequence number
indicates both the starting sequence number and the sequence number increment. If
this parameter is not provided, no sequence numbers are placed in front of the input
lines.
%RESULT = $PROCDAT ( list_identifier, num_lines, seq_inc )
$PROCDAT Function
The third argument to $PROCDAT is intended for use in conjunction with the $LISTUPD
and $LISTCMP functions.
If procedure 'SUTPENS_HUNDRED' in file 'JACKSON' contains:
B
FOR %I FROM 1 TO 10
PRINT %I
END FOR
END
This program:
B
%LIST = $LISTNEW
%RESULT = $PROCOPN('SUTPENS_HUNDRED', 'JACKSON')
%RESULT = $PROCDAT(%LIST, ,5000)
END FOR
END
——————————————————————————————————————————
326
——————————————————————————————————————————
$PROCDAT: Add lines from procedure to $list
——————————————————————————————————————————
Prints the following:
00005000B
00010000FOR %I FROM 1 TO 10
00015000 PRINT %I
00020000END FOR
00025000END
-5 - Required parameter missing
$PROCDAT return codes
●
●
●
Sirius Functions
Janus Web Server
Products authorizing $PROCDAT
——————————————————————————————————————————
327
——————————————————————————————————————————
——————————————————————————————————————————
7.155
$PROCGET: Next line of procedure
$PROCGET accepts no arguments and returns a string result. Each call to $PROCGET
returns either the next line of the current procedure or a null string to signify the end of
the current procedure.
$PROCGET accepts no arguments. If the next input line from the current procedure
contains a '??', the '??' is replaced by the third argument specified on the $PROCOPN
associated with the open procedure, just as if the third $PROCOPN argument had been
specified after the procedure name on an 'INCLUDE' command.
●
●
●
Sirius Functions
Janus Web Server
Products authorizing $PROCGET
——————————————————————————————————————————
328
——————————————————————————————————————————
$PROCLOC: Locate any of set of strings in procedure
——————————————————————————————————————————
7.156
$PROCLOC: Locate any of set of strings in
procedure
The $PROCLOC function accepts five arguments and returns a numeric result.
The first four arguments identify strings to be located in the currently open procedure. If
any of the specified strings is located in a given line of the procedure the search is
terminated. At least one search string must be specified. The total length of the first 4
arguments must be 256 or less.
The fifth argument, if set to 'Y', indicates that the case of the data in a procedure line
must match the case of the data in the search strings for a string to be considered
"matched". If this argument is not set to 'Y', a lower case character would be considered
to match the corresponding upper case character and vice versa.
%RC = $PROCLOC(string1, string2, string3, string4, respect)
$PROCLOC Function
$PROCLOC positions the "current line" in the file so that a subsequent $PROCGET
would return the line containing the matched string or strings. If you wish to continue
searching through the current procedure for the next occurrence of a string or strings
you must issue a $PROCGET to advance the current line. If you do not, $PROCLOC
will continue to match on the current line. For example, the following code, displays the
line number and contents of every line in procedure 'BIGPROC' that contains either the
string 'REPEAT' or the string 'ARRAY'.
%A = $PROCOPN('BIGPROC')
%LINE_NUM = 0
%A = 1
REPEAT WHILE %A GT 0
%A = $PROCLOC('REPEAT','ARRAY')
IF %A GT 0 THEN
%LINE_NUM = %LINE_NUM + %A
PRINT %LINE_NUM AND $PROCGET
END IF
END REPEAT
>0 - The number of lines that were tested before the
string or strings were located
-2 - Search string or strings not found
-3 - No search strings were specified
-4 - Total length of search strings > 256
$PROCLOC return codes
——————————————————————————————————————————
329
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
Sirius Functions
Janus Web Server
Products authorizing $PROCLOC
——————————————————————————————————————————
330
——————————————————————————————————————————
$PROCOPN: Open procedure for $PROCDAT, $PROCGET, $PROCLOC
——————————————————————————————————————————
7.157
$PROCOPN: Open procedure for $PROCDAT,
$PROCGET, $PROCLOC
The $PROCOPN function is used to "open" a procedure as input to a User Language
procedure via $PROCGET, $PROCDAT and $PROCLOC.
$PROCOPN accepts three arguments and returns a numeric code. As of Sirius Mods
version 6.8, it is a callable $function (“CALLing Sirius Mods functions” on page 32).
The first argument is required and identifies the User Language procedure to be opened.
The second argument is an optional file name. If the second argument is not provided,
or is a null string, the current file is used.
The third argument is a string that is used by $PROCGET for dummy string substitution
just as if this argument had been placed on an INCLUDE statement. Note that
$PROCDAT does no dummy string substitution.
For example, suppose procedure TIS_PITY in procedure file HOHO contains the line
FIND1: IN ?? FIND ALL RECORDS FOR WHICH
the sequence
%RESULT = $PROCOPN('TIS_PITY', 'HOHO', ' THESE ARE ARGUMENTS')
%LINE
= $PROCGET
would result in %LINE being set to
FIND1: IN THESE FIND ALL RECORDS FOR WHICH
%RESULT = $PROCOPN(proc_name, file_name, inc_string)
$PROCOPN Function
——————————————————————————————————————————
331
——————————————————————————————————————————
——————————————————————————————————————————
-1
0
1
2
-
3 4 5 6 -
Current include level not opened by $PROCOPN
Procedure opened without errors
Procedure is locked for edit or delete
Procedure does not exist or the current user does not
have access privilege
Specified procedure name is invalid (null)
File name invalid, or no current file, or caller
does not have sufficient privilege to
display/include procedures
The maximum number of open procedures (5)
has already been reached
Insufficient space in ITBL to hold third
argument; increase the size of ITBL
$PROCOPN return codes
After $PROCOPN has successfully opened a procedure, $PROCGET and $PROCDAT
may be used to retrieve the procedure source lines and $PROCLOC may be used to
scan them.
●
●
●
Sirius Functions
Janus Web Server
Products authorizing $PROCOPN
——————————————————————————————————————————
332
——————————————————————————————————————————
$RANDOM: Get next random number
——————————————————————————————————————————
7.158
$RANDOM: Get next random number
This function returns either an unpredictable random number, or the next number in a
series of random numbers.
$RANDOM accepts three optional arguments and returns an integer number.
The first argument specifies the smallest value that will be returned; the minimum value
of this argument is the same as its default: -1,000,000,000.
The second argument specifies the greatest value that will be returned; the maximum
value of this argument is the same as its default: 1,000,000,000. This argument must
be greater than the smallest value that will be returned.
The third argument is a %variable or IMAGE item that was set to a random number seed
using $RANDOM_SEED. This argument must be a string of length at least 144. If this
argument is omitted, the number returned is unpredictable; if it is present, the seed
determines a specific series of random numbers, and each call to $RANDOM returns the
next number in that series.
%RESULT = $RANDOM(minimum, maximum, %SEED)
$RANDOM Function
%RESULT contains a random number greater than or equal to minimum and
less than or equal to maximum.
If any argument is invalid, the request is cancelled.
%I = 5
REPEAT WHILE %I GT 0
%N = $RANDOM(1, 52)
IF %CARD(%N) NE '' THEN
PRINT %CARD(%N)
%I = %I - 1
%CARD(%N) = ''
END IF
END REPEAT
an unpredictable hand of 5 playing cards is “dealt”.
——————————————————————————————————————————
333
——————————————————————————————————————————
——————————————————————————————————————————
%HAND STRING LEN 144
REPEAT FOREVER
%X = $READ('Pick a 4-digit hand number')
IF %X EQ 0 THEN
%X = $RANDOM(1, 9999)
END IF
IF %X GT 0 AND %X LT 10000 THEN
LOOP END
END IF
PRINT 'I said a 4 digit number!'
END REPEAT
PRINT 'You are playing hand number' AND %X
%X = $RANDOM_SEED(%HAND, %X)
%I = 5
REPEAT WHILE %I GT 0
%N = $RANDOM(1, 52, %HAND)
IF %CARD(%N) NE '' THEN
PRINT %CARD(%N)
%I = %I - 1
%CARD(%N) = ''
END IF
END REPEAT
a hand of 5 playing cards is “dealt”, and the “player” can either ask for the particular
hand to play, or can just hit enter, and get an unpredictable hand.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $RANDOM
——————————————————————————————————————————
334
——————————————————————————————————————————
$RANDOM_SEED: Build seed specifying series of $RANDOM results
——————————————————————————————————————————
7.159
$RANDOM_SEED: Build seed specifying series
of $RANDOM results
This function sets a %variable or IMAGE item to a value that can be used by
$RANDOM, so that the series of numbers returned by $RANDOM is reproducible.
$RANDOM_SEED accepts two required arguments and returns zero.
The first argument is a %variable or IMAGE item to be set to a random number seed.
This argument must be a string of length at least 144.
The second argument specifies a number that determines the $RANDOM series. This
argument must be greater than or equal to -1,000,000,000 and less than or equal to
1,000,000,000.
%RESULT = $RANDOM_SEED(%SEED, seed_value)
$RANDOM_SEED Function
%SEED is initialized for a series of $RANDOM results that depends on
seed_value.
If any argument is invalid or omitted, the request is cancelled.
See the description of $RANDOM for examples of the use of $RANDOM_SEED.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $RANDOM_SEED
——————————————————————————————————————————
335
——————————————————————————————————————————
——————————————————————————————————————————
7.160
$REGEXMATCH: Whether string matches regex
This function determines whether a given pattern (regular expression, or “regex”)
matches within a given string according to the “rules” of regular expression matching
(information about the rules observed is provided in “Regex rules” on page 516). The
function is available as of version 6.9 of the Sirius Mods.
[%rc =] $REGEXMATCH(inStr, regex, [options], [%status])
$REGEXMATCH Function
%rc, if specified, is a number that is either 0 if the regular expression was
invalid or no match was found, or the position of the character after the last
character matched.
$REGEXMATCH accepts two required and two optional arguments, and it returns a
numeric value. It is also callable (“CALLing Sirius Mods functions” on page 32).
Specifying an invalid argument results in request cancellation.
●
The first argument is the input string, to which the regular expression regex is
applied. This is a required argument.
●
The second argument is a string that is interpreted as a regular expression and is
applied to the inStr argument to determine whether the regex matches inStr. This is
●
The third argument is an optional string of options. The options are single letters,
which may be specified in uppercase or lowercase, in any combination, and
separated by blanks or not separated. For more information about these options,
see “Common regex options” on page 522
I
Do case-insensitive matching between string and regex.
S
Dot-All mode: a dot (.) can match any character, including carriage return
and linefeed.
M
Multi-line mode: let anchor characters match end-of-line indicators wherever
the indicator appears in the input string.
M mode is ignored if C (XML Schema) mode is specified.
C
●
Do the match according to XML Schema regex rules. Each regex is implicitly
anchored at the beginning and end, and no characters serve as anchors. For
more information, see “XML Schema mode” on page 523.
The fourth argument is optional; if specified, it is set to an integer status value.
These values are possible:
1
A successful match was obtained.
——————————————————————————————————————————
336
——————————————————————————————————————————
$REGEXMATCH: Whether string matches regex
——————————————————————————————————————————
0
No match: inStr was not matched by regex.
-1nnn
The pattern in regex is invalid. nnn, the absolute value of the return minus
1000, gives the 1-based position of the character being scanned when the
error was discovered. The value for an error occurring at end-of-string is
the length of the string + 1.
Prior to version 7.0 of the Sirius Mods, an invalid regex results in a status
value of -1.
Note: If you omit this argument and a negative status value is to be
returned, the run is cancelled.
Notes
●
It is strongly recommended that you protect your environment from regex
processing demands on PDL and STBL space by setting, say, UTABLE LPDLST
3000 and UTABLE LSTBL 9000. For further discussion of this, see “User
Language programming considerations” on page 525.
●
$REGEXMATCH is considered Longstring-capable. Its string inputs and outputs
are considered Longstrings for expression-compilation purposes, and they have
standard Longstring truncation behavior: truncation by assignment results in request
cancellation. For more information, see “Longstrings and $functions” on page 16.
●
If %rc is zero, either regex did not match inStr, or there was an error in the regex.
The %status argument returns additional information. If it is negative, it indicates an
error. If it is zero, it indicates there was no error, but the regex did not match.
●
For information about additional methods and $functions that support regular
expressions, see “Regex Processing” on page 515.
——————————————————————————————————————————
337
——————————————————————————————————————————
——————————————————————————————————————————
The following example tests whether the regex \*bc?[5-8] matches the string a*b6.
If the return code is 0 (no match), the status variable is checked for more information.
Begin
%rc float
%regex Longstring
%String Longstring
%Options string len 10
%status float
%Options = ''
%regex = '\*bc?[5-8]'
%String = 'a\*b6'
%rc = $RegexMatch (%String, %regex, %Options, %status)
If (%rc EQ 0) then
Print 'Status from $RegexMatch is ' %status
Else
Print %regex ' matches ' %String
End If
End
The regex matches the input string; the example result is:
\*bc?[5-8] matches a\*b6
This regex demonstrates the following:
●
●
●
●
To match a string, a regex pattern must merely “fit” a substring of the string.
Metacharacters, in this case star (*), must be escaped.
An optional character (c?) may fail to find a match, but this does not prevent the
success of the overall match.
The character class range ([5-8]) matches the 6 in the input string.
$REGEXMATCH is available as of version 6.9.
●
Sirius Functions
Products authorizing $REGEXMATCH
——————————————————————————————————————————
338
——————————————————————————————————————————
$REGEXREPLACE: Replace matching strings
——————————————————————————————————————————
7.161
This function searches a given string for matches of a regular expression, and it replaces
found matches with or according to a specified replacement string. The function stops
after the first match and replace, or it can continue searching and replacing until no more
matches are found. The function is available as of version 6.9 of the Sirius Mods.
Matches are obtained according to the “rules” of regular expression matching
(information about the rules observed is provided in “Regex rules” on page 516).
outStr = $REGEXREPLACE(inStr, regex, replacement, [options], [%status])
$REGEXREPLACE Function
outStr is a string set to the value of inStr with each matched substring replaced
by the value of replacement.
$REGEXREPLACE accepts three required and two optional arguments, and it returns a
string. It is also callable (“CALLing Sirius Mods functions” on page 32). Specifying an
invalid argument results in request cancellation.
●
The first argument is the input string, to which the regular expression regex is
applied. This is a required argument.
●
The second argument is a string that is interpreted as a regular expression and that
is applied to the inStr argument to find the one or more inStr substrings matched by
regex. This is a required argument.
●
The third argument is the string that replaces the substrings of inStr that regex
matches. This is a required argument.
Except when the A option is specified (as described below for the fourth argument),
you can include markers in the replacement value to indicate where to insert
corresponding captured strings — strings matched by capturing groups
(parenthesized subexpressions) in regex, if any.
As in Perl, these markers are in the form $n, where n is the number of the capture
group, and 1 is the number of the first capture group. n must not be 0 or contain
more than 9 digits.
If a capturing group makes no matches (is positional, for example), or if there was
no nth capture group corresponding to the $n marker in a replacement string, the
value of $n used in the replacement string is the empty string.
xxx$1 is an example of a valid replacement string, and $0yyy is an example of a
non-valid one.
——————————————————————————————————————————
339
——————————————————————————————————————————
——————————————————————————————————————————
Or you can use the format $mn, where m is one of the following modifiers:
U or u
L or l
Specifies that the specified captured string should be uppercased when
inserted.
Indicates that the captured string should be lowercased when inserted.
The only characters you can escape in a replacement string are dollar sign ($),
backslash (\), and the digits 0 through 9. So only these escapes are respected:
\\, \$, and \0 through \9. No other escapes are allowed in a replacement string
— this includes “shorthand” escapes like \d — and an “unaccompanied” backslash
(\) is an error.
For example, since the scan for the number that accompanies the meta-$ stops at
the first non-numeric, you use 1$1\2 to indicate that the first captured string should
go between the numbers 1 and 2 in the replacement string.
●
The fourth argument is an optional string of options. The options are single letters,
which may be specified in uppercase or lowercase, in any combination, and
separated by blanks or not separated. For more information about these options,
see “Common regex options” on page 522
I
Do case-insensitive matching between string and regex.
S
Dot-All mode: a dot (.) can match any character, including carriage return
and linefeed.
M
Multi-line mode: let anchor characters match end-of-line indicators wherever
the indicator appears in the input string.
M mode is ignored if C (XML Schema) mode is specified.
●
C
Do the match according to XML Schema regex rules. Each regex is implicitly
anchored at the beginning and end, and no characters serve as anchors. For
more information, see “XML Schema mode” on page 523.
G
Replace every occurrence of the match, not just (as in non-G mode) the first
matched substring only.
A
Copy the replacement string as is. Do not recognize escapes; interpret a $n
combination as a literal and not as a special marker; and so on.
The fifth argument is optional; if specified, it is set to an integer error code. These
values are possible:
n
The number of replacements made.
0
No match: inStr was not matched by regex.
——————————————————————————————————————————
340
——————————————————————————————————————————
——————————————————————————————————————————
-5
An invalid replacement string. For example, an invalid escape sequence,
or a $ followed by a non-number, by a 0 or by no digits, or by more than 9
digits.
-1nnn
The pattern in regex is invalid. nnn, the absolute value of the return minus
1000, gives the 1-based position of the character being scanned when the
error was discovered. The value for an error occurring at end-of-string is
the length of the string + 1.
Prior to version 7.0 of the Sirius Mods, an invalid regex results in a status
value of -1.
Note: If you omit this argument and a negative status value is to be returned, the
run is cancelled.
Notes
●
It is strongly recommended that you protect your environment from regex
processing demands on PDL and STBL space by setting, say, UTABLE LPDLST
3000 and UTABLE LSTBL 9000. For further discussion of this, see “User
Language programming considerations” on page 525.
●
$REGEXREPLACE is considered Longstring-capable. Its string inputs and outputs
are considered Longstrings for expression-compilation purposes, and they have
standard Longstring truncation behavior: truncation by assignment results in request
cancellation. For more information, see “Longstrings and $functions” on page 16.
●
Within a regex, characters enclosed by a pair of unescaped parentheses form a
“subexpression”. A subexpression is a capturing group if the opening parenthesis is
not followed by a question mark (?). A capturing group that is nested within a noncapturing subexpression is still a capturing group.
●
In Perl, $n markers ($1, for example) enclosed in single quotes are treated as
literals instead of as “that which was captured by the first capturing parentheses.”
$REGEXREPLACE uses the A option of the Option argument for this purpose.
●
A regex may “succeed” but match no characters. For example, a quantifier like ? is
allowed by definition to match no characters, though it tries to match one.
$REGEXREPLACE honors such a zero-length match by substituting the specified
replacement string at the current position. If the global option is in effect, the regex
is then applied again one position to the right in the input string, and again, until the
end of the string. The regex 9? globally applied to the string abc with a commacomma (,,) replacement string results in this output string: ,,a,,b,,c,,.
●
Say you want to supply end tags to items of of the form <img foo="bar">,
converting them to <img foo="bar"></img>. You decide to use the following
regex to capture img tags that have attributes:
——————————————————————————————————————————
341
——————————————————————————————————————————
——————————————————————————————————————————
(<img .*>)
And you use the following replacement string to replace the captured string with the
captured string plus an appended </img>:
$1</img>
However, if the regex above is applied to the string <body><img src="foo"
width="24"></body>, the end tag </img> is not inserted after the first closing
angle bracket (>) after "24" as you want. Instead, the matched string greedily
extends to the second closing angle bracket, and the tag </img> is positioned at
the end:
<body><img src="foo" width="24"></body></img>
One remedy for this situation is to use the following regex, which employs a negated
character class to match non-closing-bracket characters:
(<img [ˆ>]*>)
This regex does not extend beyond the first closing angle bracket in the target input
string, and the resulting output string is:
<body><img src="foo" width="24"></img></body>
●
For information about additional methods and $functions that support regular
expressions, see “Regex Processing” on page 515.
In the following example, the regex (5.) is applied repeatedly (global option) to the
string 5A5B5C5D5E to replace the uppercase letters with their lowercase counterparts.
The $L1 %relacement value makes the replacement string equal to whatever is matched
by the capturing group, (5.), in the regex (the L causes the lowercase versions of the
captured letters to be used).
Begin
%regex Longstring
%inStr Longstring
%replacement Longstring
%outStr Longstring
%opt string len 10
%status float
%inStr='5A5B5C5D5E'
%regex='(5.)'
%replacement='$L1'
%opt='g'
%outStr = $REGEXREPLACE (%inStr, %regex, %replacement,
%opt, %status)
Print '%RegexReplace: status = ' %status
Print 'OutputString: ' %outStr
End
-
——————————————————————————————————————————
342
——————————————————————————————————————————
——————————————————————————————————————————
The example result is:
%RegexReplace: status = 5
OutputString: 5a5b5c5d5e
The non-capturing regex 5. matches and replaces the same substrings as the capturing
group (5.), but (5.) is used above to take advantage of the self-referring marker for
the replacement string, $L1, which is valid only for capturing groups.
This $function is available as of version 6.9.
●
Sirius Functions
Products authorizing $REGEXREPLACE
——————————————————————————————————————————
343
——————————————————————————————————————————
——————————————————————————————————————————
7.162
$RESETN: Reset or view M204 parameter
This function retrieves the current value of a Model 204 parameter, and it can also
change the value of that parameter. Not all parameters are resettable by $RESETN: the
supported subset includes only parameters considered useful to change as well as safe
to change during evaluation of a User Language request.
$RESETN accepts one required and two optional arguments, and it returns a numeric
value.
●
The first argument is a string which is the name of the parameter to retrieve (and
optionally reset). See the list in “Parameters resettable by $RESETN” on page 345
for the parameters allowed.
●
The second argument is an optional numeric value. If specified, the parameter is
reset to this value.
●
The third argument is an optional %variable which is the target for the $RESETN
return code. If specified, this %variable is set to one of the return codes shown in
the table below. If this argument is omitted and a condition occurs that is associated
with a non-zero value in the return code table, the request is cancelled.
This %variable may not be a Janus SOAP ULI class variable.
●
The returned value is the current value of the parameter (before $RESETN changes
it). If the first argument is not the name of a parameter supported by $RESETN, the
returned value is 0 (if argument 3 is supplied; otherwise this and all errors cause
request cancellation).
$RESETN is callable (“CALLing Sirius Mods functions” on page 32).
[%oldval =] $RESETN(parameter, newval, %rc_variable)
$RESETN Function
%oldval is set to the parameter value before being reset.
-1 - Invalid value for parameter
0 - Successful completion
1 - Invalid parameter name
$RESETN return codes (set in argument 3)
For example, the following fragment will to prevent the M204.0620 FILE OPENED and
M204.1203 FILE WAS LAST UPDATED messages from going to the user's terminal:
%VAL = $RESETN('MSGCTL', 2)
OPEN 'MYFILE' PASSWORD 'UPDATE'
%VAL = $RESETN('MSGCTL', %VAL)
——————————————————————————————————————————
344
——————————————————————————————————————————
$RESETN: Reset or view M204 parameter
——————————————————————————————————————————
In the following list of parameters, the minimum and maximum value is shown. Note that
these values may be more strict than the corresponding minimums and maximums
allowed by the Model 204 RESET command. For example, the RESET ERMX -2
command changes ERRMX to a value, as shown by the response to the command, of
65534. However, the value of -2 is not “meaningful” for ERMX. To avoid this, an
attempt to invoke $RESETN('ERMX', -2) is rejected, because -2 is outside the legal
range for ERMX.
Note: This situation is even more pointed for UDDLPP, which is currently not supported
for $RESETN because there's little reason to change it from within a User Language
request.
The RESET UDDLPP -1 command changes UDDLPP to a value, as shown by the
response to the command or as returned by $VIEW, of 65535. However, the
RESET UDDLPP 65535 command issues an error message and changes UDDLPP to
the value of 32767, which is very different from the meaning of -1 for UDDLPP.
The valid parameter names which may be supplied as the first argument to $RESETN
are shown in the following list, along with the minimum and maximum values and a terse
description. For more information about these parameters, see the Model 204
Command Reference Manual, except, where indicated, a parameter is not a base
Model 204 parameter but is one that is delivered with the Sirius Mods.
Parameters resettable by $RESETN
ENQRETRY
0..255: Number of record locking retries
ERCNT
0..65,535: Error count (provided by the Sirius Mods). (Note that the
you can also increment or clear this using “$ERRSET: Increment or
clear number of counting errors, set $ERRMSG” on page 99.)
ERMX
-1..65,534: Maximum number of errors
FSOUTPUT
0..2: Full screen color and highlighting
HDRCTL
0..255: Header control
MBSCAN
-2,147,483,647..2,147,483,647: Maximum table B to records scan
MCNCT
-2,147,483,647..2,147,483,647: Maximum connect time
MCPU
-2,147,483,647..2,147,483,647: Maximum CPU time
MDKRD
-2,147,483,647..2,147,483,647: Maximum disk reads
MDKWR
-2,147,483,647..2,147,483,647: Maximum disk writes
MOUT
-2,147,483,647..2,147,483,647: Maximum output lines
MSGCTL
0..255: Message printing options
——————————————————————————————————————————
345
——————————————————————————————————————————
——————————————————————————————————————————
MUDD
-2,147,483,647..2,147,483,647: Maximum USE dataset lines
As mentioned, the second argument to $RESETN is the numeric value to which the
parameter should be set. Some of the parameters supported by $RESETN are treated
as “hexadecimal” parameters by the Model 204 RESET command. For example, the
VIEW HDRCTL command displays a result such as “X'01'”. It so happens that this is a
moot point with any of these “hex” parameters currently supported by $RESETN,
because the maximum value they may have is 7, which is the same in base 10 and base
16. However, if $RESETN is extended to support, for example, UDDRFM, you might
wish to supply an argument to $RESETN expressed in hex. This could be easily
accomplished using the $X2D function. Again, assuming $RESETN were extended to
support UDDRFM, you could set the USE dataset record format to variable length
records with ASA carriage control with the following statement:
%VAL = $RESETN('UDDRFM', $X2D('12'))
See also “$SIRPARM: Set user-specific value, controlling Sirius products” on page 409.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $RESETN
——————————————————————————————————————————
346
——————————————————————————————————————————
$SCRHIDE: Hide lines in SCREEN
——————————————————————————————————————————
7.163
$SCRHIDE: Hide lines in SCREEN
This function adjusts a SCREEN structure so that all fields after a specific line number
are hidden (not displayed) on subsequent READ SCREEN statements. This makes it
possible to build a screen that contains more lines than would fit on all terminal models
and then hide an appropriate number of lines based on terminal model number. The
$SCRHIDE statement can also be used to provide space for the $SCRWIDE function for
Model 5 terminals.
The $SCRHIDE function accepts two arguments and returns a numeric code indicating
its success. As of Sirius Mods version 6.8, it is a callable $function (“CALLing Sirius
Mods functions” on page 32).
The first argument is the name of the screen on which fields are to be hidden.
The second argument is the line number of the first line on the screen to be hidden.
Fields on this line number and all subsequent lines are hidden.
%RESULT = $SCRHIDE(scr_name, line_num)
$SCRHIDE Function
%RESULT is set to indicate success of the function.
0 - No errors
1 - SCREEN does not exist or invalid screen name
2 - Invalid line number
$SIRHIDE return codes
The code fragment
[%RC =] $SCRHIDE('INPUT', 24)
hides all lines after line 24 on screen INPUT.
Using $SCRHIDE, $SCRWIDE and $SCRSIZE you can expand the number and size of
3270 screen lines available to your User Language programs to the maximum that will fit
——————————————————————————————————————————
347
——————————————————————————————————————————
——————————————————————————————————————————
on the terminal type. Here is an example technique for presenting as much information
as the user's screen can contain:
SCREEN USER1
* Line 02:
PROMPT '===>'
WHITE
AT 2 INPUT COMMAND
GREEN
AT 7 LEN 40
* Line 03:
PROMPT LINE1
AT 2 LEN 77
* Line 04:
PROMPT LINE2
AT 2 LEN 77
...
* Line 44:
PROMPT LINE42
AT 2 LEN 77
* Line 45:
PROMPT LINE43
AT 2 LEN 77
END SCREEN
%SCR.LENGTH = 24
%SCR.WIDTH = 80
%SCR.MODEL = $VIEW('MODEL')
JUMP TO (MOD0, MOD0, MOD3, MOD4, MOD5) %SCR.MODEL
JUMP TO MOD0
MOD3:
%SCR.LENGTH = 32
JUMP TO MOD0
MOD4: %SCR.LENGTH = 43
JUMP TO MOD0
MOD5: %SCR.LENGTH = 27
%SCR.WIDTH = 132
MOD0: %MAX.WIDTH = %SCR.WIDTH - 3
%X = $SCRHIDE( 'USER1' , %SCR.LENGTH )
%X = $SCRWIDE( 'USER1' )
%SCROLL.LEN = %SCR.LENGTH - 7
FOR %X FROM 1 TO %SCROLL.LEN + 1
%LINE = 'USER1:LINE' WITH %X
%X = $SCRSIZE( %LINE , %SCR.WIDTH )
END FOR
●
Sirius Functions
Products authorizing $SCRHIDE
——————————————————————————————————————————
348
——————————————————————————————————————————
$SCRSIZE: Change size of field on SCREEN
——————————————————————————————————————————
7.164
$SCRSIZE: Change size of field on SCREEN
This function changes the size of a field on a SCREEN.
The $SCRSIZE function accepts two arguments and returns a numeric code indicating
The first argument is the name of the field whose size is to be changed. The field name
must be specified as a string that contains the screen name, a colon, and the field name.
The screen name should not have a '%' at the start. 'INPUT:FIELD4' is an example of a
valid field name.
The second argument is the new size of the field. The field size can be decreased or it
can be increased up to the point where it would overlap another field or run off the end of
a screen. It is always possible to extend a field into the "TAG" field (columns 79-80) and
it is possible to extend it up to column 132 if the screen had been prepared with a
$SCRWIDE function.
[%RESULT =] $SCRSIZE(field_name, size)
$SCRSIZE Function
0
1
2
3
-
No errors
Field does not exist or invalid field name
Invalid size (less than 1 or greater than screen size)
Would overlap other field
$SIRSIZE return codes
The code fragment
%RC = $SCRSIZE('INPUT:FIELD1', 30)
sets the size of input field FIELD1 on screen INPUT to 20.
See “$SCRHIDE: Hide lines in SCREEN” on page 347 for a complete example using
$SCRHIDE, $SCRSIZE, and $SCRWIDE.
●
Sirius Functions
Products authorizing $SCRSIZE
——————————————————————————————————————————
349
——————————————————————————————————————————
——————————————————————————————————————————
7.165
$SCRWIDE: Allow SCREEN to accept fields
wider than 79
This function adjusts a SCREEN structure so that it is capable of accommodating fields
that are wider than 79 bytes. These "wide" fields can only be displayed on a Model 5
terminal and can be created with the $SCRSIZE function. Generally, the $SCRWIDE
function must be preceded by a $SCRHIDE function if it is used on a Model 5 terminal.
This is because the $SCRHIDE function provides extra space that can be used by the
$SCRWIDE function.
The $SCRWIDE function accepts one argument and returns a numeric code indicating
The only argument is the name of the screen to be “widened.”
[%RESULT =]
$SCRWIDE(scr_name)
$SCRWIDE Function
0 - No errors
1 - SCREEN does not exist or invalid screen name
2 - Not enough space to widen screen (need $SCRHIDE)
$SIRWIDE return codes
The code fragment
%RC = $SCRWIDE('INPUT')
makes it possible to create "wide" fields on screen INPUT. Note that the $SCRWIDE
function does not, in itself, change the appearance of a SCREEN. It simply makes it
possible to make fields wider than 79 columns with the $SCRSIZE function on Model 5
terminals.
See “$SCRHIDE: Hide lines in SCREEN” on page 347 for a complete example using
$SCRHIDE, $SCRSIZE, and $SCRWIDE.
●
Sirius Functions
Products authorizing $SCRWIDE
——————————————————————————————————————————
350
——————————————————————————————————————————
$SESSION, $SESSION_ID, $SESSION_OWNER and $SESSION_TIMEOUT
——————————————————————————————————————————
7.166
$SESSION, $SESSION_ID, $SESSION_OWNER
and $SESSION_TIMEOUT
These functions accept no arguments and return the requested value associated with
the current open session.
$SESSION returns a 1 if the user has a session currently open and a 0 otherwise.
$SESSION_ID returns the id of the currently open session if there is one and a null
otherwise.
$SESSION_OWNER returns the owner of the currently open session if there is one and
a null otherwise. A value of “*” indicates that the currently open session is a public
session.
$SESSION_TIMEOUT returns the timeout value of the currently open session if there is
one and a -1 otherwise.
These $functions are new in Sirius Mods version 6.3.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SESSION, $SESSION_ID, $SESSION_OWNER and $SESSION_TIM
——————————————————————————————————————————
351
——————————————————————————————————————————
——————————————————————————————————————————
7.167
$SESSION_CLOSE: Close an open session
$SESSION_CLOSE closes an open session, accepts three arguments and returns a
zero, indicating success, or a number indicating the cause of error, if there is one.
The first argument is new id to be given to the session being closed. This is an optional
argument and if not specified leaves the session's id unchanged.
The second argument is the userid that is to be set as the new owner of the session
being closed. An owner of “*” means that the session is public, that is available to all
users. Only a system administrator can create a non-public session for a user other
than itself. This is an optional argument and if not specified leaves the session's owner
unchanged.
The third argument is the new value to be used as the session timeout value, that is the
time after which the session is considered timed-out, that is eligible for deletion. A value
of -1 means to use the SRSDEFTO parameter value. This is an optional argument and
if not specified leaves the session's timeout value unchanged.
%RC = $SESSION_CLOSE(sesid, owner, timeout)
$SESSION_CLOSE function
-1
0
1
2
3
-
Session not open
No errors
Session id already exists for user
Online session limit exceeded
User session limit exceeded
$SESSION_CLOSE return codes
The return codes greater than 0 can only happen when one or more of the session
attributes (id, owner, timeout) is being changed.
After a $SESSION_CLOSE, any session $lists, longstrings and XMLDocs will no longer
be accessible.
If a $SESSION_DELETE had been done for the session before it was closed by the user
who had the session open or someone else, the session is immediately deleted when
the $SESSION_CLOSE is done. A logout always does an implied $SESSION_CLOSE
so $SESSION_CLOSE is only necessary if another session is to be open or to minimize
the time window in which the session might be requested by another thread.
The following example closes the current session, making it a public session in the
process:
%RC = $SESSION_CLOSE(, '*')
——————————————————————————————————————————
352
——————————————————————————————————————————
$SESSION_CLOSE: Close an open session
——————————————————————————————————————————
This $function is new in Sirius Mods version 6.3.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SESSION_CREATE
——————————————————————————————————————————
353
——————————————————————————————————————————
——————————————————————————————————————————
7.168
$SESSION_CREATE: Create a new session
$SESSION_CREATE creates a new session, accepts four arguments and returns a
zero, indicating success, or a number indicating the cause of error, if there is one.
The first argument is id to be given to the new session. This is a required argument.
The second argument is the userid that will own this session. An owner of “*” means
that the session is public, that is available to all users. Only a system administrator can
create a non-public session for a user other than itself. This optional argument defaults
to the creating user's userid.
The third argument is the time after a $SESSION_CLOSE (or logout) after which the
session is considered timed-out, that is eligible for deletion. A value of -1 means use the
SRSDEFTO parameter value. This optional argument defaults to -1, that is the
SRSDEFTO parameter value.
The fourth argument is a blank delimited set of options to control the create process.
The options are:
OPEN
Automatically open the session upon creating it. This is the default behavior.
NOOPEN Don't automatically open the session upon creating it. This is not the default
behavior but might be useful if creating a session for another user or creating
many sessions at once.
%RC = $SESSION_CREATE(sesid, owner, timeout, opts)
$SESSION_CREATE function
0
1
2
3
-
No errors
Session id already exists for user
Online session limit exceeded
User session limit exceeded
$SESSION_CREATE return codes
The following example creates a session called “GROUCHO” followed by a timestamp
then sets a cookie for a web application so that the session can be easily located on
subsequent web requests.
%SESID = 'GROUCHO' WITH $SIRTIME
%RC = $SESSION_CREATE(%SESID, , 3600)
%RC = $WEB_SET_COOKIE('SESID', %SESID)
——————————————————————————————————————————
354
——————————————————————————————————————————
$SESSION_CREATE: Create a new session
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SESSION_CREATE
——————————————————————————————————————————
355
——————————————————————————————————————————
——————————————————————————————————————————
7.169
$SESSION_DELETE: Delete a session
$SESSION_DELETE deletes a session, accepts three arguments and returns a zero,
indicating success, or a number indicating the cause of error, if there is one.
The first argument is the id of the session to be deleted. This is a required argument.
The second argument is the userid that owns the session to be deleted. An owner of “*”
means that the session is public, that is available to all users. This optional argument
defaults to the creating user's userid.
The third argument is the time to wait for an in-use session to be closed to perform a
synchronous delete. If timeout is 0 or the session being deleted is the session currently
opened by the invoking user or the session is not closed within the indicated timeout
time, the session is deleted asynchronously when the session is closed. This argument
defaults to 0 which means that if the session is in-use it is deleted asynchronously.
%RC = $SESSION_DELETE(sesid, owner, timeout)
$SESSION_DELETE function
0 - No errors
1 - Session not found
2 - Session in use
$SESSION_DELETE return codes
A return code of 2 indicates that while the session hasn't been deleted, it will be as soon
as it is closed. In fact, this would be the normal return code when deleting the current
sesssion — the session actually being deleted when it is closed or the user logs off. The
following example deletes the current session no matter what its id:
%SESID = $SESSION_ID
%RC = $SESSION_DELETE(%SESID)
%RC = $SESSION_CLOSE
——————————————————————————————————————————
356
——————————————————————————————————————————
$SESSION_DELETE: Delete a session
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SESSION_DELETE
——————————————————————————————————————————
357
——————————————————————————————————————————
——————————————————————————————————————————
7.170
$SESSION_LIST: Get list of sessions
$SESSION_CREATE returns information about sessions to a $list, accepts three
arguments and returns a the number of items added to the output $list. All errors result
in request cancellation.
The first argument is the $list identifier to receive the output from $SESSION_LIST. This
is a required argument.
The second argument is the session id for which information is to be returned. This
argument can contain wildcards — for example “PEQ*” indicates that information is to be
returned for all sessions beginning with the letters “PEQ”. This is an optional argument
and defaults to “*” meaning all session ids are to be listed.
The third argument is the session owner for which information is to be returned. This
argument can contain wildcards though for a non-system manager user only sessions
owned by the requesting user and public sessions will be listed. Note that a “*” will list
all private and public sessions but a “"*” will list public sessions only. This is an optional
argument and defaults to the userid of the invoking user.
%RC = $SESSION_LIST(listid, sesid, owner)
$SESSION_LIST
%RC is set to the number of added items.
The format of the data in the output $list is
Col 1-10
Owner of the session; * for public sessions.
Col 11-16 Session timeout value.
Col 17-30 Session creation time in YYYYMMDDHHMISS format.
Col 31-44 Last session access time in YYYYMMDDHHMISS format. If the session is
currently open this value is the time of the $SESSION_LIST invocation and
will have the same value for all sessions open at the time of the
$SESSION_LIST call.
Col 45-50 User number with session open. If the session is not currently open by any
users these columns contain all blanks.
Col 51-
The session id.
The session id and owner specified in the second and third arguments can be explicit
names or can contain the following wildcard characters:
*
——————————————————————————————————————————
358
——————————————————————————————————————————
$SESSION_LIST: Get list of sessions
——————————————————————————————————————————
?
"
character.
For example, “C*D” matches “CUSTID”, “COD” or “CLOD”. “S??T” matches “SALT”,
“SLOT” or “SORT”. “"*” matches “*” that is public sessions in the case of the owner. The
following example displays information about all sessions owned by the current user:
%LIST = $LISTNEW
%RC = $SESSION_LIST(%LIST)
%RC = $LIST_PRINT(%LIST)
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SESSION_LIST
——————————————————————————————————————————
359
——————————————————————————————————————————
——————————————————————————————————————————
7.171
$SESSION_OPEN: Open a session
$SESSION_OPEN opens a previously created session, accepts three arguments and
returns a zero, indicating success, or a number indicating the cause of error, if there is
one.
The first argument is the id of the session to be opened. This is a required argument.
The second argument is the userid that owns the session to be opened. An owner of “*”
means that the session is public, that is available to all users. This optional argument
defaults to the creating user's userid.
The third argument is the time to wait for an in-use session to be closed before giving
up. A value of -1 indicates to use the value of the SRSDEFOW parameter. This
argument defaults to -1, that is the value of the SRSDEFOW parameter.
%RC = $SESSION_OPEN(sesid, owner, timeout)
$SESSION_OPEN function
0 - No errors
1 - Session not found
2 - Session in use
$SESSION_OPEN return codes
Use of a non-zero timeout for $SESSION_OPEN can be useful for single-threading
multiple threads through a request or for dealing with timing problems where it's possible
for a request for a session to come in before the previous one is completely done. This
is quite possible in Janus Web Server applications where a request resulting from a
redirect comes in before the redirecting thread has closed the session or where a user
cancels a request and then resubmits it while the original request is still processing and
so has the session open. The following retrieves a session id from a cookie and opens
it:
%SESID = $WEB_GET_COOKIE('SESID')
%RC = $SESSION_OPEN(%SESID)
——————————————————————————————————————————
360
——————————————————————————————————————————
$SESSION_OPEN: Open a session
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SESSION_DELETE
——————————————————————————————————————————
361
——————————————————————————————————————————
——————————————————————————————————————————
7.172
$SETG_SUBSYS: Set subsystem-wide global
This function allows a user to set the value of a Model 204 “global variable” which has a
subsystem-wide scope. These are used for the value of the $GETG function or dummy
string (“?&”) substitution. The order in which the different scopes of global variables are
searched can be controlled using $SIRPARM parameters: for $GETG, with 'GETGSYS',
and for dummy strings, with 'DUMMYSYS'.
The $SETG_SUBSYS function accepts three arguments and returns zero, indicating
The first argument is the name of the global variable to be set. This is an optional
The second argument is the value to which the global variable is to be set. This is an
optional argument; it defaults to the null string.
The third argument is the name of the subsystem that the variable is associated with.
This is an optional argument if the $function is invoked from within a subsystem; it
defaults to the null string. A non-null subsystem name is required if the $function is
invoked from outside a subsystem. If invoked from a subsystem and the third argument
is null, the name of the subsystem is used.
System administrator privileges are required to invoke this $function, unless the third
argument is omitted or is the null string, and the $function is invoked from a precompiled
procedure; in that case, no privileges are required, and the subsystem name used is the
active subsystem.
%RC = $SETG_SUBSYS(glob_name, value, subsys_name)
$SETG_SUBSYS Function
0
1
2
3
-
No errors
Not system administrator
Insufficient storage
Subsystem name missing
$SETG_SUBSYS return codes
This function can be used to set a global variable which is used for all users of a
subsystem. The value can be set during Model 204 initialization (that is, in the CCAIN
stream), so values can be calculated once, rather than every time a user enters the
subsystem. For example, the following request can be run from CCAIN:
——————————————————————————————————————————
362
——————————————————————————————————————————
——————————————————————————————————————————
OPEN CALENDAR
BEGIN
%DAYS STRING LEN 100
%X FLOAT
%DAYS = ''
D: FOR EACH VALUE OF DAY
%DAYS = %DAYS WITH ' ' WITH VALUE IN D
END FOR
%X = $SETG_SUBSYS('DAYS', %DAYS, 'TIMESHEET')
END
Then, during execution of the TIMESHEET subsystem, the global variable DAYS can be
used to obtain the days of the week.
Also, since there is one shared subsystem global table for the entire system, a smaller
GTBL value for each user can be achieved than if the global values are set with user
global variables.
The order in which the different scopes of global variables are searched can be
controlled using $SIRPARM parameters: for $GETG, with 'GETGSYS', and for dummy
strings, with 'DUMMYSYS'. Here is an example to show the effects of DUMMYSYS and
GETGSYS; assume the following procedure is executed in the CCAIN input stream:
BEGIN
%X = $SETG_SUBSYS('JUNK', 'HELLO', 'MY_SUBSYS')
END
and the login procedure of MY_SUBSYS contains the following requests:
BEGIN
%Y = $SETG('JUNK', 'GOODBYE')
END
BEGIN
PRINT '?&JUNK'
PRINT $GETG('JUNK')
END
Then here are various command streams, and their results:
——————————————————————————————————————————
363
——————————————————————————————————————————
——————————————————————————————————————————
1. DUMMYSYS=0, GETGSYS=0:
BEGIN
%X FLOAT
%X = $SIRPARM('DUMMYSYS', 0)
%X = $SIRPARM('GETGSYS', 0)
END
MY_SUBSYS
produces the following print lines:
GOODBYE
GOODBYE
BEGIN
%X FLOAT
END
MY_SUBSYS
GOODBYE
HELLO
BEGIN
%X FLOAT
END
MY_SUBSYS
HELLO
GOODBYE
——————————————————————————————————————————
364
——————————————————————————————————————————
——————————————————————————————————————————
BEGIN
%X FLOAT
END
MY_SUBSYS
HELLO
HELLO
The current values of subsystem globals can be retrieved using $SETG_SUBSYS_LIST.
Retrieval of subsystem global variables is highly efficient; updates, however, are not, so
use this $function appropriately.
For an explanation of $SIRPARM, see “$SIRPARM: Set user-specific value, controlling
Sirius products” on page 409.
●
●
Sirius Functions
Janus Web Server
Products authorizing $SETG_SUBSYS
——————————————————————————————————————————
365
——————————————————————————————————————————
——————————————————————————————————————————
7.173
$SETG_SUBSYS_LIST: Get list of
subsystem-wide globals
This function returns names and values from the current set of subsystem global
variables. It may be useful in debugging situations.
The $SETG_SUBSYS_LIST function accepts four arguments and returns zero,
indicating success, or a number indicating the cause of error, if there is one.
The first argument identifies the $list to which items for the subsystem globals will be
added. This is a required argument.
The second argument is the string which is used to separate the global name from its
value in each item of the output $list. This is an optional argument; if omitted, or if the
null string is supplied, it defaults to a single byte with value X'00'. This separator value
(X'00') can be particularly useful for sorting the output $list, as shown in the example
below.
The third argument specifys the subsystem(s) whose global variables are to be
examined for placement on the output $list. This argument may contain pattern
matching characters. This is a required argument, and it may not be the null string.
The fourth argument is a pattern string; all global variables in the selected subsystem(s)
matching this pattern are placed on the output $list. This is an optional argument; if
omitted, all variables in the subsystems specified by the third argument are placed on
the output $list.
%RC = $SETG_SUBSYS_LIST(list_id, sep, subsys_pat, glob_pat)
$SETG_SUBSYS_LIST Function
0 - No errors
3 - Subsystem name missing
$SETG_SUBSYS_LIST return codes
This function can be used for debugging, to retrieve values of selected global variables
for selected subsystems. The names of subsystems and global variables can be
specified using the following wildcard characters:
*
?
——————————————————————————————————————————
366
——————————————————————————————————————————
$SETG_SUBSYS_LIST: Get list of subsystem-wide globals
——————————————————————————————————————————
"
character.
The format of the items created by $SETG_SUBSYS_LIST is as follows; ss is the length
of the separator string, gg is the length of the global name, vv is the length of the global
value:
Length
-----10
gg
ss
vv
Description
----------------------------------------Subsystem name, padded on right by blanks
Global name
Separator string
Global value
——————————————————————————————————————————
367
——————————————————————————————————————————
——————————————————————————————————————————
For example, the following request displays information about the global variables whose
names start with the string 'DATE' in the subsystems whose names contain either the
string 'AB' or with the string 'CD'. The display is sorted by subsystem name and global
variable name; X'00' as the separator ensures this sort order.
BEGIN
%I FLOAT
%I2 FLOAT
%L FLOAT
%L2 FLOAT
%X FLOAT
%SEP STRING LEN 1
%S1 STRING LEN 255
%L = $LISTNEW
%SEP = $X2C('00')
%X = $SETG_SUBSYS_LIST(%L, %SEP, '*AB*')
* Append more globals to $list:
%X = $SETG_SUBSYS_LIST(%L, %SEP, '*CD*')
%L2 = $LISTSORT(%L, '1,10,A 11,255,A')
PRINT 'Subsystem Global' AND '/ Value' AT 33
%S1 = '----------'
PRINT %S1 AND %S1 WITH %S1 AND ' ' AND %S1 WITH %S1
FOR %X FROM 1 TO $LISTCNT(%L2)
%S1 = $LISTINF(%L2, %X, 11)
%I = $INDEX(%S1, %SEP)
IF %I EQ 0 THEN
%I = 256
END IF
%I2 = %I
IF %I LT 21 THEN
%S1 = $PADR($SUBSTR(%S1, 1, %I - 1), ' ', 20)
%I2 = 21
END IF
PRINT $LISTINF(%L2, %X, 1, 10) AND $SUBSTR(%S1, 1, %I2 - 1) AND '/' AND $LISTINF(%L2, %X, 11 + %I)
END FOR
END
●
●
Sirius Functions
Janus Web Server
Products authorizing $SETG_SUBSYS_LIST
——————————————————————————————————————————
368
——————————————————————————————————————————
$SETG_SYS: Set system-wide global
——————————————————————————————————————————
7.174
This function allows a user to set the value of a Model 204 “global variable” which has a
system-wide scope. These are used for the value of the $GETG function or dummy
string (“?&”) substitution. The order in which the different scopes of global variables are
searched can be controlled using $SIRPARM arguments: for $GETG, with 'GETGSYS',
and for dummy strings, with 'DUMMYSYS'.
The $SETG_SYS function accepts two arguments and returns zero, indicating success,
or a number indicating the cause of error, if there is one.
The first argument is the name of the global variable to be set. This is an optional
The second argument is the value to which the global variable is to be set. This is an
optional argument; it defaults to the null string.
System administrator privileges are required to invoke this $function.
%RC = $SETG_SYS(glob_name, value)
$SETG_SYS Function
0 - No errors
2 - Insufficient storage
$SETG_SYS return codes
This function can be used to set a global variable which is used for all Model 204 users.
The value can be set during Model 204 initialization (that is, in the CCAIN stream), so
values can be calculated once, rather than coding it in the login proc of all subsystems,
in which case it is calculated every time a user enters the subsystem, or rather than
using some kind of “setup” subsystem that every user is forced into at user login time.
For example, the following request can be run from CCAIN:
BEGIN
%X FLOAT
%X = $SETG_SYS('BOSS', 'Mr. Homer J. Simpson')
END
Then the global variable BOSS can be used to obtain the name of the latest boss.
Also, since there is one shared system global table for the entire system, a smaller
GTBL value for each user can be achieved than if the global values are set with user
global variables.
——————————————————————————————————————————
369
——————————————————————————————————————————
——————————————————————————————————————————
The order in which the different scopes of global variables are searched can be
controlled using $SIRPARM parameters: for $GETG, with 'GETGSYS', and for dummy
strings, with 'DUMMYSYS'. Here is an example to show the effects of DUMMYSYS and
GETGSYS; assume the following procedure is executed in the CCAIN input stream, and
that there are no $SETG_SUBSYS invocations for the global variable named 'JUNK':
BEGIN
%X FLOAT
%X = $SETG_SYS('JUNK', 'HELLO')
END
and the procedure TESTIT contains the following requests:
BEGIN
%Y = $SETG('JUNK', 'GOODBYE')
END
BEGIN
PRINT '?&JUNK'
PRINT $GETG('JUNK')
END
Then here are various command streams, and their results:
BEGIN
%X FLOAT
END
I TESTIT
GOODBYE
GOODBYE
BEGIN
%X FLOAT
END
I TESTIT
GOODBYE
HELLO
——————————————————————————————————————————
370
——————————————————————————————————————————
——————————————————————————————————————————
BEGIN
%X FLOAT
END
I TESTIT
HELLO
GOODBYE
BEGIN
%X FLOAT
END
I TESTIT
HELLO
HELLO
Retrieval of system global variables is highly efficient; updates, however, are not, so use
this $function appropriately.
The current values of system globals can be retrieved using $SETG_SYS_LIST.
For an explanation of $SIRPARM, see “$SIRPARM: Set user-specific value, controlling
Sirius products” on page 409.
●
●
Sirius Functions
Janus Web Server
Products authorizing $SETG_SYS
——————————————————————————————————————————
371
——————————————————————————————————————————
——————————————————————————————————————————
7.175
$SETG_SYS_LIST: Get list of system-wide
globals
This function returns names and values from the current set of system global variables.
It may be useful in debugging situations.
The $SETG_SYS_LIST function accepts three arguments and returns zero, indicating
The first argument identifies the $list to which items for the subsystem globals will be
added. This is a required argument.
The second argument is the string which is used to separate the global name from its
value in each item of the output $list. This is an optional argument; if omitted, or if the
null string is supplied, it defaults to a single byte with value X'00'. This separator value
(X'00') can be particularly useful for sorting the output $list; see
“$SETG_SUBSYS_LIST: Get list of subsystem-wide globals” on page 366 for an
example with sorting.
The third argument is a pattern string; all system global variables matching this pattern
are placed on the output $list. This is an optional argument; if omitted, all system global
variables are placed on the output $list.
%RC = $SETG_SYS_LIST(list_id, sep, glob_pat)
$SETG_SYS_LIST Function
0 - No errors
$SETG_SYS_LIST return codes
This function can be used for debugging, to retrieve values of selected system global
variables. The names global variables can be specified using the following wildcard
characters:
*
?
"
character.
——————————————————————————————————————————
372
——————————————————————————————————————————
$SETG_SYS_LIST: Get list of system-wide globals
——————————————————————————————————————————
The format of the items created by $SETG_SYS_LIST is as follows; ss is the length of
the separator string, gg is the length of the global name, vv is the length of the global
value:
Length
-----10
gg
ss
vv
Description
---------------Blanks
Global name
Separator string
Global value
For example, the following request displays information about the system global
variables whose names start with the string 'DATE' or with the string 'EXPIRE'. A single
slash character (“/”) is used to separate the global name from the global value. (This
example assumes that the combined length of the global name and value is less than
245.)
BEGIN
%L FLOAT
%X FLOAT
%L = $LISTNEW
%X = $SETG_SYS_LIST(%L, '/', 'DATE*')
* Append more globals to $list:
%X = $SETG_SYS_LIST(%L, '/', 'EXPIRE*')
FOR %X FROM 1 TO $LISTCNT(%L)
PRINT $LISTINF(%L, %X)
END FOR
END
●
●
Sirius Functions
Janus Web Server
Products authorizing $SETG_SYS_LIST
——————————————————————————————————————————
373
——————————————————————————————————————————
——————————————————————————————————————————
7.176
$SETSTAT: Set local system statistic
This function allows a user to set the current value of a local system statistic. There are
10 local system statistics that can be set via $SETSTAT. These stats can be examined
via $SYSTAT under the names LOCAL0 through LOCAL9.
The $SETSTAT function accepts two arguments and returns either the new value of the
appropriate local statistic or a 0 if there is an error.
The first argument is the local stat number to be set. This number must be 0 through 9
or the $SETSTAT performs no action and returns a 0.
The second argument is a number that indicates the value to which the local stat is to be
set. This is an optional argument and defaults to 0.
%VALUE = $SETSTAT(stat_num, value)
$SETSTAT Function
%VALUE is set to either 0 or value.
This function can be used to initialize a local statistic. For example, the code fragment
%VALUE = $SETSTAT(1)
initializes local stat number 1 to 0.
●
●
Sirius Functions
SirMon
Products authorizing $SETSTAT
——————————————————————————————————————————
374
——————————————————————————————————————————
$SIR_DATE: Get current datetime
——————————————————————————————————————————
7.177
$SIR_DATE: Get current datetime
This function accepts an optional datetime format string and an optional error control
string, and returns the current date and time as a character string with the specified
format.
%odate = $SIR_DATE(fmt, errctl)
$SIR_DATE Function
where
fmt
optional datetime format string, defaults to 'YY-MM-DD'. Refer to “Datetime
Formats” on page 529 for an explanation of valid datetime formats and valid
datetime values.
errctl
optional error control string, refer to “Datetime Error Handling” on page 541.
%odate
set to contain the current date and time, in the format specified by fmt.
For example, the following fragment prints a value such as Monday, 1 January
2001 AT 01:11:10 PM:
PRINT $SIR_DATE('Wkday, DAY Month YYYY' WITH ' "A"T HH:MI:SS AM')
Error conditions are shown in the following figure (see the discussion in “Datetime Error
Handling” on page 541).
$SIR_DATE returns the null string in the following error cases:
●
fmt is not a valid datetime format.
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
●
●
●
●
●
●
●
●
Products authorizing $SIR_DATE
——————————————————————————————————————————
375
——————————————————————————————————————————
——————————————————————————————————————————
7.178
$SIR_DATEFMT: Validate datetime format
The $SIR_DATEFMT function expects a datetime format string and returns the value 1 if
the datetime format is valid, else the value 0.
%tst = $SIR_DATEFMT(fmt)
$SIR_DATEFMT Function
where
fmt
datetime format string. Refer to “Datetime Formats” on page 529 for an
explanation of valid datetime format strings.
%tst
set to 1 if fmt is a valid datetime format string, otherwise set to 0.
For example, the following fragment prints the string Good:
%X = $SIR_DATEFMT('CYYDDDHHMISSXXX')
IF %X = 1 THEN
PRINT 'Good'
ELSE
PRINT 'Bad'
END IF
This $function has no error conditions.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATEFMT
——————————————————————————————————————————
376
——————————————————————————————————————————
$SIR_DATEN: Current date and time as number of seconds/300
——————————————————————————————————————————
7.179
$SIR_DATEN: Current date and time as number
of seconds/300
The $SIR_DATEN function has no arguments and returns the number of 1/300 second
units since 1 January, 1900.
%num = $SIR_DATEN
$SIR_DATEN Function
where
%num
set to the number of 1/300th seconds units from 1 Jan 1900 12:00 AM to the
current date and time.
For example, the following fragment will print the date and time 1.5 seconds from the
current time:
PRINT $SIR_N2DATE($SIR_DATEN + 450, 'MM/DD/YY HH:MI:SS.XX')
$SIR_DATEN has no error conditions.
Notes:
●
Values returned by $SIR_DATEN will exceed the range that can be represented in a
4-byte integer, so you should probably avoid storing the value in a BINARY or
FLOAT4 field.
●
To obtain the current date and time in a readable form, use $SIR_DATE.
●
To convert a datetime number to a readable form, use $SIR_N2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATEN
——————————————————————————————————————————
377
——————————————————————————————————————————
——————————————————————————————————————————
7.180
$SIR_DATEND: Current date as number of days
The $SIR_DATEND function has no arguments and returns the number of days since 1
January, 1900.
%num = $SIR_DATEND
$SIR_DATEND Function
where
%num
set to the number of days from 1 Jan 1900 to the current date.
For example, the following fragment will print the date one week from the current date:
PRINT $SIR_ND2DATE($SIR_DATEND + 7, 'Wkday DAY Month YYYY')
$SIR_DATEND has no error conditions.
Notes:
●
Values returned by $SIR_DATEND can be represented in a 4-byte BINARY field, if
you choose to do so.
●
●
To convert the number of days to a readable form, use $SIR_ND2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATEND
——————————————————————————————————————————
378
——————————————————————————————————————————
$SIR_DATENM: Current date and time as number of milliseconds
——————————————————————————————————————————
7.181
$SIR_DATENM: Current date and time as
number of milliseconds
The $SIR_DATENM function has no arguments and returns the number of 1/1000th
seconds since 1 January, 1900.
%num = $SIR_DATENM
$SIR_DATENM Function
where
%num
set to the number of 1/1000th seconds (milliseconds) from 1 Jan 1900 12:00
AM to the current date and time.
For example, the following fragment will print the date and time 1.8 seconds from the
current time:
PRINT $SIR_NM2DATE($SIR_DATENM + 1800, 'MM/DD/YY HH:MI:SS.XX')
$SIR_DATENM has no error conditions.
Notes:
●
Values returned by $SIR_DATENM will exceed the range that can be represented in
a 4-byte integer, so you should probably avoid storing the value in a BINARY or
FLOAT4 field.
●
●
To convert the number of milliseconds to a readable form, use $SIR_NM2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATENM
——————————————————————————————————————————
379
——————————————————————————————————————————
——————————————————————————————————————————
7.182
$SIR_DATENS: Current date and time as
number of seconds
The $SIR_DATENS function has no arguments and returns the number of seconds
since 1 January, 1900.
%num = $SIR_DATENS
$SIR_DATENS Function
where
%num
set to the number of seconds from 1 Jan 1900 12:00 AM to the current date
and time.
For example, the following fragment will print the date and time 1 minute from the current
time:
PRINT $SIR_NS2DATE($SIR_DATENS + 60, 'MM/DD/YY HH:MI:SS')
$SIR_DATENS has no error conditions.
Notes:
●
Values returned by $SIR_DATENS will exceed the range that can be represented in
a 4-byte integer, so you should probably avoid storing the value in a BINARY or
FLOAT4 field.
●
●
To convert the number of seconds to a readable form, use $SIR_NS2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATENS
——————————————————————————————————————————
380
——————————————————————————————————————————
$SIR_DATE2N: Convert datetime string to number of seconds/300
——————————————————————————————————————————
7.183
$SIR_DATE2N: Convert datetime string to
number of seconds/300
The $SIR_DATE2N function expects a datetime value string and a datetime format
string and returns the input datetime converted to the number of 1/300th seconds since
1 January, 1900. It accepts an optional CENTSPAN value and an optional error control
string. If an error is detected, the returned value is -9E12 (-9000000000000).
%num = $SIR_DATE2N(dat, fmt, span, errctl)
$SIR_DATE2N Function
where
dat
datetime value string.
fmt
datetime format string corresponding to dat. Refer to “Datetime Formats” on
page 529 for an explanation of valid datetime formats and valid dates. Nonstrict matching is used for input format fmt; see “Strict and non-strict format
matching” on page 536.
span
optional CENTSPAN value, default is -50. Refer to “CENTSPAN” on page
534.
errctl
%num
set to the value of dat, converted to the number of 1/300th second units from
1 Jan 1900 12:00 AM.
For example, the following fragment prints the value Before:
IF $SIR_DATE2N('121494', 'MMDDYY') <
$SIR_DATE2N('040195', 'MMDDYY') THEN
PRINT 'Before'
END IF
-
$SIR_DATE2N returns the value -9E12 (-9000000000000) in the following
cases:
●
●
●
●
dat does not match fmt.
dat is outside of range permitted for fmt.
span is invalid.
——————————————————————————————————————————
381
——————————————————————————————————————————
——————————————————————————————————————————
Notes:
●
Values returned by $SIR_DATE2N will often exceed the range that can be
represented in a 4-byte integer, so you should probably avoid storing the value in a
BINARY or FLOAT4 field.
●
Dates prior to 1 January 1900 will return a negative number.
●
The inverse of this $function is $SIR_N2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATE2N
——————————————————————————————————————————
382
——————————————————————————————————————————
$SIR_DATE2ND: Convert datetime string to number of days
——————————————————————————————————————————
7.184
$SIR_DATE2ND: Convert datetime string to
number of days
The $SIR_DATE2ND function expects a datetime value string and a datetime format
string and returns the input datetime converted to the number of days since 1 January,
1900. It accepts an optional CENTSPAN value and an optional error control string. If an
error is detected, the returned value is -9E12 (-9000000000000).
%num = $SIR_DATE2ND(dat, fmt, span, errctl)
$SIR_DATE2ND Function
where
dat
fmt
span
534.
errctl
%num
set to the value of dat, converted to the number of days from 1 Jan 1900
12:00 AM.
For example, the following fragment prints the value 12:
%A = $SIR_DATE2ND('010695', 'MMDDYY')
%B = $SIR_DATE2ND('122594', 'MMDDYY')
%C = %A - %B
PRINT %C
$SIR_DATE2ND returns the value -9E12 (-9000000000000) in the following
cases:
●
●
●
●
span is invalid.
——————————————————————————————————————————
383
——————————————————————————————————————————
——————————————————————————————————————————
Notes:
●
Values returned by $SIR_DATE2ND can be stored in a BINARY or FLOAT4 field, if
you wish.
●
●
The inverse of this $function is $SIR_ND2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATE2ND
——————————————————————————————————————————
384
——————————————————————————————————————————
$SIR_DATE2NM: Convert datetime string to number of milliseconds
——————————————————————————————————————————
7.185
$SIR_DATE2NM: Convert datetime string to
number of milliseconds
The $SIR_DATE2NM function expects a datetime value string and a datetime format
string and returns the input datetime converted to the number of milliseconds since 1
January, 1900. It accepts an optional CENTSPAN value and an optional error control
%num = $SIR_DATE2NM(dat, fmt, span, errctl)
$SIR_DATE2NM Function
where
dat
fmt
span
534.
errctl
%num
set to the value of dat, converted to the number of milliseconds from 1 Jan
1900 12:00 AM.
%A = $SIR_DATE2NM('010695', 'MMDDYY')
%B = $SIR_DATE2NM('010595', 'MMDDYY')
%C = %A - %B
PRINT %C
$SIR_DATE2NM returns the value -9E12 (-9000000000000) in the following
cases:
●
●
●
●
span is invalid.
——————————————————————————————————————————
385
——————————————————————————————————————————
——————————————————————————————————————————
Notes:
●
Values returned by $SIR_DATE2NM will often exceed the range that can be
●
●
The inverse of this $function is $SIR_NM2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATE2NM
——————————————————————————————————————————
386
——————————————————————————————————————————
$SIR_DATE2NS: Convert datetime string to number of seconds
——————————————————————————————————————————
7.186
$SIR_DATE2NS: Convert datetime string to
number of seconds
The $SIR_DATE2NS function expects a datetime value string and a datetime format
string and returns the input datetime converted to the number of seconds since 1
January, 1900. It accepts an optional CENTSPAN value and an optional error control
%num = $SIR_DATE2NS(dat, fmt, span, errctl)
$SIR_DATE2NS Function
where
dat
fmt
span
534.
errctl
%num
set to the value of dat, converted to the number of seconds from 1 Jan 1900
12:00 AM.
%A = $SIR_DATE2NS('010695', 'MMDDYY')
%B = $SIR_DATE2NS('010595', 'MMDDYY')
%C = %A - %B
PRINT %C
$SIR_DATE2NS returns the value -9E12 (-9000000000000) in the following
cases:
●
●
●
●
span is invalid.
——————————————————————————————————————————
387
——————————————————————————————————————————
——————————————————————————————————————————
Notes:
●
Values returned by $SIR_DATE2NS will often exceed the range that can be
●
●
The inverse of this $function is $SIR_NS2DATE.
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_DATE2NS
——————————————————————————————————————————
388
——————————————————————————————————————————
$SIR_DATExxx: Sir2000 User Language Tools $functions
——————————————————————————————————————————
7.187
$SIR_DATExxx: Sir2000 User Language Tools
$functions
There is a set of $functions which are only available with Sir2000 User Language Tools.
Their names begin with the characters “$SIR_DATE”, but note that there are also a
number of $functions with names of that form which are described in this manual, and
which are not restricted to the Sir2000 User Language Tools. The $functions which are
restricted to the Sir2000 User Language Tools are described in the Sir2000 User
Language Tools Reference Manual.
——————————————————————————————————————————
389
——————————————————————————————————————————
——————————————————————————————————————————
7.188
$SIR_ND2DATE: Convert datetime number of
days to string
The $SIR_ND2DATE function expects a numeric datetime argument containing a
number of days since January 1, 1900, and a datetime format string. It returns the date
represented by the first argument, in the format corresponding to the second argument.
$SIR_ND2DATE accepts an optional error control string and returns the null string if an
error is detected.
%dat = $SIR_ND2DATE(datn, fmt, errctl)
$SIR_ND2DATE Function
where
datn
datetime number containing a signed number of days since January 1, 1900.
fmt
explanation of valid datetime formats and valid datetime values.
errctl
%dat
set to the datetime value string, using format specified by fmt, corresponding
to datn, unless an error is detected.
For example, the following fragment prints the string 07/31/84:
%X = $SIR_DATE2ND('8407301230', 'YYMMDDHHMI')
* Add a day:
%X = %X + 1
PRINT $SIR_ND2DATE(%X, 'MM/DD/YY')
$SIR_ND2DATE returns a null string in the following cases:
●
●
datn out of range.
Notes:
The inverse of this $function is $SIR_DATE2ND.
——————————————————————————————————————————
390
——————————————————————————————————————————
$SIR_ND2DATE: Convert datetime number of days to string
——————————————————————————————————————————
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_ND2DATE
——————————————————————————————————————————
391
——————————————————————————————————————————
——————————————————————————————————————————
7.189
$SIR_NM2DATE: Convert datetime number of
milliseconds to string
The $SIR_NM2DATE function expects a numeric datetime argument containing a
number of milliseconds since January 1, 1900, and a datetime format string. It returns
the date represented by the first argument, in the format corresponding to the second
argument. $SIR_NM2DATE accepts an optional error control string and returns the null
string if an error is detected.
%dat = $SIR_NM2DATE(datn, fmt, errctl)
$SIR_NM2DATE Function
where
datn
datetime number containing a signed number of milliseconds since January
1, 1900.
fmt
errctl
%dat
%X = $SIR_DATE2NM('8407301230', 'YYMMDDHHMI')
* Add 15 hours:
%X = %X + 1000 * 60 * 60 * 15
PRINT $SIR_NM2DATE(%X, 'MM/DD/YY')
$SIR_NM2DATE returns a null string in the following cases:
●
●
datn out of range.
Notes:
The inverse of this $function is $SIR_DATE2NM.
——————————————————————————————————————————
392
——————————————————————————————————————————
$SIR_NM2DATE: Convert datetime number of milliseconds to string
——————————————————————————————————————————
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_NM2DATE
——————————————————————————————————————————
393
——————————————————————————————————————————
——————————————————————————————————————————
7.190
$SIR_NS2DATE: Convert datetime number of
seconds to string
The $SIR_NS2DATE function expects a numeric datetime argument containing a
number of seconds since January 1, 1900, and a datetime format string. It returns the
date represented by the first argument, in the format corresponding to the second
argument. $SIR_NS2DATE accepts an optional error control string and returns the null
string if an error is detected.
%dat = $SIR_NS2DATE(datn, fmt, errctl)
$SIR_NS2DATE Function
where
datn
datetime number containing a signed number of seconds since January 1,
1900.
fmt
errctl
%dat
%X = $SIR_DATE2NS('8407301230', 'YYMMDDHHMI')
* Add 15 hours:
%X = %X + 60 * 60 * 15
PRINT $SIR_NS2DATE(%X, 'MM/DD/YY')
$SIR_NS2DATE returns a null string in the following cases:
●
●
datn out of range.
Notes:
The inverse of this $function is $SIR_DATE2NS.
——————————————————————————————————————————
394
——————————————————————————————————————————
$SIR_NS2DATE: Convert datetime number of seconds to string
——————————————————————————————————————————
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_NS2DATE
——————————————————————————————————————————
395
——————————————————————————————————————————
——————————————————————————————————————————
7.191
$SIR_N2DATE: Convert datetime number of
seconds/300 to string
The $SIR_N2DATE function expects a numeric datetime argument containing a number
of seconds/300 since January 1, 1900, and a datetime format string. It returns the date
represented by the first argument, in the format corresponding to the second argument.
$SIR_N2DATE accepts an optional error control string and returns the null string if an
error is detected.
%dat = $SIR_N2DATE(datn, fmt, errctl)
$SIR_N2DATE Function
where
datn
datetime number containing a signed number of seconds/300 since January
1, 1900.
fmt
errctl
%dat
%X = $SIR_DATE2N('8407301230', 'YYMMDDHHMI')
* Add 15 hours:
%X = %X + 300 * 60 * 60 * 15
PRINT $SIR_N2DATE(%X, 'MM/DD/YY')
$SIR_N2DATE returns a null string in the following cases:
●
●
datn out of range.
Notes:
The inverse of this $function is $SIR_DATE2N.
——————————————————————————————————————————
396
——————————————————————————————————————————
$SIR_N2DATE: Convert datetime number of seconds/300 to string
——————————————————————————————————————————
●
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_N2DATE
——————————————————————————————————————————
397
——————————————————————————————————————————
——————————————————————————————————————————
7.192
$SIR_WILD: Test string against a wildcard string
$SIR_WILD indicates whether the one string matches a Sirius-style pattern where a “*”
matches any set of characters, a “?” matches any single character and a “"” indicates
that the following character is to be treated as a literal even if it is one of the three
special wildcard characters, that is “*”, “?” or “"”. $SIR_WILD takes two string arguments
and returns either a 0 or 1.
The first argument is the string to be tested for a match. This is an optional argument
and defaults to null.
The second argument is the string, possibly containing wildcards, against which the first
argument is to be tested. This is an optional argument and defaults to null.
%RC = $SIR_WILD(string, wildcard)
$SIR_WILD Function
%RC is set to 0 or 1.
$SIR_WILD returns either a 1 indicating that the first string matches the second or 0
otherwise. For example, this returns 1:
$SIR_WILD('Ahab', 'A*')
This returns 0:
$SIR_WILD('Starbuck', 'A*')
This returns 1:
$SIR_WILD('*LOOK', '"*LOO?')
$SIR_WILD is new in version 6.3 of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIR_WILD
——————————————————————————————————————————
398
——————————————————————————————————————————
$SIRFIELDxxx: Sir2000 Field Migration Facility $functions
——————————————————————————————————————————
7.193
$SIRFIELDxxx: Sir2000 Field Migration Facility
$functions
There is a set of $functions which are only available with Sir2000 Field Migration Facility.
Their names begin with the characters “$SIRFIELD” and they are described in the
Sir2000 Field Migration Facility Reference Manual.
——————————————————————————————————————————
399
——————————————————————————————————————————
——————————————————————————————————————————
7.194
$SIRJGET: Place audit trail data on $list
The $SIRJGET function is used to retrieve audit trail data from the current Model 204
journal stream and place it on a $list. $SIRJGET is only available if a site has purchased
SirScan. To invoke $SIRJGET, you must have either system manager or system
administrator privileges.
$SIRJGET accepts five arguments and returns a numeric code.
%RESULT = $SIRJGET(list_id, start_time, end_time,
user_list, parms)
$SIRJGET Function
list_id
The identifier of the $list that is to receive the formatted audit trail data.
The audit trail data is appended to the current contents of the indicated
$list. This is a required argument.
start_time
The start time for the journal data to be formatted in YYDDDHHMISSXX
format (YY = year, DDD = Julian day number, HH = hour, MI = minutes, SS
= seconds, XX = hundredths of seconds). This start time is inclusive, so
any audit trail entry matching the specified start time is considered to be in
the range. If start_time is not specified, the start time is considered to be
the time that the Model 204 region was brought up.
end_time
The end time for the journal data to be formatted in YYDDDHHMISSXX
format (YY = year, DDD = Julian day number, HH = hour, MI = minutes, SS
= seconds, XX = hundredths of seconds). This end time is exclusive, so
any audit trail entry matching the specified end time is considered to be out
of the range, and is not formatted. If end_time is not specified, the end
time is considered to be the current time.
user_list
Selection criteria for users for which audit trail data is to be formatted. The
selection criteria can be a set of blank or comma delimited “phrases,” each
made up of one or more “clauses” separated by the & symbol. Each clause
can contain one of the following criteria:
IODEVn
A number n indicating a specific IODEV type, as in
IODEV15, IODEV7, or IODEV11.
PST
Entries for all Model 204 Psuedo-SubTasks.
n1.n2.n3.n4
An IP address for a Janus thread, as in 198.242.244.97 or
150.209.8.51. The IP address can also be followed by a
slash ( / ) and a subnet mask, or by a hyphen (-) and a
number of bits in a subnet mask, as in
198.242.244.0/255.255.255.0 or 198.242.244.0-24. These
——————————————————————————————————————————
400
——————————————————————————————————————————
——————————————————————————————————————————
two subnetted IP addresses encompass the same set of IP
addresses.
JAN:sss
The name of a Janus port, possibly containing wildcards,
as in JAN:WEBPORT, JAN:WEB*, or JAN:???PORT.
xxx
A specific user number, as in 0, 233, or 1024.
xxx-yyy
A range of user numbers, as in 0-20 or 111-1000.
ssss
A string, possibly containing wildcards, that indicates a
specific userid, as in RASPUTIN, RAS*, ???PUTIN. For
users in the ADMIN_xxx SCLASSes, a userid of just an
asterisk (*) is special-cased to mean not only all logged on
users, but all threads, whether logged on or not.
Criteria can be mixed and matched using the & separator, which indicates
an “AND” operation, or using blanks or commas, which indicate an “OR”
operation. For example
IODEV15&LENIN 11-20
requests information for all IODEV 15 threads logged on as userid LENIN,
and requests all the information for user numbers 11 through 20.
TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST
requests information for all of the following:
●
All connections from IP address 198.242.244.33 that log on a userid
that begins with TROT
●
All connections to Janus port SOCIALIST that log on to userid MARX
●
All PSTs
Portnames and userids can contain special wildcard characters. These
characters and their meanings are:
*
Matches any number of characters. For example, BRE* matches
BREAD, BREEZY, and BREZHNEV.
?
Matches a single character. For example, ?RUSHCHEV matches
TRUSHCHEV, BRUSHCHEV, and KRUSHCHEV.
"
Means the next character is to be treated literally, even if it is wildcard
character. Using the double-quotation character is necessary if a
wildcard character appears in the name to be matched. For example,
E"*BARTER matches E*BARTER.
——————————————————————————————————————————
401
——————————————————————————————————————————
——————————————————————————————————————————
parms
A list of parameters indicating how the audit trail data is to be formatted.
This argument is a list of blank delimited keywords that come from the
following list :
AA
Non-stat audit entries are to be formatted. This
includes AD, CI, CP, CS, ER, LI, LP, LR, LS, MS, OI,
OO, RK, and US entries. For an explanation of the
meaning of these entries, see the Model 204 System
Manager's Guide. If AA is specified, it is redundant to
also specify any of these other types.
AD
AD type entries are to be formatted.
CI
CI type entries are to be formatted.
CP
CP type entries are to be formatted.
CS
CS type entries are to be formatted.
DATE
The date associated with each audit trail entry should
be included in the formatted output. The date is output
in YYMMDD format, where YY is year, MM is month,
and DD is day.
ER
ER type entries are to be formatted.
LI
LI type entries are to be formatted.
LP
LP type entries are to be formatted.
LR
LR type entries are to be formatted.
LS
LS type entries are to be formatted.
MAXIO=num
The maximum number of sequential full track I/O's to be
performed against the journal in this call. This
parameter can be used to prevent accidentally doing a
large number of I/O's on the journal.
The value for MAXIO must be between 1 (MAXIO=1)
and 10,000,000 (MAXIO=10000000). Its default value
is 100.
MAXREC=num
The maximum number of $list items to be allowed into
the output $list. This parameter can be used to prevent
accidentally using a large amount of CCATEMP to hold
the formatted output.
——————————————————————————————————————————
402
——————————————————————————————————————————
——————————————————————————————————————————
The value for MAXREC must be between 1
(MAXREC=1) and 10,000,000 (MAXREC=10000000).
Its default value is 1000.
MS
MS type entries are to be formatted.
NOSC
The SirScan RK lines produced for the SirScan
SCANTIME feature (to facilitate identification of journal
entries by userid or other criteria) are to be suppressed
from the output $list.
OI
OI type entries are to be formatted.
OO
OO type entries are to be formatted.
RK
RK type entries are to be formatted.
SEQ
Each output $list item is to contain an eight-byte
sequence number at the start. The SEQ parameter is
followed by the starting sequence number and an an
increment separated by a comma, as in SEQ=100,5,
which means that the starting sequence number is 100,
and the sequence numbers increment by 5.
Note that the starting sequence number never actually
appears, because the first $list item causes it to be
incremented. In the previous example, the first added
$list item would actually be 105.
The starting sequence number can be omitted, in which
case it is assumed to be 0, so SEQ=,1 causes
sequence numbers to start at one and go up by one.
The sequence numbers are always eight bytes long and
padded on the left with zeros. If the sequence number
exceeds 99999999, the leading decimal digits are
simply discarded.
SERV
The server number of each audit trail entry is to be
included in the formatted output.
ST
Statistics entries are to be formatted.
TIME
The time associated with each audit trail entry is
included in the formatted output. Time is output in
HHMMSSTH format, where HH is hour, MM is minute,
SS is second, T is tenths of a second, and H is
hundredths of a second.
——————————————————————————————————————————
403
——————————————————————————————————————————
——————————————————————————————————————————
TYPE
The type of each audit trail entry is to be included in the
formatted output. Type will be AD, CI, CP, CS, ER, LI,
LP, LR, LS, MS, OI, OO, RK, or US for audit entries,
and it will be ST for statistics entries.
US
US type entries are to be formatted.
Prior to Sirius Mods version 6.7, blanks at the start of a
line are deleted, and long user entries are split into a
US line and one or more XX lines. As of version 6.7,
initial blanks are not removed, and long entries are a
single US line with continuation lines that have no prefix
and no label.
0
1
2
3
4
6
7
8
9
10
-
USER
The user number of each audit trail entry is to be
included in the formatted output.
USESC
Use the RK lines produced for the SirScan SCANTIME
feature (to facilitate identification of journal entries by
userid or other criteria). This ensures that all journal
records can be definitely identified with a userid, IP
address, or Janus port. The cost of this completeness
is that an extra SCANTIME seconds of the journal need
to be scanned before the start time. Unless SCANTIME
is set to an inadvisedly high value, the cost of this
should be minor.
WIDTH=num
The maximum width for the output $list items. If an
audit trail entry will not fit in a single $list item of this
width, it is continued in the next $list item. The
allowable range for width is 50 (WIDTH=50) through
255 (WIDTH=255).
No errors
MAXREC exceeded ($list might contain new records)
MAXIO exceeded ($list might contain new records)
CCATEMP full (if LISTFC $SIRPARM parameter not set)
Out of virtual storage
$List identifier missing
Invalid parameter (argument 5)
Invalid start or end time (argument 2 or 3)
No audit trail types selected (ST, AA, AD, etc..)
$SIRJGET return codes
——————————————————————————————————————————
404
——————————————————————————————————————————
——————————————————————————————————————————
The following statement formats all non-stat audit trail entries for IODEV3's between 10
AM and 2 PM on March 12, 1993:
%RC = $SIRJGET(%LIST, '9306310000000', '9306314000000', 'IODEV3', 'AA')
●
SirScan
Products authorizing $SIRJGET
——————————————————————————————————————————
405
——————————————————————————————————————————
——————————————————————————————————————————
7.195
$SIRMSG: Line of current $SIRMSGP procedure
The $SIRMSG function is used to retrieve a line from the current $SIRMSG procedure
as set by $SIRMSGP.
$SIRMSG accepts one required argument, and it returns a string.
The argument is the number of the line within the current $SIRMSG procedure to be
returned. A zero returns the name of the current $SIRMSG procedure.
If there is no current $SIRMSG procedure or the requested line number is invalid
(negative or greater than the number of lines in the $SIRMSG procedure), $SIRMSG
returns a null string.
%MSG = $SIRMSG (line_num)
$SIRMSG Function
%MSG is set to the contents of line_num in the current $SIRMSG procedure.
$SIRMSGP and $SIRMSG allow a programmer to use a Model 204 procedure as a
message repository. Each line of the procedure corresponds to a message that can be
requested by line number with $SIRMSG. The advantages of using $SIRMSG are:
●
●
●
No server space is wasted holding infrequently used error messages.
The virtual storage holding the messages can be shared among users.
It simplifies sharing common messages among procedures in a subsystem or
online.
Suppose the current $SIRMSG procedure as set by $SIRMSGP contains these lines:
MSG0001 Invalid PF key.
MSG0002 Record not found.
MSG0003 Invalid data in input field.
The following statement would print: MSG0002 Record not found.
PRINT $SIRMSG(2)
The following statement would print a null string:
PRINT $SIRMSG(4)
●
No authorizers for $function
Products authorizing $SIRMSG
——————————————————————————————————————————
406
——————————————————————————————————————————
$SIRMSGP: Load procedure for retrieval via $SIRMSG
——————————————————————————————————————————
7.196
$SIRMSGP: Load procedure for retrieval via
$SIRMSG
The $SIRMSGP function is used to load a procedure into virtual storage for use as the
current $SIRMSG procedure.
$SIRMSGP accepts two arguments and returns a numeric code. As of Sirius Mods
version 6.8, it is a callable $function (“CALLing Sirius Mods functions” on page 32).
The first argument is required and identifies the User Language procedure to be made
the current $SIRMSG procedure.
The second argument is an optional file name. If the second argument is not provided,
or is a null string, the current file is used.
%RESULT = $SIRMSGP(proc_name, file_name)
$SIRMSGP Function
0 - Procedure set as current $SIRMSG procedure
1 - Procedure is locked for edit or delete
2 - Procedure does not exist or the current user does not
have access privilege
3 - Specified procedure name is invalid (null)
4 - Either file name invalid, or no current file, or
caller does not have sufficient privilege to
display/include procedures
7 - There is insufficient virtual storage to load the
procedure
$SIRMSGP return codes
$SIRMSGP and $SIRMSG allow a programmer to use a Model 204 procedure as a
message repository. Each line of the procedure corresponds to a message that can be
requested by line number with $SIRMSG.
The advantages of using $SIRMSG are:
●
●
●
No server space is wasted holding infrequently used error messages.
The virtual storage holding the messages is shared among users.
It simplifies sharing common messages among procedures in a subsystem or
online.
If $SIRMSGP determines that another thread has the same procedure as its current
$SIRMSG procedure then that thread's virtual storage copy is shared. $SIRMSGP
considers another thread to be using the same $SIRMSG procedure if the procedure
name, file name and contents of the procedure are identical to the one being set.
——————————————————————————————————————————
407
——————————————————————————————————————————
——————————————————————————————————————————
If not released explicitly, the virtual storage occupied by a $SIRMSG procedure will not
be released until user logoff or restart. To release the virtual storage used by a
$SIRMSG procedure without setting a new one, simply invoke $SIRMSGP with a null
procedure name. For example
%RC = $SIRMSGP('')
would clear the current $SIRMSG procedure and set %RC to 3.
●
No authorizers for $function
Products authorizing $SIRMSGP
——————————————————————————————————————————
408
——————————————————————————————————————————
$SIRPARM: Set user-specific value, controlling Sirius products
——————————————————————————————————————————
7.197
$SIRPARM: Set user-specific value, controlling
Sirius products
This $function allows setting of parameters that affect the User Language environment,
much like the RESET command.
The $SIRPARM function accepts one to two arguments and returns a numeric result.
The first argument is the name of the parameter to be set or whose value is to be
returned.
The second argument is the new value of the parameter. If this argument is omitted, the
value of the parameter is not changed.
All parameters updated by $SIRPARM are user values that are reset to their defaults
when a user logs off. Once the value of any parameter is changed, it remains at the new
value until explicitly changed via the $SIRPARM function or until the user logs off or is
restarted at which point the parameter if set back to its default value.
There are 4 types of parameters Flags
These parameters have value either 0 or 1. Specifying a new value other
than 0 results in these parameters being set to 1.
One byte
These parameters have values from 0 to 255. Specifying a value outside
this range results in the value being unchanged.
Halfword
These parameters have values from -32,767 to 32,767. Specifying a value
outside this range results in the value being unchanged.
Fullword
These parameters have values from -(2**31 - 1) to 2**31 - 1. Specifying a
value outside this range results in the value being unchanged.
%RESULT = $SIRPARM(parm_name, new_value)
$SIRPARM Function
%RESULT is set to the value of the parameter, which is either new_value or the
current parameter value if new_value is not specified.
The following parameters can be changed with $SIRPARM :
DUMMYSYS
This is a flag that controls the order of access by dummy string
substitution (“?&”) to the various scopes (user, subsystem, and system)
of global variables. The order corresponding to the 0 and 1 values of
DUMMYSYS are:
0
first, user globals (those set by $SETG);
if not there, subsystem globals (those set by $SETG_SUBSYS);
——————————————————————————————————————————
409
——————————————————————————————————————————
——————————————————————————————————————————
otherwise, system globals (those set by $SETG_SYS)
1
first, subsystem globals (those set by $SETG_SUBSYS);
if not there, system globals (those set by $SETG_SYS);
otherwise, user globals (those set by $SETG)
For examples of the effects of DUMMYSYS, see “$SETG_SUBSYS:
Set subsystem-wide global” on page 362 and “$SETG_SYS: Set
system-wide global” on page 369.
This flag is new in version 5.5 of the Sirius Mods.
EDITMSG
This is a flag that allows suppression of certain messages issued by the
Model 204 editor. When this flag is set to 0 (the default) all Model 204
editor messages are issued to the terminal as they usually are. If this
flag is set to 1, the message M204.0525 WARNING CAN'T EDIT INTO
PROCEDURE, is suppressed when editing a read-only procedure. In
addition, the message M204.0542 EDIT COMPLETE - .. is suppressed
and the command issued to leave the Model 204 editor (QUIT, END,
GO) is placed into the global variable SIR.EDIT.MSG.
GETGSYS
This is a flag that controls the order of access by the $GETG function to
the various scopes (user, subsystem, and system) of global variables.
The order corresponding to the 0 and 1 values of GETGSYS are:
0
first, user globals (those set by $SETG);
if not there, subsystem globals (those set by $SETG_SUBSYS);
otherwise, system globals (those set by $SETG_SYS)
1
first, subsystem globals (those set by $SETG_SUBSYS);
if not there, system globals (those set by $SETG_SYS);
otherwise, user globals (those set by $SETG)
For examples of the effects of GETGSYS, see “$SETG_SUBSYS: Set
subsystem-wide global” on page 362 and “$SETG_SYS: Set systemwide global” on page 369.
This flag is new in version 5.5 of the Sirius Mods.
LISTFC
This is a flag that controls the action to be taken by the Sirius Functions
when they are unable to add an item to a $list, either because
CCATEMP is full or because the architectural limit of what will fit in a
$list has been reached. If the LISTFC flag is set to 0 (the original
setting) the $function that is unable to add the list item returns an error
code (normally 3 or -3). If the LISTFC flag is set to 1, this condition
results in request cancellation and drives the APSY error proc if in a
subsystem.
——————————————————————————————————————————
410
——————————————————————————————————————————
$SIRPARM: Set user-specific value, controlling Sirius products
——————————————————————————————————————————
Setting the LISTFC flag to 1 simplifies the use of $lists. Applications
need not constantly check result codes from $list functions and instead
can let an error proc deal with the problem. When the LISTFC flag is set
and a $list function is unable to add an item to a list, the message
M204.0441 CCATEMP FULL is issued and is also set as the last error
message. Note that with the LISTFC flag set it is possible to get this
message even when CCATEMP is not really full when a user reaches
the architectural limit on the size of $lists.
See also “$RESETN: Reset or view M204 parameter” on page 344.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIRPARM
——————————————————————————————————————————
411
——————————————————————————————————————————
——————————————————————————————————————————
7.198
$SIRPROD: Determine availability of Sirius
product or capability
The $SIRPROD function checks to see if a particular Sirius product or capability is
available.
$SIRPROD accepts one argument and returns 1 if the argument is the code of a Sirius
product or capability which is available in the current Model 204, and 0 otherwise.
The argument is a number corresponding to the following products and capabilities:
1: Base User Language Functions
2: Fast/Reload
3: Fast/Reload FLOD Compiler
4: Fast/Backup
5: Fast/Unload Functions
6: Janus Base
7: Janus Open Server
8: Janus Open Client
9: Japanese Functions
10: SirScan
11: Trusted Login
12: Janus Specialty Data Store
13: Performance Enhancements
14: Janus Web Server
15: Janus Network Security
16: Sir2000 User Language Tools
17: Sir2000 Field Migration Facility
18: SirPro
19: SirFile
20: SirMon
21: SirXref
22: SirLib
23: SirDBA
24: Sirius Functions
25: SIRMSG Functions
26: Monitor Functions
27: Procedure Functions
28: Library Functions
29: Performance Enhancements V2
30: SirSafe
31: SirFact
32: Janus Sockets
33: Performance Enhancements V3
34: $SIR_LOGIN facility
35: Janus SOAP
36: Fast/Forward
37: Limited Janus Web Server
——————————————————————————————————————————
412
——————————————————————————————————————————
$SIRPROD: Determine availability of Sirius product or capability
——————————————————————————————————————————
37: Reserved
39: Janus Debugger
39: SirTune Data Collector
41: Sirius Debugger
%AVAIL = $SIRPROD(product_code)
$SIRPROD Function
%AVAIL is set to a non-zero number if the Sirius product or capability is
available, or to 0 if it is not available.
This function can be used to ensure that a product is available. For example, the
following program would stop if the Fast/Unload User Language Interface were not
available:
IF $SIRPROD(5) = 0 THEN
PRINT 'Fast/Unload is not available'
STOP
END IF
Note: Prior to version 6.1, $SIRMOD always returned a value of 1 if the product or
capability was available, but starting with version 6.1 it may return other non-zero values.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIRPROD
——————————————————————————————————————————
413
——————————————————————————————————————————
——————————————————————————————————————————
7.199
$SIRSITE: Current Sirius customer site ID
The $SIRSITE function returns the current Sirius customer site ID.
$SIRSITE accepts no arguments and returns a string which is the current Sirius
customer site ID.
%SITE = $SIRSITE
$SIRSITE Function
%SITE is set to the current Sirius customer site ID.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIRSITE
——————————————————————————————————————————
414
——————————————————————————————————————————
$SIRTIME: Current time as YYDDDHHMISSXX
——————————————————————————————————————————
7.200
$SIRTIME: Current time as YYDDDHHMISSXX
The $SIRTIME function returns the current time in YYDDDHHMISSXX format. This
function is especially useful in conjunction with $SIRJGET.
$SIRTIME accepts no arguments and returns a string.
%TIME = $SIRTIME
$SIRTIME Function
%TIME is set to the current time in YYDDDHHMISSXX format.
Notes:
●
See the documentation of $SIR_DATE for obtaining the current time in any format.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIRTIME
——————————————————————————————————————————
415
——————————————————————————————————————————
——————————————————————————————————————————
7.201
$SIRVER: Current version number of Sirius
product
This function returns the current version number of a particular Sirius product.
The $SIRVER function accepts one argument and returns a numeric result that is the
current version number of the requested product.
The argument is a string corresponding to one of the following products:
●
SIRMODS: Sirius Mods
●
FUNLOAD: Fast/Unload (accessed via the Fast/Unload User Language Interface)
%VER = $SIRVER(product)
$SIRVER Function
%VER is set to the current product version number.
This function can be used to ensure that you are running the correct version of the Sirius
Mods or of Fast/Unload. For example, the program
IF $SIRVER < 203 THEN
PRINT 'OBSOLETE SIRIUS FUNCTIONS'
STOP
END IF
would stop if the Sirius Mods were older than release 2.03.
The default product is SIRMODS, that is, if the argument is missing or is the null string,
the version number of the Sirius Mods is returned. If the argument is invalid, 0 is
returned. If the argument is FUNLOAD, and the Fast/Unload User Language Interface is
not available, 0 is returned.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SIRVER
——————————————————————————————————————————
416
——————————————————————————————————————————
$SIRWARN: Send warning or message to user(s)
——————————————————————————————————————————
7.202
$SIRWARN: Send warning or message to
user(s)
The $SIRWARN function is used to send a warning or message to the specified user or
users. If the user invoking $SIRWARN is a system manager or system administrator,
$SIRWARN acts like a WARN command; otherwise it acts like an MSG command.
$SIRWARN accepts two arguments and returns a number.
The first argument identifies the user(s) to receive the warning. If this argument is the
string OPR, the warning is sent to the operator's console (or virtual console under CMS).
If this argument is a valid user number, the warning is sent to the indicated user number.
If the first argument is neither OPR nor a valid user number, it is treated as a userid, and
the warning is sent to every user logged on to this userid.
The second argument is the text of the warning to be sent to the user(s) indicated by the
first argument.
%RC = $SIRWARN (user, message)
$SIRWARN Function
%RC is set to indicate the success of the function.
0
1
2
3
-
Warning issued
User(s) not logged on
Insufficient storage
Parameter missing (either userid or message)
$SIRWARN return codes
The following statement sends a warning of an application error to the operator:
%RC = $SIRWARN('OPR', 'Severe application error for user' WITH $USER)
This statement sends a warning to user 57 to leave subsystem BARNEY:
%RC = $SIRWARN(57, 'Please leave subsystem BARNEY')
This statement sends a warning to all users logged on as HOMER to call Marge:
%RC = $SIRWARN('HOMER', 'Please call Marge')
——————————————————————————————————————————
417
——————————————————————————————————————————
——————————————————————————————————————————
●
Sirius Functions
Products authorizing $SIRWARN
——————————————————————————————————————————
418
——————————————————————————————————————————
$SOCK_xxx: Janus Sockets $functions
——————————————————————————————————————————
7.203
$SOCK_xxx: Janus Sockets $functions
There is a set of $functions that is only available with Janus Sockets. The function
names begin with the characters “$SOCK_”, and they are described in the Janus
Sockets Reference Manual.
——————————————————————————————————————————
419
——————————————————————————————————————————
——————————————————————————————————————————
7.204
$SRV_xxx: Janus Open Server $functions
There is a set of $functions which are only available with Janus Open Server. Their
names begin with the characters “$SRV_,” and they are described in the Janus Open
Server Reference Manual.
——————————————————————————————————————————
420
——————————————————————————————————————————
$SSSTAT: Retrieve subsystem's statistics into string
——————————————————————————————————————————
7.205
$SSSTAT: Retrieve subsystem's statistics into
string
This function allows retrieval of a specific subsystem's statistics into a string.
The $SSSTAT function accepts two arguments and returns a string made up of an error
The first argument is a string of blank delimited words indicating the statistics to be
facilitates the use of $STATD with the returned string. For more information about
available statistics, see the SirMon User's Guide.
The second argument is the subsystem name for which data is to be returned.
%STRING = $SSSTAT(stat_list, subsystem_name)
$SSSTAT Function
If the error code is negative, %STRING will only be 4 bytes long.
The data returned by $SSSTAT is binary; the first four bytes contain a return code. If the
return code is negative, only four bytes are returned. If the return code is positive, it
convenient number for calculating rates for the statistics. With a positive return code,
the next ten bytes contain the blank padded file name, followed by two bytes containing
the binary file number. This means that the actual data starts at offset 16 (byte number
17) in the result string.
-12 - Invalid parameter (argument 2 > NUSERS,
or invalid name in stat_list)
-14 - Result string would be longer than 255 bytes
-15 - Subsystem not active
$SSSTAT return codes
The following program displays some totals for subsystem SIRMON.
——————————————————————————————————————————
421
——————————————————————————————————————————
——————————————————————————————————————————
B
%DATA = $SSSTAT('NUSER RESEVAL RESSWCH', 'SIRMON')
PRINT '$SSSTAT ERROR... RC = ' WITH $UNBIN(%DATA)
STOP
END IF
PRINT 'SUBSYSNAME = ' WITH $SUBSTR(%DATA, 5, 10)
PRINT 'NUSER
PRINT 'RESEVAL
PRINT 'RESSWCH
END
●
Sirius Functions
Products authorizing $SSSTAT
——————————————————————————————————————————
422
——————————————————————————————————————————
$SSSTATL: Retrieve statistics for set of subsystems into $list
——————————————————————————————————————————
7.206
$SSSTATL: Retrieve statistics for set of
subsystems into $list
This function allows retrieval of statistics for a set of subsystems into a $list.
The $SSSTATL function accepts three arguments and returns a numeric error code.
Byte 1-10
Blank padded subsystem name
Byte 11-12
Always 0
Byte 13-
Returned statistics
The second argument is a string of blank delimited words indicating the statistics to be
facilitates the use of $STATLD with the returned $list. For more information about
The third argument is a selection criterion that indicates which files are to be included in
the output $list. The following criteria are allowed:
FILE=filename
include only subsystems that have opened file filename.
SUBSYS=subsysid
include only subsystems with names matching subsysid
(wildcards allowed).
In actual fact, all files are always included in the output list, but the excluded subsystems
have the high order bit of byte 11 turned on. This tells $STATLD to exclude the
subsystems from the difference $list.
%RESULT = $SSSTATL(list_identifier, stat_list, criterion)
$SSSTATL Function
%RESULT is either a positive number (milliseconds since the online was
brought up) or a negative error code.
——————————————————————————————————————————
423
——————————————————————————————————————————
——————————————————————————————————————————
-12 - Invalid name in stat_list
$SSSTATL return codes
The following program displays some statistics for all subsystems.
b
%data is
%list1 =
%list2 =
%list3 =
string len 255
$listnew
$listnew
$listnew
%time1 = $USStatl(%list1, 'IODEV CPU')
Pause 1
%time2 = $USStatL(%list2, 'IODEV CPU','SUBSYS=SIRMON')
%rc = $StatLD(%list1, %list2, %list3, 'N N', %time2 - %time1)
For %i from 1 to $listCnt(%list3)
%data = $listInf(%list3, %i)
Text
userid = { $substr(%data,1,10) } usernum = { $unbin($substr(%data,11,2)) } iodev = { $unbin($substr(%data,13,4)) } cpu total = { $unbin($substr(%data,17,4)) }
End Text
End For
End
●
Sirius Functions
Products authorizing $SSSTATL
——————————————————————————————————————————
424
——————————————————————————————————————————
$STATD: Calculate differences and rates for statistics strings
——————————————————————————————————————————
7.207
$STATD: Calculate differences and rates for
statistics strings
This function allows calculation of differences and rates for statistics strings. These
statistics strings must be in a format identical to strings produced by $FISTAT,
$SYSTAT, $TKSTAT, $SSSTAT and $USSTAT.
The $STATD function accepts four arguments and returns a string made up of an error
The first argument is a string containing an EBCDIC identifier in bytes 1-10, a binary
number in bytes 11-12 and data in bytes 13 to the end of the string.
The second argument is a string containing an EBCDIC identifier in bytes 1-10, a binary
number in bytes 11-12 and data in bytes 13 to the end of the string. For differences to
be calculated, bytes 1-12 must match bytes 1-12 of the first argument.
The third argument is a control string containing blank delimited tokens describing the
action to be performed for each 4 byte chunk of the input strings. The available actions
are
●
'N' - stands for number. Simply copy 4 bytes from argument 2.
●
'D' - stands for difference. Calculate binary difference between 4 bytes in argument
2 and argument 1.
●
'R' - stands for rate. Calculate binary difference between 4 bytes in argument 2 and
argument 1, multiply by 1,000,000 and then divide by argument 4. Argument 4 is
required if an R is included in the control string.
The fourth argument is a number to be used as a divisor in calculating rates. This is an
optional argument but is required if there is an 'R' in the control string (argument 3). This
would ordinarily be the elapsed time between calculation of the first argument and the
second.
%STRING = $STATD(stat_string1, stat_string2, ctl_string, divisor)
$STATD Function
If the error code is negative %STRING will only be 4 bytes long.
The data returned by $STATD is binary with the first 4 bytes containing an error code. If
the error code is negative, only 4 bytes are returned. If the differences were successfully
calculated, the first 4 bytes are set to binary 0. When a zero error code is returned the
next 12 bytes contain a copy of the first 12 bytes of argument 1 and 2. This means that
the actual data starts at offset 16 (byte number 17) in the result string.
——————————————————————————————————————————
425
——————————————————————————————————————————
——————————————————————————————————————————
-5
-12
-13
-14
-15
-
Invalid control string
Invalid rate divisor
Invalid length input string
First 12 bytes don't match in input
$STATD return codes
The following program displays system CPU as a rate and difference over a one second
interval and as a total over the whole run.
B
%DATA1 IS STRING LEN 255
%DATA2 IS STRING LEN 255
%DATA1 = $SUBSTR( $SYSTAT('CPU CPU CPU'), 5)
PAUSE 1
%DATA1 = $SUBSTR( $SYSTAT('CPU CPU CPU'), 5)
%DATA = $STATD( %DATA1, %DATA2, 'R D N')
PRINT 'CPU
$UNBIN(
PRINT 'CPU
$UNBIN(
PRINT 'CPU
$UNBIN(
RATE
= '
$SUBSTR(%DATA,
DIFFERENCE = '
$SUBSTR(%DATA,
TOTAL
= '
$SUBSTR(%DATA,
WITH 17, 4) )
WITH 21, 4) )
WITH 25, 4) )
END
●
SirMon
Products authorizing $STATD
——————————————————————————————————————————
426
——————————————————————————————————————————
$STATLD: Calculate differences and rates for statistics $lists
——————————————————————————————————————————
7.208
$STATLD: Calculate differences and rates for
statistics $lists
This function allows calculation of differences and rates for statistics $lists. These
statistics $lists must be in a format identical to $lists produced by $CFSTATL,
$FISTATL, $TKSTATL, $SSSTATL and $USSTATL.
The $STATLD function accepts five arguments and returns a numeric error code.
The first argument is the identifier of a $list where each item contains an EBCDIC
identifier in bytes 1-10, a binary number in bytes 11-12 and data in bytes 13 to the end of
the $list item.
The second argument is the identifier of a $list where each item contains an EBCDIC
identifier in bytes 1-10, a binary number in bytes 11-12 and data in bytes 13 to the end of
the $list item.
The third argument is the identifier of an output $list. The contents of this $list are
deleted and replaced by the differences between the argument 1 $list and the argument
2 $list.
The fourth argument is a control string containing blank delimited tokens describing the
action to be performed for each 4 byte chunk of the input $list items. The available
actions are
●
'N' - stands for number. Simply copy 4 bytes from argument 2.
●
'D' - stands for difference. Calculate binary difference between 4 bytes in argument
2 and argument 1.
●
'R' - stands for rate. Calculate binary difference between 4 bytes in argument 2 and
argument 1, multiply by 1,000,000 and then divide by argument 4. The fifth
argument is required if an R is included in the control string.
The fifth argument is a number to be used as a divisor in calculating rates. This is an
optional argument but is required if there is an 'R' in the control string (argument 4). This
would ordinarily be the elapsed time between calculation of the first argument and the
second.
%RESULT = $STATLD(list1_id, list2_id, list3_id, action_list, divisor)
$STATLD Function
%RESULT is either 0 or a negative error code.
The data returned into the output $list by $STATLD is binary with the first 12 bytes
matching the first 12 bytes of an item in the second $list that matches one in the first list.
——————————————————————————————————————————
427
——————————————————————————————————————————
——————————————————————————————————————————
Any item in the second $list that has the high order bit of byte 11 on (set to flag exclusion
by a selection criterion on $FISTATL, $TKSTATL, $SSSTATL or $USSTATL) is
excluded from the new $list. The actual difference data starts at offset 12 (byte number
13) in the result $list items.
-3 - CCATEMP is full
-12 - Invalid control string
-13 - Invalid rate divisor
-14 - Invalid length $list item
$STATLD return codes
The following program displays every user's CPU usage as a rate over one second
interval and as a total over the whole run.
Begin
%i
%list1
%list2
%list3
%time1
%time2
%rc
%data
is
is
is
is
is
is
is
is
float
float
float
float
float
float
float
string len 255
%list1 = $listnew
%list2 = $listnew
%list3 = $listnew
Pause 1
%time2 = $USStatL(%list2, 'IODEV CPU')
Text
userid = { $substr(%data,1,10) }
usernum = { $unbin($substr(%data,11,2)) } iodev = { $unbin($substr(%data,13,4)) }
cpu total = { $unbin($substr(%data,17,4)) }
end Text
End For
End
——————————————————————————————————————————
428
——————————————————————————————————————————
$STATLD: Calculate differences and rates for statistics $lists
——————————————————————————————————————————
●
SirMon
Products authorizing $STATLD
——————————————————————————————————————————
429
——————————————————————————————————————————
——————————————————————————————————————————
7.209
$STR: Treat a longstring as string
This function takes a longstring input and produces a string output, silently truncating the
result at 255 bytes or shorter if the target is shorter.
The $STR function accepts one argument and returns a string result that is the first
argument truncated at the $function target's length.
%STR = $STR(longstring)
$STR Function
%STR is up to the first 255 bytes of longstring.
For example, if %LINCOLN was a LONGSTRING %variable containing the text of the
Gettysburg Address and %AGE was a STRING LEN 20
%AGE = $STR(%LINCOLN)
would result in %AGE containing “Four score and seven”.
The main utility of the $STR function is to prevent the request cancellation that would
result from a direct assignment from a LONGSTRING value to a STRING %variable that
is too small to hold the entire value. While the input to $STR could be a regular STRING
this doesn't really make much sense since a regular STRING can be assigned to a
regular STRING without request cancellation for truncation, anyway. A $STR would
upgrade a WITH expression that's its argument to a LONGSTRING WITH expression
but this is again rather silly as the result would then simply be truncated at 255 bytes
should it exceed 255 bytes. $STR also makes sense as a quick shorthand for the first
255 bytes of a LONGSTRING, even if the target is a LONGSTRING.
$STR is only available in Sirius Mods version 6.2 and later.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $STR
——————————————————————————————————————————
430
——————————————————————————————————————————
$STRAND: Bit-wise AND two strings
——————————————————————————————————————————
7.210
$STRAND: Bit-wise AND two strings
This function performs a bit-wise AND of two strings.
The $STRAND function accepts three arguments and returns a string result that is the
bit-wise AND of the first two arguments, the shorter being padded with as many copies
of the third argument as are required to make the string lengths equal.
The second argument is another arbitrary string.
The third argument is another arbitrary string that is appended to the shorter of the first
two strings and replicated as many times as required to make the strings of equal length.
If this value is not specified or is null it defaults to a single null byte (X'00').
%STR = $STRAND(string1, string2, pad)
$STRAND Function
%STR is the bit-wise AND of string1 and string2.
For example
%X = $X2C('112233445566')
%Y = $X2C('654321')
%JUNK = $STRAND(%X, %Y)
would set %JUNK to X'010221000000' and
%X = $X2C('112233445566')
%JUNK = $STRAND(%X, , $X2C('CC'))
%X = $X2C('112233445566')
%Y = $X2C('1122')
%Z = $X2C('FF00')
%JUNK = $STRAND(%X, %Y, %Z)
would set %JUNK to X'112233005500'.
$STRAND is only available in Sirius Mods version 6.2 and later.
——————————————————————————————————————————
431
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $STRAND
——————————————————————————————————————————
432
——————————————————————————————————————————
$STROR: Bit-wise OR two strings
——————————————————————————————————————————
7.211
$STROR: Bit-wise OR two strings
This function performs a bit-wise OR of two strings.
The $STROR function accepts three arguments and returns a string result that is the bitwise OR of the first two arguments, the shorter being padded with as many copies of the
third argument as are required to make the string lengths equal.
%STR = $STROR(string1, string2, pad)
$STROR Function
%STR is the bit-wise OR of string1 and string2.
For example
%X = $X2C('112233445566')
%Y = $X2C('654321')
%JUNK = $STROR(%X, %Y)
%X = $X2C('112233445566')
%JUNK = $STROR(%X, , $X2C('CC'))
would set %JUNK to X'DDEEFFCCDDEE' and
%X = $X2C('112233445566')
%Y = $X2C('1122')
%Z = $X2C('FF00')
%JUNK = $STROR(%X, %Y, %Z)
would set %JUNK to X'1122FF44FF66'.
$STROR is only available in Sirius Mods version 6.2 and later.
——————————————————————————————————————————
433
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $STROR
——————————————————————————————————————————
434
——————————————————————————————————————————
$STRXOR: Bit-wise exclusive OR two strings
——————————————————————————————————————————
7.212
$STRXOR: Bit-wise exclusive OR two strings
This function performs a bit-wise exclusive OR of two strings.
The $STRXOR function accepts three arguments and returns a string result that is the
bit-wise exclusive OR of the first two arguments, the shorter being padded with as many
copies of the third argument as are required to make the string lengths equal.
%STR = $STRXOR(string1, string2, pad)
$STRXOR Function
%STR is the bit-wise exclusive OR of string1 and string2.
For example
%X = $X2C('112233445566')
%Y = $X2C('654321')
%JUNK = $STRXOR(%X, %Y)
%X = $X2C('112233445566')
%JUNK = $STRXOR(%X, , $X2C('CC'))
would set %JUNK to X'DDEEFF8899AA' and
%X = $X2C('112233445566')
%Y = $X2C('1122')
%Z = $X2C('FF00')
%JUNK = $STRXOR(%X, %Y, %Z)
would set %JUNK to X'0000CC44AA66'.
$STRXOR is only available in Sirius Mods version 6.2 and later.
——————————————————————————————————————————
435
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $STRXOR
——————————————————————————————————————————
436
——————————————————————————————————————————
$SUBCNT: Count occurrences of one string in another
——————————————————————————————————————————
7.213
$SUBCNT: Count occurrences of one string in
another
This function counts the occurrences of one string in another.
The $SUBCNT function accepts two arguments and returns a numeric result that is the
count of occurrences of the second argument string in the first argument string.
%COUNT = $SUBCNT(string, substring)
$SUBCNT Function
%COUNT is the count of occurrences of substring in string.
For example
%JUNK = $SUBCNT('ABCDABAB', 'AB')
would set %JUNK to 3 and
%JUNK = $SUBCNT('WE HAVE WAITED LONG ENOUGH', 'WEHAVE')
would set %JUNK to 0 and
%JUNK = $SUBCNT('WE HAVE WAITED LONG ENOUGH', 'E')
would set %JUNK to 4.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SUBCNT
——————————————————————————————————————————
437
——————————————————————————————————————————
——————————————————————————————————————————
7.214
$SUBERS: Remove occurrence of one string
from another
This function removes an occurrence of one string from another.
The $SUBERS function accepts four arguments and returns a string result that is part of
The third argument is a starting position in the first argument string.
The fourth argument is a repeat count indicating the number of occurrences to be
removed. This is an optional argument and defaults to 1.
%STRING = $SUBERS(string, substring, start_pos, count)
$SUBERS Function
For example, this statement sets %JUNK to CDABAB:
%JUNK = $SUBERS('ABCDABAB', 'AB')
This statement sets %JUNK to WE WAITED LONG ENOUGH:
%JUNK = $SUBERS('WE HAVE WAITED LONG ENOUGH', 'HAVE ')
This statement sets %JUNK to WE HAVE AITED LONG ENOUGH:
%JUNK = $SUBERS('WE HAVE WAITED LONG ENOUGH', 'W', 5)
This statement sets %JUNK to E HAVE AITED LONG ENOUGH:
%JUNK = $SUBERS('WE HAVE WAITED LONG ENOUGH', 'W', 1, 5)
——————————————————————————————————————————
438
——————————————————————————————————————————
$SUBERS: Remove occurrence of one string from another
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SUBERS
——————————————————————————————————————————
439
——————————————————————————————————————————
——————————————————————————————————————————
7.215
$SUBINS: Insert string inside another string
This function inserts a string inside another.
The $SUBINS function accepts three arguments and returns a string result.
The third argument is an insertion position in the first argument string.
%STRING = $SUBINS(string, ins_string, insert_pos)
$SUBINS Function
%STRING is a string made up of string and ins_string.
If no insertion position is provided, the insertion string is appended to the end of the first
input string. If the insertion point is past the first input string, the first input string is left
unmodified.
For example, this statement sets %JUNK to PAT STAMPER, TRADER HORSE:
%JUNK = $SUBINS('PAT STAMPER, TRADER', ' HORSE')
This statement sets %JUNK to PAT STAMPER, HORSE TRADER:
%JUNK = $SUBINS('PAT STAMPER, TRADER', ' HORSE', 12)
This statement sets %JUNK to PAT STAMPER, TRADER:
%JUNK = $SUBINS('PAT STAMPER, TRADER', ' HORSE', 92)
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SUBINS
——————————————————————————————————————————
440
——————————————————————————————————————————
$SUBREP: Replace occurrences of string
——————————————————————————————————————————
7.216
$SUBREP: Replace occurrences of string
This function replaces occurrences of a substring in one string with another.
The $SUBREP function accepts five arguments and returns a string result that is part of
The second argument is an arbitrary string located in argument 1.
The third argument is a replacement string.
The fourth argument is a starting position in the first argument string. This is an optional
argument and defaults to 1.
The fifth argument is a repeat count indicating the number of occurrences to be
replaced. This is an optional argument, and it defaults to 1.
%STRING = $SUBREP(string, substring, repstring, start_pos, count)
$SUBREP Function
For example, this statement sets %JUNK to XYCDABAB:
%JUNK = $SUBREP('ABCDABAB', 'AB', 'XY')
This statement sets %JUNK to XYCDXYXY:
%JUNK = $SUBREP('ABCDABAB', 'AB', 'XY', ,5)
This statement sets %JUNK to ABCDXYXY.
%JUNK = $SUBREP('ABCDABAB', 'AB', 'XY', 3 ,5)
If the substitution would cause the result value to exceed 255 characters, it is not
performed.
——————————————————————————————————————————
441
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $SUBREP
——————————————————————————————————————————
442
——————————————————————————————————————————
$SYSTAT: Retrieve system statistics into string
——————————————————————————————————————————
7.217
$SYSTAT: Retrieve system statistics into string
This function allows retrieval of system statistics into a string.
The $SYSTAT function accepts one argument and returns a string made up of an error
%STRING = $SYSTAT(stat_list)
$SYSTAT Function
The data returned by $SYSTAT is binary with the first 4 bytes containing an error code.
If the error code is negative, only 4 bytes are returned. If the error code is positive, it
contains a number of milliseconds since the online region was brought up. This provides
a convenient number for calculating rates for the statistics. When a positive error code
is returned the next 10 bytes contain the blank padded word 'SYSTEM' followed by 2
bytes of binary 0. This means that the actual data starts at offset 16 (byte number 17) in
the result string.
-5
-12
-13
-14
-
STAT not linked in
Result string would be longer than 255 bytes
$SYSTAT return codes
——————————————————————————————————————————
443
——————————————————————————————————————————
——————————————————————————————————————————
The following program displays some totals for system statistics.
B
%DATA = $SYSTAT('CPU DKIO SVIO')
PRINT '$SYSTAT ERROR... RC = ' WITH $UNBIN(%DATA)
STOP
END IF
PRINT 'CPU
PRINT 'DKIO
PRINT 'SVIO
END
●
Sirius Functions
Products authorizing $SYSTAT
——————————————————————————————————————————
444
——————————————————————————————————————————
$TABLEC: Information provided by TABLEC command
——————————————————————————————————————————
7.218
$TABLEC: Information provided by TABLEC
command
This function allows retrieval of the information provided in the TABLEC command from
a User Language program.
The $TABLEC function accepts two arguments and returns a number indicating the
The first argument, which is required, is a string identifying an image to receive returned
data. This image should have the following format :
IMAGE TABLEC_IMAGE
FILE_NAME
IS STRING LEN 8
SLOTS_TOTAL IS BINARY LEN 4
SLOTS_USED IS BINARY LEN 4
SLOTS_PCT
IS BINARY LEN 4
FOLLOWING FIELDS SET TO ZERO FOR PRE-8.1 FILES
PROP_COUNT IS BINARY LEN 4
PAGE_SPILL IS BINARY LEN 4
PROP_OVFL
IS BINARY LEN 4
PROP_SPCT
IS BINARY LEN 4
END IMAGE
The second argument is the name of the file on which the $TABLEC function should
operate. If this argument is not specified the default file at compilation time is used by
$TABLEC.
[%RESULT =] $TABLEC(image_name, file)
$TABLEC Function
%RESULT is a 0 or an error code.
See the Model 204 File Manager's Guide for more information on the data returned by
$TABLEC.
0
4
8
12
16
-
Image filled with Table C information
File invalid
File not open
Image specified by argument 1 not found
Image specified by argument 1 not active or too short
$TABLEC return codes
The following program prints the percentage of slots used in table C of file ROSA.
——————————————————————————————————————————
445
——————————————————————————————————————————
——————————————————————————————————————————
B
IMAGE JUNK
FILE_NAME IS STRING LEN 8
...
END IMAGE
PREPARE IMAGE JUNK
%RC = $TABLEC('JUNK', 'ROSA')
IF %RC ¬= 0 THEN
STOP
END IF
PRINT %JUNK:SLOTS_PCT
END
●
Sirius Functions
Products authorizing $TABLEC
——————————————————————————————————————————
446
——————————————————————————————————————————
$TERMID: Terminal ID of current user thread
——————————————————————————————————————————
7.219
$TERMID: Terminal ID of current user thread
This function returns the terminal id of the current user thread.
The $TERMID function accepts no arguments and returns either an 8 byte string
containing the terminal id or a null string indicating that a terminal id is not available.
%TERM = $TERMID
$TERMID Function
%TERMID is set to either a null or 8-byte string.
The following program displays the user's terminal id.
B
PRINT $TERMID
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $TERMID
——————————————————————————————————————————
447
——————————————————————————————————————————
——————————————————————————————————————————
7.220
$TKSTAT: Retrieve task's statistics into string
This function allows retrieval of a specific task's statistics into a string.
The $TKSTAT function accepts two argument and returns a string made up of an error
The second argument is the task number of the task for which data is to be returned.
The maintask is always task number 0. Other tasks are only available for onlines
running the MP/204 feature.
%STRING = $TKSTAT(stat_list, task_num)
$TKSTAT Function
The data returned by $TKSTAT is binary with the first 4 bytes containing an error code.
contains a number of milliseconds since the online region was brought up. This provides
a convenient number for calculating rates for the statistics. When a positive error code
is returned the next 10 bytes contain blanks followed by 2 bytes of binary 0. This means
that the actual data starts at offset 16 (byte number 17) in the result string.
-5
-12
-13
-14
-
Invalid parameter (argument 2 > NMPSUBS)
STAT not linked in
$TKSTAT return codes
——————————————————————————————————————————
448
——————————————————————————————————————————
$TKSTAT: Retrieve task's statistics into string
——————————————————————————————————————————
The following program displays some totals for subtask 1.
B
%DATA = $TKSTAT('CPU STDEQ LKWAIT', 1)
PRINT '$TKSTAT ERROR... RC = ' WITH $UNBIN(%DATA)
STOP
END IF
PRINT 'CPU
PRINT 'STDEQ = ' WITH $UNBIN( $SUBSTR(%DATA, 21, 4) )
PRINT 'LKWAIT = ' WITH $UNBIN( $SUBSTR(%DATA, 25, 4) )
END
●
Sirius Functions
Products authorizing $TKSTAT
——————————————————————————————————————————
449
——————————————————————————————————————————
——————————————————————————————————————————
7.221
$TKSTATL: Retrieve statistics for all tasks into
$list
This function allows retrieval of statistics for all tasks into a $list.
The $TKSTATL function accepts two argument and returns a numeric error code.
Byte 1-10
Blanks
Byte 11-12
Binary task number
Byte 13-
Returned statistics
%RESULT = $TKSTATL(list_identifier, stat_list, criterion)
$TKSTATL Function
%RESULT is a either a positive number, which is the milliseconds since the
online was brought up, or is a negative error code.
$TKSTATL return codes
——————————————————————————————————————————
450
——————————————————————————————————————————
$TKSTATL: Retrieve statistics for all tasks into $list
——————————————————————————————————————————
The following program displays some statistics for all tasks:
B
%LIST = $LISTNEW
%DATA = $TKSTATL(%LIST, 'CPU STDEQ LKWAIT')
IF %DATA < 0 THEN
PRINT '$TKSTATL ERROR... RC = ' WITH %DATA
STOP
END IF
PRINT 'TASKNUM = ' WITH $UNBIN(
PRINT 'CPU
= ' WITH $UNBIN(
PRINT 'STDEQ
= ' WITH $UNBIN(
PRINT 'LKWAIT
= ' WITH $UNBIN(
PRINT
END FOR
$SUBSTR(%DATA,
$SUBSTR(%DATA,
$SUBSTR(%DATA,
$SUBSTR(%DATA,
11,
13,
17,
21,
2)
4)
4)
4)
)
)
)
)
END
●
Sirius Functions
Products authorizing $TKSTATL
——————————————————————————————————————————
451
——————————————————————————————————————————
——————————————————————————————————————————
7.222
$TSOATT: Attach program in user's TSO
address space
This function invokes a program in the user's TSO address space. $TSOATT performs
an "asynchronous" call to the program. That is, control is returned from $TSOATT as
soon as the program is invoked in the TSO address space. The program continues to
run while other processing can take place in the online address space.
Note: This function requires the special version of the TSO full screen interface to
Model 204 that is distributed by Sirius Software. See “TSO $Functions” on page 505.
The $TSOATT function accepts five arguments and returns a numeric completion code
or task id.
The first argument is a string containing the name of the program to be invoked in the
TSO address space. This is an optional argument; and if it is null or missing, no
processing is performed and a completion code of 0 is returned.
The second argument is a string containing the path name for the program to be invoked
in the TSO address space. This is an optional argument.
The third argument is a string containing the parameters to be passed to the invoked
CLIST. This is an optional argument.
The fourth argument is a string containing the name of an image containing input data
for the invoked CLIST. This is an optional argument.
The fifth argument is string containing the name of an image to receive output data from
the invoked CLIST. This is an optional argument.
%RESULT = $TSOATT(clist, path, parms, in_image, out_image )
$TSOATT Function
%RESULT is set either to the created task ID or to an error code.
$TSOATT normally returns a positive task id from the invoked program. If there is some
error that prevents the program from being invoked, however, a negative error code is
returned to indicate the problem.
-1
-4
-8
-16
-20
-28
-
Connection broken
Not a TSO full screen IODEV (IODEV 11)
Incorrect version of TSO interface
Image not found
LOUTPB too small
Program name is too long
$TSOATT return codes
——————————————————————————————————————————
452
——————————————————————————————————————————
$TSOATT: Attach program in user's TSO address space
——————————————————————————————————————————
The following program invokes a program called 'COMPRESS' in the user's TSO
address space with a parameter of 'DSN(JUNK.CNTL)'.
B
%RC = $TSOATT( 'COMPRESS', , 'DSN(JUNK.CNTL)')
END
●
Japanese Functions
Products authorizing $TSOATT
——————————————————————————————————————————
453
——————————————————————————————————————————
——————————————————————————————————————————
7.223
$TSOCALL: Call program in user's TSO address
space
This function invokes a program in the user's TSO address space. $TSOCALL performs
a "synchronous" call to the program. That is, control is not returned from $TSOCALL
until the invoked program terminates.
The $TSOCALL function accepts five arguments and returns a numeric completion
code.
The first argument is a string containing the name of the program to be invoked in the
The second argument is a string containing the path name for the program to be invoked
in the TSO address space. This is an optional argument.
The third argument is a string containing the parameters to be passed to the invoked
program. This is an optional argument.
The fourth argument is a string containing the name of an image containing input data
for the invoked program. This is an optional argument.
The fifth argument is string containing the name of an image to receive output data from
the invoked program. This is an optional argument.
%RESULT = $TSOCALL(clist, path, parms, in_image, out_image)
$TSOCALL Function
%RESULT is set either to the completion code from the invoked program or to
an error code.
$TSOCALL normally returns the completion code from the invoked program. If there is
some error that prevents the program from being invoked, however, an error code is
0
-1
-4
-8
-16
-20
-28
-
No program name specified
Connection broken
Image not found
LOUTPB too small
Program name is too long
$TSOCALL return codes
——————————————————————————————————————————
454
——————————————————————————————————————————
$TSOCALL: Call program in user's TSO address space
——————————————————————————————————————————
The following program invokes a program called 'DELETE' in the user's TSO address
space with a parameter of 'DSN(TEMP.SAS.DATA)'.
B
%RC = $TSOEXEC( 'DELETE', , 'DSN(TEMP.SAS.DATA)')
END
●
Japanese Functions
Products authorizing $TSOCALL
——————————————————————————————————————————
455
——————————————————————————————————————————
——————————————————————————————————————————
7.224
$TSOCAN: Cancel program invoked via
$TSOATT
This function cancels a specific task running a program invoked via $TSOATT or all such
tasks initiated by the current user.
The $TSOCAN function accepts one argument and returns a numeric status code or
count.
The first argument is a number that is the task id of the "task" for which status is
requested. This is an optional argument and if omitted indicates that you want all tasks
to be cancelled.
%RESULT = $TSOCAN(task_id)
$TSOCAN Function
%RESULT is set either to the status code for the cancelled task or to an error
code.
$TSOCAN normally returns the status code of the cancelled task. If there is some error
that prevents the task from being cancelled, however, a negative error code is returned
to indicate the problem.
-1
-4
-8
-20
-
Connection broken
LOUTPB too small
$TSOCAN return codes
address space with a parameter of 'DSN(JUNK.CNTL)', issues a FIND while
'COMPRESS' is running, and then cancels the 'COMPRESS' command if it is still
running.
——————————————————————————————————————————
456
——————————————————————————————————————————
$TSOCAN: Cancel program invoked via $TSOATT
——————————————————————————————————————————
B
%TASKID = $TSOATT( 'COMPRESS', , 'DSN(JUNK.CNTL)')
FIND1: IN BIGFILE FIND ALL RECORDS FOR WHICH
NAME IS LIKE 'SM*'
END FIND
%RC = $TSOCAN( %TASKID )
...
END
●
Japanese Functions
Products authorizing $TSOCAN
——————————————————————————————————————————
457
——————————————————————————————————————————
——————————————————————————————————————————
7.225
$TSOCMD: Invoke command in user's TSO
address space
This function invokes a command in the user's TSO address space.
The $TSOCMD function accepts two arguments and returns a numeric completion code.
The first argument is a string containing the name of the command to be invoked in the
The second argument is a string containing the parameters to be passed to the invoked
command. This is an optional argument.
%RESULT = $TSOCMD(clist, parms)
$TSOCMD Function
%RESULT is set either to the completion code from the invoked command or to
an error code.
$TSOCMD normally returns the completion code from the invoked command. If there is
some error that prevents the command from being invoked, however, an error code is
0
-1
-4
-8
-20
-28
-
No command name specified
Connection broken
LOUTPB too small
Command name is too long
$TSOCMD return codes
The following program invokes a command called ALLOCATE in the user's TSO address
space with a parameter of DSN('M204.DATA') NEW TRACKS SPACE(15,10).
B
%RC = $TSOCMD( 'ALLOCATE', 'DSN(''M204.DATA'') NEW TRACKS SPACE(15,10)')
END
——————————————————————————————————————————
458
——————————————————————————————————————————
$TSOCMD: Invoke command in user's TSO address space
——————————————————————————————————————————
●
Japanese Functions
Products authorizing $TSOCMD
——————————————————————————————————————————
459
——————————————————————————————————————————
——————————————————————————————————————————
7.226
$TSOEXEC: Invoke CLIST in user's TSO address
space
This function invokes a CLIST in the user's TSO address space.
The $TSOEXEC function accepts four arguments and returns a numeric completion
code.
The first argument is a string containing the name of the CLIST to be invoked in the TSO
address space. This is an optional argument; and if it is null or missing, no processing is
performed and a completion code of 0 is returned.
The second argument is a string containing the parameters to be passed to the invoked
CLIST. This is an optional argument.
The third argument is a string containing the name of an image containing input data for
the invoked CLIST. This is an optional argument.
The fourth argument is a string containing the name of an image to receive output data
from the invoked CLIST. This is an optional argument.
%RESULT = $TSOEXEC(clist, parms, in_image, out_image)
$TSOEXEC Function
%RESULT is set either to the completion code from the invoked CLIST or to an
error code.
$TSOEXEC normally returns the completion code from the invoked CLIST. If there is
some error that prevents the CLIST from being invoked, however, an error code is
0
-1
-4
-8
-16
-20
-28
-
No CLIST name specified
Connection broken
Image not found
LOUTPB too small
CLIST name is too long
$TSOEXEC return codes
——————————————————————————————————————————
460
——————————————————————————————————————————
$TSOEXEC: Invoke CLIST in user's TSO address space
——————————————————————————————————————————
The following program invokes a CLIST called RUNSAS in the user's TSO address space
with a parameter of INDSN(TEMP.SAS.DATA).
B
%RC = $TSOEXEC( 'RUNSAS', 'INDSN(TEMP.SAS.DATA)')
END
●
Japanese Functions
Products authorizing $TSOEXEC
——————————————————————————————————————————
461
——————————————————————————————————————————
——————————————————————————————————————————
7.227
$TSOEXIT: Terminate TSO full screen interface
session, stack command
This function requests that the TSO full screen interface terminate the session and
optionally stacks a command to be executed upon termination.
The $TSOEXIT function accepts one argument and returns a numeric completion code.
The first argument is a string containing the name of the command to be invoked in the
command is stacked.
%RESULT = $TSOEXIT(command)
$TSOEXIT Function
%RESULT is set to a completion code.
0
-1
-4
-8
-20
-
Function successful
Connection broken
LOUTPB too small
$TSOEXIT return codes
The following program requests the TSO full screen interface to terminate its session
with Model 204 and then issue the 'LOGOFF' command in the TSO address space.
B
%RC = $TSOEXIT( 'LOGOFF' )
END
●
Japanese Functions
Products authorizing $TSOEXIT
——————————————————————————————————————————
462
——————————————————————————————————————————
$TSOID: TSO userid user's thread
——————————————————————————————————————————
7.228
$TSOID: TSO userid user's thread
This function returns the TSO userid of the current user thread.
The $TSOID function accepts no arguments and returns either an 8 byte string
containing the TSO userid of the Model 204 user or a null string indicating that the user
is not a TSO user or that the Sirius Software TSO Interface has not been installed.
%TERM = $TSOID
$TSOID Function
%TSOID is set to either a null or 8-byte string.
The following program displays the user's TSO userid.
B
PRINT $TSOID
END
●
Japanese Functions
Products authorizing $TSOID
——————————————————————————————————————————
463
——————————————————————————————————————————
——————————————————————————————————————————
7.229
$TSOSTAT: Status of program invoked via
$TSOATT
This function returns the status of a task running a program invoked via $TSOATT or
returns the number of such programs currently active.
The $TSOSTAT function accepts one argument and returns a numeric status code or
count.
The first argument is a number that is the task id of the "task" for which status is
requested. This is an optional argument and if omitted indicates that you want the count
of currently active TSO tasks.
%RESULT = $TSOSTAT(task_id)
$TSOSTAT Function
%RESULT is set to the status code for the task, a count of running tasks, or an
error code.
$TSOSTAT normally returns the status code of an invoked program or a count of
currently active tasks. If there is some error that prevents the status from being
returned, however, a negative error code is returned to indicate the problem.
-1
-4
-8
-20
-
Connection broken
LOUTPB too small
$TSOSTAT return codes
'COMPRESS' is running and then checks the status of the 'COMPRESS' command.
——————————————————————————————————————————
464
——————————————————————————————————————————
$TSOSTAT: Status of program invoked via $TSOATT
——————————————————————————————————————————
B
NAME IS LIKE 'SM*'
END FIND
IF $TSOSTAT( %TASKID ) NE 0 THEN
...
END
●
Japanese Functions
Products authorizing $TSOSTAT
——————————————————————————————————————————
465
——————————————————————————————————————————
——————————————————————————————————————————
7.230
$TSOWAIT: Wait for program invoked via
$TSOATT to complete
This function waits for a program invoked via $TSOATT to complete.
The $TSOWAIT function accepts two arguments and returns a numeric completion code
or task id.
The first argument is a number that is the task id of the "task" to be waited on. This task
id is returned by $TSOATT at program invocation time.
The second argument is string containing the name of an image to receive output data
from the invoked program. This is an optional argument.
%RESULT = $TSOWAIT( task_id, out_image )
$TSOWAIT Function
%RESULT is set either to the completion code from the invoked program or to
an error code.
$TSOWAIT normally returns the completion code from the invoked program. If there is
some error that prevents the program from being invoked, however, a negative error
code is returned to indicate the problem.
-1
-4
-8
-16
-20
-
Connection broken
Image not found
LOUTPB too small
$TSOWAIT return codes
'COMPRESS' is running and then waits for the 'COMPRESS' command to complete.
——————————————————————————————————————————
466
——————————————————————————————————————————
$TSOWAIT: Wait for program invoked via $TSOATT to complete
——————————————————————————————————————————
B
NAME IS LIKE 'SM*'
END FIND
%RC = $TSOWAIT( %TASKID )
...
END
●
Japanese Functions
Products authorizing $TSOWAIT
——————————————————————————————————————————
467
——————————————————————————————————————————
——————————————————————————————————————————
7.231
$UNBIND and $UNBINDW: Unbind resource
previously bound via $BIND
The $UNBIND and $UNBINDW functions unbind resources previously bound with the
$BIND function.
$UNBIND and $UNBINDW accept one argument and return a numeric code.
The only argument is the name of the resource to be unbound. This resource name can
be any string up to 255 bytes long.
%RESULT = $UNBIND(res_name)
$UNBIND Function
0 - Resource successfully unbound
1 - Resource name missing
2 - User does not have resource bound
$UNBIND return codes
%RESULT = $UNBINDW(res_name)
$UNBINDW Function
%RESULT is set to indicate the number of unbound semaphores.
N - The number of unbound semaphores
$UNBINDW return codes
A resource remains bound until it is either explicitly unbound with the $UNBIND or
$UNBINDW function or the binding user logs off or is restarted.
The following program unbinds the resource called ‘SMITHERS’.
B
%RC = $UNBIND( 'SMITHERS' )
END
The semaphore name specified as the argument to $UNBINDW can be an explicit name
or it can contain the following wildcard characters:
*
?
——————————————————————————————————————————
468
——————————————————————————————————————————
$UNBIND and $UNBINDW: Unbind resource previously bound via $BIND
——————————————————————————————————————————
"
Indicates that the next character must be treated literally, even if it is a wildcard
character.
For example:
This string ...
Matches ...
C*D
CUSTID or COD or CLOD
S??T
SALT or SLOT or SORT
E"*CONCRETE
E*CONCRETE
The following program unbinds the all resource that begin with the letters ‘SMITH’.
B
%RC = $UNBINDW( 'SMITH*' )
END
$UNBINDW is only available in version 6.1 and later of the Sirius Mods.
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $UNBIND and $UNBINDW
——————————————————————————————————————————
469
——————————————————————————————————————————
——————————————————————————————————————————
7.232
$UNSPACE: Normalize spaces and quotes
This function normalizes a string by removing leading and trailing “space” characters and
collapsing other sequences of “unquoted” spaces to single spaces. Normalization can
also “undouble” quoted quote characters.
The $UNSPACE function accepts three arguments and returns a string result which is
the first argument, normalized according to the description of the returned value, as
shown below.
The first argument is the string to be normalized.
The second argument is a string which is the set of space characters. The first
character of this string is the replacement space character. The default set of space
characters is the blank character.
The third argument is a string which is the set of quote characters. If a quote character
occurs twice in succession in argument 3, this indicates that the quote character should
be “undoubled” when it occurs within a string quoted by that same character. No quote
character may occur as a space character. The default is that there are no quote
characters.
The returned value is the string value of argument 1, normalized as follows:
●
Leading space characters are removed. If there is not an unmatched quote, trailing
space characters are removed.
●
Within a quoted substring, spaces are not collapsed nor replaced. If the quote
character introducing the substring is specified as two occurrences in argument 3,
each pair of consecutive occurrences of that character in the substring is replaced
by a single occurrence of that character.
If a quote character is not matched, the rest of the input is quoted.
●
Outside quoted substrings, each sequence of length one or more of any mixture of
space characters is replaced by a single occurrence of the replacement space
character.
%OUT = $UNSPACE(input, spaces, quotes)
$UNSPACE Function
%OUT is set to the normalized value of input.
Several examples follow, each one showing an invocation of $UNSPACE and the
corresponding result.
——————————————————————————————————————————
470
——————————————————————————————————————————
$UNSPACE: Normalize spaces and quotes
——————————————————————————————————————————
With only one argument, $UNSPACE simply removes leading and trailing blank
sequences and collapses other blank sequences:
$UNSPACE(' A
-> A B C
B
C
')
$UNSPACE can be used to make all space characters the same; here the space
characters include the letters “X” and “S” and the blank character; they are all replaced
by the letter “X”:
$UNSPACE(' ASSSBSSXC
-> AXBXC
', 'XS ')
Within a quoted substring, spaces are not changed:
$UNSPACE('."XAX"XBX', '.X', '"')
-> "XAX".B
An unmatched quote (which is therefore, by definition, a trailing unmatched quote),
causes the remander of the string to be quoted:
$UNSPACE('".A..."..B...C.."..', '.', '"')
-> ".A...".B.C."..
Doubling a quote character in argument 3 causes undoubling of quotes within a string
quoted by that character:
$UNSPACE('" "" "', , '""')
-> " " "
The following two inputs produce the same output; the first is a null quoted substring
followed by the letter A and a final unmatched quote; the second is a quoted string
whose first pair of characters is a doubled quote:
$UNSPACE('""A"', , '""')
-> ""A"
$UNSPACE('"""A"', , '""')
-> ""A"
If a quote character is not doubled in argument 3, undoubling for it is not performed:
$UNSPACE('" "" "', , '"')
-> " "" "
Multiple quote characters can be specified; a quote character inside a substring quoted
by a different character is not undoubled:
$UNSPACE('./A$$B/..$C//D$../E//F.', '.', '$$//')
-> /A$$B/.$C//D$./E/F.
——————————————————————————————————————————
471
——————————————————————————————————————————
——————————————————————————————————————————
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $UNSPACE
——————————————————————————————————————————
472
——————————————————————————————————————————
$USEASA: Prevent carriage control in USE output
——————————————————————————————————————————
7.233
$USEASA: Prevent carriage control in USE
output
This function fools Model 204 into not placing carriage control characters in USE dataset
output.
The $USEASA function accepts no arguments and returns 0 if successful or an error
code.
%RESULT = $USEASA
$USEASA Function
%RESULT is set to the return code.
0 - Successful
4 - Dataset does not use control characters
8 - No USE dataset active
$USEASA return codes
For example, this code fragment prevents M204 from inserting carriage control
characters:
%X
●
●
●
●
●
●
●
●
= $USEASA
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $USEASA
——————————————————————————————————————————
473
——————————————————————————————————————————
——————————————————————————————————————————
7.234
$USSTAT: Retrieve user's statistics into string
This function allows retrieval of a specific user's statistics into a string.
The $USSTAT function accepts two argument and returns a string made up of an error
The second argument is the user number of the user for which data is to be returned.
%STRING = $USSTAT(stat_list, user_num)
$USSTAT Function
The data returned by $USSTAT is binary with the first 4 bytes containing an error code.
convenient number for calculating rates for the statistics. When a positive error code is
returned the next 10 bytes contain the userid followed by 2 bytes containing the binary
user number. This means that the actual data starts at offset 16 (byte number 17) in the
result string.
-5
-12
-13
-14
-15
-
Invalid parameter (argument 2 > NUSERS)
STAT not linked in
User not logged on any more
$USSTAT return codes
The following program displays some totals for user 0.
——————————————————————————————————————————
474
——————————————————————————————————————————
$USSTAT: Retrieve user's statistics into string
——————————————————————————————————————————
B
%DATA = $USSTAT('CPU SVIO DKIO', 0)
PRINT '$USSTAT ERROR... RC = ' WITH $UNBIN(%DATA)
STOP
END IF
PRINT
PRINT
PRINT
PRINT
'USERID
'CPU
'SVIO
'DKIO
=
=
=
=
'
'
'
'
WITH
WITH
WITH
WITH
$SUBSTR(%DATA, 5, 10)
$UNBIN( $SUBSTR(%DATA, 17, 4) )
END
●
Sirius Functions
Products authorizing $USSTAT
——————————————————————————————————————————
475
——————————————————————————————————————————
——————————————————————————————————————————
7.235
$USSTATL: Retrieve statistics for set of users
into $list
This function allows retrieval of statistics for a set of users into a $list.
The $USSTATL function accepts three arguments and returns a numeric error code.
The first argument is the identifier of the $list to receive the results. The current contents
of the $list are deleted and replaced with the requested statistics. The format of each
$list item is:
Byte 1-10
Blank padded userid
Byte 11-12
Binary user number
Byte 13-
Returned statistics
The third argument is a selection criterion that indicates which users are to be included
in the output $list. The following criteria are allowed:
ACCOUNT=acctid
include only users with account ids matching acctid (wildcards
allowed).
CFR=fid
include only users holding or requesting critical file resources in
files with filename matching fid (wildcards allowed).
CHKP
include only users preventing checkpoints
FILE=filename
include only users with filename open.
IODEV=iodevnum
include only users on IODEV iodevnum.
PNAME=pname
include only users running procedures with names matching
termid (wildcards allowed).
SUBSYS=subsysid
include only users in subsystem subsysid (wildcards allowed).
TERMID=termid
include only users logged on terminals with ids matching termid
USER=userid
include only users with userids matching userid (wildcards
allowed).
——————————————————————————————————————————
476
——————————————————————————————————————————
$USSTATL: Retrieve statistics for set of users into $list
——————————————————————————————————————————
WHAT=activity
include only users with current activity matching activity
In actual fact, all users are always included in the output list, but the excluded users
have the high order bit of their user numbers turned on. This tells $STATLD to exclude
the users from the difference $list.
%RESULT = $USSTATL(list_identifier, stat_list, criterion)
$USSTATL Function
%RESULT is a either a positive number, which is the milliseconds since the
online was brought up, or a negative error code.
$USSTATL return codes
The following program displays some statistics for all users in subsystem SIRMON.
b
%data is
%list1 =
%list2 =
%list3 =
string len 255
$listnew
$listnew
$listnew
Pause 1
%time2 = $USStatL(%list2, 'IODEV CPU','SUBSYS=SIRMON')
Text
userid = { $substr(%data,1,10) } usernum = { $unbin($substr(%data,11,2)) } iodev = { $unbin($substr(%data,13,4)) } cpu total = { $unbin($substr(%data,17,4)) }
End Text
End For
End
——————————————————————————————————————————
477
——————————————————————————————————————————
——————————————————————————————————————————
●
Sirius Functions
Products authorizing $USSTATL
——————————————————————————————————————————
478
——————————————————————————————————————————
$WAKEUP: Pause user until specified time
——————————————————————————————————————————
7.236
$WAKEUP: Pause user until specified time
This function can be used to have the user pause until a particular time. The chief
advantages of $WAKEUP over the PAUSE statement are
●
You can wake up at a particular time rather than after a particular number of
seconds have passed.
●
$WAKEUP has millisecond resolution versus the second resolution of the PAUSE
statement.
●
$WAKEUP allows the wait time to not be counted toward RQTM. This is useful in
cases where the pause is simply a standard part of processing rather than a pause
to allow some condition to clear.
●
$WAKEUP will allow a user to break in with a terminal interrupt on VTAM full screen
terminals.
The $WAKEUP function accepts three arguments and returns a number that is the
number of milliseconds since the online was brought up. As of Sirius Mods version 6.8,
it is a callable $function (“CALLing Sirius Mods functions” on page 32).
The first argument is a number indicating the time to wake up expressed as milliseconds
since the online was brought up.
The second argument is a number, which if present and non-zero, indicates that the wait
time is not to be included as part of RQTM.
The third argument is an optional string (NOURGMSG, case unimportant) that prevents a
user paused by $WAKEUP from being immediately wakened if a BROADCAST
URGENT message is sent.
The third argument is available as of Sirius Mods version 7.2. Prior to Sirius Mods 7.2,
$WAKEUP completes immediately if a BROADCAST URGENT message is sent to the
user. The functionality of this argument is also available (though not controlled by an
argument) via zap in Sirius Mods 6.7 and 7.1, as described in the Sirius Mods Release
Notes for those versions.
[%TIME =] $WAKEUP(wake_time, rqtm_flag, [option])
$WAKEUP Function
%TIME is a positive integer.
——————————————————————————————————————————
479
——————————————————————————————————————————
——————————————————————————————————————————
In the following code fragment, three screens are automatically displayed for 2.3
seconds each. The sleep time is not counted toward RQTM.
%TIME = $WAKEUP(0)
%RC = $FAKEENT
READ SCREEN SCREEN1
%TIME = $WAKEUP( %TIME + 2300, 1)
%RC = $FAKEENT
READ SCREEN SCREEN2
%RC = $FAKEENT
READ SCREEN SCREEN3
●
Sirius Functions
Products authorizing $WAKEUP
——————————————————————————————————————————
480
——————————————————————————————————————————
$WEBxxx: Janus Web Server $functions
——————————————————————————————————————————
7.237
$WEBxxx: Janus Web Server $functions
There is a set of $functions that is only available with Janus Web Server. The $function
names begin with the characters “$WEB”, and they are described in the Janus Web
Server Reference Manual.
Note that although the Limited Janus Web Server capability authorizes use of the
$WEBxxx functions, it does not, as of its initial release in version 6.1 of the Sirius Mods,
authorize any of the other $functions authorized by unlimited Janus Web Server, such as
$LISTNEW.
——————————————————————————————————————————
481
——————————————————————————————————————————
——————————————————————————————————————————
7.238
$WINDEX: Word number of first occurrence of
word in phrase
This function finds the first occurrence of a word in a phrase.
The $WINDEX function accepts three arguments and returns a numeric result that is the
word number in the first argument string of the the second argument word.
The second argument is word that is to be located in the first argument. If the second
argument string is not found, $WINDEX returns a 0.
The third argument is a delimiter that separates words in the first argument string. This
is an optional argument and defaults to blank.
%NUM = $WINDEX(string, word, delim)
$WINDEX Function
%NUM is either a word number or 0.
For example, this statement sets %JUNK to 3:
%JUNK = $WINDEX('BOB CAROL TED ALICE', 'TED')
This statement sets %JUNK to 0:
%JUNK = $WINDEX('BOB CAROL TED ALICE', 'ROGER')
This statement sets %JUNK to 2:
%JUNK = $WINDEX('A WORD/OR TWO/BEFORE/I/GO', 'OR TWO', '/')
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $WINDEX
——————————————————————————————————————————
482
——————————————————————————————————————————
$XMLxxx: Janus SOAP $functions
——————————————————————————————————————————
7.239
$XMLxxx: Janus SOAP $functions
Prior to Sirius Mods version 6.5, Janus SOAP contained a set of $functions whose
names begin with the characters “$XML”. Only available with Janus SOAP, those
$functions are now deprecated.
——————————————————————————————————————————
483
——————————————————————————————————————————
——————————————————————————————————————————
7.240
$X2D: Convert hex string to integer
The $X2D function returns the integer which is represented by the hexadecimal input
string.
$X2D accepts two optional arguments and returns a numeric value.
The first argument is the hex string to be converted to an integer. If it is omitted or is the
null string or contains characters other than '0' through '9', 'A' through 'F', or 'a' through
'f', zero is the result.
The second argument is the number of characters to use from the string. If it is omitted
or is greater than 8, 8 characters are used. If, after conversion to an integer, it is 0 or
less, or can't be represented as a 31 bit value, zero is the result of $X2D.
The leading bit of the hexadecimal string is repeated out to the length derived from the
second argument. If the length is less than the length of the hexadecimal string, the
leftmost digits of the hexadecimal string are dropped. The hexadecimal string
represents an integer using 2's complement.
%VALUE = $X2D(hex_string, width)
$X2D Function
%VALUE is set to the integer represented in 2's complement by the
hexadecimal string.
The following program will print the value -1:
B
PRINT $X2D('0F', 1)
END
●
●
●
●
●
●
●
●
Sirius Functions
Janus Open Client
Janus Open Server
Janus Sockets
Janus Web Server
Japanese Functions
Products authorizing $X2D
——————————————————————————————————————————
484
——————————————————————————————————————————
——————————————————————————————————————————
——————
CHAPTER 8
User Language Statements for Sirius
Functions
This chapter lists some of the User Language statements delivered as part of the Sirius
Mods. The statements listed in this chapter are useful with certain of the $functions
listed in “Description of $Functions” on page 31.
At the end of each statement description is a figure listing the Sirius Mods products
which authorize the statement. If your site is not authorized for any of these products,
an attempt to compile a request using the statement will generate an M204.0229:
INVALID STATEMENT error message, compilation will fail, and the request will not run.
There are other User Language statements that are part of some Sirius Mods products
and are not described in this manual; see the appropriate manual for the documentation.
8.1
Assert statement
Programming errors often cause symptoms that point directly to the error. For example,
an incorrectly coded array assignment might result in a subscript range error on the very
statement with the error. Alternatively, an assignment from the wrong variable to a
screen item results in incorrect data appearing in the corresponding screen field. These
kinds of programming errors are generally easy to isolate and fix, and they are usually
caught during adhoc debugging or fairly quickly after a program goes into production.
Yet many other programming errors can cause more subtle problems that cause
completely unrelated statements to fail, or even cause corruption of data that might not
be detected until long after the original error has occurred. This often happens because
much code depends on assumptions about the current environment, including
assumptions about values of variables. A coding error or a misunderstanding of the
environmental requirements of a chunk of code can cause the code to be run with invalid
data. The code may execute but produce invalid results, or perhaps it may set values
incorrectly that can cause problems in yet another part of the code.
There are several ways to deal with this problem with assumptions:
●
Don't make assumptions in code. While it is an admirable goal to make code as
flexible as possible, taken to the extreme, this approach produces code that is
bloated by instructions to handle cases that never happen, setting return codes and
status values that should never be set that then have to be checked elsewhere. Put
another way, code has to do not only what is necessary but also has to perform
many unnecessary tasks.
——————————————————————————————————————————
485
——————————————————————————————————————————
——————————————————————————————————————————
●
Ignore the problem and hope for the best.
●
Check key assumptions in code, and terminate the program with appropriate
diagnostics to isolate the cause of the termination.
The last solution looks the most appealing. However, without the ASSERT statement,
collecting the appropriate diagnostic information can only be done in User Language, so
it can be tedious (numerous AUDIT, PRINT, or $SETG statements), and it still provides
only limited information.
The Sirius Mods provides a User Language statement, ASSERT, to get around these
problems. The ASSERT statement serves three functions:
●
It tests the validity of an assumption.
●
It causes the current request to be cancelled if the assumption is incorrect. In an
APSY subsystem, this causes transfer to the subsystem error procedure.
●
It indicates the procedure and line number containing the failing ASSERT statement.
Furthermore, in the presence of appropriate SIRFACT MAXDUMP and SIRFACT
DUMP settings, it causes the creation of a SirFact dump that contains a wide variety
of information about the program environment at the time of the error. For more
information about SirFact dumps, see the SirFact Reference Manual.
Stated another way, the ASSERT statement allows testing of assumptions and extensive
diagnostic data collection with a single, simple statement.
ASSERT cond [, [SNAP] [INFO info] [CONTINUE] ]
ASSERT statement syntax
cond
The conditions that are being asserted as true. These conditions have
exactly the same syntax as conditions on IF statements.
SNAP
Indicates a CCASNAP is to be taken on an assertion failure. A
CCASNAP is taken in addition to, but before, any SirFact dump
associated with the assertion failure.
info
Extra information that is included in the audit trail and terminal output for
the assertion failure as part of a MSIR.0494 message. info must be
enclosed in quotes if it contains spaces or other Model 204 separator
characters.
CONTINUE
Indicates that an assertion failure will not cause the request to be
cancelled. An MSIR.0494 message, and possibly a SirFact dump, will
still be produced, but the request will continue.
——————————————————————————————————————————
486
——————————————————————————————————————————
Assert statement
——————————————————————————————————————————
Some valid ASSERT statements are :
ASSERT
ASSERT
ASSERT
ASSERT
ASSERT
ASSERT
(%X GT 0) AND (%NAME NE '')
%X GT 0, SNAP
NOT $SETG('NAME', 'VALUE')
%X = 22, INFO %X
%X, INFO 'Zero %X' SNAP
%INCOME GT 10000, CONTINUE
Note: As of Sirius Mods version 6.7, a %variable in the Info clause is interpreted to
mean the contents of the indicated variable. For example, the fourth ASSERT statement
above (ASSERT %X = 22, INFO %X) produces the following message if %X is 21:
MSIR.0494: Assert info: 21
For versions prior to 6.7, an unquoted %variable name is interpreted as a literal, and the
message produced is: MSIR.0494: Assert info: %X.
An ASSERT statement uses the same expression handler as the IF statement, so it is
exactly as efficient as an IF statement with the same conditions.
To use an ASSERT, simply place it before any code that depends on some assumptions
about variables or the environment. ASSERT statements should be coded to test values
or relationships that are required for the code to run correctly, but whose values are not
immediately apparent from the surrounding code.
In addition to catching coding errors, the ASSERT statement provides the following
benefits :
●
It makes clear the assumptions that the code depends on to anyone scanning the
program. This makes it easier to understand the surrounding code. Similarly, it
makes the environmental requirements clear to someone wanting to re-use a code
fragment or call a common subroutine. While these benefits can be achieved with
comments, the ASSERT statement has the added benefit that it enforces the
restrictions.
●
It eliminates doubt when scanning code while trying to debug a problem, and it
prevents wasted time on “what if” scenarios that can be ruled out with a simple
ASSERT.
——————————————————————————————————————————
487
——————————————————————————————————————————
——————————————————————————————————————————
8.2
Html or Text statement
The Html (or Text) statement in User Language is a general purpose alternative to a
series of Print statements for producing a fair amount of literal data. Primarily for use
with Janus Web Server (hence the name Html), it is available with many Sirius
products. It is most useful when PRINT output is captured or directed by some means
(see “$LIST_CAPTURE: Capture print data to $list” on page 156). It is also quite useful
for populating a Stringlist with a large amount of mostly constant text. This latter
capability is provided by the To option of the Html/Text statement.
In this section, “HTML block” refers to either the Html or Text block.
The Html block can be used to produce print output of largely literal or static data. For
example, sending output to a browser with Janus Web Server often requires a significant
quantity of static text for HTML directives. Rather than placing this static data inside
quotes in a Print statement, the Html block will automatically assign text as print output.
Any Model 204 expression, including simple %variable values or $function invocations,
can be placed inside an Html block, as long as it is enclosed inside the expression start
and end characters. The default start and end characters are the curly brackets ( { )
and ( } ).
The following is an example of an Html statement specification:
HTML
<form method="POST" action="processform">
<br>
Last name: <input type="text"
name="lname" value="{%LNAME}">
</form>
END HTML
The syntax of the Html and Text blocks is shown below:
HTML [options]
body
block_end_line
Html block syntax
options, body, and block_end_line are discussed later in individual subsections.
TEXT [options]
body
block_end_line
Text block syntax
options, body, and block_end_line are discussed later in individual subsections.
——————————————————————————————————————————
488
——————————————————————————————————————————
——————————————————————————————————————————
The components of the Html or Text block are discussed in the following sections. The
Html (or Text) block can be used in contexts other than the production of a web page.
For example, it can be used:
●
To store lines in a temporary procedure or sequential dataset, using the USE
command
●
To populate a Stringlist, using the To option on the Html/Text statement
●
To populate a $list, using the $LIST_CAPTURE function
●
To send lines over a Janus Sockets connection, using the $SOCK_CAPTURE
function
●
To prepare output processed by some other program, when the output is created by
something like a BATCH2 or RCL connection to Model 204
Here are some advantages of the Html/Text block:
●
User Language is visually close to the output.
●
Literal text does not need to be enclosed in apostrophes.
●
The Print keyword is not necessary.
●
Any valid Model 204 expression can be included inside an Html block, not just
literals, %variables, fieldnames, $functions, and a few other constructs.
●
The With and And keywords are not needed between expressions.
●
Apostrophes do not need to be doubled, as in:
PRINT 'Just say ''No'''
——————————————————————————————————————————
489
——————————————————————————————————————————
——————————————————————————————————————————
The following is an example of an Html block using JavaScript to illustrate applications of
the Html/Text options:
HTML NOCONT EXPRS '!{' EXPRE '}!'
<html>
<head>
<title>My Javascript Page</title>
</head>
!{$SIR_DATE('Wkd Mon DD YYYY HH:MI:SS')}!
<br>
<body>
<script>
<!-name=prompt("Person's name","Type name here");
END HTML
%S1='if (name=="'
FR WHERE RECTYPE=PHONE
PRINT %S1 WITH NAME WITH '") {document.write("' WITH EXTN WITH '")}'
%S1='else if (name=="'
END FOR
HTML NOCONT EXPRS '!{' EXPRE '}!'
else {alert ("Unkown person")};
-->
</script>
</body>
</html>
END HTML
Html statement options used in this example:
●
Nocont is used to turn off continuations signified by trailing dashes. In the
JavaScript, dashes are used in an input line that prevents browsers without
JavaScript from displaying script as literal output.
●
Exprs and Expre let you use characters other than the curly brackets ( { } ) to
demarcate expressions. The curly bracket characters are necessary in JavaScript.
New in Sirius Mods version 6.0, the Html block is available to any customer who owns
any of the following products:
●
●
●
●
●
Janus SOAP
Janus Sockets
Janus Web Server
Sirius Functions
The Html block is also available if the Limited Janus Web Server capability is available.
——————————————————————————————————————————
490
——————————————————————————————————————————
——————————————————————————————————————————
8.2.1
Options: Html or Text block options
The various options for an Html or Text block are introduced after the Html or Text
keyword. They are described in the following subsections.
8.2.1.1
Data, Print, Audit, or Trace
These keywords indicate that the Html block consists of only the text that follows the
keyword on the logical line: that is, there is no End Html statement to end the block.
Prior to Sirius Mods version 7.2, only the Data keyword had this effect, and the Print,
Audit, and Trace keywords did not exist.
Any Html statement keywords that appear after a Data, Print, Audit, or Trace keyword
are processed not as keywords but simply as text. If you want to specify keywords in
addition to a Data, Print, Audit, or Trace keyword, they must appear before Data, Print,
Audit, or Trace to be treated as a keyword.
All other Html block processing, including expression processing, is performed on the
line as if it were inside an Html block. The exception is Nodummy processing, because
dummy string replacement is performed before the Html statement is parsed.
Data or Print
Either of these keywords can be thought of as providing a single-line
Html/Text statement which can still be much easier to type and read
than a User Language PRINT statement, as in:
HTML DATA Don't need to worry about apostrophes
TEXT PRINT {%I} + {%J} = {%I + %J}
The following is an equivalent alternative to the second statement in the
preceding example.
PrintText {%I} + {%J} = {%I + %J}
The PrintText statement has the same effect as a Text Print statement.
The PrintText keyword is simply a merging and reordering of Text
Print to emphasize the principle action. The lone difference between
PrintText and Text Print is that PrintText cannot be used if you want to
include other Html/Text options, as in:
text noexpr print The set is {2, 3, 5, 8, 13, ...}
The Data keyword is available in Sirius Mods 6.2 and later. The Print
and PrintText keywords are available in Sirius Mods 7.2 and later.
Audit
This keyword provides a single-line Html/Text statement that functions
like a User Language AUDIT statement, that is, routing subsequent text
to the audit trail.
——————————————————————————————————————————
491
——————————————————————————————————————————
——————————————————————————————————————————
For example, this statement directs the text content to the audit trail:
text audit It ({$time}) was the best of times
The following is an equivalent alternative to the preceding example.
AuditText It ({$time}) was the best of times
As with the PrintText keyword above, the AuditText statement has the
same effect as a Text Audit statement, except it cannot be used if you
want to include additional Html/Text options.
The Audit keyword is available in Sirius Mods 7.2 and later. The
AuditText keyword is available as of Sirius Mods 7.2.
Trace
This keyword provides a single-line Html/Text statement that is the
same as a User Language TRACE statement, that is, routing
subsequent text to the trace destination (which may be the audit trail,
print device, or CCATEMP trace table, or a combination of them).
For example, this statement directs the text content by default to the
audit trail:
text trace This day ({$date}) is unlike any other
The following is an equivalent alternative to the preceding example.
TraceText This day ({$date}) is unlike any other
As with the PrintText and AudiText keywords above, the TraceText
statement has the same effect as a Text Trace statement, except it
cannot be used if you want to include additional Html/Text options.
The Trace and TraceText keywords are available as of Sirius Mods 7.2.
The Trace statement is described in detail in the SirFact Reference
Manual.
8.2.1.2
Ent_print
The Ent_print keyword overrides the current $ENT_PRINT setting for character entity
translation over the Html block. Ent_print must be followed by one of these keywords:
Off
No character entity translation will occur over the Html block.
On
All data printed by the Html statement will undergo character entity translation.
Var
Only the results of expressions will undergo character entity translation.
——————————————————————————————————————————
492
——————————————————————————————————————————
——————————————————————————————————————————
Character entity translation is the process of converting a single character that might be
problematic in certain contexts to a more verbose but non-problematic equivalent. For
example, if a “less than” sign (<) appears in HTML text, it should typically be represented
as “<” to prevent an HTML processor from mistakenly interpreting it as the start of an
HTML tag.
When entity translation is performed, the default translations are “&” to “&”, “<” to
“<” and the double quotation mark character (") to “"”. These defaults should
be sufficient for most HTML and XML applications (though XML might also require
translation of the single quotation mark character (') to “'” if attributes are
enclosed in single quotation marks), but they can be modified with the $ENT_TAB
function.
The Ent_print keyword is a compile-time option that affects only what is inside the Html
block and that is not affected by evaluation time setting of $ENT_PRINT, even within the
Html block. If no Ent_print keyword is present on the Html statement, character entity
translation is controlled by the evaluation-time $ENT_PRINT setting.
Automatic character entity translation and the Ent_print keyword on the Html/Text
statement are only available in Sirius Mods 6.2 and later.
8.2.1.3
LiteralsToTemp
The LiteralsToTempt option indicates that the literal data in the statement is stored in
CCATEMP rather than STBL, avoiding excessive demands on STBL space. Designed
for a Text statement with an unusually large amount of literal data, this is an alternative
to setting the X'01' bit of the SIRCOMP user parameter (which performs the same
function).
8.2.1.4
Nocom or Nocomments
The Nocomments (abbreviated Nocom) option indicates that lines beginning with an
asterisk (*) are not comment lines. For example:
HTML NOCOM
* This line will go to the output
END HTML
——————————————————————————————————————————
493
——————————————————————————————————————————
——————————————————————————————————————————
8.2.1.5
Nocont or Nocontinuations
The Nocontinuations (abbreviated Nocont) option causes trailing dashes to cease
being treated as line continuations. For example, the following statement will cause the
output to appear on two separate lines:
HTML NOCONT
English:
Social Studies:
END HTML
8.2.1.6
BC
Nodum or Nodummy
The Nodummy (abbreviated Nodum) option stops dummy string substitution. For
example, the following statement will cause the literal string ?&W to be output without
global variable substitution:
HTML NODUM
Hello, ?&W
END HTML
8.2.1.7
Noell or Noellipses
With the Noellipses (abbreviated Noell) option, a trailing ellipsis (...) is not treated as
a concatenation operator. For example:
HTML NOELL
These lines are not joined...
They will appear on different lines.
END HTML
8.2.1.8
Noexpr or Noexpressions
If you do not want expression substitution, specify Noexpr or Noexpressions. For
example:
HTML NOEXPR
{This will be sent directly to output}
END HTML
8.2.1.9
Raw
The Raw option acts as Nocom, Nocont, Nodum, Noell, and Noexpr all at once.
——————————————————————————————————————————
494
——————————————————————————————————————————
——————————————————————————————————————————
8.2.1.10
Noend
The Noend option eliminates the block end line. Thus, the block will terminate at the
end of the procedure. For example:
PROC FOO
HTML NOEND
Now we are in HTML.
END HTML
Still in HTML.
END PROC
8.2.1.11
Exprs or Exprstart
The Exprstart (abbreviated Exprs) option specifies a string, up to three characters
long, that begins an expression within the block body. The default is a left curly brace
( { ). For example:
HTML EXPRS go EXPRE stp
The answer is go8*9stp
HTML END
It is probably best to use start and end sequences that are not likely to occur in the literal
text in the Html/Text block and that clearly demarcate expressions from literal text. The
go and stp in the example above are actually not very good choices.
If the expression start string occurs in the input text, you can “double” the expression
start and end strings, instead of using the Exprs and Expre options. For example:
HTML
<script>
{{alert("User error")}}
<script>
END HTML
An alternative way to handle the curly braces in the script above is shown in the Html
block example at the beginning of this chapter: that is, specifying HTML EXPRS '!{'
EXPRE '}!' and !{alert("User error")!}.
Note: If you use multiple special characters to demarcate expressions, you are advised
to enclose those characters in single quotation marks (as above) in your Exprs and
Expre specifications. Otherwise, multiple-character combinations involving certain
special characters (including these six, for example: = ¬ ( ) < > ) cause M204.0580
errors.
——————————————————————————————————————————
495
——————————————————————————————————————————
——————————————————————————————————————————
8.2.1.12
Expre or Exprend
The Exprend (abbreviated Expre) option specifies a string that ends an expression
within the block body. The default is a right curly brace ( } ).
8.2.1.13
End
To set your own block_end_line, you can use the End option. If the text of the line you
are specifying contains spaces, enclose it in single quotation marks, as in:
END 'END TEXT BLOCK'
The default block_end_line value is End Html (for the Html block) or End Text (for the
Text block).
8.2.1.14
To %stringlist | Audit | Print | Trace
The To option lets you direct the contents of the Html or Text block to a Stringlist or to
the destinations associated with the User Language statements Audit, Print, or Trace.
Stringlists are only available to Janus SOAP cuystomers. For more information about
Stringlists see the Janus SOAP Reference Manual.
To %stringlist
Here is how Text To populates a Stringlist with some names:
%jumps
is object stringlist
...
%jumps = new
text to %jumps
Axel
Flip
Lutz
Salchow
Toe Loop
Wally
end text
There are many advantages to using Html To or Text To over a plain Html statement
wih $LIST_CAPTURE:
●
$LIST_CAPTURE or an equivalent is not available for Stringlists.
●
Because Html To does not go through generic Print processing, it has a somewhat
more efficient processing path, that is, it uses less CPU.
——————————————————————————————————————————
496
——————————————————————————————————————————
——————————————————————————————————————————
●
Because Html To does not go through generic Print processing, the generated
quads take somewhat less space.
●
An Html To block does not affect the current $LIST_CAPTURE setting, so it
eliminates the need to worry about saving and restoring the $LIST_CAPTURE
setting.
●
A To option on an Html statement is simply less and cleaner code than an Html
statement inside a $LIST_CAPTURE bracket.
●
If an expression inside an Html To block invokes a User Language method, and
that method does a Print statement, the output of that Print statement does not end
up on the Stringlist target of the Html statement. Inside a $LIST_CAPTURE
bracket, the output of such a Print statement ends up on the $LIST_CAPTURE's
target $list.
The To option of the Html/Text statement appends to the target Stringlist, so it does not
instantiate the Stringlist if it is null. In fact, a null Stringlist target for an Html To results
in a null-pointer request-cancelling error.
Even if the ultimate target of an Html/Text statement is a plain $list, the Html To can still
be used to gain some of the benefits of this structure without much extra code by using
the Stringlist object MoveFromId and MoveToId methods:
%htmlList
is object stringList
%list
is float
...
%list = $listNew
...
%htmlList = new
%htmlList:modeFromId(%list)
text to %htmlList
This gets added to the $list.
end text
%htmlList:modeToId(%list)
To Audit, To Print, To Trace
These options direct the contents of an Html or Text block or line to the destinations
associated with the User Language statements Audit, Print, or Trace. Respectively
these destinations are the journal/audit trail, the current print output device, or the trace
destination (which may be the audit trail, print device, or CCATEMP trace table, or a
combination of them).
For example, the following statement directs the Text block content to the audit trail:
text to audit
Now ({$time}) is the time for all good men
to come to the aid of their company.
end text
——————————————————————————————————————————
497
——————————————————————————————————————————
——————————————————————————————————————————
To direct a single line of output, you can use the Data keyword (“Data, Print, Audit, or
Trace” on page 491) as in the following:
text to audit Data It ({$time}) was the best of times
Or, simpler, you can use the Audit keyword like this:
text Audit It ({$time}) was the best of times
8.2.2
Body: Html or Text block body
Each line of an Html or Text block, up to the block_end_line, creates a line of literal
output, with the following substitutions:
Expressions
An expression is begun by a left brace ( { ) or a user-defined string
specified with the Exprs option, and it is ended by a right brace ( } )
or a user-defined string specified with the Expre option. Text within
the expression is evaluated as if it were the right-hand side of a User
Language assignment; that value is produced, rather than literal
output.
Dummy strings
Normally, as in other Model 204 input, dummy strings are substituted
under the control of the SUB parameter. This can be suppressed
with the Nodummy option, which may be useful if your block contains
strings like “what the heck??!!”.
Continuation
Continuation allows text from multiple lines to be printed on one line
by adding a hyphen (-) to all preceding lines in the block. All spacing
and indentation following the hyphen is ignored. This option works
inside an expression.
Ellipses
Ellipses allow text from multiple command lines to be printed on one
line by adding three dots (...) to all preceding command lines.
Leading spaces will be included. This option will not work inside an
expression.
Indentation
Except for continuation lines, the output of a line is indented by as
many spaces as the input is indented relative to the Html or Text
statement that begins the block.
8.2.3
block_end_line: Html or Text block end
By default, the line that ends an Html or Text block is End Html for an Html block, or it
is End Text for a Text block. You can specify your own end line with the End option,
as described above in “End” on page 496.
——————————————————————————————————————————
498
——————————————————————————————————————————
——————————————————————————————————————————
8.2.4
Printing of expression results
Model 204 expressions enclosed in the expression start and end characters are printed
as if the result of the expression were placed literally in the place of the expression in the
HTML block. For example, Text Print {$date} produces a result like 08-02-29.
8.2.4.1
Character entity substitution
Under Sirius Mods 6.2 and later, the result of the expression might undergo character
entity substitution under control of the $ENT_PRINT setting or the Ent_print parameter
on the Html/Text statement. An expression can explicitly override the default
$ENT_PRINT and Ent_print processing by immediately following the expression start
character(s) with one of the following special characters:
&
Perform character entity substitution regardless of the current $ENT_PRINT
setting and the Ent_print setting on the Html statement.
!
Do not perform character entity substitution, regardless of the current
$ENT_PRINT setting and the Ent_print setting on the Html statement.
*
Do not print the results of the expression. This can be useful if embedding a
$function that itself prints output, such as $LIST_PRINT or $WEB_SEL, or a
$function that simply sets some environmental parameter (such as $WEB_SET or
$RESETN) whose return value should not be displayed.
Note: The asterisk (*) suppresses the printing of the return code but not the
output from a $LIST_PRINT or $WEB_SEL function.
In the following example, character entity substitution is explicitly suppressed for the
contents of %FONT and explicitly forced for %COMMENT, and the return code from
$LIST_PRINT is suppressed:
HTML
{!%FONT}This is in a fancy font</font>
<input type="text" name="comment" value="{&%COMMENT}">
<br>And here's some stuff<br>
{*$LIST_PRINT(%LIST)}
END HTML
8.2.4.2
The {~} directive
The special expression {~} directs the compiler to replace this expression with the literal
chartacter content of the next expression appearing on the same line. So PrintText
{~} {$date} produces $date 08-02-29. The evaluation of the expression following
{~} is carried out as usual.
——————————————————————————————————————————
499
——————————————————————————————————————————
——————————————————————————————————————————
8.2.5
Table Usage
While the Html/Text statement can provide a convenient typing shorthand relative to a
host of Print statements, and it can make code considerably more readable, it does not
necessarily use any less table space than the comparable Print statements.
Under Sirius Mods version 6.6 and later, however, table space can be saved with the
Html/Text statement, as follows:
●
By using the To clause and sending the Html/Text statement output directly to a
Stringlist, the amount of QTBL space used is reduced.
●
If the X'01' bit is set in the SIRCOMP user parameter when a program is compiled,
string literals are saved in CCATEMP rather than STBL. Since Html/Text
statements often have a large quantity of literal text, they can use a lot of STBL
space, so the STBL space savings of the SIRCOMP X'01' bit can be great.
The drawback to having string literals in CCATEMP rather than STBL is that the
access path to the data is somewhat longer, that is, slightly more CPU is required to
access it. When the Html/Text statement uses a To clause, the extra overhead of
CCATEMP data access is reduced, because Html/Text To processing keeps the
CCATEMP pages holding literal data open over as many literals as possible.
Furthermore, for pre-compiled APSY procedures, the literals in CCATEMP do not
need to be APSY loaded, and they are shared among all users of a procedure.
Finally, if a user with a large number of Html/Text statement literals is serverswapped, there is less data to server-swap if literals are kept in CCATEMP
(although, the data in CCATEMP does take buffer pool space and might require
CCATEMP I/O).
So there is probably no good general rule of thumb regarding whether the SIRCOMP
X'01' bit should be set. Probably, unless a site is struggling with server size problems, it
is best and simplest to just keep the literals in STBL.
8.3
Loop Next statement
It is quite common in any programming language to have a need to exit a loop under
certain conditions. User Language provides this capability with the Loop End statement:
for %i from 1 to %list:count
print %list:item(%i)
if %list:item(%i) eq '***END***' then
loop end
end if
end for
——————————————————————————————————————————
500
——————————————————————————————————————————
Loop Next statement
——————————————————————————————————————————
It is almost as common to have the need to simply do the next iteration of a loop, that is,
go to the top of the loop, under certain conditions. The Janus SOAP ULI provides this
capability with the Loop Next statement:
for %i from 1 to %list:count
if %list:item(%i) eq '' then
loop next
end if
print %list:item(%i)
end for
The Loop Next statement takes no parameters.
——————————————————————————————————————————
501
——————————————————————————————————————————
——————————————————————————————————————————
——————————————————————————————————————————
502
——————————————————————————————————————————
——————————————————————————————————————————
——————
CHAPTER 9
The Sirius Functions contains a set of $functions that provide communication between
User Language and Sirius Software's Fast/Unload product. If Fast/Unload is not
installed, these functions return no useful information.
The operation of the Fast/Unload User Language Interface is to invoke the Fast/Unload
load module on a Model 204 file or group, restricted to the records which have been
established in a User Language FIND statement. The $function which performs this
operation is $FUNLOAD, and it is the $function you will always use when you use the
Fast/Unload User Language Interface; see “$FUNLOAD: Fast/Unload records in Model
204 list or found set” on page 125 for a description of the invocation of Fast/Unload. The
other $functions are optional, and can be used for special approaches to using
Fast/Unload. The Fast/Unload User Language Interface $functions are shown in the
following list. In addition to these $functions, it is often useful to use the $list processing
$functions (“$lists” on page 7) with the Fast/Unload User Language Interface.
●
$FUNIMG
●
$FUNFORC
●
$FUNLIST
●
$FUNLOAD
●
$FUNPURG
●
$FUNSKIP
●
$FUNSSTR
●
$FUNWAIT
Refer to the Fast/Unload Reference Manual for information about setting up the
Fast/Unload User Language Interface environment; it also contains information about
the impact of using the Fast/Unload User Language Interface versus using Fast/Unload
in a batch, standalone mode.
——————————————————————————————————————————
503
——————————————————————————————————————————
——————————————————————————————————————————
——————————————————————————————————————————
504
——————————————————————————————————————————
TSO $Functions
——————————————————————————————————————————
——————
CHAPTER 10
TSO $Functions
Sirius Software distributes a special version of the TSO full screen interface to Model
204 that allows the online address space to request TSO services in the TSO address
space. These requests are issued using various $functions, which may be available
even if you have not installed the special TSO interface, but do nothing useful in this
case. The TSO $functions are
●
●
●
●
●
●
●
●
●
$TSOATT
$TSOCALL
$TSOCAN
$TSOCMD
$TSOEXEC
$TSOEXIT
$TSOID
$TSOSTAT
$TSOWAIT
——————————————————————————————————————————
505
——————————————————————————————————————————
TSO $Functions
——————————————————————————————————————————
——————————————————————————————————————————
506
——————————————————————————————————————————
Mathematical $Functions
——————————————————————————————————————————
——————
CHAPTER 11
As of Sirius Mods version 6.9, Sirius Software distributes high-performance, highprecision versions of most of the IBM mathematical functions available via User
Language.
The following functions are available, and their descriptions are in the following
subsections.
$ABS(x)
$ARCCOS(x)
$ARCSIN(x)
$ARCTAN(x)
$ARCTAN2(x,y)
$COS(x)
$COSH(x)
$COTAN(x)
$ERF(x)
$ERFC(x)
$EXP
$EXP2
$EXP10
$GAMMA(x)
$IXPI(x)
$LGAMMA(x)
$LOG
$LOG2
$LOG10
$MAX(x1,x2,x3,x4,x5,x6,x7,x8)
$MIN(x1,x2,x3,x4,x5,x6,x7,x8)
$PI
$RXPI(x)
$RXPR(x)
$SIN(x)
$SINH(x)
$SQRT(x)
$TAN(x)
$TANH(x)
Absolute value
Inverse cosine
Inverse sine
Arctangent
Arctangent of x/y
Cosine of radian argument
Hyperbolic cosine
Cotangent
Error function
Complement error function
Get natural exponent of a number
Get 2's exponent of a number
Get 10's exponent of a number
Gamma function
Integer base, integer exponent
Log gamma function
Get natural log of a number
Get log base 2 of a number
Get log base 10 of a number
Return maximum of specified arguments
Return minimum of specified arguments
Value of pi
Real base, integer exponent
Real base, real exponent
Sine of radian argument
Hyperbolic sine
Square root of positive argument
Tangent
Hyperbolic tangent
——————————————————————————————————————————
507
——————————————————————————————————————————
——————————————————————————————————————————
11.1
$ABS: Absolute value
The $ABS(x) function returns the absolute value of its given argument.
For example:
$ABS(-50) = 50
$ABS(6) = 6
11.2
$ARCCOS: Inverse cosine
The $ARCCOS(x) function returns the arccosine (in radians) of a given argument. If the
magnitude of the argument exceeds 1, an error message is printed and a 0 is returned.
11.3
$ARCSIN: Inverse sine
The $ARCSIN(x) function returns the arcsine (in radians) of a given argument. If the
magnitude of the argument exceeds 1, an error message is printed and a 0 is returned.
11.4
$ARCTAN: Inverse tangent
The $ARCTAN(x) function returns the arctangent (in radians) of a given argument.
11.5
$ARCTAN2: Inverse tangent of ratio of
arguments
The $ARCTAN2(x,y) function returns the arctangent (in radians) of the ratio of two
arguments — x divided by y. If the second argument is 0 (or omitted), an error message
is printed and a 0 is returned.
11.6
$COS: Cosine
The $COS(x) function returns the cosine of an argument that is given in radians. If the
magnitude of the argument exceeds 1015 radians, an error message is printed and a 0 is
returned.
——————————————————————————————————————————
508
——————————————————————————————————————————
$COSH: Hyperbolic cosine
——————————————————————————————————————————
11.7
$COSH: Hyperbolic cosine
The $COSH(x) function returns the hyperbolic cosine of an argument that is given in
radians. If the magnitude of the argument exceeds 175.366, an error message is printed
and a 0 is returned.
11.8
$COTAN: Cotangent
The $COTAN(x) function returns the cotangent of an argument that is given in radians.
If the magnitude of the argument exceeds 1015 radians, an error message is printed and
a 0 is returned.
11.9
$ERF: Error function
The $ERF(x) function returns the value:
x
2
2/√π 0∫ e-z dz
11.10
$ERFC: Error function complement
The $ERFC(x) function returns 1 - the $ERF(x) value, that is:
x
2
1 − 2/√π 0∫ e-z dz
11.11
$EXP: Exponential function
The $EXP(x) function returns the value ex.
If x exceeds 174.63, an error message is printed and a 0 is returned.
11.12
$EXP2: Two's exponent function
The $EXP2(x) function returns the value 2x.
——————————————————————————————————————————
509
——————————————————————————————————————————
——————————————————————————————————————————
11.13
$EXP10: Ten's exponent function
The $EXP10(x) function returns the value 10x.
11.14
$GAMMA: Gamma function
The $GAMMA(x) function returns the value:
∞
x-1 e- u du
0∫ u
If x is not within the range 0 < x < 57.5744, an error message is printed and a 0 is
returned.
11.15
$IXPI: Integer base raised to integer exponent
The $IXPI(x,y) function returns the value of its first argument (rounded to the nearest
integral value) raised to the power of its second argument (rounded to the nearest
integral value). If |x| equals 0, and |y| is less than or equal to 0, an error message is
printed and a 0 is returned.
For example:
$IXPI(8,2) = 82 = 64
$IXPI(2.4,.5) = $IXPI(2,1) = 2
11.16
$LGAMMA: Lgamma function
The $LGAMMA(x) function returns the value:
∞
loge 0∫ ux-1 e- u du
If x is not in the range 0 < x < 4.2913 * 1073, an error message is printed and a 0 is
returned.
——————————————————————————————————————————
510
——————————————————————————————————————————
$LOG: Log function
——————————————————————————————————————————
11.17
$LOG: Log function
The $LOG(x) function returns the natural logarithm (the logarithm base e) of the number
x.
If x is not greater than 0, an error message is printed and a 0 is returned.
11.18
$LOG2: Log base 2 function
The $LOG2(x) function returns the base-2 logarithm of the number x.
11.19
$LOG10: Log base 10 function
The $LOG10(x) function returns the base-10 logarithm of the number x.
11.20
$MAX: Return maximum value
The $MAX(x1,x2,x3,x4,x5,x6,x7,x8) function returns the highest value from a list of as
many as eight arguments.
For example:
$MAX(-6, 5, 0, 4, 3, 7, -7, 1) = 7
$MAX(-6,4) = 4
$MAX(4,-6,70.3) = 70.3
$MAX(-6, ,-5) = -5
$MAX(-6,0,-5) = 0
Omitted arguments to $MAX are ignored.
——————————————————————————————————————————
511
——————————————————————————————————————————
——————————————————————————————————————————
11.21
$MIN: Return minimum value
The $MIN(x1,x2,x3,x4,x5,x6,x7,x8) function returns the lowest value from a list of as
many as eight arguments.
For example:
$MIN(-6, 5, 0, 4, 3, 7, -7, 1) = -7
$MIN(4,-6,70.3) = -6
$MIN(-6, ,-5) = -6
Omitted arguments to $MIN are ignored.
11.22
$PI: Value of pi
The $PI function returns the value of pi (π) to 15 significant digits (3.14159265358979).
11.23
$RXPI: Real base raised to integer exponent
The $RXPI(x,y) function returns the value of its first argument raised to the power of its
second argument. The second argument is initially rounded to the nearest integral
value.
Omitted arguments are set to 0. If x equals 0, and |y| is less than or equal to 0, an error
message is printed and a 0 is returned.
For example:
$RXPI(2, 3) = 23 = 8
$RXPI(.5, 1.4) = $RXPI(.5, 1) = .5
11.24
$RXPR: Real base raised to real exponent
The $RXPR(x,y) function returns the value of its first argument raised to the power of its
second argument.
If either of the following is true, an error message is printed and a 0 is returned:
x is less than zero.
●
x equals 0, and y is less than or equal to 0.
●
——————————————————————————————————————————
512
——————————————————————————————————————————
$RXPR: Real base raised to real exponent
——————————————————————————————————————————
For example:
$RXPR(9, 2) = 92 = 81
$RXPR(64, .5) = 8
$RXPR(256, .25) = 4
11.25
$SIN: Sine
The $SIN(x) function returns the sine of an argument that is given in radians. If the
returned.
11.26
$SINH: Hyperbolic sine
The $SINH(x) function returns the hyperbolic sine of an argument that is given in
radians. If the magnitude of the argument exceeds 175.366, an error message is printed
and a 0 is returned.
11.27
$SQRT: Square root
The $SQRT(x) function returns the value of the square root of the given argument. If the
argument is negative, an error message is printed and a 0 is returned.
11.28
$TAN: Tangent
The $TAN(x) function returns the tangent of an argument that is given in radians. If the
returned.
11.29
$TANH: Hyperbolic tangent
The $TANH(x) function returns the hyperbolic tangent of an argument that is given in
radians.
——————————————————————————————————————————
513
——————————————————————————————————————————
——————————————————————————————————————————
——————————————————————————————————————————
514
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
——————
CHAPTER 12
Regex Processing
As of version 6.9, the Sirius Mods includes support for regular expression (“regex”)
processing in multiple $functions and Janus SOAP methods. This support is modeled
closely on Perl's regular expression implementation.
Sirius $functions and methods offer the following variety of tasks you can accomplish
using a regex.
Simple matching:
●
You can determine whether and where a single regex pattern matches within a
single input string. See “$RegexMatch” on page 336.
●
You can apply a single regex to a set (Stringlist) of strings to find one item. See the
RegexLocate and RegexLocateUp methods, described in the Janus SOAP
Reference Manual.
●
You can apply a single regex to a set (Stringlist) of strings to find all matching items
and place them on a Stringlist. See the RegexSubset method, described in the
Janus SOAP Reference Manual.
Capturing:
●
You can append to a Stringlist the characters in an input string that are matched by
regex capturing groups. See the RegexCapture method, described in the Janus
SOAP Reference Manual.
Searching and replacing:
●
You can replace the matched characters in a single input string with a specified
string, one or many times. See “$RegexReplace” on page 339.
●
You can find the characters in a single string that are matched by one of a set
(Stringlist) of regexes, and replace the matched characters with a string from a
corresponding set (Stringlist). See the RegexReplaceCorresponding method,
described in the Janus SOAP Reference Manual.
Splitting:
●
You can use a regex repeatedly to separate a given input string into the substrings
that are matched by the regex and the substrings that are not matched, and append
to a Stringlist either or both of these sets of substrings (in combination or not with
the subset of matched substrings that are captured. See the RegexSplit method,
described in the Janus SOAP Reference Manual.
——————————————————————————————————————————
515
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
Many tools implement regular expressions, each with its own variation of supported
features. The following sections describe the Sirius regex support.
●
“Regex rules” discusses the symbols and grammar of Sirius regex.
●
“Common regex options” on page 522 and “XML Schema mode” on page 523
discuss options that modify the interpretation of a specified regex, which are
available to some or all of the Sirius regex $functions and methods.
●
“User Language programming considerations” on page 525 discusses aspects of
using Sirius regex in User Language programs.
12.1
Regex rules
When a regular expression is said to “match a string,” what is meant is that a substring
of characters within the string fit (are matched by) the pattern specified by the regex.
The “rules” observed by Sirius for regex formation and matching are primarily those
followed by the Perl programing language (as described, for example, in Programming
Perl, by Larry Wall et al, published by O'Reilly Media, Inc.; 3rd edition, July 14, 2000).
An additional reference is Mastering Regular Expressions, by Jeffrey E. F. Friedl,
published by O'Reilly Media, Inc. (2nd edition, July 15, 2002). In terms of the type of
regex engine described in this book, the Sirius regex processing is considered NFA (not
DFA, and not POSIX NFA).
Highlights of the Sirius regex support are discussed in the following subsections,
especially noting where Sirius rules differ from Perl's. If a regex feature is not mentioned
below, you should assume it is supported by Sirius to the extent that it is supported in
Perl.
12.1.1 Expression constituents
This section describes elements that constitute the actual expression pattern. The next
section describes features that modify or affect a specified pattern. These sections
describe the default case where the optional XML schema mode processing (“XML
Schema mode” on page 523) is not in effect.
These features are discussed:
●
●
●
●
●
●
“Escape sequences” on page 517
“Character classes” on page 518
“Greedy and non-greedy quantifiers” on page 519
“Capturing groups” on page 520
“Look-around subexpressions” on page 520
“Alternatives” on page 520
——————————————————————————————————————————
516
——————————————————————————————————————————
Regex rules
——————————————————————————————————————————
Escape sequences
The only escape sequences allowed in a Sirius regex are those for metacharacters and
those that are “shorthands” for special characters or character classes, as specified
below.
These metacharacter escapes are allowed in regex arguments:
\.
\[
\]

\*
\\{
\}
\|
\\
\+
\?
\$
\ˆ
Period (or dot); see “Mode modifiers” on page 521 for difference from Perl on what
is matched by an un-escaped period
Left square bracket
Right square bracket
Left, or opening, parenthesis
Right, or closing, parenthesis
Star, or asterisk
Hyphen
Left curly bracket
Right curly bracket
Vertical bar
Backslash
Plus sign
Question mark
Dollar sign
Caret, or circumflex
Note: A caret is used in this documentation to represent the character that the
keyboard program translates to X'5F'; this may be a not sign (¬) on your system.
These character shorthands are allowed:
\n
\r
\t
Linefeed (X'25')
Carriage return (X'0D')
Horizontal tab (X'05')
These class shorthands are allowed:
\b
\B
\c
\C
\d
\D
\i
\I
\s
Word boundary anchor (a position between a \w character and a non-\w character)
— but not supported as a backspace character or within a character class.
\b is only supported as of Sirius Mods 7.3.
The inverse of \b: any position that is not a word boundary anchor.
\B is only supported as of Sirius Mods 7.3.
Legal name character; equivalent to [\-_:.A-Za-z0-9]
Non-legal name character; equivalent to [ˆ\-_:.A-Za-z0-9]
Digit; equivalent to [0-9]
Non-digit; equivalent to [ˆ0-9]
Legal start-of-name character; equivalent to [_:A-Za-z]
Non-legal start-of-name character; equivalent to [ˆ_:A-Za-z]
Whitespace character; equivalent to [ \r\n\t]
——————————————————————————————————————————
517
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
\S
\w
\W
Non-whitespace; equivalent to [ˆ \r\n\t]
Any letter (uppercase or lowercase), any digit, or the underscore.
\w is only supported as of Sirius Mods 7.0.
The inverse of \w: any non-letter or non-digit except the underscore.
\W is only supported as of Sirius Mods 7.0.
Prior to Sirius Mods version 7.0, the class shorthands above were not allowed within
character classes.
Character classes
In character classes (which “match any character in the square brackets”):
●
The only ranges allowed are subsets of uppercase letters, lowcase letters, or digits.
For example, [A-z] is not legal; [A-Za-z] is legal; [a-9] is not legal.
Because of the gaps in the EBCDIC encoding, you can specify [A-Z], but internally
that is converted to [A-IJ-RS-Z]; and similarly for [a-z].
●
Multi-character escape sequences (for example, \s, \c) are allowed within
character classes as of version 7.0 of the Sirius Mods. However, they are not
allowed as either side in a range.
Prior to version 7.0 of the Sirius Mods, multi-character escapes are not allowed
within character classes.
●
An unescaped hyphen (-) is allowed if it occurs as the first character (or the
second, if the first is ˆ) or as the last character in a character class expression. An
escaped hyphen (\-) is allowed in all positions.
All the following are allowed:
[-A-Z158]
[ˆ-A-Z158]
[158A-Z-]
[158A-Z0-]
But [A-F-K] is not allowed. And a hyphen is not allowed as the left or right
character in the range expression itself (["--], for example, is not allowed).
Prior to version 7.0 of the Sirius Mods, unescaped hyphens are not allowed within
character classes.
●
Some bracket characters ([ or ], from any of the several character codes that
produce a left or right square bracket in EBCDIC) do not have to be escaped. A
bracket character does not require a preceding escape character if it is:
——————————————————————————————————————————
518
——————————————————————————————————————————
Regex rules
——————————————————————————————————————————
▪
A right bracket (]) that is outside of, not part of, a character class expression.
So, (1]9) matches 0001]9zzz.
▪
A right bracket that is the first character — or the second, if the first is a caret
(ˆ) — in a character class expression. So, []xxx] and [ˆ]xxx] are legal.
▪
A left bracket that occurs anywhere in a character class expression. So,
[abc[] is legal and matches any of these four characters: a b c [
A left bracket that occurs outside of a character class expression must always
be escaped.
Although not required, escape characters may be used in the cases cited above.
Prior to version 7.0 of the Sirius Mods, unescaped brackets are not allowed within
character classes.
Greedy and non-greedy quantifiers
Both greedy and non-greedy matching are supported. That is, if there is more than
one plausible match for a greedy quantifier (*, +, ?, {min,max}), which govern how
many input string characters the preceding regex item may try to match), the longest one
is selected. In contrast, the non-greedy (aka “lazy”) quantifiers (*?, +?, ??,
{min,max}?) select the minimum number of characters needed to satisfy a match.
For example, in Sirius methods and $functions, the regex <.+> greedily matches the
entire input string <tag1 att=x><tag2 att=y><tag3 att=z>, although its set of
plausible matches also includes <tag1 att=x> and <tag2 att=y>.
The regex <.+?>, however, lazily matches just <tag1 att=x>, the shortest of the
plausible matches.
Note: Since ?? is a Model 204 dummy string signifier, you may need to use a User
Language expression such as '?' With '?' if you want to use the ?? quantifier.
Understanding greediness becomes more important when the string that a regex
matches is being replaced by another string. For an example, see the “Notes” section
for the $RegexReplace function on page 341.
Prior to version 7.0 of the Sirius Mods, the “lazy” quantifiers (*?, +?, ??, {min,max})
are not supported.
——————————————————————————————————————————
519
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
Capturing groups
●
Extraction of repeating capture groups from a string is different in Perl and User
Language. If there are multiple matches by a repeated group, Perl replaces each
capture with the next one, ending up with only the final capture. User Language
saves each capture and concatenates them when finished.
For example, if this is the regex:
9([A-Z])*9
And this is the input string:
xxx9ABCDEF9yyy
In both the Sirius Mods and Perl, the “greedy quantifier” * matches as many times
as it can, stopping at the second 9. The resulting capture in Sirius $functions and
methods is ABCDEF, the concatenation of six one-character matches. In Perl, the
resulting capture is F.
●
A subexpression that is a validly formed capturing group that is nested within a noncapturing subexpression is still a capturing group. The regex (?:[1-9]*(a+))
matches 123aa and captures aa.
Look-around subexpressions
Although look-ahead subexpressions in a regex are supported, look-behind
subexpressions are not supported. Look-behind specifications begin with (?<= or
(?<!.
The only supported parenthesized subexpression sequences that begin with a question
mark are the following, which are all non-capturing:
(?:
(?=
(?!
Denotes a non-capturing group
Denotes a positive look-ahead
Denotes a negative look-ahead
Alternatives
Alternatives (indicated by |) are evaluated from left to right, and evaluation is “shortcircuited” (that is, it stops as soon as it finds a match).
Empty expressions, for example, empty alternatives, are supported. The following
regex matches A9, B9, and 9, capturing respectively A, B, and the null string:
(A|B|)9
——————————————————————————————————————————
520
——————————————————————————————————————————
Regex rules
——————————————————————————————————————————
An empty alternative (like the |, above, that is followed only by the closing parenthesis)
is always True.
Note: Sirius and Perl make a special case of a regex that has an empty alternative on
the left (or anywhere but at the right end). You might think that such an “always true”
alternative gets selected before, and thereby prevents the evaluation of, the alternatives
to its right. However, in such a regex, this empty alternative is evaluated as the last
alternative instead of according to its actual position.
For example, the regex (|A|B)9 matches each of the strings A9, B9, and 9. However,
since the evaluation of the empty alternative is implicitly postponed until the other
alternatives are tried, the (|A|B) group captures, respectively, A, B, and the null string.
12.1.2 Features that affect the whole expression
Unicode
Unicode is not supported.
Locales
Locales are not supported.
Mode modifiers
Mode modifiers are settings that influence how a regex is applied. Sirius mode modifiers
apply to the entire regex; none can be applied to part of a regex.
●
In Sirius regex, the dot (.) metacharacter matches any character except for a
carriage return or linefeed.
Note: In Perl, which does not consider a carriage return an end-of-line character, a
dot always matches a carriage return as well.
To initiate dot-matches-all mode, in which dot matches any character, Perl uses an
s character after the regex-ending /. Sirius regex $functions and methods have an
“options” argument that can initiate this mode (value S), as described in “Common
regex options” on page 522.
●
Perl supports a case-insensitive matching mode that you can apply globally (i
after the regex-ending /) or partially (started by (?i) and ended by (?-i))) to a
regex. Sirius provides only a global case-insensitivity switch, which does not use
the Perl signifier. Instead, Sirius uses an “options” argument to initiate caseinsensitive matching (value I), as described, below, in “Common regex options” on
page 522.
——————————————————————————————————————————
521
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
●
In multi-line mode, the caret (ˆ) and dollar sign ($) anchor characters may match a
position wherever a newline character occurs in the target string — they are not
restricted to matching only at the beginning and end of the string. To enter this
mode, Perl uses an m after the regex-ending /. Sirius uses an “options” argument
to initiate this mode (value M), as described, below, in “Common regex options”.
●
In Perl, comments may be included in a regex between the number sign (#) and a
newline. Sirius does not recognize this convention, and the number-sign character
is not a metacharacter.
12.2
Common regex options
Sirius regex $functions and methods have an optional “options” argument that lets you
invoke one or more operating modes that modify how the regex is applied. In most
cases, the functionality provided by the option is similar to what Perl provides, but Perl
uses a different notation to invoke it.
The options argument is a string of one or more of the following single-letter options.
Not all options are available to all regex $functions and methods. — the individual
$function and method descriptions list the options available to that function or method.
I
Do case-insensitive matching between the input string(s) and the regex. Treat the
uppercase and lowercase variants of letters as equivalent.
S
Dot-All mode. If this mode is not specified, a dot (.), also called a point, matches
any single character except X'0D' (carriage return) and X'25' (linefeed). In Dot-All
mode, a dot also matches carriage return and linefeed characters.
M
Multi-line mode. If this mode is not specified, a caret (ˆ) or a not sign (¬) —
whichever key your keyboard program translates to X'5F' — matches only the
position at the very start of the string, and dollar sign ($) matches only the position
at the very end. (This documentation uses the caret.)
The caret and dollar sign are position-identifying characters known as “anchors,”
which match the beginning and end, respectively, of a line or string. They do not
match any text.
In M mode, a caret also matches the position immediately after any end-of-line
indicator (carriage return, linefeed, carriage-return/linefeed), and a dollar sign also
matches the position immediately before any end-of-line indicator.
M mode is ignored if option C (XML Schema mode) is also specified, since caret
and dollar sign are not metacharacters in C mode.
C
XML Schema mode. See, below, “XML Schema mode” on page 523.
——————————————————————————————————————————
522
——————————————————————————————————————————
Common regex options
——————————————————————————————————————————
G
Global replacement of matched substrings (for methods and $functions that
provide replacement substrings for matched substrings).
If this mode is not specified, a replacement string replaces the first matched
substring only. In G mode, every occurrence of the match is replaced.
A
Replace as is (for methods and $functions that provide replacement substrings for
matched substrings.
If this mode is specified, the replacement string is copied as is. No escapes are
recognized; a $n combination is interpreted as a literal and not as a special
marker; and so on.
12.3
XML Schema mode
An optional “options” argument lets you invoke XML Schema mode. In this mode (not
available in Perl), the regex matching is done according to the rules for regular
expressions in the W3C XML Schema language specification (the “Regular Expressions”
appendix, currently at http://www.w3.org/TR/xmlschema-2/#regexs).
This mode is designed for testing regexes for suitability for validating strings in a schema
document (an XML document that constitutes an XML schema). Although it is available
in most of the Sirius regex $functions and methods, it is intended primarily for matching
and not for capturing or replacing.
The Sirius regex rules described in “Regex rules” on page 516 still apply in XML Schema
mode, except:
●
In a regex, no characters are recognized as anchors, and any regex is treated as if it
is anchored at both ends. The entire regex must match the entire target string
(although you can construct an unanchored match, as described in the “Regular
Expressions” appendix).
The regex ABC in XML Schema mode is equivalent to ˆ(?:ABC)$ in non-XML
Schema mode, where the (?: indicates a “non-capturing” group.
Related to this, or as a consequence of this implicit anchoring:
●
▪
The usual anchoring-atoms, ˆ and $, are treated as ordinary characters in a
regex, and you may not escape them.
▪
If the multi-line mode option (see “Common regex options” on page 522) is
specified along with XML Schema mode, multi-line mode is ignored.
The two-character sequence (? is not valid in a regex. You can use a pair of
parentheses for grouping, but capturing is not part of the XML Schema regex
——————————————————————————————————————————
523
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
specification, nor are non-capturing and look-aheads, whose indicators begin with a
(? sequence.
If you specify the XML Schema mode option in a $function or method that makes
use of capturing (or replacing), however, any capturing groups you use in the regex
or replacement string(s) do perform their usual operation.
●
A bracket character ([ or ] requires a preceding escape character if it is:
▪
A right bracket (]) that is outside of, not part of, a character class expression.
So, (1\]9) matches 0001]9zzz, but (1]9) is not allowed.
▪
A right bracket that is the first character — or the second, if the first is a caret
(ˆ) — in a character class expression. So, [\]xxx] and [ˆ\]xxx] are
allowed.
▪
A left bracket that occurs anywhere in a character class expression. So,
[abc\[] is allowed.
A left bracket that occurs outside of a character class expression must always
be escaped.
These cases are compiler errors unless the cited bracket characters are escaped.
●
Character class subtraction is supported as of Sirius Mods version 7.0. You can
exclude a subset of characters from the characters already designated to be in the
class. This is only allowed in XML Schema mode, and it is not allowed in Perl.
This feature lets you specify a character class like the following, which matches
anything from A to Z except D, I, O, Q, U, or V:
[A-Z-[DIOQUV]]
You can also nest subtractions, as in:
[\w-[A-Z-[DIOQUV]]]
Characters immediately after the right bracket of a subtracted character class are
not allowed. [A-Z-[DIOQUV]abc] is an invalid character class.
You can also subtract a negated character class:
●
[A-Z-[ˆDIOQUV]] is valid.
If the Dot-All mode or case-insensitive mode option (see “Common regex options”
on page 522) is specified along with XML Schema mode, Dot-All mode or caseinsensitive mode works as usual.
——————————————————————————————————————————
524
——————————————————————————————————————————
——————————————————————————————————————————
12.4
These are issues of note when writing regex requests:
●
Sirius regex processing can use considerable user stack (PDL) space and STBL
space:
▪
A program running with a relatively small (less than 3000) setting of the
Model 204 LPDLST parameter is subject to a user restart due to PDL overflow,
even with relatively simple regular expressions. Regular expression
compilation and evaluation can sometimes be recursive, with each level of
recursion using a certain amount of PDL space. For certain complex regular
expressions, a large amount of PDL space may be used.
To reset LPDLST, you can use, for example, UTABLE LPDLST 3000. Prior to
Sirius Mods version 7.0, the recommended minimum value was 8000.
▪
●
In general, there must be at least 8500 bytes available in STBL (some routines
use less). Using UTABLE LSTBL 9000 is sufficient if the rest of the User
Language program requires almost no STBL space.
A question mark character (?) is a reserved character, or metacharacter, in a regex
expression. As pointed out in a preceding subsection, the ?? character combination
in a User Language regex is ambiguous, meaning either a regex quantifier or a User
Language dummy string. In that case, the dummy string interpretation prevails, and
you must use an expression like '?' With '?' to code the regex quantifier.
Similarly, the User Language dummy-string signifiers ?$ and ?& take precedence if
those character sequences occur in a regex. To use ?$ or ?& in a regex, you must
use one or two escape characters, respectively, after the question mark.
●
A caret (ˆ) is used in this documentation to represent the character that the
keyboard program translates to X'5F'; this may be a not sign (¬) on your system.
——————————————————————————————————————————
525
——————————————————————————————————————————
Regex Processing
——————————————————————————————————————————
——————————————————————————————————————————
526
——————————————————————————————————————————
——————————————————————————————————————————
——————
CHAPTER 13
This chapter presents date processing issues, including usage of the Sirius Functions
past the year 1999, an explanation of its processing of dates, and any rules and
restrictions you must follow to achieve correct results using date values with the Sirius
Functions.
The Sirius Functions uses dates in the following ways:
●
to examine the CPU clock (as returned by the STCK hardware instruction) to
determine the current date, in case the Sirius Functions is under a rental or trial
agreement
●
as arguments to various $functions, and returned values from them
●
See “Other $functions using date values” on page 542 for date processing
considerations for $functions that deal with dates from Model 204 internal
structures.
Please note that in addition to the above date processing performed by the Sirius
Functions, you also can use any number of Sirius $functions to manipulate values which
might contain two digit year date values. The customer must ensure that any application
using that data has an algorithm or rule for unambiguously determining the correct
century for the values.
To correctly use the Sirius Functions past the year 1999, version 4.6 of the Sirius Mods,
or later, is required. For headers on pages or rows that occur on printed pages or
displayed screens, Sirius Software products generally use a full four digit year format,
although they may display dates with two digit years in circumstances where the proper
century can be inferred from the context.
Above and beyond the post-1999 requirements specific to the Sirius Functions, you must
examine all uses of date values in your applications to ensure that each of your
applications produces correct results. Furthermore, both the operating system and
Model 204 must correctly process and transmit dates beyond 1999 in order for the Sirius
Functions to operate properly.
Most Sirius date processing involves the use of datetime $functions. This chapter refers
to datetime $functions in two product groups:
1.
The Sirius Functions, which are documented in the Sirius Functions Reference
Manual.
——————————————————————————————————————————
527
——————————————————————————————————————————
——————————————————————————————————————————
2.
The Sir2000 User Language Tools Functions, which are documented in the Sir2000
User Language Tools Reference Manual. These $functions are only available to
users of the Sir2000 User Language Tools.
Occasionally, we also refer to “all Sirius datetime $functions”; this stands for all date
processing $functions delivered by Sirius Software, in any product.
In operational terms, there are two classes of datetime $functions:
1.
$Functions using a numeric value to represent a datetime, where 0 represents
12:00 AM, 1 January 1900; for example, $SIR_DATE2NM and $SIR_NM2DATE
(number of milliseconds since the start of 1900).
These $functions, and $SIR_DATE, have the following error return values:
●
●
-9.E12 for numeric result $functions
null string for string result $functions
They also perform non-strict matching of date strings to date formats; for example,
a leading blank is allowed for the HH token.
All numeric datetime $functions, and $SIR_DATE, are part of the Sirius Functions.
2.
Other $functions that only manipulate strings and associated datetime formats
($SIR_DATE not included in this class); for example, $SIR_DATECHG (add number
of days to given date).
These $functions have error return values of a variable number of asterisks (or, in
the case of $SIR_DATEDIF, the value 99,999,999). They also perform strict
matching of date strings to date formats; for example, a leading blank is not allowed
for the HH token. These $functions produce the same results as CCA $DATExxx
functions, with additional enhancements.
These string format datetime $functions are available only with the Sir2000 User
Language Tools. Some references to these functions are made in this manual,
nonetheless, to illustrate some datetime $function considerations.
In addition to these two classes of functions that deal only with datetime $functions,
there are some $functions that deal with dates from Model 204 internal structures; see
“Other $functions using date values” on page 542.
See “Strict and non-strict format matching” on page 536 for a discussion of strict and
non-strict format matching, including a technique for accomplishing strict date checking
using the non-strict $functions.
The rest of this chapter contains a discussion of datetime formats, valid datetime strings,
processing of two-digit year values, and datetime error handling. It also contains
example datetime formats and corresponding example datetime strings. Finally, there is
a list of benefits of Sirius datetime processing.
——————————————————————————————————————————
528
——————————————————————————————————————————
Datetime Formats
——————————————————————————————————————————
13.1
Datetime Formats
The representation of a date is determined by a datetime format. This value is a
character string, composed of the concatenation of tokens (e.g., “YYYY” for a 4 digit
year, and “MI” for minutes) and separator characters (e.g., “/” in “MM/DD/YY” for twodigit month, day, and year separated by slashes).
These datetime format strings are used in many Sirius Software products in addition to
the Sirius Functions. The products using datetime format strings are:
●
●
●
●
●
●
●
●
●
Fast/Unload
Janus Open Client
Janus Open Server
Janus Specialty Data Store
Janus Web Server
SirDBA
Sirius Functions
The rules for these datetime format strings are consistent throughout all Sirius products,
though certain uses of these strings might impose extra restrictions. For example, a
leading blank is allowed for the HH, DD, and MM parts of a date argument using a nonstrict date $function, such as $SIR_DATE2NS, but is not allowed for the strict date
$functions (i.e., the Sir2000 User Language Tools Functions).
There are certain rules applied to determine if a format is valid. The basic rules are:
1.
If a format string contains a numeric datetime token (i.e. “ND”, “NM”, or “NS”), then
the format string must consist of only one token. Numeric datetime tokens are only
supported in format strings for the Sir2000 Field Migration Facility.
2.
You must specify at least one time, weekday, or date token.
3.
Except for “weekday”, you can't specify redundant information. More specifically
this means
●
Except for “I”, no token can be specified twice.
●
At most one year format (contains Y) can be specified.
●
At most one month format (contains MON, Mon, or MM) can be specified.
●
At most one day format (DD or Day) can be specified.
●
At most one weekday format (WKD, Wkd, WKDAY, or Wkday) can be specified.
●
If AM is specified, then PM can not be specified.
——————————————————————————————————————————
529
——————————————————————————————————————————
——————————————————————————————————————————
●
At most one fractions-of-a-second format (contains X) can be specified.
●
If DDD is specified, then neither a day nor month format can be.
4.
If ZYY is specified in a format string, no other token that denotes a variable-length
value may be used.
5.
If a format string contains other tokens that denote variable length values, then an *
token may only appear as the last character of the format string.
6.
The DAY token may not be immediately followed by another token whose value may
be numeric, regardless of whether the following token repsents a variable length
value. Thus, DAY may not be followed by *, I, YY, YYYY, CYY, MM, HH, MI, SS, X,
XX, or XXX; DAY may not be followed by a decimal digit separator, and DAY may
not be followed by a quote followed by a decimal digit.
7.
When a pair of format strings are used for transforming date values, e.g. for
$SIR_DATECNV or processing of updates to SIRFIELD RELATEd fields, additional
rules apply to the pattern matching tokens:
●
If one of the format strings includes one or more “I” tokens, then the other
format string must contain the same number of “I” tokens. Note that the
placement of “I” tokens within the format strings is not restricted. The “I” tokens
are processed left to right, with each character from the input string that
corresponds to the nth “I” token in the input format being copied unchanged to
the character position in the output string that corresponds to the nth “I” token in
the output format.
●
If one of the format strings contains an “*” token, then the other format string
must also contain an “*” token. All of the characters from the input string that
correspond to the “*” token in the input format, if any, are copied unaltered to
the output string, begining in the position that corresponds to the “*” token in the
output format.
The $functions with both an input and output format, e.g. $SIR_DATECNV, are only
available in the Sir2000 User Language Tools. SIRFIELD is part of the Sir2000
Field Migration Facility.
8.
The maximum length of a format string is 100 characters.
Note: A common mistake is to use “MM” for minutes; it should be “MI”.
The valid tokens in a date format are shown in the following list. In general, the output
format rule for a token is shown. For some of the $functions, the input format rule for a
token is the same as the output format rule; this is the definition of “strict date format
matching”. However, non-strict $functions sometimes allow a string to match a token on
input that would not be produced by that token on output.
——————————————————————————————————————————
530
——————————————————————————————————————————
Datetime Formats
——————————————————————————————————————————
All of the tokens which match alpabetic strings (e.g., “MON”) match any case for nonstrict matching. All other tokens which have differing strict and non-strict matching rules
are listed under “Special date format rules” in the index at the back of the manual, and
usage notes for them are contained in “Datetime and format examples” on page 537.
Each input datetime format argument in the description of a $function specificies
whether the use of the format observes strict or non-strict format matching. See “Strict
and non-strict format matching” on page 536.
NM
NS
ND
*
I
"
YYYY
YY
CYY
ZYY
MONTH
Month
MON
numeric datetime value containing the number of milliseconds (1/1000 of a
second) since January 1, 1900 at 12:00 AM. (This token is allowed only in
the Sir2000 Field Migration Facility.)
numeric datetime value containing the number seconds since January 1,
1900 at 12:00 AM. (This token is allowed only in the Sir2000 Field Migration
Facility.)
numeric date value containing the number of days since January 1, 1900.
(This token is allowed only in the Sir2000 Field Migration Facility.)
Ignore entire variable-length substring matching pattern, if any, when only
retrieving a date value. Substitute with null string when only creating a date
value. When copying date values, copy entire variable-length substring
matching pattern, if any, from input value to location identified by * token in
output string. See “Datetime and format examples” on page 537.
Ignore corresponding input character when only retrieving a date value.
Store a blank in corresponding output character when only creating a date
value. When copying date values, copy each character matching an I token
from from the input value to location in the output string identified by the
corresping I token in the output format. See “Datetime and format examples”
on page 537.
Following character is “quoted”, that is, it acts as a separator character. See
“Datetime and format examples” on page 537. This token is available
starting with version 5.2 of the Sirius Mods.
4 digit year
2 digit year
Year minus 1900 (3 digits, including any leading zero). See “Datetime and
format examples” on page 537.
Year minus 1900, two-digit or three-digit year number, excluding any leading
zero (variable length data). Non-strict $functions allow a three-digit number
with leading zero on input, but any number less than 100 always produces a
two-digit number on output. See “Datetime and format examples” on page
537.
Full month name (upper case variable length). Non-strict $functions allow
any mixture of upper and lower case on input, but all upper case is always
produced on output.
Full month name (mixed case variable length). Non-strict $functions allow
any mixture of upper and lower case on input, but initial upper case letter
followed by all lower case is always produced on output.
Three character month abbreviation (upper case). Non-strict $functions
allow any mixture of upper and lower case on input, but all upper case is
always produced on output.
——————————————————————————————————————————
531
——————————————————————————————————————————
——————————————————————————————————————————
Mon
MM
BM
DDD
DD
BD
DAY
WKDAY
Wkday
WKD
Wkd
HH
BH
MI
SS
X
XX
Three character month abbreviation (mixed case). Non-strict $functions
allow any mixture of upper and lower case on input, but initial upper case
letter followed by all lower case is always produced on output.
Two-digit month number. Non-strict $functions allow a two-character
number with leading blank on input, but two decimal digits are always
produced on output. See “Datetime and format examples” on page 537.
Two-character month number; if less than 10, first character is blank. Nonstrict $functions allow a two-digit number with leading zero on input, but any
number less than 10 always produces a blank followed by a decimal digit on
output. See “Datetime and format examples” on page 537. This token is
available starting with version 5.2 of the Sirius Mods.
Three digit Julian day number
Two-digit day number. Non-strict $functions allow a two-character number
with leading blank on input, but two decimal digits are always produced on
output. See “Datetime and format examples” on page 537.
Two-character day number; if less than 10, first character is blank. Nonstrict $functions allow a two-digit number with leading zero on input, but any
One-digit or two-digit day number (variable length data). Non-strict
$functions allow a two-digit number with leading zero on input, but any
number less than 10 always produces a one-digit number on output. See
“Datetime and format examples” on page 537.
Full day of week name (upper case variable length). Non-strict $functions
allow any mixture of upper and lower case on input, but all upper case is
always produced on output.
Full day of week name (mixed case variable length). Non-strict $functions
allow any mixture of upper and lower case on input, but initial upper case
letter followed by all lower case is always produced on output.
Three character day of week abbreviation (upper case). Non-strict
$functions allow any mixture of upper and lower case on input, but all upper
case is always produced on output.
Three character day of week abbreviation (mixed case). Non-strict
$functions allow any mixture of upper and lower case on input, but initial
upper case letter followed by all lower case is always produced on output.
Two-digit hour number. Non-strict $functions allow a two-character number
with leading blank on input, but two decimal digits are always produced on
output. See “Datetime and format examples” on page 537.
Two-character hour number; if less than 10, first character is blank. Nonstrict $functions allow a two-digit number with leading zero on input, but any
Two-digit minute number
Two-digit second number
Tenths of a second
Hundredths of a second
——————————————————————————————————————————
532
——————————————————————————————————————————
Datetime Formats
——————————————————————————————————————————
XXX
AM
PM
Thousandths of a second (milliseconds)
AM/PM indicator
AM/PM indicator
The valid separators in a date format are:
blank (“ ”)
apostrophe (“'”)
slash (“/”)
colon (“:”)
hyphen (“-”)
back slash (“\”)
period (“.”)
comma (“,”)
underscore (“_”)
left parenthesis (“(”)
right parenthesis (“)”)
plus (“+”)
vertical bar (“|”)
equals (“=”)
ampersand (“&”)
at sign (“@”)
sharp (“#”)
the decimal digits (“0” - “9”).
In addition, any character may be a separator character if preceeded by the quoting
character (").
See “Datetime and format examples” on page 537 for examples which include use of
various separator characters.
Decimal digits as separator charactors, and the quoting character are available starting
with version 5.2 of the Sirius Mods.
13.2
Valid Datetimes
For a datetime string to be valid it must meet the following criteria:
●
●
●
Its length must be less than 128 characters.
It must be compatible with its corresponding format string.
It must represent a valid date and/or time. For example, at most 23:59:59.999 for a
time, 01-12 for a month, 01-31 or less (depending on the month) for a day, February
29 is only valid in leap years (only centuries divisible by 4 are leap years: 2000 is
but neither 1800, 1900, nor 2100 are). Note: weekdays are not checked for
consistency against the date; e.g., both Saturday, 02/15/97 and Friday, 02/15/97 are
valid.
——————————————————————————————————————————
533
——————————————————————————————————————————
——————————————————————————————————————————
●
It must be within the date range allowed for the corresponding format. A datetime
string used with a CYY or ZYY format can only represent dates from 1900 to 2899,
inclusive. A datetime string used with a YY format can only represent dates in a
range of 100 or less years, as determined by CENTSPAN and SPANSIZE. The
valid range of dates for all other formats is from 1 January 1753 thru 31 December
9999.
13.3
Processing Dates With Two-Digit Year Values
A date field with only two digits for the year value is capable of representing a range of
up to one hundred years. When we compare a pair of two-digit year values we are
accustomed to thinking of the century as fixed, so that all dates are either “19xx” or
“20xx”. However, a date field with two-digit year values can actually represent dates
from two different centuries, provided that the range of dates does not exceed 100
years.
13.3.1 CENTSPAN
CENTSPAN provides a mechanism for unambiguously converting dates with two-digit
year values into dates with four-digit year values. The CENTSPAN mechanism allows
two-digit year values to span two centuries without confusion. CENTSPAN identifies the
four-digit year value that is the start of a range of years represented by the two-digit
year values.
CENTSPAN may be specified as an absolute unsigned four digit value between 1753
and 9999, or it may be specified as a relative signed value between -99 and +99,
inclusive. A relative CENTSPAN value is dynamically converted to an effective absolute
value before it is used to perform a YY to YYYY conversion. The effective CENTSPAN
value is formed by adding the relative CENTSPAN to the current four-digit year value at
the time the relative value is converted.
HHLL = absolute or effective
CENTSPAN
HHLL
HHLL+99
Defines 100 year period
Example:
CENTSPAN = -50
current date = 1997
effective CENTSPAN = 1947
Conversion rules, YY to YYYY
if YY < LL YYYY = (HH+1)YY
else
YYYY = HHYY
2046
2000
1947
19YY
20YY
A simple algorithm is used to convert a two-digit year value (YY) to a four-digit year
value, using a four-digit absolute or effective CENTSPAN value (HHLL). If the two-digit
year value is less than the low-order two digits of the CENTSPAN value, then the
resulting century is one greater than the high-order two digits of the CENTSPAN value.
Otherwise the resulting century is the same as the high-order two digits of the
CENTSPAN value.
——————————————————————————————————————————
534
——————————————————————————————————————————
Processing Dates With Two-Digit Year Values
——————————————————————————————————————————
Using all one hundred available years for mapping two-digit year values can cause
significant confusion and result in data integrity errors. This is because dates just above
and just below the 100-year window are mapped to the other end of the window. From
our previous example, the date “47” will be intepreted as 1947, when it could have
conceivably been 2047. Simlarly, the date “46” will be intepreted as 2046, when it might
have been 1946.
CENTSPAN
(1947)
100 year period
CENTSPAN+99
(2046)
ambiguity at each endpoint
CENTSPAN too high
CENTSPAN too low
If CENTSPAN is set to a value that is too high, dates that are just prior to CENTSPAN
will appear to occur 100 years hence. If CENTSPAN is set to a value that is too low,
dates that fall just after CENTSPAN+99 will appear to have occured 100 years earlier. A
full one-hundred year window also can not detect attempts to represent more than one
hundred years of values with a two digit year.
13.3.2 SPANSIZE
Sirius has devised a method to protect from the ambiguities that can occur at each end
of the 100-year window defined by CENTSPAN. SPANSIZE is used to restrict the size
of the window used for mapping two-digit year values. The effect is to create two guard
bands, one just below the date window and one just above. An attempt to represent a
date value that lands in a guard band produces an error.
Each guard band contains CENTSPAN-SPANSIZE years, hence a SPANSIZE of 100
removes the protection. The default SPANSIZE is 90, which provides protection for two
ten year windows: one below the CENTSPAN setting and one starting at
CENTSPAN+90. From our previous example:
Example:
1947
1937-1946
CENTSPAN = -50
SPANSIZE = 90
current date = 1997
2000
20YY
19YY
endpoint YY values illegal
2036
2037-2046
An attempt to represent the values “37” through “46” will be rejected. This protects the
range 1937 through 1946 as well as the range 2037 through 2046. Note that an
intended value of 2047, expressed as “47” will be accepted and interpreted as 1947. In
general a smaller SPANSIZE provides the highest assurance of correct mappings.
However, any setting of SPANSIZE less than 100 will probably detect the case where a
range greater than one hundred years is being used.
——————————————————————————————————————————
535
——————————————————————————————————————————
——————————————————————————————————————————
13.4
Strict and non-strict format matching
As mentioned in “Datetime Formats” on page 529, for some of the $functions, the input
format rule for a token is the same as the output format rule; this is the definition of “strict
date format matching”. However, non-strict $functions sometimes allow a string to
match a token on input that would not be produced by that token on output. The types of
strict matching are as follows:
Alpha tokens For alphabetic tokens (e.g., Month), a strict match requires the input
value to be the correct case. For example, the “MON” token is strictly
matched by “JAN” but not by “Jan”, and the reverse is true for the “Mon”
token. For non-strict matching, the alpabetic tokens are matched by any
combination of upper and lower case input.
HH, MM, DD
For these tokens, a strict match requires a leading zero for values less
than 10. For non-strict matching, a value less than 10 can also be
represented by a leading blank followed by a single numeric digit.
BH, BM, BD
For these tokens, a strict match requires a leading blank for values less
than 10. For non-strict matching, a value less than 10 can also be
represented by a leading zero followed by a numeric digit.
DAY
For this token, a strict match requires a single digit for values less than
10. For non-strict matching, a value less than 10 can also be
represented by a leading zero followed by a numeric digit.
ZYY
For this token, a strict match requires two digits for values less than 100.
For non-strict matching, a value less than 100 can also be represented
by a leading zero followed by a two numeric digits.
Since the strict $functions are only available in the Sir2000 User Language Tools, if you
wish to check a datetime string using strict rules, you can use the following technique
with the non-strict date $functions:
IF <date> EQ '' OR <date> NE $SIR_NM2DATE($SIR_DATE2NM(<date>, <fmt>), <fmt>) THEN
<error handling>
END IF
——————————————————————————————————————————
536
——————————————————————————————————————————
Datetime and format examples
——————————————————————————————————————————
13.5
There is an extensive set of format tokens, as shown in “Datetime Formats” on page
529. These tokens and the various separator characters can be combined in almost
limitless possibility, giving rise to an extremely large set of datetime formats. This
section provides examples of some common datetime formats, and also tries to explain
the use of some of the format tokens which might not be obvious. It also has examples
for formats which have usage with the Sirius Functions which differs from their usage
with other Sirius products. These are noted in the examples and are indexed at the back
of this manual under the heading “Special date format rules”. Each example format is
explained and also presented with some matching datetimes; again, bear in mind that
these tokens can be combined in very many ways and only a very few are shown here.
It is assumed that these examples are invoked sometime between the years 1998-2040,
as the basis for relative CENTSPAN calculations.
YYMMDD This is the common 6-digit date format which supports sort order if all dates
are within a single century. The following User Language fragment
IF $SIR_DATE2ND('960229', 'YYMMDD') > -9E12 THEN
PRINT 'OK'
END IF
prints the value “OK”.
YYYYMMDD
This is the common 8-digit date format which supports sort order with dates
in 2 centuries. The following User Language fragment
%N = $SIR_DATE2ND('921212', 'YYMMDD')
PRINT $SIR_ND2DATE(%N, 'YYYYMMDD')
prints the value 19921212.
MM/DD/YY
This is the U.S. 6-digit date format for display. The following User Language
fragment
IF $SIR_DATE2ND('12/14/94', 'MM/DD/YY') > -9E12 THEN
PRINT 'OK'
END IF
Notes:
●
With non-strict format matching, such as $SIR_DATE2ND, the leading
zero corresponding to an MM token may be given as a blank, thus
——————————————————————————————————————————
537
——————————————————————————————————————————
——————————————————————————————————————————
allowing “ 7/15/98”. With strict matching, however, such leading blank is
not allowed for MM; a leading blank month value with a strict $function
(i.e., one of the Sir2000 User Language Tools Functions) requires the
BM token. If the data contains leading zeroes in some month instances
and leading blanks in others, you must use a non-strict $function. The
BM token is available starting with version 5.2 of the Sirius Functions.
DD.MM.YY
This is a European 6-digit date format for display. The following User
Language fragment
IF $SIR_DATE2ND('14.12.94', 'DD.MM.YY') > -9E12 THEN
PRINT 'OK'
END IF
Notes:
●
With non-strict format matching, such as $SIR_DATE2ND, the leading
zero corresponding to a DD token may be given as a blank, thus
allowing “ 1.01.00”. With strict matching, however, such leading blank is
not allowed for DD; a leading blank day value with a strict $function (i.e.,
one of the Sir2000 User Language Tools Functions) requires the BD
token. If the data contains leading zero days in some instances and
leading blanks in others, you must use a non-strict $function. The BD
token is available starting with version 5.2 of the Sirius Functions.
Wkday, DAY Month YYYY "A"T HH:MI
This is a format which could be used for report headers. The following User
Language fragment
PRINT $SIR_DATE( 'Wkday, DAY Month YYYY "A"T HH:MI')
prints a value like “Friday, 7 February 1998 AT 21:33”.
Notes:
●
If an input format contains AM or PM, then the time (HH:MI) must be
between 00:01 and 12:00 and must be accompanied by either AM or
PM.
●
If an input format contains DAY (e.g., “DAY MON YY”) with non-strict
format matching, such as $SIR_DATE2ND, the string matching it may
have a leading zero, thus allowing “06 MAY 98”. With strict matching
$functions (i.e., one of the Sir2000 User Language Tools Functions)
——————————————————————————————————————————
538
——————————————————————————————————————————
——————————————————————————————————————————
however, such leading zero is not allowed for DAY; a single digit must
be supplied for days 1 through 9.
●
YYIIII
If an input format contains HH with non-strict format matching, such as
$SIR_DATE2ND, the string matching it may have a leading blank, thus
allowing “ 8:30”. With strict matching, however, such leading blank is
not allowed for HH; a leading blank hour value with a strict $function
(i.e., one of the Sir2000 User Language Tools Functions) requires the
BH token. If the data contains leading zero hours in some instances
and leading blanks in others, you must use a non-strict $function. The
BH token is available starting with version 5.2 of the Sirius Functions.
This is a format which could be used for data which contains a 2-digit year
prefixing other information, such as a sequence number. The following User
Language fragment
%D = $SIR_DATE2ND('92ABCD', 'YYIIII')
PRINT $SIR_ND2DATE(%D + 10*365.25, 'YY')
prints the value “02”.
Note:
●
When a pair of format strings are used for transforming date values, e.g.
for $SIR_DATECNV or processing of updates to SIRFIELD RELATEd
fields, both formats must have the same number of I tokens.
The $functions with both an input and output format, e.g.
$SIR_DATECNV, are only available in the Sir2000 User Language
Tools; SIRFIELD is part of the Sir2000 Field Migration Facility.
YY*
This is a format which could be used for data which contains a 2-digit year
prefixing other information, such as a sequence number, when the other
information is variable length. The following User Language fragment
IF $SIR_DATE2ND('92', 'YY*') > -9E12 THEN
PRINT 'OK'
END IF
IF $SIR_DATE2ND('1992ABC', 'YYYY*') > -9E12 THEN
PRINT 'OK'
END IF
prints the values “OK” and “OK”.
Notes:
●
At most one occurrence of the * token may appear in a datetime format.
——————————————————————————————————————————
539
——————————————————————————————————————————
——————————————————————————————————————————
●
When a pair of format strings are used for transforming date values, e.g.
for $SIR_DATECNV or processing of updates to SIRFIELD RELATEd
fields, then if a * token appears in one of the formats, a * must also
appear in the other format.
The $functions with both an input and output format, e.g.
$SIR_DATECNV, are only available in the Sir2000 User Language
Tools; SIRFIELD is part of the Sir2000 Field Migration Facility.
CYYDDD
This is a compact 6-digit date format with explicit century information, from
1900 through and including 2899. The following User Language fragment
IF $SIR_DATE2ND('097031', 'CYYDDD') > -9E12 THEN
PRINT 'OK'
END IF
ZYYMMDD
This is a compact 6- or 7-digit date format with explicit century information,
from 1900 through and including 2899, that can often be used with “old”
YYMMDD date values in the 1900's. The following User Language fragment
* Check 1 Dec, 1997:
IF $SIR_DATE2ND('971201', 'ZYYMMDD') > -9E12 THEN
PRINT 'OK'
END IF
* Check 1 Dec, 2000:
IF $SIR_DATE2ND('1001201', 'ZYYMMDD') > -9E12 THEN
PRINT 'OK'
END IF
prints the values “OK” and “OK”.
Notes:
●
With non-strict format matching (such as $SIR_DATE2ND), a three digit
number with a leading zero may correspond to a ZYY token, thus
allowing “0971201”. With strict matching, however, a 3 digit value with
leading zero is not allowed for ZYY; a 3-digit value less than 100 with a
strict $function (i.e., one of the Sir2000 User Language Tools Functions)
requires the CYY token. If the data contains values less than 100 as 3
digits in some instances and as 2 digits in others, you must use a nonstrict $function.
——————————————————————————————————————————
540
——————————————————————————————————————————
——————————————————————————————————————————
YY0000
Decimal digits can be used as separator characters. The following User
Language fragment
%N = $SIR_DATE2ND('92000', 'YY000')
PRINT $SIR_ND2DATE(%N, 'YYYY"N"A')
prints the value “1992NA”.
Notes:
13.6
●
Numeric separators, unlike alphabetic separators, do not need to be
preceeded by a quote character (").
●
Numeric separators are available starting with version 5.2 of the Sirius
Functions.
Datetime Error Handling
Due to an invalid argument value to a datetime $function, any of the following errors can
occur:
●
invalid datetime format specification
●
datetime string not matching format
●
datetime out of range for the format
●
invalid CENTSPAN value
●
datetime out of range for CENTSPAN/SPANSIZE combination
One way to detect these errors is to check for the appropriate error return value:
1.
$Functions using a numeric value to represent a datetime, and $SIR_DATE, have
error return values of -9.E12 or a null string for numeric or string result $functions,
respectively.
2.
$Functions (other than $SIR_DATE) that only manipulate strings and associated
datetime formats and CCA date $functions have error return values of a variable
number of asterisks (or, in the case of $SIR_DATEDIF and $DATEDIF the value
99,999,999). $SIR_DATEDIF, and the date $functions which return a variable
number of asterisks as error indication, are available only with the Sir2000 User
Language Tools.
If you are authorized to use the Sir2000 User Language Tools, you can modify the error
detection algorithm so that warning messages or request cancellation occur when a
——————————————————————————————————————————
541
——————————————————————————————————————————
——————————————————————————————————————————
datetime error occurs. One significant advantage of this product is that you can add a
great deal of error detection to applications without modifying any User Language code.
ALso, for case (2.) above, thorough error detection of error return values is somewhat
complex.
With the Sir2000 User Language Tools, you can control the error detection algoritm on a
system level, with user-level and request-level overrides. These error control features
apply to both the CCA date $functions and all Sirius datetime $functions; in addition, all
Sirius datetime $functions (excepting $SIR_DATEFMT) have an optional error control
argument, which allows you to override the error handling for the operation of a single
$function call.
See the Sir2000 User Language Tools Reference Manual for a discussion of the error
control features it provides.
13.7
$SIR_DATExxx Functions CENTSPAN Argument
Many of the $SIR_DATExxx functions accept an optional argument containing a
CENTSPAN value to be used for the call. The default value of any CENTSPAN
argument is -50, excepting the $WEB_DATE2xx functions without a format argument, in
which case the CENTSPAN argument is ignored and a CENTSPAN of 1990 is used.
The default value should be adequate in most cases; if you have carefully determined it
should be different in some application, code the value on the relevant $function
invocations.
In Model 204 V4R1.0, CCA has taken a different approach to the default 100 year period
is used; see the Model 204 documentation for a description of the CENTSPLT and
DEFCENT parameters and $function arguments.
13.8
Other $functions using date values
In addition to the Sirius datetime functions, which deal only with datetime $functions,
there are some $functions that deal with dates from Model 204 internal structures.
These $functions and any date processing considerations are:
$FINITIM
This $function returns the file initialization date and time, using a
2-digit year.
$LISTSRT
This $function sorts a $list; it allows you to specify a C modifier of
the sort key to indicate a two digit year, which it will then sort using
a CENTSPAN of 1975.
$PRCLEX[G]
These $functions retrieve a $list of information about procedures in
file or group.
——————————————————————————————————————————
542
——————————————————————————————————————————
Other $functions using date values
——————————————————————————————————————————
●
●
●
$PROC_LIST[G]
The last-modified date is retrieved as a two digit year; to
retrieve it as a four digit year, use $PROC_LIST/G.
You may sort the $list using a two digit year if you use the C
modifier of $LISTSRT.
The fourth argument, which specifies the last-modified date
selection criterion, is passed as a two digit year, using a
CENTSPAN of 1975.
These $functions retrieve a $list of information about procedures in
file/group.
●
●
The last-modified date is retrieved as a four digit year.
The fourth argument, which specifies the last-modified date
selection criterion, is passed as a two digit year, using a
CENTSPAN of 1975.
$SIRJGET
This $function retrieves audit trail data into a $list. The arguments
which specify the start and end time to extract are passed as two
digit years, using a CENTSPAN of 1990.
$SIRTIME
This $function returns the current date and time, using a two digit
year.
13.9
Benefits of Sirius datetime processing
Following is a list of benefits offered by Sirius datetime processing. To provide concrete
comparisons, there are some references to the standard Model 204 date $functions
provided by CCA.
SPANSIZE
The SPANSIZE processing creates a very strong barrier to detecting
otherwise un-noticed 2-digit year processing errors. This is unique to Sirius
datetime processing.
Relative CENTSPAN
The relative CENTSPAN specification (e.g., “-50”) allows you to maintain a
flexible “rolling” window for 2-digit year processing.
Default CENTSPAN
One significant advantage of a relative CENTSPAN is that it allows the
default (1990 for $WEB_DATE2xx functions without a format, and -50
otherwise) of a reasonable value without parameter changes in all batch and
online jobs.
——————————————————————————————————————————
543
——————————————————————————————————————————
——————————————————————————————————————————
Format tokens
There is a very large set of tokens in the Sirius datetime formats. For
example, there are 4 different tokens representing the day of the week, and
time of day can be represented. CCA date formats do not have any day of
week nor time of day tokens, and other CCA token variations, e.g., CYY vs.
ZYY, is done by a complex argument setting.
Pattern match tokens
The Sirius datetime formats can contain single-character (“I”) or variable
length character (“*”) match-any tokens in datetime formats. For example,
you can specify that a string has an imbedded year, and process that year
as a date.
Format-free representations
Non-string datetime values allow you to pass around dates simply as
numbers, without the complexities of carrying the corresponding string
format (you only need to establish the scale to operate on a value).
Operating on numeric representations
Numeric date values can be operated on directly with User Language,
especially allowing you to add datetime differences (e.g., “+”), rather than
calling a DATECHG $function and providing a format.
Time
All Sirius datetime $functions allow any reference to a “date” to include time
of day. The only CCA datetime $function which provides a time of day is
$TIME, the current time of day, in one fixed format.
$SIR_DATE formats
$SIR_DATE allows you to specify any format to return the current date and
time; $DATE has only a few numeric codes for a few formats.
Error control args
The Sir2000 User Language Tools provides error handling control that
applies to all datetime $functions - Sirius and CCA. Additionally, all Sirius
datetime $functions (except $SIR_DATEFMT, of course) allow you to specify
it for a single $function invocation.
Error values of numeric date $functions
The $functions that use non-string datetime values provide very uniform
error return values: -9.E12 or a null string for numeric or string result
$functions, respectively.
——————————————————————————————————————————
544
——————————————————————————————————————————
Messages
——————————————————————————————————————————
——————
CHAPTER 14
Messages
Please refer to Sirius Messages Manual for messages related to the Sirius Functions.
——————————————————————————————————————————
545
——————————————————————————————————————————
Messages
——————————————————————————————————————————
——————————————————————————————————————————
546
——————————————————————————————————————————
Index
——————————————————————————————————————————
——————
Index
$
$ABBREV ... 34
$ABS ... 508
$ARCCOS ... 508
$ARCSIN ... 508
$ARCTAN ... 508
$ARCTAN2 ... 508
$ARR_FIND ... 36
$ARR_INIT ... 38
$ARR_MAX ... 39
$ARR_MIN ... 41
$A2E ... 33
$BASE64_DECODE ... 43
$BASE64_ENCODE ... 45
$BGPURGE ... 47
$BGQUERY ... 48
$BIND ... 49
$BIND_LIST ... 51
$BITAND ... 53
$BITOR ... 54
$BUMP ... 55
$CENTER ... 56
$CFSTATL ... 58
$CLOSE ... 60
$CMS ... 62
$COMMAND ... 63
$COMMBG ... 66
$COMMNDL ... 69
$CONTEXT ... 71
$COS ... 508
$COSH ... 509
$COTAN ... 509
$C2D ... 73
$DAEMONMASTERNUMBER ... 75
$DAEMONPARENTNUMBER ... 76
$DB_xxx: Janus Open Client $functions ... 77
$DEFLATE ... 78
$DELCH ... 80
$DELG_SUBSYS ... 82
$DELG_SYS ... 84
$DELIMR ... 85
$D2C ... 86
$D2X ... 88
$EDSCAN ... 90
$ENT ... 93
$ENT_PRINT ... 95
$ENT_TAB ... 97
$ERF ... 509
$ERFC ... 509
$ERRSET ... 99
$EXP ... 509
$EXP10 ... 510
$EXP2 ... 509
$E2A ... 89
$FAKEENT ... 100
$FIELD_IMAGE ... 101
$FIELD_LIST ... 105
$FIELD_LISTI ... 108
$FINITIM ... 113
$FISTAT ... 114
$FISTATL ... 116
$FREEOPT ... 118
$FUNFORC ... 120
$FUNIMG ... 121
$FUNLIST ... 123
$FUNLOAD ... 125
$FUNPURG ... 131
$FUNSKIP ... 132
$FUNSSTR ... 134
$FUNWAIT ... 136
$GAMMA ... 510
$GUNZIP ... 137
$GZIP ... 139
$HEXA ... 141
$IHEXA ... 142
$IMGINF ... 143
$IMGOVL ... 145
$INCSTAT ... 147
$INFLATE ... 148
$IXPI ... 510
$JOBAUTH ... 149
$LGAMMA ... 510
$List identifier ... 7
$LIST_ADD_ORDERED ... 150
$LIST_ADD_UNIQUE ... 152
——————————————————————————————————————————
547
——————————————————————————————————————————
Index
——————————————————————————————————————————
$LIST_ADD_UNIQUE_ORDERED ... 154
$LIST_CAPTURE ... 156
$LIST_CONV_ITEM ... 161
$LIST_COPY_ITEMS ... 164
$LIST_DIFF_ITEM ... 166
$LIST_GLOBAL ... 169
$LIST_GLOBAL_DEL ... 173
$LIST_GLOBAL_LIST ... 175
$LIST_MAXIL ... 177
$LIST_PRINT ... 178
$LIST_SESSION ... 169
$LIST_SESSION_DEL ... 173
$LIST_SESSION_LIST ... 175
$LISTADD ... 180
$LISTADD_LSTR ... 182
$LISTADDI ... 184
$LISTADJ ... 187
$LISTCHK ... 189
$LISTCMP ... 190
$LISTCNT ... 192
$LISTCPY ... 193
$LISTDEL ... 194
$LISTFIND ... 195
$LISTFINDI ... 196
$LISTFINDI_SUB ... 199
$LISTFINDI_UP ... 196
$LISTILN ... 202
$LISTIMG ... 203
$LISTIMG_COPY ... 205
$LISTINF ... 206
$LISTINF_LSTR ... 208
$LISTINFI ... 209
$LISTINS ... 211
$LISTINS_LSTR ... 214
$LISTINSI ... 216
$LISTLOC ... 219
$LISTLUP ... 222
$LISTMOVE ... 225
$LISTNEW ... 228
$LISTNEWA ... 229
$LISTNEWAI ... 232
$LISTNEWI ... 234
$LISTOVL ... 235
$LISTOVLI ... 238
$LISTREM ... 241
$LISTREP ... 243
$LISTREP_LSTR ... 245
$LISTREPI ... 247
$LISTRST ... 250
$LISTSAV and $LISTSAVE ... 252
$LISTSAVL ... 255
$LISTSORT and $LISTSRT ... 257
$LISTSUB ... 260
$LISTUPD ... 263
$LOG ... 511
$LOG10 ... 511
$LOG2 ... 511
$LSTR ... 265
$LSTR_ADD_USERBUFFER ... 266
$LSTR_BASE64_DECODE ... 267
$LSTR_BASE64_ENCODE ... 269
$LSTR_C2X ... 270
$LSTR_GET_IMAGE ... 271
$LSTR_GET_USERBUFFER ... 272
$LSTR_GLOBAL ... 273
$LSTR_GLOBAL_DEL ... 276
$LSTR_GLOBAL_GET ... 278
$LSTR_GLOBAL_SET ... 280
$LSTR_INDEX ... 282
$LSTR_LEFT ... 284
$LSTR_LEN ... 286
$LSTR_PARSE ... 287
$LSTR_PARSEX ... 288
$LSTR_RIGHT ... 290
$LSTR_SESSION ... 273
$LSTR_SESSION_DEL ... 276
$LSTR_SESSION_GET ... 278
$LSTR_SESSION_SET ... 280
$LSTR_SET_IMAGE ... 271
$LSTR_SET_USERBUFFER ... 292
$LSTR_SUBSTR ... 293
$LSTR_SUBWORD ... 295
$LSTR_TRANSLATE ... 297
$LSTR_UNBLANK ... 301
$LSTR_WINDEX ... 303
$LSTR_WORD ... 305
$LSTR_WORDS ... 307
$LSTR_X2C ... 308
$MAX ... 511
$MIN ... 512
$PARSE ... 310
$PARSEX ... 311
$PI ... 512
$PRCLEX ... 313
$PRCLEXG ... 315
$PRIORTY ... 317
$PROC_LIST ... 319
$PROC_LISTG ... 321
——————————————————————————————————————————
548
——————————————————————————————————————————
Index
——————————————————————————————————————————
$PROC_TOUCH ... 323
$PROCCLS ... 325
$PROCDAT ... 326
$PROCGET ... 328
$PROCLOC ... 329
$PROCOPN ... 29, 331
$RANDOM ... 333, 335
$REGEXMATCH ... 336
$REGEXREPLACE ... 339
$RESETN ... 344
$RXPI ... 512
$RXPR ... 512
$SCRHIDE ... 347
$SCRSIZE ... 349
$SCRWIDE ... 350
$SESSION ... 351
$SESSION_CLOSE ... 352
$SESSION_CREATE ... 354
$SESSION_DELETE ... 356
$SESSION_ID ... 351
$SESSION_LIST ... 358
$SESSION_OPEN ... 360
$SESSION_OWNER ... 351
$SESSION_TIMEOUT ... 351
$SETG_SUBSYS ... 362
$SETG_SUBSYS_LIST ... 366
$SETG_SYS ... 369
$SETG_SYS_LIST ... 372
$SETSTAT ... 374
$SIN ... 513
$SINH ... 513
$SIR_DATE ... 375
$SIR_DATEFMT ... 376
$SIR_DATEN ... 377
$SIR_DATEND ... 378
$SIR_DATENM ... 379
$SIR_DATENS ... 380
$SIR_DATExxx: Sir2000 User Language Tools
$functions ... 389
$SIR_DATE2N ... 381
$SIR_DATE2ND ... 383
$SIR_DATE2NM ... 385
$SIR_DATE2NS ... 387
$SIR_ND2DATE ... 390
$SIR_NM2DATE ... 392
$SIR_NS2DATE ... 394
$SIR_N2DATE ... 396
$SIR_WILD ... 398
$SIRFIELDxxx: Sir2000 Field Migration Facility
$functions ... 399
$SIRJGET ... 400
$SIRMSG ... 406
$SIRMSGP ... 407
$SIRPARM ... 409
$SIRPROD ... 412
$SIRSITE ... 414
$SIRTIME ... 415
$SIRVER ... 416
$SIRWARN ... 417
$SOCK_xxx: Janus Sockets $functions ... 419
$SQRT ... 513
$SRV_xxx: Janus Open Server
$functions ... 420
$SSSTAT ... 421
$SSSTATL ... 423
$STATD ... 425
$STATLD ... 427
$STR ... 430
$STRAND ... 431
$STROR ... 433
$STRXOR ... 435
$SUBCNT ... 437
$SUBERS ... 438
$SUBINS ... 440
$SUBREP ... 441
$SYSTAT ... 443
$TABLEC ... 445
$TAN ... 513
$TANH ... 513
$TERMID ... 447
$TKSTAT ... 448
$TKSTATL ... 450
$TSOATT ... 452
$TSOCALL ... 454
$TSOCAN ... 456
$TSOCMD ... 458
$TSOEXEC ... 460
$TSOEXIT ... 462
$TSOID ... 463
$TSOSTAT ... 464
$TSOWAIT ... 466
$TSOxxx: TSO $functions ... 505
$UNBIND ... 468
$UNBINDW ... 468
$UNSPACE ... 470
$USEASA ... 473
$USSTAT ... 474
——————————————————————————————————————————
549
——————————————————————————————————————————
Index
——————————————————————————————————————————
$USSTATL ... 476
$WAKEUP ... 479
$WEBxxx: Janus Web Server $functions ... 481
$WINDEX ... 482
$XMLxxx: Janus SOAP $functions ... 483
$X2D ... 484
A
Alternatives, regex ... 520
Assert statement ... 485-486
testing assumptions ... 486
Audit trail messages ... 128
AuditText statement ... 492
Automatic screen refresh ... 100
B
Buffer, user
See User buffer and see Universal Buffer
C
Callable $functions ... 32
CENTSPAN ... 534, 542
CENTSPLT argument ... 542
CENTSPLT parameter ... 542
Character classes, regex ... 518
Character entity translation ... 492, 499
D
Date processing ... 527, 542
DEFCENT argument ... 542
DEFCENT parameter ... 542
Dot-All mode, regex ... 522
DUMMYSYS ... 409
dumps, SirFact ... 486
E
EDITMSG ... 410
Escape sequences, regex ... 517
F
Family, thread ... 5
Fast Unload functions
$FUNFORC: Cancel running or waiting
Fast/Unload request ... 120
$FUNIMG: Retrieve data from active
Fast/Unload request into image ... 121
$FUNLIST: $list of active and enqueued Fast
Unload requests ... 123
$FUNLOAD: Fast/Unload records in Model
204 list or found set ... 125
$FUNPURG: Purge running or waiting
Fast/Unload request ... 131
$FUNSKIP: Skip to next Fast/Unload output
record for $FUNIMG,
$FUNSSTR ... 132
$FUNSSTR: Retrieve data from active
Fast/Unload request into string ... 134
$FUNWAIT: Wait until asynchronous
Fast/Unload request completes ... 136
Function prototypes
$COMMAND(cmd, msgctl, imagename, file,
width) -> %rc ... 63
$COMMNDL(cmd, msgctl, list_id, file, width)
-> %rc ... 69
$SIR_DATE(fmt, errctl) -> %odate ... 375
$SIR_DATEFMT(fmt) -> %tst ... 376
$SIR_DATEN -> %num ... 377
$SIR_DATEND -> %num ... 378
$SIR_DATENM -> %num ... 379
$SIR_DATENS -> %num ... 380
$SIR_DATE2N(dat, fmt, span, errctl) ->
%num ... 381
$SIR_DATE2ND(dat, fmt, span, errctl) ->
%num ... 383
$SIR_DATE2NM(dat, fmt, span, errctl) ->
%num ... 385
$SIR_DATE2NS(dat, fmt, span, errctl) ->
%num ... 387
$SIR_ND2DATE(datn, fmt, errctl) ->
%dat ... 390
$SIR_NM2DATE(datn, fmt, errctl) ->
%dat ... 392
$SIR_NS2DATE(datn, fmt, errctl) ->
%dat ... 394
$SIR_N2DATE(datn, fmt, errctl) ->
%dat ... 396
$SIR_WILD(string, wildcard) ->
%result ... 398
——————————————————————————————————————————
550
——————————————————————————————————————————
Index
——————————————————————————————————————————
Function synopsis
$List item into image: $LISTINFI ... 209
$List item into longstring:
$List item into string: $LISTINF ... 206
Absolute value: $ABS ... 508
Active and enqueued Fast/Unload requests:
$FUNLIST ... 123
Add an item to an ordered $list:
Add image as new $list item:
$LISTADDI ... 184
Add lines from procedure to $list:
$PROCDAT ... 326
Add longstring as new $list item:
Add longstring to user buffer:
$LSTR_ADD_USERBUFFER ... 266
Add string as new $list item:
$LISTADD ... 180
Adjust length of $list item: $LISTADJ ... 187
Allow SCREEN to accept fields wider than
79: $SCRWIDE ... 350
Apply updates to $list: $LISTUPD ... 263
ASCII to EBCDIC translation: $A2E ... 33
Associate image with a $list:
$LISTIMG ... 203
Attach program in user's TSO address space:
$TSOATT ... 452
Binary byte representation of integer:
$D2C ... 86
Bind to a global longstring:
$LSTR_GLOBAL ... 273
Bind to a session longstring:
Bit-wise AND two strings together:
$STRAND ... 431
Bit-wise exclusive OR two strings together:
$STRXOR ... 435
Bit-wise OR two strings together:
$STROR ... 433
Bitwise AND of two integers: $BITAND ... 53
Bitwise OR of two integers: $BITOR ... 54
Build a $list subset based on image item:
Build seed specifying series of $RANDOM
results: $RANDOM_SEED ... 335
Bump a user: $BUMP ... 55
Call program in user's TSO address space:
$TSOCALL ... 454
Cancel "long" sdaemon request initiated with
$COMMBG: $BGPURGE ... 47
Cancel program invoked via $TSOATT:
$TSOCAN ... 456
Cancel running or waiting Fast/Unload
request: $FUNFORC ... 120
Capture print data to $list:
Center string: $CENTER ... 56
Change a user's priority: $PRIORTY ... 317
Change procedure time stamp and account
ID of last updator: $PROCCLS ... 323
Change size of field on SCREEN:
$SCRSIZE ... 349
Close an open session:
Close file or group in User Language request:
$CLOSE ... 60
Close procedure before reaching end:
$PROCCLS ... 325
Compare two $lists and produce $list
describing differences:
$LISTCMP ... 190
Conditionally add an item to a $list:
Conditionally add an item to an ordered $list:
Convert $list to single delimited $list item:
Convert binary byte string to integer:
$C2D ... 73
Convert EBCDIC string to hexadecimal
equivalent: $IHEXA ... 142
Convert from base 64 to byte string:
$BASE64_DECODE ... 43
Convert from base 64 to byte string:
$LSTR_BASE64_DECODE ... 267
Convert from byte string to base 64:
$BASE64_ENCODE ... 45
Convert from byte string to base 64:
$LSTR_BASE64_ENCODE ... 269
Convert from byte string to hexadecimal:
$LSTR_C2X ... 270
Convert from hexadecimal to byte string:
$LSTR_X2C ... 308
Convert hex string to integer: $X2D ... 484
——————————————————————————————————————————
551
——————————————————————————————————————————
Index
——————————————————————————————————————————
Convert hexadecimal string to EBCDIC
equivalent: $HEXA ... 141
Copy $list items:
Copy $list: $LISTCPY ... 193
Copy a $list's image association:
Cosine function: $COS ... 508
Cotangent function: $COTAN ... 509
Count and names of available global $lists:
$LISTSAVL ... 255
Count occurrences of one string in another:
$SUBCNT ... 437
Create a new session:
Create array of empty $lists associated with
an image: $LISTNEWAI ... 232
Create array of empty $lists:
$LISTNEWA ... 229
Create empty $list associated with image:
$LISTNEWI ... 234
Create empty $list: $LISTNEW ... 228
Current date and time as number of
milliseconds: $SIR_DATENM ... 379
Current date and time as number of
seconds/300: $SIR_DATEN ... 377
Current date and time as number of seconds:
$SIR_DATENS ... 380
Current date and time: $SIR_DATE ... 375
Current date as number of days:
$SIR_DATEND ... 378
Current Sirius customer site ID:
$SIRSITE ... 414
Current time as YYDDDHHMISSXX:
$SIRTIME ... 415
Current version number of Sirius product:
$SIRVER ... 416
Datetime format validation:
$SIR_DATEFMT ... 376
Datetime number of days converted to string:
$SIR_ND2DATE ... 390
Datetime number of milliseconds converted to
string: $SIR_NM2DATE ... 392
Datetime number of seconds converted to
string: $SIR_NS2DATE ... 394
Datetime number of seconds/300 converted
to string: $SIR_N2DATE ... 396
Datetime string converted to number of days:
$SIR_DATE2ND ... 383
Datetime string converted to number of
milliseconds: $SIR_DATE2NM ... 385
seconds/300: $SIR_DATE2N ... 381
seconds: $SIR_DATE2NS ... 387
Delete a session:
Delete global $lists:
Delete global longstrings:
$LSTR_GLOBAL_DEL ... 276
Delete session $lists:
Delete session longstrings:
Delete subsystem-wide global:
$DELG_SUBSYS ... 82
Delete system-wide global:
$DELG_SYS ... 84
Determine availability of Sirius product or
capability: $SIRPROD ... 412
Determine id of current open session:
$SESSION_ID ... 351
Determine if online is running under CMS:
$CMS ... 62
Determine if session open:
$SESSION ... 351
Determine if string is abbreviation within list of
words: $ABBREV ... 34
Determine if string is name of open file or
group: $CONTEXT ... 71
Determine if user has authorization for USE
$JOB: $JOBAUTH ... 149
Determine owner of current open session:
Determine timeout of current open session:
——————————————————————————————————————————
552
——————————————————————————————————————————
Index
——————————————————————————————————————————
Differences and rates for statistics $lists:
$STATLD ... 427
Differences and rates for statistics strings:
$STATD ... 425
Differences between $list and delimited $list
item: $LIST_DIFF_ITEM ... 166
Display contents of a $list:
$LIST_PRINT ... 178
Do character entity substitution on a string:
$ENT ... 93
EBCDIC to ASCII translation: $E2A ... 89
Error function complement: $ERFC ... 509
Error function: $ERF ... 509
Error function: $EXP ... 509
Error function: $EXP10 ... 510
Error function: $EXP2 ... 509
Exec command on sdaemon, results to $list:
$COMMNDL ... 69
Exec command on sdaemon, results to
image: $COMMAND ... 63
Exec commands on sdaemon:
$COMMBG ... 66
Fast/Unload records in a Model 204 list or
found set: $FUNLOAD ... 125
Fast, easy synchronization of system wide
resource: $BIND ... 49
File initialization YYDDDMMHHSSTH:
$FINITIM ... 113
Find a string inside a longstring:
$LSTR_INDEX ... 282
Find maximum value in array:
$ARR_MAX ... 39
Find minimum value in array:
$ARR_MIN ... 41
Find value within array: $ARR_FIND ... 36
Free optional file or group from subsystem:
$FREEOPT ... 118
Gamma function: $GAMMA ... 510
Get access to or create a global $list:
Get access to or create a session $list:
Get left-most characters of a longstring:
$LSTR_LEFT ... 284
Get length of a longstring:
$LSTR_LEN ... 286
Get list of global $lists:
Get list of session $lists:
Get list of sessions: $SESSION_LIST ... 358
Get list of subsystem-wide globals:
$SETG_SUBSYS_LIST ... 366
Get list of system-wide globals:
$SETG_SYS_LIST ... 372
Get next random number: $RANDOM ... 333
Get right-most characters of a longstring:
$LSTR_RIGHT ... 290
Get user buffer contents to a longstring:
$LSTR_GET_USERBUFFER ... 272
Get user number of master thread ... 75
Get user number of parent thread ... 76
Get value of global longstring:
$LSTR_GLOBAL_GET ... 278
Get value of session longstring:
Gets a single word from a long string:
$LSTR_WORD ... 305
Gets a substring of a longstring:
$LSTR_SUBSTR ... 293
Gets a substring of a longstring:
$LSTR_SUBWORD ... 295
Gets the number of words in a long string:
$LSTR_WORDS ... 307
Gets the position of a word within a long
string: $LSTR_WINDEX ... 303
Hex representation of integer: $D2X ... 88
Hide lines in SCREEN: $SCRHIDE ... 347
Hyperbolic cosine: $COSH ... 509
Hyperbolic sine: $SINH ... 513
Hyperbolic tangent: $TANH ... 513
Image item into string: $IMGINF ... 143
Increment local system statistic:
$INCSTAT ... 147
Increment or clear number of counting errors,
set $ERRMSG: $ERRSET ... 99
Information provided by TABLEC command:
$TABLEC ... 445
——————————————————————————————————————————
553
——————————————————————————————————————————
Index
——————————————————————————————————————————
Initialize every element of array to specific
value: $ARR_INIT ... 38
Insert delimiter string into input string at
regular positions: $DELIMR ... 85
Insert longstring into a $list:
Insert string inside another string:
$SUBINS ... 440
Insert string into a $list: $LISTINS ... 211
Inserts image as into a $list:
$LISTINSI ... 216
Integer base raised to integer exponent:
$IXPI ... 510
Inverse cosine: $ARCCOS ... 508
Inverse sine: $ARCSIN ... 508
Inverse tangent of ratio of arguments:
$ARCTAN2 ... 508
Inverse tangent: $ARCTAN ... 508
Invoke CLIST in user's TSO address space:
$TSOEXEC ... 460
Invoke command in user's TSO address
space: $TSOCMD ... 458
Janus Open Client $functions:
$DB_xxx ... 77
Janus Open Server $functions:
$SRV_xxx ... 420
Janus SOAP $functions: $XMLxxx ... 483
Janus Sockets $functions:
$SOCK_xxx ... 419
Janus Web Server $functions:
$WEBxxx ... 481
Length of $list item: $LISTILN ... 202
Lgamma function: $LGAMMA ... 510
Line of current $SIRMSGP procedure:
$SIRMSG ... 406
List of "long" sdaemon requests initiated via
$COMMBG: $BGQUERY ... 48
List of information about procedures in file:
$PRCLEX ... 313
List of information about procedures in file:
$PROC_LIST ... 319
List of information about procedures in group
or file: $PRCLEXG ... 315
List of information about procedures in group
or file: $PROC_LISTG ... 321
List of statistics for users holding critical file
resources: $CFSTATL ... 58
Load procedure for retrieval via $SIRMSG:
$SIRMSGP ... 407
Locate any of set of strings in procedure:
$PROCLOC ... 329
Locate image item in $list: $LISTFINDI and
$LISTFINDI_UP ... 196
Locate string in $list, searching backwards:
$LISTLUP ... 222
Locate string in $list: $LISTFIND ... 195
Locate string in $list: $LISTLOC ... 219
Log function: $LOG ... 511
Log function: $LOG10 ... 511
Log function: $LOG2 ... 511
Mathematical $functions ... 507
Maximum of multiple values: $MAX ... 511
Minimum of multiple values: $MIN ... 512
Move $list: $LISTMOVE ... 225
Move data from image to longstring:
$LSTR_GET_IMAGE ... 271
Move data from longstring to image:
$LSTR_SET_IMAGE ... 271
Next line of procedure: $PROCGET ... 328
Normalize spaces and quotes:
$UNSPACE ... 470
Number of items in $list: $LISTCNT ... 192
Open a session:
Open procedure for $PROCDAT,
$PROCGET, $PROCLOC:
$PROCOPN ... 331
Overlay part of $list item with image item:
$LISTOVLI ... 238
Overlay part of $list item with string:
$LISTOVL ... 235
Part of longstring following character in
delimiter set: $LSTR_PARSEX ... 288
Part of longstring preceding character in
delimiter set: $LSTR_PARSE ... 287
Part of string following character in delimiter
set: $PARSEX ... 311
Part of string preceding character in delimiter
set: $PARSE ... 310
Pause user until specified time:
$WAKEUP ... 479
Place audit trail data on $list:
$SIRJGET ... 400
Prepare fake ENTER to automatically satisfy
next full screen read:
$FAKEENT ... 100
——————————————————————————————————————————
554
——————————————————————————————————————————
Index
——————————————————————————————————————————
Prevent carriage control in USE output:
$USEASA ... 473
Purge running or waiting Fast/Unload
request: $FUNPURG ... 131
Real base raised to integer exponent:
$RXPI ... 512
Real base raised to real exponent:
$RXPR ... 512
Release CCATEMP storage used for $list:
$LISTDEL ... 194
Remove characters from string, compress
and strip blanks: $DELCH ... 80
Remove extraneous blanks from a longstring:
$LSTR_UNBLANK ... 301
Remove item from $list: $LISTREM ... 241
Remove occurrence of one string from
another: $SUBERS ... 438
Replace $list item with image:
$LISTREPI ... 247
Replace a $list item with a string:
$LISTREP ... 243
Replace a $list item with a string:
Replace occurrences of string:
$SUBREP ... 441
Reset or view M204 parameter:
$REGEXREPLACE ... 339
Reset or view M204 parameter:
$RESETN ... 344
Restore global $list: $LISTRST ... 250
Retrieve data from active Fast/Unload
request into image: $FUNIMG ... 121
Retrieve data from active Fast/Unload
request into string: $FUNSSTR ... 134
Retrieve file's statistics into string:
$FISTAT ... 114
Retrieve set of files' statistics into list:
$FISTATL ... 116
Retrieve statistics for all tasks into $list:
$TKSTATL ... 450
Retrieve statistics for set of subsystems into
$list: $SSSTATL ... 423
Retrieve subsystem's statistics into string:
$SSSTAT ... 421
Retrieve system statistics into string:
$SYSTAT ... 443
Retrieve task's statistics into string:
$TKSTAT ... 448
Retrieves or modifies the active character
entity substitution table. ... 97
Return field values into a $list mapped to an
image: $FIELD_LISTI ... 108
Return field values into a $list:
$FIELD_LIST ... 105
Return field values into an image:
$FIELD_IMAGE ... 101
Return list of bound semaphores onto a $list:
$BIND_LIST ... 51
Return maximum $list item length:
$LIST_MAXIL ... 177
Save global $list: $LISTSAV and
$LISTSAVE ... 252
Scan list of entities in online:
$EDSCAN ... 90
Send warning or message to user(s):
$SIRWARN ... 417
Set automatic character entity substitution for
PRINT: $ENT_PRINT ... 95
Set local system statistic: $SETSTAT ... 374
Set subsystem-wide global:
$SETG_SUBSYS ... 362
Set system-wide global: $SETG_SYS ... 369
Set user buffer to longstring value:
$LSTR_SET_USERBUFFER ... 292
Set user-specific value, controlling Sirius
products: $SIRPARM ... 409
Set value of global longstring:
$LSTR_GLOBAL_SET ... 280
Set value of session longstring:
Sine function: $SIN ... 513
Sir2000 Field Migration Facility $functions:
$SIRFIELDxxx ... 399
Sir2000 User Language Tools $functions:
$SIR_DATExxx ... 389
Skip to next output record for $FUNIMG,
$FUNSSTR: $FUNSKIP ... 132
——————————————————————————————————————————
555
——————————————————————————————————————————
Index
——————————————————————————————————————————
Sort $list: $LISTSORT and
$LISTSRT ... 257
Square root function: $SQRT ... 513
Statistics for set of users into $list:
$USSTATL ... 476
Status of program invoked via $TSOATT:
$TSOSTAT ... 464
Sublist of $list: $LISTSUB ... 260
Takes a longstring input and compresses it
using the "deflate" algorithm:
$DEFLATE ... 78
Takes a longstring input and compresses it
using the "deflate" algorithm:
$GZIP ... 139
Takes a longstring input and decompresses it
using the "inflate" algorithm:
$INFLATE ... 148
Takes a longstring input in GZIP format and
decompresses it: $GUNZIP ... 137
Tangent function: $TAN ... 513
Terminal ID of current user thread:
$TERMID ... 447
Terminate TSO full screen interface session,
stack command: $TSOEXIT ... 462
Test string against wildcard string:
$SIR_WILD ... 398
Translate longstring:
$LSTR_TRANSLATE ... 297
Treat a longstring as string: $STR ... 430
Treat a string as longstring: $LSTR ... 265
TSO $functions: $TSOxxx ... 505
TSO userid user's thread: $TSOID ... 463
Unbind resource previously bound via $BIND:
$UNBIND ... 468
Unbind resource previously bound via $BIND:
$UNBINDW ... 468
User's statistics into string: $USSTAT ... 474
Validate $list identifier: $LISTCHK ... 189
Value into image item: $IMGOVL ... 145
Value of pi: $PI ... 512
Wait for program invoked via $TSOATT to
complete: $TSOWAIT ... 466
Wait until asynchronous Fast/Unload request
completes: $FUNWAIT ... 136
Whether string matches regex:
$REGEXMATCH ... 336
Word number of first occurrence of word in
phrase: $WINDEX ... 482
G
GETGSYS ... 410
Greedy matching, regex ... 341, 519
H
Html statement ... 488
I
Image, User Language
long items ... 11
Installation ... 1
L
Large Object (LOB) data ... 266, 272, 292
List processing functions
$LIST_DIFF_ITEM ... 166
$LIST_MAXIL ... 177
$LIST_PRINT ... 178
$LISTADD ... 180
$LISTADDI ... 184
$LISTADJ ... 187
$LISTCHK ... 189
$LISTCMP ... 190
$LISTCNT ... 192
$LISTCPY ... 193
$LISTDEL ... 194
$LISTFIND ... 195
$LISTFINDI and $LISTFINDI_UP ... 196
——————————————————————————————————————————
556
——————————————————————————————————————————
Index
——————————————————————————————————————————
$LISTILN ... 202
$LISTIMG ... 203
$LISTINF ... 206
$LISTINFI ... 209
$LISTINS ... 211
$LISTINSI ... 216
$LISTLOC ... 219
$LISTLUP ... 222
$LISTMOVE ... 225
$LISTNEW ... 228
$LISTNEWA ... 229
$LISTNEWAI ... 232
$LISTNEWI ... 234
$LISTOVL ... 235
$LISTOVLI ... 238
$LISTREM ... 241
$LISTREP ... 243
$LISTREPI ... 247
$LISTRST ... 250
$LISTSAV and $LISTSAVE ... 252
$LISTSAVL ... 255
$LISTSORT and $LISTSRT ... 257
$LISTSUB ... 260
$LISTUPD ... 263
LISTFC ... 410
Locales, regex ... 521
Longstrings ... 11
converted to numeric ... 16
expressions with ... 13
Look-aheads, regex ... 520
Look-behinds, regex ... 520
Loop Next statement ... 500
M
Mathematical $functions ... 507
Mixed-case User Language ... 31
Mode modifiers, regex ... 521
MoveFromId subroutine, Stringlist class ... 497
MoveToId subroutine, Stringlist class ... 497
Multi-line mode, regex ... 522
N
NCMPBUF parameter ... 78, 137, 140, 148
P
Parameters, User Language environment
DUMMYSYS ... 409
EDITMSG ... 410
GETGSYS ... 410
LISTFC ... 410
PrintText statement ... 491
Procedure processing functions ... 29
$PRCLEX ... 313
$PRCLEXG ... 315
$PROC_LIST ... 319
$PROC_LISTG ... 321
$PROCCLS ... 325
$PROCDAT ... 326
$PROCGET ... 328
$PROCLOC ... 329
$PROCOPN ... 29, 331
$SIRMSG ... 406
$SIRMSGP ... 407
Q
Quantifiers, regex ... 519
R
Regex processing ... 515
common options ... 522
rules ... 516
Regular expression rules ... 516
S
Screen refresh ... 100
Sdaemons ... 5, 63, 66, 69, 75-76
SESDEFOW system parameter ... 27
SESDEFTO system parameter ... 26
SESNPRV system parameter ... 25
SESNPUB system parameter ... 25
SESOPT system parameter ... 26
——————————————————————————————————————————
557
——————————————————————————————————————————
Index
——————————————————————————————————————————
Session $functions ... 25
$SESSION ... 351
$SESSION_ID ... 351
$SESSION_LIST ... 358
$SESSION_OPEN ... 360
Session methods ... 25
Sessions ... 25
SESUMAX system parameter ... 26
SIRCOMP user parameter ... 500
Special date format rules ... 531-532, 537-540
* ... 539
BD with leading zero ... 538
BH with leading zero ... 539
BM with leading zero ... 538
CYY with leading zero ... 540
DAY with leading zero ... 538
DD with leading blank ... 538
HH with leading blank ... 539
I ... 539
MM with leading blank ... 537
Numeric digit separators ... 540
3 character ZYY with leading blank ... 540
Suppressed terminal messages,
capturing ... 159
System requirements ... 3
TSO functions
$TSOATT: Attach program in user's TSO
address space ... 452
$TSOCALL: Call program in user's TSO
$TSOCAN: Cancel program invoked via
$TSOATT ... 456
$TSOCMD: Invoke command in user's TSO
$TSOEXEC: Invoke CLIST in user's TSO
$TSOEXIT: Terminate TSO full screen
interface session, stack
command ... 462
$TSOID: TSO userid user's thread ... 463
$TSOSTAT: Status of program invoked via
$TSOATT ... 464
$TSOWAIT: Wait for program invoked via
$TSOATT to complete ... 466
U
Unicode, regex ... 521
Universal Buffer, Model 204 ... 266, 272, 292
User buffer, MQ/204 ... 266, 272, 292
W
Wildcard test: $SIR_WILD ... 398
X
XML Schema mode ... 522-523
T
terminal output
definition of ... 157
Text statement ... 488
Thread family ... 5
TraceText statement ... 492
——————————————————————————————————————————
558

Sirius Functions Reference Manual

Transcription

Similar documents

Flemish String Board Attachment

50 $50 - Sadoun Satellite Sales

Sirius Satellite Radio Operations

The Argumentative Essay

sponsorship package

Knotted Friendship Bracelet

Is this the best boat ever built?

Newsletter 4 - Kepler Astrology Software

Operating Guide for Sirius

Double Bass Survival Guide By David Gage