## **- A SHELL REFERENCE** A-Shell Documentation Series Copyright 2026 Jack McGregor. All rights reserved. This edition was produced on 30 June 2026. A-Shell Reference Page 2 ## **- ABOUT A SHELL** A-Shell is a general purpose development and operating environment that provides a common framework for Windows and Linux. A user running A-Shell under Windows, in other words, would see and interact with the system in exactly the same way as she would if running A-Shell under Linux. A-Shell was introduced in 1990 as a virtualization of the Alpha Micro Operating System (AMOS), offering business applications an escape from proprietary Alpha Micro hardware to the much wider range of Unix platforms. With Windows support beginning in 1993, A-Shell became a truly portable option that freed users, dealers and programmers from underlying hardware concerns. Key aspects of A-Shell include: - Provides a shell—or command prompt—with its own virtual disk directory structure, a rich set of shell commands, - command line editing and recall, a scripting capability, an editor, and a robust programming language called A-Shell Basic ("ASB"). - Includes an extensive toolbox containing hundreds of standard library routines to speed and simplify application - development. It also provides a generic C-compatible interface for calling Windows (DLL) or Linux (so) dynamic libraries. - Supports both plain text and graphical user interfaces, including GUI in the Unix environment without the overhead - normally required. - Operates in multiple modes: client-only (standalone PC or peer-to-peer network), server-only (web services, back-ends), - and client-server (smart terminal connections over SSH). - Scales smoothly from single PCs to systems of 1000 or more users. It manages not just the independent operation of each - user, but also is focused on supporting a group of users working together: file locking and sharing, system monitoring, inter-job messaging, etc. • Interfaces well with most web and computer industry standards including SQL, ODBC, PDF, XLS/XLSX, XML, JSON, SMTP, FTP/SFTP, SSL/TLS, TIF/JPG/PNG, HTTP, OAUTH2, RSA and other cryptography standards. In the 30-plus years since its debut, A-Shell has been continuously developed and maintained, focusing on the needs of its community of application developers while also keeping pace with changes to modern computing environments. This documentation is regularly updated as new features are added and processes are improved. It always refers to the latest version of A-Shell. A-Shell Reference Page 3 ## **Subtopics** - Terminology - File System Organization - System Tables - Shell (Command Prompt) - General Questions and Topics - Compatibility A-Shell Reference Page 4 ## **TERMINOLOGY** Although A-Shell operates in the Linux and Windows environments, it borrows a number of architectural concepts along with associated acronyms and terminology from earlier operating systems, most recently AMOS but also its predecessors in the minicomputer world, particularly DEC RSTS, as well as other modern programming languages that the reader may or may not be familiar with. Several of the terms are defined here and subsequently referenced throughout this document without further elaboration. Please take a quick look down this page and read up on any terms with which you are not familiar. A few terms native to A-Shell are included at the bottom. ## **AMIGOS** An AMOS component supporting certain extended terminal functions, particularly the ability to save/restore rectangular areas. A- Shell supports the main features via TAB(-1,148) and TAB(-1,149) (see Tab Functions), as well as TRACKER (see topic on this page). ## **AMOS** An acronym for the Alpha Micro Operating System. AMOS was a microcomputer-based multi-user system running on the Alpha Micro family of computers. The AM computers were originally built around the Western Digital WD16 and later the Motorola 68K family of processors. The Alpha Micro was introduced in the late 1970s, with a heyday in the 80s and early 90s. It was revolutionary for its time, offering minicomputer-like capabilities at microcomputer prices, consequently attracting the attention of business application developers who thrived for a decade or so. Most of these independent developers were squeezed out of the market by Windows and UNIX, as networking improvements started to make Linux viable for multi-user applications and improving processor performance began to make the Windows-based business machines cost-competitive. A-Shell was originally conceived as a bridge for those developers wanting/needing to migrate their applications from AMOS to the more popular operating systems. ## **ASB** - An acronym for A Shell Basic, A-Shell's application development language. ## **ASB Subroutine** A-Shell Reference Page 5 A subroutine written in ASB (A-Shell BASIC) which exists as a discrete file, is modify-able by the A-Shell programmer, and has the filespec extension ".sbx." This is in contrast to the _embedded_ subroutines, which do not exist as files and cannot be changed. ## **ATE** An acronym for A-Shell Terminal Emulator, the standard client used for connecting to A-Shell servers via telnet or ssh. In addition to the typical capabilities common to terminals and terminal emulators, ATE also supports an extensive set of advanced client/server capabilities including support for building a Windows-based GUI, remote execution, file transfer, etc. See the separate ATE Reference for more information. ## **AUI** An acronym for the A-Shell User Interface, a framework allowing applications to build GUI applications dynamically. Two unique aspects of AUI are that it allows for the possibility of integrating GUI elements into to existing plain text applications (incrementally, without requiring an all-or-nothing rewrite), and it supports client-side GUI over telnet/ssh connections, even when the server is Linux. See the AUI subroutine for more details. ## **CGI** Acronym for Common Gateway Interface (not to be confused with computer-generated imagery), a web standard for - communicating between browsers and back-end programs via a web server. See A Shell as a CGI Engine and CGIUTL. ## **Device** Aside from the more general meaning of a thing designed or adapted for a purpose, or in the computer context, a storage device like a disk drive, within the A-Shell context it refers to the first part of the DevPPN file system organization, which has the format followed by a colon. The part must be three or four alphabetic characters (not case sensitive), the one to three digits, with the total length between 4 and 6 characters plus the trailing colon, e.g. DSK0:, SDA123:, BACK99:, etc. Historically the was intended as a reference to a physical storage device, while the was typically a partition within that device although in the Windows and UNIX environments, each A-Shell Device maps to an arbitrary path by means of DEVICE directives in the system configuration file. ## **DevPPN** Hybrid abbreviation/acronym (Device Project Program{mer} Number}; a framework for organizing disk storage into Devices and PPNs. See the DevPPN topic in File System Organization for more details. A-Shell Reference Page 6 ## **Embedded Subroutine** A subroutine which is built-in component of A-Shell, cannot be changed, and does not exist as a file. This is in contrast to _ASB_ subroutines, which are written in ASB, exist as files, and can be changed. ## **GDI** Acronym for Graphic Device Interface, a Windows component used by A-Shell to support graphic printing capabilities. See GDI Printing. ## **INFLD** Pronounced "infield." The name of A-Shell's internal field-level keyboard input mechanism underlying all other keyboard input mechanisms, including the command prompt, ASB INPUT statements, Xcall input routines such as INPUT, SBXINP, and INMEMO, and the AUI edit control. See XCALL INFLD for a complete reference to its capabilities. ## **InSight** An AMOS component supporting certain text-based mouse interactions. A-Shell supports some of those ancient methods among others; see Mouse Interaction. ## **ISAM** Acronym for Indexed Sequential Access Method, a file structure supporting both direct and sequential access. Each ISAM file unit is actually made up of a data (.DAT) file and one or more index (.IDX) files. A-Shell actually supports two ISAM frameworks: the - traditional one and a more advanced version called ISAM A. See ISMBLD, ISMDMP and ISAM Files for more details. ## **- ISAM A** - Newer / alternative variation of ISAM. See ISAM A for general information, including a comparison to ISAM. ## **JOB** An instance of A-Shell, equivalent to a pid in the Windows or UNIX environments. Each JOB has a unique Job Name consisting of six upper case alphabetic characters, either specified by the -j command line switch or auto-generated. In the latter case, the format is TSKAAA thru TSKZZZ for interactive instances (with real terminals) or TASAAA thru TASZZZ for background tasks. Each JOB also has a corresponding Terminal (aka TRMDEF) with the same name, and a Job Number indicating its position in the A-Shell Reference Page 7 Job Table, ranging from one thru the maximum number of JOBs recently in use. The names and numbers are reused as instances are released. Use JOBALC to display your own JOB name, and _Job Table_ on this page for related information. See also Job Table. ## **JOB Table, aka JOBTBL** Table keeping track of JOB activity maintained in a file jobtbl.sys whose size is determined by the license in conjunction with the MAXJOBS directive in the system configuration file. Supports administrative commands such as SYSTAT, JSTAT, SEND, KILL, FORCE, etc. See also Job Table. ## **LDF** An acronym for Language Definition File, A-Shell's version of the various language/locale settings supported by various operating systems. LDF files are stored in DSK0:[1,6] as _langabbr_ .LDF with a particular one being activated via the LANGUAGE directive in the system configuration file, or the SET command. Details may be queried via XCALL GTLANG. ## **LOKSER** The historic name for a particular model of file locking built based on the underlying operating system's file locking capabilities and exposed mainly through variations of ASB file I/O statements such as OPEN, READ, and WRITE. Must be enabled in the LOKSER directive in the system configuration file or with the SET command. Applications that do their own QFLOCK-based locking may prefer to leave LOKSER disabled to avoid having to navigate the various LOKSER rules for file access. ## **MAP** Noun / verb / adjective reference to variable declaration (see MAP STATEMENTS) in general or possibly to a type of collection (i.e. ordered map). ## **MIAME** Historical acronym for Machine Independent Alpha Micro Environment (pronounced like the city in Florida). Although outdated, it continues to be used as the default base directory for A-Shell installations. See Configuration. ## **MIAMEX** A-Shell Reference Page 8 The name of a particular subroutine with over 200 sub-functions (i.e. "MIAMEX functions") for accessing A-Shell and host OS internals, system-level features and operations, and operations toO small or obscure to be worth separate subroutine implementations. ## **MULTI** An AMOS software package supporting the ability to switch between multiple jobs within a single terminal/window/connection. Roughly equivalent to PolyShell in the A-Shell environment. ## **P2P** Acronym for Peer-To-Peer, and network confirmation made up of workstations with file sharing capability. Typical environment for small Windows-based A-Shell installations (where any of the workstations can act as the "server" simply by hosting the file directories). ## Server/Client A seemingly backwards variation of the more common "client/server" (architecture) which more aptly describes ATE-based systems. In the traditional client/server scenario (e.g. web browser application), the client is driving the action, running the primary application logic and making requests to the server for information. By contrast, in the ATE framework, the application runs on the server, which drives the action but makes requests to the ATE client to extend the capabilities of the server (e.g. displaying a GUI front-end, executing SBX routines and client-side Windows commands, retrieving information from the client environment, etc.) ## **PolyTRACK** The historic name of a subsystem for managing multiple jobs from a single terminal, built around TRACKER by MicroSabio as a competitor to MULTI under AMOS. The equivalent product option under A-Shell was renamed PolyShell. ## **PPN** An acronym for Project, Program{mer} Number; a two-level directory organization scheme consisting of two numbers from 0- 999, typically formatted as [p,pn], e.g. [7,6] or [257,0]. The first number is known as the "Project", typically used to group related files or programs, such as a module like AR or GL within a larger application. The second number, more cryptically known as the "Program{mer} Number" is in practice used for sub-grouping files by type or ownership or other attribution within a project. For example, a project 50, corresponding to, say, an order entry module, might be sub-divided into the the following: A-Shell Reference Page 9 - `[50,0] - RUN programs; the ,0 directory is automatically part of the project search path` ``` [50,100] - Common source include files ``` - `[50,101] - Projection source files` - `[50,102] - Beta source files` ``` [50,121] - Hector's development/test directory ``` ``` [50,122] - Elvira's development/test directory ``` - `[50,400] - Common data files` ``` [50,401] - Tuscaloosa division data files ``` ``` [50,402] - Topolobompo division data files ``` ``` [50,403] - Transylvania division data files ``` ``` etc. ``` In the Windows and UNIX environments, PPNs are mapped to native directories with 6 digit names by expanding both parts into three digits, i.e. [1,4] maps to 001004, [50,122] maps to 050122, etc. Note that Project numbers 1 thru 9 are traditionally reserved for system use. See DevPPN for more details, the PPN system command to display existing PPNs, and the SYSACT system command for creating new PPNs. ## **QFLOCK** A reference to the system file QFLOCK.SYS used for maintaining a variety of application-level inter-Job locks. Alternative or XS XS adjunct to the OS-level file locking system LOKSER. See XLOCK and FLOCK . ## **SBR** Originally meaning "subroutine," the term now refers only to embedded subroutines. ## **SBX** A-Shell Reference Page 10 File extension identifying ASB subroutines. ## **TCRT** An acronym (for Tab Cathode Ray Tube?) referring to a set of extended terminal commands invoked via TAB(-n,f) commands. The negative first parameter separates these commands from the standard TAB(row,col) commands for cursor positioning and identifies the group of commands such as display functions, color, layout, ATE functions, etc. See Terminal Functions for more details. ## **Terminal, aka TRMDEF** The name for the terminal device—serial or network, real or virtual—attached to a JOB. Given that each JOB is attached to a Terminal of the same name, the distinction between them is mostly lost and can be ignored in modern networked environments. The concept of attaching terminals to JOBs was more salient in the days where terminal devices were hard wired to serial ports. See TRMDEFSP for additional details. ## **TRACKER** The historic name of a subsystem for tracking the text-based contents of the screen, allowing text-based applications to save and restore areas of the screen in order to implement pop-up windows or toggling between logical screen displays, typically using the subroutines MSBOXXXS or SWPSBRXS and/or TAB(-1,201), TAB(-1,202) and TAB(-1,203). The capability is built-in to A- Shell. Also see WSET.LIT. ## **XCALL** An abbreviation for eXternal CALL, used as verb, noun or adjective, whether referring to the action, the target subroutine/module, or the variation of type of ASB control statement. The XCALL mechanism allows ASB to dynamically load and invoke subroutines/procedures/functions within external modules written in other languages, complete with parameter passing by value or reference, whether to access capabilities otherwise not available (e.g. pointers) or not efficient (e.g. low level raw memory access), or to tap into existing shareable libraries (DLLs or Linux .so files; see DYNLIBXS) to avoid reinventing the wheel. Historically XCALL routines were written in assembler; in the A-Shell world they are typically written in C, or even ASB itself, where the primary motivation would be modularity. A-Shell is distributed with a couple hundred standard XCALLs, to which most application developers add their own. See Subroutines for more details. A-Shell Reference Page 11 ## **FILE SYSTEM ORGANIZATION** A-Shell has its own system for the organization of files. The system is of course a tree structure like all modern operating systems, but it differs significantly from the native file systems of Linux and Windows. For details on how it is mapped onto the Windows and Linux file systems, and more details, see the following sections. ## **Subtopics** - DevPPN Directory Structure - Filespecs - Ersatz Devices A-Shell Reference Page 12 ## **DEVPPN DIRECTORY STRUCTURE** The A-Shell directory structure is made up of the following components: - A "device" consisting of a three or four alphabetic character device name and a one to three digit unit number, such as - "DSK0" or “DOC12”. Devices are normally referred to with a trailing colon, i.e. DSK0: or DOC12: (identifying it as a device and separating it from the filename). - A PPN consisting of a pair of one to three digit numbers, such as 1,4 or 923,255. PPNs are often enclosed in brackets, i.e. - [1,4] or [923,255]. This is optional when the context is clear, such as `DSK0:1,4` but mandatory when combined with a filename, e.g. `DIR.LIT[1,4]` . Device names and unit numbers correspond historically to physical devices and partitions within each device. For example, a system might have two different types of physical disks, named DSK and DKX, each of which was divided into three partitions, e.g. DSK0, DSK1, DSK2 and DKX0, DKX1, and DKX2. The device name may be either three or four alphabetic characters long, while the unit number may be one to three digits, with an overall limit of six characters. So DSK123 and BACK27 are legal names, while DZ1234 and WACKY1 are not. PPN originally referred to “Project” and “Programmer Number”, but evolved to simply represent a two level grouping of individual directories. For the most part these PPN numbers are arbitrary, except that the project values one through seven are reserved for system files, and the [x,0] directory within each project has special meaning in the Command Search Path. The overall scheme is known as "DevPPN." When A-Shell is installed in Windows or Unix, its DevPPN directory scheme is mapped on top of the native multi-level path system by associating each device with an arbitrary path—think of it like a logical mount point—via DEVICE statements in the miame.ini file. Beneath the device directory, each PPN corresponds to a six-digit subdirectory with each of the two parts expanded to three digits. So [1,4] becomes 001004 and [123,45] becomes 123045. For example, if DSK0: is explicitly mapped to C:\VM\MIAME\DSK0\ then DSK0:[1,4] would implicitly map to C: \VM\MIAME\DSK0\001004\. Or in the Unix case, if DOC13: is explicitly mapped to /vm/library/documents/ then DOC13:[15,345] would implicitly map to /vm/library/documents/015345/. Aside from these A-Shell devices which are mapped to native directories, A-Shell also supports ersatz devices which map to A- Shell devices or PPNs. A-Shell Reference Page 13 ## **FILESPECS** A-Shell typically recognizes two types of filespecs: it’s own DevPPN filespecs and those native to the host operating system. DevPPN filespecs have the form: ``` {device:}filename{.ext}{[p,pn]} ``` DevPPN filenames consist of 1-72 RAD50 characters; allowable characters are A-Z, 0-9, dollar sign ( $ ), hyphen ( - ) and underscore ( _ ). Spaces are not allowed. DevPPN filenames are not case sensitive, but in the Unix environment are mapped to lower case native filespecs. Extensions can be from 0 to 8 RAD50 characters. Multiple extensions are not allowed. Optionally, the order of the parts can be changed to put the [p,pn] in front of the filename, e.g. DSK3:[100,200]ABC.DAT Within ASB programs, file I/O statements recognize and accept both DevPPN and native filespecs. At the command prompt, filespecs used in System Commands are expected to be in DevPPN format. But many commands, including all of the wildcard commands, will allow you to specify a native filespec by enclosing it in quotes. For example: ``` .COPY HOSTS.TXT="/etc/hosts" /NOD ``` ``` .TYPE "/etc/hosts" ``` ``` .SIZE "c:\vm\miame\bin\ashw32.exe" ``` ``` .DIR HASH.DIR="/vm/miame/bin/ashell" /H ``` When using quoted native filespecs, you cannot use wildcards. ## **Filespec recommendations** A-Shell Reference Page 14 • A-Shell does not recognize spaces in file name, so it is strongly recommended that you avoid them when naming files in other (i.e., host) operating systems. • The same for apostrophes and quotes. They might work in Windows but will be a nightmare in Linux and of course will not work in A-Shell. - Obviously slashes are also off limits. Note that that Windows treats / the same as \, but Linux does not. A-Shell Reference Page 15 ## **ERSATZ DEVICES** In addition to the devices defined by DEVICE statements in the system configuration file, the DevPPN system also supports ersatz devices which act as aliases for DevPPN devices or device:[p,pn] directories. See ERSATZSP and Ersatz Definition Files for additional details on defining and using ersatz devices. While the main benefit of the ersatz device system is to allow users to assign meaningful names to their own device:[p,pn] combinations, it is also used with A-Shell itself to assign short aliases for the following system directories: |**Device:**
**[P,PN]**|**ERSATZ**|**System Account Purpose**| |---|---|---| |DSK0:[1,2]|OPR:|System operator account. This account has special privileges and is usually password protected. Logging into this
account might be considered analogous to logging in as Administrator under Windows or as the superuser under
Unix. Certain commands, for example, will only run, or have greater powers, when executed from this account.| |DSK0:[1,4]|SYS:|"The" system account. This is the default location for all of the system commands (those with LIT extensions) plus
certain configuration files, such as the language files andersatz.ini.| |DSK0:[1,6]|DVR:|Terminal driver and language definition file account. Under A-Shell, terminal drivers are embedded in the
executable, so the only files you will normally have in this account of the language definition files (e.g.
englsh.ldf).| |DSK0:[1,7]|ASHCFG:|A-Shell configuration files, in particular, printer init (PQI) files.| |DSK0:[2,2]|CMD:|Command files (i.e. those with CMD or DO extensions). These are the A-Shell equivalents of BAT files under DOS
or shell scripts under Unix.| |DSK0:[7,0]|LIB:|Library files. Function key translation tables, color configuration files,ini.vue(VUE initialization file).| |DSK0:[7,1]|HLP:|Help files. A-Shell tends to embed help which is associated with system commands in the commands themselves,
or use external PDF (Acrobat) or CHM (Windows Compiled Help) files, leaving this directory only for the help files
that are displayed from within the VUE command mode with the HELP command.| |DSK0:[7,6]|BAS:|RUN files placed in this directory can be run from any other location.| |DSK0:[7,376]||A-Shell sample program directory| A-Shell Reference Page 16 ## **SYSTEM TABLES** In order to keep track of what is going on with and between JOBs, A-Shell dynamically creates and maintains two system tables. See the following topics for information on JOBTBL.SYS and QFLOCK.SYS. A-Shell Reference Page 17 ## **JOB TABLE** _Added November 2024_ A-Shell uses the term _job_ to refer to an individual instance or session, i.e a task or process in the lexicon of Windows and UNIX. Although each A-Shell is also a native host operating system task/process, and thus has a process id (pid), in the A-Shell context they are identified by job names and job numbers. Job names are one-to-six upper case characters, either specified by command line switch, or assigned automatically, in which case they are of the form TSKAAA, TSKAAB, ... or TASAAA, TASAAB, ... for foreground and background jobs, respectively. Job numbers range from one to the maximum concurrent number of jobs, with the numbers reused as jobs exit. - A-Shell jobs are tracked in a shared file JOBTBL.SYS, normally stored in the same directory as the A Shell Configuration File but specifically as specified by the QUEUESP, that is dynamically created when the first job is launched, and removed when the last job exits. For more information relating to the Job Table, see the following topics: ## **System Parameters** - MAXINST: maximum number of jobs allowed to originate from a single workstations - MAXJOBS: maximum number of jobs to allow total - QUEUE: location for both QFLOCK.SYS and JOBTBL.SYS ## **System Commands** - SYSTAT: detailed job table display/list - ASTAT: dynamic job table display - JSTAT: dynamic display of a single job - SEND: send message to a job - KILL: kill a job ## **Subroutines** A-Shell Reference Page 18 - MX_READJCB: read job table records - MX_WRITEJCB: write job table records - MX_KILL: send signals to jobs (analogous to UNIX kill command) A-Shell Reference Page 19 ## **QFLOCK** _Added November 2024_ The QFLOCK.SYS file, created dynamically along with its sibling JOBTBL.SYS, keeps track of various kinds of inter-job lock queues. While A-Shell applications are free to implement their own locking schemes to manage race conditions, typically using system file locks either directly or as proxies, QFLOCK.SYS provides a convenient mechanism for managing multi-process access to files or any other abstract resource. Note that when a JOB exits, any entries it may have left in the QFLOCK.SYS are automatically cleared. See the following topics for more details: ## **System Parameters** - QUEUE: specifies location for both QFLOCK.SYS and JOBTBL.SYS - SBR=MXLOCK: determines whether a JOB may lock itself out - SBR=AXLOCK: affects handling of wildcard lock conflicts ## **System Commands** - QUTL: view/manage QFLOCK.SYS entries ## **Subroutines** - MX_GETQUEUE: read a queue block - MX_QLOCK: lock QFLOCK.SYS - MX_QUNLOK: unlock QFLOCK.SYS - MX_QRBLD: rebuild QFLOCK.SYS - XLOCK: general purpose lock operations - FLOCK: file locking based on QFLOCK.SYS A-Shell Reference Page 20 ## **SHELL (COMMAND PROMPT)** The A-Shell _shell_ layer, aka the "command prompt" or "dot prompt," functions like the familiar Windows and UNIX shells: it provides an environment with its own set of commands, a scripting capability, and more importantly a launch pad for executing application programs. The most unusual aspects of the A-Shell shell are: • It supports its own virtual DevPPN-style file system structure and syntax that nevertheless maps directly on to the native (Windows or UNIX) file system structure. • It is transparent, or semi-permeable, in the sense that it offers the ability to see through it to the underlying OS or shell environment, including querying the native environment, scanning native directories, and even executing native programs. You have the choice of operating completely within the shell—for maximum portability between operating systems—or of incorporating features of the native environment—for maximum power and flexibility—without having to recreate them. ## **Command Line Editing** In the case of a real terminal connection, when there are no commands or characters queued up, such as in a Command File or via redirection, the shell displays its prompt (typically a single dot; see SET.LIT to change it) and waits for the user to enter a command. In addition to ordinary text, the following special commands are available: |**Command **|**Single Key**|**Action**| |---|---|---| |Ctrl+R|Page Up|Cycle backwards through the command line history, one at a time| |Ctrl+T|Page Down|Cycle forward through the command line history| |Ctrl+U||Move cursor to beginning of line| |Ctrl+H|Left Arrow|Move cursor left, non destructive| A-Shell Reference Page 21 |**Command **|**Single Key**|**Action**| |---|---|---| |Ctrl+L|Right Arrow|Move cursor right, non destructive| |Ctrl+Q|Insert|Toggle insert mode| |Ctrl+Z||Erase line| |Ctrl+Y||Erase from cursor to end of line| |Ctrl+A||Move cursor to start of prior word| |Ctrl+W||Move cursor to start of next word| |Ctrl+N||Move cursor to end of line| |Ctrl+F||Insert a space| |Ctrl+D|Delete|Delete character under cursor| ||Backspace|Move cursor left, destructive| A-Shell Reference Page 22 Note that except for Ctrl+R and Ctrl+T, these commands are identical to those supported by the INFLD field editor (see Keyboard Commands for the complete set) and largely shared with those of the VUE file editor. ## **See Also** - System (or "Shell") Commands - Command Files (A-Shell scripting) A-Shell Reference Page 23 ## **GENERAL QUESTIONS AND TOPICS** This section provides information that may be of interest to people updating from older versions of A-Shell, or selecting a platform on which to run A-Shell, or moving A-Shell from one platform to another. A brief note on the confusing language of "update" and "upgrade" and "conversion." In this documentation, we use the terms as follows: - **Update** : this is a move from an older version of A-Shell to a newer version. It does NOT involve a software license, it does - NOT provide additional options or features, it (generally) does NOT cost anything and you will probably not even notice any difference between the old and new versions. The purpose of an update is to keep your software "reasonably current" in relation to what the developers of A-Shell are working on and distributing. A-Shell is constantly being improved, in large ways and small, with bug fixes and new features, and it is generally a good idea to keep your copy up to date. There are exceptions and special considerations, of course. - **Upgrade** : this is when you add features or capabilities to A-Shell, or when you increase the number of authorized users. - Such changes generally require issuance of a new software license, and make your software "bigger" than it was before, in the sense that you have expanded its capabilities by either numbers or features. For example: A-Shell has an add-on module called PDFX that allows you to easily create PDF files from reports. Adding PDFX to your system is an upgrade and requires a new license; see Updating the License if that is what you need to do. - **Conversion** : this is a platform change from Windows to Unix or vice versa, or from any A-Shell platform to any other. - Also note that the information in this section frequently parallels and/or overlaps with the A Shell Installation documentation, which see for related details. ## **Subtopics** - Updating A-Shell - Conversion: Linux to Windows 1 - Conversion: Linux to Windows 2 - Questions on ATE, ZTERM, SSH, Printing A-Shell Reference Page 24 - Conversion: AM-PC File Transfers - Performance in Large Systems A-Shell Reference Page 25 ## **- UPDATING A SHELL** A-Shell is an evolving software product, meaning that it is always changing. The developers of A-Shell work on it constantly, and new versions are churned out several times a month. In order to bring some degree of order to what otherwise might be a fairly chaotic and never-ending confusion about updates, the A-Shell versions are segregated into two major categories: • **Stable** : The stable version of A-Shell has not changed since its formal release date, which is usually months or years in the past. The software is being used by many firms, is recommended by MicroSabio, and can be counted on to not change. It is stable, dependable, reliable, risk-free. The only exception to the not-changing rule is bug fixes, which are usually minor and obscure. • **Development** : The development version changes weekly or even daily, and incorporates an endless stream of improvements and new features. These changes rarely have any effect on existing programs, but it is at least possible that they might. Therefore, the development version is intended primarily for software developers who are interested in the latest features and improvements in A-Shell. For most users of A-Shell and in most circumstances, the stable version is preferred. Although some organizations want to always have the latest and greatest version of the program, most prefer the stable version because it eliminates most of the risk of something going wrong. That risk is very low even with the development version, but it is even less with the stable version. - To determine what numerical versions equate to the current stable and development systems, please see the A Shell downloads page here. ## **Version Numbering** A-Shell's version number consists of three parts, separated by periods. For example: 6.5.1688. - First digit: in over twenty years of development (as of 2020), A-Shell has had six "major major" version number changes. The - current one is "6," and that will likely remain true for quite a while. - Second digit: this indicates a "major" release of A-Shell. Also, there is another important element to this digit: EVEN numbered versions are stable/finished, ODD numbered versions were those under development. So A-Shell 4.7, 5.1, and 6.3, for example, were all development releases, whereas 4.6, 5.0, 6.2, etc., were all stable releases. A-Shell Reference Page 26 - Third digit: this indicates the "build" number of A-Shell, and shows at a glance how many times A-Shell has been recompiled / - rebuilt and released to the world since its origin. To determine the version number of your currently-running version of A-Shell, enter ABOUT, SYSTAT or LICENS at the A-Shell prompt. ## **Updating** A-Shell is used in many different ways by many different kinds of organizations. Some have in-house programmers and technicians that keep A-Shell up to date, others rely on consultants or advisors, some have relationships with a computer dealer or reseller or other firm. You should make sure that the responsible person or firm is the one updating A-Shell. ## **Subtopics** - Which Version Should I Be Using? - Updating A-Shell Windows and ATE - Updating UNIX - Updating SOSLIB and EXLIB A-Shell Reference Page 27 ## **WHICH VERSION SHOULD I BE USING?** Unfortunately, there is no one-size-fits-all answer to this question. Possible—and only possible—answers are: - Do you get your application software plus A-Shell from a dealer / reseller / consultant? Ask them about which version is right - for you. - Do you get A-Shell directly from MicroSabio? You likely should have the latest stable version. - Are you a "bleeding edge" user or developer who always wants the latest version? Get the very latest available version. - The best source of information about versions—latest, stable, historical—is the A Shell downloads page on the MicroSabio website that deals with that subject. Remember that A-Shell is being continually updated by the developers. In other words, the target is always moving and today's "latest stable" version might be—will certainly be, at some point—tomorrow's historical version. If you are the person in change of keeping your copy of A-Shell or ATE up to date, then you should probably be updating approximately once a year. Also note that it is up to you, the person installing the update, to know what you are doing! You need to determine if the update is required or recommended, and what problems you might encounter during the process. The normal answers are yes (recommended) and none (expected problems), but you are nonetheless responsible for the process. Caution is advised. A-Shell Reference Page 28 ## **- UPDATING A SHELL WINDOWS AND ATE** For A-Shell running under Windows, and for ATE, A-Shell has a very nice, clean, simple update mechanism. Here is pretty much everything you need to know: In other words, go to the "Help" menu in A-Shell/Windows or ATE, and select "Check for Updates." The system will respond with something like this: All you need to do is decide if you want to perform the suggested update. If yes, then A-Shell will download a new copy of itself and run the installation program. That is really all there is to it, unless something goes wrong or you have special circumstances or needs. Be aware that A-Shell cannot update itself while it is running, so a dialog box will pop up and tell you to shut down A-Shell; simply exit A-Shell, and click on the "Retry" button. If something DOES go wrong or you DO have special circumstances or needs, then please follow the directions for Unix updates but substitute "Windows" or "ATE" for "Unix version." Note that the update process described here is actually the small tip of a very large iceberg of update controls and procedures. If you are a system administrator or other technical person who is responsible for updating large and/or many systems, please see - the "Automatic Updating" discussed in the A Shell ATE documentation. A-Shell Reference Page 29 ## **UPDATING UNIX** _Reviewed July 2020_ There is no "automatic" method for updating to Unix, but the manual update procedure is simple. This method also works for A- Shell/Windows, ATE, and all other supported versions of A-Shell. - Determine which version you are using now, and which version you wish to update to. Make sure you know what you're doing - here! - Go to the MicroSabio distribution folder on our webserver, and view the directory contents. It should look something like this: - "64rel" means "Version 6.4 standard release," etc. You will normally want to select the latest (highest numbered) release that - is followed by "rel." Numbers followed by "dev" indicate an under-development version, which you are welcome to download but which has not yet been declared "stable." - Click on the name of the applicable folder, such as "64rel" and see another folder display like this: - Note the file install-notes-linux.txt which will apply to all Unix installations. - The "el" numbers (EL5, EL7, etc.) refer to "Red Hat Enterprise Linux version number." We primarily focus on the Red Hat - Enterprise and CentOS distributions, which share a common kernel and core set of libraries; contact us to discuss the possibility of using other distributions. The A-Shell releases for the various -el# distributions are generally—but not always—upward compatible, and almost never downward compatible; e.g. the A-Shell -el6 release will run fine on Red Hat or CentOS -el7, but probably not -el8, and definitely not -el4. The version number applies to Linux from any of the major distributions such as Red Hat and CentOS. The A-Shell versions are generally upward compatible (the EL5 version will run fine on EL6 or EL7 systems) and are generally NOT downward compatible (the EL7 version of A-Shell will not run on an EL4 system). - Again, click on the name of the applicable folder, such as "bin-linux-el6" and see another folder display like this: - To get the latest version, click—sometimes twice—on the "Last modified" column header that the files will be sorted by date. - Unless you have reason for not doing so, you should also download the latest available version. A-Shell Reference Page 30 - To download the file(s) you need, simply click on them. Go back up the directory tree to read the installation instructions if - needed. - "EFS" in the file/folder name refers to A-Shell Encrypted File System. You generally do NOT want to use this version, unless of - course you do. - See Unix Installation for more information about the "bin" and "tz" file types and how to deal with them. While you can repeat the Unix Installation steps for an update, since the installer will avoid updating most configuration files and files that you've added, most updates affect only the main ashell executable and consequently are released as compressed tar files (with names ending in **-upd.tz** ) containing only the updated executable. You can use any of these to replace the current A- Shell executable with the following procedure: Start by downloading the file into the bin directory (e.g. /vm/miame/bin). Then rename the existing ashell, typically by appending the current version edit number, which allows for a new copy to be installed without affecting the existing users running A-Shell. Note that after updating in this manner, any users currently executing ashell will continue to run the old version until they exist and launch a new session. This takes advantage of the fact (and assumes) that the new version is compatible with the old version in that way. This is virtually always true when updating within the same major.minor version, especially the stable release. You can monitor which users are still running the old version and which are running the new version via the `SYSTAT/N/VER` command. A-Shell Reference Page 31 ## **UPDATING SOSLIB AND EXLIB** The SOSLIB and EXLIB are libraries of files that will be of interest only to A-Shell developers, programmers and resellers. These libraries are updated by copying new versions over the top of previous versions. Click on the links at the beginning of this paragraph for information on where to find the current copies of the libraries. A-Shell Reference Page 32 ## **CONVERSION: LINUX TO WINDOWS 1** From a Microsabio bulletin board discussion "Suggested Platform - OS for A-shell " of November 2012. ## **Question** My client is running A=Shell 4.8 on Linux, and is considering moving to Windows. They have approximately ten users on the system, and we originally went with Linux because it was a better choice than Windows for that many users. However, that was more than ten years ago. Would Windows now be reasonable for ten users? And if we convert to Windows, how much recompiling of their .bas files will be required? ## **Reply** There is a range of possibilities for a Windows environment (P2P workgroup, domain server, ATS, Terminal Server), but all of them would work fine for 10 users if properly configured. Most ASB applications are disk-bound, rather than CPU bound, and rely on shared access to files with some kind of locking scheme. So in choosing a configuration, you should give more consideration to that aspect of performance. The peer-to-peer (P2P) workgroup is the simplest and probably the cheapest Windows configuration, but has the lowest file I/O performance and the greatest exposure to network problems, particularly if different versions of Windows are in the mix. / A domain server is a step up in terms of overall network reliability, but not a big step in file i/o performance. The ATSD (A-Shell Telnet Server) and Windows Terminal Server (along with its competitors - Citrix, etc.) put all the CPU and file activity load on the server (as in Linux), but end up giving you much better performance by eliminating all the network file sharing overhead. Given the same hardware, Linux will still be faster, but the point is probably moot given the performance of modern hardware. If your server is old, tired, or short on memory, ATSD might be a better choice since it has relatively tiny overhead (less than 10 MB per connection), and is probably cheaper. But any decent modern server with 4GB+ of RAM and a quad-core CPU can easily handle ten Terminal Services connections, and does give more flexibility in client devices. Note that ATSD, unlike Windows Terminal Server and its ilk, does not strictly require a "server" version of Windows; an ordinary "professional" version will work just as well, at least from A-Shell's perspective, for a system of modest size. This can further A-Shell Reference Page 33 reduce your costs for licensing and the expertise required, if you don't have any other reason to use the features of a true Windows "server". At some point, perhaps above 20 users, the advantages of the "server" editions in terms of resource management become more substantial or even necessary. As for the recompiling, you may not need any, either for the platform change or the A-Shell update. Regarding the platform, the only issue would be if your application had extensions that specifically related to the Unix environment (e.g., referenced native filespecs, launched native LINUX commands via HOSTEX, etc.) As for the update, the old RUN format is still supported by both the runtime interpreter and the compiler. It is always possible though that in the intervening updates between 4.8 and the current 6.0, some fix, change or enhancement might inadvertently affect your app. The main compatibility issue that I know of is the switch from octal to decimal for the [p,pn] system in 5.0. This was done to expand the range of PPNs from 255x255 to 999x999, which was important to some developers with large sites subdivided by PPNs into companies, departments, profit centers, etc. The change does not affect RUN programs per se, unless you used a subroutine to manipulate PPNs that stored each as a single binary byte. Obviously, to handle 999, you need either two bytes or a three-character string.) If unsure whether that might be an issue, you should probably _grep_ your source for SUBROUTINEs and generate a list of all the different SUBROUTINEs you use, which you could either look up in our documentation or send to us for review. Fortunately it is usually pretty easy to swap out or upgrade such calls, assuming it's even an issue at all. A-Shell Reference Page 34 ## **CONVERSION: LINUX TO WINDOWS 2** " " From the Microsabio bulletin board discussion Is it feasible to switch from Linux to Windows Server? of December 2012. ## **Question** Does it make sense performance-wise to switch from Red Hat Linux to Windows Server for an A-Shell system which typically has 70 users running programs on it at the same time? ## **Reply** Given the same hardware, Linux handily outperforms Windows, particularly in larger environments like yours. That said, there are a number of possibly mitigating or extenuating considerations: 1. Windows peer-to-peer should be ruled out of hand for this size system. So we'll assume some kind of server-based model (Windows Terminal Server, Citrix, GoGlobal, ATSD, etc.) for the remainder of the discussion. Note that these server-based models divide into two completely different categories, what I'll call RDP-style (Windows Terminal Server, Citrix, GoGlobal, etc.) and Telnet-style (ATSD). For the RDP-style (they don't all used RDP specifically, but the concept is the same), the logical screen (within the server) is replicated to the client screen by some pixel-based protocol. As opposed to the Telnet-style case where the server sends characters (bytes) to the client, which is responsible for maintaining its own state and updating the display based on the logic of the character and character-based commands that arrive. The input channel is pretty much the same for the two variations. 2. For RDP-style protocols, you will need a much bigger server than you would for Linux, or for ATSD, because each connection is essentially a full-blown Windows environment on the server. It's not easy to estimate those memory requirements, but as a very rough approximation, I would take the MEMORY partition size specified in miame.ini and add about 10MB per telnet/ATSD connection, and about 50MB per RDP-class connection. That would be for plain text applications. Add another 10-20MB for GUI. 3. In the old days, you'd have to squint very carefully at the previous paragraph. Nowadays, you may just get a server with 16GB RAM and not sweat the details. 4. Likewise for CPU - in the Windows environment, all the display operations are GUI/pixel-oriented (as opposed to byte-oriented in the Linux/ssh environment - even when using ATE for a GUI front end), so it takes a lot more CPU power to update displays. So while a single core Pentium could manage your 70 Linux users, you'd want 8 cores or more for the Windows equivalent. But again, that's no big deal these days, so maybe another meaningless detail not to sweat over. A-Shell Reference Page 35 5. If you go with an RDP-style environment (as opposed to sticking with telnet), you're probably looking at substantial licensing costs. (On the other hand, maybe all those workstations already have client licenses for other reasons, in which case the additional cost may be minimal.) 6. A-Shell GUI operations in the RDP-style environment are actually simpler than in the telnet/ATE environment, because it acts more or less just like the Windows standalone environment. (The AUI layer which converts GUI calls into ATE messages, relays them to the client, and processes the responses, is bypassed. Instead, there is a more seamless screen-replication layer, which may involve more raw bits being transferred, but for many GUI operations is actually more efficient. Plus you eliminate the latency delays involved when an ATE command requires a response from the client.) 7. For plain text applications, the situation is somewhat reversed. ATSD/telnet style communications are generally much more efficient than the RDP-style remote screen replication when it comes to displaying characters. The one exception is scrolling (like in long DIR or TYPE operation) where, in the telnet case, every byte must be transferred, whereas in the RDP case, the scroll may not be as smooth, but it can effectively skip much of the updating by just resynchronizing the display at the end of the scroll. (Admittedly this is a special case, but I do get asked why scrolling displays take longer with byte-oriented telnet than with bit-oriented RDP.) Fortunately, if you already have a Windows server at the site, which it sounds like you do, you can probably experiment on it without a lot of investment. Particularly if you're leaning towards the Terminal Server approach and already have it installed on another server, just install a demo copy of A-Shell/Windows on it and make an RDP connection to it. You may be able to get a preliminary feel for the performance just by playing with VUE, DIR, and some of the programs in the EXLIB. If you're leaning towards keeping the present telnet clients, you will have to install ATSD, but that isn't very difficult either. As for version, existing Windows Server installations of A-Shell (as of July 2025) range from W2008 to W2025. Although there are plenty of differences in Windows from one version to the next, those differences don't seem to matter much to A-Shell. In fact, if you use the ATSD/TELNET configuration, you don't absolutely need a real "Server" version of Windows; the "professional" version will work. For the relatively large system of 75 users, however, the server versions may provide better environmental support in terms of resource management, security, etc. Caveat: We have a couple of Windows server sites in the vicinity of 50 users, but yours might well be the biggest ever. In contrast, we have many Linux sites with hundreds of users. A-Shell Reference Page 36 ## **QUESTIONS ON ATE, ZTERM, SSH, PRINTING** A new A-Shell client, who is converting from an older system, asks several questions: - Do we really need to use ZTERM, or is connecting to the host using any ssh client and starting A-Shell from there sufficient? I - ask this because previously the users connected to the host using an ssh tunnel and ZTERM on top of that. I want to get rid of that scheme in favor of something simpler which I think it could be done just by an ssh session. • In the same topic, the FTP configuration is something I would like to change to a SFTP connection to the host box (Linux in this case) with an user jailed to the disk directories of A-Shell. Do you think this approach would have a problem when comparing to using the TCP/IP support of AMOS? Again I am trying to prevent the tunneling and going straight to the box using the ssh stack as much as possible. - Does A-Shell printing depend on any particular terminal emulation(s)? Following are extended discussions on each of these topics. I'm glad you asked about ZTERM, because I was under the impression that the client was actually committed to it. We still sell it due to a long-time agreement with the developer, but because he stopped doing any support or development on it more than a decade ago, we decided to create our own emulator. That A-Shell-based emulator is called ATE (A-Shell Terminal Emulator), and we fully support it as well as modernize/enhance the capabilities as time goes by. One of those being proper SSH2 / SFTP support! Another is the enhanced printing capabilities, both in redirecting Linux print requests via the Windows system, as well as supporting preview, print-to-PDF, print-to-email, etc., that I may have referred to in a previous message. Perhaps the biggest enhancements are in the area of GUI support, but I gather that the client's application currently has no need for GUI. Whether they are interested in adding some GUI enhancements to the application, I have no idea, and it may not be your concern either. But if you or the client expect to be using the application for a long time into the future, those GUI capabilities become ever more important. So take note! But even apart from "GUI-fyng" the application per se, there may be areas where they might benefit from improved communication capabilities between the application running on Linux and the resources of the Windows environment. There is a reasonably coherent summary of ATE on the MicroSabio ATE page, and there is a list of extended TAB(-10,x) functions in the A- Shell reference to give some idea of the kinds of server-to-client commands that are available. Many of these overlap the ZTERM ESCAPE Sequence commands, in which case ATE also supports the same ESCAPE sequences for upward compatibility.) A-Shell Reference Page 37 Most of the A-Shell/ZTERM users have migrated to ATE, and nearly all of the new A-Shell/Linux users choose ATE. But, it is a commercial product with a cost associated; you can see the prices on our website. To avoid those costs, or due to prior preference, some sites use other emulators, ranging from commercial ones like Anzio and AlphaLAN, to free/open-source emulators like Putty. As long as the emulator supports an emulation that is compatible with A-Shell and the features used by the application, it should work. The specific emulations that A-Shell supports are AM62A, AM62C, AM65, AM75, and WYSE50. It also supports a "generic" terminal emulation that works through the Linux TERMINFO database, allowing emulations that are known to Linux, such as VT220, VT320, etc. to function, although the capabilities are generally pretty limited. (The AMOS terminal driver system was quite advanced for its time and encouraged applications to take advantage of terminal features; the scheme was theoretically terminal independent, except that they then came out with their own line of terminals which certain tweaked capabilities to coerce most users into buying the more expensive AMOS terminals.) I haven't seen your application, so I don't know what features are being used, except that I do know that it uses the protected fields, i.e. TAB(-1,13) and TAB(-1,14), which probably rules out the use of generic emulations. Other features that are common in AMOS applications but possibly dependent on the AMOS terminal emulations are insert/delete, line drawing, save/restore, and status lines. Although it may be somewhat self-serving, my general opinion is that the difference in cost between ATE and a free emulator typically isn't worth the effort to identify and work around these issues, not to mention losing access to some of the really useful features, like printing. Regarding printing, no, A-Shell does not depend on any terminal emulator for printing. Printers can be defined to Linux, similar to how they are defined to AMOS, and A-Shell can print to those printers via PRINT.LIT or XCALL SPOOL, just like it does under AMOS. A text configuration file is used to associate the logical printer name known to the application, with the system print queue name known to the Linux operating system. The ability to print back to the terminal, for redirection to real or virtual Windows print devices, is just a bonus. Regarding the SSH tunnel and SFTP, I agree that getting rid of the tunnel would make your life easier. Since ATE (and other emulators like Putty) support SSH2, there is no need to use a tunnel; just SSH directly to the server. In the case of ATE, you can launch SFTP transfers via the same SSH terminal channel/port, which also simplifies firewalls. Jailing or sandboxing the users is possible in the normal way, based on the way you configure the SFTP service on the server, but if the application is driving those transfers (using the ZTERM ESCAPE sequences), then it probably assumes that the SFTP home directory is the real home directory, so re-homing might require some slight modification to that code, if it exists. One feature which ATE does not offer, but ZTERM does, is an interactive file transfer user interface. We deliberately excluded that because we felt that in most cases, it was an invitation to abuse, i.e. it was better to limit file transfers via the application logic, rather than to encourage users to transfer files back and forth unsupervised. But if that's the way you like to work, we recommend using one of the free SFTP-capable file transfer clients, such as FileZilla. One of our A-Shell developers also makes A-Shell Reference Page 38 available a free one called MadFTP which has some features to make it integrate slightly better with A-Shell, i.e. sharing the login, knowledge of A-Shell directories, etc. But it isn't quite as sophisticated/powerful as FileZilla. Either one can be put on to the ATE menu bar via a simple application startup command, so further integrate it into the terminal environment, if so desired. Another detail I forgot to mention earlier about file transfers: A-Shell supports the ZTXFER.LIT command that may be used from the AMOS dot prompt (or A-Shell dot prompt) to transfer files, as an alternative to the application-driven transfer method. ZTXFER with no arguments gives the help info: ``` .ZTXFER ``` ``` ZTXFER usage: ``` ``` To send from Host to PC: ``` ``` ZTXFER{/switches} host-name PC-name or ZTXFER{/switches} host-name ``` ``` To send from PC to Host: ``` ``` ZTXFER{/switches}{a host-name=PC-name or ZTXFER{/switches} =PC-name ``` ``` Switches: ``` ``` /A forces ASCII mode ``` - `/2 requests new FTP/SFTP implementation if avail (faster)` ``` /ATE use ATE terminal channel (automatic for PC -> ATSD) ``` ``` Source file name may contain * wildcard (ATE/Unix only; no /2) ``` A-Shell Reference Page 39 For example: ``` .ZTXFER AAA.BBB c:\temp\AAA.BBB ``` ``` .ZTXFER CCC.DDD = c:\temp\AAA.BBB ``` The above would transfer the AAA.BBB file from the current directory to c:\temp\aaa.bbb, and then transfer it back to ccc.ddd. The file transfer protocol and authentication would be determined by terminal emulator configuration; for ZTERM it would be FTP; for ATE it would be SFTP. But, as mentioned before, the assumption within ZTXFER is that the current directory as seen by the application, matches the directory as it would be seen by the {S}FTP server. If that were not true because of jailing/sandboxing/re-homing, an adjustment would have to be made somewhere to convert from one to the other. (It wouldn't be too difficult, but would require some tinkering.) A-Shell Reference Page 40 ## **- CONVERSION: AM PC FILE TRANSFERS** A client attempt to transfer files from an Alpha Micro computer to a PC using ZTERM, on the way to their happy future with A- Shell, reports the following: I am not having much success with ZTXFER. I have programmed and built command files for porting over my clients files from the Alpha to a Win7 Pro workstation using the ZTXFER program. Major issues. It runs exceeding slow, maybe 2 kbs per second. It also fails about every 5th transfer. It especially fails on .dat and .mmo files (do I need the /C switch?), however some port ok. Most frustrating is if it fails there is no way to either cancel , exit, reset terminal, etc. If I use task manager to end task it will stop but as soon as I open ZTERM again it just keeps going until it fails again. Our response to the client was: The /C switch for ZTXFER only applies when copying to AMOS, not from, so that's not an issue here. Our best guess as to the cause of the lockup is handshaking, i.e. that the serial connection from the ZTERM workstation to the Alpha is not wired for RTS/CTS handshaking, and/or ZTERM has not been configured for that handshaking. As a rule, XON/XOFF is not reliable with file transfers, and file transfers are not reliable without working handshaking. The symptom is typically the one reported, i.e. it works for a few files and then locks up. A good way to test handshaking is with a barber pole display, like this one: ``` program BARBER,1.0(100) ! barber poll ``` ``` MAP1 I,F ``` ``` MAP1 BAR$,S,79 ``` ``` ? tab(-1,99); ! smooth scroll (probably not supported, but no harm to try) ``` ``` FOR I = 33 TO 111 ``` ``` BAR$ = BAR$ + chr(I) ``` A-Shell Reference Page 41 ``` NEXT I ``` ``` FOR I = 1 TO 1000 ? BAR$ BAR$ = BAR$[2,-1] + BAR$[1,1] ``` ``` NEXT I ``` ``` END ``` That should output about 80K characters, which should take about 40 seconds as 19200 baud, or 20 at 38400. If the handshaking isn't working, it will probably become scrambled noticeably after several seconds. Until you can get that to work reliably, file transfer is going to be painful. Other than improving the baud rate, about the only other thing you can do is run it on multiple terminals at the same time in parallel. I remember once doing a conversion like this with 5 transfers running, and me going around from one to the next to check on them, move to new PPNs, restart after errors, etc. for the better part of a weekend.) Of course getting ethernet working will make it a hundred times faster, at least, so it's worth a little effort. But I don't know much about the hardware of a 2000VME machine. One tip: if you do get it working, you will need to add the -n switch to the FTPD startup so that FTP will be compatible with the DevPPN syntax. A-Shell Reference Page 42 ## **PERFORMANCE IN LARGE SYSTEMS** _Added February 2018_ _A reseller says: "My client has approximately 250 users, wants to migrate to A-Shell, and can create—through virtualization— pretty much any environment and operating system. What environment—Windows or Linux—should I recommend to the client for best performance, and why?" Our response follows._ In our experience, the limiting factor in overall system performance for typical A-Shell systems is disk I/O, which is dependent on a combination of factors including the physical performance of the disk hardware, cache performance, latency/bandwidth between the disk and the user memory, and locking performance. The worst architecture is Windows P2P (peer-to-peer) LAN, which has a big disadvantage due to inherent complications related to communication and data transfer between the individual workstations and the file server. They are also difficult to manage because of the degree of independence between the workstations, problems with different OS versions, security concerns, etc. Consequently, we do not recommend P2P architecture for systems larger than about 20 workstations. The best performance will be a Linux (CentOS or RHEL) system with local (not NAS or SAN) dedicated disks: local to avoid the latency of communication across some kind of network connection, and dedicated to avoid file locking delays inherent when a disk subsystem is shared between multiple computers. Virtualization is not a significant factor, but a multi-core "server class" (e.g. Xeon) CPU is. In the Linux environment, workstations should be connected over SSH2 connections, preferably from ATE (AShell) clients. 16GB RAM should be more than adequate for 250 users. For sites that want to stick with a purely Windows solution, the next best thing would be a Windows server where all of the processes run directly on that server. Because of the higher overhead of Windows processes, this requires a more powerful server, with a lot more memory than for the Linux case, but if you can build a server capable of hosting simultaneous Terminal Service sessions for all your users, then that will be an acceptable solution. It doesn't have to be Terminal Services/RDP; it could also be TELNET/ATE, or Citrix, or one of the other similar protocols which effectively turn the workstations into mere terminals rather than independent computers merely sharing the server's disk resources. Any of these designs will have a higher price-toperformance ratio compared to the Linux solution, but with enough resources should give adequate performance. Since this design only makes sense in the presence of significant local technical knowledge, you should defer to them to determine adequate RAM and CPU resources. ## **See Also** - The Performance section of this document A-Shell Reference Page 43 ## **COMPATIBILITY** ## **Data File Compatibility** Both random data files and ISAM 1.x files (.IDA and .IDX) are 100% compatible between A-Shell and AMOS. It is possible to transfer them as direct binary images between machines. Sequential files are compatible, but stored in the local operating system format. For AMOS, this means each end of line is marked with a Carriage return/Linefeed pair. This is true also of Windows, although sequential files can sometimes terminate with a **^Z** end-of-file marker. Under Unix, new lines are indicated with a single character, **\n** (linefeed). A-Shell is capable of reading both DevPPN-format and host-system-format sequential files. All newly created files are normally written in the current host-system-format. You can force A-Shell to use CRLF terminators in sequential output under Unix by setting OPTIONS=CRNL in miame.ini; see Configuration for details. Despite the minor format differences between sequential files on the various platforms, you can generally just transfer them between systems with no conversion, since all of the major A-Shell utilities (VUE, COMPIL, INPUT, etc.) will accept either format. VUE will accept files with either style of line terminator and always write them back in the native format, providing another way to convert source programs if necessary. You can override the terminators used by VUE with the CRLF= entry in the ini.vue file. Note that you should not save Unix configuration files and scripts with CRLF terminators, and this may render them undecipherable to Unix. If you are using the native operating system executable version of VUE for such, you can prevent this by creating an /etc/ini.vue file which contains CRLF=FALSE. ISAM 2.0 or ISAM Plus files are implemented using C-ISAM by Informix or D-ISAM by Byte Designs. Because of this, the format of the data and indices are not compatible, and the files must be transferred by first dumping them with ISMUTL.LIT on the host system, and then reloading them with the A-Shell version of ISMUTL.LIT. For those who object to this procedure as being too slow, due to the need to manually run ISMUTL to generate the new files and especially due to the time it takes to dump the old files on some slower machines, we have developed a pair of utilities which speed up and simplify this process; see the SOSLIB. ## **Program Compatibility** A-Shell Reference Page 44 The A-Shell runtime interpreter (RUN.LIT) is compatible with programs compiled under most versions of AMOS using either the 1.3 (OCMPIL.LIT) or 1.4 (COMPIL.LIT) compiler. It is not compatible with the RP files generated by BASIC _plus_ . On the source code side, the A-Shell compiler is compatible with all AlphaBASIC source code written for the version 1.3 compiler, and virtually all source code written for the version 1.4 compiler as well. The A-Shell compiler also supports most of the BASIC _plus_ source code (but not the compiled object code.) See PLUS Extensions for details on which BASIC _plus_ code is supported. The A-Shell compiler (either COMPIL or OCMPIL) will nearly always generate the exact same RUN file, right down to the hash code, as will the corresponding AMOS COMPIL and OCMPIL will. Thus, except for BASIC _plus_ , you have compatibility in both directions for both your source code and compiled programs. ## **- A Shell and MIAME** A-Shell was originally developed as part of a larger system called the _Machine Independent Alpha Micro Environment, "_ MIAME" for short (pronounced like the beach in Florida). MIAME is no longer considered a viable product or software environment apart from A-Shell, but many references to MIAME remain in the A-Shell system. A-Shell Reference Page 45 ## **SETUP** A-Shell Reference Page 46 ## **- A SHELL INSTALLATION** This section describes the procedure for physically installing A-Shell on your computer. Since the procedures differ slightly between Windows and Unix, each is described separately. If you are updating as opposed to doing an original installation, see the documentation on Updating A-Shell. ## **Subtopics** - Before Installation - Windows Installation - UNIX Installation - After Installation A-Shell Reference Page 47 ## **BEFORE INSTALLATION** Review the following notes and make sure you are aware of the various issues involved before beginning the installation. ## **File System Setup** Although A-Shell itself can exist in any directories, for system administration purposes it may be wise to try to separate it from other application and operating system directories, if possible. This is less of an issue under Windows, where you typically have only one file system (or partition) available, and thus the best separation you can achieve is to give A-Shell its own directory tree, and possibly its own share name. Under Unix on the other hand, it is normal to have multiple file systems, and there are some particularly good reasons for defining one or more individual file systems to keep A-Shell separate from the rest of the operating system: - Individual file systems can be separately backed up and restored. - Separate file systems are naturally insulated from each other, so that any corruption that occurs in one will not spill over to - another. This will not only protect A-Shell from problems caused by some other application but also protect you from being accused by your system administrator of allowing your application to corrupt the system. - Since different file systems can be mounted at the same mount point (though not at the same time), you have the ability to - easily switch to another version of your data or application (backup, test, archive, etc.) temporarily without making any changes to A-Shell or your application. (This works best when you have "extra" scratch file systems available which you can restore a tape to.) - Putting your A-Shell application in a separate file system will eliminate the possibility that you can bring the system down - by filling up the disk. You may still cause your application to halt when it runs out of space, but the operating system will not be affected. ## **Installation Overview** The core A-Shell installation consists of a single directory tree, normally named /vm/miame or \vm\miame. The top level contains the main configuration file, miame.ini. Below that is a bin directory containing the binaries—i.e., A-Shell's main programs and libraries—and a DSK0 directory tree with multiple sub-directories for system commands and general shell A-Shell Reference Page 48 ## variables and control file. Depending on the size and complexity of your application, you may create one more more additional pseudo-device directory trees adjacent to DSK0 or anywhere. That is something you would set up manually after finishing the basic system installation; see DEVICE. ## **Security Key** After installation, it is necessary to install the security key that was supplied at the time of purchase. This process is described in the After Installation notes. If you don’t have a security key, A-Shell will run in demo mode, which is fully functional except for nag messages and being limited to a the single user. ## **Updating** For Windows, updates are most easily accomplished via the _Help > Check For Updates_ menu, which checks for the existence of an update, and if found, gives you the option to proceed. The update routine is identical to the install except that it doesn't give you the option of a target location. For Linux, use the same process as for the original installation. Under all operating systems, the installation process will detect that (or ask if) an update is being performed and will not overwrite any existing configuration files. Any configuration files that might have new fields added, or differing formats, are stored in example form with .new extensions. If the function key translation tables are updated, the original ones will be saved with .ifs (.ifx) and .vus (.vux) extensions. The ash_install script used for installing and updating A-Shell under Unix will execute two special customization scripts— pre_ash_install and post_ash_install—if they exist in the custom subdirectory of the specified target directory tree. These allow you to customize the update process, perhaps saving, renaming, or removing certain commands or files, etc. See the sample A-Shell Reference Page 49 scripts included with the release for further notes and examples. ## **Multiple Installations** It is possible to install A-Shell several times on a single machine, in different paths, which enables entirely separate A-Shell environments. While this is generally not recommended for end-users, who are typically running A-Shell as a single-purpose application, multiple environments can be very useful for developers and resellers for a variety of purposes: development versus production systems, duplicating customers' systems, etc. The recommended directory structure is to have all virtual machines located in the \VM or /vm directory. Each A-Shell installation would live one directory level below this identified by its machine name and the MIAME environment variable pointing to this subdirectory. It is recommended that the first A-Shell installation on a machine be made in the default directory \VM\MIAME or /vm/miame. ## **Hardware and Performance** The days of agonizing over how to spend your limited hardware budget in order to get acceptable performance are pretty much over. Modern computers are so powerful and so fast that all A-Shell applications, with very few exceptions, will run at nearly unbelievable speeds. However, there are still some basic principles to consider when deciding on how to deploy and configure a multi-user system for best performance: ## **Operating System** Linux is generally much faster than Windows, especially in the area of multi-user disk I/O. It also requires a lot less memory per user. At the opposite extreme is the Windows peer-to-peer ("P2P") LAN environment, where file sharing can get bogged down in network communication between multiple PCs. If you don't have a lot of disk I/O involving simultaneous access to shared files, a P2P LAN is probably the simplest and most familiar Windows configuration, especially for those who already have such a LAN in place. Somewhere in the middle would be a Windows server configuration where the workstations are just running as terminals (i.e. connected via RDP or ATE/telnet), in which case you eliminate the network/file sharing overhead. A-Shell Reference Page 50 ## **CPU** For multi-user systems, the more CPU cores, the better. A-Shell applications are rarely limited in speed by CPU issues, so this isn't a major consideration. ## **Memory** Most A-Shell applications are quite comfortable with less than 20MB per user, which is quite small by modern standards. That said, all operating systems will benefit from lots of extra memory for disk cache and other internal uses. ## **Disk Drives** SCSI is far faster than SATA or IDE, even in a virtual hardware environment. Since most A-Shell applications will be limited in speed by disk access times rather than CPU performance, this is probably one of the most important considerations. On the other hand, most modern disk drives are very fast, especially SSDs. ## **Directories** An often overlooked consideration is how many files you allow to accumulate in a single directory. With huge disk capacities, you may be tempted to accumulate years worth of report files. However, a better approach is to move those files to archive directories so the active directories don't have to deal with overhead of scanning over thousands of files for every file lookup. A good rule of thumb is to keep the number of files in any active directory below 1000. ## **More Information** Given the pace of change in the computer hardware environment, the information presented above may be accurate or - hopelessly out of date. For more information and the latest discussions on this subject, see the relevant discussions on the A Shell forum. A-Shell Reference Page 51 ## **WINDOWS INSTALLATION** For purposes of A-Shell installation there are basically three types of Windows environments: - Single users - Local area networks (LANs) of modest size. - Other networks: this broad category includes large LANs, WANs, networks with remote users, networks where multi-user - access and/or network traffic are significant concerns, and every other network situation that is other than the two simple environments mentioned above. See Windows Performance for more information. ## **Single User Installation** A-Shell/Windows is normally downloaded from the MicroSabio web site and installed on a PC like any other Windows program. To install, follow the normal Windows software installation procedure—that is, download the appropriate Windows installation program from the MicroSabio downloads page and then run program, following the prompts and answering the questions. The - installation procedure will optionally create a shortcut for Launching A Shell, and you're off and running. The final step is to run A-Shell, go to _Help...Check for Updates_ , and install the latest version of the software. ## **Subtopics** - Windows Network Installation - Files and Registration - Installation Problems - Machine Names - Drive Mapping - Windows Printers - Windows Performance A-Shell Reference Page 52 ## **WINDOWS NETWORK INSTALLATION** Most Windows instances of A-Shell are installed into relatively small local area networks, with or without a central file server. If this is your situation, then you're in the right place. If your network situation is more complex, see Windows Performance. Note that "server" as used in the following discussion does not mean "dedicated Windows Small Business Server" or any other centralized computer upon which the other computers in the network are dependent. It simply means "the place where A-Shell data files and programs are located." This CAN be a dedicated file server, but it can also be just one of the regular PCs on the network that has been designated as the location of the A-Shell data and programs. The objectives in a typical Windows installation of A-Shell are simple and straightforward: - Have a shortcut or start-menu item on each PC so that the user can quickly and easily get A-Shell running - Load application data and programs on a server so they are accessible by all PCs running A-Shell - Create an environment for easy, manageable and coherent A-Shell updates in the future The shortcut that executes A-Shell can retrieve the A-Shell program from either the local PC or the server. Which is better? Well, that depends. - Do you have an old / tired / slow network, such that you do everything possible to minimize "get from server" calls? Then - putting A-Shell on the local PCs makes more sense. - Do you have a modern, 100-MB (or faster) network where everything is always loaded off the server? Then put A-Shell on the - server too. - When it comes time to update A-Shell, do you want each individual PC user to update at her convenience, and to make her - own decision to update? If yes, then install A-Shell on the individual PCs. - Do you want to control future updates of A-Shell from a central location—which requires making everybody on the network - stop using A-Shell so you can update? If yes, then put A-Shell on the server. As you can see, there are variables involved—and there is no right or wrong way to do this. ## **Subtopics** - Recommended Steps A-Shell Reference Page 53 - Alternative Steps A-Shell Reference Page 54 ## **RECOMMENDED STEPS** In most cases, and in the absence of information suggesting otherwise, MicroSabio recommends that the A-Shell installation program be run FROM EACH of the PCs that will be running A-Shell. While this seems a little redundant, and is in fact a little redundant, there are reasons for doing it this way. So here are the recommended steps: - 1 Create the folder on the server where A-Shell is to be installed. You can use any name you want, but MicroSabio recommends —for historical purposes and the sake of consistency—the folder "VM." You also need to create a network share, which should also be named "VM." Note: DO NOT share the entire c:\ drive; this is guaranteed to create headaches. - 2 Working on one of the workstation PCs (not the server), download the applicable version of A-Shell for Windows from the MicroSabio downloads page. 3 From the workstation, install A-Shell by running the installation program. When asked for the location into which to install A- Shell, enter: \\servername\VM\miame. As you will see the \vm\miame\ part is already included; just replace c:\ with \ \servername\. - 4 Finish running the installation program. 5 Run A-Shell to confirm that all is well. A few LOG and DIR commands is enough. What we're confirming is that the desktop shortcut you created actually executes A-Shell as intended, and that miame.ini—A-Shell's initialization file—is being found and processed. Don't proceed until you're happy and convinced that all is working, by which we mean that you click on the desktop shortcut and A-Shell runs as expected. At this point, the workstation you've been working on should be perfectly set up for A-Shell, and you know how to run the installation procedure. Now go run it again—the same steps, starting with #2 above—on each of the PCs that will be using A- Shell. It would appear that you are installing the same software into the same location multiple times. That is actually true. But the installation program is smart and knows to not actually copy files that are already present and up to date, and the installation is being rerun not for the A-Shell files but for Windows files over which A-Shell has no control. Subsequent installations will be much faster than the first one, and at the end of the process each PC will be properly and completely set up. The final step of the process is performed after you have finished installing A-Shell from each of the PCs. It does not matter which PC runs this procedure, but it needs to be done after all the installations. A-Shell Reference Page 55 6 While running A-Shell, go to _Help...Check for Updates_ . This will insure that you have the latest copy of A-Shell on the server. Run the installation as you have the other times, and you're done. You only need to run this once, and not from each PC. Note that you must not run A-Shell from any one PC while you are installing from another PC. Also note that despite the multiple installations, all the PCs are running off the same server-based copy of A-Shell. A-Shell Reference Page 56 ## **ALTERNATIVE STEPS** It is perfectly fine to install a unique (not shared) copy of A-Shell on each PC, if you think there will be some benefit from that approach. One possible reason for this approach is that you want individual PC users to be in charge of their own updates. Obviously, each user must be running her own copy if she wants her own update. When you run the A-Shell installation program, use the default install-to directory of c:\vm\miame. This puts a copy of all the A- Shell files on the local machine, and miame.ini will be configured to run that copy of A-Shell. However, you must manually modify the Windows shortcut or start menu command that invokes A-Shell so that it knows to look on the server for the initialization file miame.ini. Refer to Installation Problems and the discussions about miame.ini for information on the necessary modifications and, if necessary, troubleshooting steps. A-Shell Reference Page 57 ## **FILES AND REGISTRATION** By default, most Windows programs install themselves in a folder called c:\program files\\. A-Shell, by contrast, installs itself in the folder c:\vm\miame, although this can be changed by the user at the time of installation. If you need or want to change the installation directory, you can do so without penalty or complication. However, A- Shell uses its unconventional installation directory tree for historical and functional reasons, and you should make sure you know what you're doing before changing the installation folder. This is especially true if other people or computers are involved in your A-Shell environment. As noted above, A-Shell stores its primary configuration information in ordinary files within the A-shell directory tree rather than in the Registry. This allows the entire A-Shell system—both application and data—to be backed up, copied, or moved, with ordinary file system commands. A few caveats: - ATE uses the Registry to store connection profiles, although they can be exported to and imported from files. - A-Shell's main configuration file, miame.ini, contains references to file locations. Depending on whether they are fully qualified, or based on environment variables, you may need to adjust them if you move the entire directory tree to another location. - User-customized settings, such as initial window size and position, color scheme, etc., may be saved via File > Save Settings - either within the main A-Shell directory tree or in the Windows standard user-specific %APPDATA% directory. These are not critical and can easily be re-customized, but should be noted if you want to make a complete backup or move. - A-Shell and ATE both use the Registry to save user interface history information, such as XTREE configurations, last printer - selected, last dialog positions, etc. Again, these are not critical to operation. - One or more external COM DLLs may get registered with Windows during installation. These registrations would be broken by - relocation of the directory tree; the simplest remedy for that would be to re-run the installer/updater pointing to the new location. A-Shell may be installed multiple times on a PC. If it is installed in different folders, and you can keep the start-up icons and commands separate, then different versions of A-Shell can exist and run on the PC without problem. If you install a new version over the top of an old one (i.e., into the directory where A-Shell already exists), then obviously the old program files will be overwritten with the new ones. Note, however, than none of the configuration files will be overwritten, and all of your previous settings and values—including anything written onto A-Shell disks and other devices—will be preserved. A-Shell Reference Page 58 ## **Subtopics** - File Locations A-Shell Reference Page 59 ## **FILE LOCATIONS** When you use Windows File Explorer to look at the A-Shell "tree," you should see something like this. In this case, the base or root A-Shell folder is called "Ashell." ## **- A Shell Root Folder** As mentioned elsewhere, A-Shell can be installed in a location of your choosing or in the default folder of c:\vm\miame. This folder contains three critical and several miscellaneous files. The critical ones are: |**Filename**|**Contents / Usage**| |---|---| |coname.dat|Name of licensee.| |miame.ini|System configuration file which sets critical parameters for the overall
operations of A-Shell. Also includes license code which, along with coname.dat,
enables the non-demo operation of A-Shell.| |ashlog.log|A-Shell log file. SeeASHLOG
for more details.| ## **backup** Like most Windows programs, A-Shell uses a third-party program to handle the install and uninstall operations. The files in this folder were created by the installation program, and are copies of all the files that have been overwritten in previous updates. If and when you either revert to a previous version of A-Shell or uninstall A-Shell, the installation program will read this folder to determine which files should or should not be overwritten or uninstalled. **bin** A-Shell Reference Page 60 This folder, "binaries," contains the programs and program libraries that Windows executes when running A-Shell. A-Shell itself is contained entirely in the program file ashw32.exe. The folder contains several other programs (.exe files) that are, or may be, used in conjunction with A-Shell. The DLL (dynamic linked library) files execute various special functions within A-Shell. A-Shell will work fine without the DLLs—until you try to use the function in A-Shell that needs a particular DLL. ## **cache** see below ## **doc** This folder contains a file called ashelp.mdf, which means "A-Shell help menu definition file." See Help Menu Links on how to modify this file and change the look and function of the A-Shell help menu. The folder also may have a readme.txt file. ## **dsk0** This folder contains all of the DSK0: PPNs you have on your A-Shell system, with each PPN being its own Windows folder. The PPN DSK0:[2,2], for example, is a folder in Windows called, using the example from above, c:\ashell\dsk0\002002. If you use SYSACT to create a PPN in A-Shell, say [40,40], then a new folder will show up in dsk0 called c:\ashell\dsk0\040040. If you create a new folder using File Explorer, c:\ashell\dsk0\033033 for example, then a PPN DSK0:[33,33] will show up in your A- Shell environment. ## **icons** This folder contains all of the icons used in A-Shell. ## **cache, permcache** These folders (a) are used by ATE but not by A-Shell, but (b) frequently show up in the A-Shell folder due to an overlap between ATE and A-Shell. If you see them in your A-Shell tree, they can be either deleted or ignored with no ill effects. A-Shell Reference Page 61 ## **INSTALLATION PROBLEMS** There is very little that can go wrong during a Windows installation of A-Shell, and it is likely that if something does go wrong, the problem is related to something unexpected done by the installer. Unless there were some problems during the installation process itself, and the files A-Shell requires in order to run were not actually installed on the PC, there are basically two places to look for problems. ## **Config File** - First, make sure you understand the A Shell Configuration File and how it works. If A-Shell does not start up properly, it is likely that some file specification in miame.ini is pointing at a wrong or non-existent location, or a required command in the ini file is mis-formatted or misspelledd. ## **Start Command** Secondly, check the Windows start command (shortcut) that is invoking A-Shell. The command line should have two parts, as shown below. Note that if the path in which A-Shell was installed includes spaces (like "Program Files"), then the file specs on the target line will (and must) have quotes around them. - The first part of the command line specifies the file specification of the program to run—i.e., A-Shell. The program and file - name is ashw32.exe and it should be at the end of a file specification that begins with "c:\...." If A-Shell was installed in the c: \vm\miame folder, for example, the first part of the target command should look like this: ## `C:\vm\miame\bin\ASHW32.exe` - The second part of the target line, which begins after the first part and a space, should begin with "-i" and be followed by a - space and the full file specification for the A-Shell initialization file (normally "miame.ini"). If A-Shell were installed as above, then the second part of the target line would look like this: - `-i C:\vm\miame\miame.ini` If A-Shell were installed in the C:\Program Files\MicroSabio\Ashell folder, the full command line should look like this: - `"C:\Program Files\MicroSabio\Ashell\bin\ASHW32.exe" -i "c:\program files\microsabio\ashell\miame.ini"` The "Start In" specification of the A-Shell shortcut should be blank. A-Shell Reference Page 62 See the following for specific problems that you may encounter. ## u **Missing or Invalid MIAME** If you see this error, it is because A-Shell is trying to run but cannot find or process the required initialization file (normally "miame.ini"). This would normally indicate that the "-i " argument on the launch command line is missing or incorrect. See Specify Ini File for related information. A similar and related error message for a missing ini file is shown below. This normally occurs if A-Shell has previously been set up properly and has run as expected, but the ini file has been moved or renamed. ## u **Cannot INIT DSK0** This error (below) normally occurs when the statement in your miame.ini file that specifies the location of DSK0: is entirely missing. The three lines below show what happens as A-Shell tries to execute A-Shell's default startup command, ASTART, and there is no DSK0: on which to find that file. Solving this problem should be easy; simply add the DEVICE statement in miame.ini, or perhaps remove the semicolon in front of it that is turning it into an inactive command (i.e., a comment). ``` ?Cannot INIT DSK0:ASTART.CMD[2,2] - device does not exist ``` ``` ?Cannot INIT DSK0:ASTART.DO[2,2] - device does not exist ``` ``` ?Cannot INIT DSK0:ASTART.LIT[2,2] - device does not exist ``` A properly formatted statement in miame.ini for defining DSK0: would look like either of these: ``` DEVICE=DSK0 "c:\program files\microsabio\ashell\DSK0\" ; Pathname for DSK0: ``` A-Shell Reference Page 63 ``` DEVICE=DSK0 c:vm\miame\dsk0\ ``` ## u **Command Will Not Execute** If you get a screen like the one shown here, it normally means that your `DEVICE=DSK0:` statement is present but invalid. The problem is likely a misspelling or bad punctuation. Remember that paths with spaces in them must be quoted. A-Shell Reference Page 64 ## **MACHINE NAMES** _Rewritten April 2015_ In a peer-to-peer (P2P) network environment, A-Shell/Windows uses the computer name to establish a unique ID for each session. The computer name is sometimes referred to as the Machine Name and can be found and set in the My Computer System Properties dialog. It is critical that each workstation on the network has a unique Computer Name, although it is unfortunately common for installers to overlook this step when installing new machines. When a new A-Shell session is launched, it scans the job table to see if there is an existing record for this machine/instance, and if so, it assumes that the prior session was terminated uncleanly, such as by rebooting the PC, and re-uses that same JOB table record so as to avoid accumulating orphaned JOB table entries. If there are multiple machines with the same name, A-Shell will be fooled into thinking that a new and distinct session is actually a restart of a previously aborted one, causing the earlier session's JOB table record to be overwritten. This is likely to lead to the first session aborting with a cryptic "your job table has been zapped" message. Outside of A-Shell, the duplicate computer names will cause a variety of other problems that are best avoided. To help identify this error before it becomes a more serious problem, A-Shell (see History, below) generates its own unique identifiers for each machine during installation; it can then use that information to identify duplicate machine names when new sessions are launched, thus allowing the problem to be detected and resolved right away. In order for this to work, you must run the installer/updater to update each workstation, rather than manually installing the update by copying files. The installer/updater establishes a unique identifier for each machine and saves it in the HKLM section of the registry, to be used to determine whether an instance with the same machine name as an existing instance is actually the same machine or not. If so, then the new instance can safely overwrite the old one. But if not, an error message is displayed and the new session is not allowed to start. The error message will indicate the machine name, the user name and JOB name of the offending existing instance, and the unique identifiers (8 hex digits) for the two machines. You can use the `SYSTAT/CU` switch to display the unique identifiers for existing sessions, which may be helpful in tracking down the offending duplicate-named machine. Also note that the issue only affects P2P networks; ATE, Terminal Server, and Unix systems are not subject to the problem and are not affected by the update. ## **History** A-Shell Reference Page 65 - 2015 April, A Shell 6.1.1408: A-Shell now detects duplicate machine names. A-Shell Reference Page 66 ## **DRIVE MAPPING** _Updated April 2022_ The astute reader will have noticed that we rather glossed over the issue of drive mappings in the preceding discussion. Indeed, the essence of a network installation is setting up drive mappings so that each workstation can reference shared directories on the server. It is assumed that the installer will have enough expertise to create those drive mappings using the standard Windows procedures. However, there are a couple of subtleties worth mentioning here. First, the server must "share" the drive that will hold the files common to all of the workstations. This much is obvious. However, although it may be desirable, it is not absolutely necessary that the workstations actually create a drive mapping to it. Instead, you can use the UNC (Universal Naming Convention) notation to reference the server and share name instead of the mapped drive letter. For example, assuming the server’s machine ID is "BIGBOY", and A-Shell is installed in the directory C:\VM\MIAME, you might share that directory as "MIAME" and then refer to it from all machines on the LAN in various contexts, including the install program, as \\BIGBOY\MIAME. This technique has the advantage of eliminating the need to define a drive mapping to the server for every workstation, and eliminates any possibility of different workstations ending up with different mapped drive letters. If you decide to use the more traditional mapped drive letter approach, it is strongly recommended that you choose a relatively high drive letter (like X:) to reduce the possibility that you run into a workstation that has so many devices mapped that the desired letter is already taken up. The only known disadvantages to using the UNC name of the server rather than creating a drive mapping are that you may experience a delay the first time you try to connect —while a dynamic network connection is established—and in some cases, such as after a period of inactivity, some servers may begin to drop UNC connections. This could cause a problem if the inactive application had files open. Another subtlety to note is that since data transfer over the network is subject to bottlenecks, it is often desirable for performance reasons to define one or more devices (logical disks) that reside on each local workstation for the purpose of holding print files, temp files, that don’t need to be shared. This assumes that the application provides an option of where to send different categories of files, such as DSK1: for the master data files, DSK2: for print files, etc. Note that whenever sharing directories, it is strongly advised—for both performance and security reasons—to share the smallest directory tree that includes all the necessary subdirectories. In other words, instead of sharing the entire C: drive, share the directory that contains miame.ini and the DEVICE directories beneath it. A-Shell Reference Page 67 ## **WINDOWS PRINTERS** Like all other versions of A-Shell, A-Shell/Windows uses the PRINTER command line in miame.ini to define the default spooler name. This name, in turn, is usually associated with a configuration file for that printer, called sys:.ini or ashcfg:.pqi, the contents of which are discussed in detail in Printer Configuration in this document. The main aspect of printer configuration to be dealt with at this point is simply to identify the printers which will be used by the application, and to install and configure the necessary drivers so that each workstation can refer to each printer by a common descriptive (i.e. "Invoice Printer #1") or network (i.e. \\prtsrv\invoice1) name. This name will then be associated with the spooler name via the DEVICE statement in the spooler configuration file. In most cases, it is no longer necessary to manually install a local printer driver for network printers, provided they can be accessed via the \\machine\sharename. Applications that embed their own ESC sequences into print files for the purpose of controlling printer functions (e.g. condensed print), may need to use a printing mode called "PASSTHROUGH" printing. PASSTHROUGH printing is somewhat unusual in the mainstream world of Windows, and thus many printer drivers (and in some cases the printers themselves) do not support it. If uncertain, you can always use the Generic Text Only printer driver (provided the printer hardware supports it – try the driver Test page to confirm that.) Refer to Printer Configuration for more details about PASSTHROUGH vs. non-PASSTHROUGH printing. A-Shell Reference Page 68 ## **WINDOWS PERFORMANCE** _Added April 2022_ Here are some tips to help you maximize A-Shell performance in a Windows environment: - If your network is large, containing many PC's and applications unrelated to A-Shell, try to reduce traffic hitting the A-Shell - server by putting it on it's own subnet, if possible. - File sharing is quite efficient for read-only and text files, but not so much for record-oriented files, since each record-level - access may require querying many other PCs to see if they have an updated version of the record. To minimize that problem, if practical, open files only when you are actively using them, as opposed to opening all the files at the start of the program and closing them all at the end. - Applications that implement file locking using XLOCK or FLOCK, rather than READL (i.e. LOKSER protocol), may run faster - using the 'C' version of A-Shell. - Using a domain (with all users signed into it) results in more efficient and secure LAN performance than informal P2P - networks. - For files that don't need to be shared—print files, sort files, etc.—it's much faster to put them on each client PC then on the - shared server. Typically this is done by defining a DEVICE, e.g. WRK0:, that points to a directory on the C: drive, i.e. each client PC's C: drive, rather than on the server, and then use that device for the appropriate class of files. - If the LAN access becomes too slow, or especially if some clients connect over a WAN, telnet (ATE/ATSD) connections will be - much faster than P2P connections. The standard P2P model offers the best CPU and screen I/O performance, but the worst disk I/O, which is usually the bottleneck. ATE/ATSD connections offer the reverse set of trade-offs. A-Shell Reference Page 69 ## **UNIX INSTALLATION** _Reviewed and revised July 2020_ A-Shell/Unix releases are binary specific for a particular machine and architecture. However, the procedure is pretty much the same, regardless of the flavor of Linux / Unix. Where there are important differences, they will be noted. Note that the document uses the term "Unix" to mean "Unix, AIX, HPUX, Linux and all Unix-variants." We of course recognize the differences between the operating systems. But because they all work about the same with regard to A-Shell, and the A-Shell commands are the same for the entirely family, we've chosen to use "Unix" as the family name. A-Shell/Unix is downloaded from our web site in the form of one or more "cpio" files, typically named ash-###-???.bin, where "ash" indicates "A-Shell," ### indicates the version and build number, and ??? indicates the target platform. The file name ash-6.5.1676.7-el5.bin, for example, indicates A-Shell version 6.5, build 1676.7, for Enterprise Linux version 5. Often the file will have an additional extension, either Z or tz, in which case it first needs to be uncompressed, using `uncompress .Z` or `tar xvzf .tz` . To install the A-Shell software, copy the cpio file to a convenient location, such as /tmp, and log into Unix using your normal user id. _Do not log in as the superuser (root)_ . Then enter the following: ``` $ cd /tmp ``` ``` $ su ``` ``` [Enter root's password if requested] ``` In the examples below, we assume you are installing from a cpio file, with an A-Shell build number of 827. For the installation from a file, replace the same filename given below with the actual one you downloaded. ## **For Linux** ``` # cd /tmp ``` ``` # cpio -iuB ash_install < /tmp/ash-6.5.1663.0-el7.bin ``` A-Shell Reference Page 70 ## **For AIX:** ``` # cd /tmp ``` ``` # uncompress ash-xxxxx.bin.Z (if .Z extension only) ``` ``` # cpio -icuB ash_install < /tmp/ash-xxxxx.bin ``` ## **Then, for all platforms:** ``` # chmod +x ash_install ``` ``` # ./ash_install ``` ``` # exit ``` The ash_install script will prompt you for the directory location for the object and runtime files (we suggest /vm/miame for both) and for the name of the file or device you are installing from (which will be the same as the one you extracted the ash_install script from above.) The ASH_INSTALL script will execute two special customization scripts (PRE_ASH_INSTALL and POST_ASH_INSTALL) if they exist in the custom subdirectory of the specified target (object) directory tree. These allow you to customize the update process, perhaps saving, renaming, or removing certain commands or files, etc. See the sample scripts included with the release for further notes and examples. The process will only take a couple of minutes. At the end, it will remind you to set up your MIAME and PATH environment variables and edit miame.ini as needed. ## **Subtopics** - UNIX Downloads - File Ownership and Privileges A-Shell Reference Page 71 - Advanced Privilege Settings - Setting Up UNIX Logins - Modifying the User .Profile - Backspace Key Operation - Enabling the Use of KILL.LIT A-Shell Reference Page 72 ## **UNIX DOWNLOADS** _Reviewed July 2020_ This page explains some of the finer points of selecting and downloading A-Shell for Linux and AIX. Here the number and variety of packages is such that rather than providing direct links to each of them, which would require constant synchronizing/updating of the web page with the download directories, we instead allow you to browse the download directory tree directly. All file names in those directories follow a common naming convention: ``` prod-#.#.####.#-platform{-options}.pkgtype ``` For example: ``` ash-6.2.1548.1-el7-efs.bin ``` ## **Filename Components** ## _prod_ A-Shell product or module: |**prod**|**A-Shell Software Product**| |---|---| |ash|A-Shell| |vue|VUE| |compil|Compiler| |psh|P-Shell| |ate|A-Shell Terminal Emulator| A-Shell Reference Page 73 **prod A-Shell Software Product** ## _#.#.####.#_ is the full version number; for example, 6.4.1548.2 ## _platform_ target platform and version: |**platfor**
**m**|**Operating System**| |---|---| |el5|RHEL5/CentOS5| |el6|RHEL6/CentOS6| |el7|RHEL7/CentOS7| |el8|RHEL8/CentOS8| |aix|AIX 4.3+| A-Shell Reference Page 74 |**platfor**
**m**|**Operating System**|**Operating System**| |---|---|---| |aix53+|AIX 5.3+|| |pi|Raspbian (|Raspberry Pi
)| ## _options_ specific additional features or variations: |**options**|**A-Shell Software Product**| |---|---| |efs|Encrypted File System| |tw|Triad / WrenchHead Catalog| |upd|File contains just an update/replacement of main executable| ## _pkgtype_ type (file format) of the package: A-Shell Reference Page 75 |**pkgtype **|**A-Shell Software Product**| |---|---| |bin|Complete release in CPIO format; see the previous page for unpacking instructions.| |tz|Compressed tar file, typically containing just the main executable; unpack with**tar -xvzf****_file_**.| |tar.Z|Alternate form of compressed tar; unpack with**uncompress****_file_.Z**then**tar -xvf****_file_**| ## **32 vs 64 Bit** All A-Shell binaries are 32 bit and are fully compatible with both 32 and 64 bit Linux and AIX operating systems, so there is no need to identify this in the package names. The only issue relating to 32/64 bit that often arises in the Linux world relates to the availability of certain auxiliary libraries that A-Shell may seek to dynamically load in order to support a particular feature. Since the 32 and 64 bit libraries are installed into separate directories, you may be confused into thinking that the library you need (e.g. libncurses or glibc or libpcre) is installed, when only the 64 bit version is installed. The solution to this kind of problem is - just to manually install the necessary library, explicitly specifying the 32 bit (typically "i686") version. See the A Shell forum for questions and answers in this area. ## **Linux Distributions and Versions** Although the A-Shell source is compatible with and therefore can be made available for a wide range of the most popular Linux distributions and versions, the same cannot be said for the binary executables. So it is important to select the right binary download for your distribution/version. For whatever reasons, the A-Shell user base has overwhelmingly favored the RHEL (commercial) and CentOS (open source) distributions, so those are the environments on which A-Shell is focused. Conveniently, both use the same version number sequences, and in fact are effectively equivalent as far as A-Shell is concerned, so they are referred to as using the common platform abbreviation **-el#** (e.g. -el7 for RHEL7 / CentOS7). If you don't see the version number you are looking for, then use the next lower one—e.g. if a CentOS 6 download is not available, use the CentOS 5 download instead. The A-Shell binaries can be assumed to be upward compatible unless specifically noted to the contrary. A-Shell Reference Page 76 For other Linux distributions, such as Ubuntu, contact MicroSabio to arrange for a new binary to be built. Or, consider Docker ... ## **Docker** A public Docker image for A-Shell is compiled/bundled for CentOS 7 which, if your OS supports Docker, may simplify the process of installing A-Shell together with the necessary compatible components. To access and download the available images, use the - command **docker search microsabio** . Search for "docker" on the A Shell forum for helpful information on working with the A- Shell Docker container. ## **AIX** In the AIX world, there is a major division between versions up thru 5.2, and versions 5.3 and beyond. Because this involves both hardware and operating system compatibility factors, and because AIX 5.3 was released long ago (2004), earlier versions are no longer supported. For customers still running an old AIX box which they cannot upgrade to a newer version because of hardware or budgetary limitations, we can only suggest considering a sideways move to Linux. Or remain on A-Shell 6.0. The same A-Shell 6.2 or 6.4 binary will work with all versions of AIX from 5.3 and beyond. ## **Version Numbers and Links** A-Shell is continually evolving. Since it is not possible to offer software packages that simultaneously - have all the latest new features including, possibly, some as-yet-undetected bugs and - are entirely bug-free and the beneficiary of extensive testing MicroSabio therefore offers A-Shell in two forms, as indicated by the version number: - An even numbered version of A-Shell is stable. No changes are being made to the software other than bug fixes. - An odd numbered version of A-Shell is a development version. The most recent version (i.e. highest number) is under active - development—i.e., it is being updated regularly, which normally means every few days and in some cases more than once a day. - The two most recent versions—i.e., highest numbers—are one of each: a stable version and a development version. The A Shell download folders provide several recent versions of both development and stable versions. A-Shell Reference Page 77 ## **FILE OWNERSHIP AND PRIVILEGES** After completing the script, and before proceeding to the configuration steps below, you may need to adjust the ownership and access privileges for the files and directories installed. The script sets the group ownership to group 100, which may not be appropriate for your system. Consult your operating system documentation for the CHGRP, CHMOD, and CHOWN commands for details. A good starting point would be to create a user group (e.g. "ashell" or perhaps the name of your application) and add all applicable users to that group. Then assign the entire A-Shell directory system to that group. Assuming you installed in /vm/miame, you could do this under most Unix flavors as follows: ``` # cd /vm/miame ``` ``` # chgrp –R ashell * ``` The above commands would assign every file in the entire directory tree starting from /vm/miame to the ashell group. You could then provide unlimited access to all files for all members of that group, as well as the actual file owner, very simply with the following commands: ``` # cd /vm/miame ``` ``` # chmod –R ug+rwx * ``` This sets the read, write, and execute flags for both the owner and group for all files in all subdirectories starting from the /vm/miame. If you are concerned about unauthorized users having the ability to overwrite important parts of the A-Shell installation, then you should set up a special user (or root) to be the owner of all the files distributed as part of A-Shell, and then allow only that user to have write privileges for those files. As an example, you might protect the files in the /vm/miame/bin and /vm/miame/dsk0/001004 directories as follows: ``` (while logged in as root) ``` A-Shell Reference Page 78 ``` # cd /vm/miame ``` ``` # chown –R root * ``` ``` # chmod 750 bin/* # chmod 640 dsk0/001004/* ``` For all the files in the /vm/miame/bin directory (where the ashell executables normally are,) the above commands would allow read/write/execute access to the root user, read/execute to users in the ashell group, and no access to other users. The idea is similar for the /vm/miame/dsk0/001004 (aka SYS: or DSK0:[1,4]) directory, except that those files don’t need the execute bit, since they are never really executed by Unix. Instead, they are handled like data by the A-Shell interpreter. Use the Unix ls –l command to verify the correct settings, which might look something like this: ``` # cd /vm/miame/bin ``` ``` # ls –l ``` ``` -rwxr-x--- 1 root ashell 827127 Jan 31 17:06 ashell ``` ``` # ``` ``` # cd /vm/miame/dsk0 ``` ``` # ls –l ``` ``` drwxr-s--- 2 root ashell 512 Jan 31 17:27 001002 drwxr-s--- 2 root ashell 2048 Feb 2 11:47 001004 drwxr-s--- 2 root ashell 512 Aug 12 02:41 001006 drwxr-s--- 2 root ashell 512 Jan 31 17:17 002002 drwxr-s--- 2 root ashell 512 Jan 21 15:29 007000 drwxr-s--- 2 root ashell 2560 Jan 31 17:19 007006 ``` A-Shell Reference Page 79 ``` # ``` ``` # cd 001004 ``` ``` # ls –l ``` ``` -rw-r----- 1 root ashell 2474 Jan 31 17:03 time.lit ``` ``` -rw-r----- 1 root ashell 3024 Jan 31 17:03 type.lit ``` ``` -rw-r----- 1 root ashell 2396 Jan 31 17:03 ver.lit ``` ``` ``` ``` # ``` If you have files in a lot of directories (corresponding to many PPNs) you can use the –R (recursive) switch to chmod as follows to act on all of the subdirectories at once: ``` # cd /vm/miame/dsk0 ``` ``` # chmod –R 640 * ``` ``` # chmod 750 * ``` The first CHMOD command above would set read/write privileges for the owner and read privileges for users in the **ashell** group for all files in all subdirectories of /vm/miame/dsk0. (The –R switch causes the command to descend the directory tree recursively.) The second CHMOD command then adds the execute flag to all of the files in the /vm/miame/dsk0 directory, since these files are actually directories, and directories must have the execute flag set. **Warning:** Under most Unix implementations, the execute flag must be set in all directories in order for users to be able to access those directories. Thus while the execute flag is not needed for most A-Shell files, such as *.RUN, *.LIT, and *.DAT, it is essential for the directories themselves. A-Shell Reference Page 80 **Another warning:** Shared data files in your application must offer read and write access to all users, so it would probably be unwise to limit write privileges to the file owner for such files. Putting your *.RUN files (which don’t need to be written to by all users) in a separate PPN (e.g. [p,0]) from your data files would make it easier to fine tune the access privileges at the directory level rather than the file level. If you don’t care at all about security, and it doesn’t bother you if certain files have their executable flag set even though they are not really executables, then you can just set all the read/write/execute flags for all of the files as follows: ``` # cd /vm/miame ``` ``` # chmod –R 777 * ``` In this case, the owner and group attributes don’t matter, since everyone is allowed all types of access. Most versions of the chmod command support a syntax for adding or removing privileges, without having to replace the current privileges with a single specified value set. For example, `chmod –R a+rw *` would add the rw privilege bits (for all three levels – user, group, other) to all files in the current directory tree, without removing the x privilege bit from any files or directories that already have it set. Replacing the "a" with some combination of "u" (user/owner), "g" (group), and "o" (other) would limit the effect to the specified categories. Also, replacing the "+" with a "-" would remove rather than add the privilege bits. A-Shell Reference Page 81 ## **ADVANCED PRIVILEGE SETTINGS** Aside from the privilege considerations discussed above, there are a couple of more advanced settings that you will need to consider, and if desired, carry out manually in order to enable certain auxiliary utility operations such as CHAT, SEND, KILL, and LOKUTL. The basic problem is that unlike AMOS, where assembly language commands or subroutines can read from and write to any region of memory, including the monitor and other JOBs’ partitions and control blocks, under Unix it is generally not possible for one JOB to see or affect any other JOB’s private information, nor is it possible to see the kernel’s private memory. There are two general cases to consider here. The first is the case of a utility that needs to see or affect another JOB, such as KILL, SEND, or CHAT. To allow this, the sender and receiver must either both be running under the control of the same effective user, or the sender must have root (superuser) privileges. The second case occurs when we need to access kernel information (such as the lock list, or the list of active processes.) In that case, we must have superuser privileges. Since having every user log in as the same user, and especially as the superuser, would defeat all of the safeguards which help make Unix a more reliable operating system than AMOS or Windows, we need a way to temporarily obtain the necessary privileges in a way that is out of the control of individual users to abuse. The SETUID mechanism allows us to do this, by providing a special bit in the directory entry for an executable command which causes the user of that command to assume the privileges of the owner (creator) of the command, but only while executing the command. As an example, the Unix utility ps (process status) uses this technique to allow anyone with sufficient privileges to execute ps to temporarily acquire the superuser privileges necessary to read the kernel’s process table in order to display a list of what every process is doing. The A-Shell utilities KILL.LIT, SEND.LIT, and CHAT.LIT fall into the first category of commands described above, since they require that both the sender and receiver either share the same effective user ID, or that the sender be the superuser. Of the two alternatives, we prefer the former, since as a general principal it is wise to limit the use of superuser privileges to the bare minimum. So instead, we can use the SETUID bit to cause everyone that is running under ashell to have effectively the same user privileges. For example: ``` # cd /vm/miame/bin ``` ``` # chown ashusr ashell ``` ``` # chmod +s ashell ``` A-Shell Reference Page 82 The above commands, we first make the user **ashusr** be the owner of the **ashell** executable, and then we use the **chmod +s** command to turn on the SETUID bit. Thus all users executing **ashell** will assume the effective identity **ashusr** while they are in A-Shell, and thus then can use SEND, CHAT, and KILL on each other. (You must first create a user called **ashusr** .) Note that this "effective" user ID does not conflict with the login ID, which remains distinct, and which is used in utilities such as SYSTAT to allow you to distinguish the users from each other. Because of the dangerous implications of the KILL command, there is another level of safety involved in enabling its use which is described in section following titled "Enabling the Use of KILL." The second case of utilities (those that need superuser privileges to access kernel information) are mostly taken care of by the standard operating system installation, and are not of particular to concert to A-Shell. There are a couple of exceptions though, most notably the **lslk** (list locks) utility, which is used by A-Shell’s LOKUTL.LIT (under Unix versions) to access the list of locked files and records. Since this utility comes from a shareware source you may need to manually install it (either in the same directory as the **ashell** executable or somewhere in the PATH) and, if not already done, change the owner to **root** and set the SETUID bit using CHMOD +S as shown below: ``` # cd /vm/miame/bin ``` ``` # chown root lslk ``` ``` # chmod +s lslk ``` In most cases, lslk is distributed with and installed by A-Shell, but you may still need to perform the above steps since the ownership and privileges may get overwritten by the steps described in File Ownership and Privileges above. Another utility similar to lslk which may be distributed with A-Shell (or obtained from the web) is lsof, which displays a list of open file handles by user. You would also want to set the ownership and privileges for it exactly as for lslk, even though it is not integral to A-Shell. A-Shell Reference Page 83 ## **SETTING UP UNIX LOGINS** The actual technique for setting up Unix logins varies among Unix flavors, and is outside the scope of this document. However, since many A-Shell users are used to a rather casual security atmosphere under AMOS in which there may have been no formal user definitions, it is worth discussing the basic strategies that are available here. The simplest strategy is to define a generic user (e.g. "ashusr" or just "user") and let everyone log in as that same user. If this lack of refinement doesn’t bother you, it doesn’t bother A-Shell. The only detrimental side effect is that SYSTAT will not be able to give you any useful clues as to who is who (unless they are all on serial connections and you recognize the port numbers.) It may be possible to overcome that shortcoming by setting the A-Shell user name within A-Shell based on some kind of application logic, but this strategy is not workable if you want to use Unix utilities such as mail, which depend on the user login to establish identities. At the opposite extreme is the traditional approach of setting up a separate Unix login for each real user, which offers advantages such as allowing SYSTAT to be able to display each user’s login name. The main down side to defining individual Unix logins is that it can be a lot of administrative work (if you have a lot of users.) However, most flavors of Unix provide some way of simplifying this (e.g. template user profiles, sharing of home directories, etc.) so it generally doesn’t require much more than assigning a login name and password for each user, letting the rest of the settings (group, home directory, shell, etc.) default to the template value. The other main complication with having individual user logins for each user is the security problem of not being able to send signals to each other, but the SETUID trick described in the previous section effectively works around that problem. A-Shell Reference Page 84 ## **MODIFYING THE USER .PROFILE** There are three or four minor modifications that usually need to be made to the .profile ("dot profile" or shell initialization) file for each user to set the necessary environment variables and optionally launch A-Shell automatically after login. All of this can be done interactively from the shell prompt each time a user logs in, but it is much cleaner to make it all happen automatically. On the theory that an example is worth more than just an explanation, a typical user .profile (in this case for the Korn shell under AIX) is shown below, with A-Shell modifications, followed by explanations. Note that your .profile will probably be different, but similar. ``` PATH=/usr/bin:/etc:/usr/sbin:/vm/miame/bin:/usr/ucb:$HOME/bin: ``` ``` MIAME=/vm/miame ``` ``` TERM=am62a ``` ``` export PATH MIAME TERM ``` ``` set +o monitor ``` ``` ashell main ``` ``` exit ``` In the PATH statement, we just added the A-Shell executable directory (/vm/miame/bin), so that users could execute **ashell** (or more importantly, **vue** ) from anywhere. You might argue that this is unnecessary in a turnkey system, since the only time users would ever launch **ashell** is from within this same file, in which case it would make just as much sense to call out the full /vm/miame/bin/ashell path on the last line. Similarly, even if you wanted to use the A-Shell **vue** editor instead of **vi** , you could always put a link to it in a directory that was already in the PATH, such as /usr/bin. However, adding it to the PATH is clearly preferable if you plan to go in and out of A-Shell many times. Note that the delimiter is the colon (:). It can also avoid a lot of confusion if you are having problems launching background sessions with XCALL ASHELL or SUBMIT, and it may be necessary for certain utilities such as KILL and LOKUTL, which in turn execute native Unix commands (ASHKILL and LSLK) which are expected to be in the PATH (and which are typically stored in the same directory as the **ashell** executable.. A-Shell Reference Page 85 `MIAME=/vm/miame` defines the environment variable MIAME, which is used by A-Shell to locate miame.ini. Again, you could get by without defining this variable since you can always specify miame.ini on the startup command (e.g. `ashell –i /vm/miame/miame.ini` ) TERM=am62a is shown here for those cases where the login script (specifically the TSET command) is not managing to set the TERM variable correctly. If you are using a known terminal type (am62a, am62c, am75, wyse50, hz1500, vt420) then it is essential that the TERM variable get set correctly to one of those names (using the spelling and case as given in the list above.) Otherwise, A-Shell will not recognize your terminal type, and will be forced to use the TERMINFO database, which is at best, not as good. Of course it is less than ideal to hard code your terminal type in your login script—it is much better to have the login routine prompt you—but this at least demonstrates the brute force approach. If you want to use the am62a emulation with Unix utilities (such as the vi editor) then you will need to define a TERMINFO entry for it. Since am62a is not a standard Unix terminal type, we provide a TERMINFO source, am62a.tis which you can add to your TERMINFO database with the following command (execute as root from the /vm/miame directory): # tic –v am62a.tis The export statement is needed to make the preceding environment variables visible to programs running outside of the shell (such as A-Shell). SET +O MONITOR is only needed when you are using PolyShell and a "job control" shell, such as the Korn Shell (ksh) or Born Again Shell (bash). It turns off the shell’s trapping of the job control signals so that PolyShell can use them itself. ASHELL MAIN launches A-Shell (assuming it is in the PATH and the MIAME environment variable defines the location of miame.ini) and tells it to execute CMD:MAIN (CMD or DO) as a startup command. If that command file brings up your main menu, and you want the user to go directly back to the Unix login prompt when exiting from your main menu, then add a HOST command at the end of your main.cmd file, as shown here: ``` :R ``` ``` LOG DSK1:[20,0] ``` ``` RUN MAIN ``` ``` HOST ``` A-Shell Reference Page 86 When HOST command is executed, the A-Shell session is terminated, returning execution control to the login profile script, where the next command to execute (based on the example above) is EXIT. This logs you out of Unix. Depending on the connection type, you may then go back into the Unix login prompt, or perhaps your Telnet connection window will close and disappear. Another way to force the A-Shell session to terminate after the program completes is to use the –e switch on the A-Shell command line. A-Shell Reference Page 87 ## **BACKSPACE KEY OPERATION** Within A-Shell, the BACKSPACE key on a PC keyboard should work just as you would expect the RUB key to work (backspacespace-backspace.) However, if you work at the Unix prompt with a terminal emulator, you may find that the backspace key terminates the command line. This can be very frustrating. To get the BACKSPACE key to work like you would expect (and to change the interrupt command from BACKSPACE to CTRL+C) try typing the following commands (or adding them to your profile.): ``` $ stty intr \^C ``` - `$ stty erase \^?` - `$ stty echo` A-Shell Reference Page 88 ## **ENABLING THE USE OF KILL.LIT** Because the normal Unix security rules do not permit one process to send signals to another (unless they both belong to the same user or the sender is the superuser), the A-Shell KILL.LIT utility invokes a command called ASHKILL rather than accessing the standard Unix KILL command directly. It is up to you to create the ASHKILL file according to the type of security you want for this potentially dangerous function. In most cases, the thing to do is to make a copy of the standard KILL executable called ASHKILL. (It is typically located in the /usr/bin or /bin directories.) To avoid mixing A-Shell files up with the operating system files, it is recommended that you put ASHKILL in the MIAME bin directory (e.g. /vm/miame/bin). If you only want the superuser to be able to use the KILL.LIT command, or if you have already set the SETUID bit on the A-Shell (as described above) so that every A-Shell JOB is effectively owned by the same user, then there is nothing else to do. Otherwise, if you want ordinary users to be able to execute KILL.LIT, then configure ASHKILL to temporarily give the user superuser privileges with the following commands: ``` $ su root ``` ``` ``` ``` # cd /vm/miame/bin ``` ``` # chown root ashkill ``` ``` # chmod +s ashkill ``` ## `# exit` Another option is to create a script called _ashkill_ that uses more sophisticated logic to decide whether the current user (perhaps on the basis of his logon identity) should be allowed to kill other users. A-Shell Reference Page 89 ## **AFTER INSTALLATION** After the formal installation is complete, as described in the preceding pages, there are a number of miscellaneous configuration and follow-up steps to be performed before the installation can be considered complete. These include reviewing and adjusting the miame.ini file, installing the security key, possibly transferring programs and data from another machine, etc. Instructions for these topics follow. ## **Subtopics** - Modifying MIAME.INI - Installing the Security Key - Transferring from AMOS - Folding Filenames to Lower Case - Selecting a Terminal Emulation - Running A-Shell - Log File Maintenance A-Shell Reference Page 90 ## **MODIFYING MIAME.INI** Before proceeding with installation of the security key, it is a good idea to review miame.ini to make sure that it references the proper local drives and directories. This is particularly necessary for A-Shell/Unix if you didn't install the software in the default directory. Refer to Configuration for more details, paying particular attention to the DEVICE parameter. Attempting to launch A- Shell with references to incorrect or non-existent paths in miame.ini is virtually guaranteed to result in confusion and mysterious symptoms. A-Shell Reference Page 91 ## **INSTALLING THE SECURITY KEY** A-Shell runs in one of two modes: licensed or demonstration. To run in demonstration mode, it is necessary only to install the software and run it; when prompted for the serial number, simply enter "0000." To run A-Shell in licensed mode, and thereby avoid the demonstration mode message, you need to enter three data elements: a serial number, a company name, and a security key (also called the "Product Installation Code" or "PIC"). This information is available from MicroSabio or your reseller, and is normally provided when you purchase your original or updated A-Shell license. - The serial number is a four-digit number. - The company name is not sensitive to case or to punctuation (spaces, hyphens, etc.), but otherwise needs to be entered - exactly as provided. - The security key (also called a "product installation code", or "PIC") is not case-sensitive, but is sensitive to punctuation and - spacing. It is a 29 character string which encodes information about the licensed company name, number of nodes, operating system, and other options such as ATE, PDFX, AXL, etc. The key is made up of numbers and letters only, plus three hyphens. Note: very old versions of A-Shell used a different key format than described here. To install or re-install the security key, see the next topic, Updating the License. ## **Comments** The security key is requested the first time A-Shell is invoked. For Unix, this is achieved by typing **ashell** at the host machine command prompt, assuming the necessary Environment Variables were defined. For Windows, you generally launch A-Shell by clicking on the icon. The key is stored in miame.ini, and re-validated each time you launch A-Shell. The company name is stored in a file referenced by the CONAME parameter within miame.ini (typically dsk0:coname.dat[1,4].) If either is invalid, it will give you the option of reentering it (which is useful for converting from demo mode to a proper license). You can force A-Shell to prompt you for a new key (which is necessary for updating your node license) by using the LICENS command from the dot prompt. The company name and security key are intimately related. This means that you cannot change the company name without impacting your A-Shell license. If your firm's name is Smith Jones & Wilson, and then Wilson leaves the firm, you _cannot_ simply A-Shell Reference Page 92 change the A-Shell company name so that it now displays Smith & Jones. If you do so, the license will fail and A-Shell will revert to demo mode. If you want to change the company name, you must contact MicroSabio or your reseller. Attempting to run more nodes than the key allows will result in a message similar to the following: ``` ?A-Shell 4-node license already in use ``` The number of nodes and all options are noted in the license banner that displays for a few seconds on startup. You can also view detailed information about the license from the dot prompt using the ABOUT command. Under A-Shell/Windows, you can also view similar information on the Help...About dialog box. Note that the definition of a "node" is slightly different for different operating systems. For A-Shell/Windows, a node is simply a PC, and any number of windows may be running A-Shell on each PC without using up node licenses. (In the case of Windows Terminal Server and Citrix, A-Shell attempts to determine when multiple A-Shell sessions originate from the same workstation, but this is not always possible.) Under A-Shell/Unix, generally each A-Shell session counts as a separate node. So a PC with a terminal emulator running two sessions over Ethernet for example would use up two node licenses. The exceptions to this are (1) that an A-Shell session can spawn another one with no penalty, and (2) all sessions running underneath a single instance of PolyShell count as a single node for licensing purposes. ## **Subtopics** - Updating the License - License Options - LICENS Error Codes - Troubleshooting Licensing Issues - What Expiration Means - Other License Matters A-Shell Reference Page 93 ## **UPDATING THE LICENSE** _Revised and Reviewed July 2020_ There are several reasons why you might need to update your A-Shell license: increase the numbers of licensed nodes, extend your software maintenance contract through a new date, add options, change company name, or change platforms. In all cases, make sure you have received clear and unambiguous license information before beginning. Having somebody tell you over the phone that the company name is "Smith and Company," for example, is likely to cause problems; is it Smith and Company? Smith & Company? Smith & Co, Inc.? J. SmithCo? It may not make a difference to you or Smith, but it does to A-Shell. To update the A-Shell license: - Log to the system operator account OPR: - Type LICENS followed by the ENTER key. There are two things that can happen at this point: either LICENS will run, or it will not, in which case A-Shell displays `?LICENS?` . If LICENS runs, then you need only to follow the prompts and enter your new or updated information. If it does not run, then this means that your version of A-Shell is very old and may no longer be supported; contact Microsabio to investigate. If LICENS runs as expected but the license info you enter is declared invalid, see the topics LICENS Error Codes and Troubleshooting Licensing Issues. ## **Comments** The company and license key fields are NOT case-sensitive. The "Maintenance Expiration" date will not prevent A-Shell from running unless you update A-Shell beyond your maintenance expiration date. If your expiration date is 15 January 2026, for example, and you install a new version of A-Shell on 16 January 2026 or after, A-Shell will revert to demo mode and require that you get an updated license. The basic rule is, don't update A- Shell unless your current maintenance expiration date is in the future. Information about the A-Shell license is also available with the ABOUT command, and from the _Help...About_ menu under A- Shell/Windows. A-Shell Reference Page 94 If the existing company name needs to be changed (it was misspelled, firm has a new name, you need to add "Inc.", etc.), you must simultaneously get a new security key from MicroSabio and change the company name on your system. Both the new key and the name company name can be entered by use of the LICENS command. A-Shell Reference Page 95 ## **LICENSE OPTIONS** Here is a complete listing of the options available in A-Shell. In order to be useable, each of these options must be enabled via the product key. |**Licens**
**e**
**Code**|**Full Name of**
**Licensed**
**Option**|**Description**| |---|---|---| |POLY|PolyShell|Permit multiple sessions from a single A-Shell node. Applies only in Unix environments, is
meaningless in Windows.| |ISMA|ISAM-A|Enables the use of the ISAMA (aka d-ISAM, aka ISAM-Plus) file system.| |ATE|A-Shell Terminal
Emulator|Allows telnet-connected PCs to create user sessions on Unix systems. Improves performance in PC
networks.| |ATS|A-Shell Telnet
Service Daemon|Implements telnet on PC. Is normally required for terminal connections under Unix, improves
performance in PC networks.| |PDFX|PDFX|Generates and post-processes PDF files.| |ASQL|ASQL|Provides connectors to SQL databases and thereby bi-directional data exchange with those
databases.| |AXL|A-Shell XLS|Provides a function library with which to read and create XLS/XLSX files—i.e., Excel and other| A-Shell Reference Page 96 |**Licens**
**e**
**Code**|**Full Name of**
**Licensed**
**Option**|**Description**| |---|---|---| ||Library|spreadsheets.| |EM|Expiration
Message|Causes alerts to pop-up as license expiration date nears.| |GRP|Group License|Allows the subdivision of an A-Shell license, thereby insuring that a given subgroup of A-Shell users
cannot use more than their allocated number of nodes.| |SNL|Strict Node
Licensing|Causes each foreground session to count against the license. Otherwise, sessions from the same PC
usually share a node.| |EFS|Encrypted File
System|Provides secure file encryption at a layer "below" programmer control, so programmer doesn't have
to deal with encryption issues.| |CGIX|CGI Exemption|Exempt CGI sessions from the license count, so as to permit a large and unknown number of
simultaneous CGI sessions.| A-Shell Reference Page 97 ## **LICENS ERROR CODES** When you run the licensing program LICENS to install a new license, the normal and desired result is a final response from the program saying "License Valid!" Given that things don't always work as expected, however, a "License Invalid!" response is not beyond the realm of possibility. If and when this happens, knowing WHY the new license data was rejected can be helpful. The table below shows the meaning of the error codes that may be shown in brackets immediately following the negative message. |**Error **|**Description**| |---|---| |2|Bad encryption key| |3|Bad company name| |4|No node license| |5|PolyShell not licensed| |6|Key applies to other platform| |7|License expired| |8|EXE date beyond end of maintenance license| |9|Key in old format| |10|ATSD not licensed| A-Shell Reference Page 98 |**Error **|**Description**| |---|---| ||| |11|Support use only| |12|MAC not valid| |13|Serial number too large, or invalid| A-Shell Reference Page 99 ## **TROUBLESHOOTING LICENSING ISSUES** _Reviewed July 2020_ The A-Shell license program and process has been in place for many years, and has never been shown to have a problem or to produce invalid results. If you having a problem, it is likely because either you or the person who provided the license has overlooked something. Here are some suggestions for finding the problem. ## **Confirm your license** If you are having trouble with any aspect of A-Shell (including ATE) licensing, the first thing to do it to make sure that your license is and says what you think it is. Use the following steps to check for discrepancies, oddities, unexpected results, etc. - Run ABOUT from the prompt. - If you are using A-Shell/Windows or ATE, check the _Help...About_ box for confirming info. - Run SYSACT from the prompt. - Run LICENS from the prompt while _not_ logged in to OPR: ## **- A Shell Version 6.2.1425** In February 2016, the A-Shell license key format was changed to xxxxxxx-xxxxxx-xxxxxx-xxxxxxx (seven characters, two sets of six characters, seven characters). If you are trying to use a key of that format in a version of A-Shell before 6.2.1425, that's the problem; it won't work. Please request another key in the "old" format. The format of the old key, by the way, in characters, is 4-4-3-6-8. Note also that the old style key was all lower case letters, whereas the new style is all capitals. ## **ATE Issues** Run ABOUT from the prompt; it will show the license options for the ATE aux license independently of the main server license. In addition, next to "ATE Licensing:" it will list "Client", "Auxiliary (aux.lic)", AND/OR "Server". If it lists "Client" in addition to one of the other two, that means that the ATE client supplied its own license, even though the server could have done so. (This could be the reason for the confusion between the features included in the server-based license and those in the client-based license.) Also note that in this case, the information displayed will be relative to the aux license, even though that won't necessarily be what the client is actually using. To check what the client is actually using for licensing, see Help > About on the ATE menu bar. A-Shell Reference Page 100 If you are using A-Shell/Windows or ATE, check the _Help...About_ box for confirming info. In the case of ATE, near the bottom, after "Additional license information:", it will indicate "(Server supplied)" if the license info came from the server. If it doesn't say that, then the information will be relative to the license which is local to the ATE client. A-Shell Reference Page 101 ## **WHAT EXPIRATION MEANS** _Reviewed July 2020_ One of the key data elements of the software license and key is the "maint. expir." date. The "maintenance expiration" date works like this: - Regardless of the expiration date, A-Shell will run properly; the maintenance expiration date has nothing to do with the - normal _running_ of A-Shell. A-Shell will keep running forever, regardless of the maintenance expiration date—unless you try to update, as explained in the following notes. - The expiration date has only to do with your ability to _update_ A-Shell. - As long as the expiration date has not passed—i.e., your software maintenance is "current"—there are no restrictions or - limitations on your ability to update A-Shell. - When the expiration date is in the past, then your ability to update is limited. The general rule is: don't update A-Shell if the - maintenance expiration date is in the past. More specifically, here is how that works: - When A-Shell runs, it checks its own release date against the maintenance expiration date. If the A-Shell date is newer than - the expiration date, then A-Shell will run, but it judges the software license to be invalid. An invalid license means that A-Shell will operate only in demo mode, which in turn means that only one user is permitted and annoying "nag" messages appear frequently. - Note that the comparison of the A-Shell date and the expiration date do not involve _today's_ date. In other words, it doesn't - matter when you perform the update; what matters are the dates of A-shell and the expiration date. ## **Practical Concerns** I just got a new A-Shell license. Must I install it? No. You _should_ install it, so that when you check the status of your A-Shell license, it shows the same date as your most recent authorized license. However, you don't _need_ to install it unless/until you are planning to update your A-Shell software. My license has a maintenance expiration date of 15 October 2019. Can I install the latest update? A-Shell Reference Page 102 No. The latest version of A-Shell is more recent that 15 October 2019. Therefore, if you install that update, the date of the A- Shell program will be more recent than your expiration date, and A-Shell will revert to demo mode. My license has a maintenance expiration date of 15 October 2019. What version of A-Shell can I install? - Anything with a release date before 15 October 2019. Check the A Shell History documentation, and determine what is the newest version of A-Shell that was released before 15 October 2019. You can install that version of A-Shell, or any one that is older. I accidentally updated A-Shell to a version that's newer than my license, and I'm now able to run only in demo mode. What do I do? Contact MicroSabio or the firm from which you bought A-Shell, and get an updated license. Once you install the new license, with an expiration date in the future, A-Shell will run in licensed mode. - If you are unable or unwilling to install an updated license, then you can try installing an older version of A-Shell. Check the A Shell History documentation, and install a version of A-Shell with a release date before the maintenance expiration date on your license. How to I check the maintenance expiration date? Get to the A-Shell prompt and enter LICENS or ABOUT. In A-Shell/Windows, you can also check _Help...About_ on the menu bar. A-Shell Reference Page 103 ## **OTHER LICENSE MATTERS** _Reviewed July 2020_ ## **Unfamiliar License Options and Terms** Although you will be familiar with most of the options that show up in your license, there are a few terms that may not be so familiar. LFS stands for Large File Support, referring to support for files larger than 2GB. This is not a pay-for feature (although perhaps it should have been). It appears as a "license option" just because it seemed like a handy place to put it. It is more precise to call it an attribute of the _build_ , as opposed to the license. Generally, all current versions of A-Shell support LFS, except perhaps the Windows "C" version. W32IO is a similar kind of thing - this is a build option, not a licensing option. It means that we're using the WIN32 I/O routines, as opposed to the standard "C" library I/O routines. VI(5.65.7) is a reference to the Victor Imaging library. That originally was a kind of licensing option (in that we did charge for it) but like the other two just described, doesn't relate to any bits in the actual PIC code. COM, an acronym for Microsoft's _Component Object Model_ , was an extra-cost option for A-Shell when it was introduced quite some time ago. It is no longer charged for, and may show up in both Windows and Linux licenses. Note that the COM interface is always enabled in A-Shell, and works regardless of whether "COM" is displayed with the license information. ## **- Exceed A Shell License** If you exceed your A-Shell license ("authorized nodes") by trying to log in when all available nodes are in use, you will be a message saying "node counted exceeded," and you will not be able to log in. ## **Exceed ATE License** If you exceed your ATE license authorization—i.e., you try to connect as the sixth ATE connection in a system where five ATE nodes are licensed—you will get a "nag" message but will be allowed to operate. ## **Group Licensing** A-Shell Reference Page 104 Beginning with A-Shell 6.3.1540 of December 2016, A-Shell provides an option for group licensing. This allows fine tuning of the license usage by providing a means of reserving and/or limiting the license usage relative to license groups. For example, in a fifteen user license, you can reserve two licenses for "admin" users, and/or limit the "remote" users to no more than five licenses. When group licensing is enabled, via an option encoded in the A-Shell license, A-Shell will call BAS:ASHUSR.SBX on startup. Contact MicroSabio for further specifications on how to implement the group licensing routine. In A-Shell 1785 of March 2025, the capabilities of the group licensing mechanism were expanded. Details are not documented due to possible security issues; contact MicroSabio if interested. A-Shell Reference Page 105 ## **TRANSFERRING FROM AMOS** If you are migrating from AMOS, A-Shell provides binary file compatibility with all of your data files and in most cases your program source code (*.bas, *.bsi, etc.) as well. The only files that must be converted are any ISAM PLUS files, which you must first dump using ISMUTL, and then use a binary transfer method to get the dumped file to the Unix or Windows box, where you can reload it using the A-Shell version of ISMUTL.LIT. Source files (BAS, CMD, DO) and other text files are binary compatible between AMOS and Windows. Under Unix, these files normally have line terminators of LF instead of CRLF, but since A-Shell can accept either format, the easiest approach is to just transfer all your files using the binary transfer method. The main down side of not using an ASCII or text transfer method to transfer your source files to Unix is that VUE will give you a warning that the file is in DevPPN format and will be converted. (You can, however, turn off the warning; see CVTWARN.) On the other hand, by not converting the line terminators from CRLF to LF, you preserve the hash code and size of the files, which allows you to verify the transfer results by comparing the hash codes using DIR/H and/or VERIFY which are implemented on both AMOS and A-Shell. RUN files compiled under AMOS should run as is under A-Shell. In most cases, you can recompile the source code and regenerate the identical RUN file, although this takes some care to use the right compiler switches. In most cases, however, it makes more sense to use the full range of ASB enhancements (see the COMPIL /x:2 and /px switches), which will result in RUN files which may work the same as before but are no longer compatible with the original AMOS RUN format. See VERSYS.LIT for a way to examine the RUN file compatibility level. Because of the difference in directory structures between AMOS, Windows and Unix, it is virtually impossible to do wildcard transfers of files involving multiple PPNs and devices. Instead, it will be necessary for you to manually specify the Unix or Windows path that corresponds to the PPN for each directory. (See the discussion of the DEVICE parameter of miame.ini for information on how PPNs are mapped to directories.) The only way around this with FTP transfers is to use an FTP package that allows programmatic scripting. A-Shell Reference Page 106 ## **FOLDING FILENAMES TO LOWER CASE** One additional consideration when transferring files to Unix is that the filenames must all be folded to lower case. If your PCbased FTP package does not support an option for this (a problem with the built-in W95 ftp.exe), then we advise getting one that does (such as ZTERM or WS_FTP Pro.) If that is not practical, or you forget and end up with thousands of files with mixed upper and lower case names, there is a utility script called **trlcs** in the /vm/miame/bin directory which will properly fold one or more filenames (based on a wildcard spec) in a single directory to lower case. It does, however, require that you execute the command in each of your directories. For example: ``` $ cd /vm/miame/dsk0/020001 ``` ``` $ trlcs '*' ``` ``` $ cd ../020002 ``` - `$ trlcs '*'` - `` (Note that if a wildcard specification is given, it must be quoted.) If for some reason you do not have the **trlcs** command, you can create it by typing in the following and then using CHMOD +X TRLCS to make it executable: ``` # trlcs: converts wildcarded files to lower case names ``` ``` if [ $# != 1 ] ``` ``` then ``` ``` echo "trlcs converts names of files in wildspec list to lcs" ``` ``` echo "usage: trlcs \047wildspec\047 (wildspec must be quoted)" ``` ``` else ``` ``` for f in $1; do ``` ``` mv $f `echo $f | tr A-Z a-z` ``` A-Shell Reference Page 107 ``` done ``` ``` fi ``` A-Shell Reference Page 108 ## **SELECTING A TERMINAL EMULATION** Under A-Shell/Windows, selecting a terminal emulation is usually a one-setting-fits-all affair. Typically one specifies the default driver PCTDVG in the CONSOLE statement in miame.ini and that’s the end of it. Under Unix, it can be a bit more complicated because you could be connecting from a variety of different types of terminal devices or terminal emulation software. Typically, Unix will attempt to establish the terminal type when you log in, either by querying the terminal directly, or by prompting the user. It then saves the terminal type in the TERM environment variable, which in turn, A-Shell queries to determine which terminal driver to use. If A-Shell does not recognize the terminal type as being one of those that it supports internally, it will use a generic terminal driver that works through the Terminfo database via the curses library. (This assumes that the terminal type is defined in the Terminfo database!) The generic driver is adequate for many applications, but it is not nearly as sophisticated as the drivers embedded into A-Shell. For example, it will not provide very good function key support, nor 132 columns, nor status line support. For this reason, we recommend that if at all possible, you use one of the following terminal types: |**TERM**
**type**|**Description**| |---|---| |aixterm|AIX window emulation.| |am62a|AM62A emulation. This is perhaps the most common in the AMOS world. Field attributes, monochrome.| |am62az*|ZTERM-enhanced version of AM62A. Use only with ZTERM 2000 build 144 or higher. Supports variable rows.| |am62c|Color version of AM62A.| |am62cg|ATE-enhanced AM62C| |am62cz*|ZTERM-enhanced version of AM62C. Supports variable rows.| |am65|AM65 emulation. Similar to AM62A, but uses mode rather than field attributes. Also supports 42 rows.| |am65g|ATE-enhanced AM65| |am65z*|ZTERM-enhanced version of AM65.| |am75|AM75 emulation. Essentially a color version of the AM65.| |am75g|ATE-enhanced AM75| A-Shell Reference Page 109 |**TERM**
**type**|**Description**| |---|---| |am75z*|ZTERM-enhanced version of AM75.| |cgi|Special pseudo-driver which is automatically set when running in CGI mode.| |dumb|Dumb tty (hard-copy style) terminal. Useful for running background tasks to avoid cluttering log file with terminal-
specific ESC sequences.| |h1500|Hazeltine 1500 emulation. Uses tilde as a lead-in sequence. Not recommended.| |vt220|VT220 emulation. This is often a reasonable choice for console devices that might otherwise use "ansi", "scoansi", or
"linux" terminal emulation.| |vt220a|(Linux only) Special version of vt220 emulation that uses no delay on the aux port commands. This is mainly of
interest to users of a particular proprietary emulation package.| |vt420|VT420 emulation. Supports both 7 and 8 bit versions.| |wyse50|Wyse 50 emulation. Similar to AM62A but does not support addressable status lines, certain smart box operations.| |wyse5g|ATE-enhanced Wyse 50.| |wyse5z*|ZTERM-enhanced version of Wyse 50. Supports variable rows.| |wyz50|(Linux only) Special version of Wyse 50 adapted from the original DOS version of ZTERM (by John Pruitt.) Requires
ersemu.dllto work with ZTERM.| The terminal type names stored in the TERM environment variable should always be in lower case. (A-Shell, like AMOS, confuses things by displaying the names in upper case when within A-Shell.) * The ZTERM-enhanced versions shown above all require ZTERM 2000 Build 144 or higher. In addition, you will have to manually set up the TERM environment variable, which you can do in one of two ways. One is to plug the "z" name into the Terminal Identity field on the Emulation tab of ZTERM’s configuration dialog (e.g. specify "am62az" or "wyse5z"). The other is to manually assign the TERM environment variable before launching A-Shell, such as TERM=am62az). Note that although ZTERM allows you to specify the number of display rows within its configuration screens, it is best to leave it at the default setting there and only change it from within A-Shell. Otherwise, your software will not be able to determine the current number of rows via A-Shell Reference Page 110 the TRMCHR subroutine. Too change the number of display rows, use SET TERM HEIGHT command or Set Number of Columns. VUE and EZTYP will allow you to toggle between 24 and 42-row display mode. You can also set the initial number of rows in the INI.CLR file; see Color Configuration. The ATE-enhanced versions shown above all require ATE (A-Shell Terminal Emulator). You can select the emulation in the ATE configuration dialog; it will automatically communicate that to the server, setting the TERM environment variable accordingly. The ATE enhancements include support for the main ZTERM ESCAPE sequences (for file transfer, etc.) as well as the full range of ATE functions. A-Shell Reference Page 111 ## **- RUNNING A SHELL** Once the software is installed, and the applications to be run have been loaded into the correct accounts, A-Shell is ready to run. Under Unix, type "ashell" at the host machine command prompt; under Windows, select the A-Shell icon from the Start menu or desktop icon. A-Shell will respond with its prompt, and you are free to enter any AMOS commands that have been defined. To terminate the A- Shell session, enter the command "host" at the A-Shell command prompt. - Refer to Launching A Shell for details on the command line options and other details of launching A-Shell (and PolyShell). See System Commands for details on the commands that can be entered from the A-Shell command prompt (aka the "dot prompt"). A-Shell Reference Page 112 ## **LOG FILE MAINTENANCE** A-Shell's primary log file—ashlog.log, typically in the %MIAME% directory—is self-maintaining. It rolls over to ashell.001, .002, .etc, up to a reasonable limit and then erases the older ones. But in the UNIX environment, it does create one continuously growing log file, OPR:SPOOL.LOG, which records details of submissions to the system print queues. Depending on how much printing your application performs, you may want to set up a cron job to execute every so often to roll it over. See LOGROLL for a handy command for this purpose. A-Shell Reference Page 113 ## **CONFIGURATION** This section and the two following, System Parameters and Printer Configuration, serve as references to the configuration files and settings which are critical to successful operation of A-Shell. You should browse through this material, immediately before or after installing A-Shell, to get a sense of what kind of options exist. Later, you will probably use this as a reference document to get precise details on specific system parameters that you want to change. ## **Subtopics** - MIAME Environment Variable - A-Shell Configuration File - Color Configuration - Help Menu Links A-Shell Reference Page 114 ## **MIAME ENVIRONMENT VARIABLE** The first thing A-Shell does upon being launched is look for its main configuration file. By convention, the configuration file is called miame.ini, though in keeping with the Unix convention, the filename is given in lower case, ("miame.ini") on both Unix and Windows system. Unless overridden via a command line switch, the location of the configuration file is given by the MIAME environment variable. This variable is generally defined in a system configuration file, such as AUTOEXEC.BAT or /etc/profile, though may be defined at any stage using the appropriate system command, as shown in the following examples: ``` MIAME=/vm/miame; export MIAME (Unix) ``` The actual pathnames used may be changed of course, but it is recommended that the MIAME directory is made a subdirectory of **/vm** (to enable multiple virtual A-Shell machines to be configured), and the parent of the directories which correspond to the devices where the application files are stored. A-Shell itself allows the location and name of the configuration file to be overridden with the **-i** switch. This is particularly useful, and is standard procedure, for A-Shell/Windows, since it enables a desktop icon in the program manager to be configured with properties to auto-start A-Shell without the need to set an environment variable in AUTOEXEC.BAT or elsewhere. For example: ``` ashell -i /vm/miame/miame.ini (Unix) ``` ``` c:\vm\miame\bin\ashw32.exe –i c:\vm\miame\miame.ini (Windows) ``` If the location of the configuration file is given by the MIAME environment variable, then the file must be called miame.ini. If it is given via the **-i** switch, then it may have any valid filename. A-Shell Reference Page 115 ## **- A SHELL CONFIGURATION FILE** The System Parameters which define and configure the A-Shell operating environment are specified in the main A-Shell configuration file, which is normally called miame.ini. This is a standard text file that must be edited with VUE or another text editor to make changes. Each line of the configuration file is in the form of an equation defining a particular system parameter. Some of these are so critical that A-Shell cannot run at all without them, while others are more for fine-tuning the system or achieving better compatibility with a particular application. A typical A-Shell configuration file is shown below. Note that anything to the right of a semicolon (comment marker) is ignored. ``` SERIAL=3401OJGI-6280-BNJ-400695-L1109B ; Serial # and key ``` ``` CONAME=C:\VM\MIAME\CONAME.DAT ; Licensee file ``` ``` FILES=40,40 ; 40 files, 40 ISAM ``` ``` ERSATZ=C:\VM\MIAME\DSK0\001004\ERSATZ.INI ; Ersatz defs ``` ``` LANGUAGE=C:\VM\MIAME\DSK0\001006\ENGLSH.LDF ; Language defs ``` ``` CONSOLE=NETUNIQUE,PCTDVG ; Console device ``` ``` ;Device definitions ``` ``` ;Use this format for an individual ppn ``` ``` DEVICE=DSK0:[1,4] C:\VM\MIAME\DSK0\001004\ ; Individual ppn def ``` ``` ;Use this format for logical disks with implicit \###### ppns ``` ``` DEVICE=DSK0 C:\VM\MIAME\DSK0\ ; Pathname for DSK0: ``` ``` ;Subroutine aliases (alias-name:ashell-name) ``` ``` ALIAS=INPUT:INFLD ``` ``` ALIAS=SPOOL:EZSPL ``` ``` SBR=CCYY:50,MALLOCSORT ``` A-Shell Reference Page 116 ``` LOKSER=ON ; LOKSER; ISAM sequence checks PRINTER=LP0 ; Set printer default to LP0 MEMORY=500K ; A-Shell memory partition ``` ``` QUEUE=100,DISK:C:\VM\MIAME\QFLOCK.SYS ; Q blocks ``` The file is processed only at the start of an A-Shell session, so for any changes to it to take effect it is therefore necessary to exit A-Shell and start a new session. Under Windows, the install program will configure your initial miame.ini to match your install directory, allowing you to at least launch A-Shell with no manual configuration changes. Under Unix, however, you will need to adjust miame.ini manually before - Launching A Shell for the first time, unless you installed it in the default (/vm/miame) directory. You can embed system environment variables in any of the filespecs in miame.ini by using the %ENV-VAR% notation. Some examples: ``` CONAME=%MIAME%/coname.dat ``` ``` DEVICE=TMP0:[1,1] %TMP%\ ``` See System Parameters for detailed information on the individual parameters specified within the A-Shell Configuration File. The ini file also permits an optional [MIAME] section header at the top, thereby making it easier to use standard INI-processing routines, including INIXxs for updating it. A-Shell Reference Page 117 ## **COLOR CONFIGURATION** Color configuration is an entirely optional step, and may be skipped without penalty. Although application programs have the ultimate control over the colors that appear on the screen, for applications that do not assume such control, it is possible to customize a number of aspects of the color display by configuration a color initialization file. When A-Shell launches, it checks if the file DSK0:INI.CLR[7,0] exists, and if so, processes it. If you update the file, or wish to experiment with different color configurations, you can force a new color initialization file to be processed using the SET command (SET TERM COLORINI ). |**Setting**|**Description**| |---|---| |VUECLR|Allows you to set up the color scheme used by VUE.| |EZCLR|Defines the color scheme used by EZSPL (and EZTYP/EZVUE).| |INFCLR|Defines the color scheme used with INFLD.| |SCNCLR|Defines the initial color scheme to be used when A-Shell launches. The default is 6,0 (green on black).| |MMOCLR|Defines the color scheme used with INMEMO.| |SCNSIZ|Defines the initial number of rows and columns.| ## **Example** A typical INI.CLR file is shown below. Note that lines that start with semicolons are ignored (comments). The numbers correspond to the color numbers which may be used in the SET TERM FCOLOR # and SET TERM BCOLOR # commands (or in the TAB(-2,x) and TAB(-3,x) print statements). Note the embedded comment lines that explain the color numbers and the various statement parameters. - `; Color Definition File` - `; Color legend: 0=blk, 1=wht, 2=blu, 3=mag, 4=red` - `; 5=yel, 6=grn, 7=cyn` A-Shell Reference Page 118 - `; VUECLR=override?,edit fg,edit bg, command fg,` - `; command bg, help fg, help bg,` - `; status/info fg,bg` ``` VUECLR=Y,6,0, 5,0, 7,0, 1,0 ``` - `; EZCLR=override?,text fg,bg, border fg,bg` - `; cmd fg,bg, sts fg,bg, help fg,bg,` - `; highlight fg,bg, menu fg,bg, brief menu fg,bg` ``` EZCLR=Y, 6,0, 6,0, 5,0, 0,9, 1,3, 3,6, 5,0, 7,0 ``` - `; INFCLR=override?,display fg,bg, edit fg,bg` - `; negative fg,bg, update fg,bg,` - `; message fg,bg, original msg line fg,bg, forms fg,bg` ``` INFCLR=Y, 1,0, 5,0, 4,0, 7,0, 5,0, 6,0, 9,0 ``` - `; MMOCLR=Y,border fg,bg, text fg,bg, arrows fg,bg, prompt fg,bg,` - `; status line fg,bg, protected fg,bg` ``` MMOCLR=Y, 6,0, 7,0, 5,0, 5,0, 5,0, 10,0 ``` - `; SCNCLR=override?,screen text (fg), screen background` - `; The following sets up magenta on black` ``` SCNCLR=Y,3,0 ``` - `; SCNSIZ=rows,cols` ``` SCNSIZ=18,60 ``` A-Shell Reference Page 119 Most of the lines begin with an "Override?" option. When set to Y, the color scheme defined on that line will override the default color scheme normally used for that function, or the one which a program has specifically asked to use. Setting it to N is nearly the same as commenting out the line entirely, except for situations where no other color scheme had been set up or specified for that function. You may set any color number to –1 to indicate that it should use the color which happens to be current at the time the function begins. (Setting all of the numbers to –1 will effectively defeat any color changes within the function.) Also note that making the foreground and background numbers in any pair the same effectively makes that text impossible to see. This is generally a very bad idea, except in some isolated cases. For example, some people don’t like the status line information displayed by EZTYP; you can eliminate it by setting the status line pair of the **EZCLR** line to 0,0 (black on black). A-Shell Reference Page 120 ## **VUECLR** The VUECLR line allows you to set up the color scheme used by VUE. The first pair of numbers defines the foreground and background colors used for the editing display. The second set defines the colors used in command mode. The third set defines the colors used with for HELP displays. And the fourth pair defines the colors used for status and other information displays. In the example above, this would be green on black for the display mode, yellow on black for the command mode, cyan on black for the help displays, and white on black for the status displays. A-Shell Reference Page 121 ## **EZCLR** The EZCLR line defines the color scheme used by EZSPL (and EZTYP/EZVUE). The concept is the same as that for VUECLR except the color pairs refer to the EZTYP display mode ("text"), graphic line drawing characters used for borders, command mode, status line, help (pop up) display, highlighted search strings, printer selection menu mode, and the brief version of the printer selection prompt/menu. A-Shell Reference Page 122 ## **INFCLR** The INFCLR line defines the color scheme used with INFLD. The pairs refer to display of data (without editing), editing mode, negative numbers (red), the redisplay of a field after it has been edited, the message line (bottom line of screen), the original color of the message line (so it can be returned to its original state), and the color used for forms characters. Note that applications have the option of specifying all of these colors explicitly for each field edited or displayed. If you set the "override" field to Y, this will override any colors specified by the application. However, if the application does not specify colors, then it is not necessary to set override to Y. (In other words, if you set the override option to N, it will only override the color scheme on fields for which the application did not establish its own color scheme.) A-Shell Reference Page 123 ## **MMOCLR** The MMOCLR line defines the color scheme used with INMEMO. Here the pairs refer to the color used to draw the border around the memo, the color of the text within the memo, the color of the navigation arrows (which display on the border), the color of the prompts (top and bottom titles), the color of any status messages, and the color of protected text. Note that these colors also apply to the PCKLST subroutine and any other utility which internally uses INMEMO. The comments about the override field given above for INFCLR apply here as well. A-Shell Reference Page 124 ## **SCNSIZ** The SCNSIZ line defines the initial number of rows and columns. The default is 24 by 80. Under Windows, rows may range from 1 to 50, and columns may range from 1 to 160. Under Unix, it depends on the capability of your terminal emulator. In most cases, you will be limited to 24 by 80 or 24 by 132. In the case of ZTERM (Build 144 or higher), the number of rows may vary from 1 to 50. A-Shell Reference Page 125 ## **HELP MENU LINKS** The contents of the A-Shell/Windows Help menu are easily configurable. It is recommended that you take a minute to set up documentation and other help links appropriate for your type of installation. Configuration is accomplished via the text file ashelp.mdf, which is installed into the DOC subdirectory. A sample copy of the file, as it is included with A-Shell, is shown below. The documentation set-up step is entirely optional; the presence or absence of documentation files will not affect the operation of A-Shell. If the documentation files are missing, or if the set-up file ashelp.mdf is damaged or contains invalid data, or even if the entire documentation folder/directory is missing, A-Shell will run without problem—although also without, of course, documentation. ``` ;This file sets up the selections on the A-Shell Help menu. ``` ``` ; ``` ``` HELP,"h1",SEP ``` ``` HELP,"&A-Shell Reference",REG,"http://www.microsabio.net/dist/60rel/doc/conref/00ashref.htm" ``` ``` ; ``` ``` HELP,"&Release Notes",REG,"http://www.microsabio.net/dist/60rel/doc/ashdevnotes/00ashdevnotes.htm" ``` ``` ; ``` ``` HELP,"h2",SEP ``` ``` ; ``` ``` HELP,"A-Shell &Documentation Home",REG,"http://www.microsabio.com/documents.html" ``` ``` ; ;Add your app's docs here... ``` ``` HELP "h3",SEP ``` A-Shell Reference Page 126 The above ashelp.mdf produces the following _help_ menu: The lines that start with semicolons are comments and are ignored. The first field on each line (HELP) indicates that it applies to the Help menu. The second field indicates the text that will appear in the menu item, unless the menu type (third field) is "SEP" (i.e. separator), in which case the second field just needs to be a unique string used internally for identification. The third field indicates the type of menu item. The most likely choices are SEP (separator) or REG, which means that the file or URL in the fourth field will be launched according the Windows file-type association in the Registry. The fourth and last field is the document file or URL to be launched. If it is a file spec, you must include the complete path, unless it is in the DOC subdirectory (where the ashelp.mdf file itself is located.) You can (and are encouraged to) edit this file, using any text editor. In addition to removing or commenting out links that you don't want, you can add links for your own application documentation, as well as any links to sites frequently referenced by A- Shell users, such as government, shipping, legal, search, dictionary, etc. A complete listing of available A-Shell documentation is always available from the A-Shell web site on the downloads...documents page. A-Shell Reference Page 127 ## **SYSTEM PARAMETERS** Following is a list of the A-Shell system parameters, also known as directives. These are terms that are used as verbs in the A- Shell configuration file, miame.ini. All lines except comments must begin with one of these directives followed by an equals sign. They are listed here in alphabetic order, and may appear in any order within miame.ini, except for SERIAL, which must be the first non-comment line of the file and is therefore listed first in the following table. See Boolean Arguments in Ini Files if needed. |**Parameter**|**Description**||**Parameter**|**Description**| |---|---|---|---|---| |SERIAL|Define A-Shell serial number||LOKSER|Specify LOKSER operation| |ALIAS|Specify A-Shell subroutine aliases||MALLOCLIMIT|Specify limit on dynamic memory allocations| |ALTRUNEXT|Define alternate RUN extensions||MAPIDA|Enable/disable ISAM Plus extension mapping| |ALTSBXEXT|Define alternate SBX extensions||MAXINST|Specify max A-Shell instances per workstation| |ATETIMEOUT|Set the ATE timeout period||MAXJOBS|Specify maximum number of jobs total| |CHARSET|Specify A-Shell character set||MAXLOCKS|Specify max locks to track for LOKSER| |COMPRGEXT|Define additional files that can be executed||MEMORY|Specify A-Shell memory partition| |CONAME|Specify location of licensee name file||MMAPLIST|Specify files to be automatically memory mapped| |CONSOLE|Define console device format & default driver||NOTRACE|Disables specific XCALL traces| A-Shell Reference Page 128 |**Parameter**|**Description**||**Parameter**|**Description**| |---|---|---|---|---| |DEVICE|Map devices to host machine pathnames||OPTIONS|Set miscellaneous A-Shell options| |EFSEXT|Specify extensions to be encrypted.||POLYKEY|Define PolyShell hot key| |ERSATZ|Specify ERSATZ definition file||PRINTER|Define default printer name| |FILES|Specify A-Shell FILE buffers||QUEUE|Specify A-Shell queuing system| |FKEYWAIT|Specify delay following function key lead in||QUITKEY|Define or disable Unix QUIT key| |FLDATTR|Enable/disable field attributes||SBR|Tune operation of A-Shell subroutines| |FONT|Specify A-Shell font face (Windows only)||SSD|Define returned SSD sequence| |IATIMEOUT|Define idle timeout||SWAPKEY|Define PolyShell swap key| |IJCFREQ|Define frequency of IJC clock||SWAPWAIT|Specify delay after screen swap| |INCLUDE|Include specified file||TRACE|Activate debugging options| |JOBPREFIX|Specify jobname prefix for auto-named jobs||TRMDEF|Define terminal characteristics| |LANGUAGE|Specify language definition file||UMASK|Specify default file creation mask| A-Shell Reference Page 129 |**Parameter**|**Description**||**Parameter**|**Description**| |---|---|---|---|---| |LOGDIR|Specify location of ashlog.log file||XONXOFF|Enable or disable XON/XOFF protocol| A-Shell Reference Page 130 ## **SERIAL** ## **SERIAL= Security key** The SERIAL directive must be present in order for A-Shell to run. In older versions of A-Shell, SERIAL had to be the first line of the initialization file except for comments. While that is no longer true, it still is normally the first line of the ini file. If the security key field is set to _DEMONSTRATIONXX_ , then A-Shell will operate in demonstration mode. If the field is set to _XXXXXXXXXXXXXXX_ , then the first time A-Shell is invoked, then the security key will be requested: ``` A-Shell Serial Number: ``` ``` A-Shell Serial # nnnn security key: ``` ``` Company name: ``` You should then enter the serial number, security key and company name as received with the A-Shell software license. This key will then overwrite the SERIAL line in miame.ini. An incorrect security key will cause A-Shell to operate in demonstration mode. Use the LICENS command from the A-Shell prompt to force A-Shell to prompt for a new security key. The security key and company name must match. Case and punctuation of the company name are not important. Note that the SERIAL line in miame.ini can be replaced with an `INCLUDE=` line, where is the full native filespec of a file which contains SERIAL. This feature allows sites supporting multiple A-Shell installations to maintain just one miame.ini for _all_ the installations, while storing the one thing that is unique—the SERIAL specification—in a separate file. A-Shell Reference Page 131 ## **ALIAS** _Rewritten May 2024_ ## **ALIAS=oldsbr:newsbr** The ALIAS directive allows you to redirect Xcall _oldsbr_ to Xcall _newsbr—_ i.e. to treat _oldsbr_ as an alias for _newsbr_ . An example of this in nearly every A-Shell installation is SPOOL being aliased to EZSPL via the following: ## `ALIAS=SPOOL:EZSPL` (EZSPL is an enhanced, upward compatible version of the original SPOOL subroutine. Rather than implement both variations separately, A-Shell includes only EZSPL and redirects Xcall SPOOL to Xcall EZSPL via this alias method.) ## **Comments** The maximum number of ALIAS directives is 50. The _oldsbr_ and _newsbr_ names must be six or fewer characters. The ALIAS scan occurs only once per {V}Xcall statement, i.e. the _newsbr_ name is not re-scanned for another ALIAS match. So if you have `ALIAS=A,B` and `ALIAS=B,C` the statement `Xcall A` will redirect to B (not C), but `Xcall B` will redirect to C. If _newsbr_ and _oldsbr_ are the same, then the ALIAS effectively redirects the call from the internal/embedded subroutine to the external (SBX) version. See History below. ALIAS applies to VXcall as well as Xcall, and to internal subroutines as well as external (SBX) routines—again, provided the names are six or fewer characters. ALIAS can be used to effectively disable a subroutine by redirecting it to a subroutine that does nothing such as PRIV. The ALIAS mechanism only makes sense if the two subroutines have compatible parameter lists. If you need a subroutine which is similar to one we already offer but with different parameters, you can probably create your own SBX version as a wrapper to the existing one. See SBX Subroutines for details on writing your own subroutines. A-Shell Reference Page 132 To add functionality to an existing internal Xcall subroutine via a wrapper, you can use ALIAS to redirect calls to an SBX of a different name (the wrapper), and then within that SBX you can Xcall the original internal subroutine via a second ALIAS. For example, to create a wrapper for an internal subroutine A, you might start with `ALIAS=A,AX` and `ALIAS=AY,A` so that Xcall A is redirected to AX.SBX. Within your AX.SBX wrapper you can then call the original embedded A subroutine via `Xcall AY` ,relying on the second ALIAS to redirect `Xcall AY` to the original A subroutine, and the fact that the ALIAS table is only scanned once per Xcall so the redirection from AY to A is final. ## **History** - 2024 May, A Shell 7.0.1759.1: Support the case where _oldsbr_ and _newsbr_ are identical to replace an internal subroutine with an external SBX version under the same name. Previously this would have done nothing. A-Shell Reference Page 133 ## **ALTRUNEXT AND ALTSBXEXT** _Added January 2019_ ## **ALTRUNEXT=** ## **ALTSBXEXT=** The keys ALTRUNEXT and ALTSBXEXT define, respectively, alternate RUN and SBX extensions. Each of the above keys takes a single 1-3 character extension, which is automatically added to the internal COMPRGEXT list, as well as to the relevant search path, where it will be found BEFORE the corresponding standard extension in each directory of the search path. The intended usage is to define extensions for test or 'beta' modules that can be easily deployed and removed without overwriting the stable RUN and/or SBX modules. For example, assume we have the following in miame.ini: ``` ALTRUNEXT=RNX ``` ``` ALTSBXEXT=SXX ``` After deploying a release of your package (mixture of RUN and SBX modules), you might later need to fix or enhance a particular program. To avoid affecting the stable version while working on it, you can add the pragma `++PRAGMA FORCE_EXT "RNX"` (or "SXX" for a subroutine) to the source so that the compiled version will have the specified alternate extension. When the alternate version is placed into the same directory where the production version resides, the ALTXXXEXT definition will cause it to be loaded in preference to the standard production version, allowing you to easily test the new version. If you decide there is a problem, just erase the new version, which will cause A-Shell to resume using the standard version. Otherwise, you can rename the test version to replace the production version. ## **Notes** - For each directory in the program search path (e.g. [p,pn], [p,0], BAS: ), it will check first for the alternate extension, and - only if not found will it check for the standard extension. If neither is found, then the search continues with the next directory in the search path. A-Shell Reference Page 134 • The alternate extension search logic only applies when then extension is not explicit in the command, e.g. would not apply to `RUN FOO.RUN` or `RUN FOO.RNX` or `VXCALL "FOO.SXX"` . • Defining an alternate extension does incur some overhead due to the need for additional directory lookups, so is not recommended unless you actually intend to use the feature. The overhead, however, is likely to be fairly insignificant, except perhaps in cases where you have very large directories. • For subroutines, the alternate extension will be cached just like the standard extension, and subject to the same automatic refresh logic which insures that the version in memory gets updated or removed when the corresponding version on disk does. The one difference between the behavior of a subroutine with the alternate extension and one with the standard SBX extension is that the alternate version cannot be manually loaded from a non-standard directory (e.g. `LOAD MYDEV:FOO.SXX` ). The problem here is that the automatic refresh logic, after not finding the corresponding module on disk in the search path, will conclude that it has been deleted and thus will remove it from memory and revert to using the standard version. • If in doubt about which RUN module version was actually loaded, you can activate the FOPENS trace (e.g. SET TRACE FOPENS ON), which will trace the load operations in the ashlog.log file. For example you will see something like this: ``` OpenFile1: C:\VM\MIAME\DSK0\150277\FOO.RUN, fh=-1, err=2 [214 us], ... ``` ``` OpenFile1: c:\vm\miame\DSK0\150000\foo.run, fh=-1, err=2 [355 us], ... ``` ``` OpenFile1: c:\vm\miame\DSK0\007006\foo.rnx, fh=716, err=0 [371 us], ... ``` The above indicates that it first tried foo.rnx and .run in [150,277]; the RNX lookup might not be traced if the file isn't present. The another unsuccessful attempt in [150,0], and finally it finds foo.rnx in DSK0:[7,6]. • For subroutines, use the subroutine trace ( `SET TRACE XCALL ON` ) for a similar trace, e.g. the following traces a subroutine TSTSBX statement, first checking for both the alternate and standard extensions in [150,277], before finding the alternate extension in [150,0]... ``` xcall TSTSBX,S7[BONJOUR] ``` ``` OpenFile1: c:\vm\miame\DSK0\150277\tstsbx.sbx, fh=-1, err=2 [264 us],... ``` ``` OpenFile1: c:\vm\miame\DSK0\150000\tstsbx.sxx, fh=872, err=0 [86 us],... ``` A-Shell Reference Page 135 ``` Executing c:\vm\miame\DSK0\150000\TSTSBX.SXX ... ``` • For subroutines, you can also use the MAP statement after running the program to see the names and extensions of the cached routines, although that won't indicate the locations from where they were loaded. ## **History** - 2019 January, A Shell 6.5.1654: Function added to A-Shell A-Shell Reference Page 136 ## **ATETIMEOUT** _Added December 2014_ ## **ATETIMEOUT=** ATETIMEOUT allows you to change the default ATE command/response time out from the standard 7500 milliseconds to something else. Depending on your network, you may find that 7500 is too low, producing spurious timeout conditions, or too high. ## **History** - 2014 December, A Shell 6.1.1399: Function added to A-Shell. A-Shell Reference Page 137 ## **CHARSET** ## **CHARSET=** ``` Examples: CHARSET=US ``` (Windows only) CHARSET is used to specify the character set used by the application, per the table below. Note that the CHARSET options may be abbreviated to the characters shown in parentheses in the table, but they must be in upper case. |**CHARSET**|**Notes**| |---|---| |US|(Default) Standard ASCII.| |UK|British national replacement character set. The # or £ keys return
ASCII character 35, and character 35 is always displayed as £.| |FRENCH (FR)|French AZERTY| |GERMAN (GER)|German| |PORTUGUESE
(PORT)|Portuguese| |SPANISH (SPA)|Spanish| |SWISS|Swiss| |ITALIAN (ITAL)|Italian| |DANISH (DAN)|Danish| |SWE-FIN|Swedish/Fin| |LATIN1|Use 8 bit Latin1 characters. (All of the non-ASCII characters
referenced above would need to be specified as 8 bit values in the
range of 128-255.) Equivalent to OPTIONS=LATIN1.| A-Shell Reference Page 138 CHARSET is related to, but not the same, as the symbol set parameter on the FONT directive (which see). The font symbol set is mainly of internal significance to A-Shell, while the character set specified with CHARSET must match up with the way your application encodes non-ASCII characters. It is highly recommended that you use the 8 bit LATIN1 character set for displaying non-ASCII characters, rather than one of the 7 bit national replacement character sets, since Latin1 is much more portable and standard under Windows. In order for any of the character set choices above, other than US and LATIN1, to be effective, you must specify the OEM symbol set in the FONT directive. The CHARSET directive replaces the special terminal driver names previously used with the CONSOLE directive (which see) to specify national replacement character sets. That is, setting the terminal driver to PCUK (rather than PCTDV) has no effect; you must instead specify `CHARSET=UK` . A-Shell Reference Page 139 ## **COMPRGEXT** _Added January 2019_ ## **COMPRGEXT=** COMPRGEXT defines additional file extensions recognized as compiled programs. The list of extensions must be comma-delimited, with no spaces or other characters. The specified extensions are added to the built-in list (RUN, SBX,LIT) which is used by the file loader to determine whether the file needs to be set up for execution. Files with extensions not in the list are treated as raw data and will not be runnable. The maximum length of the RUNEXT list, not including the built-in extensions, is 64 characters. Note that adding extensions to the COMPRGEXT does not automatically add them to the program search path. It only makes it possible to run them with an explicit command (e.g. `RUN TEST.RNX` ). Note that for subroutines, it is not possible to specify explicit extension in the XCALL statement, but it is possible to do so with the VXCALL statement, e.g. `VXCALL "FOO.SXX", ARG1` . SP SP See ALTRUNEXT / ALTSBXEXT . ## **History** - 2019 January, A Shell 6.5.1654: Function added to A-Shell A-Shell Reference Page 140 ## **CONAME** ## **CONAME= filespec of company name file** The CONAME directive specifies the name and location of the file containing the A-Shell licensee name. On installation of A-Shell, the security key field is tied to a specific company name (the licensee company), which is stored in the file specified in the CONAME directive in miame.ini. This is done by prompting for the licensee when entering the security key after A-Shell is run for the first time: ## `A-Shell Licensee (company name):` The location of the coname file is specified in terms of its native operating system (e.g. c:\vm\miame\coname.dat) rather than in DevPPN format. You may, however, place it in a directory which also maps to a PPN to allow easy access from within A-Shell. For example, applications may read this file as a form of copy protection, since, although it is a straight text file, alteration of its contents will cause A-Shell to operate in demonstration mode. Since the CONAME file must be shared by all users on a network, it must be placed on the server, and referenced either via a mapped drive letter or a UNC (\\server\share\path\coname.dat) name. A-Shell Reference Page 141 ## **CONSOLE** _Reviewed and revised, July 2020_ ## **CONSOLE={,drivername}** CONSOLE establishes an internal identifier for the instance, and optionally a terminal driver. Over the years is has devolved to become a nearly bottomless pit of complexity and confusion, but fortunately, in 99% of the cases, you can just set it to the following: ``` CONSOLE=NETUNIQUE, ; windows networks ``` The parameter should be either PCTDVG or PCTDV, with the only difference being that the PCTDVG version implements certain GUI improvements, such as the conversion of text message boxes to Windows dialog boxes. Historically, certain national replacement character set variations of the terminal driver were supported, such as PCUK and PCFR. This function has been taken over by the CHARSETSP directive. The NETUNIQUE option on the CONSOLE directive generates a unique identifier for each A-Shell session, made up of the computer name, followed by a colon and a numeric suffix indicating the instance number. The computer name may be set via the Windows Control Panel, using the Networks applet under W9x and the System applet in subsequent versions. Other options exist, but are for all practical purposes obsolete now. You can see these identifiers with `SYSTAT/C` . You can also retrieve your own identifier with the subroutine GETUSN. If you establish meaningful computer names, then these console identifiers are probably more useful than AMOS-style job names. But since job names are so embedded in ASB applications, A-Shell also generates them using the TSKAAA, TSKAAB, etc. format. If you don't like the dynamically generated job names, you can override them by using the `j ` command line switch, or you can create a cross-reference association between console identifiers and job names using TRMDEF statements. Because the console device name is used by the TRMDEF parameters, the CONSOLE statement must occur before any TRMDEF specifications. ## **History** A-Shell Reference Page 142 - 2015 May, A Shell 6.1.1408: Windows enhancement: A-Shell now detects duplicate machine names. Previously, this would have led to the nth instance on machine 2 overwriting the JOBTBL record for the nth instance on machine 1. In order for this to work, you must run the installer/updater to update each workstation, rather than manually installing the update by copying files. It is also important to update the six system commands, described in the next topic, although the installer will normally take care of this for you. The installer/updater establishes a unique identifier for each machine and saves it in the HKLM section of the registry, to be used to determine whether an instance with the same machine name as an existing instance is actually the same machine or not. If so, then the new instance can safely overwrite the old one. But if not, an error message is displayed and the new session is not allowed to start. The error message will indicate the machine name, the user name and jobname of the offending existing instance, and the unique identifiers (8 hex digits) for the two machines. You can use the `SYSTAT/CU` switch to display the unique identifiers for existing sessions, which may be helpful in tracking down the offending duplicate-named machine. Note that duplicate named machines can cause all kinds of problems for Windows networking, but it is not always detected. This feature should help avoid the ensuing problems in both A-Shell and in the network in general. Also note that the issue only affects P2P networks; ATE, Terminal Server, and Unix systems are not subject to the problem and are not affected by the update. A-Shell Reference Page 143 ## **DEVICE** _Revised August 2025_ ## **DEVICE=devn basedir/** ## **DEVICE=devn:[p,pn] dir/** ## **DEVICE = devn:[] dir** The DEVICE directives allow you to map DevPPN filespecs to Unix- or Windows-style directories. The _devn_ part of the DevPPN filespec (known as the "logical disk") consists of a three or four alphabetic character device name, followed by a one to three digit unit number, up to a maximum combined length of 6 characters (e.g. DSK0 or BACK99). The _p_ and _pn_ components are each one to three digits, ranging from 1-999 for _p_ and 0-999 for _pn_ . Note that although the the DevPPN logical disk is by convention all upper case, in actual usage, DevPPN filespecs are entirely case INsensitive; XYZ37:MyFile.DAT and xyz37:myfile.dat are equivalent.) The case sensitivity of the _basedir_ or _dir_ , on the other hand, depends on the host operating system, but by convention is typically all lower case. There are three variations of this mapping: • The first, and most common, maps a DevPPN-style logical disk (e.g. DSK1) to a base directory path (e.g. /vm/miame/dsk1/). The trailing slash on basedir/ is mandatory. The PPN equivalents are then set up as subdirectories of this base directory using the format /######, corresponding to devn:[###,###]. So for example if DSK1 maps to /vm/miame/dsk1/ then DSK1:[1,4] would map to /vm/miame/dsk1/001004. Note that the trailing colon, required to separate the devn from a filename or [p,pn] or in other contexts to identify a token as a devn instead of a filename, is omitted from this version of the DEVICE syntax. • The second variation overrides the implicit PPN subdirectory scheme just described, by specifying a complete and explicit directory to be associated with a specific devn:[p,pn]. The trailing slash on dir/ is mandatory. • The third variation is similar to the second but is reserved for logical devices that have no [p,pn] component associated with them. See the separate topic Devices without PPNs for a more thorough discussion. As an example, consider the following two DEVICE statements on a Unix-based host: A-Shell Reference Page 144 ``` DEVICE=DSK1:[31,3] /usr/tmp/ ``` ``` DEVICE=DSK1 /vm/miame/dsk1/ ``` Together, these statements would be used by A-Shell / MIAME to map the DevPPN specification dsk1:test.dat[31,5] onto the path /vm/miame/dsk1/031005/test.dat, and the DevPPN specification DSK1:TMPCMP.DAT[31,3] to /usr/tmp/tmpcpy.dat The file name is always converted to lower case as part of the mapping operation. The case of the directory component depends entirely on the case of the basedir in the DEVICE statement (lower case by convention). In Windows network environments, you can substitute UNC-style names (Universal Naming Convention) in place of the DOS drive letter in these DEVICE statements. For example: ``` DEVICE=DSK1 f:\vm\miame\dsk1\ ``` ``` DEVICE=DSK2 \\kahuna\ashell\dsk2\ ``` In the first DEVICE directive, logical device DSK1: is defined as being on the F: drive (which presumably is a mapped network drive.) In the second, DSK2: is defined as being at a location defined by the share name "ashell" on the server named "kahuna". The advantage to the UNC approach is that it eliminates the need to map the same (or any) drive letter on each client workstation to the server, thus simplifying the setup of client workstations in a network. The only known downside to this approach is that due to a bug in Windows 95, SYSTAT will not be able to report the number of free blocks on any device which is defined this way. But this is a relatively minor concern, and the bug is fixed in later versions of Windows. Although not recommended, if you insist on mapping DevPPN-style devices to directories that contain spaces, you can do so by enclosing the directory specification in quotes, as in this example: ``` DEVICE=XYZ0:[1,1] "C:\Program Files\COOL.STF\ZTERM For Windows\" ``` It should be noted that due to the automatic generation of pathnames from PPNs, and because DevPPN-style filenames are restricted to 81 (72.8) characters (as well as the case problem under Unix) there are many files that cannot be accessed via an DevPPN file specification. This mapping of an DevPPN file specification (using the definitions described here) is performed by by an internal conversion subroutine known as fspec2host. To solve the file-inaccessibility problem, if the DevPPN specification passed to the conversion subroutine contains a directory separator character ( / or **\** ) then no attempted mapping to a A-Shell Reference Page 145 pathname takes place. Under A-Shell, programs could be written to directly manipulate any files on the system (file protection permitting), for example: ``` open #1,"c:\autoexec.bat", input ``` ``` .. ``` In order to access a file in the current working directory whose name doesn't fit the 72.8 limit, or which contains upper-case characters or no extension under Unix, then it is necessary to specify a path containing the current directory symbol " **."** , for example: ``` kill "./core" ``` The following special form of the DEVICE directive may be used to define a device that references user memory: ``` DEVICE=MEM: MEM: ``` Technically, you could use any device name for the logical name (the first MEM:) but the physical name (the second MEM:) must be MEM: (in upper case, with the colon on the end). If you already have a PPN-specific MEM: or MEM0: device defined, then it must be defined first, i.e.: ``` DEVICE=MEM0:[1,1] /tmp ``` ``` DEVICE=MEM: MEM: ``` Make sure there is no MEM: in your ersatz.ini file; ERSATZ devices are processed first. Obviously, if you are using the MEM: ersatz, you will want to make other arrangements. However, it you are too committed to using MEM: as an ersatz disk device, then you could use some other logical name to refer to user memory. For example, `DEVICE=RAM: MEM:` would define a logical device named "RAM:" which referred to the physical device MEM: (user memory). ## **Notes** A-Shell Reference Page 146 Only those devices defined explicitly with a DEVICE line are allowable in an DevPPN file specification. All others will report _Device does not exist_ or _Invalid filename_ messages, depending on the context. If the configuration file contains both full device/PPN definitions (syntax two) and a default device definition for a given drive (syntax one), then the full device/PPN definitions must appear first. Under Windows, the host pathname may include the drive letter and a colon at the start, followed by the full pathname beginning (and ending) with a directory separator character; or, it may use the UNC format \\server\sharename\path\. ## **Symbolic links** In the Unix environment it is possible to create symbolic links to directories such that a single directory might be accessible by two (or more) paths. To fully accommodate this situation, you may want to define the same DEVICE multiple times for the different names, so that in situations where A-Shell may need to translate from the native directory (or alias) to the DevPPNstyle equivalent, it will find the native directory, regardless of which alias is being used. For example, if you have a symbolic link from /vm/sites/xyz to /vm/miame, then the following DEVICE statements might apply: ``` DEVICE=DSK0 /vm/miame/dsk0/ ``` ``` DEVICE=DSK0 /vm/sites/xyz/dsk0/ ``` The first entry will be the one used whenever translating from an DevPPN-style spec to native; the second one would come into play only when reverse-translating from a /vm/sites/xyz/dsk0/... native directory back to DSK0:. See "Issue when using " - symbolic link on the A Shell forum for further details. ## **Caution** If you use DEVICE to define specific a specific PPN (as opposed to entire DSKs), make sure that the PPN so defined does not _also_ exist in the location defined for the DSK. If you create a situation where the PPN exists twice, then DIR will display the files in _both_ locations. This is a special case of a larger problem with DIR, in that DIR scans the raw directory, then for each entry found, tries to display it as if it were an DevPPN file, using a backwards translation from the raw directory spec to the DevPPN equivalent. This causes DIR to find things, both files and directories, that might otherwise not be quite what was intended by a particular set of DEVICE definitions. The only solution would be to then do another forward translation of the found DevPPN spec A-Shell Reference Page 147 back to the native spec to compare when that native spec matched the one found by DIR, but that would slow DIR down considerably. ## **Examples** For both Windows and Unix, the host pathname may contain system environment variables, using the syntax %VAR%: ``` DEVICE=USR0:[1,1] %HOME%/ ``` ``` DEVICE=TMP0:[1,1] %TMP%\ ``` ``` DEVICE=DSK0 %MIAME%\dsk0\ ``` The first example makes USR0:[1,1] map to the current user's home directory (assuming that the environment variable HOME was defined by the user's shell). Note that even though the normal syntax for environment variables under Unix is $VAR, A-Shell uses %VAR%. The second example makes TMP0:[1,1] map to the user's TMP directory (in this case assuming that the TMP environment variable was defined on the PC, either for the machine or for the login user). The last example illustrates that the environment variable can be combined with other static elements. ## **See Also** - "No-PPN" devices (syntax three) ## **History** - " - " 2025 April, A Shell 7.0.1771: Add support for No PPN devices. A-Shell Reference Page 148 ## **DEVICES WITHOUT PPNS** _Written April 2025_ Beginning with version 7.0.1771 of April 2025, A-Shell supports a "no-PPN" variation of the DEVICE system parameter, allowing it to support individual arbitrary directories as devices without any PPNs. ## **DEVICE = dev#:[] path** Examples (two no-PPN devices followed by a single-PPN device) : ``` DEVICE = TMP0:[] "%TEMP%" ``` ``` DEVICE = TMP1:[] "C:\TEMP" ``` ``` DEVICE = BIN0:[1,1] "/vm/miame/bin" ``` Note that the no-PPN DEVICE definition syntax is similar to the single-PPN version, except without anything inside the []. When referencing the no-PPN DEVICE in code or on the command line, you never specify the [p,pn], whereas with the single-PPN device, if you don't specify the [p,pn] it will default to your current [p,pn] (probably failing unless it just happened to match the one [p,pn] on the device). The effect is similar to defining a single-PPN DEVICE and then creating an ERSATZ definition to point to that dev#:[p,pn]. The main advantage of the ERSATZ approach is that you can eliminate the device #; the main disadvantage is that it requires two matching definitions (one in the MIAME.INI, the other in an ERSATZ file.) One other advantage to the no-PPN DEVICE is that you can create a series of such definitions using the same base device but different unit numbers (as in the example above) and then perform combined searches on all of the units belonging to that device by just omitting the device # in the wildcard spec. For example, again assuming the above two DEVICE definitions, consider the following: ``` .LOG BAS: ``` ``` .DIR TMP:MYFILE.* ``` A-Shell Reference Page 149 Because TMP: is the (automatic) base device for TMP0: and TMP1:, omitting the device # in a wildcard command line context, acts like a wildcard (in this case matching both TMP0: and TMP1:). And since these are no-PPN devices, our current P,PN (7,6) has no bearing on where it searches (as would be the case with a single-ppn ERSATZ definition). Note that although the ground work for this is embedded into A-Shell, to successfully reference such devices at the command prompt you'll need to update the LIT commands: ``` DIR.LIT 3.4(178) ``` ``` COPY.LIT 3.4(149) MOVE.LIT 3.4(149) ERASE.LIT 3.4(138) PRINT.LIT 3.4(139) SIZE.LIT 3.3(103) DEVTBL.LIT 3.3(106) ``` The DEVTBL display was also modernized to eliminate pointless references that only made sense in the AMOS world, and to replace them with indicators of single-PPN and no-PPN devices. Several other LITs were recompiled with minor internal updates at the same time; use UPDCUR to update them. The updated LITs remain compatible with prior versions of A-Shell. A-Shell Reference Page 150 ## **EFSEXT** ## **EFSEXT=ext1 {,ext2, ext3,...ext10}** EFXEXT specifies which file extensions are to be encrypted. An encrypted file will be created if the following conditions are met: - The file is being created with either OPEN for output or ALLOCATE - The extension is in the EFSEXT list - A-Shell's Encrypted File System (EFS) is licensed and enabled - EFS has not been disabled via `XCALL ASFLAG,1024` Note that EFS is an entire system for file encryption and security. It is not included in the standard release of A-Shell, must be licensed as an option, and should be carefully considered before being implemented. If you are interested in implementing this filing system, see the documentation on the subroutine EFS and contact MicroSabio to discuss. A-Shell Reference Page 151 ## **ERSATZ** ## **ERSATZ=Pathname** ``` Example: ERSATZ=C:\VM\MIAME\DSK0\001004\ERSATZ.INI ``` Ersatz devices are defined in ERSATZ definition files, which should be located in the file and path given (in host operating system format) in the ERSATZ directive lines. Any number of ERSATZ directive lines may be present in the configuration file. Ersatz definitions allows you to add to the list of definitions without having to close and re-launch the A-Shell session. If there are multiple ersatz definition files, only the last one can be updated this way while A-Shell is running. The way it works is that if A-Shell attempts to look up an ersatz definition and it is not found, and at least 30 seconds have passed since the last time it reloaded the ersatz definition file, in then reloads the last ersatz definition file to see if there are any new definitions. The 30 second limit is to prevent excessive thrashing if a rash of undefined ersatz names are encountered in sequence. Any ERSATZ devices containing CPU numbers will be ignored. The maximum number of ERSATZ device definitions allowed is 1000 for A-Shell/Unix and A-Shell/Windows/32. The maximum length of the ERSATZ filespec is 160 characters. ## **Subtopics** - Ersatz Definition Files A-Shell Reference Page 152 ## **ERSATZ DEFINITION FILES** _Updated October 2014_ Ersatz devices are defined in one or more ersatz definition files, each of which is activated by a corresponding ERSATZ statement in miame.ini. By convention, these files are stored in the DSK0:[1,4] directory, with the first (and main) one being called ersatz.ini. If there are additional ersatz definition files, these are typically named xxxxx.ERZ where xxxxx is some kind of helpful allusion to the source or nature of the definitions contained in that file. Each ersatz definition file line must match one of the following formats: ## **ersatz-device: =real-device:{[p,pn]}** ## **++include real-device:file.erz{[p,pn]}** ## **ersatz-device: =%INCDEV%:{[p,pn]}** ## **Definitions** ## _ersatz-device_ the name of the ersatz device being defined: one to ten alphabetic or numeric characters, starting with an alphabetic character, and immediately followed by a colon. ## _real-device_ the name of a "real" device, defined via a DEVICE statement in miame.ini. It must be immediately preceded by the equals (=) symbol, and immediately followed by the colon. The real device names must be three or four alphabetic characters, followed by one or two numeric digits, with a maximum length of five combined characters. ## _[p,pn]_ an optional directory. If not included, then the ersatz device name can be used just like a real-device name in file specifications, meaning that you can optionally include a [p,pn] at that time. ## _file.erz_ A-Shell Reference Page 153 an arbitrary file name and extension of another ersatz definition file to "include" (i.e. effectively insert) into the current file. Note that contrary to the normal convention of ersatz definition files being in DSK0:[1,4], the ++INCLUDE feature is most useful with ersatz definition files that are stored on some other device. See %INCDEV% below for more details. ## _%INCDEV%_ This literal pseudo-environment variable may be used in place of a real-device reference within an ersatz definition file that has been ++INCLUDE'D, and will be interpreted as the real-device that was in the ++INCLUDE statement. See ERSATZ ++INCLUDE Statements for more details. Whenever A-Shell attempts to decode an DevPPN-style filespec, it compares the device part of the specification against the ersatz definitions first, before then comparing against the DEVICE definitions from miame.ini. So it is actually possible to "redirect" a real device by redefining it as an ersatz. For example, the ersatz definition DSK1:=DSK0: would effectively redirect all DSK1: references to DSK0:, even if DSK1: was a real device. If the device is not found in either the list of ersatz definitions or real device definitions, then the last loaded ersatz file (i.e. the one referenced in the last ERSATZ statement in miame.ini) will be reloaded, assuming that a minute has passed since the last time it was reloaded. So you can effectively add ersatz definitions without re-launching A-Shell, although the value of this is limited since re-launching A-Shell only takes a few seconds. ## **Examples** Valid ersatz file entries look like this: ``` SYS:=DSK0:[1,4] ``` ``` LIB: =DSK0:[7,0] DSK100: =DSK99: AA12345678:=ZZZ12:[345,678] ``` The ersatz definition file that is distributed with A-Shell and invoked by default, ersatz.ini, looks like this: ``` OPR:=DSK0:[1,2] ``` A-Shell Reference Page 154 ``` SYS:=DSK0:[1,4] ``` ``` DVR:=DSK0:[1,6] CMD:=DSK0:[2,2] LIB:=DSK0:[7,0] HLP:=DSK0:[7,1] BOX:=DSK0:[7,2] BAS:=DSK0:[7,6] SBX:=DSK0:[7,6] MAC:=DSK0:[7,7] ASHCFG:=DSK0:[1,7] PTR:=DSK0:[1,7] ASHLPD:=DSK0:[1,25] FAXWRK:=DSK0:[1,26] ASHBAS:=DSK0:[907,6] ASHINC:=DSK0:[907,16] ``` Another example: ``` ++include SOS6:SOSLIB.ERZ[1,4] ``` Within an ersatz definition file that has been ++INCLUDED, the following would be legal: `SOSFUNC:=%INCDEV%:[907,10]` A-Shell Reference Page 155 ## **History** - 2014 October, A Shell 6.1.1393: Add ++INCLUDE capabilities A-Shell Reference Page 156 ## **ERSATZ ++INCLUDE STATEMENTS** _Added October 2014_ ERSATZ definition enhancement: ersatz definition files may contain ++INCLUDE statements of the form: ## **++INCLUDE dev:file.erz[p,pn]** In addition, the dev specified in the ++INCLUDE statement may then be referenced from within the included file using the pseudo-environment variable %INCDEV%, e.g. ``` ADCJSON:=%INCDEV%:[907,10] ``` The combination of these two enhancements facilitates the ad-hoc addition of modular sets of current-device-relative ersatz definitions. As an example, for the 2014 A-Shell Developer Conference, we created a set of ersatz definitions, in the file ADC.ERZ: ``` ADCARY:=%INCDEV%:[908,61] ADCCGI:=%INCDEV%:[908,62] ``` ``` ADCJSON:=%INCDEV%:[908,63] ``` Because there is no explicit device reference, these ersatz directories can be installed on any available device on the target machine, assuming no conflicting PPNs. Let's say we want to use an existing device DSK29:. To install the ersatz definitions copy the ADC.ERZ file to any ppn on DSK29, let's say DSK29:[1,2]. Then just add a ++INCLUDE reference to it in the main system ersatz.ini: ``` ++include DSK29:ADC.ERZ[1,2] ``` Note: "main system ersatz.ini" refers to last one referenced in miame.ini, since that is the only one that will be reprocessed on the fly, which is an essential part of this scheme. Now, without re-launching A-Shell, you can use those ersatz definitions, i.e. `LOG ADCJSON:` A-Shell Reference Page 157 Aside from ad-hoc ersatz additions like this, the feature is also useful for maintaining different versions of the same ersatz definitions. For example, you might have a set of ersatz definitions for your application, but you also want to maintain two versions, the stable version and the development version. With this scheme, you can use a single app.erz file containing your ersatz definitions, and just install it and the associated directories on two different devices. By avoiding the need to explicitly reference the devices, you avoid the hassle of having to convert the device reference to match the actual device where you installed it, as well as the confusion that occurs when you forget to do that. **Warning:** If the applicable ERSATZ statement in miame.ini comes before the DEVICE statement that defines the device referenced in the ++INCLUDE, it won't be resolved until after A-Shell is launched and a subsequent reference is made to the ersatz. Failed references trigger a re-scan of the ersatz definitions, after a small time interval. So that generally isn't a problem. BUT, in the case of the APN.LIT compiler command line, it only gets one chance to define the ersatzes, so if you are using this technique, move the ERSATZ statement(s) below the DEVICE statements. ## **History** - 2014 October, A Shell 6.1.1393: Add ++INCLUDE capabilities A-Shell Reference Page 158 ## **FILES** ## **FILES=<# File buffers>,<# ISAM buffers>** ``` Example: FILES=40,40 ``` In order to keep track of files opened within programs, A-Shell allocates internal file buffers within the _memory partition;_ see the MEMORY directive. Each file buffer requires approximately 80 bytes, and each ISAM buffer approximately 300 bytes. In order to save memory, or to support an extended number of files, the number of buffers may be changed, according to the following rules. Note that the buffer values refer to the maximum number of files which may be simultaneously open at any one time. ISAM buffers are only used for ISAM 1.x files. If your application makes use of only sequential, random, and ISAM PLUS files, the number of ISAM buffers may be set to zero. Sequential, random, and ISAM PLUS files require only a single FILE buffer each. An ISAM 1.X file requires two FILE buffers and one ISAM buffer for the initial open of the main index, while each subsequent secondary index requires just one FILE buffer, and one ISAM buffer. ## **Notes** The default number of buffers is 40 FILE and 40 ISAM, in order to maintain compatibility with earlier versions of A-Shell. The FILES parameter only adjusts A-Shell’s internal resource allocations; you may need to adjust the parameters for your operating system locking mechanism to allocate enough locking resources for large numbers of open files. The operating system and/or environment may further impose limits on the maximum number of open files. Under Unix, there are typically kernel configuration variables which set the limit, although it may be further limited by the shell. A-Shell Reference Page 159 ## **FKEYWAIT** ## **FKEYWAIT=<# ms>** ``` Example: FKEYWAIT=50 ``` (Unix Only) Most "function keys" send multiple bytes. In order to distinguish between a true multi-byte sequence and a series of individual single-byte keystrokes, A-Shell considers the time delay between the first byte (the "leadin") and the following byte. In practice, this means that whenever A-Shell sees a byte that could be a "leadin" (typically ESCAPE or CTRL+A), it does a timed input operation for the next byte. If one or more bytes arrive within the specified interval, then it is considered a multi-byte sequence, otherwise the initial byte is treated as a stand-alone character. Under normal circumstances, the default five milliseconds wait is sufficient, but still short enough that you don’t notice the delay. However, in some cases, the delay between the "leadin" and the following bytes can be substantially longer. One example of this occurs when using rlogin instead of telnet to log into a remote system. In that case, you may need to specify a much longer delay, perhaps as much as 200 ms. If the FKEYWAIT value is too short, function keys may stop working properly, and will instead typically put some kind of garbage on the screen. However, the longer the wait, the longer you have to wait before an individual ESCAPE or CTRL+A is acted on. For example, in VUE, the ESCAPE character switches between edit and command mode. If you like to switch quickly between these modes, you may find that a 200 ms delay in response to the ESCAPE key is unbearable. So the advice is to use experimentation to get the FKEYWAIT value as low as possible without causing your function keys to break up. Since the required FKEYWAIT value may change from terminal to terminal, you may also change this on a job-by-job value at runtime using SET; type `SET /?` from the A-Shell prompt to display help info. A-Shell Reference Page 160 ## **FLDATTR** ## **FLDATTR=ON/OFF (default is ON)** FLDATTR is used to disable "field" attributes, to avoid display problems caused by programs assuming "field" emulation, when the actual display device is operating as a "mode" terminal. See FIELDEMU under OPTIONS for a discussion of the difference between "field" and "mode" emulations. When FLDATTR is off, "field" attribute commands, such as reverse video and underline, are ignored. Doing without your reverse video and underline highlights is better than having them spill over the screen incorrectly, as would otherwise happen if your application was not written to support both field and mode emulations. `FLDATTR=OFF` is equivalent to `OPTIONS=NOFLDATTR` . A-Shell Reference Page 161 ## **FONT** ## **FONT= {,}** ``` Examples: FONT=Courier New (default) ``` ``` FONT=Lucida Console, ANSI ``` Under A-Shell/Windows, FONT may be used to specify two aspects of the font: the face name and the symbol set. The face is the name that appears in standard font selection dialog boxes (including the one on A-Shell's Edit menu), such as Courier New or Lucida Console. It is case sensitive. If not specified, A-Shell will select what it thinks is the best font from the available choices— i.e., those installed on this system. Common choices are Courier New, Lucida Console, and Consolas.. The symbol set may optionally be specified as OEM, ANSI, or DEFAULT. If not specified, OEM is used. The face name will be overridden by a font specified in the default.ash or other settings file. See the –Settings File switch and the Settings Menu...Font topic for more details. However, the symbol set will affect all subsequent font selections, even overriding a previously saved font in the settings file. The only fonts suitable for A-Shell are those that offer a fixed pitch, so that typically limits you to Courier New, Lucida Console, and Consolas. Miame Terminal and Andale Mono were frequently used in older versions of Windows and A-Shell, but they are no longer convenient; Miame Terminal because it is a bitmap font that doesn't scale well, and Andale because it is available only for a fee. The symbol set determines which characters are available and how they are numbered. Most of the fixed pitch fonts support both OEM and ANSI. Fortunately, both character sets use the same values for the ASCII printable characters 32-127, so it probably makes little difference in most applications which one you use. Furthermore, both character sets include the Latin1 characters in the range 128-255, and although they are mapped differently, if you specify OPTIONS=LATIN1 A-Shell will convert both mappings to match the Latin1 mapping used under AMOS (such as with the AM65A terminal). Historically, the main problem with the ANSI character set in A-Shell was that it didn't include the line drawing characters, but this is no longer an issue since A-Shell renders them graphically. The only remaining shortcoming is its lack of a few special characters available in the alternate character set via TAB(-1,65) thru TAB(-1,77) commands (raised dot, end of line, horizontal tab, paragraph, dagger, section, cent, quarter, half, trademark, copyright, register mark). On the other hand, the OEM character A-Shell Reference Page 162 sets (except for the MIAME Terminal version) do not include a Euro symbol. With ANSI , you can display a Euro symbol via TAB(-1,253) or chr(128). Note that Windows applications such as A-Shell can only make "requests" for a particular font. The system then provides a font that is the best match for the requirements given. Thus, you can easily end up with an unexpected font if your system does not have the requested font installed. For example, if you ask for Andale Mono but it isn't installed, it should try to select something with similar capabilities, hopefully (but not necessarily) ending up with a font reasonably like Courier New. ## **Comments** - The actual font and symbol set in use is identified on the A-Shell/Windows Help...About box. - In order to use a national replacement character set, you must specify the OEM symbol set. See the CONSOLESP and - CHARSETSP parameters. A-Shell Reference Page 163 ## **IATIMEOUT** _Updated May 2025; see History_ ## **IATIMEOUT=** ``` Example: IATIMEOUT=60 ``` IATIMEOUT activates an inactivity timer that will shut down a session if it has been inactive—no keyboard input or ASB/LIT instructions—for at least . In practice, the actual delay until the timeout is detected and the job is shutdown may be as much as twice the specified number of minutes. The default value is 0, meaning no inactivity timer. The –cgi command line switch automatically sets the IATIMEOUT to 7 seconds. See _History_ note below. ## **Comments** The process of determining whether a session is truly inactive is fairly complicated. Since the objective is to close down jobs that have obviously been abandoned, rather than precisely limit users to N minutes of inactivity, the timing program was built to err on the side of too long rather than too short. Consequently, as mentioned above, the actual timeout period may be quite a bit longer than the setting. ## **See Also** - AG_IATIMEOUT - MX_IATIMEOUT ## **History** - 2025 May, A Shell 1772: When the inactivity timer expires, as long as the session is running an application program and not waiting on an ATE operation (e.g. XTREE, GUI INFLD, etc.), it will now beep and present a message box telling the user the session is about to time out, allowing up to 10 seconds to cancel the timeout. In addition, provided the SIGHUP TRACE option is enabled, inactivity checkpoint messages will be added to the ashlog for periods of inactivity lasting 1/4 of the IATIMEOUT value. This improves forensic confidence that the timeout is working as expected, as users are often doubtful!. A-Shell Reference Page 164 ## **IJCFREQ** ## **IJCFREQ=** ``` Example: IJCFREQ=10 ``` IJCFREQ activates a timer interrupt that checks for "Inter Job Communication" (IJC) messages. These include inactivity timeout checks (see IATIMEOUT), and SEND.LIT and KILL.LIT under A-Shell/Windows. (The Unix version of these commands uses the more powerful and direct Unix signals.) The default value is automatically determined based on the number of users licensed, and will be in the range of 5 to 30 seconds. To disable the timer and the corresponding functions, set IJCFREQ to zero. Note that in the Windows world, checking for IJC messages involves reading a record from jobtbl.sys on the server, and thus you don’t want to make it any more frequent than necessary. But if you set the value too high, you could have to wait for a long time to get a response from a KILL or SEND command. A-Shell Reference Page 165 ## **INCLUDE** ## **INCLUDE=filename** ``` Example: INCLUDE=f:\miame\trmdef.ini ``` INCLUDE is the equivalent of the C #include or the ASB ++INCLUDE directive. It forces the inclusion at that point of another file which itself contains any of the valid configuration file commands, with the exception of INCLUDE itself. The typical use of this directive is to reference a file containing TRMDEF statements, as shown in the example above. Another way you might use this directive is to separate the statements which may differ from one user to another from the main body of miame.ini. Note that most users can get by without including a trmdef.ini file, since A-Shell will, by default, generate names of the form TSKAAA, TSKAAB, etc., for the jobs and terminals as needed. trmdef.ini is only relevant if you want to predefine certain job and/or terminal names to be associated with specific terminal devices. The INCLUDE directive may replace the SERIAL[SP] directive as the first line of the file, provided that the file being included starts with a SERIAL line. This is useful if you want to have identical miame.ini files across many systems, each referencing a separate file for the SERIAL information, i.e. `INCLUDE=SERIAL.INC` . A-Shell Reference Page 166 ## **JOBPREFIX** ## **JOBPREFIX=** ``` Example: JOBPREFIX=JOB ``` ``` Default: JOBPREFIX=TSK ``` JOBPREFIX allows you to override the default jobname prefix ("TSK") which is used to generate unique job names. The prefix is normally 3 characters, to which A-Shell appends a sequentially generated suffix (e.g. "AAA", "AAB", etc.) resulting in job names like TSKAAA, TSKAAB, TSKAAC, etc. Job names can also be specified by the TRMDEF statement or by use of the `–j ` command line argument. A-Shell Reference Page 167 ## **LANGUAGE** _Rewritten December 2023_ ## **LANGUAGE=pathname** A-Shell uses a language definition file (aka LDF) to define certain language- and locale- dependent parameters, such as: - translations of words for dates, yes/no, etc. - numeric formatting: use of commas, decimal points, currency symbol - date formatting: month-day-year vs day-month-year, separators - collating sequence The specified _pathname_ must be fully qualified; by convention the LDF files are stored in the equivalent of DSK0:[1,6]. The LDF file format is equivalent to the AMOS 2.x language definition file format. Several standard variations are supplied with A-Shell: ENGLSH, BRTISH, FRENCH, FRANGL, PORTUG, SPANSH, ITALIA, etc. Contact MicroSabio for information on creating your own variants. A-Shell automatically relies on the LDF for several built-in functions such as those mentioned above. Applications may also query the LDF via the GTLANG subroutine, which see for a list of the specific parameters. ## **Examples** ``` LANGUAGE=C:\VM\MIAME\DSK0\001006\ENGLSH.LDF ``` ``` LANGUAGE=/vm/miame/dsk0/001004/brtish.ldf ``` ## **See Also** - SET - GTLANG A-Shell Reference Page 168 - DATES - IDTIM - ODTIM - VAL() - USING ## **History** - 2009 January, A Shell 5.1.1136: LDF enhancements: New LDF files (each named by appending an "X" to the existing name) have been created to add a standard Latin 1 character collating sequence for the upper 128 characters. This may be an interim measure until we decide whether there is any reason not to just update the standard LDFs with the collating sequence. Until then, if you are interested in the collating sequence, either rename the "X" version to the standard name, or change the ERSATZ statement in miame.ini to reference the "X" version of the LDF. A-Shell Reference Page 169 ## **LOGDIR** ## **LOGDIR=** ``` Examples: LOGDIR=/vm/miame/dsk0/001002 ``` LOGDIR allows you to specify a directory for the A-Shell log file (ashlog.log); absent any such specification, the log will be found in the same directory as miame.ini. You must specify a directory using native operating system syntax, but you may optionally include environment variable names (such as $MIAME in one of the examples above.) A-Shell Reference Page 170 ## **LOKSER** _Rewritten June 2023_ ## **LOKSER=['ON' | 'OFF'] {,FORCE_WRITE}** This directive specifies whether LOKSER is to be activated. LOKSER is a file locking scheme involving a combination of OS-level locking operations and rules governing file access. When _not_ enabled, all file operations are lock-free from the standpoint of the operating system, requiring applications to employ some other kind of A-Shell locking mechanism such as XLOCK or FLOCK in order to coordinate multi-user access. When LOKSER is enabled: - Random files opened in mode RANDOM are effectively opened exclusively. - Random files opened in mode RANDOM'FORCED are shared - In shared mode, the READ statement reads without locking while READL reads and locks the record. WRITE unlocks the record after writing (requiring a prior READL), while WRITEL locks, writes, and then unlocks. UNLOKR can be used to unlock a record without writing. - Attempts to read a locked record, or to open a file in a mode that conflicts with another user already having the file open, unless the WAIT'FILE or WAIT'RECORD option is specified on the open, will generate one of the LOKSER-related errors 37 (file in use) or 38 (record in use). - Other LOKSER-related errors include 42 (record not locked) and 44 (LOKSER queue full due to too many locks being held at once). - ISAM sequence checking—a set of rules dictating the sequence of ISAM File Statements—is activated, generating ISAM error 39 on any violation. ISAM-A operations always act as if LOKSER is enabled, i.e. they use OS-level file locking regardless of the LOKSER setting. However, they do respect the FORCE_WRITE option if enabled. A-Shell Reference Page 171 The FORCE_WRITE option requests that file updates be flushed to disk immediately. It is generally supported for random file WRITE operations under Windows, and for ISAM-A operations in all environments. But it drastically slows down performance and thus is not recommended. A-Shell Reference Page 172 ## **MALLOCLIMIT** ## **MALLOCLIMIT=** ``` Examples: MALLOCLIMIT=32M ``` MALLOCLIMIT is useful for changing the default dynamic memory allocation limit of 8MB. This mainly affects sorting, which, if the SBR=MALLOCSORT option is specified (which see), can allocate and take advantage of large amounts of memory. A situation where you might want to increase the limit would be under Windows (where you probably have huge amounts of physical memory per workstation) if you were sorting files larger than 8MB. For example, if you were often sorting files of up to 32MB in size, setting the MALLOCLIMIT to 32M would make sure sorts run many times faster. A situation where you might want to decrease the default MALLOCLIMIT would be on a large, older, multi-user Unix system where memory might be a bit tight. Although any memory allocated for sorting would be released back to the system pool as soon as the sort was complete, Unix systems often will delay making the memory available to another process until the situation becomes desperate. This is based on the historical case where Unix processes tended to be short-lived, and thus efficiencies could be gained by delaying all memory cleanup until the process exited. The MALLOCLIMIT limit will also affect the size of the largest file that can be brought entirely into memory by the VUE editor. Note that the limit is stored as a 32 bit unsigned variable in units of bytes, so it will wrap back to zero at 4096M. Thus the maximum value is 4095M. A-Shell Reference Page 173 ## **MAPIDA** ## **MAPIDA='ON' | 'OFF'** Under AMOS, ISAM Plus files are given the same extensions as their ISAM 1.x counterparts, namely .IDA for the data files and .IDX for the index files. Under A-Shell, however, C-ISAM or D-ISAM are used to implement ISAM Plus. This gives the data files extension .DAT; the index files have the same extension. Many programs are likely to use the LOOKUP and KILL statements on ISAM Plus data files. If MAPIDA is specified as true, then an extension of .IDA will be mapped onto an extension of .DAT if no file with extension .IDA exists. Care must be taken specifying MAPIDA if ISAM 1.x applications are to run concurrently with ISAM Plus. It is possible that some minor programming changes will be required in terms of LOOKUP and KILL. A-Shell Reference Page 174 ## **MAXINST** ## **MAXINST=##** ``` Example: MAXINST=1 ``` (Windows only) MAXINST allows you to limit the number of A-Shell windows or sessions that can be run simultaneously on one workstation. If not specified, then there is no particular limit. The main reason for setting a limit, especially a limit of one, would be to eliminate the confusion that arises when inexperienced users don’t realize they have a session already going (perhaps because it is minimized) and so they open another, perhaps repeatedly. This, by itself, is not a problem for A-Shell, but it may be a problem for the application, if, for example, the user has a record locked in one of the sessions and then leaves it there indefinitely because they forgot about the session. A-Shell Reference Page 175 ## **MAXJOBS** ## **MAXJOBS=## ; set job table size to ##** ## **MAXJOBS=*## ; set size to ## times licensed nodes** MAXJOBS specifies the maximum size of the job table (jobtbl.sys). jobtbl.sys gets automatically allocated to this size whenever an instance of A-Shell is launched and there is no pre-existing jobtbl.sys. (Like qflock.sys, it gets removed automatically as well when there are no active A-Shell jobs, and can be removed manually if for some reason the automatic removal fails and you want to re-initialize it.) If you fill up the job table, the next attempt to launch an instance of A-Shell will get a job table full error. However, you can fix that by simply adjusting the MAXJOBS parameter and launching A-Shell again, at which point it will expand the table. (It is not necessary to get all users out to perform this expansion.) The second form of the directive is preferable since it results in the file automatically expanding as you increase the number of licensed nodes. The only penalty for making the job table excessively large is the few extra microseconds it takes to scan the table when looking for active jobs (so when in doubt, make it larger.) If you don’t specify a MAXJOBS parameter, a complicated and classified formula will be applied to arrive at a reasonable size. A-Shell Reference Page 176 ## **MAXLOCKS** ## **MAXLOCKS=##** ``` Example: MAXLOCKS=500 ``` MAXLOCKS specifies the maximum number of locks (per job) that A-Shell will keep track of for enforcing the LOKSER rules on ISAMPLUS UPDATE'RECORD and DELETE'RECORD operations. According to the rules under AMOS, UPDATE'RECORD and DELETE'RECORD must only be used on records that were previously locked, and it uses the LOKSER lock queue to enforce this. A-Shell implements LOKSER via the natural locking facility of the native operating system, which does not permit it to easily scan the lock list. Thus it uses its own internal list to keep track of which records have been locked. The default for MAXLOCKS is 100, which should be more than enough in most cases. The only likely reasons why you might want to override this would be if you wanted to disable the rule (i.e. allow unlocked records to be updated or deleted, even when LOKSER is on.), in which case you would specify MAXLOCKS=0, or if your application allowed a user to lock more than 100 records at a time, in which case specify an appropriately large number. The lock list requires 8 bytes per lock, and is allocated separately from the memory partition and thus does not subtract from any other specified allocation size. A-Shell Reference Page 177 ## **MEMORY** ## **MEMORY={,sbxmem size{,cachelimit}}** ``` Examples: MEMORY=700K MEMORY=700K,200K ``` ``` MEMORY=2M,400K,500K ``` MEMORY configures certain memory allocation sizes used by each A-Shell user. The first number specifies the size of the ASB work area. If no MEMORY statement is specified, the default work area size is 512K. This work area is used for a variety of purposes, including variable storage, the CALL/RETURN stack, allocation of dynamic arrays, string stack, and if sufficient in size, for sorting files, and compiling, and editing programs. The ASB MEM() function displays the amount of free memory available in the main work area. Note, however, the program itself —and any modules loaded by the LOAD command—is stored in dynamically allocated memory outside of the ASB work area. The second parameter specifies the amount of memory to be provided for any SBX subroutine call. If not specified, the default is 384K. In either case, if the main work area has sufficient free space at the time the subroutine is executed, then that will be used instead. (So if you call a lot of SBX routines, it might be more efficient to make your main work area large enough to accommodate the needs of your largest SBX.) The last parameter specifies the maximum amount of memory to be set aside for caching of SBX subroutines and other modules that are automatically loaded on demand. The default is 200K. Such modules are kept in memory for a period of about 10 minutes after their last access, or until the specified limit is exceeded. At that point, modules are discarded on a LRU (least recently used) basis. ## **Notes** A number of A-Shell operations that require additional memory, such as BASORT, COMPIL.LIT, and VUE.LIT, may take the liberty of allocating it outside of the ASB work area. See the MALLOCLIMIT directive for details on limiting those allocations. A-Shell Reference Page 178 The minimum practical amount of memory to execute many of the system commands is about 350K. You can also specify the memory size on the A-Shell command line. ## **History** - 2016 July, A Shell 6.3.1518: Memory enhancement: Move the string expression stack out of the main partition into a separate module which now auto-expands as needed. This should eliminate the most common and yet most unpredictable cause of outof-memory (or stack-overflow) errors, which are related to operations on strings whose size is not obvious or easily predictable. The main partition (specified by the first and/or second values in the MEMORY statement) is now used mainly for mapped variable storage, call stack, and command files. The actual RUN files are loaded separately. `SYSTAT/M` shows the minimum available memory in the partition since the beginning of the session, allowing you to perhaps gauge how much larger-thannecessary your partition allocation is. A-Shell Reference Page 179 ## **MMAPLIST** ## **MMAPLIST=** (Unix only) MMAPLIST allows you to specify a list of files that should automatically be memory-mapped whenever they are opened. __ should be a fully qualified filespec, although it may contain environment variables using the %ENVVAR% syntax. The specified file should contain a list of DevPPN-style or native filespecs, one per line, for the files you want to automatically memory-map. Blank lines are ignored, and anything after a number sign (#) is treated as a comment. Ersatz devices are allowed. For example: ``` #List of files to be memory mapped ``` ``` c:\vm\miame\dsk0\100005\myfile.dat # native allowed ``` ``` MYAPP:MYDATA.DAT # ersatz allowed DSK0:MYIDX.DAT[100,5] # standard DevPPN allowed ``` The above list specifies three files to be memory mapped whenever they are opened. Note that DevPPN specifications are recommended over native ones since they are not sensitive to changes in the device definitions. In the example above, the device where MYAPP: is could be redefined without having to change the MYAPP: reference in this file. But if c:\vm\miame was relocated to d:\vm\miame, you would have to remember to also edit this file to fix the native filespec. Memory mapping gives you much better file i/o throughput, at the cost of more memory usage. It works best on files that have a lot of access relative to their size (SERCH index files are a particularly good example.) There are other ways to memory map files, such as using the subroutine ASFLAG or by loading the files directly into memory and using OPTIONS=AUTO_MEMOPEN in miame.ini. This method has the advantage of being entirely independent of your application, allowing you to tune your system or just experiment with memory mapping, without making any changes to the application itself. A-Shell Reference Page 180 ## **NOTRACE** _Written January 2024_ ## **NOTRACE=name1,name2,...** NOTRACE disables specific traces that have been more generally enabled. It only supports XCALL traces; so if TRACE=XCALL, either in the miame.ini or at run time via the SET command or system message window, the names listed in NOTRACE will still not be traced. You may have any number of NOTRACE directives, and each one can have one or more XCALL names listed, but they must be comma-delimited, with no spaces. For example: ``` NOTRACE=TRIM,FILL,MIAMEX,STRIP ``` ## **History** - 2024 January, A Shell 7.0.1754: Function added to A-Shell. A-Shell Reference Page 181 ## **OPTIONS** _Updated December 2013 (Added STR0)_ ## **OPTIONS=option {,option} {,option}...** The OPTIONS directive is used to set various options that don’t fall neatly into another category. You can specify several options on a single line separated by commas, or you can specify them using multiple OPTIONS directives. Note also that the values for these options may be queried or changed by the subroutines MX_GETOPTIONS or MX_SETOPTIONS. |**Options**|**Description**| |---|---| |ABSLOOKUP|CausesLOOKUP()to return a positive value.| |ASHELL_RUNSBR|CausesASHELLXSto execute commands as true subroutines.| |AS400|Special AS400 Telnet option.| |AUTO_MEMOPEN|Causes OPEN to see if file is already in memory.| |AUTOTPRINT|Causes PRINT statements to act likeProportional Font Text Objects
—i.e., create static text controls).| |BRKALC|Pre-fill random files with ]]]]]]].| |CRLF|Terminate sequential files with CRLF.| |CRNL|Same as CRLF.| A-Shell Reference Page 182 |**Options**|**Description**| |---|---| |AUTODLGSTATE|Make the MBF2_DLGSTATE option be the default for all dialogs. If you set it as the default, the only way to turn it off for
individual dialogs would be to useMX_SETOPTIONS
(GOP2_AUTODLGSTATE ) to clear the flag before creating the dialog.| |EFFUSR|Returns "effective user name."| |EFS|Various options related to "EFS," A-Shell's encrypted file system| |EXITWAIT|Causes A-Shell to wait for a keyboard response before closing the window down due to the –e switch, thus giving you a
chance to read any final screen messages before the window is destroyed.| |EXTFIO|Allows access to contiguous files that are NOT a multiple of 512 bytes.| |FSPECNATIVE|Allow more flexibility for native file specs.| |FIELDEMU|Emulate field terminal attributes.| |FPROUND|Apply rounding factor of .000005 to INT and FIX.| |GUI_SPC_IND|Tokenizes horizontal fixed-pitch spacing for use in variable-spacing GUI screens| |HEXDEC|Special hexadecade date processing.| |ISAM_IDXLOK|Causes the entire ISAM index file to be locked whenever it would otherwise only be necessary to lock the "rock" (i.e.
during index update operations.) For reasons that no one understands, this actually seems to give better results in some
Windows network environments.| |LATIN1|Remap OEM character set to Latin1.| A-Shell Reference Page 183 |**Options**|**Description**| |---|---| ||| |LONGDIR|CausesDIR.LITto use the 10.4 format by default. Equivalent to system command SET LONGDIR.| |NOAUTOX|Disables auto expansion of ISAM & INMEMO files; same as NOISAM_AUTOX.| |NOAUTOXLT|(Windows only) Disables the automatic translation of thePG-UPandPG-DNkeys under A-Shell/Windows toCTRL+Rand
CTRL+T. This way you could translate the keys to something else. SeeFIXTRN.LIT
.| |NOFLDATTR|Discards field attributes.| |NOINSTRX_PCP|NoINSTR
precompiled patterns.| |NOISAM_AUTOX|Disables auto expansion of ISAM and INMEMO files; same as NOAUTOX.| |NOJOBMAP|(Unix only) Preventsjobtbl.sysfrom being memory mapped. Normallyjobtbl.syswill be memory mapped or not
depending on whetherqfock.sys(i.e. whether the QUEUE= parameter specifies "DISK" or "MEM"). The option is mainly
of interest for debugging or other exotic situations.| |NOSPACEATTR|Eliminates the automatic space associated with the on/off field attributes.| |NOWHEEL|Disables the otherwise automatic conversion of the mouse wheel events intoUP/DOWN-ARROWkey presses.| |NOXABORT|Prevents user from closing window containing an active program.| A-Shell Reference Page 184 |**Options**|**Description**| |---|---| |NTTS|Identifies A-Shell instances like NT Terminal Server sessions.| |NUMPAD_COMMA|Converts the "." key on the number pad to a comma for the convenience of locales which use comma as the decimal
point.| |RAWTABS|(Unix variants only) Causes A-Shell to output raw tab characters rather than converting them to spaces. It would only
be useful if your terminal emulator had some kind of special tab handling feature.| |RC_DIMX|Tells the compiler to allowDIMXstatements in /RC mode.| |SBX_RUNDIR|Alters the search path for SBX modules.| |SEQLOK|Enables locking on sequential files for Unix.| |STR0|Causes numeric conversions to string, whether implicit or explicit, via str(x), to retain the leading zero for fractional
values between -1 and 1. Normally the leading zero is stripped in all cases. For example, if x=0.5 and y=-0.3, str(x) and
str(y) would normally return ".5" and "-.3" respectively, whereas with
`OPTIONS=STR0`set, the output would be "0.5"
and "-0.3".| |STRICT|Causes A-Shell to emulate various AMOS functions.| |TRKTOPSTS|Causes PolyShell to treat the top status line as part of the screen.| |XABORT|Generates error 255 when user tries to close window if program running.| |XTAUTOFILTER|Automatically sets the XTF2_AUTOFILTER flag for allXTREEcalls, enablesXTREEauto-filtering.| A-Shell Reference Page 185 ## **History** - 2013 December, A Shell 1369: Add STR0. A-Shell Reference Page 186 ## **ABSLOOKUP** This option causes the ASB LOOKUP statement (and corresponding BASIC _plus_ function) to always return a positive value. Otherwise, in order to more closely mimic AMOS, it will return a negative value if the file is an exact multiple of 512 bytes (since this makes it most likely that the file was originally random or contiguous, and thus you would have returned a negative LOOKUP value under AMOS.) Note that while this is a nice trick, it is not infallible, since the chances are 1 out of 512 that a sequential file will also be an exact multiple of 512 bytes. We strongly recommend that you review the use of LOOKUP in your programs and convert your logic to use ABS() to convert negative values to positive, rather than simply negating the value. A-Shell Reference Page 187 ## **ASHELL_RUNSBR** Note: this switch was previously known as AMOS_RUNSBR. This switch causes ASHELLXS (previously known as AMOSXS which is still supported) to execute most commands (anything except CMD and DO files) as true subroutines within the current process, rather than in another process, as would otherwise be the normal behavior for A-Shell. For example, `XCALL ASHELL,"RUN XYZ"` would run the XYZ program within the current process, using the current job environment. This is how most versions of AMOS.SBR worked under the old AMOS operating system. CMD and DO files cannot be executed within the current process, so they will run in a separate process regardless of the ASHELL_RUNSBR switch. Aside from making the A-Shell version of ASHELLXS act more like the original AMOS versions of AMOS.SBR, the other advantage of the ASHELL_RUNSBR switch is that it is much more efficient. We recommend that you use this switch, and would have made it the default behavior, except for historical compatibility. There may be situations where the use of a separate process is actually better, particularly when you don’t want side effects from the subroutine process to linger, either on the screen or in the job’s current environment. For example, any screen output generated by the subroutine will remain on the screen after return to the caller if the subroutine executes within the current job/process. Otherwise, the screen output of the subroutine will appear in a different window, or in a different virtual screen, which will be discarded when it returns. Similarly, any changes to the job’s environment, such as the current PPN or other status settings will be discarded if the subroutine executes in a separate process, but will be retained if the subroutine executes within the current process. For example, consider: ``` xcall ASHELL,"LOG DSK1:100,2" ``` ``` xcall ASHELL,"SET HEX" ``` The commands above make no sense if `OPTIONS=ASHELL_RUNSBR` is not specified, since the effect of the command (changing the ppn or a job status setting) would otherwise be lost as soon as the command completed, since it would be taking place in a separate job and process from the caller. When Xcall ASHELL runs a command within the current job, it guarantees the child process will have a certain amount of memory, even if it has to be specifically allocated on the fly. The amount defaults to 360K, but can be specified with the second SP argument to the MEMORY parameter in miame.ini. A-Shell Reference Page 188 ## **AS400** (Unix only) This is a rather weird option that was implemented to overcome some kind of shortcoming in the AS400 implementation of Telnet, and would only apply (if then) in a situation where AS400 users were connecting via Telnet to A-Shell running on a Unix machine. The problem was that when the user typed too fast, bursts of BACKSPACE and other control characters would mysteriously be dumped into the input buffer. With this option turned on, A-Shell filters those characters out. A-Shell Reference Page 189 ## **AUTO_MEMOPEN** This option causes every ASB random file OPEN to first check to see if the file being opened is already in memory. If so, it accesses the memory copy as if the filespec had specified MEM: directly. The idea of this option is that it permits you to experiment with, or take advantage of the MEM: device (described above) without actually modifying your programs to specify MEM: in the file open statements. For example, consider the following open statement: ``` OPEN #CH, "DSK2:MYFILE.DAT[123,222]",RANDOM,RSIZE,RFILE ``` If `OPTIONS=AUTO_MEMOPEN` is set, then the OPEN will first check to see if myfile.dat is in user memory. If not, then it works normally. But if it is, then it uses the memory copy. So to make a particular report program run faster, you could just manually load the file (e.g. . `LOG DSK2:MYFILE.DAT[123,222]` ) before running the program. It must be noted that this is only practical for files that are not updated by a program. Any updates would be written to memory, not disk. Caution should be exercised to make sure you don't inadvertently leave the file in memory and then run a program that performs updates on it, thinking the updates were being written to disk. ## **Comments** AUTO_MEMOPEN also applies to sequential input files ( `OPEN #CH, FILE$, INPUT` ) and LOOKUP. See DEVICE for details on defining the MEM: device. A-Shell Reference Page 190 ## **AUTOTPRINT** This option causes all PRINT statements in RUN programs to be treated as Proportional Font Text Objects. In other words, they will generate static text, proportional font controls. This can be useful for quickly establishing how well your application would work with all proportional fonts. (It can also be turned on and off with SET, i.e. `SET {NO}AUTOTPRINT` .) A-Shell Reference Page 191 ## **BRKALC** This option causes A-Shell to pre-fill random files with a repeating pattern of close square brackets "]]]]]]]]]]]]]..." when they are allocated. ## **History** - 2009 October, A Shell 5.1.1163: BRKALC outputs **all and only** brackets to the file. Previously, it output "MIAME" after every 27 brackets. This was useful in some cases for visually confirming that the file was allocated by A-Shell, but undermined one of the purposes of filling a new file with brackets (to make unwritten records sort to the end). The old documentation said: "This option causes A-Shell to pre-fill random files with a repeating pattern of close square brackets "]]]]]]]]]]]]]]]]]]]]]]]]]]]MIAME" when then are allocated. In the early days of A-Shell this was the default, but it is not necessary for AMOS compatibility and slows down (slightly) the process of allocating a new file, so it is now available only by setting this option." A-Shell Reference Page 192 ## **CRLF** (Unix only) This option forces A-Shell/Unix to terminate sequential file print lines with CRLF (e.g. 0x0D 0x0A) instead of the normal NL or LF (0x0A) used under Unix. There are two good reasons why you might want to use this option. One is in a situation where you are creating files under Unix that you want to share with some other operating systems that require the CRLF line terminators (like Windows, DOS, or AMOS.) Since the INPUT LINE statement is implemented under A-Shell in such a way as to throw away superfluous CR line terminators (if immediately followed by a LF), the addition of the extra CR on the end of print lines will not adversely impact A-Shell. The second reason is that you are having trouble getting your Unix printers to automatically supply the carriage return when goes with each new line. Although this can generally be handled by a filter, having A-Shell simply add the necessary CR for you is an acceptable approach in some cases. A-Shell Reference Page 193 ## **EFFUSR** This option (short for "Effective User") also applies only under Unix implementations, in which case it forces A-Shell to return the "effective user name" instead of the "login user name" in any function that requires this information such as the SYSTAT system command. A-Shell Reference Page 194 ## **EFS OPTION** _Reviewed August 2016_ ## Following are the various EFS_xxx options that may be used in conjunction with A-Shell's encrypted file system. |**Options**|**Description**| |---|---| |EFS_OUT_AMOS|This causes any output file (sequential) which is created using an DevPPN-style name
to be automatically encrypted. (e.g.
`OPEN #1, "REPORT.PRT", OUTPUT`)| |EFS_OUT_HOST|This causes any output file (sequential) which is created using a Unix-style name to be
automatically encrypted. (e.g.
`OPEN #1, "/tmp/report.prt", OUTPUT`)| |EFS_ALLOCATE|This causes theALLOCATEfunction (to create a contiguous file) to automatically
encrypt it.| |EFS_ALCINDEX|This causes the ISAM-A ALLOCATE'INDEXED command (to create a new ISAM-A file)
to automatically encrypt it.| A-Shell Reference Page 195 ## **EXTFIO** This option (short for "Extended File I/O") relaxes the normal A-Shell regulation that any file opened for RANDOM (contiguous) access must be an exact multiple of 512 bytes in length. This might be handy if you want to use ASB to read/write some kind of unstructured binary data. It also removes certain AMOS peculiarities which seem of dubious value, such as the automatic stripping of isolated carriage returns from strings in INPUT and INPUT LINE statements. A-Shell Reference Page 196 ## **FIELDEMU** (Windows only) This option causes A-Shell/Windows to emulate 'field' attributes (i.e. like the AM62A) rather than the 'mode' attributes which are otherwise normal under Windows (as well as the AM65 and VTxxx terminals.) In the normal 'mode' operation, all video attributes (such as reverse and underline) work just like dim and bright, except that the on and off commands cause a space to be output (unlike dim and bright, which do not.) That is, the attribute for a character is determined by the chronological sequence of attribute commands which preceded the display of the character. When the FIELDEMU option is active, the attribute for a character is determined by the position of that character on the screen relative to attribute on/off commands which may be embedded in the display. The chronological sequence of the commands has nothing to do with it. For example, consider the following statements: ``` PRINT TAB(-1,0); ``` ``` PRINT TAB(10,15);"What am I?"; ``` ``` PRINT TAB(10,9);TAB(-1,32);TAB(10,25);TAB(-1,33); ``` In field operation, the "What am I" string will appear in reverse video, even though the reverse ON command (-1,32) was sent chronologically later than the "What am I?" string. However, in mode operation, no reverse video will display at all, because no characters were actually displayed after the reverse video on command and before the OFF (-1,33) command. To allow the above program to work correctly in both field and mode environments, it should be changed as follows: ``` ? TAB(-1,0); ``` - `? TAB(10,25);TAB(-1,33);TAB(10,9);TAB(-1,32);` - `? TAB(10,15);"What am I?";TAB(-1,33);` The first TAB(-1,33) is superfluous in mode operation, and only serves in field operation to limit the screen flash that would otherwise appear when the TAB(-1,32) command is given. Since the TAB(-1,32) is sent before the "What am I?" string, as well as positioned to the left of the string, the string will appear in reverse in both field and mode environments. A-Shell Reference Page 197 Finally, the last TAB(-1,33); is superfluous in field operation (given that we already stored a reverse-off attribute in that position in the previous statement) but it is needed in the mode environment to prevent subsequently output characters from appearing in reverse. The sole purpose for implementing the `OPTIONS=FIELDEMU` feature is to allow programs that were written strictly for field devices (like AM62A terminals) to work properly under A-Shell/Windows. Previously, the only option available to prevent such programs from displaying their attributes all mixed up was to specify `OPTIONS=NOFLDATTR` , which simply disabled the field attributes. If your programs are able to run in both field and mode environments, then they will probably run faster and cleaner under A- Shell/Windows in the normal 'mode', since the performance advantage of certain field operations on a serial terminal (like moving a menu bar up and down) is lost in Windows where there is no noticeable screen I/O bottleneck. Two other notes about the implementation of field attributes: 1) unlike on the AM62A terminal, A-Shell will automatically terminate the field spillover effect at the end of the line, rather than letting the attribute spillover to the end of the screen. Technically this is incorrect, but it is so rare for software to be deliberately written to take advantage of that spillover, and so common for the spillover to produce an unwanted screen flash, that we decided this was an improvement. 2) A-Shell does not currently support the blinking attribute. Under A-Shell/Unix, the choice of Mode vs. Field is determined entirely by the choice of terminal driver, which in turn is determined by the TERM environment variable setting. A-Shell Reference Page 198 ## **FSPECNATIVE** _Added July 2017_ When set, the rules for converting filespecs which do not contain native directory separators are changed to allow more flexibility for native file specs. Under these rules, any character in the set of "<>(){};=/\" plus space, TAB, CR and NL, and comma— unless there is a "[" present—will cause the filespec to be interpreted as native (as-is). The only clean-up performed on such filespecs is to remove trailing blanks. If the blanks are followed by any non-blank, including a dot (extension), they are left as is. - " " See the A Shell forum topic FILE NAMES 6.1 AND 6.4 for a lengthy discussion of the issues, motivations and ramifications behind this. Same feature added to 6.5.1610.0. ## **History** - 2017 July, A Shell 6.4.1552: Function added to A-Shell A-Shell Reference Page 199 ## **GUI_SPC_IND** Turning on OPTIONS=GUI_SPC_IND causes PRINT statements to be "tokenized" so that each token is positioned at the place where it would have been positioned if using fixed pitch. It also converts tokens made of hyphens (---------) or equals signs (=========) to graphic horizontal lines. For more detail, see the examples under the topic OPTIONS=GUI_SPC_IND. A-Shell Reference Page 200 ## **HEXDEC** This rather strange option invokes two features related to "hexadecade" date notation (in which 1-Jan-2000 is coded as "0101A0", 15-Jun-2014 is "0615B4", etc.) which can possibly eliminate a lot of Y2K conversion programming in some legacy applications. The first feature causes the VAL() function (whether called explicitly or implicitly, by assigning a string to a numeric variable) to accept a single leading hex digit. Thus, `VAL("A5")` would return 105. This may allow ASB routines which add and subtract dates to continue to work, even with hexadecade format dates. The second feature causes PRINT to scan the output for strings which look like hexadecade dates (e.g. ##/##/A#) and convert any such pattern to the 'standard' notation. For example, `PRINT "12/15/A2"` would display 12/15/02. This feature may eliminate much of the need to manually clean up the output when switching to hexadecade date format. Note that all of the above would probably only make sense if you were also using INFLD’s hexadecade feature. The HEXDEC PRINT formatting logic also applies to XCALL PRINT. A-Shell Reference Page 201 ## **LATIN1** (Windows only) This option applies only when the (now deprecated) Miame Terminal font is being used. When invoked, it causes A-Shell to re-map the OEM character set used by the Miame Terminal font to implement the ISO 8 bit Latin1 international character set. By setting your Windows keyboard format to US International or equivalent, you can use the Windows compose sequences to input accented characters, and A-Shell will properly save them so that they will be displayed properly on any display device supporting the Latin1 character set. Note that the Miame Terminal font is no longer recommended. For more information on fonts, see the system parameter FONT. A-Shell Reference Page 202 ## **NOAUTOX** Disables auto expansion of ISAM and INMEMO files (same as NOISAM_AUTOX). The auto-expand feature can be turned off for individual files by creating a .NOX file in the same directory where the .IDX and .IDA files reside. If they are in different directories, create a .NOX file in each location. Note: - If you have multiple IDX files, you will need a .NOX for each (unless you only want to disable the auto-expansion for a - specific IDX). - The .NOX file does not have to have any size. You can create it with the MAKE command (to create a 0 byte file), or with VUE - or whatever. It is just the presence of the file in the directory that matters. - All auto-expansion operations, including those disabled due to the NOX file, will be recorded in the ashlog.log file. A-Shell Reference Page 203 ## **NOFLDATTR** (Windows only) This option (short for "No Field Attributes") causes A-Shell to "throw away" screen attributes that are field oriented (such as TCRT functions 32,33,34,35, etc.). The motivation for this would be to avoid screen attribute chaos when running an application on a "mode" display device (such as a VGA monitor,) when the application was only written to support "field" terminals. See FIELDEMU above for a more sophisticated way of dealing with this problem. Note that `OPTIONS=NOFLDATTR` is equivalent to `FLDATTR = OFF` . A-Shell Reference Page 204 ## **NOSPACEATTR** The switch OPTIONS=NOSPACEATTR eliminates the automatic space associated with the on/off field attributes (TCRT commands 21,22,30-35,100-105). Currently this only applies to the AM75{G} Unix emulation, and was implemented to provide compatibility with applications developed with a very old AMOS terminal driver standard in which mode emulation drivers did not automatically add the space which otherwise was added by field terminals directly. Note that if OPTIONS=NOSPACEATTR on the server side, the option will be automatically forwarded to ATE. A-Shell Reference Page 205 ## **NOWHEEL** This setting OPTIONS=NOWHEEL disables the otherwise automatic conversion of the mouse wheel events into UP/DOWN-ARROW key presses when the focus is not on a control that captures the mouse wheel directly (such as XTREE, multi-line INFLD, etc.). The default behavior allows you to use the mouse wheel to scroll within certain environments that are otherwise text-only (like VUE). But in some cases the default behavior is undesirable, for example: - On laptops with sensitive mouse pads, you may get spurious cursor motion just from brushing your palm against it (very - annoying in VUE). - In screen contexts where there may be a mixture of controls that scroll (like XTREE) and those that don't (like a single line - INFLD), users may attempt to use the mouse wheel with the intent to scroll an object like XTREE, when in fact the focus is on a control like INFLD where the conversion of the mouse wheel to an UP/DOWN-ARROW may trigger unwanted exitcodes (3 & 5), leading to further confusion. Note that VUE supports its own version of this switch (in the ini.vue and command mode) MOUSEPOS , which see for information on the relationship of this setting and that one. Also, the mouse wheel is disabled in INFLD self-combo fields (which exit on the first down arrow key); otherwise it is too easy to end up with several additional down arrow key events which would then be interpreted according to logic impossible for the user to predict. Self-combos within XTREE continue to operate as before. ## **History** - 2020 June, A Shell 6.5.1681: NOWHEEL now also disables the mouse wheel within a combo box field. A-Shell Reference Page 206 ## **NOXABORT** (Windows only) This option prevents a user from closing the window while a program is running by clicking on the "X" button or hitting ALT-F4. With or without this option, such an action will bring up a dialog box warning the user about the reasons not to abort that way and suggesting the proper way to exit. But without this option, the user can choose to ignore the warning and click on the "OK" button to proceed with the abort anyway. With this option, the "OK" button is deactivated. See XABORT option. A-Shell Reference Page 207 ## **NTTS** (Windows only) This option forces A-Shell to identify instances in the same way that it does if it detects the presence of NT Terminal Server (or the subsequently renamed Windows Terminal Server, aka Remote Desktop, aka RDP). This would also apply to non-Microsoft remote client variations such as Citrix and possibly other environments which don't fall into the typical peer-topeer or ATE models. Without this option, you may end up with multiple instances assigned the same ID, causing them to clobber each other in the job table. The downside is that it prevents multiple instances running on the same client from sharing an A- Shell license. A-Shell Reference Page 208 ## **RC_DIMX** This switch tells the compiler to allow DIMX statements in /RC mode. DIMX is not supported by AMOS, so this doesn't make sense, but it may be useful in cases where you know you won't try to execute the DIMX statement but just want to have a single copy of the RUN program that runs on AMOS and A-Shell. A-Shell Reference Page 209 ## **SBX_RUNDIR** This option alters the search path for SBX subroutines, replacing dev:[p,0] with the current RUN file location. Normally, the search is: current [p,pn], [p,0], BAS: When OPTIONS=SBX_RUNDIR set, search is: current [p,pn], .RUN location, BAS:. ## **See Also** - SBX Loading and Cacheing A-Shell Reference Page 210 ## **SEQLOK** (Unix) This option enables locking on sequential files when LOKSER is enabled. In old versions of A-Shell, sequential files under Unix were not subject to locking rules (other than VUE, which implements its own locking scheme). A-Shell Reference Page 211 ## **STRICT** This option causes A-Shell to emulate some of the more restrictive characteristics of AMOS that are not always wanted. (The presumed motivation would be to prevent you from getting too comfortable with bypassing such limitations, making it difficult to port back to AMOS.) As of Build 791, the only example of this is the "protection violation" error you get when trying to write to a file outside your project. (Since neither Windows nor Unix has any such arbitrary restriction, A-Shell normally ignores it.) But if you want to a "protection violation" whenever you attempt to write outside your project, then set OPTIONS=STRICT. A-Shell Reference Page 212 ## **TRKTOPSTS** This causes PolyShell to treat the top status line as part of the screen, to be saved and restored when switching sessions. Note that this behavior is automatic for the bottom status line, but the top status line by default is intended for messages that are associated with the user or terminal, rather than the session. A-Shell Reference Page 213 ## **XABORT** (Windows only) Without this option, an attempt to close the A-Shell window by clicking on the "X" button or hitting ALT-F4 while a program is running, will display a dialog box warning you of the reasons why this might not be a good idea. If you ignore the warning and choose to abort anyway, the program will be aborted without any good chance of recovery. (See NOXABORT to prevent that possibility.) OPTIONS=XABORT presents a different approach by generating an ASB error #255 instead of displaying warnings. Then your ASB program can decide the best way to handle the situation, possibly by ignoring the error, possibly by closing the program gracefully and then exiting A-Shell. A-Shell Reference Page 214 ## **XTAUTOFILTER** _Written July 2023_ - This option enables auto filtering for all XTREE calls, eliminating the need to set the XTF2_AUTOFILTER flag on each individual XTREE. Note, however, that when the feature is enabled globally this way, but not explicitly for the individual tree (via XTF2_AUTOFILTER), then the initial state of the filter buttons will be hidden, but can be activated (made visible) via the context menu. This is intended to make it easier to enable auto-filtering globally without having to worry about the overcrowding of narrow column headers or general clutter caused by the filter buttons in trees where filtering may not be important. As with most other MIAME.INI options, you can also query and/or set the option via the MX_GETOPTIONS, MX_SETOPTIONS calls, here using the flag GOP2_XTAUTOFILTER flag (&h40000000). Also note that in the ATE environment, the flag is automatically passed from the server to the client. A-Shell Reference Page 215 ## **POLYKEY** _Updated August 2015_ ## **POLYKEY=key (or ^key)** ``` Examples: POLYKEY=^W (Control W) POLYKEY=| (vertical bar) ``` POLYKEY defines the hot key that can be used to switch between sessions, but there are two completely different cases: • PolyShell Server Side: If the server session of A-Shell is running PolyShell, the key is transmitted to the server where it triggers a switch between server-side sessions. The key will be "hot", except when you have shelled out via HOST.LIT or HOSTEX.SBX, or when running in GUI mode. Also see SWAPKEY. • Client Side: If the server session is not running PolyShell and the client is ATE, or in an A-Shell/Windows standalone or P2P environment, then the key is processed on the client side, causing the next A-Shell/Windows or ATE instance in the task list to be activated, put on top, and given the focus. If there are only two such instances, the key will toggle between them, equivalent to ALT+TAB. If there more than two such instances, repeated uses of the key will advance you through the set of sessions in sequence. You may also use CTRL+TAB as an alias for the same operation. ## **History** - 2012 August, A Shell 1255: Support for the Client-Side switching added. A-Shell Reference Page 216 ## **PRINTER** ## **PRINTER={,screen pict ptr{,NODLG}}** ``` Examples: PRINTER=LASER ``` ``` PRINTER=LASER,MYJET ``` ``` PRINTER=LASER,MYJET,NODLG ``` PRINTER is used to define the A-Shell default printer, i.e. the printer to be used if no printer name is specified in a SPOOL or PRINT command. This name specified is the name that the printer is to be known by within your applications (i.e. the AMOS Spooler Name). To get further configuration information about the specified printer, including how it is known to the operating system, printer ini files are used. See Printer Configuration for further details. Optionally, you may define a separate printer name that will be used for screen pictures only. If defined, the screen picture command (CTRL+P) will skip past the printer selection, saving precious keystrokes when taking screen pictures. You may also specify a third parameter, the keyword "NODLG" (not case sensitive) which complete eliminates the screen picture dialog options; it just sends the screen picture to the specified printer with no option to add a comment, view it, opt not to delete the picture file, etc. See Screen Pictures for more details. A-Shell Reference Page 217 ## **QUEUE** ## **QUEUE=,MEM: | DISK:** ``` Unix Example: QUEUE=100,MEM:C:\VM\MIAME\QFLOCK.SYS ``` ``` Windows (or Unix) Example: QUEUE=100,DISK:C:\VM\MIAME\QFLOCK.SYS ``` A-Shell uses a pool of "queue blocks" to keep track of locks and other shared system resources. While AMOS uses the queue for a variety of operating system functions, including LOKSER, A-Shell uses it primarily just for maintaining locks placed by XLOCK, FLOCK, and similar custom locking subroutines. (LOKSER-style locks are handled directly by the native operating system.) Thus, the required number of queue blocks is simply the maximum number of concurrent XLOCK and FLOCK (or similar) locks. Specifying an unnecessarily large queue file will have a _minor_ impact on performance. The queue may reside either in memory (MEM:) or on disk (DISK:), though as of A-Shell 4.8, memory based queues are only supported under the Unix versions of A-Shell. (A-Shell 4.9 adds the capability for A-Shell/Windows.) Memory queues are quite a bit faster, but this is not significant unless your application makes a large number of XLOCK or FLOCK calls. Whether QFLOCK is disk-based or memory-based, a complete pathname (including filename) must be given. The name is usually qflock.sys, and it must reside in a directory accessible by all users, typically the same directory where the shared miame.ini is located. Memory based queues are implemented under A-Shell/Unix as memory-mapped files, so even though all accesses are performed in memory, the file will appear in the directory. (In addition, a small control file named qflock.lck will be created in the same directory.) ## **Notes** The QUTL utility may be used to display the contents of the queue, as well as to manually remove locks placed by another user. The queue file is created automatically by the first user to launch A-Shell, and deleted automatically by the last user to exit (provided there are no locks currently in use). On a normal exit, A-Shell will purge the queue of all locks owned by the current user, but if a job or user should crash out of A-Shell for whatever reason, locks may be left in the queue. (Use QUTL.LIT to manually remove such locks.) Should the queue file become corrupted, it can always be removed manually (provided it is not currently in use) since the next user will recreate it. A-Shell Reference Page 218 Prior to Build 4.6, the qflock.sys file also held two records for each job which functioned like the job table records under AMOS. As of Build 4.6, this information is kept in a separate file called jobtbl.sys. The jobtbl.sys file is also created and deleted automatically alongside qflock.sys. See MAXJOBS. If, for some reason you have to manually delete one of them, it is best to delete them both. **Warning:** Although these files will be recreated automatically, they should not be removed while there are active users! Removing a disk based (DISK:) qflock.sys will cause all locks for any current users to disappear. Removing a disk based jobtbl.sys file will cause existing users to abort with a " _jobtbl/queue zapped_ " error the next time they execute a command or perform any function that updates the job accounting information. Removing memory based (MEM:) versions of these files (by deleting them from the disk directory) will not appear to affect currently running users, since they will continue to use the copy in memory. However, the next user to launch A-Shell will create new copies of these files in memory, leading to a situation where there are two (or even more) "pools" of users that don't know about each other. Locks placed in one "pool" will not be visible in the other, which could lead to file corruption due to locking failure. So if there are any users currently running A-Shell (even if they appear to be "dead") it is preferable to manually remove the users (either with the QUTL.LIT "ZAP" function or via the operating system) before deleting the jobtbl and qflock files. The maximum number of queue blocks is 65,535. A-Shell Reference Page 219 ## **QUITKEY** ## **QUITKEY=key (or ^key)** ``` Examples: QUITKEY=^\ (Control backslash) QUITKEY=~ (tilde) QUITKEY= (no quit key) (default) ``` (Unix only) QUITKEY defines the key which Unix uses to abort a running process. Normally, the Unix "Quit" key is CTRL+BACKSLASH. Hitting this key while a process is running causes the SIGQUIT signal to be sent to the process. Since this signal is un-trappable, it invariably causes the process to abort with a core dump. The only defense an application has against this key is that it can be redefined or even disabled (prior to it being used.) Because of the obvious danger posed by the ability to abort A-Shell and cause a core dump just by hitting a key, the default is for the key to be disabled while A-Shell is running. A-Shell Reference Page 220 ## **SSD** ## **SSD=nnn-nnn-nnn-nnn-nnn-nnn-nnn-nnn** This parameter is more for programmers of A-Shell than end users. A-Shell contains a rudimentary but effective SSD emulator, which enables the eight numbers returned by the SSDIAG program to be exactly specified. It is these numbers, padded with leading zeros to three digits, which follow SSD on the command line. It is not a true SSD simulator since it is not based on an actual SSD number, but it does enable the same PIC code to be used for any software protected by a real SSD by simply specifying the same sequence of numbers as returned by SSDIAG.RUN on that machine. The SSD emulator does not emulate all aspects of the SSD, so it is important that the SSD is written to and read from in the same manner as by the SSDIAG program. The read/write sequence (in ASB) required is: ``` io(514) = 0 ``` ``` for SSD'LOOP = 1 to 8 ``` ``` io(514)=(2^SSD'LOOP)+1 print io(512) ``` ``` next SSD'LOOP ``` Failure to use this read/write sequence within an application will still generate a unique PIC on each A-Shell machine, assuming they are given differing eight-number sequences. In this case, however, it is not guaranteed that if the eight numbers produced by SSDIAG from a real SSD are used, that the PIC used on the original machine will in fact work on the machine running A-Shell. A-Shell Reference Page 221 ## **SBR** ## **SBR=optioncode {,optioncode} {,optioncode}** SBR is used to specify various configurable subroutine options to account for local variations in some otherwise standard subroutines. These variations are typically the result of someone modifying a standard subroutine to suit their purposes. An example of this the subroutine COMMON, which many people have modified to change the number and size of the saved modules. Rather than have several implementations of each subroutine which can differ, various SBR options can be specified to tune the operation of such subroutines. |**Option**|**Description**| |---|---| |AMOSJOB1|Causes JOBNAM to return the name of the parent job.| |AMOS_RUNSBR|Deprecated. Use OPTIONS=ASHELL_RUNSBR
.| |AUTO_DLG_MAX|Maximizes dialogs, helpful for tablets and net-books.| |AUTO_TABX|Automatically converts all Tab controls to TabX controls.| |AXLOCK|Causes A-Shell to duplicate the behavior of XLOCK under AMOS.| |BSMID5|Affects sequential search in SERCH.| |BUBBLESORT|Obsolete, but documented by way of explanation.| |CCYY|Affects the way INFLD and IDTIM guess at the century.| A-Shell Reference Page 222 |**Option**|**Description**| |---|---| |COMMONNDR|Non-destructive read in COMMON.| |EZPRTX|Causes EZTYP to use EZPRTX.| |GETOFD_NOCOM|Use old style Open/Save File dialogs inMX_GETOFD
.| |GET_CRNL2CR|Automatically sets the &h02 flag inXcall GET
.| |INFLD_V1|Eliminates the need to specify the V parameter to INFLD.| |INFDEF|Specifies type codes to INFLD.| |INFLD143|Affects the operation of
**J**justified types in INFLD.| |INFLDB3|Causes INFLD to add blank spaces for comma-formatted fields.| |INFLDCBRJ|Right-justifies text label.| |INFLDEDIT|Provide support for a variation of INVUE.| |INFLDLDROP|Special handling for type "L" operation in INFLD.| |INFLD_KEEPALIVE|Sends a few bytes every 15 seconds while waiting for input.| A-Shell Reference Page 223 |**Option**|**Description**| |---|---| ||| |INFLD_PRINTS|Maps ^P to File > Print Screen rather than to the text-based screen print/capture.| |INFLD_NOPRINTS|Disables ^P screen print function..| |VINFLDPS|Impacts the operation of types "P" and "S" inINFLDXS.| |LSTLINSTRIP|Strips comments from command line before returning them toLSTLIN.LIT.| |MALLOCSORT|Affects the memory allocation strategy ofBASORTXS.| |MESAGRTN|Changes behavior ofMESAG.| |MSGNUM|Changes the number of packets available toCOMMONXS.4| |MSGSIZ|Changes the size of each packet available toCOMMONXS.| |MXLOCK|ForcesAG_XLOCKto conform exactly to standard documentation.| |PCKLST_GUI|Use XTREE (GUI) in place of PCKLST (text)| |PRINT_TIME|Allow for the time to be added to the report header.| A-Shell Reference Page 224 |**Option**|**Description**| |---|---| |PRINT_JOBUSN|Allow for the user name to be added to the report header.| |PRINTNOFF|Eliminates form feed character in PRINT.| |PRTCHK1|Causes PRTCHK to return 1 if printer is found, 0 if it is not.| |SUBMIT2|Forces a new process to be the grandchild of the current process.| |TRIMCTL|Causes TRIM to remove leading and trailing control characters.| |TTI_PGRW|Affects how INFLD type codes
**$**and
**H**are handled.| |XMASCB_OPEN|Optimizes file open/close in XCALL xMASCB, ignores redundant open, explicit close;
auto-close at program end.| |XPPPNOCT|Affects how XPPN displays PPN value.| |XTREE|Enables various operations for all XTREEs.| A-Shell Reference Page 225 ## **AMOSJOB1** This causes the JOBNAM subroutine to return the name of the parent job rather than the current job, when the current job was launched via ASHELL[XS] and the ASHELL_RUNSBR switch is not active. This mimics one aspect of the way Xcall AMOS worked under AMOS—i.e. that the child process was still the original job. Note that under A-Shell, the child process is truly a separate job and thus cannot share any memory based information, unless the ASHELL_RUNSBR switch is active. A-Shell Reference Page 226 ## **AXLOCK** The AMOS version of XLOCK has a bug in which an attempt to get a wildcard lock (e.g. X,0) will appear to succeed (i.e. return MODE 0) even when you already have a conflicting lock (X,Y). One could argue whether a lock previously set by the same user should be considered a conflict or not, but it is hard to justify returning a status of success when the wildcard lock was, in fact, not set due to the conflict. Yet, in the rarified world of programming, there are those that consider this a feature rather than a bug. For those, we have the AXLOCK option, which causes A-Shell to copy the AMOS bug. For all others, the default behavior is to return an error status (MODE set to your own job number) to indicate that there was a conflicting lock, set by yourself, and that the wildcard lock request was not set. Note that there is a similar issue relating to how to handle a request to obtain a lock that you already have, for which the MXLOCK switch was created. A-Shell Reference Page 227 ## **AUTO_DLG_MAX** This option causes AUI_CONTROL to automatically maximize any newly created dialog which is larger than the screen size (for single monitor systems). The intent is to help existing dialogs conform better to net book and tablet environments whose screens are smaller than the dialogs were originally designed for. Maximizing in this case actually reduces the size of the dialog, and scales all the controls within it accordingly. If the dialog is small enough to fit, but is partially off the screen, it is shifted so as to be entirely visible. ## **History** - 2012 December, A Shell 6.1.1329: Modified to work on multi-monitor systems. It now operates relative to the monitor over which the center of the dialog (in its original coordinates) appears. - 2011 April, A Shell 5.1.1214: Added to A-Shell. A-Shell Reference Page 228 ## **BSMID5** This option affects the operation of the sequential search (BSMID=5) in the SERCH subroutine. If specified, then the sequential search begins at the record following the current record in the file. This is the normal operation in the U.S. If omitted, then the sequential search begins at the current record, which is the normal operation in the UK. A-Shell Reference Page 229 ## **BUBBLESORT** This option no longer has any effect. Historically, it was used to force BASORT to use the bubble sort algorithm, which was slow but didn't rearrange records with equal keys, like the other algorithms used to do. All of the sort algorithms now preserve the order of records with equal keys, eliminating any need for bubble sort. A-Shell Reference Page 230 ## **CCYY** ## **CCYY:##** (default ## = 60) This code affects the way subroutines with date logic (e.g. INFLD, IDTIM, MATCH, etc.) guess at the century when only provided with a two digit YY. The two digit number (##) sets the minimum year which will be assumed to be part of the twentieth century. Any year below that will be assumed to be part of the twenty-first century. For example, if you specify `SBR=CCYY:25` and then supply a date to such a subroutine like 09/15/22, it will be treated as 15-Sep-2022. However, if the date you enter is 09/15/25, then it will be treated as 15-Sep-1925. This can be useful as part of a simplified workaround to the Y2K millennium problem in applications where the range of dates being dealt with is significantly less than 100 years. For example, a typical accounting system is only concerned with dates within a range of a few years. However, note that by itself, it doesn’t do anything for you unless you are storing your dates in some kind of format which can support century information. For example, if you are taking the result of IDTIM and storing it in a 4 byte binary format, or if you are using the INFLD type "j" to return the date in Julian format, then this CCYY trick can be helpful. But if you are merely calling INFLD to get a date in MMDDYY format and are then storing it in your files as MMDDYY, the CCYY trick doesn’t do anything for you except correctly determine whether 02/29/00 is valid or not; 02/29/2000 is but 02/29/1900 is not. For subroutines other than those explicitly referenced above, check the specific documentation to see whether it recognizes the SBR=CCYY:## setting. A-Shell Reference Page 231 ## **COMMONNDR** This option stands for "COMMON Non Destructive Read". Normally, a read operation in the COMMON subroutine destroys the packet, requiring it to be rewritten before it can be read again. However, some developers apparently got their hands on a version of COMMON, in days of yore, which did not have this unfortunate characteristic, and thus were eternally grateful for the addition of this sensible option. A-Shell Reference Page 232 ## **GETOFD_NOCOM** _Added February 2021_ ## **SBR=GETOFD_NOCOM** (Windows) This option controls whether to use the Open/Save File dialogs as implemented in A-Shell 6.5.1698.0: When specified, A-Shell uses the older implementation of the Open/Save File dialogs in MX_GETOFD along with internal operations like File > Load. The default (i.e. when not specified) is to use the new implementation. ## **History** - 2021 February, A Shell 6.5.1699: Added to A-Shell. A-Shell Reference Page 233 ## **EZPRTX** This option causes the EZTYP print file preview utility (aka EZVUE) to use the customizable SBX subroutine, EZPRTX, in place of its own logic for printing of a selected range of pages. This allows more sophisticated or application-specific printing logic to be used in place of the generic logic within EZTYP. For example, you may want to use different printer selection logic, or add logic to embed printer control codes into the selected pages to be printed. The source code to a generic sample version of EZPRTX.SBX is included in EZPRTX.SAM in [7,376]. Use it as the basis for your own customized version. There are additional notes in the source code about parameters and other technical details. A-Shell Reference Page 234 ## **INFLD_V1** This code eliminates the need to specify the V parameter to INFLD. Otherwise, if you fail to specify V, INFLD doubles the row. This is an historical artifact going back to the invention of the 24 row display, which doubled the size of the previous 12 row displays. A-Shell Reference Page 235 ## **INFDEF** ## **INFDEF:{string}** Under AMOS, the INFLD subroutine supports a defaults file infld.def. This is used to contain default type codes which are always appended to any codes in a call to the INFLD subroutine. Under A-Shell, the same is achieved by specifying these type codes after a colon with the INFDEF patch. A-Shell Reference Page 236 ## **INFLD143** This code affects the operation of J justified types in INFLD. If specified, then a null input to a J-type field, as distinct from an explicit input of zero, will return ENTRY padded with spaces to _xmax_ , e.g. ‘ ’. This conforms to the operation of INPUT.SBR as supplied with AlphaACCOUNTING in the UK. If INFLD143 is not specified, then a null input would return ENTRY padded with zeros, e.g. 000000. This conforms to the operation of the assembly language subroutine as supplied by MicroSabio for AMOS. A-Shell Reference Page 237 ## **INFLDB3** Later versions of INFLD.SBR, and the C version used in A-Shell, output spaces to blank the fringe of comma-formatted numeric input types, dependent on the input size, decimal point specification, and so on. The old AlphaACCOUNTING INPUT.SBR subroutine (and very early versions of INFLD.SBR) were not so intelligent about this matter. For comma-formatted types (specifically $ type financial fields), they just output three blanking spaces regardless of field size. To accommodate older software, the INFLDB3 code has been implemented. If specified, INFLD will blank three spaces for comma formatted fields (‘M’, ‘$’ and ‘H’) to the right or left according to justification. Otherwise the number of spaces to blank will be determined exactly as a function of field size. Note that INFLD "prehistoric compatibility mode," which causes to INFLD to mimic nearly all of INPUT'S shortcomings and idiosyncrasies, and which can be invoked with SBR=INFDEF:|P, will also accomplish this effect. A-Shell Reference Page 238 ## **INFLDCBRJ** This parameter, INFLD Checkbox Right Justify, can be used to right justify the text label associated with an INFLD-created checkbox ( _type_ **|c** ). Without _type_ **R** , the text goes on the left and the box on the right; _type_ **R** reverses that. But in either case, the text itself is normally left justified within its space. `SBR=INFLDCBRJ` will force it to be right justified in its space. A-Shell Reference Page 239 ## **INFLDEDIT** The INFLDEDIT code may be used in conjunction with `ALIAS=EDIT:INFLD` to support a variation of INVUE.SBR written by Pat LaFollette that goes by the name EDIT. EDIT is very similar to INVUE, with the main difference being the return parameter. A-Shell Reference Page 240 ## **INFLDLDROP** The INFLDDROP code affects the operation of **L** type in INFLD. The default for an L type field is for the right arrow to move across the field until it hits the end, and then it exits, setting the appropriate exit code. With INFLDLDROP set, it exits immediately. A-Shell Reference Page 241 ## **INFLD_KEEPALIVE** (Unix) This sends a harmless byte sequence every 15 seconds while waiting for input within INFLD, which includes the dot prompt and ASB INPUT statements). This serves two purposes. First, it will prevent connections from being dropped due to lack of activity while they are actually in a program waiting for input. Second (and perhaps more important), it provides a mechanism for Unix servers to detect connections that have been dropped (without having to wait for the standard keep-alive timers to expire, which by default may run to 2 hours). This way, within 15 seconds of the connection being dropped, the server will send a packet, which cannot be delivered. This should trigger a retry timer which will try to resend the packet some number of times before concluding that the connection is dead. This process is generally much quicker than the keep-alive detections process. Note that under Unix, the retry timers are controlled by two files in the /proc filesystem: /proc/sys/net/ipv4/tcp_retries1 and tcp_retries2. The default values of 3 and 15, respectively, may be large for your liking, possibly taking as long as 15-30 minutes to close the dropped connection. You can set them as low as 1 and 2 for nearly immediate detection, at the possible risk of prematurely judging a temporarily sluggish connection to be dead. There are being many sites on the web with good documentation about the files in the Linux /proc filesystem. A-Shell Reference Page 242 ## **INFLDPS** The INFLDPS code affects the operation of **P** and **S** types in INFLD. The default is for a **P** type field to be a U.S.-format phone number, and an **S** type field to be a secure (non-echoed) input. This conforms to the operation of the standard AMOS version of INFLD. If INFLDPS is specified, then the meanings of the two types are reversed. This corresponds to the operation of INPUT.SBR with AlphaACCOUNTING in the UK, which uses type **P** for non-echoed passwords. A-Shell Reference Page 243 ## **LSTLINSTRIP** The LSTLINSTRIP code causes comments to be stripped from the end of command lines before returning them to Xcall LSTLIN. Note that this occurs inside LSTLIN so it does not apply to use of the CMDLIN system variable to retrieve the command line. A-Shell Reference Page 244 ## **MALLOCSORT** This code affects the memory allocation strategy of BASORT. Normally, BASORT uses only the "impure" memory within the user’s pre-allocated memory partition to perform the sort. Depending on how much is available, it decides between a pure quick sort (entirely in memory), a quick sort of a tag file of the keys, followed by a one-pass reordering based on the sorted keys, or in the worst case, the dreaded poly-phase merge in which the file is broken into pieces which are individually sorted and then merged back together. When MALLOCSORT is specified, BASORT will attempt to temporarily allocate as much memory as it needs (within reason) to perform the fastest possible sort. This only makes sense under Unix and Windows, where it is highly recommended, since it may dramatically speed up sorting in these environments which typically have lots of memory available for temporary use. ## **See Also** - MALLOCLIMIT A-Shell Reference Page 245 ## **MESAGRTN** The normal operation of MESAG is such that a message type 1 is displayed followed by `CR TO RECOVER` , and a message type 2 followed by `CR TO CONTINUE` . If the MESAGRTN code is specified, then the operation of both these message types becomes identical, and they are displayed followed by `Press Return` . Also note that the text of this and other subroutine messages can be edited directly in SBRMSG.. A-Shell Reference Page 246 ## **MSGNUM** ## **MSGNUM: ** This changes the number of packets available to the COMMON subroutine to the value specified after the colon. The default number of packets is six. A-Shell Reference Page 247 ## **MSGSIZ** ## **MSGSIZ: ** This changes the size of each packet available to COMMON to the value specified. It may be used with the MSGNUM setting to tailor the implementation of COMMON to match that of equivalent AMOS installations. The default packet size is 150 bytes. A-Shell Reference Page 248 ## **MXLOCK** The XLOCK subroutine normally returns the job number of the job which is in possession of a lock in the MODE parameter, if an attempt is made to create a conflicting lock. Under AMOS, if an attempt is made to duplicate a lock which your job already owns, then a MODE of zero is returned, indicating success, even though no extra lock information is created. This, although contrary to the standard documentation, is the default operation under A-Shell. If the MXLOCK code is specified, then the operation of XLOCK conforms exactly to the standard documentation. An attempt to create a lock which conflicts only with a lock possessed by your own job, will still return a non-zero MODE, the job number of your own job. A-Shell Reference Page 249 ## **PCKLST_GUI** This switch causes PCKLST to use the GUI interface of XTREE. It is not quite the same as using `ALIAS=XTREE,PCKLST` , but very close. A-Shell Reference Page 250 ## **PRINT_JOBUSN, PRINT_TIME** These options allow for the time and/or user name to be added to the report header: ``` SBR=PRINT_TIME ; Add time (hh:mm am) to date in header ``` ``` SBR=PRINT_JOBUSN ; Add user name to date in header ``` If either option is selected, the "Run Date: mm/dd/yy" header string will be shortened to just "mm/dd/yy" with the time and/or user name appended. Note that the user name may be truncated to as few as 6 characters depending on the paper width and whether the time was also displayed. Also, if both are selected, the report title and coname strings will be truncated to 46 characters (down from the previous maximum of 50). A-Shell Reference Page 251 ## **PRINTNOFF** This switch affects the operation of PRINT and leading form feeds. In the default case, PRINT would put a leading form feed character at the top of the file. Under AMOS, this would generally not result in an extra blank page, due to a peculiarity of the AMOS spooler. However, under most other platforms, it probably would cause an extra leading blank page. To eliminate those, set `SBR=PRINTNOFF` . A-Shell Reference Page 252 ## **PRTCHK1** Some versions of PRTCHK return 1 if a printer is found and 0 if it is not. To get this behavior, add `SBR=PRTCHK1` to miame.ini. A-Shell Reference Page 253 ## **SUBMIT2** (Unix only) This switch affects the operation of SUBMITxs and SUBMIT.LIT, and the COMMAND parameter in printer initialization files. Each of these operations involves the Unix fork() function to create a child process in order to run a command outside the current process. In the normal case, the new process is a direct child of the current process, which makes the current process responsible for burying the child when it dies. This is often not convenient, and can have either of two undesirable side effects. One is that the current process can get stuck waiting for the child to complete. The other is that if the current process exits before the child exits, the child will become a zombie. .) `SBR=SUBMIT2` causes A-Shell to use a two-level fork(), which results in the new process being a grandchild of the current process. The first child exits immediately, which makes the grandchild an orphan, to be adopted by the init process (pid 1). The end result is that the current process is relieved of its parental responsibilities, eliminating the two problems mentioned above. In the case of the COMMAND= option in the printer initialization file, a more straightforward benefit is that XCALL SPOOL returns immediately to the program, regardless of how long the process invoked via the COMMAND= statement takes to complete. Without `SBR=SUBMIT2` , SPOOL would wait for the child process to complete before returning. A-Shell Reference Page 254 ## **TRIMCTL** This switch causes TRIM to remove leading and trailing control characters, as well as blanks, from the string passed to it. You can also get the same effect by passing a second, numeric, non-zero valued argument to TRIM (e.g. `XCALL TRIM,A$,1` ). A-Shell Reference Page 255 ## **TTI_PGRW** This rather obscure switch activates certain adjustments to the way in which the _type_ codes **$** and **H** are handled in INFLD. It also activates CTRL+G as the help key in INFLD and SEL1. A-Shell Reference Page 256 ## **XPPPNOCT** This switch causes XPPN to adjust the value of the returned P (project) and PN (programmer number) values so that even though they appear in decimal as if they were octal. For example, if you are in PPN [100,377], it would normally return 64 and 255, since those are the decimal equivalents of the octal values 100 and 377. But with SBR=XPPNOCT, it will actually return the decimal values 100 and 377. Note however, that such numbers may not fit in a single byte, so the P and PN parameters should be at least 2 bytes long. A-Shell Reference Page 257 ## **XTREE** _Revised and reviewed July 2020_ The following SBR= options add the corresponding features to the XTREE right-click context menu, as a global shortcut to adding them explicitly using XTREE'S PopupMenu, which see for more discussion. |**Switch**|**Description**| |---|---| |XTREE_EXPCSV|Exports tree contents to comma separated file.| |XTREE_EXPTSV|Exports tree contents to tab separated file.| |XTREE_EXPOPEN|Launches player for exported file type.| |XTREE_PRINT|Prints the tree.| |XTREE_SRCH|Display windows "Find" dialog.| |XTREE_EXPCSV2XL|Exports tree contents to XLS format usingCSV2XL.SBX. Auto-
matically enables XTREE_EXPCSV2XLSX as well.| |XTREE_EXPCSV2XLSX|Like XTREE_EXPCSV2XL except outputs to XLSX format, and also
includes selected formatting attributes such as cell colors.| For example: ``` SBR=XTREE_EXPCSV2XL,XTREE_EXPOPEN,XTREE_SRCH ``` Note that some of these context menu functions, particular the search option, may conflict with editable cell validation, since interaction with function the may trigger the cell validation, causing the tree to exit before it can process the function. To avoid the confusion this may cause users, in some cases the option should be left off the context menu, unless it is added explicitly via the PopupMenu option; explicit PopupMenu options will override the corresponding XTREE_xxx global directives. ## **See Also** - XTAUTOFIILTER in System Parameters A-Shell Reference Page 258 ## **History** - 2020 June, A Shell 6.5.1682: Add XTREE_EXPCSV2XLSX - 2018 January, A Shell 6.5.1626: Add XTREE_EXPCSV2XL - 2012 December, A Shell 6.1.1326: Function added to A-Shell A-Shell Reference Page 259 ## **SWAPKEY** ## **SWAPKEY=key (or ^key or numeric value)** ``` Examples: SWAPKEY=^] (Control bracket) ``` ``` SWAPKEY=0xFF47 (F12) ``` (Unix with PolyShell only) SWAPKEY functions like POLYKEY, except for three important differences. The first is that the key is not truly "hot;" that is, it can only be used when the process is actually waiting for keyboard input. The second is that rather than swap you to the PolyShell menu, it will swap you directly to the next instance of A-Shell running under the control of PolyShell—or, the reverse if PolyShell is launched with the –x switch. The third difference is that, unlike POLYKEY, the swap key may be a multi-key sequence generated by a function key. To specify this, you can use octal, hex, or decimal notation to indicate the two byte value which is returned by the function key. Numbers beginning with 0x are treated as hex, those beginning with 0 are octal, and all others are decimal. For your convenience, here are the standard two-byte values for function keys in hex notation: |**Key**|**Hex**||**Key**|**Hex**| |---|---|---|---|---| |F1|0xFF75||F7|0xFF42| |F2|0xFF74||F8|0xFF43| |F3|0xFFD3||F9|0xFF44| |F4|0xFFC0||F10|0xFF45| |F5|0xFF40||F11|0xFF46| |F6|0xFF41||F12|0xFF47| A-Shell Reference Page 260 ## **SWAPWAIT** ## **SWAPWAIT=** ``` Example: SWAPWAIT=25 ``` (Unix only) This directive allows you to specify something other than the default wait within the terminal driver when swapping screens or screen sizes. Currently this only affects the Wyse50 driver, and was implemented because the standard wait is a full 1 second, which is apparently necessary on some versions of the terminal but not on terminal emulators. The main downside of the extra wait occurs within PolyShell, where it delayed the repaint of the new screen when swapping sessions. To allow this to remain as flexible as possible, the default value of zero simply causes the terminal driver to use its normal wait time (which in the case of wyse50 is equivalent to `SWAPWAIT=1000` . So to minimize the wait, set SWAPWAIT to 1. In order to allow this to be set on a terminal by terminal basis, SET.LIT supports a SET SWAPWAIT {#} subcommand. If the {n} value is specified, it sets the SWAPWAIT time, otherwise it displays the current setting. ## **See Also** • MX_GETSW, MX_SETSW A-Shell Reference Page 261 ## **TRACE** ## **TRACE=option {,option} {,option}** This setting can be specified to cause various types of debugging trace messages to be output during normal A-Shell operation. Unless otherwise noted, TRACE messages are output to the file ashlog.log, typically in the same directory as miame.ini, or as specified by LOGDIR. This file is automatically "rolled over" when it reaches a certain size (generally 3 MB), with several prior versions archived as ashlog.001, ashlog.002, etc. Trace messages written to the log file may also be output to the System Messages Window. Some of the traces output directly to the screen, or as noted in the table below. Most of these settings can be adjusted with SET.LIT, and all of them can be queried and set using MX_GETTRACE / MX_SETTRACE. Note also that for Windows and ATE, they can be enabled/disabled via the System Messages window mentioned above. It is recommend that you enable the INOUT, BASERR, and SIGHUP traces by default (e.g. `TRACE=INOUT,BASERR,SIGHUP` ) as they leave a trail of information that is very useful for reviewing system activity and researching errors without creating an excess number of log entries. The following table shows the options used with the TRACE function. The "Used In" column specifies if the option applies to the TRACE system parameter ("INI") or to the SET TRACE command ("SET"). |**Option**|**Used In**|**Description**| |---|---|---| |AMOS|INI, SET|Logs information related to the use of XcallASHELLand operations that involve the launching of another ashell session.| |AMSORT|INI, SET|Displays information (in a pop-up window) during sorting operations, showing the type of sort, current phase, memory
usage, etc. If sorts are talking a long time, this can be very useful for determining what is happening, and how much
memory you might need to improve the performance. (For very large sorts, we also offer an add-on "world class" sort
module that is much faster and more flexible, but requires a small license fee; contact us for details.)| |ATE|INI, SET|Logs details of the GUI commands and responses sent between a server and an ATE client. Note that this command
might make sense to activate on both the server and the client, as they have different perspectives. This will result in
two log files, one on the server and on the ATE client.and responses.| |BASERR|INI, SET|Logs all ASB errors, indicating if they were trapped or not, along with other details typically lost in the translation
between the user experiencing the error and the programming investigating it. Highly recommended for nearly all| A-Shell Reference Page 262 |**Option**|**Used In**|**Description**| |---|---|---| |||installations. BASERR| |CGI|INI,SET|Logs details related toCGIUTL. Also see XCALL and SOCKS traces.| |DEBUG|SET only|This is a catch-all for logging all kinds of information. It should only be used in focused circumstances, since the amount
of tracing data quickly becomes overwhelming. May also be activated via the –trace switch on the A-Shell command
line.| |ERS|INI only|same as "EFS."| |EFS|SET only|Traces the A-Shell stream (sequential file i/o) wrappers used when the Encrypted File System (EFS) is enabled. Also
sometimes "overloaded" to trace specific unrelated operations for debugging purposes, usually on a temporary basis| |EXEC|INI, SET|Traces RUN, CHAIN, command line and XcallASHELLstatements.| |FOPENS|INI, SET|Logs information about file opens (both programs and data). Under Windows, this also includes how many microseconds
it takes to open the file, which can sometimes be useful in identifying bottlenecks due to network issues.| |FUNCS|INI, SET|Activates automatic tracing of function and procedure calls.| |GDIPRT|INI, SET|(Windows only) Logs and/or displays information about processing of print directives.| |GUI|INI, SET|(Windows only) Logs details about various low-level GUI operations. It is quite verbose.| |INOUT|INI only|Writes debugging information toashlog.logas each new instance of A-Shell is opened or closed, indicating the number
of jobs running at that point. Highly recommended for virtually all installations.| |ISAM|INI, SET|Logs ISAM operations.| A-Shell Reference Page 263 |**Option**|**Used In**|**Description**| |---|---|---| |JOBLCK|INI, SET|Causes all unresolved lock/unlock operations on thejobtbl.sysfile to be traced in the filejobtbl.lck.| |JOBS|INI only|Logs details relating to the job table operations (quite verbose).| |KBD|INI, SET|Logs keyboard operations (quite verbose).| |LOCKS|INI, SET|Displays debugging information on the bottom status of the window related to record locking operations. In particular, it
provides a sense of how many retries or how long the job is waiting for access to a record. In the case of FLOCK, it will
also display all of the relevant locking parameters whenever the subroutine is forced to wait and whenever it exits with
a non-zero error code.| |LP|INI, SET|(Possible in INI context, but not recommended.) Displays on the screen details about printing, including processing of
any EZSPL configuration file, plus the printer init commands, plus the actual communication or initialization operations
with the printer itself. Extremely useful for debugging printing problems. (SET TRACE LP ON, then using PRINT to print a
dummy file, likeersatz.ini).| |MALLOC|INI,SET|Log details of all memory allocations.| |QOP|INI|Logs details relating to queue block operations.| |RW|INI, SET|Log all random/isam file reads and writes, INPUT and PRINT file operations, SERCH reads.| |SIGHUP|INI, SET|Log receipt of SIGHUP (hangup) and SIGTERM (kill) signals, along with information indicating how the signal was
responded to, whether the program and ashell session were shut down, etc. We recommend you set this switch
permanently inmiame.ini(TRACE=SIGHUP) since they should be relatively rare and frequently either worth
investigating directly, or they provide an explanation for something else you are investigating.| |SIGNAL|INI, SET|(Unix only) Same as the SIGHUP option, but also displays on the screen the name of any trapped signal received by the
process. SeeJob Terminations
for more information relating to handling of incoming signals.| A-Shell Reference Page 264 |**Option**|**Used In**|**Description**| |---|---|---| |SOCKS|INI, SET|Logs details about TCP (socket) operations, including those embedded in CGIUTL.| |SQL|INI, SET|Logs information about SQL operations.| |SYSERR|INI, SET|Display (in a pop-up window on screen) details about all errors. This is sometimes useful for see the system error
details corresponding to a particular A-Shell error, but can also be annoying since it presents the appearance of a
serious error having occurred, sometimes in situations that weren’t really very serious at all.| |USRMEM|INI, SET|Log details about "user memory" operations – i.e. loading of programs, subroutines, function key translation files, etc.| |XCALL|INI, SET|Logs most subroutine calls.| |XDEBUG|INI only|Increases the verbosity of several other traces.| |XTREE|INI only|Logs XTREE operations.| ## **See Also** • MX_GETTRACE, MX_SETTRACE A-Shell Reference Page 265 ## **SYSTEM MESSAGES WINDOW** To open the System Messages window, position the cursor anywhere in the A-Shell window except on a GUI control and press CTRL+SHIFT+DOUBLE-CLICK. The _A-Shell Developer Control Operations_ window will open, offering the following buttons: **Dump Control Info to Spreadsheet** outputs a list detailing all the current application-created controls in CSV format. This is mainly useful as an independent way (outside of looking at the application source code) of examining the attributes of the controls that aren't readily visible (bit flags, click codes, etc.) **Dump Menu Info to Spreadsheet** is like the previous option but for the application-added menu items. **Change Text Attributes** leads to a dialog allowing you to alter some attributes of the standard text used by PRINT statements. This is mostly useful for experimenting with approaches to systematically converting screens from text to GUI. **System Message Window** opens the System Message Window _._ See below for additional options once this window is open. **Print/Preview XTREE** outputs the currently active XTREE (if applicable) to a variation of the APEX preview/print utility, allowing the entire contents of the tree (not just the visible part) to be printed. ## **- A Shell System Messages Window** Right click on the window to get a context menu of options: - Use the _Properties_ dialog to enable/disable the display of system trace messages - Activating a checkbox option in the _Properties_ dialog is equivalent to turning on the TRACE of the same name (either in - miame.ini or via the SET command). - Any enabled system TRACE option will result in the corresponding messages appearing in the ashlog.log file, and, while the - _System Messages_ window is open, in that window as well. A-Shell Reference Page 266 - Unchecking the _Show System Traces_ option leaves the checked traces in effect (so they output to the ashlog.log) but stops - them from going to the _System Messages_ window. This might be useful in cases where you want to concentrate just on trace messages explicitly output from your application via TRACE.PRINT or DEBUG.PRINT statements. - Closing the _System Messages_ window does not deactivate any of the currently enabled traces; they continue outputting to the - ashlog.log file. - Clipboard operations: You can select/unselect individual lines in the _System Messages_ window by clicking on them, or by - using the _Select All_ option from the context menu to select them all. Use the _Copy_ option from the context menu to copy the selected lines to the clipboard. (From there, they can be pasted into other text editors, such as notepad or an email editor.) Since there are no integrated search or editing features, the recommend procedure for such is to select the desired lines (or all), copy to the clipboard, then paste into Notepad or your text editor of choice for further searching and editing. - The _Dump Font Cache_ option on the context menu outputs details about all the fonts currently used by A-Shell - The _Set Debug Mode_ option on the context menu is equivalent to the dot prompt command `SET DEBUG` . Since the DEBUG - switch often results in a considerable volume of trace messages, the ability to turn it on and off in the middle of a program is often very useful for obtaining debugging information without being overwhelmed by it. - Note that for some timing-dependent GUI operations, turning on the _System Messages_ window can sometimes affect the - timing to the extent that the issue you are trying to track may actually change or disappear. In such a case, minimizing the message window may help; otherwise, closing it entirely (and then extracting the messages later from the ashlog.log) may be the only option. - Abort Application Program provides an alternative way to send an abort signal (^C) to the application program in cases where - the keyboard may be locked or not responsive. ## **See Also** - Using the Message Window ## **History** - 2023 September, A Shell 6.5.1744: Add the EXEC trace option to the System Messages Window properties dialog. Previously this was only settable via the SET command or the TRACE directive in the MIAME.INI. When set, each command-level command (RUN, CMD/DO, LIT) is traced.. A-Shell Reference Page 267 - 2023 January, A Shell 6.5.1724: Add context menu option to send ^C to the application. - 2014 October, A Shell 6.1.1384: Add _View A-Shell Log File_ to the _A-Shell Developer Control Operations_ dialog and rename the dialog to Developer Control Operations. A-Shell Reference Page 268 ## **TRACE OPTION EXEC** _Updated October 2025; see History_ The TRACE option EXEC traces RUN, CHAIN, command line and Xcall ASHELL statements. This is particularly useful for tracking user activity. Example trace formats: |**Context**|**Format**| |---|---| |RUN PROG1 (from dot prompt or command file)| Exec(CHAIN):
c:\vm\miame\dsk0\007006\prog1.run| |CHAIN PROG2 (from PROG1)| Exec(CHAIN):
c:\vm\miame\dsk0\007006\prog2.run| |Xcall Ashell, "RUN PROG3" (from PROG2)| Exec(AMOS): Exec(AMOS):
RUN PROG3| |LOG DSK0:100,150
(from dot prompt or command file)| Exec(CMDLIN) LOG DSK0:100,150| So essentially you can search or filter for "Exec(" to easily pick up all the command lines and programs executed. It also traces the A-Shell launch command line, e.g. ``` C:\vm\miame\bin70\ashw32.exe -i c:\vm\miame\miame.ini -j slave1 -ua stslave1 ``` ## or ``` /vm/miame/bin/ashell -i /vm/miame/miame.ini -erz /vm/miame/sys1/ersatz.ini -hei mystart ``` A-Shell Reference Page 269 As with other TRACE options, you can set it from/in various contexts: |**Context**|**Statement**| |---|---| |Inmiame.ini|TRACE=EXECUTE| |From the command prompt|SET TRACE EXECUTE ON| |From within a program|xcall MIAMEX, MX_GETTRACE, trflags| |From within a program|xcall MIAMEX, MX_SETTRACE, trflags OR TROP_EXECUTE| The symbol TROP_EXECUTE is defined as &h80000000 in ashell.def. ## **History** - 2025 October, A Shell 7.0.1779: When the EXEC trace is set, a line showing all of the A-Shell command line arguments is added to the ashlog. A-Shell Reference Page 270 ## **TRACE OPTION JOBLCK** _Added October 2016_ TRACE=JOBLCK causes all unresolved lock/unlock operations on the jobtbl.sys file to be traced in the file jobtbl.lck. The intent here is to make it easier to debug and resolve a rogue condition whereby a process has a lock on jobtbl.sys preventing other users from getting in or out of A-Shell. Under Unix you can use the lslk utility to see who has a lock on the file, but under AIX this appears to be nearly impossible, and under Windows it may be difficult. The jobtbl.lck file is created in the same directory as jobtbl.sys, and consists of human readable ASCII text lines in the following format: ``` pid,op,recnovar ``` where pid is the process id, op is either "lock" or "unlock", and recnovar is 0 for the jobtbl header, else a number indicating the jobtbl record for that job number. For example: ``` 2415,lock,5 ``` ``` 3723,lock,15 ``` ``` 2415,unlock,5 ``` ``` 3724,unlock,15 ``` The above case indicates the following chronology: ``` process 2415 locked the jobtbl record for job #5 ``` ``` process 3723 locked the jobtbl record for job #15 ``` ``` process 2415 unlocked the jobtbl record for job #5 process 3723 unlocked the jobtbl record for job #15 ``` A-Shell Reference Page 271 Since at this point the locks and unlocks match, on the next operation, the file will be truncated and started over again. If the option is enabled and you get a "unable to access jobtbl.sys" error, you can then display this file to hopefully identify which processes have locks on the file and can then investigate or kill those processes. ## **History** - 2016 September, A Shell 6.3.1526: JOBLCK added to A-Shell. Note that a stripped-down version of this feature was added in 6.2.1428.0. A-Shell Reference Page 272 ## **TRACE OPTION FUNCS** _Written August 2025_ TRACE=FUNCS activates automatic tracing of function and procedure calls (calling parameters and the return value), including XPUTARG operations. Some examples of how these traces show up in the ashlog: ## **Function Call and Return** The following shows a function call to which two arguments, "today+3" and "" are passed. That function in turn makes two additional function calls before returning the result of "08/21/2025". Note that the nested calls are indented (2 spaces per level) and the function return is lines up with the function call... ``` ... -> @0016ac( S50[today+3],S3[] ) ``` ``` ... -> @0000b4( S1[t] ) ``` ``` ... -1 <- @0000b4() ... -> @00379a( S50[today+3],S3[] ) ... 08/21/2025 <- @00379a() ... 08/21/2025 <- @0016ac() ``` ## **Procedure with a Parameter "doggie" Passed to It** The procedure passes "perrito" back to the same parameter before returning. ``` ... -> @003af1( S30[doggie] ) ``` - `... xputarg @1=S30[perrito] ... <- @003af1()` A-Shell Reference Page 273 The overall effect is similar to what you can get by embedding trace.print statements at the start and end of each function and procedure, and after each XPUTARG, but doesn't require any editing or recompilation of the program. It just requires that you enable the FUNCS trace by one of the methods (SET, system message window properties, editing the MIAME.INI, etc.). For example: ``` .SET TRACE FUNCS ON ``` It also requires that you have access to an LSX file matching the program so that you can decipher the @xxxxxx locations. See VIEWASHLOG.LIT for a related enhancement. A-Shell Reference Page 274 ## **TRACE OPTION XCALL** _Updated October 2025_ Logs most subroutine calls. Certain extremely common routines, like MIAMEX, are not logged, unless the XDEBUG trace is also activated. In CGIUTL, creates additional logging in cgiutl.log file. Beginning with A-Shell 7.0.1778, the xcall trace (e.g. `SET TRACE XCALL ON` ) traces return parameters for xcall subroutine calls. Previously, only the parameters passed to the subroutine were traced. For internal subroutines, the return trace is identical to the calling trace except it will show the updated parameter values. To take a simple example, the following traces: ``` xcall XSTRIP,S20[ ABCD123 ],S3[123],F8[1] ``` ``` <---- XSTRIP,S20[ ABCD ],S3[123],F8[1] ``` ... show the xcall XSTRIP being called with the first parameter " ABCD123 " being changed to " ABCD " on return. Note that there are a few xcall routines, including STRIP (but not XSTRIP) which are converted by the compiler to internal functions, in which case they will not show up in the traces. For external (SBX) subroutines, it isn't necessary to list the entire parameter list on return because any explicit parameter updates require the user of XPUTARG, which is also separately traced. See the notes for 7.0.1776.0 below which covers XPUTARG tracing in the context of user defined functions but which applies equally to SBX subroutines. ## **History** - 2025 October, A Shell 7.0.1778: See note above. A-Shell Reference Page 275 ## **TRMDEF** ## **TRMDEF=Device, Jobname, Terminal, Driver** A-Shell will automatically generate job and terminal names in the form of TSKAAA, TSKAAB as each new job is launched. For most applications, this is perfectly acceptable—and virtually unavoidable for Telnet connections. But if you want to try to associate TRMDEF and JOB names with particular terminal devices, the TRMDEF facility may help you. The general idea is that whenever a new A-Shell session is launched, A-Shell first checks the Command Line Switches. If switch –j has been specified, then that jobname is used. Otherwise, it determines the device name of the workstation, then checks if there are any TRMDEF statements which reference either all or part of that device name. If a match is found, then the JOBNAME, TERMINAL, and DRIVER specified in the TRMDEF statement will be assigned to the new job. Otherwise, the first available name of the type TSKAAA will be used instead. As an example, suppose the terminal device (as displayed by the –d switch to ashell or by `SYSTAT/C` ) is tty3a:5623. The part after the colon will change every time, but since tty3a is a regular serial port (as opposed to a network pseudo port) it will be the same each time. So if you wanted to make that terminal come up with the jobname and terminal name "ship," you could add the following statement to miame.ini: ``` TRMDEF=tty3a,ship,ship,am62a ``` When this statement is processed by an instance of A-Shell whose device name starts with "tty3a", it will cause the jobname SHIP and terminal name SHIP to be assigned to that instance. (You could theoretically make the job and terminal names different, but this doesn’t really accomplish anything other than add to the confusion, since it is not possible to change the attachment between a job and a terminal.) The terminal type am62a will also be assigned, although in most cases it is preferable to omit the terminal type from the TRMDEF line so that the terminal specified in the TERM environment variable will be used instead. Under Windows , the device name is, in most cases, the workstation’s machine name (or "network ID") with a suffix identifying the window number appended (e.g. "SHIPPING-PC:01".) You could use this as the basis of the following TRMDEF statements: ``` TRMDEF=SHIPPING-PC:01,SHIP1,SHIP1,PCTDVG ``` ``` TRMDEF=SHIPPING-PC:02,SHIP2,SHIP2,PCTDVG ``` A-Shell Reference Page 276 The first line above would apply to the first window opened by the PC whose machine name was "SHIPPING-PC", and the second line would apply to the second window opened by the PC. The terminal driver name (PCTDVG) is again optional; if not specified here, the default will come from the CONSOLE statement. For system administration convenience, you can put all of your TRMDEF directives in a separate file (trmdef.ini) which is included into the configuration file using the INCLUDE command. This file should contain one TRMDEF line for each terminal which is allowed to run the MIAME application. You may mark comment lines by starting them with a semi-colon or number. Note: The following section applies to Unix-based systems only: Although Unix does not have terminal drivers as such, it does have a table-driven equivalent ( _terminfo_ ), which enables fairly advanced screen handling to be performed in a terminal-independent manner, though it is nowhere near as good at it as AMOS terminal drivers. A-Shell makes use of terminal driver equivalents (written in C) in order to better handle attached screens, though a generic driver ( _GENERC_ ) is provided which does make use of the _terminfo_ database. Unix makes use of an environment variable TERM to indicate the terminal type in order to find the correct terminfo entries. A- Shell also makes use of this variable in order to determine which terminal driver to use. The **TERM** variable is analogous to the terminal driver name, except that it is not guaranteed to be restricted to six characters, and so is not returned directly by the gettdv() routine. The TRMDEF lines in miame.ini must therefore be kept in step with the terminal types defined on the system, with six-character equivalents of each terminal’s TERM variable setting. Note: The following section applies to Windows-based systems only: There is only one proper terminal driver embedded within the Windows version of A-Shell, although there are several variations: |**Driver**
**Name**|**Notes**| |---|---| |PCTDV|Standard Windows.| |PCTDVG|Windows version only. Same as PCTDV except certain "GUI enhancements" may be
applied, such as displayingXCALL MESAGmessages in a dialog box rather than on line
24.| A-Shell Reference Page 277 |**Driver**
**Name**|**Notes**| |---|---| |PCUK|Standard UK (national replacement character set) version of PCTDV. The # or £ keys
return ASCII character 35, and character 35 is always displayed as £.| |PCUKG|Same as PCUK but with the Windows "GUI enhancements" described above.| |PCFR|French national replacement keyboard version. Same idea as PCUK| |PCFRG|Same as PCFR but with the "GUI enhancements" described above.| Note that TRMDEF directives are entirely optional, and in most cases, are best ignored, since unique job and terminal names of the form TSKAAA, TSKAAB, etc. will be created. The use of INCLUDE in order to separate terminal definitions is entirely optional. If TRMDEF commands are used, then they can equally well be given in the main MIAME environment definition file. A-Shell Reference Page 278 ## **UMASK** _Updated July 2025_ ## **UMASK=filemask {,dirmask}** (Unix only) UMASK allows you to change A-Shell’s default file creation mask from 111 to something else. If you set `UMASK=000` , it will use the mask set by the shell. Otherwise it will use the specified mask. Note that the bits in the umask clear the corresponding bits in the file creation mask, which starts at 666 (rw-rw-rw-). So setting `UMASK=111` will result in no change to the rw-rw-rw- mask. But `UMASK=137` would result in rw-r---- (rw by the file owner, read only by members of the group, otherwise no access). Note that although you can't directly set the UMASK to 000, because that effectively sets it to the current default, in some environments you can work around that limitation by setting `UMASK=1000` . The optional second parameter, _dirmask_ , is used to set UMASK for directory creation: For example: ``` UMASK=011,002 ``` Remember that the bits in the UMASK cause the corresponding bits in the file or directory permissions to be cleared, so 002 corresponds to drwxrwxr-x. A-Shell Reference Page 279 ## **XONXOFF** (Unix only) When ON, the ^S and ^Q keys can be used to stop and start rapidly scrolling output (such as from a TYPE or DIR command) as long as the program is not waiting for input, and as long as the current line handshaking discipline supports XON/XOFF. In most cases, while waiting for keyboard input, XON/XOFF is disabled to avoid conflicts with other uses of these keys. (One exception is VUE. In order to access the ^Q and ^S VUE commands, you can use the alternate sequences ^_Q and ^_S.) When XONXOFF is off, the ^S and ^Q keys do not do anything special. `XONXOFF=ALWAYS` is like ON, except that it leaves XON/XOFF control active even during input operations. This takes away the ability to use ^S and ^Q as input commands, but it eliminates a problem which can happen with some dumb terminals in which the turning off of flow control during the transition from a long output to an input can cause the last few characters of the previous output operation, which had been output by A-Shell but were still buffered by the operating system, to become garbled. The symptom of this problem could be seen in a long DIR/W operation, in which it would handshake correctly up until the last couple of lines at the end, just before returning to the dot prompt. In most cases, PAGE.LIT will accomplish the same thing (only better) for which you were trying to use CTRL+S and CTRL+Q. A-Shell Reference Page 280 ## **PRINTER CONFIGURATION** Printing is probably the most complicated and confusing area within A-Shell. There are a couple of reasons for this. - The print spooling facilities and capabilities vary widely among the platforms supported by A-Shell. - Network environments impose another layer of configuration complexity beyond what you may have been used to with - AMOS. Perhaps we could have approached this problem by developing an emulation of the AMOS spooler for each platform. However, this would have conflicted with one of the underlying design philosophies of A-Shell, which is to allow your application to coexist with other applications on a given platform, sharing common operating system facilities as appropriate. Therefore, since virtually all Windows applications spool reports via the Print Manager, it makes sense that A-Shell does too. Unix applications typically use one of the spoolers provided by the operating system, so again, A-Shell does the same. This approach may make it easier for a system administrator to integrate and manage A-Shell in an existing environment, but it does require that the administrator or installer create printer configuration files which define the interface between the logical printer names used within the DevPPN / A-Shell applications, and the corresponding real printers available in the physical establishment. The following sections describe this in detail. ## **Subtopics** - Defining Spoolers - Ini File Directives - Troubleshooting Techniques - Supported Printer Interfaces - EZSPL - EZSPL Print Preview - Send File to Printer or Queue A-Shell Reference Page 281 ## **DEFINING SPOOLERS** A-Shell spoolers have names of one to six characters and are defined by means of an initialization file, normally abbreviated "ini" or "init," which is a small text file containing various configuration parameters. Under AMOS, these files were named .ini and were stored in the SYS: directory. Although A-Shell supports that method and will find and process those ini files, the recommended and preferred method is to use files named .pqi which are stored in the ASHCFG: directory. The extension PQI stands for "Printer Queue Initialization" and was chosen to minimize the likelihood of conflict or confusion with other file extensions, as well as other types of ini files. The actual content of .PQI files and .INI files is identical. The ersatz directory ASHCFG: is typically DSK0:[1,7] but can in fact be anything. By grouping the printer initialization files in a special directory (away from the standard release files) and by using a unique extension, it is easy to identify the available printer configurations on a system. However, when looking for a printer, if the ashcfg:.pqi file is not found, A-Shell will continue to look for SYS:.ini as before. To allow for a temporary override of the printer ini file without actually modifying or changing the active one, A-Shell will first check for .pqi in the %TEMP% directory. So the complete search path is: ``` %TEMP%\.PQI ``` ``` ASHCFG:.PQI ``` ``` SYS:.INI ``` For example, if the application wants to spool to a printer called LASER1, then A-Shell will look for a printer ini file called %temp%\laser1.pqi or ashcfg:laser1.pqi or sys:laser1.ini which defines the configuration of that printer. If no printer name is specified in the `PRINT` or `XCALL SPOOL` statement, the default name is determined by the PRINTER directive in miame.ini. If there is no PRINTER directive, under Unix, A-Shell will look for a file $HOME/.PRINTER, from which the printer name will be read from the first line of the file, if found. If no default printer is defined, then A-Shell will attempt to print to the default printer for the host operating system environment. Unlike AMOS, where the printer initialization files are processed at system boot up, A-Shell ignores these files until you actually make a print request. This is possible because the printer ini files only specify interfacing information that can be processed at A-Shell Reference Page 282 run time. Thus, any changes you make to a printer ini file will take effect with the next print request. Also, because the printer ini files are only processed when referenced by a print request, there is no harm in having printer ini files that do not refer to actual or available printers. There is no limit to the number of printer initialization files you may have. Thus, there is no limit to the number of logical A-Shell printers that may exist. There is also no limit to the number of logical A-Shell printers that may actually correspond to the same system spooler. Any given line in a printer ini file can be a maximum length of 256 characters. The exception to the rule requiring the existence of a printer ini file is that it is possible to use the Windows or Unix printer name directly, instead of the AMOS or A-Shell name. In that case, a default printer configuration will be used. For Windows, this consists of `DEVICE = , PASSTHROUGH=OFF` and `PITCH=AUTO` . Under Unix is would simply be `DEVICE = ` . This technique is particularly useful under Windows in conjunction the subroutine MIAMEX 120, _Prompt for Window Printer_ , which allows the user to select a printer using the standard Windows printer selection dialog. Examples of typical printer initialization files for Windows and Unix are given in the following topic. Note that in all cases, the only mandatory parameter is DEVICE (or alternatively, COMMAND); all others are optional. ## **Subtopics** - Printer Ini File Examples A-Shell Reference Page 283 ## **PRINTER INI FILE EXAMPLES** Following is an example of a typical Windows printer ini file. ``` DEVICE=\\server\hp1 | HP LaserJet Series II ``` ``` LPP=66 ``` ``` CPP=80,136 ``` ``` FONT=Courier New ``` ``` CHARSET=ANSI ``` ``` WEIGHT=400 ``` ``` PITCH=AUTO ``` ``` ORIENTATION=PORTRAIT ``` ``` TMARGIN=1 ``` ``` LMARGIN=0 ``` ``` PASSTHROUGH=OFF ``` ``` PREFIX=SYS:LASER.PFX ``` ``` SUFFIX=SYS:LASER.SFX ``` ``` FORMFEED=ON ``` ``` DELETE=OFF ``` ``` BIN=UPPER ``` The typical Unix printer ini file is generally simpler: ``` DEVICE=jet7 ``` A-Shell Reference Page 284 ``` PREFIX=SYS:JET7.PFX ``` ``` SUFFIX=SYS:JET7.SFX ``` ``` FORMFEED=ON ``` ``` AUTOFF=ON ``` ``` STRIPFF=ON ``` ``` DELETE=ON ``` ``` BANNER=OFF ``` Any commands that are not recognized are just ignored. It should be noted that not all commands are interpreted by all implementations of A-Shell, and they are very much at the mercy of the capabilities of the host operating system. Note that the all parameters are optional except for **DEVICE** or **COMMAND** , one of which is critical. A-Shell Reference Page 285 ## **INI FILE DIRECTIVES** Below is a list of the printer initialization file directives, also called "parameters" or "commands." For each directive, there is a link to another page which contains a detailed description along with usage, syntax, suggestions and warnings. The directives are listed here in alphabetic order, but may in any order within the ini file. The only absolute requirement for printer ini files is that they contain one DEVICE (or COMMAND) entry. Directives that apply only to Windows or only to Unix are so noted at the start of the description for each. If not otherwise stated, the directive applies to both Windows and Unix. Under Windows, the PASSTHROUGH parameter has a very significant effect on nearly every other aspect of printing, so you may want to review it first. |**Command**|**Description**||**Command**|**Description**| |---|---|---|---|---| |APEX|Ignore server PREVIEW
setting, execute on client||LMARGIN|Specify left margin| |AUTOFF|Add trailing form feed||LPP|Specify number of lines
per page| |AUTODLGOK|Auto respond to some
pseudo printer drivers||ORIENTATION|Specify portrait or
landscape page
orientation| |AUXPCDIR|Specify location of output
file||OVERLAY|Add specified file to
beginning of each page| |BANNER|Add banner to beginning
of printout||NOABORTDLG|Disable display of
Windows "Abort?" dialog| A-Shell Reference Page 286 |**Command**|**Description**||**Command**|**Description**| |---|---|---|---|---| |BIN|Specify paper source||PAPERLENGTH|Set custom paper size| |CHARSET|Specify character set||PAPERSIZE|Set paper size| |COMMAND|Specify alternate
processing of print file||PAPERWIDTH|Set custom paper size| |CPP|Specify columns per page,
hence font width||PASSTHROUGH|Set Windows mode| |CRLF, CRNL|Force output lines to have
CRLF terminators||PITCH|Calculate font height and
width| |CRNL|Same as CRLF||PREFIX|Prepend specified prefix
file to print file| |DATATYPE|Send command to
Windows Print Manager||PREVIEW|| |DELETE|Delete file after printing||PRTCMD|Same as COMMAND| |DEVICE|Associate A-Shell printer
with host printer||PRTCOPIES|Select mode for printing
multiple copies| |DUPLEX|Enhances duplex printing.||STRIPFF|Remove form feed from| A-Shell Reference Page 287 |**Command**|**Description**||**Command**|**Description**| |---|---|---|---|---| |||||beginning of print file| |FONT|Specify font||SUFFIX|Append specified suffix file
to print file| |FONTHEIGHT|Specify font height||TMARGIN|Specify top margin| |FONTWIDTH|Specify font width||WEIGHT|Specify weight
("boldness") of font| |FORMFEED|Enable/disable form feed||XOFFSET, YOFFSET|Make minor positioning
adjustments.| |HEADER|Add header to page(s)||XORIGIN, YORIGIN|Define offset from paper
corner.| A-Shell Reference Page 288 ## **APEX** ## **APEX = ** This switch is nearly the same as PREVIEWpq, b ut is specifically for the ATE case where you want the PREVIEW option to be ignored on the server and only recognized on the client. Otherwise, activating PREVIEW on the server in a non-GUI environment might give you the text-mode preview, EZTYP. See APEX for operations. A-Shell Reference Page 289 ## **AUTOFF** ## **AUTOFF = ** (Unix only) This option (which defaults to off) may be turned on to have A-Shell itself take over the task of putting a trailing form feed on the end of a print file when required by your spooler switches. Note that in order for this to work, you must use a printer filter which never adds a trailing form feed. For SCO we supply one on our web site called **dumbnoff** (copy it to /usr/spool/lp/model). For most other Unix flavors, you can simply select a "dumb" or "null" printer filter (aka "driver" or "model"). AUTOFF can be used in conjunction with STRIPFFpq and FORMFEEDpq (which see) to reconcile different applications’ approaches to form feeds. A-Shell Reference Page 290 ## **AUTODLGOK** ## **AUTODLGOK={class,}** This command makes it possible to automatically respond to a predictable dialog displayed by some pseudo printer drivers like PDF writers. Typically these will default to the same name as the source file, but with a PDF extension, and wait for the user to hit the SAVE button (or possibly to change the directory or filename first.) If you would rather just accept the default and not have to respond to such dialogs, you can this command to your printer initialization file: ## **Parameters** _{class}_ is an optional Window class for the dialog (which you may be able to get from a Spy utility). If omitted, then the dialog will be recognized solely by its title. __ is the string appearing in the title bar of the dialog. ## **Example** For example, for the popular PDF995 driver, you could use: ## `AUTODLGOK=Pdf995 Save As` In this case, after A-Shell sends the file to the printer, it waits a few seconds to see if a dialog pops up with the specified title. If so, it sends an ENTER keystroke to it to just accept the default and proceed. ## **Comments** Note that in most cases, the default directory will be set to match the directory used for the previous Save As operation by that driver. So before creating a thousand PDF files this way, you may want to first use the regular interactive method to establish the default directory. A-Shell Reference Page 291 ## **AUXPCDIR** ## **AUXPCDIR=** This command may be used in conjunction with DEVICE=AUXLOC: to specify where the output file will be placed on the PC. Normally this doesn't matter much because the file is usually deleted after printing, but in cases where that is not true, and especially for PDF generation, the location is rather important. For example, ``` AUXPCDIR=%MIAME%\PDF ``` If does not exist, it will be created, provided that its parent path exists. A-Shell Reference Page 292 ## **BANNER** ## **BANNER = ** (Unix only) BANNER _may_ invoke a printed banner at the start of each printout if such an option is available. On some Unix spoolers, a banner is unavoidable. The default is OFF, though this may be overridden by the correct switch to SPOOL. Under SCO Unix, you must use the `lpadmin –p -onobanner` command to enable the ability to ask for no banner. Failure to do this may cause the spooler to reject all print requests specifying no banner. You may also want to use the scoadmin utility to set the default number of banners to 0. See Troubleshooting Techniques. A-Shell Reference Page 293 ## **BIN** ## **BIN = bin-ID** (Windows only) This command allows you to specify a particular paper source in a printer that has multiple paper sources. The choices for _bin-id_ are: |UPPER|LOWER|MIDDLE|MANUAL|AUTO| |---|---|---|---|---| |ENVELOPE|ENVMANUAL|LARGEFMT|SMALLFMT|| |LARGECAPACITY|FORMSOURCE|USER<#>||| Since some of these bin identifiers are rather cryptic, it may not be easy to determine what the appropriate name is for the bin you want to specify. Ultimately, this may require some trial and error, but you can at least get a list of the available bins in a specific printer, by adding one of the above BIN commands to your printer INI, then activating line printer trace mode and printing a sample file: ``` .SET TRACE LP ON ``` ``` .PRINT =SYS:.INI ``` This will cause a lot of tracing information to be displayed to the screen, including a list of all of the BIN names for the specified printer. ## **Notes** Some printers may require that you manually configure them to allow the application to select the bin. See your printer documentation for details on that. If you specify a bin that the printer does not support, the result will be dependent on the printer driver. It may ignore the request, it may attempt to give you a closest match, or it may do something else. A-Shell Reference Page 294 Some printers may implement "user-defined bins". The first 8 of these can be usually be referenced by "USER1" through "USER8". Note, however, that some printer drivers start the user-defined bins at something other than "USER1". If in doubt, use the tracing technique described above to display the list of available bins. When a printer supports a bin that is not recognized by name by A-Shell, it will appear in the list of bins (displayed when using SET TRACE LP ON) as a number. You can use any such number in the BIN command just like it was a bin name (e.g. BIN = 265). For what it’s worth, "USER1" is equivalent to BIN #256, "USER2" to BIN #257, etc. BIN works with both PASSTHROUGH=ON and with PASSTHROUGH=OFF. BIN is one of the printer ini file commands that has a GDI Printing Directive Equivalent. A-Shell Reference Page 295 ## **CHARSET** ## **CHARSET = ** (Windows only) This optional command works in conjunction with the FONTpq command to determine the font character set that is selected. Choices are as follows: |**Value**|**Meaning**||**Value**|**Meaning**| |---|---|---|---|---| |ANSI (or 0)|ANSI character set
(default)||161|Greek| |OEM (or 255)|OEM character set||162|Turkish| |Symbols (or 2)|Symbol set||177|Hebrew| |Default (or 1)|Default for selected font
face name||178|Arabic| |77|Mac||186|Baltic| |128|Shift JIS (Japanese Kanji)||204|Russian| |129|Hangeul||222|Thai| |134|GB2312||238|Eastern Europe| |136|Chinese Big5|||| Note that merely specifying an exotic character set does not mean you will get it, because a font with those characteristics has to exist. If you specify both a font name (using the FONTSP parameter) and a charset, the character set will become most important if the requested font face name does not exist. This is why the default setting is ANSI rather than DEFAULT, because ANSI is what is expected. You must set `PASSTHROUGH=OFF` for CHARSET to be applicable. Also note that you can change fonts in mid report using the GDI print commands; see Print Directives. Also see FONTSP and WEIGHTPQ, which work together with CHARSET to determine the actual font selected. A-Shell Reference Page 296 ## **COMMAND** COMMAND may be used in place of (or in some cases, in addition to) DEVICE[pq] , in order to specify an alternate command or subroutine for processing the print file, which is also known as a "print filter." This can be especially useful when interfacing to non-printer devices such as faxes, email, archival systems, etc., as well as for performing special filtering operations on print files without having to change the application that created them. There are two forms of the command, named according to which system will be doing the processing." Only one COMMAND can be specified in a single printer ini file. A-Shell Reference Page 297 ## **HOST PROCESSING** ## **COMMAND = ** This specifies an arbitrary native operating system command to be executed. The command may optionally contain two optional and case-sensitive parameters: _$COPIES,_ which is replaced by the actual number of copies requested, and _$FILE_ which is replaced by the filename requested. If _$FILE_ is not specified, then the (native) print file name is appended to the end of the command line. Here are two examples: ``` COMMAND = mylpr –n$COPIES $FILE ``` ``` COMMAND = notepad.exe $FILE ``` If the requested print file request was for one copy of SYS:ersatz.ini, these would expand to something like the following:: ``` mylpr –n1 /vm/miame/dsk0/001004/ersatz.ini ``` ``` notepad.exe c:\vm\miame\dsk0\001004\ersatz.ini ``` The above commands assume Unix in the first case, with the default definition of DSK0: as /vm/miame/dsk0, and Windows in the second case, with DSK0: defined as C:\vm\miame\. Note that in this example, the _$file_ parameter is not necessary since the filename would have been appended to the end of the command line anyway. Also note that under Unix, the host command must be executable from the current command shell—i.e. be either an executable binary or a script. See the SBR option SUBMIT2 for related information. A-Shell Reference Page 298 ## **- A SHELL PROCESSING** _Updated February 2015_ ## **COMMAND = SBX:{,}** This form of the command invokes the specified SBX subroutine. In order to use this form of the command, you will have to have an appropriate SBX subroutine in DSK0:[7,6]. That subroutine will be "XCALLed" with the following parameters: ## **xcall ,status, fspec, printer, switches, copies, form {,}** _Status_ is mapped B,1 and must returned with a positive number if you want the print operation to proceed. Else set it to 0 to cancel the print operation, or a negative number to signify an error. (It gets passed in as -1, so you don't need to set it to abort.) If _status_ comes back to the print processor set to 1 or more, then it will first check to see if the subroutine has changed the printer name. If so, it starts the print operation all over again with a different printer initialization file. Otherwise, it proceeds to process the current printer request as if the command had not been executed. This only has an effect if your printer initialization file also contains a DEVICE[pq] directive. The remaining parameters are all string format. You can convert _switches_ and _copies_ to numeric variables, but if you want to change them, convert them back to strings before passing the parameters back. Any parameters that are specified on the `COMMAND = SBX:` line will be added to the end of the parameter list, to be interpreted by the SBX subroutine. For example: ``` COMMAND = SBX:EMAILP,4,"Subject","Intro, text..." ``` In the above example, EMAILP.SBX will be called with the following parameter list: ``` XCALL EMAILP, STATUS, FSPEC, PRINTER, SWITCHES, COPIES, FORM, 4, "Subject", "Intro, text..." ``` The SBX subroutine may change any of the first six parameters ( _status_ thru _form_ ), and the changes will take effect before the print operation proceeds (assuming STATUS is set > 0.) Four sample routines (PFILTR, EMAILP, HTMLP, and GDIPRT) are supplied, with source, in the samples directory. PFILTR just prints out the parameters and allows you to update them before returning to the print processor. (This is very useful for A-Shell Reference Page 299 learning/testing.) EMAILP launches the local email client and inserts the print file into the message (either in the body or as an attachment.) HTMLP wraps the print file with a simple HTML header and trailer (using a temporary file) and then displays it in your default browser (as a sort of preview utility). GDIPRT can be used under A-Shell/Unix, to forward the print file to be processed on the local PC. It requires ZTERM, ATE or A-Shell/Windows on the PC. ## **APEX Export Extensions** APEX supports custom export/extension modules which use the same print filter interface specification, except that APEX will always pass two additional parameters ( _inifile_ and _flags_ ) following the _form_ parameter. So if you are adding custom parameters to a print filter routine, if you want the routine to be fully compatible with APEX, you should allow for those two parameters—and add your custom parameters after that. Because of this distinction, APEX includes a variation of the EMAILP subroutine, called PRTMAPI, with the parameters so adjusted. But had the APEX version been created first, it would have served just as well as EMAILP, except with slightly different COMMAND=SBX: syntax due to the additional parameters. See APEX Extensions for more detail. ## **History** - 2014 November, A Shell 6.1.1398: Print filter enhancement: The printer init statement `COMMAND=SBX:filter,...` now supports two optional macro arguments, $PREFIX and $SUFFIX, which evaluate to the current prefix and suffix options. For example, given the following printer ini file: ``` DEVICE=TEST ``` ``` COMMAND=SBX:PFILTR,$PREFIX,$SUFFIX ``` ``` PREFIX=TEST.PFX ``` ``` SUFFIX=TEST.SFX ``` the print filter PFILTR.SBX would receive "TEST.PFX" and "TEST.SFX" as the 7th and 8th arguments. The first 6 arguments to a printer filter are always preset to STS,FSPEC,PRINTER,SWITCHES,COPIES and FORM. A-Shell Reference Page 300 ## **CPP** ## **CPP = <# columns per page> {,<# cols in condensed mode>}** (Windows only, PASSTHROUGH[pq] must be off) The CPP (columns per page) parameter works in conjunction with the PITCH=AUTO option (see PITCHpq) to establish a suitable font width. Note that if any of the first fifteen lines of the file (not counting trailing spaces) are longer than the first parameter specified, the CPP value is automatically switched to the second parameter, or 132 (if no second parameter specified), in order to accommodate applications that use condensed print on some reports. For example, consider the following: ## `CPP = 80,140` If none of the first fifteen lines of the report are longer than 80 characters (not counting trailing spaces), then a font suitable for 80 characters across the page will be used. However, if any of those first fifteen lines exceeds 80 characters, then it will switch the entire report to a font suitable for 140 characters across the page. You can also let A-Shell adjust the font size to handle whatever the longest of the first fifteen lines is (again, not counting trailing spaces), by using this syntax: ## `CPP = AUTO` Or, you can specify a fixed width for reports up to a certain size, and beyond that use the AUTO option: ## `CPP = 80,AUTO` This might make sense if you print reports with far fewer than 80 columns, which you didn’t want to come out in an extra large font (to expand all the way across the page), but for reports beyond 80 columns, you just wanted them to use whatever font size would fit across the page. ## **Notes** The main reason for specifying a "non-standard" second value in the CPP directive would be if for some reason your condensed (132 column) font were not quite small enough, resulting in a few columns being truncated. One typical case where this occurs is where a programmer took advantage of a 17 CPI condensed printing option to print 136 columns on an 8 inch line. By specifying a larger number of columns (e.g. 140), you will force a slightly smaller font to be used, eliminating the truncation problem. (This A-Shell Reference Page 301 can also happen with printers having limited font scaling capability, although in that case, there’s no guarantee any particular size would have an effect.) ## **History** - 2009 December, A Shell 5.1.1168: "*" (asterisk) is now treated as equivalent to "AUTO." For whatever reason, this was apparently a common mistake or misunderstanding, aggravated by the fact that anything other than "AUTO" or a number was effectively treated as 132 (making CPP=80,*) appear to work, until you tried a file with more than 132 columns. In addition to recognizing "*", essentially anything non-numeric now results in the equivalent of AUTO. A-Shell Reference Page 302 ## **CRLF, CRNL** ## **CRLF = ** (Unix only) CRLF=ON may be used in conjunction with DEVICE=AUXLOC: to force the output lines to have CRLF (aka CRNL) terminators. This may be handy to eliminate the "stair step" problem that occurs under Unix when the printer does not automatically add a CR to each LF or NL character. To deal with the "stair step" problem in printer devices other than AUXLOC:, you typically select a printer filter to translate NL characters to CRNL during output. Or, you would configure the printer to automatically supply its own carriage return. A related setting in miame.ini is `OPTIONS=CRNL` , which causes all sequential output files created by A-Shell to have CRLF terminators instead of the Unix-standard LF terminators. This would eliminate the need for special CRLF handling in your printer INI, but may cause confusion with the ability of some other Unix utilities to act on those files, due to the non-standard line terminators. A-Shell Reference Page 303 ## **DATATYPE** ## **DATATYPE = ** The command `DATATYPE=RAW` prevents A-Shell from doing any special processing relating to the CR, LF, and FF control characters. This may be necessary in order to embed raw graphics into print files, as may be needed with certain EPF (e.g. Zebra label printer) and PCL protocols. Otherwise, even though PASSTHROUGH[pq] mode sounds like it "passes everything through", in reality, you still get conversion of isolated LF into CRLF, and it still identifies page breaks by FF (i.e. chr(12)), calling a standard GDI printing routine to inform the printer of the start of a page. The LF to CRLF conversion would obviously alter any graphic image, and the page break call may have had unknown results, depending on the driver. A-Shell Reference Page 304 ## **DELETE** ## **DELETE = ** The DELETE switch controls whether the file is deleted after printing. (Default is OFF.) Under Windows, this option is under A-Shell’s control, and works reliably. However, under Unix, unless A-Shell is building a temporary file to pass to the spooler (which it does to implement certain features, such as STRIPFF, AUTOFF, PREFIX and SUFFIX), A-Shell has to rely on the spooler itself to delete the file when it is done being printed. This is accomplished by passing a switch to the line printer request command (e.g. lpr, lp, enq). In some cases, particularly with Unix, this option may be "deprecated" and may not even work, due to the security issues that arise when a user is allowed to indirectly delete files via the line printer daemon (which typically operates under a different security environment than the original user.) Refer to the documentation (or "man" page) for the line printer for your operating system for more details about this if it is found to be a problem. One way to overcome an inability of your spooler to delete files is to add the **–c** switch to your DEVICE[pq] command to cause the spooler to make its own local copy of the print file before printing it. This would allow your application to immediately delete the print file after sending it to the spooler, using the ASB KILL command. Another workaround would be to create an empty SUFFIX file, which will force A-Shell to create a temporary file combining your original file with the empty suffix. In this case, if you specify the DELETE option, A-Shell will delete the original file immediately after constructing the temporary file. The temporary files are located either in the same directory where miame.ini exists, or in a directory specified by defining an environment variable _**ASHTMP**_ (e.g _. export ASHTMP=/vm/tmp_ ). You could then create an automated procedure (using cron) to remove all of the undeleted temporary files from this directory, say, every midnight. A-Shell Reference Page 305 ## **DEVICE** _Revised and reviewed July 2020_ Windows: ## **DEVICE = ** ## **DEVICE = | ** Unix: ## **DEVICE = {optional switches}** This defines the host printer queue or device to be used for the given A-Shell printer whose name matches the name of the printer initialization file. The syntax and semantics of the device specification vary with the host operating system. Note that in addition to actual printers, A-Shell supports the pseudo-devices DEVICE = AUXLOC:, DEVICE = PROMPT:, and DEVICE = DISK:. ## **Windows** **:** The and may either be descriptive names for the printers as they appear in a standard Windows printer selection dialog box (e.g. , _PDF-XChange_ or _Brother HL-5250DN_ ), or in case of shared printers, a UNC share name, e.g. _\\server\hp2_ . In order to provide flexibility for heterogeneous networks where different workstations may see the same printers differently, you can specify two device names separated by a vertical bar, as shown here: ## `DEVICE = HP LaserJet | \\server2\hp2` In this case, if the first name cannot be found, the second name is used. This can be useful in heterogeneous networks where it might be difficult for every workstation to refer to a particular printer by the same name. ## **Notes** See History below for additional notes. A-Shell Reference Page 306 Network printers do not need to be locally defined as long as the local machine can access the target printer by means of the \ \machine\sharename of the printer. To take advantage of this, the DEVICE directive must specify the \\machine\sharename by itself, or as the second choice (after the vertical bar) if there are two names (as in the example above). If it is not possible for all workstations in a network to refer to a shared printer by the same device name (or by either of a pair of alternate names under Windows), and if it is not possible for the application to allow different users to refer to the same printer by different names, then you may have to arrange for these workstations to have their own private ASHCFG: directory (or DSK0:[1,4]) so they can have different versions of a particular .pqi or .ini file. Refer to the DEVICE directive in miame.ini. If you are having difficulty figuring out the proper DEVICE specification for your printer, turn on line printer tracing (see Troubleshooting Techniques) and then print a sample file. It will display information showing you which printer names from the Registry it is trying to match against your device. Printer names given in the DEVICE statement under Windows are not case sensitive, and do not need to be complete. For example, "DEVICE=HP" will match "hp LaserJet" (but not "jet HP"). Be careful, however, to make the name long enough to be reasonably unique, because A-Shell will stop on the first printer that matches. So in the case of "DEVICE=HP", if you had both an "HP LaserJet 4" and an "HP DeskJet", it would match whichever one appeared first in the Registry. ## **Unix** You must specify a valid printer queue name. These are the names that can be specified in the P switch of the _lpr_ (Unix) or _enq_ (AIX) commands. (A-Shell submits the file to the printing subsystem by creating and then executing an _lpr_ or _enq_ command line based the specified, file, printer, and other options.) A copy of the actual command line created and submitted for each print request, along with any error response, is written to the log file opr:spool.log. Because Unix spool commands may support additional switches that are not directly analogous to PRINT or XCALL SPOOL parameters, or otherwise not supported by A-Shell directly, you may add any such parameters after the spooler name, as shown here: ``` DEVICE = laserque 1 -c -o sides=two-sided-long-edge ``` A-Shell Reference Page 307 In this example, the spooler name is _laserque1_ , and the additional arguments _-c -o sides=two-sided-long-edge_ are added to the command line created which is automatically generated, based on the file, operating system, and other parameters passed to the A-Shell spool request. (The _-o sides=two-sided-long-edge_ option illustrates a way of implementing duplexing under Unix, even though the DUPLEXpq printer init command is not supported except under A-Shell/Windows.) The –c switch generally causes most Unix spooler commands to make a local copy of the file before printing it, thus eliminating conflicts which might otherwise occur if the application then proceeded to erase or modify that file before it was done printing. See the discussion about deleting files (DELETEpq) for more comments on this topic. ## **History** 2019 December, A-Shell 6.5.1672: Add DEVICE=LASTPROMPT: function - 2019 November, A Shell 6.5.1671: If you know the exact and complete name of the printer, you can eliminate the normal logic which enumerates the available printers in order to determine the best match, by preceding the name with an asterisk. This could potentially be useful in certain environments where the printer enumeration operation was hanging, taking too long, or otherwise causing problems. For example: ``` DEVICE = *PDF-XChange Printer 2012 ``` - 2009 June, A Shell build 1150: If a printer is known to exist but A-Shell fails to find it in the matching logic, you can set the first character of the printer name in the DEVICE statement to lower case (e.g. DEVICE = hP Laser), in which case if it fails to find it in the directory, it will trust you and just try to open it blindly. (This has long been the procedure for printers using share names like \\server\name.) - 2009 May, A Shell build 1148: Windows printer names can be up to 100 characters in length. The previous limit was 50. A-Shell Reference Page 308 ## **DEVICE = AUXLOC:** This causes the file to be redirected to the auxiliary port on the current terminal, which hopefully has been set up to further redirect the printout to an appropriate printer attached to the terminal or to the PC on which the terminal emulator is running. Note the trailing colon. Under Windows, DEVICE=AUXLOC: only makes sense when the Windows machine is acting as a telnet server (i.e. running ATSD), in which case, the client terminal or emulator would handle auxiliary port request the same as if the host was a Unix machine. If the client is ATE, the application can override the client's auxiliary port printer choice at runtime by sending the extended TAB command AG_SPOOLCFG prior to printing a file to the AUXLOC: device; see AG_SPOOLCFG for details. Or, it can use the following syntax: ``` DEVICE = AUXLOC: ``` For example, DEVICE = AUXLOC:LASER would send the file to ATE client and then tell ATE to print it to the printer named LASER (overriding the current ATE printer configuration). Note that this would require that there either be a printer visible to the ATE client whose name started with "LASER", or that there was a sys:laser.ini or ashcfg:laser.pqi file already installed on the ATE client, containing the printer initialization commands to be used. Note that the could itself be a pseudo-printer specification, such as DEVICE=AUXLOC:PROMPT:, in which case ATE would prompt for the printer choice, even if ATE had previously be configured to print to a specific printer without prompting. Another ATE-only variation is the ability to force the PASSTHROUGH option on or off, but otherwise accept the existing ATE printer configuration. This is accomplished with the following syntax: ``` DEVICE = AUXLOC:+GDI ``` or ``` DEVICE = AUXLOC:+PASSTHROUGH ``` It is also possible to set the mode (GDI or Passthrough) in the printer name; see the topic Set Printer Mode Using Printer Name for more information. A-Shell Reference Page 309 ## **Note on Multiple Copies** See PRTCOPIESpq for information on how copies are handled with AUXLOC: printing. A-Shell Reference Page 310 ## **SET PRINTER MODE USING PRINTER NAME** It is possible to combine the +G{DI} or +P{ASSTHROUGH} option with a printer name, whether a printer ini file or a raw Windows printer name, in the DEVICE = AUXLOC: statement. For example: ``` DEVICE = AUXLOC:\\SERVER\SHARE NAME+PASSTHROUGH ``` ``` DEVICE = AUXLOC:HP Laserjet Series 37+PASS ``` ## **Notes** - The mode may be specified with a few as 2 characters (e.g. +G or +P). The downside of this is that those pairs of characters - cannot appear within the printer name itself. - When printing to a printer by its raw Windows printer name or share name (i.e. not via a printer ini file), the default mode is - GDI, so there is no particular need to specify +GDI in that case. - When printing to a printer via a printer ini file, the printer ini file will override any mode specified in the DEVICE=AUXLOC: - statement. Even if the printer ini file has no PASSTHROUGH[pq] statement, that is equivalent to `PASSTHROUGH=ON` . A-Shell Reference Page 311 ## **DEVICE = PROMPT:** _Updated March 2013; see History_ The second special pseudo-device is PROMPT: and applies only to A-Shell/Windows. Instead of specifying the printer device, it causes a standard Windows printer-selection dialog to be invoked, allowing the user to select any available Windows printer. Again, note the trailing colon. The PROMPT: device should only be used with PASSTHROUGH=OFF, since it cannot be guaranteed that all printer drivers support PASSTHROUGH mode. When using the PROMPT: device, many of the other parameters within the printer initialization file may be overridden by the selection of the printer in the dialog. A print request sent to a printer named PROMPT, will, if no printer ini file is found, be treated as if DEVICE=PROMPT: and PASSTHROUGH=OFF. (This makes "PROMPT" a very useful default spooler name under A-Shell/Windows.) The printer selection dialog triggered by DEVICE=PROMPT: must be executed in a client A-Shell/Windows context. If it occurs in the context of an ATE connection to an A-Shell/Windows server (using ATSD), it will be automatically re-interpreted as DEVICE=AUXLOC:PROMPT: so that it gets forwarded to the ATE client where the printer selection dialog can be displayed. This however, defeats the effect of most other printer init commands in the printer ini file on the server, overriding them with options set in the ATE client Connection Properties > Printer dialog. To force the other options in the original (server-side) printer ini file to be processed on the client side, replace the DEVICE=PROMPT: in the server-side printer ini file with an explicit DEVICE=AUXLOC:printername where printername is the name of a printer ini file installed on the ATE client. (i.e. sys:printername.ini or ashcfg:printername.pqi). That printer ini file should be a copy of the original printer ini file on the server, with only the DEVICE statement changed to DEVICE=PROMPT: . The Windows default printer may be specified with the DEVICE directive: ## `DEVICE=PROMPT(DEFAULT):` This is identical to PROMPT:, except that it ignores the last used printer and instead defaults to the system default printer. This is useful in places where printers come and go, and defaulting to the last used printer can cause confusion or worse when the last used printer is no longer present. ## **Warnings** A-Shell Reference Page 312 The _printername_ can be PROMPT, but if so, be careful not to include the trailing colon in the DEVICE=AUXLOC:PROMPT statement. While both PROMPT and PROMPT: will result in the printer selection dialog being displayed, PROMPT: (with a trailing colon) is a pseudo-device which does not have an associated printer ini file, while PROMPT (without the colon) is a logical printer name that can be associated with a printer ini file (which was the whole point of the exercise just described above). Although it is possible for the server-side and client-side printer ini files to have the same name, this is probably not a good idea. For one reason, you may confuse the two files when transferring them. And for another, if the server and client happen to share the same DSK0: (either because they are the same physical machine, or share a network drive on a LAN), then it would be impossible for the two variations using the same name to coexist. ## **History** - 2024 February, A Shell 7.0.1755: Windows 11 printing refinement: A-Shell/Windows and ATE now force Windows to use the traditional print dialog rather than the newfangled Windows 11 version, which isn't well suited to our purposes. A-Shell Reference Page 313 ## **DEVICE = DISK:** The third special pseudo-device is DISK:, which as its name implies, leaves the file on disk, and it works under both A-Shell/Windows and A-Shell/Unix. There are two variations of this device as shown here: ``` DEVICE = DISK: ``` ``` DEVICE = DISK:g:\vm\miame\dsk0\301222 ``` ``` DEVICE = DISK:%ATECACHEDIR% ``` In the first example, the file is simply left in place rather than being sent to the spooler. In the second example, the print file is moved to the specified directory. (It must be an existing directory in the native host directory format.) In the third case, the file would be copied to the ATE Cache directory rather than printed. Case is not significant for Windows, but is for Unix. When printing to the DISK: pseudo-printer (including via ATEAPX.SBX), the target directory will be created if necessary. Note, however, that the parent directory must exist. A-Shell Reference Page 314 ## **DEVICE = LASTPROMPT:** _Added December 2019_ Beginning with A-Shell 6.5.1672, the printer pseudo device LASTPROMPT: uses the printer last selected in an A-Shell or ATE printer selection dialog. As with PROMPT:, it can be used with ATE AUXLOC: printing, i.e. ``` DEVICE=AUXLOC:LASTPROMPT: ``` The above would send the printout to ATE via the AUXLOC: device, where ATE would then send it to the printer previously selected. Note that the PROMPT: device also uses the printer previously selected as the default printer in the selection dialog, while PROMPT(DEFAULT): useS the printer set as "the default" in your Windows printer definitions. ## **History** - 2019 December, A Shell 6.5.1672: Function added to A-Shell A-Shell Reference Page 315 ## **DUPLEX** ## **DUPLEX =