GENERAL SYS SYSTEM FUNCTION CALLS

SYS system function calls allow a user program to perform special I/O functions, to establish special characteristics for a job, to set terminal characteristics, and to cause the monitor to execute special operations.

The specified SYS format is employed for two reasons. One, the calls are unique to the RSTS/E implementation of the BASIC language. As such, the calls are system dependent and have calling formats different from any BASIC language call. Second, the SYS format allows the usage of a variable number of parameters.

SYS calls are separated into two classes: privileged and nonprivileged. The privileged calls can be used only by a privileged user or by a privileged program. The nonprivileged calls can be used by anyone and are completely safe in the sense that their misuse can do no damage to other programs or to the system.

7.1.1 SYS System Function Fonnats and Codes The general format of the SYS call is as follows:

V$ = SYS(CHR$(F%) + 0$) where:

V$ is the target string returned by the call F% is the SYS system function code

0$ is the optional (by function code) parameter string passed by the call

Function codes denoted by F% in the general format are from zero through eleven, inclusive. SYS calls which specify a code outside of these numbers or which pass a zero length string generate the ILLEGAL SYS() USAGE error (ERR

=

18). Table 7-1 summarizes the codes and their usages. The subsequent pages describe the usage, calling format, and purpose of the calls.

Table 7-1 SYS System Function Codes Function

Code (F) Usage

0 Cancel

to

effect on terminal

1 Enter tape mode on terminal

2 Enable echoing on terminal 3 Disable echoing on terminal

4 Enable delimiterless character input mode (ODT submode) on terminal

5 Exit with no prompt message

7.1.2 General SYS System Function Calls

7.1.2.1 Cancel

to

Effect on Terminal Not Privileged Data Passed:

Byte(s)

2

3

Meaning CHR$(O%), the cancel

to

effect code

CHR$(N%) where N% is the number (between 0 and 12) of the channel on which the system executes the call. If this byte is not specified, chaimel

o

is used.

CHR$(K%) where K% is the number (between 0 and 127) of the keyboard assigned but not open by the job. This follows the multiple terminal service rule. The keyboard is the slave terminal under control of a master terminal open on the channel specified in byte 2.

If this byte is not specified, the keyboard effected is the one open on the channel specified in byte 2.

Data Returned: The target string is equivalent to the passed string.

Discussion:

This call cancels the effect of the user typing a CTRL/O combination at the terminal specified. The terminal is selected by channel number given in byte 2. (The terminal must be open on that channel.) If a slave terminal is to be used, byte 2 must be a nonzero channel number (on which the master terminal is open) and byte 3 denotes the keyboard number of the slave terminal. See the RSTS/E System User's Guide for a description of the CTRL/O combination.

7-2

7.1.2.2 Enter Tape Mode on Terminal - Not Privileged Data Passed:

Byte(s)

2

3

Meaning CHR$(l%), the enter tape mode code

CHR$(N%) where N% is the number (between 0 and 12) of the channel on which the system executes the call. If this byte is not specified, channel 0 is used.

CHR$(K%) where K% is the number (between 0 and 127) of the key-board assigned but not open by the job. This follows the multiple terminal service rule. The keyboard is the slave terminal under control of a master terminal open on the channel specified in byte 2.

If this byte is not specified, the keyboard effected is the one open on the channel specified in byte 2.

Data Returned: The target string is equivalent to the passed string.

Discussion:

The action of this call is the same as that of the TAPE command described in the RSTS/E System User's Guide.

The terminal is selected by channel number given in byte 2. (The terminal must be open on that channel.) If a slave terminal is to be used, byte 2 must be a nonzero channel number (on which the master terminal is open) and byte 3 denotes the keyboard number of the slave terminal.

7.1.2.3 Enable Echoing on Terminal - Not Privileged Data Passed:

Byte(s) 1 2

3

Meaning CHR$(2%), the enable echoing code

CHR$(N%) where N% is the number (between 0 and 12) of the channel on which the system executes the call. If this byte is not specified, channel 0 is used.

CHR$(K%) where K% is the number (between 0 and 127) of the keyboard assigned but not open by the job. This follows the multiple terminal service rule. The keyboard is the slave terminal under control of a master terminal open on the channel specified in byte 2.

If this byte is not specified, the keyboard effected is the one open on the channel specified in byte 2.

Data Returned: The target string is equivalent to the passed string.

Discussion:

This code cancels the effect of SYS calls with Codes 1 and 3. The terminal is selected by channel number given in byte 2. (The terminal must be open on that channel.) If a slave terminal is to be used, byte 2 must be a nonzero channel number (on which the master terminal is open) and byte 3 denotes the keyboard number of the slave terminal.

7-4

7.1.2.4 Disable Echoing on Terminal - Not Privileged Data Passed:

Byte(s) 1 2

3

Meaning CHR$(3%), the disable echoing code

CHR$(N%) where N% is the number (between 0 and 12) of the channel on which the system executes the call. If this byte is not specified, channel 0 is used.

CHR$(K%) where K% is the number (between 0 and 127) of the keyboard assigned but not open by the job. This follows the multiple terminal service rule. The keyboard is the slave terminal under control of a master terminal open on the channel specified in byte 2.

If this byte is not specified, the keyboard effected is the one open on the channel specified in byte 2.

Data Returned: The target string is equivalent to the passed string.

Discussion:

This call prevents the system from echoing information typed at the terminal. As a result, information such as a password is kept secret but accepted as valid input by the system. The terminal is selected by channel number given in byte 2. (The terminal must be open on that channel.) If a slave terminal is to be used, byte 2 must be a nonzero channel number (on which the master terminal is open) and byte 3 denotes the keyboard number of the slave terminal.

7.1.2.5 Enable Delimiterless Character Input Mode (ODT Submode) on Terminal - Not Privileged Data Passed:

Byte(s)

2

3

Meaning

CHR$( 4%), the enable single character input mode code

CHR$(N%) where N% is the number (between 0 and 12) of the channel on which the system executes the call. If this byte is not specified, channel 0 is used.

CHR$(K%) where K% is the number (between 0 and 127) of the keyboard assigned but not open by the job. This follows the multiple tenninal service rule. The keyboard is the slave terminal under control of a master terminal open on the channel specified in byte 2.

If this byte is not specified, the keyboard effected is the one open on the channel specified in byte 2.

Data Returned: The target string is equivalent to the passed string.

Discussion:

This call allows less than a full line to be accepted as input from the terminal. Normally, the system waits until a line tenninated by a RETURN, LINE FEED, FORM FEED, or ESCAPE character or CTRL/D combination has been typed before accepting input. In delimiterless character mode, one or more characters typed at the tenninal are passed immediately to the program by the next keyboard input request statement without waiting for a delimiting character.

This function must be enabled prior to every input request statement that immediately passes characters to the program. A GET statement is used as the input request statement. (INPUT or INPUT LINE statements cause repeated generation of the input request until a line terminator is detected and, therefore, must not be used.) If a program performs other lengthy operations before it executes either another SYS call and GET statement or other input/output operation at the terminal, it allows time for the user to type more than one character. To provide for such a possibility, the program should examine the system variable RECOUNT after executing each GET statement. This procedure determines how many characters the user typed between keyboard input operations and enables the program to process all the characters without losing any.

Since this function is used in the system program ODT.BAS, it is sometimes referred to as "ODT submode". The terminal is selected by channel number given in byte 2. (The terminal must be open on that channel.) If a slave terminal is to be used, byte 2 must be a nonzero channel number (on which the master terminal is open) and byte 3 denotes the keyboard number of the slave terminal.

7-6

7.1.2.6 Exit with No Prompt Message - Not Privileged Data Passed:

Byte(s) Meaning

CHR$(5%), the exit with no prompt code Data Returned: No data is returned.

Discussion:

This type of exit does not clear the program from memory and thus allows the user to continue running the program.

The following are the specific effects.

1. No mes are closed

2. The current program state is saved (to allow a continue) 3. No prompting message is generated

4. The BASIC-PLUS editor waits for a command

7.1.2.7 FIP Function Call - Both Privileged and Not Privileged See Section 7.2 for a description of SYS calls to the me processor.

7-8

7.1.2.8 Get Core Common String - Not Privileged Data Passed:

Byte(s) Meaning

1 CHR$(7%), the get core common string code

Data Returned: The target string is the contents of the job core common area.

Discussion:

Allows a program to extract a single string from a data area loaded by another program previously run by the same job. The data area is called the core common and is from 0 to 127 8-bit bytes long. This call does not alter the contents of the core common area. Refer to SYS function code 8.

7.1.2.9 Put Core Common String - Not Privileged Data Passed:

Byte(s) Meaning

CHR$(8%), the put core common string code

2-128 The string to put in the core common area

Data Returned: The target string is the passed string.

Discussion:

Allows a program to load a single string in a common data area called core common. This string can be extracted "-later by another program, running under the same job and called via the CHAIN statement. The string is from 0 to

127 8·bit bytes long. If the string to be put into the core common area is longer than 127 bytes, the system sets the length of the core common string to O. Refer to SYS function code 7.

This function provides a means for passing a limited amount of information when a CHAIN statement is executed.

If a larger amount of information is to be passed, it must be written to a disk me and read back by the later program.

7-10

7.1.2.10 Exit and Clear Program - Not Privileged Data Passed:

Byte(s)

2-3

4-5

Meaning CHR$(9%), the exit and set up NONAME code

First 3 characters of the name of the run time system, in Radix-50 format, to which control is passed.

Last 3 characters of the name of the run time system, in Radix-50 format, to which control is passed.

Data Returned: The target string is equivalent to the passed string.

Discussion:

This call clears the current program from memory and returns control to the user's private run time system. It also __ closes all channels without cleaning up partial buffers. (That is, any I/O in pr<:>gress is not completed). This is the

proper way of stopping a program that is not to be rerun. Such programs are those that terminate on an error and are privileged. The same action is performed by the command NEW NONAME.

If bytes 2 through 5 specify a run time system, the call transfers control to that run time system and establishes it as the job's private default run time system. If bytes 2 through 5 are not specified, control is transferred to the job's private default run time system.

The run time system to which control is returned prints its prompting message. For the BASIC-PLUS run-time system, two prompts are possible. If the job is logged into the system, BASIC-PLUS prints carriage return, line feed, and Ready followed by one carriage return and two line feeds. If the job is not logged in, BASIC-PLUS prints carriage return, line feed and BYE followed by one carriage return and two line feeds.

7.1.2.11 Cancel All Type Ahead - Not Privileged Data Passed:

Byte(s) 1 2

3

Meaning CHR$(11 %), the cancel type ahead code

CHR$(N%) where N% is the number (between 0 and 12) of the channel on which the system executes the call. If this byte is not specified, channel 0 is used

CHR$(K%) where K% is the number (between 0 and 127) of the keyboard assigned but not open by the job. This follows the multiple terminal service rule. The keyboard is the slave terminal under control of a master terminal open on the channel specified in byte 2.

If this' byte is not specified, the keyboard effected is the one open on the channel specified in byte 2.

Data Returned: The target string is equivalent to the passed string.

Discussion:

This call clears all unread, pending input from a terminal's buffers. This cancels any input typed in advance of programmed solicitation of input. The application of this call is mainly for echo control operations where echoing of unsolicited input ruins the visual indication in painted fields. Refer to Section 4.3.3 for the discussion of controlling echo and declaring a field on a screen to have a special paint character.

The terminal is selected by channel number given in byte 2. (The terminal must be open on that channel.) If a slave terminal is to be used, byte 2 must be a nonzero channel number (on which the master terminal is open) and byte 3 denotes the keyboard number of the slave terminal.

Dans le document RSTS/E Programming Manual (Page 88-99)