A-Shell Reference

xcall ASCEBC, record

xcall EBCASC, record

ASCEBC and EBCASC convert the specified record from ASCII to EBCDIC and from EBCDIC to ASCII, respectively. The single parameter is a string or unformatted record of any size, which will be converted in place.  

xcall CCON {,flag}

xcall CCOFF

CCON enables or disables Ctrl+C. When called with no arguments, or if the argument passed has a non-zero numeric value, then it enables Ctrl+C. When called with an argument that evaluates to zero, it disables Ctrl+C and is therefore equivalent to CCOFF.

CCOFF disables Ctrl+C. This might be useful in a program at the start of a critical update sequence that you did not want the operator to be able to interrupt. It is also equivalent to SET NOCTRLC (from the dot prompt).

xcall CHKONE, c$

CHKONE is similar to TINKEY in that it allows you to check if a keyboard character is available, without getting stuck waiting if there is no character available. However, unlike TINKEY, which returns the actual character if available, CHKONE returns a "0" if no character is available, else "1". Any available characters remain in the input buffer, waiting for you to use another input routine to get them. c$ is a one-byte string.

xcall CMDR

Calling CMDR has the same effect as if the line :R were executed in a command file. It can be particularly useful when trying to integrate command files and BASIC programs in order to implement more .LIT A-Shell commands.

CMDR has no effect if the command file is currently in either :R or :T modes.

xcall FORCE, job, string {,status}

FORCE is a programmatic equivalent to the FORCE.LIT user command, both of which provide a scheme for forcing characters into another job’s input stream.

FORCE relies on the same mechanism as SEND, which see for notes on limitations specific to particular operating system environments.

xcall GETPPN, ppn

GETPPN returns the current PPN in the two-byte format (first byte is project number, second byte is programmer number).

Note that the two-byte PPN format is largely obsolete, as of build 897, which supports decimal PPNs up to 999,999. You are better off using one of the other routines which retrieve the ppn, which retrieve the PPN in string format, such as LOG or GETJTB, or as a pair of two-byte binaries, such as XPPN.

xcall IMAGE, opcode, handle, status {,params...}

Aside from the difference in calling syntax, IMAGE is nearly identical to the subroutine AUI_IMAGE, which see for full documentation. It is normally preferable to use AUI_IMAGE rather than IMAGE because AUI_IMAGE supports ATE while IMAGE is only implemented under Windows.

xcall JOBNUM, jobnumber

JOBNUM returns the current job number (in any numeric parameter format).

Note that the job number is established when the session is launched, as the position within the job table, and remains fixed for the duration of a session.

xcall MSGLOG, text, code, status

MSGLOG is equivalent to the version under AMOS, except for the format of the opr:syslog.sys file. Under AMOS, the file is binary coded and requires SYSLOG.LIT to format and display it. Under A-Shell, the file is a simple text file which can be printed or displayed directly.

As the name suggests, NOP does nothing, aside from serving as a useful target for ALIAS directives to effectively disable an existing xcall that maybe be embedded in your code but no longer serves any purpose. If by some odd coincidence you have created a subroutine called NOP.SBX that actually does something, you will need to use the ALIAS system parameter to create an alias for either NOP or your existing SBX.

History

2024 July, A-Shell 7.0.1761:  Routine added to A-Shell.

xcall RXTERM, exitcode

RXTERM (Windows only) looks in the type-ahead buffer to see if a function key or Ctrl+C character has been entered, and if so, returns the INFLD-compatible exitcode. This can be useful to short-circuit some program actions and provide immediate response to a function key command.

xcall XDEFLT, string

XDEFLT inserts characters (string) into the type-ahead buffer. The characters will sit in the type-ahead buffer until the next input operation, when they will act like they were typed at that point. If the type-ahead string contains carriage returns, and/or the next input operation is limited in length, then the unused remainder of the type-ahead string will be used on the subsequent input operation, until it is all used up.

xcall XPAINT, paintlit

XPAINT was developed to allow screens that were created with AlphaPAINT 2.0 to be executed by A-Shell. Under AMOS, these screens are assembled into LIT file executables, which are typically executed via AMOS.SBR. Since AMOS machine code will not run on other operating systems directly, A-Shell provides this interpreter that reads the specified LIT file and produces the expected screen display. Note that this only works for LITs generated by AlphaPAINT 2.0.