! statement
Use the ! statement to insert a comment in a UniVerse BASIC
program. Comments explain or document various parts of a
program. They are part of the source code only and are
nonexecutable. They do not affect the size of the object code.
Syntax
! [comment.text]
A comment must be a separate BASIC statement and can appear
anywhere in a program. A comment must begin with one of the
following comment designators:
- REM
- *
- !
- $*
Any text that appears between a comment designator and the end
of a physical line is treated as part of the comment, not as
part of the executable program. If a comment does not fit on one
physical line, you can continue it on the next physical line
only by starting the new line with a comment designator. If a
comment appears at the end of a physical line containing an
executable statement, you must put a semicolon (; ) before the
comment designator.
Example
The PRINT statement at the end of the third line is not executed
because it follows the exclamation point on the same line and is
treated as part of the comment. Lines 4, 5, and 6 show how to
include a comment in the same sequence of executable statements.
001: vi PRINT "HI THERE"; ! Anything after the ! is a comment.
002: ! This line is also a comment and does not print.
003: IF 5<6 THEN PRINT "YES"; ! A comment; PRINT "PRINT ME"
004: IF 5<6 THEN
005: PRINT "YES"; ! A comment
006: PRINT "PRINT ME"
007: END
This is the program output:
HI THERE
YES
YES
PRINT ME
!ASYNC #
!ASYNC subroutine
Use the !ASYNC subroutine (or its synonym !AMLC) to send data
to, and receive data from an asynchronous device.
Syntax
CALL !ASYNC (key, line, data, count, carrier)
key defines the action to be taken (1 through 5). The values for
key are defined in the following list:
line is the number portion from the &DEVICE& entry TTY##, where
## represents a decimal number.
data is the data being sent to or received from the line.
count is an output variable containing the character count.
carrier is an output variable that returns a value dependent on
the value of key. If key is 1, 2, or 3, carrier returns the
variable specified by the user. If key has a value of 4 or 5,
carrier returns 1.
You must first assign an asynchronous device using the ASSIGN
command. An entry must be in the &DEVICE& file for the device to
be assigned with the record ID format of TTY##, where ##
represents a decimal number. The actions associated with each
key value are as follows:
Key Action
1 Inputs the number of characters indicated by the
value of count.
2 Inputs the number of characters indicated by the
value of count or until a linefeed character is
encountered.
3 Outputs the number of characters indicated by the
value of count.
4 Returns the number of characters in the input buffer
to count. On operating systems where the FIONREAD key
is not supported, 0 is returned in count. When the
value of key is 4, 1 is always returned to carrier.
5 Returns 0 in count if there is insufficient space in
the output buffer. On operating systems where the
TIOCOUTQ key is not supported, 0 is returned in
count. When the value of key is 5, 1 is always
returned to carrier.
Example
The !ASYNC subroutine returns the first 80 characters from the
device defined by ASYNC10 in the &DEVICE& file to the variable
data.
data=
count= 80
carrier= 0
call !ASYNC(1,10,data,count,carrier)
!EDIT.INPUT subroutine
Use the !EDIT.INPUT subroutine to request editable terminal
input within a single-line window on the terminal. Editing keys
are defined in the terminfo files and can be set up using the
KEYEDIT statement, KEYTRAP statement, and KEYEDIT statement. To
ease the implementation, the UNIVERSE.INCLUDE file GTI.FNKEYS.IH
can be included to automatically define the editing keys from
the current terminfo definition. We recommend that you use the
INCLUDE file.
Syntax
CALL !EDIT.INPUT (keys, wcol, wrow, wwidth, buffer, startpos,
bwidth, ftable, code)
All input occurs within a single-line window of the terminal
screen, defined by the parameters wrow, wcol, and wwidth. If the
underlying buffer length bwidth is greater than wwidth and the
user performs a function that moves the cursor out of the window
horizontally, the contents of buffer are scrolled so as to keep
the cursor always in the window.
If the specified starting cursor position would take the cursor
out of the window, the buffers contents are scrolled immediately
so as to keep the cursor visible. !EDIT.INPUT does not let the
user enter more than bwidth characters into the buffer,
regardless of the value of wwidth.
Qualifiers
Qualifier Description
keys Controls certain operational characteristics. keys can take
the additive values (the token names can be found in the
GTI.FNKEYS.IH include file) shown here:
Value Token Description
0 IK$NON None of the keys below are required.
1 IK$OCR Output a carriage return.
2 IK$ATM Terminate editing as soon as the
user has entered bwidth characters.
4 IK$TCR Toggle cursor-visible state.
8 IK$DIS Display contents of buffer string
on entry.
16 IK$HDX Set terminal to half-duplex mode
(restored on exit).
32 IK$INS Start editing in insert mode.
Default is overlay mode.
64 IK$BEG Separate Begin Line/End Line
functionality required.
wcol The screen column of the start of the window (x-coordinate).
wrow The screen row for the window (y-coordinate).
wwidth The number of screen columns the window occupies.
buffer Contains the following:
on entry The text to display (if key IK$DIS is set).
on exit The final edited value of the text.
startpos Indicates the cursor position as follows:
on entry The initial position of the cursor (from start of
buffer).
on exit The position of the cursor upon exit.
bwidth The maximum number of positions allowed in buffer. bwidth can
be more than wwidth, in which case the contents of buffer
scroll horizontally as required.
ftable A packed function key trap table, defining which keys cause
exit from the !EDIT.INPUT function. The !PACK.FNKEYS function
creates the packed function key trap table.
code The reply code:
= 0 User pressed Return or entered bwidth characters
and IK$ATM was set.
> 0 The function key number that terminated
!EDIT.INPUT.
!EDIT.INPUT functions
!EDIT.INPUT performs up to eight editing functions, as follows:
Value Token Description
3 FK$BSP Backspace
4 FK$LEFT Cursor left
5 FK$RIGHT Cursor right
19 FK$INSCH Insert character
21 FK$INSTXT Insert/overlay mode toggle
23 FK$DELCH Delete character
24 FK$DELLIN Delete line
51 FK$CLEOL Clear to end-of-line
The specific keys to perform each function can be automatically
initialized by including the $INCLUDE UNIVERSE.INCLUDE
GTI.FNKEYS.IH statement in the application program.
If any of the values appear in the trap list, its functionality
is disabled and the program immediate exits the !EDIT.INPUT
subroutine when the key associated with that function is
pressed.
Unsupported functions
This implementation does not support a number of functions
originally available in the Prime INFORMATION version. Because
of this, sequences can be generated that inadvertently cause the
!EDIT.INPUT function to terminate. For this reason, you can
create a user-defined terminal keystroke definition file so that
!EDIT.INPUT recognizes the unsupported sequences. Unsupported
sequences cause the !EDIT.INPUT subroutine to ring the terminal
bell, indicating the recognition of an invalid sequence.
The file CUSTOM.GTI.DEFS defines a series of keystroke sequences
for this purpose. You can create the file in each account or in
a central location, with VOC entries in satellite accounts
referencing the remote file. There is no restriction on how the
file can be created. For instance, you can use the command:
>CREATE.FILE CUSTOM.GTI.DEFS 2 17 1 /* Information style */
or:
>CREATE-FILE CUSTOM.GTI.DEFS (1,1,3 17,1,2) /* Pick style */
to create the definition file. A terminal keystroke definition
record assumes the name of the terminal which the definitions
are associated with, for example for vt100 terminals, the
CUSTOM.GTI.DEFS file record ID would be vt100 (case-sensitive).
Each terminal keystroke definition record contains a maximum of
82 fields (attributes) which directly correspond to the
keystroke code listed in the GTI.FNKEYS.IH include file.
The complete listing of the fields defined within the
GTI.FNKEYS.IH include file is shown below:
Key name Field Description
FK$FIN 1 Finish
FK$HELP 2 Help
FK$BSP 3 Backspacea
FK$LEFT 4 Left arrowa
FK$RIGHT 5 Right arrowa
FK$UP 6 Up arrow
FK$DOWN 7 Down arrow
FK$LSCR 8 Left screen
FK$RSCR 9 Right screen
FK$USCR 10 Up screen, Previous page
FK$DSCR 11 Down screen, Next page
FK$BEGEND 12 Toggle begin/end line, or Begin line
FK$TOPBOT 13 Top/Bottom, or End line
FK$NEXTWD 14 Next word
FK$PREVWD 15 Previous word
FK$TAB 16 Tab
FK$BTAB 17 Backtab
FK$CTAB 18 Column tab
FK$INSCH 19 Insert character (space)a
FK$INSLIN 20 Insert line
FK$INSTXT 21 Insert text, Toggle insert/overlay
modea
FK$INSDOC 22 Insert document
FK$DELCH 23 Delete charactera
FK$DELLIN 24 Delete linea
FK$DELTXT 25 Delete text
FK$SRCHNX 26 Search next
FK$SEARCH 27 Search
FK$REPLACE 28 Replace
FK$MOVE 29 Move text
FK$COPY 30 Copy text
FK$SAVE 31 Save text
FK$FMT 32 Call format line
FK$CONFMT 33 Confirm format line
FK$CONFMTNW 34 Confirm format line, no wrap
FK$OOPS 35 Oops
FK$GOTO 36 Goto
FK$CALC 37 Recalculate
FK$INDENT 38 Indent (set left margin)
FK$MARK 39 Mark
FK$ATT 40 Set attribute
FK$CENTER 41 Center
FK$HYPH 42 Hyphenate
FK$REPAGE 43 Repaginate
FK$ABBREV 44 Abbreviation
FK$SPELL 45 Check spelling
FK$FORM 46 Enter formula
FK$HOME 47 Home the cursor
FK$CMD 48 Enter command
FK$EDIT 49 Edit
FK$CANCEL 50 Abort/Cancel
FK$CLEOL 51 Clear to end of line1
FK$SCRWID 52 Toggle between 80 and 132 mode
FK$PERF 53 Invoke DSS PERFORM emulator
FK$INCLUDE 54 DSS Include scratchpad data
FK$EXPORT 55 DSS Export scratchpad data
FK$TWIDDLE 56 Twiddle character pair
FK$DELWD 57 Delete word
FK$SRCHPREV 58 Search previous
FK$LANGUAGE 59 Language
FK$REFRESH 60 Refresh
FK$UPPER 61 Uppercase
FK$LOWER 62 Lowercase
FK$CAPIT 63 Capitalize
FK$REPEAT 64 Repeat
FK$STAMP 65 Stamp
FK$SPOOL 66 Spool record
FK$GET 67 Get record
FK$WRITE 68 Write record
FK$EXECUTE 69 Execute macro
FK$NUMBER 70 Toggle line numbering
FK$DTAB 71 Clear tabs
FK$STOP 72 Stop (current activity)
FK$EXCHANGE 73 Exchange mark and cursor
FK$BOTTOM 74 Move bottom
FK$CASE 75 Toggle case sensitivity
FK$LISTB 76 List (buffers)
FK$LISTD 77 List (deletions)
FK$LISTA 78 List (selects)
FK$LISTC 79 List (commands)
FK$DISPLAY 80 Display (current select list)
FK$BLOCK 81 Block (replace)
FK$PREFIX 82 Prefix a. Indicates supported
functionality.
Example
The following BASIC program sets up three trap keys (using the
!PACK.FNKEYS subroutine), waits for the user to enter input,
then reports how the input was terminated:
$INCLUDE UNIVERSE.INCLUDE GTI.FNKEYS.IH
* Set up trap keys of FINISH, UPCURSOR and DOWNCURSOR
TRAP.LIST = FK$FIN:@FM:FK$UP:@FM:FK$DOWN
CALL !PACK.FNKEYS(TRAP.LIST, Ftable)
* Start editing in INPUT mode, displaying contents in window
KEYS = IK$INS + IK$DIS
* Window edit is at x=20, y=2, of length 10 characters;
* the user can enter up to 30 characters of input into
TextBuffer,
* and the cursor is initially placed on the first character of
the
* window.
TextBuffer=""
CursorPos = 1
CALL !EDIT.INPUT(KEYS, 20, 2, 10, TextBuffer, CursorPos, 30,
Ftable,
ReturnCode)
* On exit, the user's input is within TextBuffer,
* CursorPos indicates the location of the cursor upon exiting,
* and ReturnCode contains the reason for exiting.
BEGIN CASE
CASE CODE = 0 * User pressed RETURN key
CASE CODE = FK$FIN * User pressed the defined
FINISH key
CASE CODE = FK$UP * User pressed the defined
UPCURSOR key
CASE CODE = FK$DOWN * User pressed the defined
DOWNCURSOR key
CASE 1 * Should never happen
END CASE
!ERRNO #
!ERRNO subroutine
Use the !ERRNO subroutine to return the current value of the
operating system errno variable.
Syntax
CALL !ERRNO (variable)
variable is the name of a BASIC variable.
The !ERRNO subroutine returns the value of the system errno
variable after the last call to a GCI subroutine in variable. If
you call a system routine with the GCI, and the system call
fails, you can use !ERRNO to determine what caused the failure.
If no GCI routine was called prior to its execution, !ERRNO
returns 0. The values of errno that apply to your system are
listed in the system include file errno.h.
!FCMP #
!FCMP subroutine
Use the !FCMP subroutine to compare the equality of two
floating-point numeric values as follows:
Syntax
CALL !FCMP (result, number1, number2 )
If number1 is less than number2, result is -1.
If number1 is equal to number2, result is 0.
If number1 is greater than number2, result is 1.
!GET.KEY #
!GET.KEY subroutine
Use the !GET.KEY subroutine to return the next key pressed at
the keyboard. This can be either a printing character, the
Return key, a function key as defined by the current terminal
type, or a character sequence that begins with an escape or
control character not defined as a function key.
Function keys can be automatically initialized by including the
$INCLUDE UNIVERSE.INCLUDES GTI.FNKEYS.IH statement in the
application program that uses the !GET.KEY subroutine.
Syntax
CALL !GET.KEY (string, code)
Qualifiers
Code String value
string Returns the character sequence of the next key pressed at the
keyboard.
code Returns the string interpretation value:
Code String Value
0 A single character that is not part
of any function key sequence. For
example, if A is pressed, code = 0
and string = CHAR(65).
>0 The character sequence associated
with the function key defined by that
number in the GTI.FNKEYS.IH include
file. For example, on a VT100
terminal, pressing the key labeled
--> (right cursor move) returns code
= 5 and string =
CHAR(27):CHAR(79):CHAR(67).
<0 A character sequence starting with an
escape or control character that does
not match any sequence in either the
terminfo entry or the CUSTOM.GCI.DEFS
file.
Example
The following BASIC program waits for the user to enter input,
then reports the type of input entered:
$INCLUDE GTI.FNKEYS.IH
STRING = ' ' ; * initial states of call variables
CODE = -999
* Now ask for input until user hits a "Q"
LOOP
UNTIL STRING[1,1] = "q" OR STRING[1,1] = "Q"
PRINT 'Type a character or press a
function key (q to quit):':
CALL !GET.KEY(STRING, CODE)
* Display meaning of CODE
PRINT
PRINT "CODE = ":CODE:
BEGIN CASE
CASE CODE = 0
PRINT " (Normal
character)"
CASE CODE > 0
PRINT "
(Function key
number)"
CASE 1; * otherwise
PRINT "
(Unrecognized
function key)"
END CASE
* Print whatever is in STRING, as decimal
numbers:
PRINT "STRING = ":
FOR I = 1 TO LEN(STRING)
PRINT
"CHAR(":SEQ(STRING[I,1]):") ":
NEXT I
PRINT
REPEAT
PRINT "End of run."
RETURN
END
!GET.PARTNUM #
!GET.PARTNUM subroutine
Use the !GET.PARTNUM subroutine with distributed files to
determine the number of the part file to which a given record ID
belongs.
Syntax
CALL !GET.PARTNUM (file, record.ID, partnum, status)
file (input) is the file variable of the open distributed file.
record.ID (input) is the record ID.
partnum (output) is the part number of the part file of the
distributed file to which the given record ID maps.
status (output) is 0 for a valid part number or an error number
for an invalid part number. An insert file of equate tokens for
the error numbers is available.
An insert file of equate names is provided to allow you to use
mnemonics for the error numbers. The insert file is called
INFO_ERRORS.INS.IBAS, and is located in the INCLUDE
subdirectory. To use the insert file, specify $INCLUDE statement
SYSCOM INFO_ERRORS.INS.IBAS when you compile the program.
Equate name Description
IE$NOT.DISTFILE The file specified by the file variable
is not a distributed file.
IE$DIST.DICT.OPEN.FAIL The program failed to open the file
dictionary for the distributed file.
IE$DIST.ALG.READ.FAIL The program failed to read the
partitioning algorithm from the
distributed file dictionary.
IE$NO.MAP.TO.PARTNUM The record ID specified is not valid for
this distributed file.
Use the !GET.PARTNUM subroutine to call the partitioning
algorithm associated with a distributed file. If the part number
returned by the partitioning algorithm is not valid, that is,
not an integer greater than zero, !GET.PARTNUM returns a nonzero
status code. If the part number returned by the partitioning
algorithm is valid, !GET.PARTNUM returns a zero status code.
Note: !GET.PARTNUM does not check that the returned part number
corresponds to one of the available part files of the currently
opened file.
Example
In the following example, a distributed file SYS has been
defined with parts and part numbers S1, 5, S2, 7, and S3, 3,
respectively. The file uses the default SYSTEM partitioning
algorithm.
PROMPT ''
GET.PARTNUM = '!GET.PARTNUM'
STATUS = 0
PART.NUM = 0
OPEN '', 'SYS' TO FVAR ELSE STOP 'NO OPEN SYS'
PATHNAME.LIST = FILEINFO(FVAR, FINFO$PATHNAME)
PARTNUM.LIST = FILEINFO(FVAR, FINFO$PARTNUM)
LOOP
PRINT 'ENTER Record ID : ':
INPUT RECORD.ID
WHILE RECORD.ID
CALL @GET.PARTNUM(FVAR, RECORD.ID, PART.NUM, STATUS)
LOCATE PART.NUM IN PARTNUM.LIST<1> SETTING
PART.INDEX THEN
PATHNAME = PATHNAME.LIST <PART.INDEX>
END ELSE
PATHNAME = ''
END
PRINT 'PART.NUM = ':PART.NUM:' STATUS =
':STATUS :'
PATHNAME = ': PATHNAME
REPEAT
END
!GET.PARTNUM returns part number 5 for input record ID 5-1, with
status code 0, and part number 7 for input record ID 7-1, with
status code 0, and part number 3 for input record ID 3-1, with
status code 0. These part numbers are valid and correspond to
available part files of file SYS.
!GET.PARTNUM returns part number 1200 for input record ID
1200-1, with status code 0. This part number is valid but does
not correspond to an available part file of file SYS.
!GET.PARTNUM returns part number 0 for input record ID 5-1, with
status code IE$NO.MAP.TO.PARTNUM, and part number 0 for input
record ID A-1, with status code IE$NO.MAP.TO.PARTNUM, and part
number 0 for input record ID 12-4, with status code
IE$NO.MAP.TO.PARTNUM. These part numbers are not valid and do
not correspond to available part files of the file SYS.
!GET.PATHNAME #
!GET.PATHNAME subroutine
Use the !GET.PATHNAME subroutine to return the directory name
and file name parts of a path name.
Syntax
CALL !GET.PATHNAME (pathname, directoryname, filename, status)
pathname (input) is the path name from which the details are
required.
directoryname (output) is the directory name portion of the path
name, that is, the path name with the last entry name stripped
off.
filename (output) is the file name portion of the path name.
status (output) is the returned status of the operation. A 0
indicates success, another number is an error code indicating
that the supplied path name was not valid.
Example
If pathname is input as /usr/accounts/ledger, directoryname is
returned as /usr/accounts, and filename is returned as ledger.
PATHNAME = "/usr/accounts/ledger "
CALL !GET.PATHNAME(PATHNAME,DIR,FNAME,STATUS)
IF STATUS = 0
THEN
PRINT "Directory portion = ":DIR
PRINT "Entryname portion = ":FNAME
END
!GET.USER.COUNTS #
!GET.USER.COUNTS subroutine
Use the !GET.USER.COUNTS subroutine to return a count of
UniVerse and system users. If any value cannot be retrieved, a
value of -1 is returned.
Syntax
CALL !GET.USER.COUNTS (uv.users, max.uv.users, os.users)
uv.users (output) is the current number of UniVerse users.
max.uv.users (output) is the maximum number of licensed UniVerse
users allowed on your system.
os.users (output) is the current number of operating system
users.
!GET.USERS #
!GET.USERS subroutine
The !GET.USERS subroutine allows a BASIC program access to the
system usage information.
Syntax
CALL !GET.USERS(uv.users,max.users,sys.users,user.info,code)
The user.info argument returns a dynamic array with a field for
each user. Each field is separated by value marks into four
values, containing the following information:
- The UniVerse user number
- The user ID
- The process ID
- The user type
The user type is a character string containing either Terminal
or Phantom.
Example
The following example illustrates the use of the !GET.USERS
subroutine.
0001:USERS = "!GET.USERS"
0002: CALL @USERS(UV.USERS,MAX.USERS,SYS.USERS,USER.INFO,CODE)
0003:CRT "UV.USERS = ":UV.USERS
0004:CRT "MAX.USERS = ":MAX.USERS
0005:CRT "SYS.USERS = ":SYS.USERS
0006:CRT "USER.INFO = ":USER.INFO
0007:CRT "CODE = ":CODE
0008:END
This program returns information similar to the following
example:
UV.USERS = 1
MAX.USERS = 16
SYS.USERS = 1
USER.INFO = -916:@FM:NT
AUTHORITY\system:@FM:916:@FM:Phantom|1172:@FM:NORTHAMERICA\claireg:@FM:1172:@FM:
Terminal
CODE = 0
>ED &BP& TRY.GETUSERS
8 lines long.
!GETPU #
!GETPU subroutine
Use the !GETPU subroutine to read individual parameters of any
logical print channel.
Syntax
CALL !GETPU (key, print.channel, set.value, return.code)
key is a number indicating the parameter to be read.
print.channel is the logical print channel, designated by -1
through 255.
set.value is the value to which the parameter is currently set.
return.code is the code returned.
The !GETPU subroutine allows you to read individual parameters
of logical print channels as designated by print.channel. Print
channel 0 is the terminal unless a PRINTER ON statement has been
executed to send output to the default printer. If you specify
print channel -1, the output is directed to the terminal,
regardless of the status of PRINTER ON or OFF. See the
description of the !SETPU subroutine later in this appendix for
a means of setting individual print.channel parameters.
Equate names for keys
An insert file of equate names is provided to allow you to use
mnemonics rather than key numbers. The name of the insert file
is GETPU.INS.IBAS. Use the $INCLUDE statement compiler directive
to insert this file if you want to use equate names. The
following list shows the equate names and keys for the
parameters:
Mnemonic Key Parameter
PU$MODE 1 Printer mode.
PU$WIDTH 2 Device width (columns).
PU$LENGTH 3 Device length (lines).
PU$TOPMARGIN 4 Top margin (lines).
PU$BOTMARGIN 5 Bottom margin (lines).
PU$LEFTMARGIN 6 Left margin (columns, reset on
printer close). Always returns 0.
PU$SPOOLFLAGS 7 Spool option flags.
PU$DEFERTIME 8 Spool defer time. This cannot be 0.
PU$FORM 9 Spool form (string).
PU$BANNER 10 Spool banner or hold filename
(string).
PU$LOCATION 11 Spool location (string).
PU$COPIES 12 Spool copies. A single copy can be
returned as 1 or 0.
PU$PAGING 14 Terminal paging (nonzero is on).
This only works when PU$MODE is set
to 1.
PU$PAGENUMBER 15 Returns the current page number.
PU$DISABLE 16 0 is returned if print.channel is
enabled; and a 1 is returned if
print.channel is disabled.
PU$CONNECT 17 Returns the number of a connected
print channel or an empty string if
no print channels are connected.
PU$NLSMAP 22 If NLS is enabled, returns the NLS
map name associated with the
specified print channel.
PU$LINESLEFT 1002 Lines left before new page needed.
Returns erroneous values for the
terminal if cursor addressing is
used, if a line wider than the
terminal is printed, or if terminal
input has occurred.
PU$HEADERLINES 1003 Lines used by current header.
PU$FOOTERLINES 1004 Lines used by current footer.
PU$DATALINES 1005 Lines between current header and
footer.
PU$DATACOLUMNS 1006 Columns between left margin and
device width.
The PU$SPOOLFLAGS key
The PU$SPOOLFLAGS key refers to a 32-bit option word that
controls a number of print options. This is implemented as a
16-bit word and a 16-bit extension word. (Thus bit 21 refers to
bit 5 of the extension word.) The bits are assigned as follows:
Bit Description
1 Uses FORTRAN-format mode. This allows the attaching of
vertical format information to each line of the data file. The
first character position of each line from the file does not
appear in the printed output, and is interpreted as follows:
Character Meaning
0 Advances two lines.
1 Ejects to the top of the next page.
+ Overprints the last line.
Space Advances one line.
- Advances three lines (skip two lines).
Any other character is interpreted as
advance one line.
3 Generates line numbers at the left margin.
4 Suppresses header page.
5 Suppresses final page eject after printing.
12 Spools the number of copies specified in an earlier !SETPU
call.
21 Places the job in the spool queue in the hold state.
22 Retains jobs in the spool queue in the hold state after they
have been printed.
other All the remaining bits are reserved.
Equate names for return code
An insert file of equate names is provided to allow you to use
mnemonics rather than key numbers. The name of the insert file
is ERRD.INS.IBAS. Use the $INCLUDE statement to insert this file
if you want to use equate names. The following list shows the
codes returned in the argument return.code:
Code Meaning
0 No error
E$BKEY Bad key (key is out of range)
E$BPAR Bad parameter (value of new.value is out of
range)
E$BUNT Bad unit number (value of print.channel is out
of range)
E$NRIT No write (attempt to set a read-only parameter)
Examples
In this example, the file containing the parameter key equate
names is inserted with the $INCLUDE compiler directive. Later
the top margin parameter for logical print channel 0 is
interrogated. Print channel 0 is the terminal unless a prior
PRINTER ON statement has been executed to direct output to the
default printer. The top margin setting is returned in the
argument TM.SETTING. Return codes are returned in the argument
RETURN.CODE.
$INCLUDE UNIVERSE.INCLUDE GETPU.H
CALL !GETPU(PU$TOPMARGIN,0,TM.SETTING,RETURN.CODE)
The next example does the same as the previous example but uses
the key 4 instead of the equate name PU$TOPMARGIN. Because the
key number is used, it is not necessary for the insert file
GETPU.H to be included.
CALL !GETPU(4,0,TM.SETTING,RETURN.CODE)
The next example returns the current deferred time on print
channel 0 in the variable TIME.RET:
CALL !GETPU(PU$DEFERTIME,0,TIME.RET,RETURN.CODE)
!INLINE.PROMPTS #
!INLINE.PROMPTS subroutine
Use the !INLINE.PROMPTS subroutine to evaluate a string that
contains in-line prompts.
Syntax
CALL !INLINE.PROMPTS (result, string )
In-line prompts have the following syntax:
<<{ control, }...text {, option }>>
result (output) is the variable that contains the result of the
evaluation.
string (input) is the string containing an in-line prompt.
control specifies the characteristics of the prompt, and can be
one of the following:
Prompt Description
@(CLR) Clears the terminal screen.
@(BELL) Rings the terminal bell.
@(TOF) Issues a formfeed character: in most
circumstances this results in the cursor moving
to the top left of the screen.
@ (col, row ) Prompts at the specified column and row number
on the terminal.
A Always prompts when the in-line prompt
containing the control option is evaluated. If
you do not specify this option, the input value
from a previous execution of the prompt is
used.
Cn Specifies that the nth word on the command line
is used as the input value. (Word 1 is the verb
in the sentence.)
F (filename Takes the input value from the specified record
record.id [,fm in the specified file, and optionally, extracts
[,vm [ ,sm]]] ) a value (@VM), or subvalue (@SM), from the
field (@FM). This option cannot be used with
the file dictionary.
In Takes the nth word from the command line, but
prompts if the word is not entered.
R (string ) Repeats the prompt until an empty string is
entered. If string is specified, each response
to the prompt is appended by string between
each entry. If string is not specified, a space
is used to separate the responses.
P Saves the input from an in-line prompt. The
input is then used for all in-line prompts with
the same prompt text. This is done until the
saved input is overwritten by a prompt with the
same prompt text and with a control option of
A, C, I, or S, or until control returns to the
UniVerse prompt. The P option saves the input
from an in-line prompt in the current
paragraph, or in other paragraphs.
Sn Takes the nth word from the command (as in the
In control option), but uses the most recent
command entered at the UniVerse system level to
execute the paragraph, rather than an argument
in the paragraph. This is useful where
paragraphs are nested.
text The prompt to be displayed.
option A valid conversion code or pattern match. A
valid conversion code is one that can be used
with the ICONV function. Conversion codes must
be enclosed in parentheses. A valid pattern
match is one that can be used with the MATCHING
keyword.
If the in-line prompt has a value, that value is substituted for
the prompt. If the in-line prompt does not have a value, the
prompt is displayed to request an input value when the function
is executed. The value entered at the prompt is then substituted
for the in-line prompt.
Note:
Once a value has been entered for a particular prompt, the
prompt continues to have that value until a !CLEAR.PROMPTS
subroutine is called, or control option A is specified. A
!CLEAR.PROMPTS subroutine clears all the values that have been
entered for in-line prompts.You can enclose prompts within
prompts.
Example
A = ""
CALL !INLINE.PROMPTS(A,"You have requested the <<Filename>>
file")
PRINT "A"
The following output is displayed:
Filename=PERSONNEL
You have requested the PERSONNEL file
!INTS #
!INTS subroutine
Use the !INTS subroutine to retrieve the integer portion of
elements in a dynamic array.
Syntax
CALL !INTS (result, dynamic.array)
result (output) contains a dynamic array that comprises the
integer portions of the elements of dynamic.array.
dynamic.array (input) is the dynamic array to process.
The !INTS subroutine returns a dynamic array, each element of
which contains the integer portion of the numeric value in the
corresponding element of the input dynamic.array.
Example
A=33.0009:@VM:999.999:@FM:-4.66:@FM:88.3874
CALL !INTS(RESULT,A)
The following output is displayed:
33VM999FM-4FM88
!MAKE.PATHNAME #
!MAKE.PATHNAME subroutine
Use the !MAKE.PATHNAME subroutine to construct the full path
name of a file.
Syntax
CALL !MAKE.PATHNAME (path1, path2, result, status)
The !MAKE.PATHNAME subroutine can be used to:
- Concatenate two strings to form a path name. The second
string must be a relative path.
- Obtain the fully qualified path name of a file. Where only
one of path1 or path2 is given, !MAKE.PATHNAME returns the
path name in its fully qualified state. In this case, any file
name you specify does not have to be an existing file name.
- Return the current working directory. To do this, specify
both path1 and path2 as empty strings.
path1 (input) is a file name or partial path name. If path1 is
an empty string, the current working directory is used.
path2 (input) is a relative path name. If path2 is an empty
string, the current working directory is used.
result (output) is the resulting path name.
status (output) is the returned status of the operation. 0
indicates success. Any other number indicates either of the
following errors:
Status Description
IE$NOTRELATIVE path2was not a relative path name.
IE$PATHNOTFOUND The path name could not be found
when !MAKE.PATHNAME tried to
qualify it fully.
Example
In this example, the users working directory is /usr/accounts:
ENT = "ledger"
CALL !MAKE.PATHNAME(ENT,"",RESULT,STATUS)
IF STATUS = 0
THEN PRINT "Full name = ":RESULT
The following result is displayed:
Full name = /usr/accounts/ledger
!MATCHES #
!MATCHES subroutine
Use the !MATCHES subroutine to test whether each element of one
dynamic array matches the patterns specified in the elements of
the second dynamic array. Each element of dynamic.array is
compared with the corresponding element of match.pattern. If the
element in dynamic.array matches the pattern specified in
match.pattern, 1 is returned in the corresponding element of
result. If the element from dynamic.array is not matched by the
specified pattern, 0 is returned.
Syntax
CALL !MATCHES (result, dynamic. array , match.pattern )
result (output) is a dynamic array containing the result of the
comparison on each element in dynamic array1.
dynamic.array (input) is the dynamic array to be tested.
match.pattern (input) is a dynamic array containing the match
patterns.
When dynamic.array and match.pattern do not contain the same
number of elements, the behavior of !MATCHES is as follows:
- result always contains the same number of elements as the
longer of dynamic.array or match.pattern.
- If there are more elements in dynamic.array than in
match.pattern, the missing elements are treated as though they
contained a pattern that matched an empty string.
- If there are more elements in match.pattern than in
dynamic.array, the missing elements are treated as though they
contained an empty string.
Examples
The following example returns the value of the dynamic array as
1VM1VM1:
A='AAA4A4':@VM:2398:@VM:'TRAIN'
B='6X':@VM:'4N':@VM:'5A'
CALL !MATCHES(RESULT,A,B)
In the next example, there are missing elements in match.pattern
that are treated as though they contain a pattern that matches
an empty string. The result is 0VM0SM0FM1FM1.
R='AAA':@VM:222:@SM:'CCCC':@FM:33:@FM:'DDDDDD'
S='4A':@FM:'2N':@FM:'6X'
CALL !MATCHES(RESULT,R,S)
In the next example, the missing element in match.pattern is
used as a test for an empty string in dynamic.array, and the
result is 1VM1FM1:
X='AAA':@VM:@FM:''
Y='3A':@FM:'3A'
CALL !MATCHES(RESULT,X,Y)
!MESSAGE #
!MESSAGE subroutine
Use the !MESSAGE subroutine to send a message to another user on
the system. !MESSAGE lets you change and report on the current
users message status.
Syntax
CALL !MESSAGE (key, username, usernum, message, status)
key (input) specifies the operation to be performed. You specify
the option you require with the key argument, as follows:
Key Description
IK$MSGACCEPT Sets message status to accept.
IK$MSGREJECT Sets message status to reject.
IK$MSGSEND Sends message to user.
IK$MSGSENDNOW Sends message to user now.
IK$MSGSTATUS Displays message status of user.
username (input) is the name of the user, or the TTY name, for
send or status operations.
usernum (input) is the number of the user for send/status
operations.
message (input) is the message to be sent.
status (output) is the returned status of the operation as
follows:
Status Description
0 The operation was successful.
IE$NOSUPPORT You specified an unsupported key
option.
IE$KEY You specified an invalid key option.
IE$PAR The username or message you specified
was not valid.
IE$UNKNOWN.USER You tried to send a message to a user
who is not logged in to the system.
IE$SEND.REQ.REC The sender does not have the
MESSAGERECEIVE option enabled.
IE$MSG.REJECTED One or more users have the
MESSAGEREJECT mode set.
Note: The value of message is ignored when key is set to
IK$MSGACCEPT, IK$MSGREJECT, or IK$MSGSTATUS.
Example
CALL !MESSAGE (KEY,USERNAME,USERNUMBER,MESSAGE,CODE)
IF CODE # 0
THEN CALL !REPORT.ERROR ( MY.COMMAND','!MESSAGE',CODE)
!PACK.FNKEYS #
!PACK.FNKEYS subroutine
The !PACK.FNKEYS subroutine converts a list of function key
numbers into a bit string suitable for use with the !EDIT.INPUT
subroutine. This bit string defines the keys which cause
!EDIT.INPUT to exit, enabling the program to handle the specific
keys itself.
Syntax
CALL !PACK.FNKEYS (trap.list, ftable)
Qualifiers
Qualifier Description
trap.list A list of function numbers delimited by field
marks (CHAR(254)), defining the specific keys
that are to be used as trap keys by the
!EDIT.INPUT subroutine.
ftable A bit-significant string of trap keys used in
the ftable parameter of the !EDIT.INPUT
subroutine. This string should not be changed in
any way before calling the !EDIT.INPUT
subroutine.
trap.list can be a list of function key numbers delimited by
field marks (CHAR(254)). Alternatively, the mnemonic key name,
listed below and in the UNIVERSE.INCLUDE file GTI.FNKEYS.IH, can
be used:
Key name Field Description
FK$FIN 1 Finish
FK$HELP 2 Help
FK$BSP 3 Backspacea
FK$LEFT 4 Left arrowa
FK$RIGHT 5 Right arrowa
FK$UP 6 Up arrow
FK$DOWN 7 Down arrow
FK$LSCR 8 Left screen
FK$RSCR 9 Right screen
FK$USCR 10 Up screen, Previous page
FK$DSCR 11 Down screen, Next page
FK$BEGEND 12 Toggle begin/end line, or Begin line
FK$TOPBOT 13 Top/Bottom, or End line
FK$NEXTWD 14 Next word
FK$PREVWD 15 Previous word
FK$TAB 16 Tab
FK$BTAB 17 Backtab
FK$CTAB 18 Column tab
FK$INSCH 19 Insert character (space)a
FK$INSLIN 20 Insert line
FK$INSTXT 21 Insert text, Toggle insert/overlay
modea
FK$INSDOC 22 Insert document
FK$DELCH 23 Delete charactera
FK$DELLIN 24 Delete linea
FK$DELTXT 25 Delete text
FK$SRCHNX 26 Search next
FK$SEARCH 27 Search
FK$REPLACE 28 Replace
FK$MOVE 29 Move text
FK$COPY 30 Copy text
FK$SAVE 31 Save text
FK$FMT 32 Call format line
FK$CONFMT 33 Confirm format line
FK$CONFMTNW 34 Confirm format line, no wrap
FK$OOPS 35 Oops
FK$GOTO 36 Goto
FK$CALC 37 Recalculate
FK$INDENT 38 Indent (set left margin)
FK$MARK 39 Mark
FK$ATT 40 Set attribute
FK$CENTER 41 Center
FK$HYPH 42 Hyphenate
FK$REPAGE 43 Repaginate
FK$ABBREV 44 Abbreviation
FK$SPELL 45 Check spelling
FK$FORM 46 Enter formula
FK$HOME 47 Home the cursor
FK$CMD 48 Enter command
FK$EDIT 49 Edit
FK$CANCEL 50 Abort/Cancel
FK$CLEOL 51 Clear to end of linea
FK$SCRWID 52 Toggle between 80 and 132 mode
FK$PERF 53 Invoke DSS PERFORM emulator
FK$INCLUDE 54 DSS Include scratchpad data
FK$EXPORT 55 DSS Export scratchpad data
FK$TWIDDLE 56 Twiddle character pair
FK$DELWD 57 Delete word
FK$SRCHPREV 58 Search previous
FK$LANGUAGE 59 Language
FK$REFRESH 60 Refresh
FK$UPPER 61 Uppercase
FK$LOWER 62 Lowercase
FK$CAPIT 63 Capitalize
FK$REPEAT 64 Repeat
FK$STAMP 65 Stamp
FK$SPOOL 66 Spool record
FK$GET 67 Get record
FK$WRITE 68 Write record
FK$EXECUTE 69 Execute macro
FK$NUMBER 70 Toggle line numbering
FK$DTAB 71 Clear tabs
FK$STOP 72 Stop (current activity)
FK$EXCHANGE 73 Exchange mark and cursor
FK$BOTTOM 74 Move bottom
FK$CASE 75 Toggle case sensitivity
FK$LISTB 76 List (buffers)
FK$LISTD 77 List (deletions)
FK$LISTA 78 List (selects)
FK$LISTC 79 List (commands)
FK$DISPLAY 80 Display (current select list)
FK$BLOCK 81 Block (replace)
FK$PREFIX 82 Prefix Indicates supported
functionality.
If ftable is returned as an empty string, an error in the
trap.list array is detected, such as an invalid function number.
Otherwise ftable is a bit-significant string which should not be
changed in any way before its use with the !EDIT.INPUT
subroutine subroutine.
Example
The following program sets up three trap keys using the
!PACK.FNKEYS function, then uses the bit string within the
!EDIT.INPUT subroutine:
$INCLUDE UNIVERSE.INCLUDE GTI.FNKEYS.IH
* Set up trap keys of FINISH, UPCURSOR and DOWNCURSOR
TRAP.LIST = FK$FIN:@FM:FK$UP:@FM:FK$DOWN
CALL !PACK.FNKEYS(TRAP.LIST, Ftable)
* Start editing in INPUT mode, displaying contents in window
KEYS = IK$INS + IK$DIS
* Window edit is at x=20, y=2, of length 10 characters;
* the user can enter up to 30 characters of input into
TextBuffer,
* and the cursor is initially placed on the first character of
the
* window.
TextBuffer=""
CursorPos = 1
CALL
!EDIT.INPUT(KEYS,20,2,10,TextBuffer,CursorPos,30,Ftable,ReturnCode)
* On exit, the user's input is within TextBuffer,
* CursorPos indicates the location of the cursor upon exiting,
* and ReturnCode contains the reason for exiting.
BEGIN CASE
CASE CODE = 0
* User pressed RETURN key
CASE CODE = FK$FIN
* User pressed the defined FINISH
key
CASE CODE = FK$UP
* User pressed the defined
UPCURSOR key
CASE CODE = FK$DOWN
* User pressed the defined
DOWNCURSOR key
CASE 1 * Should never happen
END CASE
!REPORT.ERROR #
!REPORT.ERROR subroutine
Use the !REPORT.ERROR subroutine to print explanatory text for a
UniVerse or operating system error code.
Syntax
CALL !REPORT.ERROR (command, subroutine, code)
command is the name of the command that used the subroutine in
which an error was reported.
subroutine is the name of the subroutine that returned the error
code.
code is the error code.
The general format of the message printed by !REPORT.ERROR is as
follows:
Error: Calling subroutine from command. system error code:
message.text.
system is the operating system, or UniVerse.
Text for values of code in the range 0 through 9999 is retrieved
from the operating system. Text for values of code over 10,000
is retrieved from the SYS.MESSAGES file. If the code has no
associated text, a message to that effect is displayed. Some
UniVerse error messages allow text to be inserted in them. In
this case, code can be a dynamic array of the error number,
followed by one or more parameters to be inserted into the
message text.
Examples
CALL !MESSAGE (KEY,USERNAME,USERNUMBER,MESSAGE,CODE)
IF CODE # 0
THEN CALL !REPORT.ERROR ( MY.COMMAND','!MESSAGE',CODE)
If code was IE$SEND.REQ.REC, !REPORT.ERROR would display the
following:
Error calling "!MESSAGE" from "MY.COMMAND" UniVerse error 1914:
Warning: Sender requires "receive" enabled!
The next example shows an error message with additional text:
CALL !MESSAGE (KEY,USERNAME,USERNUMBER,MESSAGE,CODE)
IF CODE # 0
THEN CALL !REPORT.ERROR (
MY.COMMAND','!MESSAGE',CODE:@FM:USERNAME)
If code was IE$UNKNOWN.USER, and the user ID was joanna,
!REPORT.ERROR would display the following:
Error calling "!MESSAGE" from "MY.COMMAND" UniVerse error 1757:
joanna is not logged on
!SET.PTR #
!SET.PTR subroutine
Use the !SET.PTR subroutine to set options for a logical print
channel. This subroutine provides the same functionality as the
UniVerse SETPTR (UNIX) or SETPTR (Windows platforms) command.
Syntax
CALL !SET.PTR (print.channel, width, length, top.margin,
bottom.margin, mode, options)
print.channel is the logical printer number, -1 through 255. The
default is 0.
width is the page width. The default is 132.
length is the page length. The default is 66.
top.margin is the number of lines left at the top of the page.
The default is 3.
bottom.margin is the number of lines left at the bottom of the
page. The default is 3.
mode is a number 1 through 5 that indicates the output medium,
as follows:
- 1 - Line Printer Spooler Output (default).
- 2, 4, 5 - Assigned Device. To send output to an assigned
device, you must first assign the device to a logical print
channel, using the UniVerse ASSIGN command. The ASSIGN command
issues an automatic SETPTR command using the default
parameters, except for mode, which it sets to 2. Use !SET.PTR
only if you have to change the default parameters.
- 3 - Hold File Output. Mode 3 directs all printer output to a
file called &HOLD&. If a &HOLD& file does not exist in your
account, !SET.PTR creates the file and its dictionary
(D_&HOLD&). You must execute !SET.PTR with mode 3 before each
report to create unique report names in &HOLD&. If the report
exists with the same name, the new report overwrites.
options are any of the printer options that are valid for the
SETPTR command. These must be separated by commas and enclosed
by valid quotation marks.
If you want to leave a characteristic unchanged, supply an empty
string argument and specify the option NODEFAULT. If you want
the default to be selected, supply an empty string argument
without specifying the NODEFAULT option.
Printing on the last line and printing a heading
If you print on the last line of the page or screen and use a
HEADING statement to print a heading, your printout will have
blank pages. The printer or terminal is set to advance to the
top of the next page when the last line of the page or screen is
printed. The HEADING statement is set to advance to the top of
the next page to print the heading.
Example
The following example sets the options so that printing is
deferred until 12:00, and the job is retained in the queue:
CALL !SET.PTR (0,80,60,3,3,1,'DEFER 12:00,RETAIN)
!SETPU #
!SETPU subroutine
Use the !SETPU subroutine to set individual parameters of any
logical print channel.
Syntax
CALL !SETPU (key, print.channel, new.value, return.code)
Unlike !SET.PTR subroutine, you can specify only individual
parameters to change; you need not specify parameters you do not
want to change. See the description of the !GETPU subroutine
subroutine for a way to read individual print.channel
parameters.
key is a number indicating the parameter to be set (see !GETPU
subroutine).
print.channel is the logical print channel, designated by -1
through 255.
new.value is the value to which you want to set the parameter.
return.code is the returned error code (see !GETPU subroutine).
The !SETPU subroutine lets you change individual parameters of
logical print channels as designated by print.channel. Print
channel 0 is the terminal unless a PRINTER ON statement has been
executed to send output to the default printer. If you specify
print channel -1, the output is directed to the terminal,
regardless of the status of PRINTER ON or PRINTER OFF.
Equate names for keys
An insert file of equate names is provided to allow you to use
mnemonics rather than key numbers. The name of the insert file
is GETPU.INS.IBAS. Use the $INCLUDE compiler directive to insert
this file if you want to use the equate names. For a description
of the $INCLUDE statement compiler directive, see UniVerse
BASIC. The following list shows the equate names and keys for
the parameters:
Mnemonic Key Parameter
PU$MODE 1 Printer mode.
PU$WIDTH 2 Device width (columns).
PU$LENGTH 3 Device length (lines).
PU$TOPMARGIN 4 Top margin (lines).
PU$BOTMARGIN 5 Bottom margin (lines).
PU$SPOOLFLAGS 7 Spool option flags (see !GETPU
subroutine).
PU$DEFERTIME 8 Spool defer time. This cannot be 0.
PU$FORM 9 Spool form (string).
PU$BANNER 10 Spool banner or hold file name
(string).
PU$LOCATION 11 Spool location (string).
PU$COPIES 12 Spool copies. A single copy can be
returned as 1 or 0.
PU$PAGING 14 Terminal paging (nonzero is on). This
only works when PU$MODE is set to 1.
PU$PAGENUMBER 15 Sets the next page number.
The PU$SPOOLFLAGS key
The PU$SPOOLFLAGS key refers to a 32-bit option word that
controls a number of print options. This is implemented as a
16-bit word and a 16-bit extension word. (Thus bit 21 refers to
bit 5 of the extension word.) The bits are assigned as follows:
Bit Description
1 Uses FORTRAN-format mode. This allows the attaching of
vertical format information to each line of the data file. The
first character position of each line from the file does not
appear in the printed output, and is interpreted as follows:
Character Meaning
0 Advances two lines.
1 Ejects to the top of the next page.
+ Overprints the last line.
Space Advances one line.
- Advances three lines (skip two lines). Any
other character is interpreted as advance
one line.
3 Generates line numbers at the left margin.
4 Suppresses header page.
5 Suppresses final page eject after printing.
12 Spools the number of copies specified in an earlier !SETPU
call.
21 Places the job in the spool queue in the hold state.
22 Retains jobs in the spool queue in the hold state after they
have been printed.
other All the remaining bits are reserved.
Equate names for return code
An insert file of equate names is provided to allow you to use
mnemonics rather than key numbers. The name of the insert file
is ERRD.INS.IBAS. Use the $INCLUDE statement to insert this file
if you want to use equate names. The following list shows the
codes returned in the argument return.code:
Code Meaning
0 No error
E$BKEY Bad key (key is out of range)
E$BPAR Bad parameter (value of new.value is out of
range)
E$BUNT Bad unit number (value of print.channel is out
of range)
E$NRIT No write (attempt to set a read-only parameter)
Printing on the last line and printing a heading
If you print on the last line of the page or screen and use a
HEADING statement to print a heading, your printout will have
blank pages. The printer or terminal is set to advance to the
top of the next page or screen when the last line of the page or
screen is printed. The HEADING statement is set to advance to
the top of the next page to print the heading.
Examples
In the following example, the file containing the parameter key
equate names is inserted with the $INCLUDE compiler directive.
Later, the top margin parameter for logical print channel 0 is
set to 10 lines. Return codes are returned in the argument
RETURN.CODE.
$INCLUDE SYSCOM GETPU.INS.IBAS
CALL !SETPU(PU$TOPMARGIN,0,10,RETURN.CODE)
The next example does the same as the previous example, but uses
the key 4 instead of the equate name PU$TOPMARGIN. Because the
key is used, it is not necessary for the insert file
GETPU.INS.IBAS to be included.
CALL !SETPU(4,0,10,RETURN.CODE)
!TIMDAT #
!TIMDAT subroutine
Use the !TIMDAT subroutine to return a dynamic array containing
the time, date, and other related information. The !TIMDAT
subroutine returns a 13-element dynamic array containing
information shown in the following list.
Syntax
CALL !TIMDAT (variable)
variable is the name of the variable to which the dynamic array
is to be assigned.
Field Description
1 Month (two digits).
2 Day of month (two digits).
3 Year (two digits).
4 Minutes since midnight (integer).
5 Seconds into the minute (integer).
6 Ticks of last second since midnight (integer). Always
returns 0.
Tick refers to the unit of time your system uses to
measure real time.
7 CPU seconds used since entering UniVerse.
8 Ticks of last second used since login (integer).
9 Disk I/O seconds used since entering UniVerse. Always
returns -1.
10 Ticks of last disk I/O second used since login
(integer). Always returns -1.
11 Number of ticks per second.
12 User number.
13 Login ID (user ID).
Use the following functions for alternative ways of obtaining
time and date information:
Use this To obtain this data...
function...
DATE function Data in fields 1, 2, and 3 of the dynamic
array returned by the !TIMDAT subroutine
TIME function Data in fields 4, 5, and 6 of the dynamic
array returned by the !TIMDAT subroutine
@USERNO User number
@LOGNAME Login ID (user ID)
Example
CALL !TIMDAT(DYNARRAY)
FOR X = 1 TO 13
PRINT 'ELEMENT ':X:', DYNARRAY
NEXT X
!USER.TYPE #
!USER.TYPE subroutine
Use the !USER.TYPE subroutine to return the user type of the
current process and a flag to indicate if the user is a UniVerse
Administrator.
Syntax
CALL !USER.TYPE (type, admin)
type is a value that indicates the type of process making the
subroutine call. type can be either of the following:
Equate Name Value Meaning
U$NORM 1 Normal user
U$PH 65 Phantom
admin is a value that indicates if the user making the call is a
UniVerse Administrator. Possible values of admin are 1, if the
user is a UniVerse Administrator, and 0, if the user is not a
UniVerse Administrator.
An insert file of equate names is provided for the !USER.TYPE
values. To use the equate names, specify the directive $INCLUDE
SYSCOM USER_TYPES.H when you compile your program. (For PI/open
compatibility you can specify $INCLUDE SYSCOM
USER_TYPES.INS.IBAS.)
Example
In this example, the !USER.TYPE subroutine is called to
determine the type of user. If the user is a phantom, the
program stops. If the user is not a phantom, the program sends a
message to the terminal and continues processing.
ERROR.ACCOUNTS.FILE: CALL !USER.TYPE(TYPE, ADMIN)
IF TYPE = U&PH THEN STOP
ELSE PRINT 'Error on opening ACCOUNTS file'
!VOC.PATHNAME #
!VOC.PATHNAME subroutine
Use the !VOC.PATHNAME subroutine to extract the path names for
the data file or the file dictionary of a specified VOC entry.
Syntax
CALL !VOC.PATHNAME (data/dict, voc.entry, result, status)
data/dict (input) indicates the file dictionary or data file, as
follows:
- IK$DICT or 'DICT' returns the path name of the file
dictionary of the specified VOC entry.
- IK$DATA or ' ' returns the path name (or path names for
distributed files) of the data file of the specified VOC
entry.
voc.entry is the record ID in the VOC.
result (output) is the resulting path names.
status (output) is the returned status of the operation.
An insert file of equate names is provided for the data/dict
values. To use the equate names, specify the directive $INCLUDE
SYSCOM INFO_KEYS.H when you compile your program. (For PI/open
compatibility you can specify $INCLUDE SYSCOM
INFO_KEYS.INS.IBAS.)
The result of the operation is returned in the status argument,
and has one of the following values:
Value Result
0 The operation executed successfully.
IE$PAR A bad parameter was used in data/dict or
voc.entry.
IE$RNF The VOC entry record cannot be found.
Example
CALL !VOC.PATHNAME (IK$DATA,"VOC",VOC.PATH,STATUS)
IF STATUS = 0
THEN PRINT "VOC PATHNAME = ":VOC.PATH
If the users current working directory is /usr/account, the
output is:
VOC PATHNAME = /usr/accounts/VOC
#INCLUDE #
#INCLUDE statement
Use the #INCLUDE statement to direct the compiler to insert the
source code in the record program and compile it with the main
program. The #INCLUDE statement differs from the $CHAIN
statement in that the compiler returns to the main program and
continues compiling with the statement following the #INCLUDE
statement.
Syntax
#INCLUDE [filename] program
#INCLUDE program FROM filename
When program is specified without filename, program must be a
record in the same file as the program containing the #INCLUDE
statement.
If program is a record in a different file, the file name must
be specified in the #INCLUDE statement, followed by the name of
the program. The file name must specify a type 1 or type 19 file
defined in the VOC file.
You can nest #INCLUDE statements.
The #INCLUDE statement is a synonym for the $INCLUDE and INCLUDE
statements.
Example
PRINT "START"
#INCLUDE END
PRINT "FINISH"
When this program is compiled, the #INCLUDE statement inserts
code from the program END (see the example on the END
statement). This is the program output:
START
THESE TWO LINES WILL PRINT ONLY
WHEN THE VALUE OF 'A' IS 'YES'.
THIS IS THE END OF THE PROGRAM
$* #
$* statement
Use the $* statement to insert a comment in UniVerse BASIC
object code. Comments explain or document various parts of a
program. They are nonexecutable.
Syntax
$*[comment.text]
A comment must be a separate UniVerse BASIC statement and can
appear anywhere in a program.
Any text appearing between the $* and the end of a physical line
is treated as part of the comment, not as part of the executable
program. If a comment does not fit on one physical line, you can
continue it on the next physical line only by starting the new
line with another $*. If a comment appears at the end of a
physical line containing an executable statement, you must put a
semicolon (; ) before the $*.
Example
The PRINT statement at the end of the third line is not executed
because it follows the exclamation point on the same line and is
treated as part of the comment. Lines 4, 5, and 6 show how to
include a comment in the same sequence of executable statements.
001: PRINT "HI THERE"; $* Anything after the $* is a comment.
002: $* This line is also a comment and does not print.
003: IF 5<6 THEN PRINT "YES"; $* A comment; PRINT "PRINT ME"
004: IF 5<6 THEN
005: PRINT "YES"; $* A comment
006: PRINT "PRINT ME"
007: END
This is the program output:
HI THERE
YES
YES
PRINT ME
$CHAIN #
$CHAIN statement
Use the $CHAIN statement to direct the compiler to read source
code from program and compile it as if it were part of the
current program. The $CHAIN statement differs from the $INCLUDE
statement, #INCLUDE statement, and INCLUDE statement in that the
compiler does not return to the main program. Any statements
appearing after the $CHAIN statement are not compiled or
executed.
Syntax
$CHAIN [filename] program
When the program name is specified without a file name, the
source code to insert must be in the same file as the current
program.
If the source code to insert is in a different file, the $CHAIN
statement must specify the name of the remote file followed by
the program name. filename must specify a type 1 or type 19 file
defined in the VOC file.
When statements in program generate error messages, the messages
name the program containing the $CHAIN statement.
Example
PRINT "START"
$CHAIN END
PRINT "FINISH"
When this program is compiled, the $CHAIN statement inserts code
from the program END (see the example in END statement). This is
the program output:
START
THESE TWO LINES WILL PRINT ONLY
WHEN THE VALUE OF 'A' IS 'YES'.
THIS IS THE END OF THE PROGRAM
$COPYRIGHT #
$COPYRIGHT statement
Use the $COPYRIGHT statement to specify copyright information in
UniVerse BASIC object code. copyright.notice is inserted in the
copyright field at the end of the object code.
Syntax
$COPYRIGHT "copyright.notice"
copyright.notice must be enclosed in single or double quotation
marks.
The copyright field in the object code is set to the empty
string at the beginning of compilation. It remains empty until
the program encounters a $COPYRIGHT statement.
If more than one $COPYRIGHT statement is included in the
program, only the information included in the last one
encountered is inserted in the object code.
This statement is included for compatibility with existing
software.
$DEFINE #
$DEFINE statement
Use the $DEFINE statement to define identifiers that control
program compilation. $DEFINE has two functions:
- Defining an identifier
- Supplying replacement text for an identifier
Syntax
$DEFINE identifier [replacement.text ]
Parameters
Parameter Description
identifier The symbol to be defined. It can be any valid
identifier.
replacement.text A string of characters that the compiler uses
to replace identifier everywhere it appears in
the program containing the $DEFINE statement.
When used as a replacement text supplier, $DEFINE adds the
specified identifier and its associated replacement.text to the
symbol table. Each time identifier is found in the program
following the $DEFINE statement in which its value was set, it
is replaced by replacement.text. If replacement.text is not
specified, identifier is defined and has a null value.
Separate replacement.text from identifier with one or more
blanks. Every character typed after this blank is added to
replacement.text up to, but not including, the Return character
that terminates the replacement.text.
Note: Do not use comments when supplying replacement.text
because any comments after replacement.text are included as part
of the replacement text. Any comments added to replacement.text
can cause unexpected program behavior.
UniVerse does not supported nested $DEFINE/$UNDEFINE statements.
The $UNDEFINE statement removes the definition of an identifier.
Conditional compilation
You can use $DEFINE with the $IFDEF statement or $IFNDEF
statement to define an identifier that controls conditional
compilation. The syntax is as follows:
$DEFINE identifier [replacement.text]
.
.
.
{ $IFDEF | $IFNDEF } identifier
[statements]
$ELSE
[statements]
$ENDIF
The $IFDEF or $IFNDEF statement that begins the conditional
compilation block tests identifier to determine whether it is
defined by a $DEFINE statement. If you use $IFDEF and identifier
is defined, the statements between the $IFDEF and the $ELSE
statements are compiled. If identifier is not defined, the
statements between the $ELSE statements and the $ENDIF
statements are compiled.
If you use $IFNDEF, on the other hand, and identifier is
defined, the statements between $ELSE and $ENDIF are compiled.
If identifier is not defined, the statements between the $IFDEF
statement and the $ELSE statements are compiled.
Conditional compiler directives
Conditional compiler directives allow the inclusion of code and
features available in later releases of UniVerse to be included
in programs used in earlier releases. The newer, unavailable
features are ignored by the compiler on older UniVerse releases.
This helps developers avoid maintaining multiple code streams
for the various releases of UniVerse.
The following compiler definitions are available in UniVerse
BASIC. Note that the directives with "UNIVERSE" in the name use
a double underscore.
- U2__UNIVERSE
- U2__UNIVERSEv11
- U2__UNIVERSEv11.2
- U2__UNIVERSEv11.3
- U2_LOCALCALL
For example, specifying $IFDEF U2__UNIVERSEv11.2, allows the use
of 11.2 functionality within the $IFDEF statement. The
U2_LOCALCALL identifier can be used for local subroutines and
variables without being specific to 11.2. Using $IFDEF with the
UniVerse supplied identifiers allows for compiling a program on
an earlier release where the code contained in the $IFDEF
statement will be ignored.
Note: The $UNDEFINE statement cannot be used to remove the
UniVerse supplied identifiers.
Example
In this example the identifier NAME.SUFFIX is defined to have a
value of PROGRAM.NAME[5]. When the compiler processes the next
line, it finds the symbol NAME.SUFFIX, substitutes
PROGRAM.NAME[5] in its place and continues processing with the
first character of the replacement text.
$DEFINE NAME.SUFFIX PROGRAM.NAME[5]
IF NAME.SUFFIX = '.B' THEN
.
.
.
END
.
.
.
$EJECT #
$EJECT statement
Use the $EJECT statement to begin a new page in the listing
record.
Syntax
$EJECT
This statement is a synonym for the $PAGE statement.
$IFDEF #
$IFDEF statement
Use the $IFDEF statement to test for the definition of a
compile-time symbol. $IFDEF tests to see if identifier is
currently defined (that is, has appeared in a $DEFINE statement
and has not been undefined).
If identifier is currently defined and the $ELSE clause is
omitted, the statements between the $IFDEF and $ENDIF statements
are compiled. If the $ELSE clause is included, only the
statements between $IFDEF and $ELSE are compiled.
If identifier is not defined and the $ELSE clause is omitted,
all the lines between the $IFDEF and $ENDIF statements are
ignored. If the $ELSE clause is included, only the statements
between $ELSE and $ENDIF are compiled.
Both the IFDEF statement and $IFNDEF statement can be nested up
to 10 deep.
Syntax
$IFDEF identifier [statements] [[$ELSE] [statements]] $ENDIF
Example
The following example determines if the identifier "modified" is
defined:
$DEFINE modified 0
$IFDEF modified
PRINT "modified is defined."
$ELSE
PRINT "modified is not defined."
$ENDIF
$IFNDEF #
$IFNDEF statement
Use the $IFNDEF statement to test for the definition of a
compile-time symbol. The $IFNDEF statement complements the
$IFDEF statement.
If identifier is currently not defined and the $ELSE clause is
omitted, the statements between the $IFNDEF and $ENDIF
statements are compiled. If the $ELSE clause is included, only
the statements between $IFNDEF and $ELSE are compiled.
If identifier is defined and the $ELSE clause is omitted, all
the lines between the $IFNDEF and $ENDIF statements are ignored.
If the $ELSE clause is included, only the statements between
$ELSE and $ENDIF are compiled.
$IFDEF and $IFNDEF statements can be nested up to 10 deep.
Syntax
$IFNDEF identifier [statements] [[$ELSE] [statements]] $ENDIF
Example
The following example determines if the identifier "modified" is
not defined:
$DEFINE modified 0
$IFNDEF modified
PRINT "modified is not defined."
$ELSE
PRINT "modified is defined."
$ENDIF
$INCLUDE #
$INCLUDE statement
Use the $INCLUDE statement to direct the compiler to insert the
source code in the record program and compile it with the main
program. The $INCLUDE statement differs from the $CHAIN
statement in that the compiler returns to the main program and
continues compiling with the statement following the $INCLUDE
statement.
Syntax
$INCLUDE [filename] program
$INCLUDE program FROM filename
When program is specified without filename, program must be a
record in the same file as the program currently containing the
$INCLUDE statement.
If program is a record in a different file, the file name must
be specified in the $INCLUDE statement, followed by the name of
the program. The file name must specify a type 1 or type 19 file
defined in the VOC file.
You can nest $INCLUDE statements.
The $INCLUDE statement is a synonym for the #INCLUDE and INCLUDE
statements.
Example
PRINT "START"
$INCLUDE END
PRINT "FINISH"
When this program is compiled, the $INCLUDE statement inserts
code from the program END (see the example in END statement).
This is the program output:
START
THESE TWO LINES WILL PRINT ONLY
WHEN THE VALUE OF 'A' IS 'YES'.
THIS IS THE END OF THE PROGRAM
$INSERT #
$INSERT statement
Use the $INSERT statement to direct the compiler to insert the
source code contained in the file specified by primos.pathname
and compile it with the main program. The difference between the
$INSERT statement and $INCLUDE statement (and its synonyms
#INCLUDE and INCLUDE) is that $INSERT takes a PRIMOS path name
as an argument, whereas $INCLUDE takes a UniVerse file name and
record ID. The PRIMOS path is converted to a path; any leading
*> is ignored.
$INSERT is included for compatibility with Prime INFORMATION
programs; the $INCLUDE statement is recommended for general use.
Syntax
$INSERT primos.pathname
If primos.pathname is the name of the program only, it is
interpreted as a relative path. In this case, the program must
be a file in the same directory as the program containing the
$INSERT statement.
You can nest $INSERT statements.
primos.pathname is converted to a valid path using the following
conversion rules:
Conversion rules
/ is converted to ?\
? is converted to ??
ASCII CHAR 0 (NUL) is converted to ?0
. (period) is converted to ?.
If you specify a full path name, the > between directory names
changes to a / to yield:[pathname/] program
$INSERT uses the transformed argument directly as a path of the
file containing the source to be inserted. It does not use the
file definition in the VOC file.
Example
PRINT "START"
$INSERT END
PRINT "FINISH"
When this program is compiled, the $INSERT statement inserts
code from the program END (see the example in END statement).
This is the program output:
START
THESE TWO LINES WILL PRINT ONLY
WHEN THE VALUE OF 'A' IS 'YES'.
THIS IS THE END OF THE PROGRAM
FINISH
$MAP #
$MAP statement
In NLS mode, use the $MAP statement to direct the compiler to
specify the map for the source code. Use the $MAP statement if
you use embedded literal strings that contain non-ASCII
characters.
Syntax
$MAP mapname
mapname must be the name of a map that has been built and
installed.
You can use only one $MAP statement during compilation.
Note: You can execute programs that contain only ASCII
characters whether NLS mode is on or off. You cannot execute
programs that contain non-ASCII characters that were compiled in
NLS mode if NLS mode is switched off.
For more information, see the Rocket UniVerse NLS User Guide.
Example
The following example assigns a string containing the three
characters alpha, beta, and gamma to the variable GREEKABG:
$MAP MNEMONICS
.
.
.GREEKABG = "<A*><B*><G*>"
$OPTIONS #
$OPTIONS statement
Use the $OPTIONS statement to set compile-time emulation of any
UniVerse flavor. This does not allow object code compiled in one
flavor to execute in another flavor. You can select individual
options in a program to override the default setting.
Note: You must specify $OPTIONS for each internal subroutine.
Syntax
$OPTIONS [flavor] [options]
Flavor keywords
Use the following keywords to specify flavor:
Keyword Flavor
PICK Generic Pick emulation
INFORMATION Prime INFORMATION emulation
REALITY REALITY emulation
IN2 Intertechnique emulation
DEFAULT IDEAL UniVerse
PIOPEN PI/open emulation
For instance, the following statement instructs the compiler to
treat all UniVerse BASIC syntax as if it were running in a PICK
flavor account:
$OPTIONS PICK
Another way to select compile-time emulation is to specify one
of the following keywords in field 6 of the VOC entry for the
BASIC command:
INFORMATION.FORMAT
PICK.FORMAT
REALITY.FORMAT
IN2.FORMAT
PIOPEN.FORMAT
By default the VOC entry for the BASIC command corresponds with
the account flavor specified when your UniVerse account was set
up.
Options keywords
options are specified by the keywords listed in following table.
To turn off an option, prefix it with a minus sign (-).
Option name Option Description
letter
CASE none Differentiates between uppercase and
lowercase identifiers and keywords.
COMP.PRECISION none Rounds the number at the current
precision value in any comparison.
COUNT.OVLP O For the INDEX function and the COUNT
function, the count overlaps.
DIM.IN.SUB By default, arrays passed as arguments
in a subroutine call cannot be
redimensioned in the subroutine. An
attempt to redimension the array is
simply ignored. If you set the
DIM.IN.SUB option through the $OPTIONS
statement, you can redimension the array
in a subroutine. See the following
example:
>AE BP CALLER SUBTEST
CALLER
0001 DIM A(10)
0002 CALL SUBTEST(MAT A)
0003 CRT A(100)
0004 END
SUBTEST
0001 SUBROUTINE SUBTEST(MAT A)
0002 $OPTIONS DIM.IN.SUB
0003 DIM A(100)
0004 A(100) = 100
0005 RETURN
0006 END
>RUN BP CALLER
100
END.WARN R Prints a warning message if there is no
final END statement.
EXEC.EQ.PERF P Compiles the EXECUTE statement as the
PERFORM statement.
Note: If the syntax of the EXECUTE
statement is changed so it is no longer
compatible with the PERFORM statement,
UniVerse ignores EXEC.EQ.PERF. For
example, UniVerse ignores EXEC.EQ.PERF
in the following program:
0001 "$OPTIONS EXEC.EQ.PERF
0002 EXECUTE 'DATE' CAPTURING RESULTS
0003 END
EXTRA.DELIM W For the INSERT function and the REPLACE
function, the compiler handles fields,
values, and subvalues that contain the
empty string differently from the way
they are handled in the IDEAL flavor. In
particular, if you specify a negative
one (-1) parameter, INFORMATION and IN2
flavors add another delimiter, except
when starting with an empty string.
FOR.INCR.BEF F Increments the index for FOR...NEXT loop
before instead of after the bound
checking.
FORMAT.OCONV none Lets output conversion codes be used as
format masks (see the FMT function).
FSELECT none Makes the SELECT statements return the
total number of records selected to the
@SELECTED variable. Using this option
can result in slower performance for the
SELECT statement.
HEADER.BRK none Specifies the PIOPEN flavor for the I
and P options to the HEADING statement
and FOOTING statement. This is the
default for the PIOPEN flavor.
HEADER.DATE D Displays times and dates in headings or
footings in fixed format (that is, they
do not change from page to page). Dates
are displayed in 'D2-' format instead of
'D' format. Allows page number field
specification by multiple invocations of
'P' in a single set of quotation marks.
HEADER.EJECT H HEADING statement causes initial page
eject.
IN2.SUBSTR T Uses IN2 definitions for UniVerse BASIC
substring handling (string[n,m]). If a
single parameter is specified, a length
of 1 is assumed. The size of the string
expands or contracts according to the
length of the replacement string.
INFO.ABORT J ABORT statement syntax follows Prime
INFORMATION instead of PICK.
INFO.CONVERT none Specifies that the FMT, ICONV, and OCONV
functions perform PI/open style
conversions.
INFO.ENTER none Specifies the PIOPEN flavor of the ENTER
statement.
INFO.INCLUDE none Processes any PRIMOS paths specified
with the $INSERT statement.
INFO.LOCATE L LOCATE syntax follows Prime INFORMATION
instead of REALITY. The Pick format of
the LOCATE statement is always supported
in all flavors.
INFO.MARKS none Specifies that the LOWER, RAISE, and
REMOVE functions use a smaller range of
delimiters for PI/open compatibility.
INFO.MOD none Specifies the PIOPEN flavor for the MOD
function. This is the default for the
PIOPEN flavor.
INPUTAT none Specifies the PIOPEN flavor for the
INPUT @ statement. This is the default
for the PIOPEN flavor.
INPUT.ELSE Y Accepts an optional THEN...ELSE clause
on INPUT statement.
INT.PRECISION none Rounds the integer at the current
precision value in an INT function.
LOCATE.R83 none A LOCATE statement returns an "AR" or
"DR" sequence value compatible with
Pick, Prime INFORMATION, and PI/open
systems.
NO.CASE none Does not differentiate between uppercase
and lowercase in identifiers or
keywords. This is the default for the
PIOPEN flavor.
NO.RESELECT U For the SELECT statements and SSELECT
statement, active select list 0 remains
active; another selection or sort is not
performed. The next READNEXT statement
uses select list 0.
NO.RETURN.WARN none Suppresses display of warning messages
from ambiguous RETURN statements.
ONGO.RANGE G If the value used in an ON...GOTO or
ON...GOSUB is out of range, executes the
next statement rather than the first or
last branch.
PCLOSE.ALL Z The PRINTER CLOSE statement closes all
print channels.
PERF.EQ.EXEC C The PERFORM statement compiles as the
EXECUTE statement.
PIOPEN.EXECUTE none EXECUTE behaves similarly to the way it
does on PI/open systems.
PIOPEN.INCLUDE none Processes any PRIMOS paths specified
with the $INSERT statement and the
$INCLUDE statement.
PIOPEN.MATREAD none Sets the elements of the matrix to empty
strings when the record ID is not found.
MATREAD, MATREADL, and MATREADU will
behave as they do on PI/open systems.
PIOPEN.SELIDX none In the SELECTINDEX statement, removes
multiple occurrences of the same record
ID in an index with a multivalued field.
RADIANS none Calculates trigonometric operations
using radians instead of degrees.
RAW.OUTPUT none Suppresses automatic mapping of system
delimiters on output. When an
application handles terminal control
directly, RAW.OUTPUT turns off this
automatic mapping.
READ.RETAIN Q If READ statements, READU statement,
READV statement, READVL statement, or a
READVU statement fail, the resulting
variable retains its value. The variable
is not set to an empty string.
REAL.SUBSTR K Uses REALITY flavor definitions for
substring handling (string[n,m]). If m
or n is less than 0, the starting
position for substring extraction is
defined as the right side (the end) of
the string.
RNEXT.EXPL X A READNEXT statement returns an exploded
select list.
SEQ.255 N SEQ(" ") = 255 (instead of 0).
STATIC.DIM M Creates arrays at compile time, not at
run time. The arrays are not
redimensioned, and they do not have a
zero element.
STOP.MSG E Causes a STOP statement and an ABORT
statement to use the ERRMSG file to
produce error messages instead of using
the specified text.
STRING.MATH none Causes UniVerse BASIC to automatically
use the SADD, SSUB, SDIV, and SMUL
functions rather than +, -, /, and *.
This option also applies to the INT,
ABS, NEG, and MOD functions.
SUPP.DATA.ECHO I Causes input statements to suppress echo
from data.
TIME.MILLISECOND none Causes the SYSTEM (12) function to
return the current system time in
milliseconds, and the TIME function to
return the current system time in
seconds.
ULT.FORMAT none Format operations are compatible with
Ult/ix. For example, FMT("","MR2")
returns an empty string, not 0.00.
USE.ERRMSG B The PRINTERR statement prints error
messages from ERRMSG.
VAR.SELECT S SELECT TO variable creates a local
select variable instead of using
numbered select lists, and the READLIST
statement reads a saved select list
instead of an active numbered select
list.
VEC.MATH V Uses vector arithmetic instructions for
operating on multivalued data. For
performance reasons the IDEAL flavor
uses singlevalued arithmetic.
WIDE.IF none Testing numeric values for true or false
uses the wide zero test. In Release 6 of
UniVerse, the WIDE.IF option is OFF by
default. In Release 7, WIDE.IF is ON by
default.
You can also set individual options by using special versions of
some statements to override the current setting. These are
listed as follows:
Statement Equal to...
ABORTE The ABORT statement with $OPTIONS STOP.MSG
ABORTM ABORT with $OPTIONS -STOP.MSG
HEADINGE The HEADING statement with $OPTIONS HEADER.EJECT
HEADINGN HEADING with $OPTIONS -HEADER.EJECT
SELECTV The SELECT statements with $OPTIONS VAR.SELECT
SELECTN SELECT with $OPTIONS -VAR.SELECT
STOPE The STOP statement with $OPTIONS STOP.MSG
STOPM STOP with $OPTIONS -STOP.MSG
The default settings for each flavor are listed in the following
table:
IDEAL PICK INFO REALITY IN2 PIOPEN
CASE X
COMP.PRECISION
COUNT.OVLP X X X
END.WARN X X X
EXEC.EQ.PERF X X
EXTRA.DELIM X X X
FOR.INC.REF X X X X
FORMAT.OCONV X
FSELECT
HEADER.BRK X
HEADER.DATE X X
HEADER.EJECT X X
IN2.SUBSTR X X X
INFO.ABORT X
INFO.CONVERT
INFO.ENTER X
INFO.LOCATE X X
INFO.MARKS X
INFO.MOD X
INPUTAT X
INPUT.ELSE X X
INT.PRECISION
LOCATE.R83
NO.CASE X
NO.RESELECT X X X X
NO.SMA.COMMON
ONGO.RANGE X X
PCLOSE.ALL X X X
PERF.EO.EXEC X X
PIOPEN.EXECUTE
PIOPEN.INCLUDE X
PIOPEN.MATREAD
PIOPEN.SELIDX X
RADIANS X
RAW.OUTPUT
READ.RETAIN X X X
REAL.SUBSTR X X X
RNEXT.EXPL X
SEQ.255 X X X
STATIC.DIM X X X
STOP.MSG X X X
SUPP.DATA.ECHO X X X
ULT.FORMAT
USE.ERRMSG X
VAR.SELECT X X X
VEC.MATH X X
WIDE.IF X X X X X
Example
>ED BP OPT
4 lines long.
----: P
0001: $OPTIONS INFORMATION
0002: A='12'
0003: B='14'
0004: PRINT A,B
Bottom at line 4
----: Q
>BASIC BP OPT
Compiling: Source = 'BP/OPT', Object = 'BP.O/OPT'
@EOF WARNING: Final 'END' statement not found.
Compilation Complete.
>ED BP OPT
4 lines long.
----: P
0001: $OPTIONS PICK
0002: A='12'
0003: B='14'
0004: PRINT A,B
Bottom at line 4
----: Q
>BASIC BP OPT
Compiling: Source = 'BP/OPT', Object = 'BP.O/OPT'
Compilation Complete.
$PAGE #
$PAGE statement
The $PAGE statement is a synonym for the $EJECT statement.
$UNDEFINE #
$UNDEFINE statement
Use the $UNDEFINE statement to remove the definition of
identifiers set with the $DEFINE statement. The $UNDEFINE
statement removes the definition of identifier from the symbol
table if it appeared in a previous $DEFINE statement. If the
identifier was not previously defined, $UNDEFINE has no effect.
Syntax
$UNDEFINE identifier
identifier is the identifier whose definition is to be deleted
from the symbol table.
You can use $UNDEFINE with the $IFDEF statement or $IFNDEF
statement to undefine an identifier that controls conditional
compilation. The syntax is as follows:
$UNDEFINE identifier
.
.
.
{ $IFDEF | $IFNDEF }identifier
[statements]
$ELSE
[statements]
$ENDIF
The $IFDEF statement that begins the conditional compilation
block tests identifier to determine whether it is currently
defined. Using this syntax, the $UNDEFINE statement deletes the
definition of identifier from the symbol table, and the
statements between the $ELSE and the $ENDIF statements are
compiled.
If you use the $IFNDEF statement, on the other hand, and
identifier is undefined, the statements between $IFDEF and
$ENDIF are compiled. If identifier is not defined, the
statements between $IFDEF and $ELSE are compiled.
Note: UniVerse does not support nested $DEFINE/$UNDEFINE
statements.
* statement
Use the * statement to insert a comment in a UniVerse BASIC
program. Comments explain or document various parts of a
program. They are part of the source code only and are
nonexecutable. They do not affect the size of the object code.
Syntax
* [comment.text]
A comment must be a separate UniVerse BASIC statement, and can
appear anywhere in a program. A comment must begin with one of
the following comment designators:
- REM
- *
- !
- $*
Any text that appears between a comment designator and the end
of a physical line is treated as part of the comment, not as
part of the executable program. If a comment does not fit on one
physical line, you can continue it on the next physical line
only by starting the new line with a comment designator. If a
comment appears at the end of a physical line containing an
executable statement, you must put a semicolon (; ) before the
comment designator.
Example
The PRINT statement at the end of the third line is not executed
because it follows the asterisk on the same line and is treated
as part of the comment. Lines 4, 5, and 6 show how to include a
comment in the same sequence of executable statements.
PRINT "HI THERE"; * Anything after the * is a comment
* This line is also a comment and does not print.
IF 5<6 THEN PRINT "YES"; * A comment; PRINT "PRINT ME"
IF 5<6 THEN
PRINT "YES"; * A comment
PRINT "PRINT ME"
END
This is the program output:
HI THERE
YES
YES
PRINT ME
< > #
< > operator
Use the < > operator (angle brackets) to extract or replace
elements of a dynamic array.
Syntax
variable < field# [ ,value# [,subvalue#]] >
Parameters
Parameter Description
variable Specifies the dynamic array containing the data
to be changed.
field#, value#, Delimiter expressions.
subvalue #
Angle brackets to the left of an assignment operator change the
specified data in the dynamic array according to the assignment
operator. For examples, see the REPLACE function. Angle
brackets to the right of an assignment operator indicate that an
EXTRACT function is to be performed. For examples, see the FADD
function.
@() #
@ function
Use the @ function with the PRINT statement to control display
attributes, screen display, and cursor positioning.
Note: You can save processing time by assigning the result of a
commonly used @ function, such as @ (-1), to a variable, rather
than reevaluating the function each time it is used.
Syntax
@ (column [,row])
@(-code [,arg ])
Parameters
Parameter Description
column Defines a screen column position.
row Defines a screen row position.
-code The terminal control code that specifies a
particular screen or cursor function.
arg Specifies further information for the screen or
cursor function specified in -code.
Cursor positioning
You position the cursor by specifying a screen column and row
position using the syntax @ (column [,row]). If you do not
specify a row, the current row is the default. The top line is
row 0, the leftmost column is column 0. If you specify a column
or row value that is out of range, the effect of the function is
undefined.
If you use the @ function to position the cursor, automatic
screen pagination is disabled.
Screen and cursor controls
You can use the @ function with terminal control codes to
specify various cursor and display operations using the syntax @
(-code [ ,arg]).
If you want to use mnemonics rather than the code numbers, you
can use an insert file of equate names by specifying either of
the following options when you compile your program:
$INCLUDE UNIVERSE.INCLUDE ATFUNCTIONS.H
$INCLUDE SYSCOM ATFUNCTIONS.INS.IBAS (PIOPEN flavor only)
Note: Not all terminal control codes are supported by all
terminal types. If the current terminal type does not support
the code you specified, the function returns an empty string.
You can use this to test whether your program operates correctly
on a particular terminal, and whether you need to code any
alternative actions.
If you issue multiple video attributes (such as blink and
reverse video) at the same time, the result is undefined. See
the description of the @ function for details of additive
attributes.
The following table summarizes the characteristics of the
terminal control codes, and the sections following the table
give more information on each equate name:
Integer Equate name Function Argument
-1 IT$CS Screen
clear and
home
-2 IT$CAH Cursor home
-3 IT$CLEOS Clear to
end of
screen
-4 IT$CLEOL Clear to
end of line
-5 IT$SBLINK Start blink
-6 IT$EBLINK Stop blink
-7 IT$SPA Start
protect
-8 IT$EPA Stop protect
-9 IT$CUB Back space Number of
one characters to
character back space
-10 IT$CUU Move up one Number of lines
line to move
-11 IT$SHALF Start
half-intensi
ty
-12 IT$EHALF Stop
half-intensi
ty
-13 IT$SREV Start
reverse
video
-14 IT$EREV Stop
reverse
video
-15 IT$SUL Start
underlining
-16 IT$EUL Stop
underlining
-17 IT$IL Insert line Number of lines
to insert
-18 IT$DL Delete line Number of lines
to delete
-19 IT$ICH Insert Number of lines
ch