Saturday | 20 APR 2024

Pick (UniVerse) BASIC Manual


!
!ASYNC
!EDIT.INPUT
!ERRNO
!FCMP
!GET.KEY
!GET.PARTNUM
!GET.PATHNAME
!GET.USER.COUNTS
!GET.USERS
!GETPU
!INLINE.PROMPTS
!INTS
!MAKE.PATHNAME
!MATCHES
!MESSAGE
!PACK.FNKEYS
!REPORT.ERROR
!SET.PTR
!SETPU
!TIMDAT
!USER.TYPE
!VOC.PATHNAME
#INCLUDE
$*
$CHAIN
$COPYRIGHT
$DEFINE
$EJECT
$IFDEF
$IFNDEF
$INCLUDE
$INSERT
$MAP
$OPTIONS
$PAGE
$UNDEFINE
*
< >
@()
@VARIABLES
ABORT
ABS()
ABSS()
ACOS()
ACTIVATEKEY
ADDS()
ALPHA()
ANDS()
ASCII()
ASIN()
ASSIGNED()
ATAN()
AUTHORIZATION
AUXMAP
AuditLog()
BEGIN CASE
BEGIN TRANSACTION
BITAND()
BITNOT()
BITOR()
BITRESET()
BITSET()
BITTEST()
BITXOR()
BREAK
BSCAN
BYTE()
BYTELEN()
BYTETYPE()
BYTEVAL()
CALL
CASE
CATS()
CENTURY.PIVOT()
CHAIN
CHANGE()
CHAR()
CHARS()
CHECKSUM()
CLEAR
CLEARCOMMON
CLEARDATA
CLEARFILE
CLEARPROMPTS
CLEARSELECT
CLOSE
CLOSESEQ
COL1()
COL2()
COMMAND.EDITOR
COMMIT
COMMON
COMPARE()
CONVERT
CONVERT()
COS()
COSH()
COUNT()
COUNTS()
CREATE
CRT
CloseXMLData()
DATA
DATE()
DBTOXML()
DCOUNT()
DEACTIVATEKEY
DEBUG
DEFFUN
DEL
DELETE
DELETE()
DELETELIST
DESCRINFO()
DIGEST()
DIMENSION
DISABLEDEC
DISPLAY
DIV()
DIVS()
DOWNCASE()
DQUOTE()
DTX()
EBCDIC()
ECHO
ENABLEDEC
ENCODE()
ENCRYPT()
END
END CASE
END TRANSACTION
ENTER
EOF(ARG.)
EQS()
EQUATE
EREPLACE()
ERRMSG
EXCHANGE()
EXECUTE
EXIT
EXP()
EXTRACT()
FADD()
FDIV()
FFIX()
FFLT()
FIELD()
FIELDS()
FIELDSTORE()
FIELDWRITE
FILEINFO()
FILELOCK
FILEUNLOCK
FIND
FINDSTR
FIX()
FLUSH
FMT()
FMTDP()
FMTS()
FMTSDP()
FMUL()
FOLD()
FOLDDP()
FOOTING
FOR
FORMLIST
FSUB()
FUNCTION
GES()
GET
GET(ARG.)
GETLIST
GETLOCALE()
GETREM()
GETX
GOSUB
GOTO
GROUP()
GROUPSTORE
GTS()
HEADING
HMAC()
HUSH
ICHECK()
ICONV()
ICONVS()
IF
IFS()
ILPROMPT()
INCLUDE
INDEX()
INDEXS()
INDICES()
INMAT()
INPUT
INPUTCLEAR
INPUTDISP
INPUTDP
INPUTERR
INPUTIF
INPUTNULL
INPUTTRAP
INS
INSERT()
INT()
ISNULL()
ISNULLS()
ITYPE()
KEYEDIT
KEYEXIT
KEYIN()
KEYTRAP
LEFT()
LEN()
LENDP()
LENS()
LENSDP()
LES()
LET
LN()
LOCALEINFO()
LOCATE
LOCATE INFORMATION
LOCK
LOOP
LOWER()
LTS()
MAT
MATBUILD
MATCH
MATCHFIELD()
MATPARSE
MATREAD
MATREADL
MATREADU
MATWRITE
MATWRITEU
MAXIMUM()
MINIMUM()
MOD()
MODS()
MQCLOSE()
MQCONN()
MQDISC()
MULS()
NAP
NEG()
NEGS()
NES()
NEXT
NLS
NOBUF
NOT()
NOTS()
NULL
NUM()
NUMS()
OCONV()
OCONVS()
ON
OPEN
OPENCHECK
OPENDEV
OPENPATH
OPENSEQ
ORS()
OpenXMLData()
PAGE
PERFORM
PRECISION
PRINT
PRINTER
PRINTERR
PROCREAD
PROCWRITE
PROGRAM
PROMPT
PWR()
PrepareXML()
PyCall()
PyCallFunction()
PyCallMethod()
PyGetAttr()
PyImport()
PySetAttr()
QUOTE()
RAISE()
RANDOMIZE
READ
READBLK
READL
READLIST
READNEXT
READSEQ
READT
READU
READV
READVL
READVU
REAL()
RECORDLOCK
RECORDLOCKED()
RELEASE
REM
REM()
REMOVE
REMOVE()
REPEAT
REPLACE()
RETURN
RETURN (value)
REUSE()
REVREMOVE
REWIND
RIGHT()
RND()
ROLLBACK
ROUND()
RPC.CALL()
RPC.CONNECT()
RPC.DISCONNECT()
RQM
ReadXMLData()
ReleaseXML()
SADD()
SCMP()
SDIV()
SEEK
SEEK(ARG.)
SELECT
SELECTE
SELECTINDEX
SELECTINFO()
SEND
SENTENCE()
SEQ()
SEQS()
SET TRANSACTION ISOLATION LEVEL
SETLOCALE()
SETREM
SIGNATURE()
SIN()
SINH()
SLEEP
SMUL()
SOAPCreateRequest()
SOAPCreateSecureRequest()
SOAPGetDefault()
SOAPGetFault()
SOAPGetResponseHeader()
SOAPRequestWrite()
SOAPSetDefault()
SOAPSetParameters()
SOAPSetRequestBody()
SOAPSetRequestContent()
SOAPSetRequestHeader()
SOAPSubmitRequest()
SOUNDEX()
SPACE()
SPACES()
SPLICE()
SQRT()
SQUOTE()
SSELECT
SSUB()
STATUS
STATUS()
STOP
STORAGE
STR()
STRS()
SUBR()
SUBROUTINE
SUBS()
SUBSTRINGS()
SUM()
SUMMATION()
SWAP
SYSTEM()
TABSTOP
TAN()
TANH()
TERMINFO()
TIME()
TIMEDATE()
TIMEOUT
TPARM()
TPRINT
TRANS()
TRANSACTION ABORT
TRANSACTION COMMIT
TRANSACTION START
TRIM()
TRIMB()
TRIMBS()
TRIMF()
TRIMFS()
TRIMS()
TRUNC()
TTYCTL
TTYGET
TTYSET
UDOArrayAppendItem()
UDOArrayDeleteItem()
UDOArrayGetItem()
UDOArrayGetNextItem()
UDOArrayGetSize()
UDOArrayInsertItem()
UDOArraySetItem()
UDOClone()
UDOCreate()
UDODeleteProperty()
UDOFree()
UDOGetLastError()
UDOGetNextProperty()
UDOGetOption()
UDOGetProperty()
UDOGetPropertyNames()
UDOGetType()
UDOIsTypeOf()
UDORead()
UDOSetOption()
UDOSetProperty()
UDOWrite()
UNASSIGNED()
UNICHAR()
UNICHARS()
UNISEQ()
UNISEQS()
UNLOCK
UPCASE()
UPRINT
USERINFO()
WEOF
WEOFSEQ
WRITE
WRITEBLK
WRITELIST
WRITESEQ
WRITESEQF
WRITET
WRITEU
WRITEV
WRITEVU
XDOMAddChild()
XDOMAppend()
XDOMClone()
XDOMClose()
XDOMCreateNode()
XDOMCreateRoot()
XDOMEvaluate()
XDOMGetAttribute()
XDOMGetChildNodes()
XDOMGetElementByld()
XDOMGetElementsByName()
XDOMGetElementsByTag()
XDOMGetNodeName()
XDOMGetNodeType()
XDOMGetNodeValue()
XDOMGetOwnerDocument()
XDOMGetUserData()
XDOMItem()
XDOMLength()
XDOMLocate()
XDOMLocateNode()
XDOMOpen()
XDOMQuery()
XDOMRemove()
XDOMReplace()
XDOMSetNodeValue()
XDOMSetUserData()
XDOMTransform()
XDOMValidate()
XDOMWrite()
XLATE()
XMAPAppendRec()
XMAPClose()
XMAPCreate()
XMAPOpen()
XMAPReadNext()
XMAPToXMLDoc()
XMLError()
XMLExecute()
XMLGetError()
XMLTODB()
XTD()
[]
acceptConnection()
addAuthenticationRule()
addCertificate()
addRequestParameter()
amInitialize()
amReceiveMsg()
amReceiveRequest()
amSendMsg()
amSendRequest()
amSendResponse()
amTerminate()
analyzeCertificate()
assignment
closeSocket()
createCertRequest()
createCertificate()
createRequest()
createSecureRequest()
createSecurityContext()
generateKey()
getCipherSuite()
getHTTPDefault()
getIpv()
getSocketErrorMessage()
getSocketInformation()
getSocketMap()
getSocketOptions()
initSecureServerSocket()
initServerSocket()
loadSecurityContext()
openSecureSocket()
openSocket()
protocolLogging()
readSocket()
saveSecurityContext()
setAuthenticationDepth()
setCipherSuite()
setClientAuthentication()
setHTTPDefault()
setIpv()
setPrivateKey()
setRandomSeed()
setRequestHeader()
setSocketMap()
setSocketOptions()
showSecurityContext()
submitRequest()
transaction
uvsysmon
writeSocket()

! #


! 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 #


!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