A Guide To The UniVision System
Transcription
A Guide To The UniVision System
A Guide To The UniVision System Version 3 Publication No. 44-00100-98A April 1998 rd 3 Edition, April1998 It is the policy of Objectware Inc., and its subsidiaries, to improve products as new technology, components, software and firmware become available. Objectware Inc., and its subsidiaries, therefore, reserves the right to change specifications without prior notice. All features, functions, and operations described herein may not be marketed by Objectware Inc., and its subsidiaries, in all parts of the world. Therefore, before using this document, consult your system supplier for information that is applicable and current. Copyright Notice This document contains information which is proprietary to and considered a trade secret of Objectware Inc., and its subsidiaries. It is expressly agreed that it shall not be reproduced in whole or part, disclosed, divulged or otherwise made available to any third party directly or indirectly. Reproduction of this document for any purpose is prohibited without the prior express written authorisation of Objectware Inc. Disclaimer Objectware Inc., and its subsidiaries, makes no representation and no expressed or implied warranty of any kind with the regard to the documentation for any particular purpose. Whilst every effort has been made to ensure the accuracy of the documentation Objectware Inc., and its subsidiaries, accepts no liability for any losses or consequential damages arising directly or indirectly from the use of the documentation. Objectware Inc., and its subsidiaries, reserves the right to amend this documentation without obligation to notify any person or organisation of any such amendments. 1998 Objectware Inc. ! Note: The information contained herein is correct as of 28 February 1998 th A Guide to the UniVision System Preface ABOUT THIS GUIDE Organisation of the Documentation Set The UniVision documentation set includes the following manuals: A Guide to the UniVision System: This guide describes the UniVision system and explains how to use it. Designed for the applications programmer it explains concepts and terminology essential to understanding the structure and operation of the UniVision system. UniVision Command Reference Guide: This guide is a general reference source for the commands available under the UniVision system. It gives experienced users complete information about command usage. The guide includes reference pages for all UniVision commands organised into the following sections: UCL stacker commands, User Account verbs, SYSPROG verbs, connectives, modifiers, and options, correlatives and conversions, Editor commands and PROC commands. UniVision Database Processors Guide: This manual contains four separate guides: one each for VISION, the PROC processor, the Editor, and Runoff. A separate section describes each processor. UniVision BASIC Reference Guide: This guide is a reference for the BASIC language, the application development tool under UniVision. Designed for the experienced programmer it covers all BASIC statements and functions, listed alphabetically. UniVision System Administration Guide: This guide covers all tasks normally performed by the UniVision system administrator. It includes such things as system start-up and shutdown, creating and deleting accounts, performing day-to-day management and backing up and restoring the system. Included with the UniVision System Administration Guide is a separately bound handbook of UniVision Operating Procedures for system operators. Preface xi Documentation Relationship Advanced Users, Developers UniVision Database Processors Guide VISION Reference Guide PROC Reference Guide Editor Reference Guide Runoff Reference Guide UniVision BASIC Reference Guide Administrators UniVision System Administration Guide All Users A Guide to the UniVision System UniVision Command Reference Guide Important Note UniVision is an application that resides on a base-operating environment such as UNIX SVR4, AIX, Windows NT etc. Organisation of this Guide A Guide to the UniVision System comprises the following sections: Section 1, System Overview, provides an introduction to the UniVision system. It discusses the hardware components that make up the system as well as the system software, and introduces some fundamental database concepts that are unique to the system. Section 2, Users Accounts, describes the structure and contents of user accounts. Topics covered are how to log on and off the system, how to enter commands using the UniVision Control Language (UCL), and how to use the UCL Stacker. In addition it describes the contents of an account's Master Dictionary. Section 3, Creating a Database, shows how to design and create a simple database made up of a single file. It explains how to create files, how to define entries in the file dictionary, and how to enter data. Section 4, Database Architecture, explains the UniVision file hierarchy in detail. It describes the structure of dictionary items; Account Definition items, Verb Definition items, File Definition items, and Attribute Definition items. The section concludes with an explanation of the hierarchical structure of items (that is, their division into attributes, values and sub-values), and a brief introduction to correlatives and conversions. xii A Guide to the UniVision System Section 5, The UniVision Database Management System, describes the fundamental structure of the UniVision database management system. Among the topics covered are methods of file access, and management of peripheral devices. Section 6, The UniVision Control Language, describes the user's interactive working environment in detail. It explains how to log on and off the system, how to set communications line characteristics and user process characteristics, how to us UCL commands, and how to use the UCL Stacker. Topics introduced in Section 2 and covered in more detail in this Section. Section 7, File Management, provides an overview of how to manage files on the UniVision system. Topics covered are: creating and deleting files, copying file items, creating Q-pointers to files in other accounts, protecting your files, resizing files for retrieval efficiency, and backing up and restoring files. Section 8, Account Management, discusses the SYSPROG account, how you create and delete accounts, the SYSTEM Dictionary and its contents, and the ERRMSG file. Section 9, The Spooler, introduces the system process that manages printing operations for the UniVision system. It explains how the spooler works and describes the commands used to do such things as change the default printer assignment, cancel a print job and capture output in Spooler hold files. Section 10, Using Magnetic Tape, describes the commands used for writing and reading magnetic tapes. It contains a tutorial for new users that introduces the fundamental commands, guiding the user step-by-step through the process of creating a tape. Section 11, Data Communications, describes how the UniVision system communicates with other computer systems. It explains how to establish the connection between two machines, and how to use that connection to initiate a remote logon session on the other machine. Section 12, B+Tree Files and Secondary Indexing, describes the B+Tree files. B+Trees are dynamic structures that guide the storage mechanism to the proper disk page through a tree like series of pointers. In addition, it explains how to support secondary indexing. Section 13, Database Triggers, covers an overview of Database Triggers. Triggered procedures are UniVision BASIC subroutines that control the behaviour of the UniVision Database environment. rd Section 14, External File Handling, covers access of data on 3 party file handlers. Section 15, Remote File Handling, covers how to set up two or more systems to provide access across multiple UniVision environments. Preface xiii Sample Files Throughout this guide, reports and examples are based on a sample application: a mail order publishing business. The application consists of three main files: 1. The CUSTOMERS file, which contains the names, addresses, and phone numbers of individual customers. 2. The ORDERS file, which contains information about book orders, including dates and sale amounts. 3. The BOOK-CATALOG file, which contains titles, prices, and other information about the mail-order business's inventory. Syntax Notation The following conventions indicate command line syntax throughout the documentation set. Convention Usage BOLD CAPS You must type anything shown in upper-case bold characters exactly as shown. italics Anything shown in italics is variable information that the user provides a specific value. () You must type parentheses. It is usually sufficient to type only the first parenthesis; the second is optional. [] Anything shown enclosed in brackets is optional. You do not type the brackets themselves. | A vertical bar separating two or more elements indicates that you can type any one of the elements. {} Two or more elements enclosed in braces and separated by a bar, indicate you must type one of the elements. You must enter all punctuation marks included in syntax format lines (for example, commas, parentheses, angle brackets, underscores, and hyphens) unless otherwise indicated. You do not type the brackets. In the following syntax example: LIST [DICT] filename [WITH[EVERY|EACH] attribute-name value-list][(P)] xiv A Guide to the UniVision System the only two elements of the line that you must enter are 'LIST' and 'filename'. You must enter 'LIST' exactly as shown. 'filename' is a variable; you can enter the name of any accessible file. 'attribute-name' and 'value-list' are also variables that the user supplies. The vertical bar indicates that you can enter either 'EVERY' or 'EACH'; the brackets indicate that both of these keywords are optional. If you enter the 'P' option, you must enclose it in parentheses. When variables supplied by the user are two or more words long, hyphens, instead of blank spaces separate the words indicate that you only require one element. For example, in the command: LIST filename item-list the word filename indicates a single element, and the words item and list joined by a hyphen likewise indicate a single element. Notation in Examples Screen examples use the following conventions: Convention Usage BOLD Anything the user types as input. PLAIN Any output displayed by the system (prompts, responses to user input, etc.). <RETURN> Indicates that you must press the RETURN key. <CTRL-char > Indicates that you should type a control character. To enter a control character, simultaneously hold down the CONTROL (CTRL) key and press the specified character. You enter most commands by typing the command line at one of the prompts and pressing the RETURN key. This is true whether you are entering a one-letter Editor command or a lengthy VISION statement. Therefore, in examples the RETURN key symbol (<RETURN>) only appears in cases where it is necessary for clarity. ! Note: Preface This symbol indicates an important note or caution. xv Section 1 SYSTEM OVERVIEW UniVision allows multiple users to work interactively on a computer, performing a variety of tasks that involve access to a central database. The database organises information about a business, such as employee salary, parts inventory, customer orders, product manufacturing, and accounting. One major task performed by UniVision is generating reports that organise and arrange the data stored in the database into useful information. A business might generate reports that show the volume of sales or the size of current inventory. Normally, you perform tasks such as report generation under the control of an application program that makes the underlying facilities of the system available in a structured, useful manner. The key insight incorporated into UniVision is that businesses use a computer to organise information. All the facilities of the computer system are designed around how the UniVision system organises data. This section describes the way in which UniVision organises data, UniVision as a whole, how it manages the computer system, and what facilities it provides for users. If you prefer to use the system right away, skip to the section entitled User Accounts for a more 'hands-on' approach to learning the system. You might want to return to this section at a later date to get a thorough overview of how UniVision works. Organising Information UniVision is a database model for the storage and retrieval of data. This model makes UniVision ideal for describing the kinds of data managed in a business application. A UniVision database is a collection of files. A file is a collection of related data. UniVision uses dictionaries to define the relationships among files and to identify the data they contain. A dictionary is itself a file. System Overview 1-1 The UniVision file system comprises four levels: • SYSTEM Dictionary level • Master Dictionary level • file dictionary level • data file level The following figure illustrates the hierarchical structure of the UniVision file system. The following description begins at the top of the hierarchy and moves down it. System Level SYSTEM DICTIONARY MASTER DICTIONARY DICTIONARY DATA Master Dictionary Level MASTER DICTIONARY File Dictionary Level DICTIONARY DATA Data File Level DATA Figure 1-1 UniVision organises its files hierarchically Each system has a single SYSTEM Dictionary used to store information gathered and needed system-wide. This includes information on user accounts, system usage, and security. Typically only the system administrator accesses the SYSTEM Dictionary through the SYSPROG account. 1-2 A Guide to the UniVision System A Master Dictionary represents the account-level. An account is a user's place on the system, just as an employee works in a particular office. Each account has its own Master Dictionary that you can tailor to the needs of the users of that account. All the files and verbs that are available to an account have entries in the Master Dictionary. A file dictionary can point to one or more data-level files. The file dictionary and the data file are distinct sets of data stored in separate files. However, logically you can think of it as a single data file comprising a dictionary portion and a data portion. Each data-level file is associated with a file dictionary. The dictionary defines the format of the data files associated with it. The system stores the actual data that appears in a report in the data file. When you use the name of a file in a command, the system looks up the filename in the Master Dictionary of that account and follows a pointer to the file's dictionary. This dictionary, in turn, contains a pointer that points to the data file. Structure of Data A UniVision file contains any number of variable length items. An item is equivalent to a record in standard data processing terminology. For instance, in a file containing information about employees, each employee would be described in a single item. In addition, a dictionary consists of items, but to prevent confusion we sometimes refer to dictionary items as entries or descriptors. Figure 1-2 illustrates the elements of an item. An item consists of any number of attributes, which are basically the equivalent of fields. An attribute is a container of data that can hold a single value or multiple values. For instance, the attribute LASTNAME holds an employee's last name. The value of this attribute varies from item to item; it might be 'Jones' or 'Smith'. The attribute PHONE might hold more than one value for each item, for instance, the person's work number and home number. Values in turn can contain any number of sub-values. Attributes, values, and sub-values are all of variable length. System Overview 1-3 Attributes Item 1 2 3 4 Value Value 5 Value Sub- Values Multiple Values Figure 1-2 The elements of an item You must assign a unique item ID or key to each item. The system uses this key to access the item in the file. For instance, you might use an employee’s Social Security number as an Item ID. To programmers, a file is a collection of individually accessed items. Each item is a string containing various delimiter characters to indicate attributes, values, and sub-values. UniVision UniVision is, in fact, an application that resides on a base-operating environment such as UNIX SVR4, AIX, Windows NT, etc. System Software You can define the functions of the system software in terms of the facilities it has to manage. In the following section, we look at how the UniVision system manages: 1-4 • Users • Files A Guide to the UniVision System Managing Users Perhaps UniVision's biggest responsibility is to manage the work performed by users. Each user working at a terminal is connected, by cable, to one of the communications ports on the system. Each port is linked to a user process. Generally, a user process is a structure representing the user's activity on the system. Initially all user processes are set to use the Logon processor. The Logon processor sends a message to the user's screen, such as the one below. Logon Please: The job of the Logon processor is to wait for a response to this prompt and verify that the user belongs on the system. The user must supply the valid name of an account and a password to log onto the system. Once the system has verified the user's response, it gives them access to an account. All the files and programs that the user needs are available to this account. The UniVision Control Language (UCL) processor displays a prompt (>) on the user's screen. When the user enters a command line or statement, the UCL processor determines which system processor the user intends to use and executes the program. The system processor communicates with the user process and the communications line associated with it. Perhaps it prompts for additional input or sends output to the screen. On completion, control of the user process returns to UCL. There are a number of processors in UniVision. This guide describes most of them. Table 1-1 contains a list of several UniVision system processors together with a brief description of their use. System Overview 1-5 Processor Description VISION A database language processor that accepts English-like query statements and generates formatted reports. BASIC An extended version of Dartmouth BASIC programming language, that enables a program to be compiled and executed. ED A line-oriented editor for editing programs and files. In addition, UniVision supports a full screen text editor, DE. UCL The UniVision Control Language processor that allows a user to invoke other processors. PROC A procedural language processor that interprets a series of stored commands. Used to automate any sequence of operations performed by entering commands at a terminal. Table 1-1: UniVision System Processors Process Scheduling The base operating system handles process scheduling. Managing Files A UniVision file consists of one or more groups of frames. The minimum size of a group is one frame (2048 bytes, of which 2000 is available for data). The system references a file by its base (the frame ID of the first group). In the file dictionary, an entry for a file keeps track of the base frame ID as well as the number of groups of a file. The number of groups is known as the file's modulo. It represents an area of space on the disk, known as the primary file space. The system allocates this space when a user is creating a file and remains fixed regardless of how the file grows or shrinks. The system stores each item in a particular group, as illustrated below. UniVision uses a random-access technique known as hashing to distribute items in a file. It derives the group address of an item from the item ID. The result of a hashing computation is the number of a particular group, from zero to one less than the number of groups or modulo. The system adds this result to the base frame ID of the file to come up with a specific frame ID. Once the system locates this frame, it searches through the contents of this group sequentially through the entire file by narrowing the search to a particular group. 1-6 A Guide to the UniVision System An item always hashes to the same group, even if that group is full. When you exceed the capacity of a group, the system takes the additional frames from a table of available frames, the Overflow table, and links to that group. These frames are referred to as the secondary file area. If you reduce the size of the group, the system returns the frames in the secondary file area to the Overflow Table. The system only allocates these frames as needed. Groups are like dividers in a file drawer, organising items in a file Item Item GROUP 2 Item Item GROUP 1 FILE Figure 1-3 Each item hashes to a particular group The penalty of allowing a group to overflow into secondary frames is that additional disk reads are necessary in order to access items that are not in the primary frame of the group. Therefore, reallocating a file to increase the modulo helps to distribute items more efficiently across all groups. In this section, we have covered the basic facilities of UniVision. In subsequent sections you will learn more about these facilities and the commands that access them. Before continuing on to the next section, you might review the terms introduced in this section. System Overview 1-7 Glossary Account Groups of files and verbs by a Master Dictionary (MD). A user gains access to an account when logging on. AMC Attribute mark counter, or attribute number. Attribute Structure that contains one or more data values. It is possible to sub-divide attributes to comprise multi-values and multiple sub-values. An attribute is analogous to a field used on other systems. Attribute mark System delimiter used to separate attributes. It is ASCII value 254 (hexadecimal FE). Base Frame ID of the first group of a file, specified by Attribute 2 of a File Definition item. CPU Central Processing Unit Database Collection of logically related data organised for efficient storage and retrieval. A database might consist of a group of files or a single file. Data file Fourth-level file associated with a dictionary on the previous level. The data file contains the raw data whereas the dictionary defined the structure of the data. Dictionary File structure for defining the structure of data. File Dictionary File structure that points to a data file on the next level and defines its contents. If you have not associated a file dictionary with a data file, it points to itself. 1-8 Form Queue Logical print queue that permits the association of a particular form with one or more printers. Frame Fixed length unit of storage; 2048 bytes for UniVision Group Group of items whose item Ids hash to the same group number. Initially a file consists of a set of contiguous frames as indicates by the modulo. Individuals groups can overflow into secondary allocation when the primary frames become full. Item Piece of data in a file. Analogous to record used on other systems. Item ID Key used to access any item. A Guide to the UniVision System Logical Tape Unit Number that identifies a tape drive Master Dictionary Master file of any account on the system. It contains definition items for all verbs, VISION keywords, Procs, and file accessible to an account. Modulo Number of groups allocated for a file; it represents an area of contiguous disk space. Overflow Table Table that keeps track of available frames that the system can use to expand the storage of a group. Peripheral Device Various hardware devices connected to the computer, such as terminal, tape drives, printers, modems, etc. RAM Random Access Memory – main memory of the computer system. Spooler System process that handles all printer operations. SYSTEM Dictionary Master file of the UniVision system at the top of the file hierarchy. It holds Account Definition items that define all accounts on the system. UCL UniVision Control Language. The UCL processor handles most of the user’s communication with the computer, passing control to other system processors whenever appropriate. In most cases control returns to UCL on completion of other processing User process Part of the UniVision system that handles all user activity. Each terminal connects to the computer via a serial port that, in turn, links to a user process. Value Structural sub-division of an attribute. Attributes can comprise one or more values. Virtual Memory Way of overcoming the limitations of RAM size by using the hard disk as an extension of physical memory. System Overview 1-9 Section 2 USER ACCOUNTS An account is a user's place on UniVision. It controls a user's computing environment by providing access to system resources and files. You can customise this account for the needs of a particular user or application such that the collection of files and processors available might differ from one account to the next. A user must know the name of the account, and usually a password, to be able to log on to the account. On logging on, communication with the system is usually via UniVision Control Language (UCL). The UCL processor interprets commands entered at the user's terminal and initiates processing by other system processors, such as the Editor, VISION and BASIC. This Section covers logging on and off the system, entering a few basic commands, and examines the contents of a user account and a sample file. Creating an Account On a newly installed system, there is one master account, called SYSPROG, used by the administrator to perform system-wide tasks such as adding new user accounts. When an administrator creates a new account, three things happen: • The system allocates space for the Master Dictionary of the account. • The system creates an Account Definition item in the SYSTEM Dictionary. • The system copies all items in the NEWAC file, located in the SYSTEM Dictionary, into the new account's Master Dictionary. The account definition in the SYSTEM Dictionary identifies the location of an account's Master Dictionary. It defines the security level of the account and sets access restrictions, including passwords that prevent unauthorised users from gaining entry to the system. In addition it can specify various options that customise the user's computing environment. The administrator can set up unique user IDs, enabling multiple users to use the same account, but requiring each user to identify their own logon name and password. User Accounts 2-1 The Section entitled Database Architecture describes the format of Account Definition items. ! Note: It is assumed that the administrator has set up an account for you and that you know the logon name and password for the logon account. If you do not have an account, ask your administrator to create one for you, or follow the procedures described in the Section entitled Creating and Deleting Accounts in the UniVision System Administration Guide. Logging On and Off Logging to the UniVision Environment Login is the process of gaining access to the UniVision environment. You must have installed UniVision and set up the environment according to the loading instructions. During the initial installation of UniVision, the system allows the installer to install the software in a different directory other than the default directory of /home/UniVision. During installation you can specify a password that any user must know when logging in. Check with the system administrator for the login name and password. If you use the default directory for UniVision, the login for UniVision is UniV. ! Note: If you use the default directory, you must use capital U and V and the remaining letters must be in lower-case. If this is not so the system does not recognise you as a valid user. For example, a typical login is as follows: UNIX System V Release 5.0 Version 3.0 login: UniV Password: ! Note: 2-2 For security reasons, the operating system does not echo the password typed by the user. Type both the login name and password correctly, otherwise the system denies login. In addition, under some operating system releases with the proper option, if you have not created a password for the login directory the system might not prompt you for a password. A Guide to the UniVision System After you have completed the login process, on a UNIX based system it displays a login banner and copyright notice. You are now at the Logon Please: prompt where you are in the UniVision environment but have not gained access to a user account or database. To gain access to the database you must logon. Logging On Logging on is the process of gaining access to the system from a terminal. The system must be up and running, and the terminal must be connected to the system and turned on. The following logon prompt (or similar one) should appear on the screen: Logon Please: To logon, type the account name (or user ID) and press <RETURN>. Be sure to enter the account name in upper case. If the account is password protected, the system prompts for you to enter it. The characters do not appear on the screen as you type the password. It is possible to enter both the account name and password at the logon prompt. You must follow the account name with a comma and the password, as shown below: Logon Please: JOHN, OVL314 ! Note: If you use this form of logon the system does not echo the password to the screen, nor does it display the Password prompt. If you do not enter a valid account name and password, the system redisplays the logon prompt for additional attempts. At some sites, after several unsuccessful logon attempts, the system inhibits logging on for a fixed period of time, refer to LOCKOUT in the UniVision Command Reference Guide for more detail. In addition, the administrator might prevent users from logging on while the system performs certain maintenance or system backup tasks. If you have any problems logging on, contact your administrator. Once a user has logged on, the system displays a message identifying the UniVision software release and the current system date. User Accounts 2-3 [] UniVision time is 16:49:26 12 JUL 1995 [] Logon Please: JOHN, OVL314 [[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]] [] e|d|p [] [] Research & Development Group [] [] GCA Release 2 [] [] Version 4.10.6 [] [] Wed Jul 12 10:20:30 GMT 1995 [] [[[[[[[[[[[[[[[[[[[[[[[[[[[]]]]]]]]]]]]]]]]]]]]]]]]]]] > ! Note: The system does not echo the password to the screen. UCL displays the greater-than symbol (>) as the system prompt. When this prompt appears on the screen, the user can begin entering commands. It is possible for system suppliers and administrators to customise both the logon prompt and the messages that appear when logging on. Therefore, it is possible that something different from the display shown in this section to appear on the screen. In addition, the sequence of events after logging on might differ. The Section entitled The UniVision Control Language, describes use of a Logon Proc to control what happens after logging on. For instance, you can use it to start up a BASIC application so that the user never gets to the UCL prompt. Logging Off To end a user session, type OFF at the UCL prompt and press <RETURN>. On logging off, the system displays a message that gives usage statistics for the current user session and the logon prompt appears on the screen. >OFF [] [] Connect time = 0 mins.; CPU = 1 units; LPTR pages = 0 Logged off at 20:32:56 on 03 MAY 1989 [] [] [] UniVision time is [] 20:32:56 03 MAY 1989 Logon Please: If OFF does not succeed in logging off from the system, make sure that you entered it at the UCL prompt. For example, if you are in another processor, such as the Editor, which uses a period (.) as the prompt character, you must exit the Editor before you can log off. 2-4 A Guide to the UniVision System The UniVision system has an auto-logoff feature which, when implemented by the system administrator, logs off any user automatically after a specified duration of inactivity. For instance, if you leave your terminal and go to lunch, you might find that you have been logged off by the time you return. For more detail refer to AUTO-LOGOFF in the UniVision Command Reference Guide. Exiting the UniVision Environment To exit the UniVision Environment at UCL you can enter OFF to logoff the user account, followed by QUIT at the Logon Please prompt. QUIT returns the user to the UNIX login prompt. A one step method exists for the above. A user at UCL can enter :QUIT to logoff the user account and return to UNIX. Introducing the UniVision Control Language The UniVision Control Language (UCL) is the primary interface between the user and UniVision. It is a command processor. st When you enter a command line at the UCL prompt, UCL looks at the 1 word typed, and looks up the word in the Master Dictionary. If it finds an entry, it identifies a system processor and passes control to the processor. The system processor interprets the rest of the command line. As shown in Figure 2-1, UCL acts on user commands to invoke other system processors. User Accounts 2-5 DATA/ BASIC Editor VISION PROC Spooler UniVision System Processors Figure 2-1 The UniVision Control Language interprets input from the user’s terminal and passes control to other system processors The following is a description of a few simple commands. WHO displays two pieces of useful information: the number of the user process associated with the terminal and the name of the account logged on. To enter WHO, type WHO at the UCL prompt and press <RETURN>: WHO 2 JOHN WHO is the user's input entered at the UCL prompt. 2 JOHN is the output returned by the command. 2 is the user process number. The system identifies each user process by a unique number in a range from 0 to the maximum number of users supported. JOHN is the name of the account. The user process number is independent from the account. If you log on to a different account from the same terminal, the account name would change, but the process number would be the same. Many commands have optional parameters that modify the action of the verb. In addition, WHO has an optional * parameter that allows you to see this information for all users on the system. The following example shows a listing for all users currently logged on to a system. 2-6 A Guide to the UniVision System > WHO 2 JOHN > WHO * 0 JULIE 1 FRED 2 JOHN 3 STAFF 4 WALTER 5 LINDA 6 KATIE 7 UNKNOWN 8 UNKNOWN 9 UNKNOWN 10 UNKNOWN 11 UNKNOWN 12 UNKNOWN 13 UNKNOWN 14 UNKNOWN 15 UNKNOWN The full output produced by WHO * tells us that this system supports 16 users (015) and that only seven users are currently logged in. For instance, 'LINDA' is on user process 5. If you require a printout of this result, add the P option to the command line. Enclose the option in parentheses. > WHO * (P) Instead of the listing appearing on the screen, a message tells the user that the system has sent the output to a printer. UCL Prompt Parameter >WHO*(P) Option Command Figure 2-2 A UCL statements consists of a verb followed by optional or required parameters and any parenthetical options User Accounts 2-7 Entering Commands A UCL statement consists of a verb, optional or required parameters, and options enclosed in parentheses: verb [parameters][(] options [)] Figure 2-2 shows an example of these syntactical elements. You must type the entire statement in upper-case characters. The system does not interpret the statement until you press <RETURN>. The verb is the action word that initiates processing. The set of optional or required parameters is specific to the verb. For instance, COPY that copies items in a file, takes two parameters: the name of a file followed by the name of an item. COPY ORDERS 10118 COPY is the verb, 'ORDERS' is the name of file defined in the account, and '10118' identifies an item in that file. When you enter this command line, the system responds with TO:, prompting for the destination for the copy operation. Pressing <RETURN> at this prompt causes the system to display the item on the screen. Parenthetical options appear at the end of a command line and are surrounded by parentheses. You only require the left parenthesis for the system to recognise the option. CT ORDERS 10118 (P You can use the P option with any of the commands described in this section to direct the output to the printer. Options comprise a single alphabetic character or a single number or two numbers indicating a range (n-m). You ca specify multiple options without spaces or delimiters between them, although you can separate options with commas. For a complete list of parenthetical options, refer to the Section entitled Connectives, Modifiers and Options in the UniVision Command Reference Guide. Editing the Command Line You can change what you typed on the command line up until the time you press <RETURN>. Table 2-1 lists the control characters available for editing the command line. 2-8 A Guide to the UniVision System Character Operation <CTRL-H> Backspace over and delete previous character. Same as <BACKSPACE>. <CTRL-W> Backspace over and delete last word. <CRTL-X> Cancel and delete entire command line. <CTRL-R> Redisplay line. One use is during a communication session to see if garbage characters stemming from noisy telephone lines affect the UCL input line. Table 2-1: Control Characters Paging Some commands produce more output than can fit on a single screen. Normally the processor displays one page of output at a time and pauses. To see the next page of output, press any key. To exit instead of seeing the next page of output, press <CTRL-X>, which returns to the UCL prompt. This is particularly useful to know when producing VISION reports on the terminal. If you find what you want st in the 1 page, you can exit and ignore the rest of the output. You can specify the parenthetical option N (NOPAGE) on the command line to disable paging. In other words, output to the screen is continuous. To control the flow of output, press <CTRL-S> to halt the output and <CTRL-Q> to resume output. (This works whether or not paging is in effect). <CTRL-S> and <CTRL-Q> send X-OFF and X-ON signals, respectively, to the communications line. You must enable the X-ON/X-OFF protocol for your communications line for these control sequences to work. LIST-LINE-CHARS or LINE-PROTOCOL list line settings for each line on the system. You can use PROTOCOL to change these settings. The Break Key While a system process is running, it remains in control of the terminal. Normally you require the system process to complete its work and return control to the UCL level. If you press <BREAK> while a process is running, the system suspends it and invokes debugger. Programmers use debugger to examine the state of a program as it is executing. UniVision has two debuggers: the system debugger, identified by an exclamation mark (!) prompt and the BASIC debugger, identified by an asterisk (*) prompt. If you break a program by accident, you can resume execution of the process by typing G. User Accounts 2-9 There are two other debugger commands that you might want to know. END which terminates the suspended process and returns to UCL. OFF which logs you off the system. For instance, to exit to the UCL prompt from the system debugger, type END and press <RETURN>. !END > ! Note: You should be extremely cautious in exiting a process because it might have been updating items in a file. Consult with your system administrator if you enter the debugger unexpectedly. You can enable or disable <BREAK> using DEBUG-ON and DEBUG-OFF, respectively; the default setting is <BREAK> enabled. In addition, you can disable it by placing B in Attribute 9 of the Account Definition item. Introducing the UCL Stacker A useful feature of UCL is the UCL Stacker. The UCL Stacker puts each command entered on top of a 'stack'. You can list the contents of the stack and review recent statements. You can recall, modify, and re-execute any statement in the stack. You can save a series of commands as an item in a file. This can save a lot of time when typing long VISION statements or performing a sequence of actions such as editing, compiling, and running a program. The system specifies UCL Stacker commands with a period (.) that precedes a single-letter command. The section entitled The UniVision Control Language, reviews all of the UCL Stacker commands. The following shows two most frequently used commands: Stacker Command Function .L List most recent statements. Can specify the number of statements to list, default is 20. .X Execute last statement. Can execute any statement for stack by supplying its number. The following example shows .L; the output is a list of the commands executed so far during this session. ! Note: 2-10 The most recently submitted command is at the top of the stack. A Guide to the UniVision System .L 001 WHO A (P 002 WHO A 003 WHO The default length of the stack is 20. That is, you can list up to 20 previous commands. You can execute any command from the stack using .X. .X3 WHO 2 JOHN .X without an argument executes the statement on top of the stack. The Master Dictionary The Master Dictionary provides each account with its own view of the UniVision system. It defines the user's vocabulary. You can customise the Master Dictionary in a variety of ways for user preferences or to establish the 'vocabulary' needed or a specific application. The Master Dictionary contains six types of entry, as shown in Figure 2-3. The Section entitled Creating a Database describes the format of the dictionary entries. MASTER DICTIONARY File Definition Items Attribute Definition Items VISION Keywords PROC Verb Definition Items File Synonym Items Figure 2-3 The Master Dictionary contains six types of entry User Accounts 2-11 Verb Definition item identifies a command you can execute in this account. File Definition item is a pointer to a database file. In the Master Dictionary, the D-pointer supplies the location and size(modulo) of the dictionary. The dictionary in turn contains a D-pointer that supplies the location and size of the data file. File Synonym item is a pointer to a File Definition item. Instead of pointing to the location of the file, the Q-pointer is a reference to a File Definition item in the user's account or in any other account on the system. Attribute Definition item describes data by identifying a specific attribute of a data file item, or it derives data by operating on existing data. It describes how VISION should format the data. The system stores most Attribute Definition items in the dictionary associated with the data file, but, in addition, it searches the Master Dictionary if it cannot find the entry for an attribute identified in a VISION statement in the file dictionary. Proc is a series of commands interpreted by the PROC system processor. Procs stored in the Master Dictionary can invoke Procs stored in special files, such as UVPROCS. VISION Keywords are syntactical elements of the VISION data retrieval language. Keywords comprise connectives (such as AND, OR, or USING), and modifiers (such as WITH, BY, or TOTAL). st When a user enters a statement, UCL expects the 1 word in the statement to be a verb, a Proc or a UCL Stacker command. When you enter a verb, UCL looks for a Verb Definition item in the account's Master Dictionary. This entry points to the location of the program code actually executed. The Section entitled Database Architecture describes the format of Verb Definition items. If you cannot identify the verb, the system displays the following error message: [3] Verb? In most cases, when this message appears, the user has mistyped the statement. The [3] preceding this message identifies this message by number in a system file named ERRMSG. Examining an Account You can examine the contents of an account by looking at the Master Dictionary. The following sections introduce a few commands that allow you to examine the Master Dictionary. 2-12 A Guide to the UniVision System Listing the Files You can use LISTFILES to view a list of the files available in the account. It generates a VISION statement that selects a set of related items, sorts them alphabetically by name, and displays the contents of various attributes. Generally, the LISTFILES report is too long for it to be displayed all at once on a screen. The system pauses after displaying one page of output and waits for you to press a key before displaying the next page. An example of the LISTFILES report follows >LISTFILES PAGE 1 *** MD *** FILE DEFINING ITEMS 13 JUL 1993 MD FILE TYPE FILE BASE........... F/MOD........ BP CONV CUSTOMERS LOCKXREF NEWAC ORDERS-WINTER PATCHES PAYROLL POINTER-FI SAVEDFILE SM SN STAT-FILE SYSPROG-BP SYSPROG-L TC TEST2 ACC BASICLIB DC DC D D D D D D DC D D D D DC DC D D Q Q 4717 4343 6762 3398 3390 8437 3467 8162 3428 8435 3512 4379 4768 3498 4724 8271 8245 ACC BASICLIB 1 1 3 1 1 1 1 1 7 1 1 1 1 1 1 1 1 ACC BASICLIB You can summarise the report produced by LISTFILES as follows. The report lists information in four columns and displays a row of data for each File Definition st item in the Master Dictionary. The 1 column contains the names of files. The filename is the item ID of a File Definition item. The next three columns correspond to the first three attributes of a File Definition item. The column labelled FILE TYPE lists a Definition Code that identifies what kind of item it is. A value of D indicates a D-pointer to a file located in the account. nd The 2 attribute, FILE BASE, of a D-pointer specifies the base frame ID used to st rd locate the 1 group on disk for the file. The 3 attribute, F/MOD, specifies the modulo of the file or the number of groups occupied by the file. User Accounts 2-13 In the sections that follow, many examples make use of the CUSTOMERS file. It contains basic information such as name, address, and phone number for a group of individual customers. Find the File Definition item in the example for CUSTOMERS; it has a base of 6762 and consists of 3 groups. In addition, this report lists Q-pointers. Q-pointers reference files located in this nd and other accounts on the system. The 2 attribute of a Q-pointer identifies the account in which the file is located. If null, you can find the file in the same rd account. The 3 attribute identifies the name of the file in that account. If null, the file is the Master Dictionary. MD and M/DICT are Q-pointers that refer to the Master Dictionary itself. Enter LISTFILES at the UCL prompt to display a listing of the files defined in your account. In addition, you can try LISTVERBS that displays a listing of the verbs defined in your account. It shows the first five attributes of Verb Definition items in the Master Dictionary. The output from this report is less meaningful to a new user; you will understand it better when we look at the format of Verb Definition items in the Section entitled The UniVision Control Language. Listing the Contents of Items You can use CT (Copy to Terminal) to see a copy of one or more items from any file. (It is a Proc that invokes the COPY processor.) CT is a very useful command for looking at items in the Master Dictionary or in any file. You can view the item on your screen or send it to the printer to get a hard copy. You must specify the name of a file and a valid item ID in that file. You can specify multiple item IDs by separating each one with a space. CT [DICT] filename item-list [(options)] Use CT to examine a File Definition item in the Master Dictionary, a File Definition item in a file dictionary, and finally a data item in a data file. These examples using the sample file CUSTOMERS illustrate the multi-level relationship among the Master Dictionary, the file dictionary and the data file shown in Figure 2-4 2-14 A Guide to the UniVision System CUSTOMERS 001 D 002 11408 003 3 . . Master Dictionary CUSTOMERS 001 D 002 11411 003 3 . . File Dictionary JBOHA5422 001 JOHN 002 BOHANNON 003 126 TREMONT ST . . Data File Figure 2-4 The Master Dictionary contains a pointer to the dictionary that contains a pointer to the data file The following example lists the File Definition item for CUSTOMERS in the Master Dictionary > CT MD CUSTOMERS CUSTOMERS 001 002 003 004 005 006 007 008 009 010 D 11408 3 L 10 > This D-pointer file identifies the location of the dictionary for the CUSTOMERS file A portion of this dictionary appeared in the previous LISTFILES report. The CUSTOMERS file dictionary contains an item named 'CUSTOMERS' that is the pointer to the data file. The next example shows that item: User Accounts 2-15 >CT DICT CUSTOMERS CUSTOMERS 001 002 003 004 005 006 007 008 009 010 CUSTOMERS D 11411 3 L 12 > The DICT modifier specifies the dictionary of a data file. CUSTOMERS appears as both the filename and the item ID in the command. This item is virtually identical to the File Definition item in the Master Dictionary, except for the specification of a different base. The base frame ID of 11408 points to the location of the data file. rd The 3 example lists an item from the CUSTOMERS data file. >CT CUSTOMERS AJOHN5396 001 002 003 004 005 006 007 008 AJOHN5396 ANNE JOHNSON 760 JEFFERSON STREET LOUISVILLE KY 6069034566 99475 192-83-7465 AJOHN5396 is the item ID of this item, which has eight attributes. This item contains data; it does not contain any information about what the data means or how it should appear in reports. The file dictionary contains Attribute Definition items corresponding to each attribute in the data file item. st Look at the Attribute Definition item for the 1 attribute in a CUSTOMERS data file item. The item ID is FIRST-NAME. 2-16 A Guide to the UniVision System >CT DICT CUSTOMERS FIRST-NAME 001 002 003 004 005 006 007 008 009 010 FIRST-NAME A 1 First Name L 10 > A identifies the item as an Attribute Definition item. 1 references the position of the attribute in the data file item. First Name is a column heading used in reports. In addition, the entry defines that data should be left-justified (L), in a column ten characters wide. The VISION processor uses the dictionary to generate listings of data file items, as shown in the next section. A VISION report is a much more useful way of presenting data. Generating VISION Reports VISION is a query language processor put to many uses in the UniVision system. Its simple, English-like statements produce formatted reports for the printer or screen. In this section, several examples of VISION reports demonstrate the relationship between the dictionary and the data file. The UniVision Database Processors Guide explains VISION in full. LIST is a VISION verb that produces listings of items in a report format. The simplest statement consists of LIST followed by the name of a file. The following is a report from the CUSTOMERS file: User Accounts 2-17 >LIST CUSTOMERS FIRST-NAME LAST-NAME CITY STATE PAGE 1 12:05:42 CUSTOMERS... First Name Last Name. City........ State HJENK7127 JBOHA5422 JBROW6749 JBUCK6488 BLEAR6803 JMASO6378 AORLA5993 SPIRS5289 MASHX5777 AEDWA5224 JPEER5993 RPIER5539 AJOHN5396 HJOHN7265 HHIGG6849 DEDGE6635 AMEAD5619 BLAMP6196 INDIANAPOLIS BOSTON BOSTON LINCOLN BOSTON LINCOLN VENICE WINSTON INDIANAPOLIS SUDBURY LOS ALTOS RIDGEWOOD LOUISVILLE OMAHA OMAHA MIAMI SUDBURY BOSTON IN MA MA IN MA IN CA NC IN MA CA NJ KY NB NB FL MA MA HAROLD JOHN JAMES JULIE BILL JULIA AMY SANDRA MARY ANTHONY JAN RICK ANNE HENRY HENRY DAVID ANDREW BOB JENKINS BOHANNON BROWN BUCKLER LEARY MASON ORLANDO PIRS ASH EDWARDS PEERCE PIERCE JOHNSON JOHNSON HIGGINS EDGECOMB MEADE LAMPSON 02 AUG 1994 18 ITEMS LISTED The report lists information in five columns with a row for each data item in the st CUSTOMERS file. The 1 column lists item IDs. The remaining columns display the contents of several attributes. An Attribute Definition item in the dictionary describes each attribute telling VISION how to display the data. You use the item ID of an Attribute Definition item to refer to the data. For instance, the CUSTOMERS dictionary contains Attribute Definition items name FIRSTNAME, LAST-NAME, CITY, and STATE. You can specify the names of the attributes in a VISION statement to override the default display format. The following statement: >LIST CUSTOMERS LAST-NAME FIRST-NAME produces a report listing the item ID followed by the last name and first name of each customer. Listing the Contents of a Dictionary You can use LISTDICT to view a report that lists the Attribute Definition items in a dictionary. If you do not specify a filename, the system displays a report listing the Master Dictionary. Using this command to list the Master Dictionary produces a long report containing many pages. To break out of this report after viewing several pages and exit to UCL, press <CTRL-X>. 2-18 A Guide to the UniVision System The following command produces a listing of the dictionary for the CUSTOMERS file. > LISTDICT CUSTOMERS st The following screen shows the 1 page of the output. PAGE 1 12:20:15 02 AUG 1994 CUSTOMERS : FULLNAME CODE S A/AMC 0 S/NAME FULL NAME CORRELATIVES C;2,1 TP L MAX 20 CUSTOMERS : FIRST-NAME CODE A A/AMC 1 S/NAME First Name TP L MAX 10 CUSTOMERS : FNAME CODE A A/AMC 1 S/NAME First Name TP L MAX 10 In the file dictionary, FIRST-NAME and FNAME are the item IDs of Attribute st Definition items that refer to the 1 attribute in the data item. FULL-NAME is an entry that defines a correlative that concatenates data found in st nd the 1 and 2 attribute in reverse order. In other words, it derives its value by processing data. The following Section describes the format of Attribute Definition items as you create a simple database file. User Accounts 2-19 Section 3 CREATING A DATABASE A database is the foundation of a UniVision application. It provides a way to organise and use business data in a logical and efficient manner. Once a database exists, you can use VISION to generate reports that extract information for end users. Application developers can write custom programs in the BASIC language that provides the end-user with an integrated, task-oriented environment. Using menus, users can perform a variety of database management tasks, such as selecting reports, adding new items to the database, or updating existing items. It is possible to base an application on one or more files, each one containing a logical grouping of data. These files might be available in any or all accounts on the system. The term 'database' refers both to an individual file and to all of these files collectively associated with an application. This section describes the design and creation of a simple database comprising a single file. This process comprises the following steps: • Design the database. • Create one or more files. • Define entries in the file dictionary. • Create data. Designing a Database You can create a simple database such as one used to generate a personal phone directory without considering the size of the database or its structure. However, to set up a database for use in a business application a developer should follow the steps outlined in this section. It is essential that careful thought be given to database design. The design should accomplish three objectives: • To organise data generated by a business so that you can access and manipulate it easily. • To establish relationships among all the pieces of data. • To determine what information is useful for display in reports. Creating a Database 3-1 Before structuring the database, you should consider the following points: • Decide what output you must produce for reports. • Determine what data elements exist and their names and relationships. There is the flexibility to change the database after you have set it up. However, you should establish the structure of the database before creating it. The most important thing is to establish the sequence of attributes, values, and sub-values in a data file item. It is cumbersome and time-consuming to change these relationships once you have defined them. Use the following check-list to design a database: • Decide how many files you need and assign a unique name to each one. • Identify what set of data constitutes an item (record) in each file. • Identify one piece of data unique to each item and is it possible to use this as the item ID or key. • Assign a name unique and descriptive to each attribute. Determine if you require a more descriptive name for identification in reports. • Determine the maximum column width needed to display each attribute in a VISION report, and decide whether data should be left- or rightjustified in this column. It is possible to see that the dictionary’s Attribute Definition items reflect most of these decisions. The CUSTOMERS File This section examines another sample file, the CUSTOMERS file, containing the names and addresses of customers for a mail-order business. The previous Section describes reports generated from this file. The system stores the person’s first and last names, street address, city, state, and zipcode for each customer. In addition, the system stores the person’s phone number. Each of these pieces of data in an attribute of a data file item must be unique to the customer. Creating a File CREATE-FILE creates a file. Typically, you use it to create both the dictionary and the data file at the same time. CREATE-FILE requires you to specify the name of the file and physical disk space allocated for it. You specify the amount of space as the file's modulo and base it on an estimate of the size and expected growth of the database. 3-2 A Guide to the UniVision System Selecting a Filename A filename identifies the database file in the account. The following are a few rules to remember when assigning a filename: • You cannot use the following characters in a filename: a space, comma, semi-colon, and a single or double quote mark. • Parentheses, apostrophes, and quotes, while legal are not recommended. The name of a file should indicate something about the contents of the database. It must be unique in the account. In addition, you can use Q-pointers to create shorter synonyms for a file. For instance, a file named 'CUSTOMER.MASTER' might have a synonym name 'CM'. Selecting a Modulo Before creating a file it is necessary to estimate the amount of space needed for the file. The modulo specifies the number of groups allocated for a file. In choosing a modulo, estimate the average size of an item and the number of items in a file. If the average item size is less than 2000 bytes, you can use the following chart to estimate the modulo of a file. The right-hand column gives an estimate for a sample file. Round off calculations to the next largest integer. A. Average Size of Item 100 B. Number of Items 50 C. Multiply A and B 5000 D. Group Size (2000) 2000 E. Divide C By D 3 F. Choose prime number Modulo 3 The modulo of a file should be a prime number for an even distribution of items. It should never be a multiple of 2 or 5. CREATE-FILE ensures that the modulo entered is not a multiple of two, by adding one to get an odd-numbered modulo. For instance, if you enter a modulo of 2, CREATE-FILE specifies a modulo of 3. Some databases are static by design, that is, they contain a fixed amount of information that does not change often or increase significantly. Others are dynamic in that they increase in size over time. When estimating the size of a file, you should know whether to allow for the dynamic growth of the database. It is possible to calculate the amount of space available in each group for expansion. Use the following chart for this test. Creating a Database 3-3 G. H. I. J. Divide B by F Group Size 16 Multiple A by G Characters Used 1600 Subtract H from D Available Group Space 400 Divide I by A Number of New Items 4 Using the sample figures, this tells us that with a modulo of 3, the average number of items per group is 16 and that there is sufficient space for 4 more items per group. This is an indication that the file can expand by 12 items or approximately 20 per cent over the estimate before requiring additional storage space. However, this is only an estimate of actual usage; the hashing scheme does not guarantee even distribution across all groups. The Section entitled File Management gives additional information on creating and deleting file, and on monitoring the size and efficiency of files. Using CREATE-FILE To use CREATE-FILE, you must specify the following information on the command line: • the name of the file • the modulo of the dictionary • the modulo of the data file The name specified for the file must be unique in the account. In this example CREATE-FILE, creates a database file called PAYROLL. The modulo specified for the dictionary is 3 and for the data file is 43. >CREATE-FILE PAYROLL 3 43 [417] UniVision File 'PAYROLL' Created; Base = 6762; Modulo = 3 [417] UniVision File 'PAYROLL' Created; Base = 6765; Modulo = 43 CREATE-FILE allocates disk space for the PAYROLL file and creates D-pointers in two different dictionaries. It creates an entry for the PAYROLL dictionary in the Master Dictionary, and an entry for the PAYROLL data file in the PAYROLL dictionary. 3-4 A Guide to the UniVision System When you create a database as shown in the previous example, the dictionary and the data file are in a one-to-one relationship. The dictionary and the data file have the same name. When multiple data files share a dictionary, only one data file can have the same name as the dictionary. If an existing database has a single data file, you can use CREATE-FILE to create additional data files. For example: >CREATE-FILE DATA PAYROLL,PAYROLL.LASTYEAR 43 [417] UniVision File 'PAYROLL.LASTYEAR' Created; Base = 6873 Modulo = 43 The DATA modifier specifies that you only want to create the data file, the dictionary PAYROLL MUST exist already. When setting up a shared dictionary, you can create the dictionary before or at the st same time as the 1 data file. The following example creates the dictionary file 'INVOICES with a modulo of 3. >CREATE-FILE DICT INVOICES 3 [417] UniVision File 'INVOICES' Created; Base = 6648, Modulo = 3 Then you can create each data file. You must supply the name of the dictionary followed by a comma and the name of the date file. >CREATE-FILE DATA INVOICES,OCTOBER 3 [417] UniVision File 'OCTOBER' Created; Base = 6749, Modulo = 3 >CREATE-FILE DATA INVOICES,SEPTEMBER 3 [417] UniVision File 'SEPTEMBER' Created; Base = 6752, Modulo = 3 As a result of these commands, the INVOICES dictionary has two D-pointers to identify the data file: 'OCTOBER' and 'SEPTEMBER'. It is possible to set up additional data files at any time as needed. You could have combined the first two commands in the previous example to create the dictionary and one of the data files at the same time. >CREATE-FILE INVOICES,OCTOBER 3 3 [417] UniVision File 'INVOICES' Created; Base = 11898, Modulo = 3 [417] UniVision File 'OCTOBER' Created; Base = 11901, Modulo = 3 ! Note: There is no data file named 'INVOICES'; however, you could create it explicitly. Creating a Database 3-5 Creating Dictionary Entries A item in the dictionary has the following format: Item ID Name D/CODE A/AMC A/NAME A/AMC Definition Code Attribute Number Column Heading Structure 1 2 3 4 V/CONV V/CORR V/TYP V/MAX Not Used Not Used Conversion Code Correlative Code Type Column Width 5 6 7 8 9 10 Line Description Enter identifier Attribute Mark Count Report heading or tag Controlling and Dependent attributes Conversion specification Correlative specification Justification and wrap Width of display field You only require the Definition Code and attribute number. ! Note: Lines 5 and 6 are empty. The next section examines each specification. You can create dictionary items using the line editor (EDIT or ED) or the full screen editor (DOC-EDIT or DE). If you use the line editor to create entries, you cannot insert empty lines, in insert mode, by pressing <RETURN>. Pressing <RETURN> on an empty line exits insert mode; the screen editor uses <ESC> to exit insert mode and avoids this problem. There are two ways around it: one is to enter a single character on any line you want to be empty and later use R to find that character and replace it. Perhaps the best way is to use <CTRL-^> to insert attribute marks for each empty line. The following example demonstrates this method to create a dictionary entry named 'CUST-ID'. 3-6 A Guide to the UniVision System >ED DICT ORDERS CUSTOMERS-ID NEW ITEM .I 001+A 002+1 003+ Customer ID^^^^ 004+ML(#-####-####)^ 005+L 006+12 007<<RETURN>> .F TOP .P 001 A 002 1 003 Customer ID 004 005 006 007 ML(#-####-####) 008 009 L 010 12 .FI 'CUSTOMER-ID' FILED When the system updates and displays the editor buffer, the new listing shows that the system has interpreted the attribute marks as new lines. The subsequent sections look at each of the dictionary specifications in more detail. Naming the Attribute Definition Item Each entry in the dictionary requires a unique name. This name is the item ID of the Attribute Definition item. The name usually serves as a logical reference to the data contained in an attribute in the data file item. For instance, if the first attribute of an item contains a customer's first name, the name of the Attribute Definition item might be FIRST-NAME. Since you often use these names in VISION commands, you should ensure they are reasonably descriptive. Identifying the Entry (Line1) st A Definition code or D/CODE specified on the 1 line identifies each entry in a dictionary. A Creating a Database Attribute Definition item. It references the contents of an attribute in the data file. 3-7 S Synonym Definition item. Usually, you create Attribute synonyms to define default output specifications for VISION. I phrase definition. You can use phrases to store parts of a VISION command. X place holder that maintains the sequence of default output attributes but produces no output. In addition, you find D-pointers in the dictionary. You create them using CREATE-FILE and users should not modify them. Attribute Number (Line 2) The attribute number or A/AMC is an integer specifying the sequential position of an attribute in a data file item. For example, LAST-NAME has an attribute nd number of 2, identifying it as the 2 attribute in a CUSTOMERS data file item. Table 3-1 summarises the attribute numbers of the items in the CUSTOMERS dictionary. Attribute FIRST-NAME LAST-NAME STREET CITY STATE PHONE ZIP Attribute Number 1 2 3 4 5 6 7 Table 3-1: Attribute Positions in the CUSTOMERS File An attribute number of 0 (zero) refers to the item IDs in the data file. When creating synonyms, you can specify an AMC of 0, the AMC of a referenced attribute, or any number greater than the last attribute number specified. You can assign an arbitrarily high attribute number to any entry so that you can reference it in correlative expressions. An attribute number of '9998' or '9999' has special meaning. In a VISION report, an entry with an attribute number of 9998 displays a running count of items in the report; 9999 displays the size of each item in bytes. 3-8 A Guide to the UniVision System Column Heading (Line 3) This parameter defines the column heading or S/NAME that appears when you include the attribute in a VISION report. For example, the definition of the column heading for LAST-NAME in initial caps and does not include a hyphen: Last Name If you are not specifying a column heading, the system uses the item ID of the Attribute Definition item. In a columnar report, the column heading appears at the top of a column, identifying its contents. If you do not specify it, the system uses the name of the attribute. If you specify a backslash (\), the system does not output a heading. To specify a multi-line heading, use <CTRL-]> to indicate a line break. Associating Multi-Valued Attributes (Line 4) You use the structure specification (S/AMC) to define an association between multiple values of two or more attributes. When you create an association, each value in the Controlling attribute corresponds to a value in each of the Dependent attributes. You can print each set of related values as a single line in a VISION report. The C and D codes specify a Controlling or Dependent association, respectively. A C structure code links a Controlling attribute to one or more Dependent attributes. A D structure code links a Dependent attribute to a single Controlling attribute. The CUSTOMERS file does not have multi-valued attributes. Conversion (Line 7) A conversion is an expression applied to data just before the data appears in a report. For example, a conversion code could format dollar amounts to insert a decimal point and a dollar sign ($). This means that you do not have to store these characters with the amount. The following section describes correlatives. Correlative (Line 8) A correlative is an expression specifying arithmetic and other types of preprocessing performed on data before processing it in any other way. It derives its value by processing stored data. The previous section describes conversions. Creating a Database 3-9 Justification (Line 9) The justification specification (V/TYP) determines the alignment of columnar data in reports, as follows: L Left-justified (generally the case for alphabetic data). If data exceeds the length defined by the maximum column width, it wraps to the next line, beginning at the first character over the maximum length. R Right-justified (generally the case for numeric data). T Text left-justified. You use this type of justification for textual data. If data exceeds the length defined by the maximum column width, it wraps to the next line, starting at a blank space. In addition, justification affects the way in which the system shows sorted data. If left-justified, the system sorts data from left to right. If right-justified, the system sorts data numerically. For example, given the data '10', '9', and '90' the following sorting occurs: Right Justified Left -Justified 10 9 9 10 90 90 Column Width (Line 10) The Column Width specification (V/MAX) specifies the maximum width of the display field in characters. Data exceeding this specification wraps on the next line depending on V/TYP specification. ! Note: This is an output specification and does not affect the storage of data The column width specification is particularly important because the sum of the display width of specified attributes when compared with the line length of the screen or printer determines whether the system prints a report in columns or vertically. You can create synonyms to specify alternative display formats. For instance, an attribute containing a parts description might require a 40-character display field; this might be too wide to include with either information in a columnar report. You might define a synonym that differs from the Attribute Definition only in that it specifies a smaller display width. 3-10 A Guide to the UniVision System If the width of the column heading exceeds the column width specification, the display field is the width of the column heading. If the length of the column heading is less than the display field, the system pads the column heading with dots (.). Creating Data Items The CUSOMERS Dictionary Table 3-2 shows the contents o f th e Attribute Definition items in the CUSTOMERS dictionary. Item-ID FIRST-NAME LAST-NAME STREET CITY STATR PHONE D/CODE A A A A A A A/AMC 1 2 3 4 5 6 S/NAME First Name Last Name Street City State Phone V/CONV ML(######-#### ####) V/CORR V/TYP L L L L L R V/MAX 7 12 20 10 2 17 Table 3-2: CUSTOMER Attribute Definition Items The Attribute Definition items shown in Table 3-2 describe a data file item format consisting of six attributes. The attribute number (A/AMC) references the sequential location of attributes in the data file item. You have already seen the CUSTOMERS dictionary describing the format of items in the CUSTOMERS data file been seen. Examine the following item from the CUSTOMERS data file. AEDWA5224 001 ANTON 002 EDWARDS 003 51 BLAIR AVENUE 004 SUDBURY 005 MA 006 6178897764 223 The item ID of this item is AEDWA5224. The CUSTOMERS file uses an alphanumeric 9-character item ID constructed when you create the item. The system builds it from the first letter of the customer's first name, the first four letters of the last name, and an integer representing the date, as stored in internal format, when the system created the item. For example, the data item for a customer name Amy Orlando has the following item ID: Creating a Database 3-11 ORLA5993 5993 is the date in internal format; if you converted the date to a normal date format it would be 28 MAY 1984. The applications program constructs item IDs such as these when you add a new customer to the database. Each line in the data file item is a separate attribute. Attribute 1 contains the first name, defines by the Attribute Definition item FIRST-NAME in the CUSTOMERS dictionary. Attribute 2 contains the last name, defined by the Attribute Definition item LAST-NAME, and so on. Assigning Item IDs The item ID allows the system to locate the specific item of a customer. The item ID is a piece of data that must be unique for each customer in the file. For instance, a person's last name is not a unique identifier. For that reason, you often use sequential numeric item IDs to ensure that the ID is unique. Another benefit of numeric IDs is more even distribution of items across groups. However, there is nothing to prevent you from using alphanumeric keys. You should not base a key on information that is likely to change. When you have defined the structure of the database in the dictionary, you can create items in the data file. You can create a simple database containing a small amount of data using the Editor. The Editor, of course, does not supply prompts or validate input. You should take care to input the data in the correct order as defined in the dictionary. The following table lists the key sequences for entering system delimiter characters. Mark Input in Editor Attribute <RETURN> or <CTRL-^> Value <CTRL-]> Sub-Value <CTRL-\> You could write a Proc to automate data entry via the Editor, prompting for the data and submitting a series of Editor commands to create a new item and insert multiple lines. Most applications rely on custom UniVision BASIC programs for data entry. A typical data entry program prompts a user to supply data and verifies the input before adding a new item to the database. You might require a generalised data entry program that you could use to create items for any database. Such a program might use a phrase entry in the dictionary to identify the attributes that it prompts the user to enter. If you use sequential numeric IDs, you might use an entry in the dictionary to store the last ID number used. 3-12 A Guide to the UniVision System Extracting Information Before you create a database, you should note what information is useful to retrieve and in what context you want to present it. VISION gives developers the ability to design complex reports and forms, that the system can send to the user's screen, printer, or tape drive. For the most part, VISION allows the developer to forego writing programs to generate reports. Its English-like syntax makes it suitable for direct use even by end users. Users can query the database and display information in formatted reports on the screen or printer. The major component of a VISION query is an action-oriented verb, such as LIST, SORT, or COUNT. You can use VISION verbs to: • Display and print lists. • Sort items according to complex criteria. • Select items you want to include in a report. The various elements of VISION syntax can make for some long command lines. Fortunately, there are several ways to store and execute VISION commands. You can EXECUTE any VISION statement from a UniVision BASIC program or submitted from a Proc. ! Note: You cannot execute a VISION statement from within a B correlative. In addition, you can save a VISION statement from the UCL stack (.C) and store it as an item in the Master Dictionary or in any dictionary or data file. You can recall and execute this item at a later time (.R). The syntax for referring to a data file is: dictionary [,datafile] st nd The 1 parameter is the name of the dictionary. The 2 parameter specifies the name of the data file. The name of the dictionary and the data file can be the same, as they normally are when they exist in a one-to-one relation. If the dictionary points to a single data file, the name of the data file is the same as the name of the dictionary. When multiple data files are using a shared dictionary, you must specify which data file you want to access. To view the dictionary instead of the data file, you must use the DICT modifier. Creating a Database 3-13 Defining Default Output Specifications The preceding sections described how dictionaries define the structure of the data appearing in VISION reports. In addition, dictionaries affect the contents of these reports by defining default output specifications. These specifications determine the attributes displayed automatically when a VISION query does not specify the names of any Attribute Definition items. Unless you redefine the default explicitly, the default output for a file consists if item IDs only. Thus, entering the following query produces a list of the item IDs in the CUSTOMERS file: > LIST CUSTOMERS PAGE 1 10:33:54 01 NOV 1994 CUSTOMERS HJENK7129 JBOHA5422 JBROW6749 JBUCK6488 BLEAR6803 JMASO6378 AORLA5993 SPIRS5289 MASHX5777 AEDWA5224 JPEER5993 RPIER5539 AJOHN5369 HJOHN7265 HHIGG6849 DEDGE6635 AMEAD5619 BLAMP6196 18 Items Listed. > You can define the default output specifications for the CUSTOMERS data file by performing any of the following operations in the CUSTOMERS dictionary: • Defining an @ phrase • Creating a sequence of descriptors having consecutive numbers as their item IDs. A phrase is a dictionary item consisting of any parameters from a VISION query except a verb or a filename. 3-14 A Guide to the UniVision System If you implement all of these methods in the CUSTOMERS dictionary, the system treats them in the preceding order. In all cases, the default output specifications only take effect if a VISION query does not include the names of any Attribute Definition items. Creating an @ Phrase Creating a phrase in the CUSTOMERS dictionary whose item ID is @ defines the default output specifications for the report. You use these output specifications for reports sent to the screen, or printer. For example, you might define the following @ phrase in the CUSTOMERS dictionary: @ 001 I 002 FIRST-NAME LAST-NAME 003 CITY STATE Creating Dictionary Items in Numeric Sequence The dictionary contains a sequence of numeric item IDs in consecutive order beginning with 1, the system users these items to define the default output specifications. Each item in the sequence must contain an S code in Attribute 1. If an Attribute Definition item in a numeric sequence contains an X instead of an A in Attribute 1, the data is not part of the default output specifications. However, the system includes the data for items that follow this X item in the numeric sequence in the report. For example, you can create the same Attribute Definition items 1-4 in the CUSTOMERS dictionary, except that Attribute 1 of item 3 (CITY) contains an X. In this case, the default output specifications includes the data defined only by items 1, 2, and 4 (FIRST-NAME, LAST-NAME, and STATE). Example: Creating a Database Application This exercise asks you to create a simple database and uses several UniVision system tools to build and generate useful reports. A company has several hundred employees, each with a four-digit telephone extension number. Create a database that contains the names of employees and their telephone extension number. Assume that the extension number is unique for each person. (How might you create the database if the extension number was not unique? What if individuals had more than one extension?) Creating a Database 3-15 Once you have constructed the database, you can use VISION statements to extract information from the database. You need two different reports. One serves as a phone directory: a printed listing of employees sorted alphabetically by name and referencing the extension number. The switchboard operator generates the other report at a terminal; it displays the extension number for a particular employee. You need to be familiar with the VISION Reference Guide to nd accomplish this part of the exercise. In particular, to generate the 2 report, you should look at selection expressions that allow selection of items that appear in a report; as well as FIND. The next step is to automate the generation of both reports so that users can access st them. You can automate the 1 report by saving the VISION statement from the UCL stack and storing it as an item in the Master Dictionary. The Section entitles The UniVision Control Language describes .C used to save and store commands nd from the stack. The 2 report is slightly more difficult to automate because the user should be able to supply the name of the employee each time they run it. You can generate it using a Proc that prompts for an employee's name and builds the VISION statement. In addition, you can generate it from a UniVision BASIC program using EXECUTE. This exercise should help you become familiar with the application development facilities in the UniVision system. Especially important is understanding how well they work together to create a seamless database application for users. 3-16 A Guide to the UniVision System Section 4 DATABASE ARCHITECTURE A database defines logical relationships among individual elements of data. In one sense, a database is a set of containers for data. Imagine that a person puts something in a small box, and puts the small box in the top drawer of a bureau located in the bedroom of a house. You might direct another person to the small box, regardless of its contents, by having giving them the appropriate instructions. It is possible to describe the location of the small box as a series of pointers from one container to the next: House > Bedroom > Bureau > Top Drawer > Small Box This diagram depicts a chain of relationships. It is possible to follow the pointer to reference this without really knowing what it contains. For instance, 'everything in the top drawer' or 'everything in the bureau' indicates a set of things. The architecture of UniVision allows you to reference a piece of data by providing a set of files. A chain of logical relationships specifies the data contained in a particular attribute, regardless of what it actually holds. The physical structure of the item is the same for each file, but its logical structure or format depends on its use. The dictionary does more than just point to the location of data, it describes what the data is. It establishes symbolic references that are much more in keeping with the way people actually refer to things. For instance, a filename is a symbolic reference to a set of data stored on disk. A dictionary item contains both the physical and symbolic references to data in the data file item. UniVision File System The UniVision file system consists of four levels. At the top is the SYSTEM Dictionary. It contains pointers to multiple Master Dictionaries (MD or M/DICT) nd on the 2 level, each Master Dictionary represents an account on the system. The Master Dictionary of an account contains pointers to the account's file dictionaries rd th (3 level). A file dictionary can point to one or more data files on the 4 level. Figure 4-1 illustrates the UniVision file system. Database Architecture 4-1 SYSTEM DICTIONARY MASTER DICTIONARY MASTER DICTIONARY DICTIONARY DATA DICTIONARY DATA DATA System Level Master Dictionary Level File Dictionary Level Data File Level Figure 4-1. The organisation of the UniVision file system is on four levels Dictionaries represent the top three levels of the file system. A dictionary is a file containing any number of items or entries. These entries supply definitions for lower-level dictionaries and data level files. Dictionaries contain the following types of items: • Account Definition items. • File Definition items (D-pointers). • Verb Definition items. • Attribute Definition items. Account Definition items and File Definition items are both D-pointers; that is, st they both contain a D-code as the 1 line of the entry. In addition, there are Qpointers that reference D-pointers that exist as synonym definitions. Verb Definition items are available in each account, providing access to system programs. Attribute Definition items created in the file dictionary describe the structure of the data file. 4-2 A Guide to the UniVision System Only the SYSTEM Dictionary contains Account Definition items. Only the Master Dictionary contains Verb Definition items. All three types of dictionaries contain File Definition items. You can find Attribute Definition items in the file dictionaries as well as the Master Dictionary. SYSTEM Dictionary The SYSTEM Dictionary organises information about user accounts. It contains an Account Definition item for each user on the system. In addition, it contains File Definition items for various system files. The SYSTEM Dictionary is accessible from the SYSPROG account. A system administrator uses this account to maintain the UniVision system. To create a new account, the administrator invokes CREATE-ACCOUNT. It creates a Master Dictionary for the account and copies all the items from NEWAC, a prototype Master Dictionary, into it. In addition, it creates an Account Definition item in the SYSTEM Dictionary. You can create account synonyms to reference an Account Definition item. These items are Q-pointers pointing to the Account Definition item. In this way, an administrator can provide individual user IDs, as well as security privileges, to users of the same account. You should not update entries in the SYSTEM Dictionary while there are other users logged onto the system. When users log on to the system, the UniVision system establishes pointers to data in the SYSTEM Dictionary, and updating this dictionary can destroy these pointers. However, you can create a new account at any time. Creating new items does not affect existing pointers. In addition, the SYSTEM Dictionary contains pointers to a number of important system-level file. The Section entitled Account Management discusses systemlevel files. Master Dictionary Each account has one Master Dictionary containing the vocabulary for that account. Primarily, the Master Dictionary contains Verb Definition items, File Definition items, and keywords. At the time of its creation, the Master Dictionary is a copy of the NEWAC file defined in the SYSTEM Dictionary. File Dictionary Each data file must be associated with a file dictionary on the level above it. The file dictionary points to the data file and describes the structure of the data file. It is possible for more than one data file to share the same file dictionary. Database Architecture 4-3 Some file dictionaries do not have an associated data file. You refer to these files as single-level files and they might contain actual data. A single-level file points to itself. You can reference it as a file dictionary or as a data file. Data Files In UniVision a database file comprises two physical files: a dictionary describing the structure of the database and a data file containing the actual data stored on disk. In other words, the system keeps raw data in one place and stores the definition of that data separately in the dictionary. You can store a piece of data in a single location, unencumbered by its description. The dictionary contains this description, and it might contain multiple descriptions of the same piece of data. This arrangement provides a tremendous amount of flexibility in setting up a database, permitting different logical views of the same set of data. The system organises a data file as a collection of variable length items. It organises an item as a sequence of variable length attributes. A unique item ID identifies each item. For example, you assign items, in the ORDERS file, a sequential numeric item ID that appears on a printed form as the order number. It is possible for multiple data files with a similar structure to share a single dictionary. Dictionary Items The section describes the different types of items found in dictionaries. Account Definition Items You create Account Definition items using CREATE-ACCOUNT, and they appear only in the SYSTEM Dictionary. An Account Definition item is a D-pointer that references the location of the Master Dictionary for the account it defines. The Account Definition item supplies the account name and password, sets the privilege level for the account, and defines a number of options for the account. Item ID The item ID of an account Definition item is the name of the account. It serves as the user's logon ID or user ID. Attributes Account Definition items can have 13 attributes. The system reserves attribute 4 and 11, and therefore they are empty. 1. Definition Code. A D indicates a File Definition item. 2. Base 4-4 The base frame ID is a positive integer indicating the starting location of the file. CREATE-FILE assigns this value automatically. A Guide to the UniVision System 3. Modulo The modulo is a positive integer indicating the number of groups occupied by the Master Dictionary for the account. The user supplies it as a parameter during file creation. To change the modulo, edit attribute 13 to resize a file during a file save and restore 4. Reserved 5. Retrieval Codes An optional list of file-access locks associated with the account. The user defines the format of retrieval codes. If a user accesses a file containing a retrieval lock the system compares the code in Attribute 5 of the Account Definition item and Attribute 5 of the Account Definition item. If you have specified multiple values, it matches any single value. For more information, refer to the section entitled File Security in the Section entitled File Management 6. Update Codes An optional list of file-update locks associated with the account. The user defines the format of the update code. If the user attempts to modify a file containing an update lock, the system compares the code in Attribute 6 of the file Definition item and Account Definition item. If you specified multiple values, it matches any single value. UniVision BASIC OPEN fails if the lock codes do not match, as it assumes that if you can open a file, you might try to write to it. For more information, refer to the section entitled File Security in the Section entitled File Management. 7. Password The system stores a user password in encrypted format. When you create the account you establish the user password. If you do not define a password, Attribute 7 is null. To change a password, use PASSWORD. Database Architecture 4-5 8. Privilege Level A code indicating the system privilege for the account. If this attribute is null, the lowest privilege level, SYS0, applies. Each level includes the privileges on lower levels. SYS0 Level 0 is the lowest level of privilege. Users of accounts with SYS0 privileges can only run the application software. SYS1 Level 1 permits updating of the Master Dictionary of the account and the use of tape. SYS2 Level 2 permits use of the BASIC Debugger, DUMP, file-save and filerestore processors. SYS3 Level 3 id the highest privilege level. It provides unrestricted access to all files regardless of retrieval and update codes. 9. Account Options One or more codes that enable various options for the account. 4-6 B Disables <BREAK> for this account. O Automatically logs off user when a security violation occurs. The SECURITY-LOG file records security violations. R Enables the RESTART option, this causes the system to execute the Logon Proc when user exits the debugger using END. T Prevents the user from accessing UCL directly providing a Proc named account-name @ UCL exists in the user's master Dictionary or a Proc named @UCL exists in ERRMSG file. A Guide to the UniVision System U Specifies that you want to update the accounting History file, a file that maintains a log of user logon times and the number of pages sent to the printer, whenever the user logs off. 10. Width A positive integer indicating the maximum column width of the item ID column. Used by VISION processor. 11. Reserved 12. User Process Code A list of user process numbers permitted to log onto the account. A value mark separates individual process numbers with value marks. If null, all processes can log onto the account. You can use Process 0, associated with the system console, to log onto any account regardless of the list of user processes permitted. 13. Reallocation A positive integer specifying a new modulo for the Master Dictionary. You can enclose this value in parentheses. The reallocation of the Master Dictionary occurs during a file-restore. The system administrator should make updates to the Account Definition item only when there are no other users logged on to the system. The following example shows an Account Definition item: STAFF 001 D 002 6572 003 7 004 005 CD]CE 006 D]F]G 007 FqKs3IXsfm 008 SYS1 009 U 010 10 This item for the account named 'STAFF' specifies an encrypted password, file retrieval and update codes, SYS1 privileges, and the account option: the Accounting History file records the time of logon (U). Database Architecture 4-7 Account Synonym Items Account synonyms are Q-pointers to Account Definition items that allow you to set up individual user IDs for the same account. It is possible to create them using the Editor. Item- ID. An Account Synonym items that is a pointer to an Account Definition item. The item ID is another name for an account that already exists. Attributes Account Synonyms usually have 10 attributes. Only Attributes 1 and 2 differ from those in Account Definition items. 1. Definition Code A Q indicates a Synonym Definition item or Qpointer. 2. Account The name of the Account Definition item, that is a D-pointer in the SYSTEM Dictionary. The remaining attributes are the same as described for the Account Definition item, except that the system ignores the reallocation parameter (line 13). If the Account Synonym does not specify these attributes, the retrieval and update codes are the values specified in the Account Definition item. The system assumes the password is null and the privilege level is SYS0. The following example shows an Account Synonym item: JOHN 001 Q 002 STAFF 003 004 005 CD 006 D 007 U9Pau6RDo 008 SYS1 009 OU 010 10 This sets up the user ID, JOHN as a Q-pointer to the STAFF account. It establishes a password and SYS1 privileges, and specifies its own file retrieval and update codes. 4-8 A Guide to the UniVision System Verb Definition Items Verb definition items appear only in the Master Dictionary of the account. The system copies them into the Master Dictionary from the NEWAC file when creating the account. It is possible to modify each Master Dictionary such that all accounts cannot have the same set of Verb Definition items. A Verb Definition item allows a user to invoke a system processor. These items are the verbs or commands it is possible to execute at the UCL prompt. The Section entitled The UniVision Control Language describes the format of Verb Definition items. File Definition Items File Definition items are D-pointers that point to the location of a file. The file can be a single-level file, in which case it has no data-level file associated with it. This SYSTEM Dictionary and the Master Dictionary are two examples of single-level files. Most files, however, have two levels. In this case, the File Definition item points to a dictionary file which, in turn, contains a D-pointer to a data file. Dpointers occur in the SYSTEM Dictionary, the Master Dictionary, and file dictionaries. Use CREATE-FILE to create File Definition items. Item ID A File Definition item is a pointer to a dictionary or data file. The item ID is the actual name of the referenced dictionary or data file. If it points to a data file, the item ID is the same as the name of the file. Attributes File Definition items can have 13 attributes. The system reserves attributes 4, 11, and 12, and therefore they are empty. 1. Definition Code A D indicates a File Definition item. In addition, it is possible to use the following Definition Codes. Database Architecture DX Do not save the file during file-save; the file does not exist following a filerestore. DY Only save the file sizing parameters, not its data, during a file-save; the file is empty following a file-restore. 4-9 DC 2. Base Indicates that it is possible to use the file for UniVision BASIC programs. The dictionary usually contains items that are pointers to frames containing object code. You can specify 'DCX' and 'DCY'. The base frame ID is a positive integer indicating the starting location of the file. CREATE-FILE assigns this value automatically. Do not change this value. 3. Modulo The modulo is a positive integer indicating the number of groups occupied by the file. The user supplies it as a parameter during file creation. To change the modulo, edit Attribute 13 to resize a file during a file-save and restore. Do not change this modulo in Attribute 3. 4. Reserved 5. Retrieval Code An optional user-supplied security code used to restrict access to a file. When specified, its value must match any retrieval code in the account Definition item for the system to access the file. 6. Update Code An optional user-supplied security code used to prevent modification of a file. When specified its value mark must match any update code in the Account Definition item for the system to modify the file. 7. Conversion Code A conversion specification applied to the item ID. Used by the VISION processor. 8. Correlative Code A correlative specification applied to the item ID. Used by the VISION processor. 9. Justification A code specifying the justification of the item ID in a column. L indicates left-justification and R indicates right-justification. Used by the VISION processor. 4-10 A Guide to the UniVision System 10. Width A positive integer indicating the maximum column width of the item ID column. Used by VISION processor. 11. Reserved 12. Reserved 13. Reallocation A positive integer specifying a new file modulo. You can enclose this parameter in parentheses. Use this modulo to resize the file during a filerestore. The following example of a File Definition item shows the entry in the Master Dictionary for the ORDERS file. ORDERS 001 D 002 6850 003 7 004 005 006 007 008 009 L 010 10 011 012 013 (3) ! Note: The modulo of the file is currently 7. However this example specifies a reallocation parameter of 3 so that when the system saves and restores the file from tape, it reduces the number of groups. File Synonym Items A File Synonym item is a Q-pointer to a File Definition item. It is possible to create Q-pointers using the Editor. In addition, use SET-FILE to establish a temporary Q-pointer named 'QFILE'. ! Note: Database Architecture You cannot copy D-pointers using COPY; therefore, Qpointers are the only acceptable entries for the file synonyms. 4-11 Item ID. The item ID is the name you choose for a file already existing in the same account or in another account. Attributes. File Synonyms usually have 3 to 10 attributes. Only attributes 1, 2, and 3 differ from those in File Definition items. 1. Definition Code A Q indicates a Synonym Definition item or Qpointer. 2. Account. The name of the account containing the actual definition of the file. If not specified, the file definition is in the same account. 3. Filename The name of the reference file. It is the item ID of the actual File Definition item. If not specified, it refers to the target account's Master Dictionary. In addition, a File Synonym item can point to the Master Dictionary of another account. The remaining attributes are the same as described for the File Definition item. However, you cannot specify a reallocation parameter for a Q-pointer. The following example of a File Synonym item, BOOK-CAT, shows an entry for accessing the BOOK-CATALOG in the STAFF account. BOOK-CAT 001 Q 002 003 BOOK-CATALOG 004 005 006 007 008 009 L 010 10 Line 2 is empty because the example is defining the file synonym in the same account as the one that contains BOOK-CATALOG. To access the file from another account, line 2 would contain 'STAFF', the name of the account. Attribute Definition Items Attribute Definition items define the format of items in the data file. It is possible to create these items using the Editor. The Section entitled Creating a Database, described the creation of Attribute Definition items in the process of building a dictionary. 4-12 A Guide to the UniVision System Item ID. A logical name used to reference the contents of the attribute in VISION statements. Attributes. Attribute Definition item can have 10 attributes. The system reserves Attributes 5 and 6, and therefore they are empty. 1. Definition Code. Any one of these Definition Codes specify an Attribute Definition item. A An Attribute Definition item referencing the contents of an attribute in the data file. S An Attribute Synonym. Same as 'A' for all practical purposes. LISTDICT sorts S after A codes. Usually the system creates attribute synonyms as a numerical sequence of item IDs to define the default output specifications for VISION reports. I A VISION phrase follows in line 2. X A place-holder item skipped when maintaining sequence of numeric item IDs to specify the default output specification for VISION reports. The system does not display the attribute reference by an X item/ 2. Attribute Number. An integer identifying the attribute by its sequential location, also called the Attribute mark Count (AMC). An attribute number of 0 references the item ID. A 0 or any number greater than the number of attributes that exist in the file references data derived or computed rather than actually stored on disk. In addition, if line 1 defines a phrase, the actual phrase interpreted by VISION starts on line 2. Database Architecture 4-13 3. Tag An optional name used in place of the item ID as a column heading in VISION reports. The backslash (\) is a symbol, reserved by the system, causing no tag to be output. You can use value marks (CTRL-]) to indicate a line break, making it possible to place a column heading on multiple lines. If the heading is shorter than the column width, the system pads it with dots(…). 4. Structure. An optional code defining an associative structure for two or more multi-valued attributes. A structure code of 'C' indicates a Controlling attribute; a structure code of 'D' indicates a Dependent attribute. You can only list Dependent attributes in a VISION report when the Controlling attribute appear in the output specification. 5. Reserved. 6. Reserved. 7. Conversion Code. A conversion specification applied to the contents of the attribute. Used by VISION processor. 8. Correlative Code. A correlative specification applied to the contents of the attribute. Used by the VISION processor. 9. Justification. A code specifying the justification of the output field in a column. In addition it affects the sorting of data. 4-14 L Left-justified, generally the case for alphabetic data. If data exceeds the length defined by the maximum column width, it wraps to the next line, beginning at the first character over the maximum length. R Right-justified, generally the case for numeric data. A Guide to the UniVision System T Left-justified. Type of justification used for textual data that might include embedded blank spaces. If data exceeds the length defined as the maximum column width, it wraps to the next line, starting at a blank space. Used by the VISION processor. 10. Width A positive integer indicating the maximum column width of the column. Used by VISION processor. The following example shows an Attribute Definition item taken from the CUSTOMERS file: PHONE 001 A 002 6 003 Phone 004 005 006 007 ML(###-###-#### ####) 008 009 R 010 17 th This item defines the 6 attribute in a data item. It supplies a column heading and a conversion code that presents this numeric data in a conventional format. If you store the following piece of data in Attribute 6 of an item in the data file. 5168769091 and apply a conversion code (line 7) on output, the data has the format of a phone number: 516-876-9091 The CUSTOMERS Dictionary Table 4-1 shows the contents of some of the Attribute Definition items in the ORDERS dictionary. Database Architecture 4-15 Item ID CUST.ID DATE PRODUCT QTY PAYMENT D/CODE A/AMC S/NAME S/AMC V/CONV V/CORR V/TYPE V/MAX A 1 Customer ID A 2 Date of Order A 3 Product C:4 A 4 Quantity D;3 A 5 Payment L 5 R 3 L 10 D2/ L 10 L 10 Table 4-1. ORDERS Attribute Definition Items This table describes a data file item format of five attributes. The attribute number (A/AMC) references the sequential location of attributes in the data file item. The codes stored in S/AMC and V/CONV require some further explanation, covered in later sections. The Structure of Items In conventional database terminology, records and files are equivalent to items and attributes. However, the terms, records and fields do not convey the structure of item in the UniVision system fully. Each item is a variable-length string of characters. The presence of delimiters, special characters that indicate structural elements define the structure of this item. Table 4-2 shows the UniVision system delimiters. An item is a sequence of variable-length attributes. An attribute corresponds to a line when you list the item vertically (such as in Editor). Attributes can contain any number of values. If an attribute contains more than one value the system considers it to be multi-valued. values, and in turn, you can divide it further into any number of sub-values. Representation ASCII Value Attribute ^ 254 Value ] 253 Sub-Value \ 252 Mark Table 4-2. UniVision System Delimiters Using these structures, you could structure a database file such that each item was the equivalent of a collection of records and each attribute was the equivalent of a collection of fields. The value mark delimits the contents of each field within the attribute and the sub-value mark delimits multiple entries in a single field. 4-16 A Guide to the UniVision System Multi-valued Attributes To understand the usage of multi-valued attributes, look at the structure of an ORDERS database created to capture the data on the sample form in Figure 4-2 Purchase Order 03128 No. To. John Swenson 14 Crosswoods Place Fremont, NV Product X47-180 X47-191 X25-340 Quantity 2 2 1 Date: 16/4/89 Ship Via: U.P.S. Payment: Cash Amount 25.00 32.00 21.00 78.00 Original Figure 4-2. A sample order form You can use multi-valued attributes to describe 'line items' on an order form. The shaded area in Figure 4-2 holds the line items on the printed form. A line item represents information about the purchase of a particular product. The customer might place orders for several different products in different quantities with each having a different price. The rest of the data fields on this form contain only a single piece of data, such as the customer's name and address, a credit card number or the amount of the order. Each order has an order number, outlined in the top right hand corner of the form. This number serves as the item ID to identify each order in the database file. Each item in the data file has the following sequence of attributes: Database Architecture 4-17 CUSTOMER-ID DATE PRODUCT QTY PAYMENT SHIP 1 2 3 4 5 6 There are six attributes. Notice that not all data fields on the form are in use. For instance, there is no AMOUNT or TOTAL-AMOUNT attribute. That is because it is possible to derive this information from data that already exists in the file. The actual data file item storing the data from the order form would look like this: JSEWN14CRO^7414^X47-180]X46191]Y25340^2]2]1^CASH^UPS A caret (^) represents an attribute mark. PRODUCT and QTY are multi-valued attributes; that is, each attribute has several pieces of data separated by value marks. A right bracket (]) represents a value mark. In the above example, each multi-valued attribute has three values. You associate any group of multi-valued attributes as a unit so that VISION st reports display related values together. In other words, the 1 value in PRODUCT corresponds to the first value in QTY. Figure 4-3 illustrates this concept. Remember that a multi-valued attribute is a structure defined by specific delimiters in the data file item. The attribute definition in the dictionary does not describe it. Therefore, it is possible to create an attribute for which some items might have multiple values while others do not. For example, if a person supplied two home phone numbers, you could place both numbers in the data file item, separated by value marks. 4-18 A Guide to the UniVision System 10139 CUSTOMER-ID JSWEN5390 DATE PRODUCT 16/4/89 QUANTITY X47-180 X47-191 X25-340 2 2 1 PAGE1 PAYMENT SHIP CASH U.P.S 12:47:19 24 MAY 1989 ORDERS CUSTOMER ID DATE PRODUCT QTY PAYMENT SHIP 10139 JSWEN5390 16/4/89 X47-180 X47-191 X25-340 2 2 CASH UPS END OF LIST > Figure 4-3. Multi-valued attributes create another level of structure within an item. It is possible to associate these attributes so that reports display corresponding values together in reports. The ORDERS Dictionary The ORDERS file implements multi-valued attributes to describe the data in a single order transaction. When a customer places an order, the system stores the data in an item in the ORDERS file. A unique product code identifies each book. For example, when displayed by LIST-ITEM, item 10118 in the ORDERS file, has the following structure: > LIST-ITEM ORDERS '10118' 001 002 003 004 005 006 10118 DROBI5424 7563 N01]QR02]N04 3]2]1 CASH UPS Database Architecture 4-19 Attribute 3 contains the code numbers of the ordered books and Attribute 4 contains the number of books ordered. Attributes 1, 2, 5, and 6 each have only a single value. The system derives the rest of the data describing an order transaction, such as PRICE, TITLE, AMOUNT, and TAX, from existing data. Value marks, entered in the file with <CTRL-]> separate the pieces of data in each multi-valued attribute. The interpretation of data in item 10118 is as follows: • 3 copies of book N01 • 2 copies of book QR02 • 1 copy of book N04 Controlling and Dependent Specifications You can define the relationship that multi-valued attributes have to one another further using a Controlling attribute and one or more related Dependent attributes. Controlling and Dependent attributes identify a unit of related data. You cannot display a Dependent attribute in a report unless you include the related Controlling attribute as well. This is because the data in Dependent attributes might otherwise have no meaning. For example, it would make little sense to display the number of books ordered unless you identify the books themselves in the report. Line 4 of an Attribute Definition item determines whether an attribute is Controlling, Dependent, or neither. For example, the Attribute Definition item for PRODUCT in the ORDERS dictionary defines this attribute as Controlling and links it to Dependent Attribute 4 (QTY): >LIST-ITEM DICT ORDERS 'PRODUCT' 001 002 003 004 005 006 007 008 009 010 PRODUCT A 3 PRODUCT C:4 L 5 The Attribute Definition item for QTY defined this attribute as dependent and links it to Controlling Attribute 3 (PRODUCT): 4-20 A Guide to the UniVision System QTY 001 002 003 004 005 006 007 008 009 010 A 4 QUANTITY D;3 R 3 Correlatives and Conversions A database provides for the storage and retrieval of data. The reason for creating a database, however, is so that you can process the data easily for reports. If you store data from a series of customer orders on the computer, you would expect to do more than simply retrieve that data. You might accumulate totals so that you could report the number of units sold or the dollar amount in sales per day, per week, per month and so on. A database provides a way to transform data into information. Correlatives and conversions provide a great deal of flexibility in creating VISION reports. You can define conversions to convert raw data into a particular format. You can define correlatives that permit you to access and process data in existing attributes or other database files. Normally you store conversions in Attribute 7 and correlative in Attribute 8 of an Attribute Definition item. Refer to the Section entitled Correlatives and Conversions in the VISION Reference Guide for the full description of the usage of correlative and conversion codes. Stored Format and Output Format Correlatives and conversions add flexibility to the way you store and handle data. Conversions translate data from a raw or stored format to output format, for example, you could translate a phone number consisting of a string of fourteen numeric characters as follows: Stored Format Output Format 61724577853397 617-245-7785 3397 It is more efficient to store the data without the hyphens or blank spaces. In addition, it makes it easier to achieve a consistent output format. For instance, to put the area code in parentheses, you need change only the conversion code in the dictionary, not the data itself. Correlative codes often manipulate the data in one attribute by extracting, concatenating, or substituting data from other attributes. For example, you can construct a customer's full name by concatenating the last name and the first name from the CUSTOMERS file as follows: Database Architecture 4-21 Code First Name Last Name Full Name C;2 1 JULIE BUCKLER BUCKLER JULIE The correlative code 'C;2 1' specifies that you form a customer's full name by concatenating Attribute 2 and Attribute 1 and use a blank space as a separator. Similarly, if you store a person's name as a full name, you could use a correlative to extract the person's first or last name. Formatting Dollar Amounts Using conversions to format dollar amounts is a typical example. The Attribute Definition item for AMOUNT (amount of sale) in the ORDERS dictionary contains a conversion to produce a formatted dollar amount: >LIST-ITEM DICT ORDERS 'AMOUNT 001 002 003 004 005 006 007 008 009 010 AMOUNT A 0 AMOUNT MR2$ A;N(QTY)*N(PRICE) R 10 The conversion MR2$ specifies the format of the dollar amount. The M specifies that you want to convert numeric data. The following specifies the format of the amount: • Right-justification of the amount (R). • Two digits follow the decimal point (2). • A dollar sign precedes the amount ($). Assume that you stored the amount of sale for an item in the ORDERS file as '1100'. The conversion operates on this data element an produces the result: $11.00. If a VISION report included the AMOUNT attribute, the conversion code would ensure that all of the dollar amounts were right-justified and, therefore, properly lined-up 4-22 A Guide to the UniVision System ! Note: The system actually derives the amount of sale by a correlative that multiples the attribute QTY by the attribute PRICE. You can find a description of this correlative in the section entitled Manipulating Existing Data. Formatting Dates and Times You can use conversion codes to specify formatting for dates and times. Normally the system stores dates and times in internal format, an integer value that is much easier for processing and storage. In order to output this type of numeric data, you must convert it into a specified format. The following shows two examples from the ORDERS file: Item ID DATE TIME D/CODE A/AMC S/NAME S/AMC V/CONV V/CORR V/TYP V/MAX A 2 Date of Order A 7 Time of Order D2/ MTHS L 10 L 10 Table 4-3. Date and Time Conversion You format dates using two digits for the year and a slash character (/) as a delimiter. For example: 04/04/88 You format times using the 12-hour format with AM or PM appended, and include seconds. For example: 09:13:56 AM For alternative formats, refer to the Section entitled Correlatives and Conversion in the VISION Reference Guide. Manipulating Existing Data The BOOK-CATALOG file describes the inventory for the mail-order publishing business. Table 4-4 shows the contents of three of the Attribute Definition items in the BOOK-CATALOG dictionary. Database Architecture 4-23 Item ID AUTHOR TITLE PRICE AMOUNT D/CODE A/AMC S/NAME V/CONV V/CORR V/TYPE V/MAX A 1 Author A 2 Title A 3 Price MR2$ L 20 T 20 R 8 A 0 Amount MR2$ A;N(QTY)*N(PRICE) R 10 Table 4-4. BOOK-CATALOG Attribute Definition Items The preceding Attribute Definition items describe the structure of a BOOKCATALOG data file item. For example, the data item for the book whose code is N01 contains the following information: >LIST-ITEM BOOK-CATALOG 'N01' N01 001 STRANG 002 OPERATING SYSTEM CONCEPTS 003 2000 The data stored in the BOOK-CATALOG file is relatively stable (the prices of the books might change, but the book titles and authors remain the same). It makes sense, therefore, to maintain inventory information in this file and to reference (not duplicate) it in the ORDERS file. The dictionary entry for 'AMOUNT' contains a correlative used to derive its value by manipulating other values in the database. The correlative A;N(QTY)*N(PRICE) multiples the data in two other numeric attributes in the ORDERS file to derive the data for AMOUNT. Specifically, this correlative multiplies QTY by PRICE. Use the A code to specify the processing. The N function identifies the attribute by name. In addition, it is possible to reference attributes by AMC. For example, A;2*3 multiples the value of Attribute 2 by the value of Attribute 3. The expression A;2*"3" multiples the value of Attribute 2 by the number 3. In other words, you determine the amount of sale automatically by multiplying the number of books ordered by the price of a single book. 4-24 A Guide to the UniVision System Translating Data from Another File The Tfile (file translation) code eliminates the need for duplicating data in related files by retrieving data from one file for use in another file. To access the remote file, you must create the dictionary entry containing the Tfile correlative with the AMC specifying the attribute of the source item that provides the item IDs for items in the target file. Assume that a user wants to be able to generate reports from the ORDERS file that include book titles and prices. The BOOK-CATALOG file contains this information in Attributes 2 and 3 respectively. The item IDs in BOOKCATALOG are unique character strings (PRODUCT) that identify each book. In addition, the ORDERS file uses the PRODUCT attribute, but as Attribute 1. Since you can use PRODUCT to link data in the ORDERS and BOOKCATALOG files, this is the only piece of data required in the ORDERS file to identify a book uniquely. Table 4-5 shows the Attribute Definition items for TITLE and PRICE in the ORDERS file: Item ID TITLE PRICE D/CODE A/AMC S.NAME V/CONV V/CORR V/TYP V/MAX S 1 S 1 TBOOK-CATALOG;X;;2 T 40 TBOOK-CATALOG;X;;3 R 8 Table 4-5. ORDERS File Attribute Definition Items The Tfile correlative for TITLE specifies that you want to retrieve the data from Attribute 2 of the BOOK-CATALOG file. The Tfile correlative for PRICE specifies Attribute 3 of the BOOK-CATALOG file. the X sub-code shown for both TITLE and PRICE causes the system to return a null value if for any reason it cannot return the data. With the preceding Tfile correlatives in place, there is no need to duplicate lengthy titles in each order item. In addition, you could change the price of any book in the BOOK-CATALOG file, and generate reports from the ORDERS files would reflect the new data automatically. Database Architecture 4-25 Section 5 UNIVISION DATABASE MANAGEMENT SYSTEM The UniVision environment is a powerful, multi-user database management system (DBMS) designed to run the extensive library of applications available for the Pick data model. UniVision is an efficient and high-performance DBMS, implemented using state-of-the-art object-oriented programming techniques. UniVision is designed for the open systems environment, and is written in the C++ programming language. This section describes the fundamental structure of UniVision and covers the following main areas: • File access methods • Peripheral device management. Physical Mapping of the Disk UniVision organises the hard disk into the following areas: • File Area • Available Space Area. The following is an example of the report generated on UniVision by WHAT. 13:19:20 CORE LINES 65152 254 24 AUG 1993 MAXUSERS [254} CURRENT # USERS [21] PROCESSES PCB0 WSSTART WSSIZE SYSBASE/MODULO MAXFID OVRFLW 2500 0400 N/A N/A 1 3 756135 119612 Overflow Area The overflow area is just available disk space. It consists of a pool of frames that the system can allocate dynamically to create files, or that various system processors can use as additional data space by various system processors. For instance, when a group needs an additional frame for storage of items, the system takes this frame from the overflow area. UniVision Database Management System 5-1 The heading OVRFLW in the WHAT report lists the number of frames in the overflow area. In the sample report, there are 119612 available frames. At the end of the overflow area is the maximum frame ID, that appears under the MAXFID heading in the WHAT report. How You Use the Overflow Table On a new system, and following a file-restore, the overflow area consists of a single block of contiguous frames. Contiguous space consists of adjacent frames allocated as one or more blocks. As the system returns frames to the overflow area, this area becomes more fragmented, consisting of multiple blocks of contiguous frames. The system keeps track of these sets of blocks in the Overflow Table. This table contains a pointer to the beginning and end of each block. The UniVision system uses the Overflow Table to handle requests for additional frames. If it requests a block, the system assigns frames from the first contiguous block of space that is equal to or greater than the amount requested. Frame Formats Data frames have a specified format that places linking information at the start of the frame. The frame size is 2048 bytes, data comprises 2000 bytes with the remaining 48 bytes reserved for linking information. Sometimes you refer to data frames as linked frames, because they contain the link information. UniVision can combine blocks of frames to create a file. You can display the contents of disk frames using DUMP. DUMP displays the contents of disk frames, including information about forward and backward links, and has the following syntax: DUMP frame-ID1[frame-ID2] [options] frame-ID1 number of the frame you want to display. frame-ID1-frame-ID2 specifies a range of frames options 5-2 can be any of the following: B Display frame branching details. G Group option. Displays all forward-linked frames, attached to the specified frame. Used with U, G displays all backward-linked frames in the group. L Link option. Only displays information; does not display date. N Suppresses automatically paging. frame link A Guide to the UniVision System P Sends output to the printer. U Traces data or links logically forward using backward links instead of the default forward links. X Displays data in hexadecimal format rather than ASCII. The following is an example of the output from DUMP. forward link backward link FID FID : 0 50 100 150 200 250 300 350 400 450 500 550 600 650 700 750 800 850 900 950 1000 hexadecimal equivalent 9530 : 9531 9246 (253A : 253B 241E) :....____;%...$..............................0...T : :3 THEN^ database<<15>>=''^ END^ GOSUB reb : :uild.contacts^ CRT @(30,33):database<<14>>:@(-4):^ : : IF database<<33>> NE ' ' THEN^ GOSUB contrac : :t.update^ END^ GOSUB validate.normal^ GOS : :UB rebuild.contacts^ IF old.database NE databas : :e THEN IF debug=true THEN^ MAT fld.n : :ew=''^ MAT fld.old=''^ CRT @(0,4): : :@(-3):^ do.debug=false^ FOR x = 1 : :TO 10^ fld.new(x)=database<<field<<1,x>>>>^ : : fld.old(x)=old.database<<field<<1,x>>>>^ : : IF fld.new(x) NE fld.old(x) THEN^ : : CRT 'Field ':fields<<1,x>>"L#2":' differs'^ : : CRT ' Old ':fld.old(x)^ CRT : :' New ':fld.new(x)^ do.debug=true^ : : END^ NEXT x^ CRT 'Att diff : :er:':^ FOR x = 1 TO DCOUNT (old.database,am : :)^ IF old.database<x> NE database<x> THE : :N^ CRT ' '':x:^ END^ : :NEXT x^ CRT^ CRT 'Old record ':DCO : :UNT(old,database,am);' / New record ':DCOUN(datab : For more detail regarding DUMP refer to the UniVision Command Reference Manual. UniVision Database Management System 5-3 Physical Item Structure An item is a variable-length string containing delimiters or special characters indicating its structure. Each item begins with a null character and a four-character binary count field specifying the number of characters that make up the item. An item-ID follows the count field. An item contains any number of attributes, delimited by attribute marks (ASCII 254) printed as a caret (^). Attributes can contain any number of values, delimited by value marks (ASCII 253) printed as a right bracket (]). A value can contain any number of sub-values, delimited by subvalue marks (ASCII 252) printed as a backslash (\). At the end of the item there is a segment mark (ASCII 255) printed as an underscore (_). Two consecutive segment marks indicate the end of the item and the end of the group. The output from DUMP, shown above shows only the first page of a two page report. The system displays the data in lines of 50 bytes each. You can see that the data begins with the item count (in hexadecimal) of the first item followed by its item ID. It is possible to find attribute mark (^), value marks (]) and the segment mark (_) that indicates the end of an item. The DUMP report actually shows over 900 bytes of data in the above frame; however almost half the frame contains characters left over from previous use. This is referred to as 'Lint'. Returning a frame to the overflow area and allocating it again does not erase data in the frame; new data overwrites the old data. The end-of-group mark indicates the end of useful data to the system. To indicate that the frame does not contain any useful data (that is, that it is empty), commands like CREATE-FILE place a segment mark as the first byte of data following the linking information. File Access The file structure allows a user to run UniVision application code that has less than the optimal file allocation without impacting performance severely. Close attention to file sizing and weekly or monthly file restoring is not essential with UniVision. UniVision reduces the need for periodic file resizing dramatically, thus minimising downtime. When you create a file on UniVision, it establishes the primary file space. It sets aside one two thousand (2 Kbyte) page for each group specified by the modulo in the create file process. UniVision establishes the primary pages for a file and, in the case of badly fragmented free disk space, these do not have to be contiguous. Each group can contain an unlimited number of pages of disk space. Each page can contain up to two thousand bytes of data. As a page of disk space fills with data items, the system adds additional pages. Conversely, as the system removes or deletes items, it returns pages to the available space table for re-use. 5-4 A Guide to the UniVision System Each group contains a number of items. A unique item identifier or key determines the items in the group. The system applies each key to the UniVision hashing algorithm in an attempt to distribute items evenly across all groups. As you add items to a file, each group can contain a large number of items. To prevent long sequential searching for data within a group. UniVision continues to add data to a group until the group contains one hundred and fifty items. Once a group expands beyond one hundred and fifty items, the system assigns a subgroup to a group. A sub-group contains five groups. Each sub-group can grow to one hundred and fifty items, then the sub-group can again split into a sub-sub-group. The splitting can continue for a long as required. In the following example, group two contains five pages and over one hundred and fifty items. The group attaches an additional five sub groups, in which subgroup three expanded to over one hundred and fifty items. The system attaches a sub-group to sub-group three of the original group two. The process of creating sub-groups continues as many times as required to save all the items in the group. This file structure allows for a poorly allocated file. However, UniVision compensates for this by dividing the groups for improved item retrieval performance. UniVision Database Management System 5-5 Customer File Group 1 Group 2 Sub-Group Sub-Group Group 3 Figure 5-1. File Structure of UniVision Retrieving Items It is possible to appreciate the efficiency of the UniVision file access method when compared with a purely sequential search of a file. A sequential access method locates an item within the file by reading all characters from the beginning of the file until it locates the item ID or reaches the end of the file. As a consequence, you retrieve items located at the beginning of the file much faster than those at the end. In addition, performance suffers as files get larger. A sequential access method is analogous to searching an alphabetical list beginning with the A's and proceeding to search the B's and so on. If you wanted to make a search on a list of names, it would locate names beginning with letters towards the start of the alphabet faster than other names. A random-access method of storing and retrieving items limits the search to a portion of the file. 5-6 A Guide to the UniVision System Each item falls into a particular group based on its item ID. Once the system locates that group, in conducts a sequential search of items in that group, comparing item IDs. Each item's count field contains the size of the item, used to locate the next item in the group. Instead of reading each character to look for the segment mark indicating the end of an item, the system is able to jump ahead by a specified number of bytes to locate the beginning of the next item. If the system encounters a segment mark instead of a count field, this indicates the end of the group. An empty group has a segment mark in the first data position. UniVision's file access method, using the item ID to locate the group and find the item within the group, is an efficient way to locate data. The system overhead required to access an item is essentially independent of the actual size of the file. Processes and Lines A line refers to a serial communications port and the control structure that manages the data as you send and receive it across the line. A cable running from a serial device, such as a terminal, connects that device to one of the system's communication ports. The system number lines sequentially, starting with line 0, usually the system console. Terminals, printers and modems connect to additional lines, usually beginning with line 1. The system configuration is the basis for the number of lines that are available on UniVision. A user process, is a workspace that records the current state of processing tasks for a particular user. It keeps track of the location of the user's Master Dictionary, the location of a file being accessed, whether a printer or tape drive is in use, and what system processor is executing. Each process is essentially independent of the other processes on the system. Almost all the software processors within UniVision have the capability to accept input from a single line and send all output back to the same line. On most Pick systems, lines and processes are not interchangeable because they always remain linked. However, on UniVision it is possible to unlink a line from a process, providing additional communications capabilities. You called a line not linked to a process an available line, and sometimes call the unlinked process a phantom process. You can link and unlink lines dynamically, and can attach a process to an unlinked line. The commands listed in the following table are available to link or unlink lines, and attach or detach lines. Refer to the Section entitled Data Communications to see how to use them to connect a modem to the system. UniVision Database Management System 5-7 Command Description LINK-LINE Creates a link between an available line and a process. Only available from accounts with SYS3 privilege. UNLINK-LINE Breaks the link between a line and a process, creating an available line and a phantom process. Only available from accounts with SYS3 privilege. LINE-ATT Attaches a line to a process, providing exclusive use of that line. LINE-DET Detaches an attached line from a process. LINE-PROTOCOL Displays line characteristics for specified lines. LINE STATUS Displays the status of a specified line of range of lines. LISTDEV Lists the UniVision Line to UNIX Device Relationship. LISTPRO Lists the UniVision Process to UNIX Device Relationship. CONVERSE 'Connects' an attached line and a linked line. PROCESS-STATUS Displays the status of a specified process or a range of processes. ACQUIRE-LINE Acquires a UNIX line for subsequent use by UniVision. RELEASE-LINE Releases an acquired line back to UNIX. LIST-ACQUIRED-LINE Lists UNIX lines acquired for UniVision use. Table 5-1. Line Commands A line can only link to one process. A process can only link to one line at a time, but it can attach to however many lines are available. Attaching a line to a process gives the process exclusive control over the line. The process can take input from or send input to the attached line by using commands that specify the attached line by number. Typically you do this using GET and SEND in BASIC. By default, all input and output for a process uses the linked line. You cannot direct input from a line to any other process. However, other processes can send output to a linked line. If you require to prevent output being sent to the line, attach a line, thereby gaining exclusive control of the input and output for a process. The line is said to be 'linked and attached'. 5-8 A Guide to the UniVision System A line can have one of the following statuses: AVAILABLE An available line is neither linked nor attached to any process. You can send output to an available line from another process. LINKED A process uses its linked line for all default input and output. It is only possible to link a line to one process at a time. No other process can receive input from a linked line. However, it is possible for another process to send output to a linked line. ATTACHED A process uses its attached line for any specified input and output. You must specify the attached line by line number. It is only possible to attach a line to one process at a time. The process has exclusive control over the line. No other process can receive input from or send output to an attached line. LINKED and ATTACHED The system uses a line linked and attached to a process for all default input and output. The process has exclusive control over the line. No other process can receive input from or send output to the line. ACQUIRED The system has acquired the line from UNIX for subsequent use by UniVision. UniVision Database Management System 5-9 Line 0 Process 0 Line0 is linked to Process 0 Process 1 Line 1 Process 2 Line 2 Process 3 Process 3 is a phantom Process not linked to a line Line 3 Line 3 is attached to Process 4 Line 4 Process 4 Line 4 is linked to Process 4 Line 5 Process 5 Line 5 is linked to Process 6 Line 6 Process 6 Line 6 became an available line when it was unlinked from Process 6 Figure 5-2 Lines link to processes. In addition, lines can attach to a process. An unlinked process is a phantom process and an unlinked line is an available line. LIST-LINE-CHARS, or its synonym LLC, produces a report where the heading LINE contains a listing of the characteristics of each line. The heading PROCESS, contains an L for a linked process, an A for an attached process, an LA for a linked and attached process and an a for an acquired process. Phantom processes do not have an entry in this column. The previous figure shows a set of seven lines and seven processes for a system. There is a link between process 0 and line 0, process 1 and line 1, and process 2 and line 2. Normally, the system establishes all these links when you boot it. The system unlinks line 3 from process 3 and attaches it to process 4. If you have connected line 3 to a terminal, the terminal appears to be frozen because there is no link to a process. There is a link between process 6 and process 5. In order for this to happen, the system unlinks process 5 from line 5 and process 6 from line 6, then it links process 6 to line 5. Line 6 is an available line and process 7 is a phantom process. 5-10 A Guide to the UniVision System A BASIC program running on process 4 could use SEND to output a message to all lines except line 3. If line 1 was also attached by process 1, the program could not output to line 1. Line 3 is the only line with input and output controlled exclusively by process 4. Any process can send output to line 4 so it does not control its own line exclusively. While there is a link between process 4 and line 4 and an attachment to line 3, it is possible to attach it to line 6 as well. In that way, it could control two lines exclusively. As another example, suppose there is a modem attached to line 6. CONVERSE attaches a line to a modem and uses that line to communicate with another computer system. If process 2 executes the following command: >CONVERSE 6 all subsequent output passes through to line 6 and out to the modem. CONVERSE takes care of attaching an available line to the process and detaching the line on exit, automatically . There is another way to control input and output at a terminal using TANDEM. When you tandem another process, the current screen displays all input from that process, and the resulting output simultaneously. TANDEM runs in two modes, View mode and Feed mode. View mode allows you to observe the activity; while Feed mode allows you to submit input to the process. This command is useful for monitoring the activity of users for diagnostic or instructional purposes. Refer to the UniVision Command Reference Manual for more information on TANDEM. UniVision Database Management System 5-11 Section 6 THE UNIVISION CONTROL LANGUAGE The UniVision Control Language Processor (UCL) is an interactive command processor monitoring activity on a user's terminal. When a user logs on, they communicate with the system using the UniVision Control Language (UCL). This section covers the user's interactive environment, including the following topics: • Logging on and off. • Setting line and process characteristics. • User commands. • UCL Stacker. Logging On and Off A user must log on to the system to gain access to the UniVision Control Language processor. The Logon processor monitors each communications line. It displays a logon prompt and waits for user input. To log on, a user must supply the name of the account and, usually, a password. Invalid logon entries cause the system to display an error message and redisplay the logon prompt. The Logon processor must be able to find an Account Definition item in the SYSTEM Dictionary that matches the account name entered at the logon prompt. It must verify the password. Once the system verifies the account name and password, the Logon processor sets up a pointer in the user's workspace to the Master Dictionary for that account and normally passes control to the UCL processor. In addition, the Account Definition item establishes the user's privilege level and various account-level options. The Logoff processor ends user sessions on the UniVision system. The user must enter OFF at the UCL prompt or from the Debugger. The UniVision Control Language 6-1 Restricting User Access The system administrator sets the number of users that can log onto the system at any one time using MAXUSERS. Once the number of users reaches this limit, the system denies access to any additional users as they attempt to log on. Sometimes, the system administrator might use MAXUSERS to prevent users from gaining access to the system during a file-save. It is possible to restrict access to an account to one or more selected processes. You must specify the numbers of the processes permitted to log onto the account as values in Attribute 12 of the Account Definition item. The Logon Proc The Logon Proc is a user-defined Proc with the same name as the account; and stored in the Master Dictionary. The system executes this Proc when a user logs onto the account, whether from the logon prompt or using LOGTO. In addition, execution of the Logon Proc occurs on exiting UCL from the system, providing that the user's Account Definition item has an R in Attribute 9. The two main uses for a Logon Proc are: • to customise the computing environment for a user. • to invoke a user application automatically. For instance, you can use this Proc to establish terminal and printer characteristics for the session. You can insert TERM to set the terminal type. In addition, you can use SP-ASSIGN to change the default printer assignment for the account. For instance, the Master Dictionary for the account named 'SALES' contains the following Proc: PQ HTERM 132,,,,1 P Similarly, a Logon Proc could prompt a user to identify the type of terminal they are working at, and set the terminal type appropriately. Restricting Access to UCL It is possible to use a Logon Proc to invoke an application automatically when a user logs on and bypass the UCL level. However, that does not necessarily prevent the user from exiting the program and getting to the UCL level. To deny access to UCL: • 6-2 Edit the user’s Account Definition item, placing a T in Attribute 9. A Guide to the UniVision System • Create a Proc in the user’s Master Dictionary with the name of the account followed by @TCL Thus, you create a Proc called STAFF@TCL in the STAFF account. • Or create an @TCL Proc in the ERRMSG file. The system executes this Proc only if an @TCL Proc does not exist in the Master Dictionary. Usually, ERRMSG is a global file used by all users. This Proc should not be account-specific. If Attribute 9 of the Account Definition item contains 'T', and neither Proc exists, the user exits to UCL. If the Proc does exist, the system executes it whenever the user's process reaches a state where the UCL prompt would appear. This Proc might present the user with a menu of various application-specific selections, or it might simply execute OFF. ! Note: If this Proc returns control to UCL, the system invokes it repeatedly in a loop. Receiving System Messages On log on, the system might display a message it sends to all users of the system. The system administrator creates these messages as a LOGON item in the system ERRMSG file. For example, the administrator might need to notify users that the system is closing down after 6 PM to perform routine maintenance. Thus, the following message might appear: ****SYSTEM WILL BE DOWN FROM 6PM TO 7PM TONIGHT**** The LOGON item must exist in the ERRMSG file, even if there are no system messages. During a user session, the administrator or other users can send broadcast messages using MSG or MESSAGE. The Logoff Proc The Logoff Proc is a user defined Proc having the same name as the account but having a @ prefix and .OFF suffix. The system stores this Proc in the account’s Master Dictionary. For example: @SALES.OFF The system executes the Logoff Proc when a user logs off or when a user logs to another account using LOGTO. The UniVision Control Language 6-3 Logging to Other Accounts You can use LOGTO to log to another account directly without logging off the system. You must know the account name and password for that account. You must supply the name of the account as a command-line parameter. The password is an optional command-line parameter and the system prompts for it if required and you have not supplied it. For instance, the following command logs on to the STAFF account: >LOGTO STAFF,GTY708 The system updates the account's usage statistics and displays them on the screen. When s different account logs on the system maintains the UCL command stack and tape attachment. Logging Other Users On and Off LOGON and LOGOFF provide a way to log on and off other users at other processes. Both verbs are only available from accounts with SYS3 privilege. You can use LOGON and LOGOFF to log terminals on and off, making them available for a group of users, none of who actually log on or off the system. Such terminals might run a program displaying a continuous listing of events at a college, for instance. You can use LOGON and LOGOFF to run phantom processes that do not require user intervention. To log on a remote process, enter LOGON and the system displays the following prompt: PROCESS,NAME You must specify the process number followed by a comma, the account name and, if required, a password. To log off a remote process, enter LOGOFF and the system prompts for the process number. Both commands display a message indicating that the operation was successful. In addition, you can use LOGOFF to log off users who cannot quit their session normally by typing OFF at the terminal. Automatic Logoff It is possible to enable automatic logoff for a process, causing the process to be logged off the system after a specified period of keyboard inactivity. AUTO-LOGOFF target [seconds] [(options[)]] 6-4 A Guide to the UniVision System target One of the following account Any account logged on to this process. n Process number n-m Range of processes * All processes ** All account *** All processes and accounts seconds Number of seconds of keyboard inactivity before the system logs off the process automatically. options Can be one of the following: C Turns off automatic logoff for the specified target. D Monitors the incoming DTR signal for the specified target and performs an automatic logoff if it detects none. Q Enables Logoff and Quit from UniVision. R Redisplays the setting after an update. The following example specifies that you want to log off process number 9 automatically after 600 seconds (10 minutes) of keyboard inactivity: >AUTO-LOGOFF 9 600 For more details on automatic logoff refer to the UniVision Command Reference Manual. Setting Line and Process Characteristics Communications line settings allow a user's terminal to communicate properly with the system. In addition, each process has a number of default settings that you can modify. Normally, you expect the line characteristics and the default process settings to be correct, especially if the terminal has been connected to the system and in operation on a regular basis. If they are not, however, it is fairly easy to change these characteristics. Communications Line Settings Typically, the means of connection between a terminal and the system is a cable running between a communications port on the computer system and a port on the terminal. Two devices can communicate when both are using the same protocol. The UniVision Control Language 6-5 At installation, the UniVision system establishes its default settings for a communications line, as shown in Table 6-1. In addition, this table lists the command used to change these settings. Setting Default Command Baud Rate Parity Bits DTR X-in X-out Echo 9600 NONE 8 OFF ON ON ON PROTOCOL PROTOCOL PROTOCOL PROTOCOL PROTOCOL PROTOCOL ECHO-ON/ECHO-OFF Table 6-1: Default Line Characteristics. As you can see you use PROTOCOL to change most of the communications line settings. Refer to the UniVision Command Reference Guide for more information on these commands and a description of each of these parameters. ! Note: These defaults might be different at your site. When you turn on the terminal and the system displays a stream of unfamiliar garbage characters instead of a logon prompt, it could be that you have not set the baud rate or parity properly. Baud rate, is the speed of transmission, and is usually 9600 for lines connected to terminals. Commonly you set modem lines at 300, 1200, or 2400, or even higher with more modern modems. These settings must be the same at both ends. You should ask the system administrator for help in establishing the correct line characteristics for your line. Process Settings There are a number of default settings established for each process on the system. These settings define the state of the type-ahead buffer and provide or deny user access to the UCL stack and the Debugger. Table 6-2 shows the default settings, together with the command used to change the setting. Setting Default Command Type-Ahead Buffer UCL Stack ON ON Always on STACK-ON/STACK-OFF Debugger ON DEBUG-ON/DEBUG-OFF Table 6-2: Default Process Settings 6-6 A Guide to the UniVision System Once again, the defaults might be different on your system. For instance, end-user applications usually disable <BREAK>, denying users access to the Debugger. The Type-Ahead Buffer Each process maintains a type-ahead buffer. The type-ahead buffer allows a user to continue typing another command while the system is still processing a previous command. In other words, the user does not have to wait for the UCL prompt to reappear to begin typing. The type-ahead buffer collects user input and processes it when the system is ready for it. UniVision always enables the type-ahead buffer. In addition, PROTOCOL has options that affect the operation of the type-ahead buffer: wrap You can enter this option, but it has no effect. bell You can enter this option, but it has no effect. C When you specify C, the system clears the contents of the type-ahead buffer. Listing Line and Process Characteristics LIST-LINE-CHARS lists the line characteristics for any or all lines on the system. Entering LIST-LINE-CHARS (or its synonym LLC) at the UCL prompt produces a report similar to the following: LINE 0000 0001 0002 0003 0004 0005 0006 0007 0008 BAUD 9600 9600 9600 9600 9600 9960 9600 9600 9600 PARITY BITS DTR X- BELL EVEN 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON NONE 7 OFF OFF ON BUFFER 0 0 0 0 0 0 0 0 0 PROCESS L 0000 L 0001 L 0002 L 0003 L 0004* L 0005 TA- ECHO TANDEM N/A OFF ON N/A N/A N/A N/A N/A N/A N/A ON BY 000 N/A N/A L 0007 L 0008 N/A N/A N/A N/A This report lists the line and process characteristics for 9 lines. The asterisk for line 4 in the PROCESS column indicates that line 4 generates the report. If you want to list the line characteristics for a single line, you should specify the line number as a parameter in LIST-LINE-CHARS. In addition, refer to LINEPROTOCOL. The UniVision Control Language 6-7 Terminal and Printer Output Settings TERM displays or modifies terminal and printer characteristics. Normally, you do not have to change the standard settings. However, if the logon is from a different type of terminal from the one normally in use, you might have to change these settings. In addition, some terminals support a 132-character display, that you might require on some occasions to preview reports sent to a line printer. You use TERM to change the settings for the process for the current Logon session. Do not use SET-TERM (in SYSPROG) to make the changes, as the change affects the default settings for all users. Entering TERM at the UCL prompt lists the current terminal and printer characteristics. >TERM PAGE WIDTH PAGE DEPTH LINE SKIP LF DELAY FF DELAY BACKSPACE TERM TYPE TERMINAL 79 24 0 1 5 8 V PRINTER 132 60 Table 6-3 describes each of these settings: Parameter Default Description width 79 Number of characters per line on a terminal. Must be in range 9 to 350. depth 24 Number of lines displayed on the terminal screen. Must be in the range 0 to 32767. 0 means no page breaks. skip 0 Number of lines skipped at the bottom if the terminal screen. The system subtracts skip from page depth. Must be a number between 0 and 32767. lf-delay 1 Number of null characters output after each carriage return. Must be a number between 0 and 127. The delay characters provide a pause for terminals that cannot displays characters as fast as the CPU outputs them Table 6-3: Specifying Terminal Setting with TERM 6-8 A Guide to the UniVision System Parameter Default Description ff-delay 5 Number of null characters output after a form feed character for the terminal or printer. Must be a number between 0 and 127. If you specify 0, the system does not send a form feed character to the terminal or printer at the beginning of a page. If you specify 1, the system sends a form feed (FF) character to the printer, hexadecimal (0'C), CHAR912), but not to the terminal. If you specify 2 or greater the system sends the form feed character to both the printer and terminal. backspace Taken from the UNIX parameters. It is a number between 0 and 127. ptr-width 132 Number of character per line for a printer. Must be a number between 10 and 350. ptr-depth 60 Number of lines on printer page. Must be a number between 0 and 32767. type V Terminal type code. The parameter changes the form feed character to match the requirements of the specific terminal and sets cursor addressing for BASIC cursor functions. Table 6-4 lists some terminal type codes. Table 6-3: Specifying Terminal Settings with TERM (continued) You must enter each of these parameters in the order shown above, each separated by a comma. Consecutive commas indicate a null parameter, leaving the current setting unchanged. The following command sets the line width to 132 and the form-feed delay to 0: >TERM 132,,,0 TERM does not return any message. You can verify the changes by entering TERM again without any parameters. Specifying the terminal type allows the UniVision system to send the proper codes, as required by the terminal, to perform certain functions that control the screen, such as form feeds, clearing the screen, and cursor addressing. The full screen editor, UniWord, and BASIC programs that use @, use these functions most often Table 6-4 lists the default terminal types and the codes used to identify them. The UniVision Control Language 6-9 Code Description A B I J M P Q S T V W a b s v AT386 AT386-M IBMPC VT100 AMPEX HP2621A WYSE 50 ANSI Standard TEC2402 VIEWPOINT Standard VIEWPOINT Enhanced at386 at386-m ANSI standard VIEWPOINT 132 col Table 6-4: Terminal Type Codes ! Note: The system terminal defaults and terminal types might be different for your system installation. Check with your System Administrator for any differences. If the terminal you require does not appear in the list, check the manufacturer's documentation to see if it is possible to set up the terminal to emulate any of the terminals in this list. If not, refer to the UniVision System Administration Guide for information on defining a new terminal type. If type is the only parameter you want to specify, you can enter its value without any preceding commas. For instance, if you were dialling into UniVision from a personnel computer, you can use TERM to identify the terminal as type S, an ANSI standard terminal: >TERM S This setting would remain in effect throughout the current logon session. User Commands There are two types of command a user can execute at the UCL prompt: 6-10 • Verbs • Procs A Guide to the UniVision System The UCL processor looks in your Master Dictionary for the first word you type and passes control to a system processor specified by the entry. The one exception is UCL Stacker command set, that the UCL processor handles directly. Verbs Typically, verbs fall into the following categories: UCL-I Verbs These verbs do not access data files and typically provide system information. UCL-II Verbs These verbs do access files, usually performing common file management tasks. VISION These verbs access data files using the definitions found in an associated dictionary. Catalogued Programs The verbs represent catalogued UniVision BASIC programs, allowing users to invoke UniVision BASIC programs without RUN. It is useful to learn these categories because the syntax is similar for commands found in each group. Verb Syntax The UCL statement consists of a verb, optional or required parameters, and options enclosed in parentheses. verb [parameters] [(options)] The system does not interpret the statement until you press <RETURN> to submit it. The verb must exist in the Master Dictionary of the account and the user must have the appropriate privilege level to use the verb. Parameters comprise one or more arguments supplied on the command line. These parameters might be a filename, a single-letter, or a numeric value, as required specifically by the verb. Parenthetical Options One or more parenthetical options, specified on the command line, and enclosed in parentheses. You only require the opening parenthesis. You can enter these options, listed alphabetically below, in any order, and need not separated them with spaces or delimiters. Where a comma is shown as part of the syntax, it is optional. Option Function C Suppress default column and page headings, and end-of-list message. The UniVision Control Language 6-11 D Suppress detail lines. D Delete original select-list (COPY-LIST). E Terminate selection process with <CTRL-X> or <ESC>. F Generate form feed. H Suppress page heading and end-of-list message. I Suppress item-IDs. I List item IDs (FIND) L[,n] Limit number of items selected. N Suppress pagination for terminal output. O Overwrite item (T-LOAD and COPY). P Direct output to printer. Q Suppresses the need to enclose item IDs and attribute values in quotes. R,[n] Keep running count of item selected, n is the step; default is 1. T Direct output to the terminal (default). X Print data in hexadecimal format (COPY-LIST). Y Displays translation of DICT entries. Not all options are available for all verbs. In fact, some options are specific to a verb. Verb Formats Each user has their own verb vocabulary, based on verb entries in the account's Master Dictionary. It is possible to expand or reduce the user's vocabulary by adding or deleting entries in the Master Dictionary. Users can create synonyms for existing verbs by making a copy of the entry under a new name. ! Note: You should take care not to remove entries accidentally or modify the contents of any verb entry. Each verb has its own entry in the Master Dictionary. The format of these entries is similar for all verbs, but it varies slightly according to whether the verb is a UCL-I, UCL-II, or VISION verb, or a catalogued BASIC program. It is not necessary to understand the format of verb entries. New users might want to skip the remaining material in this section. 6-12 A Guide to the UniVision System A P in Attribute 1 identifies a verb. It is possible to follow this letter by any letter except a Q (Q indicates a Proc and PQX indicates a PQX/PQN Proc). In addition, all verbs define a main entry point for a processor in Attribute 2. This entry point is the location in hexadecimal of the executed code. Table 6-5 shows the format of UCL-I verbs. Attribute Example Description 0 TIME Item ID: Unique identifier of verb in Master Dictionary. 1 P Identifiers: A P indicates a verb. Optionally followed by a single character passed to the processor. 2 2D Processor's Entry Point. Table 6-5: UCL-I Verb Format UCL-II verbs are entries that have a '2' in Attribute 2. Table 6-6 shows the format of UCL-II verbs. Attribute 2 parses the command line, verifies the filename, and stores the location of the file in the process workspace. On completion the system transfers control to the processor defined in Attribute 3. In addition, some UCL-II verbs define a tertiary transfer point in Attribute 4 used as a branch routine by the processor. Attribute 5 contains a parameter string passed to the processor. Attribute Example Description 0 ED Item ID: Unique identifier of a verb in Master Dictionary. 1 P Identifier: A P indicates a verb. Optionally followed by a single character passed to the processor. 2 2 File Processor Entry Point: Defines entry point for routine to parse command line for file and validate filename and item ID. 3 3 Secondary Transfer Point: Defines transfer point for processor to handle file and item now specified in workspace. 4 Not Used Tertiary Transfer Point: defines routine to branch to routine above. Table 6-6: UCL-II Verb Format The UniVision Control Language 6-13 Attribute Example Description Parameter String: These parameters determine how UCL-II verbs retrieve and pass items to the processor defined in Attribute 3. 5 C Copy item to process workspace. F Use file parameters only and ignore item list. N Creating new items is permitted. P Printer item ID if item list ID '*@ or if using a select-list. Table 6-6: UCL-II Verb Format (Continued) VISION verbs are entries that contain '35' in Attribute 2. Table 6-7 describes the format of VISION verb entries. '35' references code in entry point hex 35 that parses the VISION command line. Attribute Example Description 0 LIST Item ID: Unique identifier of verb in Master Dictionary. 1 PL Identifiers: A P indicates a verb. Optionally followed by a single character passed to the processor. In this case L indicates LIST 2 2 Processor's Entry Point: Defines entry point for routine to parse VISION command line. Table 6-7: VISION Verb Format Catalogued UniVision BASIC programs have entries in the Master Dictionary referencing the entry point of the UniVision BASIC Runtime package and the name of the file containing a pointer to the location of the object code. Table 6-8 describes the format of entries for catalogued programs. Attribute Example Description 0 FX Item ID: Unique identifier of verb in Master Dictionary. Table 6-8: Catalogued Program Verb Format 6-14 A Guide to the UniVision System Attribute Example Description 1 P Identifiers: A P indicates a verb. 2 E6 Processor's Entry Point: Defines entry point for UniVision BASIC Run-time Package. 3 Not Used 4 Note Used 5 BASICLIB Program File: This is the name of the file, whose dictionary contains a pointer to the object code. Table 6-8: Catalogued Program Verb Format (Continued) UCL-I Verbs UCL-I verbs are a set of general purpose verbs that do not require the user to specify the name of file. These verbs can access various system files to get information, but the user does not need to identify the file. In general, these verbs do not support parenthetical options, except where specifically allowed. The following is a list of some UCL-I verbs: BLOCK-PRINT Displays a character string using block letter definition in the BLOCK-CONVERT Dictionary. DUMP Lists the contents of one or more frames. ECHO Controls whether the system echoes user input on the screen. MSG or MESSAGE Send a message to users of a specified account or line, or to all users or all lines. P Suppresses or permits, toggle, output to terminal. SLEEP Suspends a process for a specified number of seconds or until a time-of-day specified. TERM Sets and displays terminal and printer settings. TIME Displays the current time and date. WHO Displays the user process numbers and account names. >> Enters a multi-command execution level without entering the Debugger. << Exits from a multi-command execution level without entering the Debugger. The UniVision Control Language 6-15 A set of UCL-I verbs define the user environment: DEBUG-ON Enables the use of the Virtual Debugger and the UniVision BASIC Debugger for a particular process. DEBUG-OFF Disables use of both Debuggers. ECHO-ON Enables echoing by the operating system of all character entered by user. ECHO-OFF Disables echoing of user input. STACK-ON Enables the UCL Stacker. STACK-OFF Disables the UCL Stacker. In addition, there are verbs that perform various arithmetic functions: ADDD SUBD MULD DIVD Performs addition, subtraction, multiplication and division on pairs of decimal numbers. ADDX SUBX MULX DIVX Performs addition, subtraction, multiplication and division on pairs of hexadecimal numbers DTR DTX Converts decimal to another radix. Default is hexadecimal. RTD XTD Convert hexadecimal to another radix. Default is decimal The preceding lists of UCL-I verbs include only those used most commonly verbs. Refer to the UniVision Command Reference Guide for a complete description of the use of all verbs. UCL-II Verbs UCL-II verbs are commands that access files. You must supply the name of the file together with a list of one or more item IDs. The general form of the syntax is: verb [DICT] filename [item-list|*] [(options)] st The name of a file must follow the verb immediately as the 1 parameter on the command line. The DICT modifier specifies the dictionary of the file. An item list is a list of individual item IDs, each separated by a blank space or surrounded in quotes. You can specify an asterisk in place of an item list to indicate all items in the file. If an item ID contains blanks or parentheses, you must surround it with single quotes. The item list is optional when a select-list is available. 6-16 A Guide to the UniVision System A list of some general-purpose UCL-II verbs follows: COPY Copies selected file items to another file, the terminal or the printer, or copies an item to a new item in the same file. RENAME Changes the name of a file. DOC-EDIT or DE Invokes the screen-oriented Editor. EDIT or ED Invokes the line-oriented Editor. FIND Selects items in a file containing a specified string. GROUP List file item statistics for an item's group. NSELECT Uses a current select-list to search a file and creates a selectlist containing items not found in the file PRINT-ERR Invokes System message processor. QSELECT Creates a select-list containing data from specified attributes instead of item IDs. VISION Verbs It is possible to think of VISION verbs of as UCL-II verbs that support an extended syntax. These verbs include LIST, SORT, and SELECT. In addition, VISION verbs require a filename and accept an item list. The st filename can appear in any position on the command line except the 1 . In addition, these verbs allow you to specify output criteria as well as modifiers and connective. Refer to the Section entitled VISION Syntax the VISION Reference Guide for a complete description of the syntax of VISION verbs. Procs Procs are stored procedures interpreted by the PROC processor. You define Procs as PQ or PQX items in the Master Dictionary and often as items in a user's Proc library. The system uses the global file, UVPROCS, to store system Procs. The Master Dictionary contains a pointer to the UVPROCS file and each Proc points to an item in that file. The following shows the CT Proc in the Master Dictionary: CT 001 PQ 002 (UVPROCS CT) A number of standard Procs are available in an account including: The UniVision Control Language 6-17 CT Copies one or more items from file to screen. Invokes COPY. LISTCONN Displays a sorted list of the connectives available in the account. Invokes SORT. LISTDICT Displays a sorted list of the Attribute Definition items in the Master Dictionary or any file dictionary. Invokes SORT. LISTFILES Displays a sorted list of File Definition items in the master Dictionary or any file dictionary. Invokes SORT. LISTPROCS Displays a sorted list of Procs in the Master Dictionary or any specified file dictionary. Invokes SORT. LISTVERBS Displays a sorted list of verbs in UVPROCS or any specified file dictionary. Invokes SORT. Catalogued UniVision BASIC Programs You can execute UniVision BASIC programs catalogued in an account as userdefined verbs. These verbs might invoke user applications software for word processing or spreadsheets. The BASICLIB and UVPROCS files, contain a few sample UniVision BASIC programs. In addition, other programs might be available in your account. You must catalogue UniVision BASIC subroutines in an account to enable programs to call them. You do not have to catalogue the calling program. UCL Stacker The UCL Stacker maintains a stack of previous commands entered by the user. In addition, Procs and UniVision BASIC programs can add to the stack. The default size of the stack, or the number of statements stored, is 20. The system pushes each new command on top of the stack. For instance, once the system executes WHO, it goes on to the stack as statement 1. 1 WHO nd Entering another command pushes WHO into the 2 position. Entering TIME, for example, places TIME in the top position. 1 TIME 2 WHO The system now refers to WHO as statement 2. Each time you enter a statement the system pushes all previous statements down to make room for the new statement at the top. 6-18 A Guide to the UniVision System 1 TERM V 2 TIME 3 WHO If entering a new command causes the stack size to exceed 20, the system removes a statement from the bottom of the stack. You can retrieve, execute and save any statement in the UCL stack from the stack using a few basic commands. UCL Stacker commands begin with a (.) and consist of a single letter. The stack does not store UCL Stacker commands. .? lists a summary of the UCL Stacker commands. Enabling the UCL Stacker Normally, you enable the UCL for an account. You can disable it using STACKOFF and enable it using STACK-ON. If you disable the UCL Stacker, the system attempts to interpret stack commands as verbs and produce an error message. Referencing Other Processes It is possible to use all UCL Stacker commands with a few exceptions to reference a stack belonging to another process, providing the user has SYS2 privileges. Thus, you can retrieve, modify and execute statements from another user's stack,. The syntax for this option is to place the process number in parentheses. For instance, the UCL Stacker command: >.L5 (2) Lists the top five statements in the stack of process 2. There are several commands that do not accept this option: .A, and .M modify the top statement in your stack only; .K does not allow you to delete statements from the stack of another process; and .R reads an item into the current stack only. In addition, .Q, .S, and .Z accept the parameter '(A)' specifying that the command affects all processes. Listing the Stack .L displays all or some if the statements stored in the stack currently. By default, the system displays the first 20 statements in the stack. This command takes one or two parameters as follows: .L[n[,m]][(process)] The UniVision Control Language 6-19 n specifies the number of statements to display. If you do not specify a value, .L uses the last value specified for n. By default, .L displays 20 statements. m specifies the number of the statement from which the display begins. If you do not specify a value, .L begins the display with the first statement in the stack, the statement entered or executed most recently. process number of a process other than your own. This option allows you to list statements in the stack of a specified process. You require SYS2 privileges to use this option. ! Note: The number of statements listed is independent of the number of statements stored in the stack, as set by .S. Executing Previous Statements It is possible to re-execute any statement from the stack. .X without any parameters executes the top statement in the stack, the last statement entered. In addition, the command accepts parameters as follows: .X[n[,m,...]][(options)] n number of the stack statement you want to execute. Default is 1. m number of each additional stack statement you want to execute. Use commas, without spaces, to separate the statement numbers. .X displays and executes the statements in the order specified. options number of process other than your own. This option allows you to execute statements from the stack of the specified process. You require SYS2 privileges to use this option. The system displays the statement before executing the command. The system does not duplicate the command on the stack unless n equals m. ! Note: After the system re-executes a stack statement, it moves it from its original position to the top of the stack. Modifying Previous Statements There are a number of ways to modify commands in the stack: 6-20 .E Edit statements in the stack. .M Modify top statement by replacing specified text. .A Append text to top statement in stack. A Guide to the UniVision System Because the last two commands affect only the top statement in stack, you often use them after .G to get any command in the stack and bring it to the top. All of these commands affect the contents of the stack; however, they do not execute the modified statements. You must do this explicitly, using the UCL Stacker execute command, .X. Editing the Stack .E invokes the system Editor to edit the statements in the stack. The system treats each statement as a separate line, like an attribute in a file item. This command is useful for modifying more than one statement in the stack. .E[n][(process)] n number of the statement in the stack. If you do not specify a number, .E positions the current line pointer at line 1. process number of a process other than your own. This option allows you to edit statements in the stack of the specified process. You require SYS2 privileges to use this option. Choosing a Command to Modify .M and .A can operate only on the top statement in the stack. You use .G to retrieve any statement in the stack and place it on top. .G requires a single parameter, the number of the statement you want to move. The system moves the specified statement from its previous position, and renumbers all statements accordingly. Replacing Text .M modifies the top statement in the stack. It allows you to perform a search-and replace operation on the line. The syntax is: .M[U]/text1/text2[/] U changes all occurrences of text1 to text2. Use this option if text1 appears more than once in the statement. text1 text string in statement you want to replace. text2 text string you want to substitute for text1. The following examples show two uses of .M to edit a single command line. The st 1 use is an example of making multiple replacements on a one line using U. Without U, the system only changes the first occurrence of NAME to LAST-NAME. nd The 2 use is an example of a single replacement. The UniVision Control Language 6-21 >.L1 001 LIST CUSTOMERS WITH NAME EQ SMITH NAME PHONE >.MU/NAME/LAST-NAME/ LIST CUSTOMERS WITH LAST-NAME EQ SMITH LAST-NAME PHONE >.M/SMITH/"SMITH"/ LIST CUSTOMERS WITH LAST-NAME EQ "SMITH" LAST-NAME PHONE The search pattern must contain at least one character. Remember that the search string need only consist of as many characters that identify the text you want to replace uniquely. You can use any non-numeric character as the delimiter in place of the slash (/). You might use a different delimiter, such as *, when either the search or replacement string contain a slash. Appending Text .A appends text to the end of the top statement on the stack. The syntax is: .A text You must separate the specified text from .A by one space. As you often use this command to append parameters to a statement you will find that the text string must also begin with a space. For example, to append BY LAST-NAME to an VISION statement, you would specify: .A__BY LAST-NAME st nd where _ represents a single space. The 1 space serves as a delimiter; the 2 space is part of the text string you want to append. Storing a Series of Statements .C invokes the COPY processor to copy statements from the UCL stack to an item in a file. You can store multiple statements as a single file item. The syntax is: .Cn [,m,... [(options)] 6-22 n number of the statement in the stack you want to copy. m number of one or more additional stack statements you want to copy to a file item. A Guide to the UniVision System options list of options that modify the operation. Enclose the options in a set of parentheses. process process number of a process other than your own. This option allows you to copy statements from the stack of the specified process. You require SYS2 privileges to use this option. A copies all stack statements. O overwrites existing file item. P copies to printer. T copies to terminal X copies in hexadecimal. Because .C invokes the COPY processor, the system displays the standard COPY prompt to identify the name of an item. By default, the system copies the statements to the Master Dictionary. To specify another file, enter the filename, preceded by an opening parenthesis and followed by a closing parenthesis or a space, and the item ID. The following example shows saving the top two statements in the stack as an item in the Master Dictionary. Use CT to list the new item to show the order in which the system stores the statements. >.L2 001 LIST CUSTOMERS 002 QSELECT ORDERS * (1) >.C2,1 TO : CUST.ORDER.LIST 1 TO CUST.ORDER.LIST 1 ITEM COPIED >CT MD CUST.ORDER.LIST CUST.ORDER.LIST 001 QSELECT ORDERS * (1) 002 LIST CUSTOMERS > You might create a file specifically for storing items created from the command stack. Using such a file makes it easier to locate and maintain these items. For example, the following command: .C3,5,6 TO:(TC REPORTS) The UniVision Control Language 6-23 copies statements 3, 5, and 6 from the stack to the item 'REPORTS' in the file 'TC'. When the TO: prompt appears, pressing <RETURN> displays the list of commands on the screen. If you specify a filename, you must specify an item ID as well. Retrieving an Item .R reads the contents of any item containing valid UCL statements, executes them in sequence, and places them on the stack. Typically .R retrieves items created using .C. Its syntax is: .R [DICT] filename [item-ID] [(L)] DICT specifies the file dictionary filename name of the file. item-ID identifies the item in filename containing the stored statements you want to execute. L load statements in item-ID into the stack without executing them Each attribute in the specified item must contain a valid UCL command. The system places statement 1 on the stack and executes it, then it pushes the next statement on the stack and executes it. You can incorporate any UCL stacker command in a Proc. For example: 001 002 003 004 005 PQ C DO ITEM-ID : RUN IDENTIFIED PROC FOUND IN TC FILE H.R TC A2 P .R is completely recursive; it can execute items containing .R commands that, in turn, executes the statements in other items. Deleting Statements from the Stack .K deletes, kills, any statement from the stack. The syntax is: .Kn n number of the stack statement you want to delete. You can only delete one statement at a time from the stack. When you delete a statement, the system renumbers the statements preceding it in the stack. Thus, if you want to delete several consecutive statements, delete them in reverse order. 6-24 A Guide to the UniVision System Setting UCL Stacker Options There are a number of commands used to change the operation of the UCL Stacker. These commands toggle the current state. You require SYS2 privileges to uses these options. .O Disables or enables the UCL Stacker. Used to disable the commands in the stack storage temporarily. .P Disables or enables Proc command storage. By default, Proc command storage is ON. When you execute a Proc from UCL, the system places the name of the Proc and the statements it executes on the stack. When disabled, the system only places the name of the Proc on the stack. .U Enables or disables upper-case conversion. Normally, the system places commands on the stack exactly as you enter them. When you enable upper-case conversion, the system converts all statements to upper-case before placing them on the stack. The system does not convert literals. Only requires SYS0 privileges. .Sn Set the maximum number of statements stored in the stack to n. The default is 20. .Zc Assign c as the UCL delimiter. ESC is the default delimiter of UCL statements. Use this command to specify a new delimiter. Only requires SYS0 privileges. Normally, you use all of these commands to change the state of your own process. If you have SYS2 privileges, you can change the state for any other process by specifying the process number in parentheses. In addition, .Z and .S allow you to change the UCL delimiter and stack size for all processes by specifying A. You can examine the status of all of the UCL Stacker options using .Q (query). Its syntax is: .Q [(A|process)] .Q lists the UCL Stacker options for your process. A lists the status of the UCL Stacker options for all users. Specifying process lists the status of the UCL Stacker options for the specified process. You require SYS2 privileges to use these options. An example of the report generated by .Q follows: >.Q User# 4 Stack 20 #Cmnds 25 The UniVision Control Language Page 2 .O ON .P OFF .U OFF UCL Delim ([) X’RFB’ 6-25 The report has the following format: 6-26 User# line number of the user's terminal. Stack maximum length of the stack, as set by .S. Default is 20. #Cmnds number of commands stored in the stack. Page number of stack commands displayed, as set by .L. .O indicates whether the UCL Stacker is enabled or disabled. .P indicates whether Proc command storage is enabled or disabled. .U indicates whether upper-case conversion is enabled or disabled. UCL Delim shows in parentheses the character used for the UCL delimiter as set by .Z, followed by its equivalent hexadecimal value. A Guide to the UniVision System Section 7 FILE MANAGEMENT This section provides an overview of managing files on the UniVision System. It covers the following topics: • Creating and deleting files. • Copying items from files. • Creating Q-pointers to reference files in other accounts. • Establishing file security procedures. • Performing routine file maintenance to ensure retrieval efficiency. • Understanding backup and restoration procedures. File Management Tasks UniVision provides a number of system commands for managing files and manipulating the items contained in files. You use these commands to create, edit, copy, delete, and clear files. The file management commands are: CREATE-FILE Creates new dictionaries and data files in an account by allocating the file's primary space. RENAME Changes the name of the dictionary portion of a file, the data portion of the file, or both the dictionary and data portions. MOVE-FILE Transfers file between accounts. CLEAR-FILE Clears the file area occupied by the data file or dictionary. It does not de-allocate the primary space, as does DELETEFILE. In addition, it releases any linked frames, returning them to the overflow area. DELETE-FILE Deletes the file dictionary, the data file, or both, from the account. All frames allocated for the file are released. File Management 7-1 ! Note: It you delete a dictionary file you must have deleted the data files associated with this dictionary before attempting to delete it. EDIT or ED Creates modifies, or deletes individuals items in a file. EDIT (or ED) is a line-oriented editor based on the standard Editor, and DOC-EDIT (or DE) is a full-screen editor. COPY Copies selected file items to another file, the printer or the terminal, or copies any item to a new item ID in the same file. DELETE Deletes specified items from a file. Filename Syntax All the file management commands are UCL-II verbs. All recognise the same syntax for specifying a file. You must define the specified file in the Master Dictionary of the account. Each data file must have as its counterpart a dictionary file describing the nature of the data. You can think of each file of as having two sections: a data section and a dictionary section. Both the dictionary and the data file contain items. When the dictionary and the data file have the same name, you only need to specify the name of the data file. When you supply a filename, the system looks in the account's Master Dictionary for a File Definition item of the same name identifying the dictionary. It then looks in the file dictionary to find a File Definition item pointing to the data file. For example, when you specify the filename 'CUSTOMERS', the name of the dictionary is 'CUSTOMERS' and the name of the data file is again 'CUSTOMERS'. You can use file management commands to access the data file or the file dictionary independently. The following modifiers precede the filename: DATA A modifier specifying that only the data file is the target of processing. DICT A modifier specifying that only the dictionary is the target of processing. 'DICT CUSTOMERS', for instance, refers to the dictionary of the CUSTOMERS FILE. If multiple data file share a dictionary, you can access each data file independently of the other data files associated with the dictionary. If the name of the data file you want to access is different from the name of the dictionary, you must specify the name of the dictionary followed by the name of the data file. A comma, with no spaces on either side of it, must separate the name of the dictionary from the name of the data file. In the following example: 7-2 A Guide to the UniVision System PERSONNEL,DAY-SHIFT The syntax indicates that DAY-SHIFT is a data file associated with the dictionary PERSONNEL. A dictionary can exist without a data file, this is a single-level file. The dictionary contains a Q-pointer that references itself, indicating that the items in the dictionary are the target of any operation. The Master Dictionary is a single-level file, which is why you do not have to specify 'DICT MD' to access it. On the other hand, a data file cannot exist without an associated dictionary file. Item Lists Some of the file management commands (COPY, ED and DE) accept an item list. st An item list indicates one or more items you want to process in the file. The 1 form of an item list is a string of item IDs with each item ID surrounded by single or double quotes or separated from the next item ID by a space. An example of a list of three item IDs is: '10118' '10119' '10121' nd A 2 form for specifying an item list is by an asterisk (*). This indicates that you rd want to process all items in the file. A 3 way to specify an item list is to generate a select-list before invoking the file management processor. You use the select-list as the item list for the command. You use SELECT, SSELECT, QSELECT or GET-LIST to make a select-list active. Refer to the Section entitled Statement and Function Reference in the VISION Reference Guide for more information on working with select-lists. Creating Files You use CREATE-FILE to create: • a dictionary file. • a data file and its associated dictionary. • a data file only, if a dictionary already exists with the same name. • a file using the B+Tree hashing algorithms. The syntax for creating a file is: CREATE-FILE {filnam|dicnam,datnam} dicmod datmod [(R)] [(options] CREATE-FILE DICT filnam mod [(R)] [(options] CREATE-FILE {filnam}{dicnam}{datnam} (B[J] [(options] CREATE-FILE DATA filnam mod [(R)] [(options] File Management 7-3 filnam name of the file dicnam,datnam full name of the file. Use this format to create a data file that is one of multiple files associated with a single dictionary. dicmod modulo value of the dictionary datmod modulo value of the data file DICT specifies the file dictionary DATA specifies the data file mod modulo value of the dictionary or data file R creates a file in a target account. B creates a file using the B+Tree hashing algorithm with leftjustified identifiers. BJ creates a file using the B+Tree hashing algorithm with rightjustified identifiers. options one of the following: X creates a DX file, which means you cannot save the file. Y creates a DY file, which means you can save the file, but not the data. Creating a Dictionary >CREATE-FILE DICT INVENTORY 3 [417] UniVision File 'INVENTORY' Created; Base=10074, Modulo=3. Creates a dictionary called 'INVENTORY', allocating 3 frames for it, and placing a D-pointer of the same name in the Master Dictionary. If, subsequent to the creation of the dictionary, you do not create a data file, the dictionary is a single-level file that contains a Q-pointer to itself. This is called a reflexive Q-pointer, containing no information in Attributes 2 and 3 of the entry. Creating a Data File A dictionary must exist before you attempt to create a data file. 7-4 A Guide to the UniVision System When you create a data file, CREATE-FILE allocates the data file's primary file space. The system creates a File Definition item in the associated dictionary. This D-pointer identifies the data file and contains the base frame ID and modulo. The dictionary has File Definition item for each data file that it points to. For example: >CREATE-FILE DATA INVENTORY 373 [417] UniVision File 'INVENTORY' Created; Base=10077, Modulo=373. Creates the data file 'INVENTORY', allocating a block of 373 frames for it, and placing a D-pointer of the same name in the file dictionary named 'INVENTORY'. Creating a New Database It is possible to create a dictionary and data file at the same time. This usage requires you to specify the modulo of the dictionary and the modulo of the data file. This form of CREATE-FILE performs the creation of the dictionary followed by the creation of the data file in a single step. If you want multiple files st to share the dictionary, you can only use this syntax to create the 1 data file. You only specify the name of the dictionary if you do not want it to have the same name as the data file. >CREATE-FILE SHIPPING 3 373 [417] UniVision File 'SHIPPING' Created; Base=10450, Modulo=3. [417] UniVision File 'SHIPPING' Created; Base=10453, Modulo=373. Creates a dictionary named 'SHIPPING', allocating 3 groups for it, and placing a D-pointer in the Master Dictionary. In addition, it creates the data file 'SHIPPING', allocating 373 groups for it, and placing a D-pointer in the SHIPPING dictionary. The following example creates a dictionary and a data file with different name: >CREATE-FILE PERSONNEL,DAY-SHIFT 3 37 [417] UniVision File 'PERSONNEL 'Created; Base=10826, Modulo=3. [417] UniVision File 'DAY-SHIFT Created; Base=10829, Modulo=37. This command creates the dictionary 'PERSONNEL', allocating 3 groups for it. In addition, it creates the data file 'DATA-SHIFT' allocating 37 groups for it. The Master Dictionary has a D-pointer for the dictionary PERSONNEL which has the D-pointer to the data file 'DAY-SHIFT'. The Master Dictionary does not have any reference to DAY-SHIFT. To create another data file associated with the PERSONNEL dictionary, you would enter the following: File Management 7-5 >CREATE-FILE DATA PERSONNEL,NITE-SHIFT 37 [417] UniVision File 'NITE-SHIFT' Created; Base=10867, Modulo=37. This command creates a data file name 'NITE-SHIFT', placing a D-pointer in the PERSONNEL dictionary. Creating a File in a Target Account >CREATE-FILE ORDERS 3 3 (R ACCOUNT NAME: SYSPROG Creates a file in a target account, creates the file ‘ORDERS’ and stores the pointer for that file in the account SYSPROG. Creating UniVision BASIC Files You use CREATE-BFILE to create a UniVision BASIC program file. The system creates the source code for a UniVision BASIC program as an item in the data file; when you compile the source file, the system places an item in the file dictionary pointing to the location of the object code. CREATE-BFILE has the same basic syntax as CREATE-FILE. >CREATE-BFILE BP 3 37 [417] UniVision File 'BP' Created; Base=10904, Modulo=3. [417] UniVision File 'BP' Created; Base=10907, Modulo=37. CREATE-BFILE performs the same function as CREATE-FILE except that it creates a File Definition item in the Master Dictionary with a Definition Code of 'DC'. This indicates to the system that the file dictionary contains items pointing to the location of complied UniVision BASIC object code. In addition, it is possible to use CREATE-FILE for this task, providing you change the Definition Code of the D-pointer in the Master Dictionary from 'D' to 'DC'. Clearing a File CLEAR-FILE clears data from a file. You use it when you want to discard the contents of a file yet want to maintain the primary file space for future use. CLEAR-FILE sets the file to an empty state by placing a segment mark in the first data position of each group. The system releases any additional frames linked to a group. The system returns these frames to the overflow area. Thus, by clearing a file, the system reduces it to the space originally allocated for it. CLEAR-FILE clears either the dictionary of the data file. It is not possible to clear both files with a single command. The syntax is: 7-6 A Guide to the UniVision System CLEAR-FILE DATA {filnam|dicnam,datnam} CLEAR-FILE DICT filnam DATA specifies the data file. DICT specifies the file dictionary filnam name of the file. dicnam,datnam full name of the file. Use this form to clear a data file that is one of multiple files associated with a single dictionary. Clearing a file does not change the disk space allocated for the file originally; however, it returns any additional frames linked to the file to the available space. >CLEAR-FILE DATA SHIPPING clears all items from data file SHIPPING. This command does not return a message when successful. Deleting Files You use DELETE-FILE to delete: • a dictionary and its associated data files. • any data file. • any dictionary, provided you have deleted the data files associated with the dictionary before attempting to delete it. DELETE-FILE removes the D-pointer referencing the file and releases the frames occupied by the file. Obviously, you should use any command that removes data from the system with extreme caution. You should only remove files for which there is a backup. DELETE-FILE does not delete files referenced by Q-pointers. You can delete only files referenced by D-pointers. You can delete the File Synonym item in the Master Dictionary (using DELETE), but cannot delete the file itself. In fact, you should remove all Q-pointers to a file you want to delete, as those synonyms no longer point to a valid file. The syntax is: DELETE-FILE filnam DELETE-FILE DICT filnam DELETE-FILE DATA {filnam|dicnam,datnam} filnam name of the file you want to delete. DATA specifies the data file. File Management 7-7 DICT specifies the file dictionary dicnam,datnam full name of the file. Use this format to delete a data file that is one of multiple files associated with a single dictionary. If you do not specify modifiers, filnam identifies the file dictionary and all of its associated data files. For example, if PERSONNEL is a dictionary shared by two data files. >DELETE-FILE PERSONNEL deletes the dictionary and both of the data files. The system does not return a message when the command finishes successfully. If you only want to delete one of the data files, you could use the following command: >DELETE-FILE DATA PERSONNEL,NIGHT.SHIFT The system removes the D-pointer 'NIGHT.SHIFT' in the PERSONNEL dictionary and returns the space occupied by the data file to the overflow area. You use the DICT modifier to delete a file dictionary. You cannot delete just the dictionary if it contains any D-pointers. In other words, you must delete all of its associated data files before you can delete the dictionary. You use the DATA modifier to delete a single data file. If the data file and the file dictionary do not have the same name, you must specify the dictionary name. Copying File Items You can use COPY to copy: • one or more items to other items in the same file, assigning new item IDs. • Any or all items in a file to another file, using the same item ID or assign new ones. In addition, you can use COPY to display the contents of one or more items on the screen or printer. In addition, CT invokes a COPY, CT copies the contents of an item to the screen or printer. A copy operation involves a source and a destination. COPY requires you to specify the source on the command line and prompts you for the destination. The command-line syntax is: COPY [DICT] filnam item-list [(options)] 7-8 A Guide to the UniVision System DICT specifies the file dictionary filnam name of the source file containing the original item or items. This must exist on the current account item-list list of item IDs you want to copy, separated by blanks. Use double quotes to enclose item IDs that have embedded blanks. An asterisk (*) specifies all items. options modify COPY. Enclose the options in parentheses and separate the options with a comma. The following options are available for specifying the target destination of the copied items: P copies data to the line printer. T copies data to the terminal. In addition, you can use CT to copy items to the terminal. The following options are available for copying items or files to other items or files; D deletes the source item after copying it. I does not list item IDs after copying them. N does not copy an item to the target file unless an item with the same name already exists there. O overwrites items in the target file it they already exist there S suppresses error messages. The following options are available for copying items or files to a printer or terminal. F inserts a form feed between each item. N skips the automatic end-of-page wait. S suppresses line numbers. X displays data in hexadecimal form. COPY displays the prompt TO: where you enter the destination, using the following syntax: {item-list|([DICT] filnam )}[item-list] File Management 7-9 DICT specifies a file dictionary. When copying from a dictionary, COPY does not copy dictionary items that have a definition code of D (File Definition items) filnam name of the destination file, enclosed in parentheses. This file must exist on disk. item-list list of item IDs to be assigned in sequence to the copied items. Use blanks to separate the item IDs, and use double quotes to enclose any item ID with embedded blanks. If you omit this item-list, the system uses the item IDs in the source file. If you are copying the items to the same file, the item IDs cannot be the same as those for existing items, unless you are using the O option. If you have not specified any of the above parameters, pressing <RETURN> causes the system to display the source items on the screen. If you only specify an item-list, the source file and the destination file are the same. The system copies items to the same file, using the item IDs specified in the item list. The following example creates a duplicate of the item 'LETTER-JOHN' in the file 'DOCUMENTS'; the duplicate has the item ID 'LETTER-JAMES'. >COPY DOCUMENTS LETTER-JOHN TO:LETTER-JAMES 1 LETTER-JOHN TO LETTER-JAMES 1 Items copied Following the copy operation, the DOCUMENTS file contains both 'LETTERJOHN' and 'LETTER-JAMES' items. You require a left parenthesis before a filename that is the destination of the copy operation. A right parenthesis after the filename is optional. If you specify a file and an item list, the system copies the source items to the destination file using the item IDs specified in the destination item list. You cannot copy File Definition items in a dictionary to another file. If you do not specify a destination item list, the system copies the source items using the same item ID. The following example copies two items from the file 'ORDERS' to the file 'ORDERS,PAID': >COPY ORDERS 10123 10124 TO:(ORDERS,PAID) 1 10123 2 10124 2 Items copied After the copy operation, both files have items '10123' and '10124'. On a file copy, the system displays the item ID of each item copied. (The I option suppresses the display of item IDs). 7-10 A Guide to the UniVision System During a file copy operation, you can specify the source file item list using an asterisk (*), indicating that you want to copy all items to the destination file. If the source is a dictionary file, the system copies all items except D-pointers. If the item ID in the destination file, the system displays the following message: [415] 'item' exists on file. 0 Items copied Use the O option to overwrite all items specified on the destination item list. The N option used with the O option restricts the operation to overwriting existing items. This option specifies that a file copy operation should succeed only if the item already exists in the destination file. It ensures that the system does not create new items in the destination file. Use the D option on a file copy operation to delete the source file item once the system has copied it to the destination file. In the following example: >COPY ORDERS '10103' (D) TO:(ORDERS,PAID) 1 10103 1 Items copied The system copies item 10103 to the ORDERS,PAID file, and then deletes it from the ORDERS file. Editing Items UniVision provides two editors you can use to create and modify items in a file. An editor performs the bulk of file management tasks on UniVision from editing items in the Master Dictionary or the file dictionary to creating items in the data file. You can create, copy, merge, modify or delete one or more items in a file using an editor. EDIT (or ED) invokes the line-oriented Editor. DOC-EDIT or DE invokes the screen-oriented editor. The syntax for invoking either editor is: ED[IT]|D[OC ]E[DIT] [DICT] filnam [item-ID] [(options)] DICT specifies the file dictionary filnam name of the file containing the items you want to edit. item-ID list of items you want to edit. The list can include a UniVision BASIC program as well as items in either a dictionary or data file. It is possible to enter multiple item IDs. An asterisk (*) specifies all items in filename. File Management 7-11 options can be any of the following: H displays data in hexadecimal format. (ED and EDIT only). L displays line numbers. (DE and DOC-EDIT). S suppresses the display of line numbers. (ED and EDIT only). Z suppresses TOP (top of item) and EOI (end of item) messages. (ED and EDIT only). The following example uses the Editor to create a new item in the ORDERS file. The Editor prompts for the item ID: >ED ORDERS ITEM ID: 10135 NEW ITEM TOP . The new item ID is 10135. When you invoke the Editor, the system positions the line pointer at the top of the item. The Editor prompt is a period (.). It is only possible to enter Editor commands at this prompt. When you use the full screen editor, I (insert) to enter insert mode and allows you to type new text. Pressing <ESC> exits insert mode, and typing FI in command mode saves the new item in the file and quits the Editor. FD deletes the item you are editing. Refer to the UniVision Editor Reference Guide for more information on using the Editor. Refer to the UniDoc Reference Manual for more information on using DE. Deleting Items DELETE removes items from dictionary or data files. The syntax is: DELETE [DICT] filnam item-list DICT specifies a file dictionary filnam name of the file that contains item-list item-list list of item IDs you want to delete. Separate each item ID with a space. An asterisk (*) specifies all items in the file. The system deletes the items specified in the item-list from the specified file. >DELETE ORDERS,PAID '10123' '10123' Deleted 7-12 A Guide to the UniVision System Take care when using with DELETE since it has no safety feature. Issuing a DELETE results in the system removing the item or items from the file immediately. However, DELETE does not allow you to delete a file pointer. For example, if you try to delete a 'D' pointer the system displays the following message: >DELETE MD INVOICE [236] File definition item 'INVOICE' not deleted To remove the Editor from a user's account, you could delete the Verb Definition item from the Master Dictionary. DELETE does not prompt for confirmation that you want to delete the item. >DELETE MD ED EDIT 'ED' Deleted 'EDIT' Deleted ! Note: If you accidentally delete a verb from the master Dictionary, you can copy the verb definition from the NEWAC file located in the SYSPROG account. If you do not specify the item ID on the command line, DELETE prompts for an item ID. >DELETE MD ITEM ID:ED 'ED' Deleted In addition, you can delete a list of items if a select-list is present when you perform a DELETE: >SELECT INVOICE WITH PAID = "Y" 4 Items Selected >DELETE INVOICE '101767 Deleted '103678' Deleted '102901' Deleted '102906' Deleted File Management 7-13 Creating File Synonyms As discussed previously, you cannot copy File Definition items from a dictionary. The system discourages the creation of duplicate D-pointers. Instead, you use Qpointers, or File Synonym items, to reference a file under a different name in the same account or to access files in other accounts. The Q-pointer is a symbolic reference to the original file. The system follows this reference to the File Definition item in the Master Dictionary of the specified account to determine the location of the file. You can perform most file management operations on a file regardless of whether you access it by a Dpointer or a Q-pointer. In addition, this is true of all VISION operations. However, DELETE-FILE is an exception, preventing you from using a Q-pointer to delete the original file. While DELETE-FILE deletes the original file and its D-pointer, it does not check for existing Q-pointers in the Master Dictionary. Make sure you delete any Qpointer if you delete the file they reference. Creating Q-Pointers The basic format for a File Synonym Definition item requires you to specify the first three attributes. Attribute 1 A 'Q' that identifies the type of item. Attribute 2 The name of the account where you can find the File Definition item, as reference in Attribute 3. If null, the system assumes file is in the same account. Attribute 3 The name of the file, or more precisely, the item ID of the File Definition item that identifies the file in the account specified in Attribute 2. It cannot reference a Q-pointer. If null, then this item points to the Master Dictionary of the account. The remaining attributes are the same as for a File Definition item. You can create File Synonym Definition items in the Master Dictionary using the Editor or SET-FILE, as described in the next section. The following example provides a short synonym for a file: ORD-1 001 Q 002 003 ORDERS-JANUARY Attribute 2 is null, indicating that the File Definition item is in this account. 7-14 A Guide to the UniVision System In the next example, the system can find the file in another account. BK-CAT 001 Q 002 BOOK-INVENTORY 003 BOOK-CATALOG This Q-pointer 'BK-CAT' references the file 'BOOK-CATALOG' in the account 'BOOK-INVENTORY'. Because a File Definition item need only be unique in its own account, another Q-pointer named 'BOOK-CATALOG' could point to the account as well. If you access files in another account regularly, it might be useful to create a pointer to the Master Dictionary for that account. For instance: MD-STAFF 001 Q 002 STAFF 003 is a Q-pointer to the Master Dictionary of the STAFF account. ! Note: rd The 3 attribute is null. Once you have created this Q-pointer, you could copy items such as Procs between the two Master Dictionaries. The following example, copies a Proc named 'ED-PROG' to the Master Dictionary of the STAFF account. >COPY MD ED-PROG TO:(MD-STAFF 1 ED-PROG Now the item 'ED-PROG' exists in both accounts. A Q-pointer must point to a valid File Definition item or to another Q-pointer. SET-FILE SET-FILE creates a temporary Q-pointer. It requires two parameters: the name of the account containing the file and the name of the file. It creates a File Synonym Definition item named 'QFILE' in the Master Dictionary containing this information. Each use of SET-FILE overwrites the previous contents of the item. This type of file synonym is especially useful in applications for establishing access to a file in another account in order to run VISION reports or to copy items from the file. For example, assume you created a catalogued BASIC program named 'PHONELOG' and you want to make it available to two other accounts. To do that, you must copy the verb from the current Master Dictionary into the other accounts. You can use SET-FILE to create a temporary file pointer to the Master Dictionary of each account. File Management 7-15 >SET-FILE STAFF MD 'QFILE' Updated >COPY MD PHONE-LOG TO: (QFILE 1 PHONE-LOG 1 Items copied >SET-FILE SALES MD 'QFILE' Updated >COPY MD PHONE-LOG TO: (QFILE 1 PHONE-LOG 1 Items copied Once you have created the QFILE item, it is possible to make a copy of it under a new name in the Master Dictionary. This is an alternative way to create a permanent Q-pointer instead of using the Editor. For instance, if you wanted to create a permanent Q-pointer to the Master Dictionary of the SALES account, you would enter the following: >COPY MD QFILE (D) TO:SALES 1QFILE 1 Items copied This command makes a copy of the QFILE item under the name 'SALES' and deletes the original QFILE item from the Master Dictionary. File Security On a database management system, most security issues revolve around protecting valuable data from unauthorised use or modification. This section describes the various ways that UniVision allows application developers to protect data stored on the system. st The 1 level of file security is preventing unauthorised users from gaining access to an account. The logon process requires users to specify an account name and, usually, a password. The use of secure passwords is the best way to limit access by users and therefore restrict file access. An Account Definition item in the SYSTEM Dictionary contains the specified account name and password. 7-16 A Guide to the UniVision System nd The 2 level of security is restricting user access to UCL. This prevents users from using the commands that access files. A Logon Proc in the user's account makes it possible to invoke an application program on successful logon. In addition, if Attribute 9 of the user's Account Definition item specifies a 'T', the system denies the user access to UCL whenever an application would normally return control to the UCL. This is contingent on the existence of a Proc named 'account-name@TCL' in the Master Dictionary or one named '@TCL' in the ERRMSG file. rd The 3 level of security is establishing system privilege levels. UniVision provides four privilege levels from zero to three with SYS3 being free from restrictions, SYS0 permits users to access files in an account but not to create or delete them. In addition, SYS0 users cannot modify the Master Dictionary. SYS1 and SYS2 permit updating of files, but SYS1 users cannot access the system debugger. SYS3 is the top privilege level, typically used by the administrator and overrides any other form of protection, such as retrieval and update codes (as explained below). SYSPROG gives SYS3 privileges automatically; it is recommended that you give access to the SYSPROG account sparingly. th The 4 level of file security is the proper segregation of files in accounts. You should limit the D-pointer in an account to only those files needed by the users of the account. You should disable the ability to create Q-pointers in accounts where it is necessary to restrict access to files outside the account. The removal of the Editor verbs and SET-FILE from the account ensures that users cannot create Qpointers to access remote files. For instance, an application developer might determine that files in the PERSONNEL account or PAYROLL account should not be available to users of the general STAFF account. th The 5 level of file security is retrieval and update codes, specified in File Definition items. These codes can restrict file access among users of the same account as well as files available to many accounts. Retrieval and Update Codes Retrieval and update codes amount to setting up permissions on reading the contents of a file and modifying the file. You must establish the retrieval and update codes themselves and use them consistently on each system. The codes can be any string of ASCII characters. Place retrieval codes in Attribute 5 and update codes in Attribute 6 of the following items: • Account Definition item in the SYSTEM Dictionary. • File Definition item in an account’s Master Dictionary or in a File dictionary. File Management 7-17 You can specify multiple codes separated by value marks for an Account Definition item. You can specify retrieval and update codes in the Account Definition item during CREATE-ACCOUNT. If You do not specify a code, the system does not perform any retrieval or update checking. In addition, you can add or modify them, for any item using the Editor. The recommended time for modifying the retrieval and update codes is when there is no one else logged on to the system. Placing a code in a file dictionary pointer protects the data file but not the dictionary itself. Placing a code in the Master Dictionary, restricts access to both the dictionary and the data file. The system determines retrieval and update permissions by comparing the code specified in the user's Account Definition item with the code in the File Definition item of the file being accessed. For a match to occur, the code specified in the File Definition item must be identical to the initial sub-string of any value specified in the code of the Account Definition item. For instance, a File Definition item with a code of '12' would match an Account Definition item with a code of '123'. To access a file in the account, the retrieval code for the file must match any value in the retrieval code in the user's Account Definition item. To update a file, the retrieval codes must match, and then the update code of the file must match any value in the update code for the Account Definition item. If a file is in a different account, the system compares retrieval and update codes specified in the remote account's Account Definition item with the codes specified in the user's Account Definition item. For a match to occur, the first value of the code for the remote account must match any value specified for the user's account. The following processors update files and thus require a match for both the retrieval code and the update code: • COPY • EDIT • RUN If a match does not succeed, the processor does not continue, and displays the message that the file is 'access protected'. UniVision BASIC requires a match of the retrieval and update codes to open a file. It is possible to establish a fairly simple four-tiered scheme using the string '1234'. You could classify each user as either '1' (the lowest permission level), '12', '123', or '1234' (the highest permission level), and classify all files using the same set of codes. Thus, only users with a retrieval code of ‘123’ or ‘1234 could read a file containing a retrieval code of '123'. Similarly, a user with any of the four codes could access a file with a code of '1'. More examples are shown below. 7-18 A Guide to the UniVision System File Dictionary Code User Identification Code Result 123 123 Match 12 123 Match 123 12 No Match XYZ XUZ5 AQ2 AO Match No Match File Maintenance UniVision files use a hash-encoding scheme to allow fairly direct access to any item in a file without searching through the entire file. The success of the hashencoding, and thus the speed of access to any item, depends on a number of related factors including the type of item in the file, the size of the average item and of the largest and smallest items, and the structure of the file. UniVision allows you to improve access speed by adjusting the file modulo. The modulo determines the number of groups used to store items in. It affects speed of access in two ways. The hashing algorithm, that transforms the key, uses the modulo directly in the hashing algorithm. The modulo should be a prime number to ensure an even distribution of items. The modulo determines the typical number of items stored in each group (the group depth) because it specifies the number of groups. The group depth is a function of the total number of items divided by the modulo. For example, if the number of items is 808 and the modulo is 101, the system estimates the group depth to be 8. The modulo should be sufficiently large such that the expected number of items in a group fit in the frame allocated for the group. Designers of UniVision files should try to estimate the total number and size of items that the file will contain when they are creating the file. However, files have a tendency to grow beyond their designers' expectations, and therefore you should check; the size and efficiency of important files and reallocate space for them when necessary. Tools for Checking File Efficiency Two commands that you can use to test and make recommendations about the best modulo for a file are ISTAT and HASH-TEST. You can check the File Statistics Report, produced by a full backup or file-save, regularly to look for files that might need resizing. How often you carry this out depends on how often you modify the file and how easy it is to access data in the file. File Management 7-19 Once you find that a file seems to be out of trim, you can use HASH-TEST to show how the items the system would reallocate if you used a given modulo for the file. HASH-TEST perform exactly the same function as ISTAT but on a 'what if' basis. The following describes ISTAT and HASH-TEST in detail below. In addition, it describes how to resize files with inefficient modulos. For purposes of illustration, the examples show the results of these commands for both the default Master Dictionary created in a new user's account, and for the same data after being copied to another file with a different, much less effective modulo. Analysing File Structure with ISTAT ISTAT produces a summary of the item distribution for a file and analyses the structure of groups within the file. This item distribution summary can help you determine whether the current file structure is the best one for the file. The following example shows the result of ISTAT run on the Master Dictionary of an account: >ISTAT MD FILE= MD MODULO = 7 FRAMES 1 1 1 1 1 1 1 7 BYTES 1006 595 787 898 643 862 1219 15:36:03 21 APR 1988 ITMS 45 *>>>>>>>>>>>>>>>>>>>>>>>>>>> 28*>>>>>>>>>>>>>>>>>>>> 38 *>>>>>>>>>>>>>>>>>>>>>>> 42 *>>>>>>>>>>>>>>>>>>>>>>>>> 33 *>>>>>>>>>>>>>>>>>>>> 45 *>>>>>>>>>>>>>>>>>>>>>>>>>>> 49 *>>>>>>>>>>>>>>>>>>>>>>>>>>>> ITEM COUNT= 280, BYTE COUNT= 6010 AVG.BYTES/ITEM= 21.4 AVG.ITEMS/GROUP=40.00 STD.DEVIATION= 7.4, AVG.BYTES/GROUP= 858.5 You can see that the distribution of the items is even, with an average of 40 items in each group. Testing File Structure with HASH-TEST HASH-TEST produces the same listing as ISTAT shown above, but displays what the distribution of records would be if you chose a given modulo. The following example shows the result of HASH-TEST run on the same Master dictionary as in the preceding section with ISTAT. It uses a test modulo of 3 instead of the actual modulo of 7: 7-20 A Guide to the UniVision System >HASH-TEST MD TEST MODULO:3 FILE= MD MODULO= 3 FRAMES 1 2 2 BYTES 1740 2005 2265 15:44:46 21 APR 1988 ITMS 78 *>>>>>>>>>>>>>>>>>>>>>>>>>>>>! 98 *>>>>>>>>>>>>>>>>>>>>>>>>>>>>! 104 *>>>>>>>>>>>>>>>>>>>>>>>>>>>>! Item Count= 280, Byte Count= 5010, Avg Bytes/item= 21.4 Avg.items/Group =93.3, Std Deviation=13.6, Avg.Bytes/Group=2003.3 You can see that there is an even distribution across 3 groups, with an average of 93 items in each group. The most obvious problem is that the number of characters in each group is too large and exceeds one frame. On the other hand, with a test modulo of 79, this is the result: >HASH-TEST MD TEST MODULO:79 FILE= MD MODULO= 79 FRAMES 1 1 1 1 1 1 1 . . . 1 1 1 1 79 15:44:46 21 APR 1988 BYTES 119 178 34 119 24 0 79 ITMS 5 9 2 6 1 0 6 62 117 105 36 2 5 6 2 *>>>>> *>>>>>>>>> *>> *>>>>>> *> * *>>>>>> *>> *>>>>> *>>>>>> *>> Item Count= 280, Byte Count= 6010, Avg.Bytes/Item= 21.4 Avg.Items/Group= 3.5, Std.Deviation= 2.0, Avg Bytes/Group = 76.0 Here things are just as bad, but in the opposite direction: several of the frames are empty, and the system is only using only four per cent of the space allocated to each group, a very inefficient use of disk space. File Management 7-21 It is possible to make a few general observations about the number of items per group and the size of groups. If items have sequential numeric IDs, the system distributes the items evenly. If keys are random (that is, not in any particular sequence), the distribution varies. A small modulo and a large number of bytes per group might raise the average access time of items if you need to scan more than one data frame. A large modulo and a small number of bytes per group wastes disk space but provides faster access. The trick is to find the right modulo to balance the number of items per group. One frame per group is ideal. The minimum number of frames per group is one, even for any empty group. A thousand empty groups is worse than having three hundred groups where only some of them require an overflow frame. While the larger file provides more direct access, this affects the VISION and the file-save processor since they have to read empty frames into memory. In addition, remember that the system places an updated item at the end of the group. Having a modulo too small requires extra time to find where the item starts, move the other items nearer the front of the group, and place the updated item at the end. Many groups containing many items affect performance. A low standard deviation (about 1 or less) is good because it is a sign of even distribution. If an item size is greater than one frame, (for example is program source), you cannot help using additional frames. The best choice here is one item per group, but you must balance it against how many empty groups might exist if the modulo was very large. Examining Groups in Closer Detail GROUP and ITEM are two commands that allow you to look at the distribution of items in groups in closer detail. GROUP shows some information about each item and summarises the contents of each group. For each group, it lists the number of items, the total number of bytes, the number of full frames, and the number of bytes used in the last frame. ITEM produces the same information for a single group to which a particular item hashes. The syntax is: GROUP [DICT] filnam [(P)][(S)] DICT specifies the file dictionary. filnam name of the file. P sends report to the printer. S suppresses the item-list. GROUP lists items by group, within each group, it lists each item separately (unless you use the S option). The following example shows the first page of group statistics for the file ORDERS: 7-22 A Guide to the UniVision System >GROUP ORDERS The report displays statistics in the following format: frame IDs (hexadecimal) number of characters frame ID (hexadecimal) displacement from frame ID item ID 8115 0047 8115.030 HJENK1222M 003F 8115.077 SPIRS112A 0048 8115.0B6 AJOHN760JE 3 ITEMS 206 BYTES 0/206 FRAMES 8116 004C 8116.030 BLEAR34TRE 0042 8116.07C JBOHA126TR 004D 8116.0BE JBUCK26STO 003D 8116.0FE JPEER89RIA 003D 8116.13B HJOHN455OT 5 ITEMS 328 BYTES 0/328 FRAMES 8117 0042 8117.030 MASH912AE 003C 8117.072 DEDGE338BR 004F 8117.0AE AORLA55VEN 3 ITEMS 205 BYTES 0/2O5 FRAMES At the end of each group listing, the system displays totals that provide the number of items in the group; the total number of bytes used in the group; the number of full frames in the group; and the number of bytes used in the last frame of that group, in decimal. S only displays this line for each group. ITEM accepts an additional parameter, an item ID. The report produced by this command displays the same information as GROUP except that it shows only one group, the one to which the specified item hashes. The item need not exist, so you can use ITEM to find out to which group a particular item hashes. >ITEM ORDERS ITEM ID:10104 10104 9529 0029 9529.030 10107 0022 9529.059 10119 0039 9529.07B 10110 0023 9529.0B4 10122 002A 9529.0D7 10113 0036 9529.101 10104 0033 9529.137 10116 0022 9529.16A 10101 0022 9529.18C 10134 9 ITEMS 382 BYTES 0/382 FRAMES File Management 7-23 This report shows that item '10104' hashes to a group whose frame ID is 9529. It th is the 6 of nine items in the group. The items in this group are quite small, totalling 382 bytes. In the next example, the group examined is from a file containing UniVision BASIC programs. >ITEM BP PHONE-SEL PHONE-SEL 9478 0894 9478.030 ODATA-ENTRY 00A2 9481.0F4 PHONE-SEL 2 ITEMS 2358 BYTES 1/358 FRAMES >XTD 894 2196 >XTD 00A2 162 There are two items in this group, occupying two frames. It invokes XTD to convert the size of each item in bytes from hexadecimal to decimal. Thus, the first item is 2196, 2000 of which can fit in the first frame of the group. This information is helpful in evaluating the size of this file, showing you that items exist that are larger than a single frame. Reallocating Files Once you have determined that a file needs a new modulo, it is easy to reallocate the space for it. You do this by specifying a reallocation parameter as Attribute 13 of the file Definition item. You must enclose the new modulo in parentheses. The reallocation takes place by performing an account-save or file-save followed by an account-restore or file-restore. The following procedure summarises how to back up and restore the account containing the file: • • Change the modulo by entering the new modulo, enclosed in parentheses, in Attribute 13 of the File Definition item or Account Definition item. Back up either the account containing the file or the entire data area (with ACCOUNT-SAVE or FILE-SAVE). Refer to the UniVision System Administration Guide for information about backing up and restoring files. • Restore either the account or the entire data area (with ACCOUNTRESTORE or :FILELOAD). The system creates a file with the new modulo and restores the items to it. 7-24 A Guide to the UniVision System R is available for ACCOUNT-RESTORE or :FILELOAD to alter the effects of bypassing any resize parameters. R allows you to recover from problems encountered with incorrect resize parameters. For example, if you resize a file or set of files more than the current amount of disk space you have available. R is available to restore the data without applying any resize setting in attribute 13. In addition, you can copy data from the file you want to resize to a newly created file with the correct modulo. The method using COPY is less common and might be inappropriate for very large files. • Create a temporary file using CREATE-FILE. • Copy the contents of the file you want to resize into the temporary file using COPY. • Delete the original file using DELETE-FILE. • Create a new file with the new modulo. • Copy the contents of the temporary file into the new file. • Delete the temporary file. You can resize larger files by writing the file to tape with T-DUMP and restoring it to disk with T-LOAD. In COPY operations, make sure that you do not forget the dictionary items. Of all of these methods of file allocation, the most common one is a file-save and restore using :FILELOAD. The system administrator should perform this when there is no one else logged onto the system. :FILELOAD deletes all SYSTEM entries immediately, and requires a tape to be ready. Since this is a planned save and restore, you should use the validation check of FILE-SAVE to ensure the tape is good before any optional or elective restore. A full file-restore is the only way to ensure the reallocation of files in one block of contiguous frames. That is, all secondary file frames for each group follow the primary file area (one frame per group). Reallocating files using COPY or ACCOUNT-RESTORE creates a contiguous block for primary space, but the secondary space comes from the Overflow Table. A full file-restore can improve performances. When selecting the reallocation parameter, here are a few things to remember: • The modulo should be a prime number. • The modulo should not be divisible by three or five. These are not 'hard and fast' rules, but help to ensure a more even distribution of items in groups. File Management 7-25 Backup and Restoration Making backups of files on tape is an important part of protecting data and ensuring the integrity of files. If you accidentally delete a file subsequently or if its data becomes corrupted, you can restore the most recent version of the file from tape. Generally speaking, the system administrator at each site should establish routine backup procedures for the entire system. Nonetheless, application programmers should know enough about these procedures to understand the contents of the back up and how often it occurs. There are two types of backup: full and partial. A full backup saves the entire data area of disk; a partial backup saves only a portion of it. It is possible to make partial backups that save an entire account. For a complete description of the backup and restoration strategies and procedures, refer to the UniVision System Administration Guide. This section describes the account-save and account-restore procedures. An account-save is similar to a file-save; it backs up a single account whereas a file-save backs up all accounts on the system. In addition, you can use the account-save and restoration process to move an account from one UniVision to another via tape. The commands that allow you to back up and restore a single account are: ACCOUNT-SAVE A full backup of all files in a single account. ACCOUNT-RESTORE Restores ACCOUNT-RESTORE an entire account from an ACCOUNT-SAVE tape. In addition, the following command is useful for restoring individual items from a tape. SEL-RESTORE Restores one or more items selectively from a file on a tape created by the FILE-SAVE or ACCOUNT-SAVE tapes. These commands are available in the SYSPROG account and for details of their syntax and use, refer to the UniVision Command Reference Guide. 7-26 A Guide to the UniVision System Section 8 ACCOUNT MANAGEMENT This section examines account management in the context of individual users and groups of users. It describes the facilities for managing accounts available in the SYSPROG account. It looks at the structure of items that identify the account and users of the account at the system level. It looks at how to tailor an account's Master Dictionary. It touches on accounting history, system messages, and security on an account level. Account management is mostly the responsibility of the system administrator. It involves issues affecting all users of the system and requires access to the SYSPROG account. However, application programmers should understand the issues involved in maintaining and managing multiple user accounts, and the activity of users working in those accounts. The SYSPROG Account It is only possible to perform many of the system-level tasks in a special account called the SYSPROG (SYStem PROGrammer) account. The SYSPROG account gives unlimited access to all files on the system as well as to certain commands that ordinary users cannot invoke because their Master Dictionary does not include those commands. The SYSPROG account is the account used to maintain the entire UniVision system. You can only perform starting up and shutting down the system, backing up and restoring the system, and many other administrative tasks, from the SYSPROG account. The SYSPROG Master Dictionary contains a number of verbs used for administrative purposes not found in any other account on the system. Accessing the SYSPROG Account You should password protect the SYSPROG account. The password prevents unauthorised users from accessing the verbs and files in this account. If the administrator has given you authorisation to use the SYSPROG account, you can log on to it from the logon prompt. In addition, you can log to it from another account using LOGTO. The rest of this section describes files and verbs accessed from the SYSPROG account. Account Management 8-1 Contents of the SYSPROG Account The SYSPROG account contains files used for administrative purposes. They are similar in function to the system-level files contained in the SYSTEM Dictionary, described in a later section. You can find more detailed information about these files in the UniVision System Administration Guide. SYSPROG Commands The commands in the SYSPROG account are available for the system administrator to set up and maintain the system. This section describes the administrative commands, both verbs and Procs, available only in the SYSPROG account, arranged in functional groups; you can find details of these commands in the UniVision Command Reference Guide. For more information on a number of system administration tasks that use these commands, refer to the UniVision System Administration Guide. Start-up and Shutdown STARTUP Performs verification tasks required for a given installation each time you start up the system. RESET-PROCESS Resets a process record corrupted by an untidy exit from UniVision. Setting the Date and Time IDATE Sets the system date format to the international standard. UDATE Sets the system date format to the United States standard. SET-DATE-EUR Sets the system date format to the international standard. SET-DATE-STD Sets the system date format to the United States standard. ! Note: 8-2 The administrator should use the date commands in UNIX to make adjustments to system time and data. The user must be a UNIX super-user to change the system time and date. A UNIX super-user logs in as root. A Guide to the UniVision System Account Management CREATE-ACCOUNT Creates accounts, defines retrieval and update lock codes for them, and defines system privilege levels. DELETE-ACCOUNT Deletes an account and all its files from the system AUTO-LOGOFF Logs off specified processes automatically after a designated period of inactivity or the loss of an incoming DTR signal. LOCKOUT Prevents prospective users from logging on if a specified number of invalid attempt to logon have occurred. LOCKOUT-STATUS Displays the parameters currently in effect for LOCKOUT. LIST-SECURITY-LOG Lists all security violations logged in the SECURITY-LOG file. System Maintenance and Control TANDEM Allows display and control of another process on your terminal; TANDEM effectively links two lines to one process. POKE Inserts a UCL command or a character string in the input buffer of another process. MAXUSERS Sets the maximum number of user who can log on to the system at any one time. :AUTHORIZE Displays the current User Serial Number and Current Authorisation Code and allows the system administrators to changes the Authorisation Code. MODEM-ON/MODEM-OFF MODEM-ON enables DTR monitoring for a specified line. MODEM-OFF disables DTR monitoring. :STARTSPOOLER Initialises or restarts the Spooler without restarting the whole system. SET-TERM Sets the system wide default characteristics for terminals and printers. SET-TAPE Assigns a logical tape unit to a physical tape device. Account Management 8-3 :INIT-TAPE Resets all logical tape units to their default assignments, and clears all tape buffers. :INIT-DISK Allows a user to allocate UNIX disk space reserved for the UniVision environment. :INIT-SYSTEM Sets the type of hardware platform in use. This setting allows UniVision to make correct decisions regarding the configuration of the hardware. BUILD-LOCK-XREF Builds the LOCK-XREF file, containing the UniVision file pathnames for all accounts and files in the UniVision environment. DEFINE-CURSOR Allows administrators to change the UNIX terminal type to UniVision term type letter cross-reference. BUILD-TR-INDEX Builds and index of all triggers, indexing and replicas on the system LIST-TR-INDEX Lists the index of triggers, indexing and replicas. CLEAR-GROUP-LOCKS Clears all the group locks in the system group lock table. RESET-ITEM-LOCKS Clears all the item locks in the item locks table set by the UniVision BASIC statements READU, READVU and MATREADU. ! Note: Use CLEAR-GROUP-LOCKS and RESET-ITEM-LOCKS with caution; they override the protection provided by the UniVision environment to prevent data corruption and Group Format Errors, GFEs. System Monitoring DUMP Displays the contents of disk frames including information about forward and backward links. LIST-FILE-STATS Lists the statistical information from the most recent FILESAVE operation. 8-4 A Guide to the UniVision System System Backup FILE-SAVE Saves the entire data area of the disk to tape. ACCOUNT-SAVE Copies a specified account to tape. SAVE Copies all or part of the data area of the disk to tape. All PROCs used to make backup tape invoke SAVE. System Restoration :FILELOAD Restores all data on the disk using any full file-save tape, that is, those made with the FILE-SAVE commands. ACCOUNT-RESTORE Restores a single account from a FILE-SAVE or ACCOUNTSAVE tape. ADD-ACCOUNTS Restores all accounts that are present on a FILE-SAVE, or ACCOUNT-SAVE tape, but are not on disk. Server Control :STOP-MASTER-SERVER Stops the master server. SERVER-STATUS Displays the contents of specified Server Status files. Miscellaneous Administrative Commands COMPARE Compares items and highlights differences and insertions. >> Enters a multi-command level without entering Debugger. << Exits from multi-command level without entering Debugger. Copying SYSPROG Commands The reason why commands are in the SYSPROG account and are not available to all users is that use of these commands could affect other users on the system. Recommended practice is that only knowledgeable users should attempt to use them. If you give authorisation to access these commands, the user should understand them thoroughly and exercise caution when using them. Account Management 8-5 It is possible to access some SYSPROG commands, but not all of them, from accounts other than SYSPROG. If you access individual verbs in the SYSPROG account regularly, it might be worth considering duplicating the verb in the Master dictionary. However you should implement some way of restricting others from this account. You should not copy the verb from the SYSPROG Master Dictionary. Instead, copy it from SYSMD file. This file contains verbs that you can use outside the SYSPROG account. The commands that you cannot access outside SYSPROG usually reference files defined in the SYSPROG Master Dictionary or the SYSTEM Dictionary. User Account Management You use the SYSPROG account to set up and maintain user accounts. This section describes the creation and deletion of accounts and the maintenance of a system accounting history. Creating and Deleting Accounts CREATE-ACCOUNT creates a new user account. DELETE-ACCOUNT removes an account from the system and deletes all the files defined in that account. You should you both of these commands from the SYSPROG account. CREATE-ACCOUNT prompts for the name of the new account, retrieval and update codes for the account, the privilege level of the account, the modulo for the Master Dictionary, and any password used to access the account. It creates a new Account Definition item in the SYSTEM Dictionary. It is possible to change many of these specifications later by editing the Account Definition item. For instance, you can add or modify update and retrieval codes at a later time. In addition, you change the account's password using PASSWORD. CREATE-ACCOUNT creates the Master Dictionary for the account by copying the NEWAC file in the SYSPROG account. Although there is a standard NEWAC file shipped with each system, administrators can modify this file for a particular site. For instance, you can create new items in NEWAC to include Procs, Qpointers to global files, and catalogued UniVision BASIC programs. In addition, it is possible to remove certain items from NEWAC-verbs that invoke the Editor, for instance. In this way administrators can establish the standard contents of a new account. DELETE-ACCOUNT is obviously a very destructive command. It not only deletes the Account Definition item from the SYSTEM Dictionary, it deletes the account's Master Dictionary and all the files defined in that account. You should only run this program when there are no other users logged on the system. For more information on creating and deleting accounts, refer to the UniVision System Administration Guide. 8-6 A Guide to the UniVision System Account Usage Statistics The UniVision system keeps track of system usage for each user in the Accounting History file (ACC). Users must have a 'U' specified in Attribute 9 of the Account Definition item to store accounting information. The ACC file keeps track of information about users currently active on the system, such as the logon date and time. In addition, it accumulates usage statistics for all users. You can use the ACC file to keep accumulates usage statistics for all users and to keep track of system usage for security or billing purposes. The UniVision System Administration Guide describes the ACC file in detail. CHARGES and CHARGE-TO Verbs CHARGE-TO and CHARGES make use of the Accounting History file for keeping track of computer usage during a work session. CHARGES reports the charges incurred for the current work session in the account. CHARGE-TO allows a user to change the charge-account that they want to bill for subsequent use of the system. CHARGES displays the same one-line report as displayed when you log off the system. It states how long the user has been logged on the system and the amount of CPU time used (in tenths of a second). This information is useful for obtaining the current status of the work session without, of course, ending it. The following example shows the use of CHARGES: >CHARGES []Connect time = 110 minutes; CPU = 48 units Printer = 0 pages[] > The connect time reported is the amount of elapsed time since the user logged on. The CPU time reflects actual processing done by the user including activation overhead. CHARGES does not write this information to the Accounting History file, the system carries this out when the user actually logs out. You can use CHARGE-TO to keep separate records for different activities performed during a single session. For instance, the system might charge a user to one department while performing certain activities and to another department while performing other activities. Using CHARGE-TO ends the current work session, displaying the usage statistics shown above, and begins a new work session. Using CHARGE-TO does not end the current logon session. When invoking this verb, you should specify a single argument, that is any ASCII string. It identifies the charge-account you want to bill. The system appends the name of the charge-account to the name of the account, and separates it with an asterisk. Account Management 8-7 Entering CHARGE-TO without any parameter removes the charge-account identifier. The SYSTEM Dictionary The SYSTEM Dictionary controls the entire system. It holds several different types of files and items: • Account Definition Items • Users IDs • Special operator accounts. • Message items • System level files. The following sections give brief definitions of each of these types. Account Definition Items These are items that define all accounts on the system, together with their associated passwords, security codes, and system privileges. They function as pointers to each account's Master Dictionary. Refer to the Section entitled Database Architecture for the format of Account Definition Items. User IDs A user ID is an Account Synonym Definition item pointing to the account a user actually logs on to. User IDs can have passwords, security codes, and system privileges that are different from those of the Account Definition item. Refer to the Section entitled Creating and Deleting Accounts in the UniVision System Administration Guide for more information. Special Operator Accounts These are special accounts that operators can log on to in order to perform specific backup functions or cold-start the system. These accounts are: • STARTUP • FILE-SAVE The items that define these operator accounts are Account Synonym Definition items (Q-pointers) pointing to the SYSPROG account and invoking a Logon Proc. The UniVision System Administration Guide describes operator accounts. 8-8 A Guide to the UniVision System Message Items The SYSTEM Dictionary contains the system logon message. The item called LOGON contains the logon message and the system displays it on the screen when there is no user logged on to any UniVision account. The standard logon message is as follows: [] UniVision time is 09:39:27 23 AUG 1995 [] Logon Please: The above logon message has the same format and structure as any ERRMSG item. You can change the contents of the logon message using the system editor (ED[IT]) or full screen editor (D[OC ]E[DIT]). You can display the standard logon message using CT. >CT SYSTEM LOGON LOGON 001 L 002 H[] UniVision time is 003 T 004 H 005 D 006 H[] 007 L 008 L 009 HLogon Please: + You can modify the UniVision message following the rules outlined in 'Format of ERRMSG' later in this Section ! Note: You should not update any item in the SYSTEM file while there are users logged on to UniVision. There are two conditions where UniVision can change the above logon message st automatically. The 1 different logon message occurs when the number of users exceeds the maximum set. The other way is when a process exceeds its lockout settings that limit the number of failed logon attempts. MAXUSERS can change the setting for the maximum number of users who can log on to the system at any one time. MAXUSERS is useful when you want to restrict access to UniVision. For example, you should have all users log off during a file-save. Setting the maximum number of users to zero can prevent users from logging on until the system administrator allows logons after completion of the file-save. If the number of users ever exceeds the maximum, the system displays the following message: Account Management 8-9 LOGON DENIED: Maximum licensed number of users reached [] UniVision time is 10:03:23 23 AUG 1995 [] Logon Please: st It is not possible to change the 1 line of the message. However, any modifications to LOGON as described above alter the last two lines of the message. The LOCKOUT item in the ERRMSG file contains the 'LOCKOUT in process' message. The system displays this message after a user's process reaches the limit of permissible invalid logon attempts. Refer to LOCKOUT and LOCKOUTSTATUS in the UniVision Command Reference Guide for further details. The default logon message during a lockout condition is as follows: +--------------------------------------------------------+ + + + LOCKOUT in progress for nnn minutes + + + +--------------------------------------------------------+ Try Later: ! Note: A lockout remains in effect for the number of minutes specified by 'nnn'. LOCKOUT sets the number of minutes before allowing additional logon attempts. The message displayed shows the amount of time before the system allows a logon attempt. The system administrator can override this setting. You can change the above default message using one of the system editors and following the rules outlined in Format of ERRMSG Items later in this section. System Level Files The SYSTEM Dictionary contains pointers to special system files essential to the operation and maintenance of the UniVision environment. Below is a description of these files. ACC 8-10 The ACC file, or Account History file, contains two types of st item. The 1 type holds data about users actively logged on nd to the system. The 2 type holds data that keeps track of usage statistics for users; when they logged on, how much computer time they used, how many pages they sent to the printer, etc. The system updates these items when users log off. Refer to the Section entitled System Security, for more information about the Account History file. A Guide to the UniVision System BLOCK-CONVERT The BLOCK-CONVERT file contains the format of the characters displayed when using BLOCK-PRINT. Each Master Dictionary on the system contains a Q-pointer to BLOCK-CONVERT. DEVICE, DETAILS (DEVICE-DETAILS) The DEVICE-DETAILS file contains information on the tape devices installed under UNIX. :INIT-SYSTEM and :INITTAPE create the items in this file. Various tape commands use the information contained in this file to perform tape operations. DEVICE, ERRORS (DEVICE-ERRORS) The DEVICE ERRORS file contains information on the tape error messages used under UNIX. :INIT-SYSTEM and :INIT-TAPE create the items in this file. Various tape commands use the information contained in this file to recover from UNIX tape errors. DEVICE, NAME (DEVICE-NAMES) The DEVICE-NAMES file contains information on the optional tape name created in the UniVision environment. :INIT-SYSTEM and :INIT-TAPE create the items in this file. Various tape commands use the information contained in this file to use the correct tape device. ERRMSG The ERRMSG file contains system messages. Some of these messages just provide useful information, others provide warnings or indicate error conditions. Each Master Dictionary on the system contains a Q-pointer to ERRMSG. There is a description of the format of the ERRMSG file in the section entitled The ERRMSG File. The UniVision Command Reference Guide, Volume 2, contains a list of the system messages. LOCKS, GROUPS-LOCKS (GROUP-LOCKS) The GROUP-LOCKS file contains a list of group locks set by the UniVision environment. Group locks ensure database integrity. LOCKS, ITEM-LOCKS (ITEM-LOCKS) The ITEM-LOCKS file contains a list of item locks set in the UniVision BASIC programming language. The application code uses item locks to ensure database integrity. Account Management 8-11 LOCKS-XREF The LOCKS-XREF file contains file path names for all account and files in the UniVision database. The system uses the data contained in this file to display the account and file names rather than the frame of page number. NEWAC The NEWAC file is a template for the Master Dictionaries of all accounts on the system: when the administrator creates a new account’s Master Dictionary, the system copies the contents of the NEWAC file to it. The system uses the SYSMD file is the SYSPROG account as a template for accounts requiring SYSPROG capabilities. POINTER-FILE The POINTER-FILE contains saved select-list items. SECURITY-LOG The SECURITY-LOG contains items that record invalid logon attempts, system privilege violations, file access protection violations, etc. STAT-FILE The STAT-FILE stores the file statistics information. FILESAVE or SAVE with the S option creates items in the STATFILE. The administrator uses this information to generate the file statistics report available at the end of a file save of regenerated by using LIST-FILE-STAT. STORE-PATHS The STORE-PATHS file contains information on the disk devices installed under UNIX. :INIT-DISK creates the items in this file. The administrator uses the information contained in this file when they want to add additional disk space to the available space pool. 8-12 UVPROCS The UVPROCS file contains all common Procs such as LISTU, LISTFILES, CT, etc. Each Master Dictionary contains a Q-pointer to UVPROCS, as well as items the link to the Procs stored in UVPROCS. UVPROGS The UVPROGS file contains all common UniVision BASIC programs. Each Master Dictionary contains a Q-pointer to UVPROGS. UV.HELP The UV.HELP file contains all the documentation available to the On-line help utility. A Guide to the UniVision System The ERRMSG File The ERRMSG file provides a standard set of system messages for use by UniVision system processors as well as application programs. An item in this file contains a series of instructions interpreted by the ERRMSG processor. The next section describes the format of ERRMSG items. The following screen shows a simple example of an item in the ERRMSG file in st nd two different formats. The 1 format is a listing produced by CT. The 2 format is a listing produced by PRINT-ERR. >CT ERRMSG 414 414 001 L 002 E Invalid specification of a file >PRINT-ERR ERRMSG 414 [414] Invalid specification of file > You can use PRINT-ERR to invoke the ERRMSG processor on an item in any file. Many of these messages alert the user to an error condition, but might inform the user about the progress or the completion of an operation. A good example is item [289] in the ERRMSG file. TERM uses it to present a formatted display of terminal and printer settings. You can use STOP and ABORT in UniVision BASIC to invoke the error message processor and pass parameters to it. Format of ERRMSG Items An item in the ERRMSG file contains instructions that direct the actions of the ERRMSG interpreter. ERRMSG items work similarly to Procs: the system builds a message in an output buffer and displays the contents of the output buffer on the screen. You can form the message from the list of parameters passed to the ERRMSG processor, from literal strings, or from system variables for date and time. By convention, many items in the ERRMSG file use numeric item IDs. Those starting with 'B' are for UniVision BASIC. When creating new items in this file, you should be careful not to overwrite existing items used by the system. You might want to use a standard prefix as part of the item IDs so that you can identify st the messages specific to an application. The 1 character on each line describes a specific action. Account Management 8-13 A Inserts the next parameter in the list of parameters passed to the ERRMSG processor. A(n) Inserts next parameter in a left-justified field of width n. D Puts the date in the output buffer. E Output ID of the error message. Use it in place of H or on a line by itself. Typically found in Attribute 1. H Places the string that follows in the output buffer. H+ Suppresses final carriage return or line feed when specified on the last line of the item. L(n) Inserts a carriage return or line feed into output buffer. If you specify (n), the system follows the message with n carriage returns. R(n) Inserts the next parameter in a right-justified field of width n. S(n) Sets the pointer in the output buffer to position n. T Puts the current time in the output buffer. X Skips a parameter in the parameter list. The following example shows several lines of a UniVision BASIC program. OPEN specifies a STOP condition executed when the system cannot find the file. The STOP specifies two parameters: the item ID of an item in the ERRMSG file and the string you want to pass. In the following example, the string is the name of a file. FILE="CUSTOMER" OPEN"",FILE ELSE STOP 201, FILE It invokes the ERRMSG processor on item 201, a standard error message. The following shows this item: 201 001 E' 002 A 003 H' is not a UniVision file name Lines 1 and 3 output literal text. Line 2 retrieves the name of the file; specified as the parameter following the message number. When the program invoked this error message, you would see: [201]'CUSTOMER' is not a UniVision file name 8-14 A Guide to the UniVision System When you pass multiple parameters from UniVision BASIC to ERRMSG processor, you separate parameters with attribute marks. STOP "MYMSG"; "PARAMA"; CHAR(254); "PARAMB" Logon Messages Several messages seen by the user are items in the ERRMSG or SYSTEM Dictionary. You specify them in the format of ERRMSG items. You can find the Logon Please message in SYSTEM.ERRMSG items [335] and [336] contain the connect time messages displayed when a user logs on or off the system. In addition, [335] gives the date and release number of the operating system. @TCL You can create an @TCL Proc in the ERRMSG file to assume control over a user's process when control would otherwise pass to the UCL processor. In order for the @TCL Proc to receive control, the user's Account Definition item must specify a 'T' in Attribute 9. If the user's Master Dictionary contains an Proc named 'account-name@TCL', the system executes that Proc instead of @TCL in ERRMSG. Account Management 8-15 Section 9 THE SPOOLER The Spooler is a process that manages access to printers by multiple users. For most users, the function of the Spooler is transparent to them. They generate a job for a printer and go to the printer to pick up their output. These users are probably not aware of a Spooler intervening to capture their output and direct it to an available printer. The Spooler permits users to continue working without waiting for a print job to finish printing. This section introduces how the Spooler works and the commands used to modify its operation. The main focus is on the Spooler-related tasks that you can perform from user accounts, such as changing the default printer assignment, cancelling a job, and capturing output in Spooler hold files. The system administrator handles most of the tasks involving Spooler administration, such as installing and starting up new printers. Refer to the UniVision System Administration Guide for more information. Basic Operation of the Spooler The UniVision Spooler manages any UniVision job that is 'sent to the printer'. The following VISION command uses the keyword 'LPTR' to direct the output to the printer. >LIST CUSTOMERS LAST-NAME FIRST-NAME LPTR In addition, most commands accept the parenthetical option P to send the output of a command to the printer. The Spooler is a special process used by the UniVision environment to control all printers connected to the system and activated in UniVision. The Spooler runs as a separate deamon process, that is a process not linked or attached to any line. The UniVision Spooler is always running in the background waiting for opportunities to direct completed print jobs to the appropriate printer. The UniVision Spooler sends print jobs by issuing the appropriate lp command to the operating system spooler. The Spooler 9-1 In UniVision, the system assigns a number to each printer connected to it, starting with printer number 0, usually the default system printer. In addition, you can assign each printer from one-to-three different form queues, allowing you to use different paper sizes and formats with the same printer. You can assign the same form queue to several different printers, so that if a printer is printing a job nd currently, it is possible to print a 2 job sent to the same form queue on another printer if it is available. In short, the UniVision Spooler has the following roles: • It spools print jobs by directing the output from a user's process to a UniVision print file. In addition, it creates an entry in the print queue for the job. This entry queue allows UniVision to manage the print job until submitted to operating system spooler in UNIX or AIX. • It spools print jobs to the operating system spooler by issuing the appropriate lp command. The system issues the lp command for the appropriate and available printer. This allows UniVision users and users on other UNIX or AIX based products to share the same printer devices. • UniVision maintains copies of the print files and they follow the normal rules for UniVision print jobs described later in this section. For further information on setting up printers, refer to the UniVision System Administrator Guide. About Printers and Forms You reference each printer connected to the system by number. Usually printer number 0 is the default system printer. The administrator assigns each printer a number when they add it to the system. In addition, the administrator can assign up to three form queues to a printer. The default is form queue 0. You can consider a form queue as a logical printer. A form queue represents any printer or printers set up to handle the same computer paper or preprinted form. You can assign multiple printers to service the same form queue. Figure 9-1 illustrates how you might assign several printers to service different form queues. The following illustration, directs form queue 1 to two line printers using 130column computer paper. A job sent to form queue 1 prints on either Printer 1 or Printer 2. When you load Printer 3 with preprinted labels, it services form queue 2; when loaded to print envelopes, you must configure Printer 3 to service form queue 3. 9-2 A Guide to the UniVision System Form Queue 1 Printer 1 Printer 2 Form Queue 2 Printer 3 with labels Form Queue 3 Printer 3 with envelopes Figure 9-1. You assign printer to serve a form queue At startup, the administrator decides the form queue serviced by Printer 3. To change the form queue, the administrator must remove the printer from the system and restart it. ! Note: You can direct jobs to form queue 2 or 3, regardless of the form queue assigned to Printer 3. If Printer 3 is servicing form queue 2, the system accepts jobs sent to form queue 3 and holds them in the print queue. When you restart Printer 3 to service form queue 3, the system outputs the spooled jobs. Each account has a single form queue assigned to it, as illustrated in Figure 9-2. The default is from queue 0, usually directed to the default system printer. Users can change the form queue assignment for their account, using SP-ASSIGN. ! Note: The Spooler It is important to remember that users do not choose a system printer directly; they choose a form queue serviced by that printer. 9-3 Assigned Form Queue Account Figure 9-2 You assign a single form queue to an account Consider as an example a system with only one printer. The administrator sets up this printer as the default printer 0 that services form queue 0. The default form queue assignment handles all jobs on 130-column computer paper. However, it is possible to set up the same printer to handle special preprinted invoices. You direct these special jobs to form queue 1 by changing the form queue assignment in the account. When you submit the print job, the Spooler looks to see if any printer is servicing that form queue. If the printer is not printing another job currently the system handles a job sent to form queue 0 immediately. The system holds a job sent to form queue 1 until you restart the printer to service that form queue. Perhaps you decide to holds invoices and print them at the end of the day. The Spooler allows users to share a single printer or multiple printers, as well as to use a single printer to print on different types of paper or forms. Print Files and Hold Files Each print job generates a print file. The job's entry in the print queue points to the location of the print file, retrieved when the printer is ready to accept the job. Once the job finishes printing, the system removes the print queue entry and returns the space used by the print file. The system holds print files in the print queue if the assigned printer is not available. 9-4 A Guide to the UniVision System In addition, the system can maintain output from an account as a hold file. A hold file is a print file with a ‘hold' status. It remains on the print queue, regardless of whether the system prints the job or not. You must delete hold files explicitly from the queue when you no longer need them. You use SP-ASSIGN to specify that you want to retain spooled output as a hold file. You use SP-EDIT to manipulate hold files on the queue. It allows you to examine, print or direct to tape any hold file on the screen. In addition, you use SP-EDIT to delete hold files or direct them to a form queue different from the one specified originally. SP-KILL can only cancel a job printing currently. You must convert print files not printing in the queue into hold files using SP-KILL; only then it is possible to manipulate them. That is, you cannot view or delete a print file unless it has a hold status. You must make it a hold file and use SP-EDIT to perform those tasks. Command Summary This section covers many commands used to affect the operation of the Spooler or to report on its status. The UniVision Command Reference Guide describes the following commands in detail. STARTPTR Initialises or restarts a system printer. :STARTSPOOLER Restarts the Spooler without restarting the entire system. LISTABS Lists the current Spooler assignments for all lines on the system. LISTPEQS Lists the status of the print files and hold files managed currently by the Spooler. LISTPTR Displays information about system printers. SP-ASSIGN Directs and controls output sent to the printer and assigns a form queue to a process. SP-CLOSE Closes the print file. SP-COPIES Allows administrators to modify Spooler records SP-EDIT Manipulate Spooler hold files SP-ENABLE Allows users to restart the printer. SP-KILL Stops a current print job from printing, removes a printer from the system, and makes print files into hold files. SP-OPEN Opens a single print file for several consecutive print requests. SP-STATUS Lists current status of all system printers. The Spooler 9-5 SP-TAPEOUT Copies the contents of a print file from tape to a print file on the Spooler. STOPPTR Stops one or more printers after the current print job, if any have finished printing. Summary of Spooler Features The following summarises the Spooler features: • It maintains up to 9999 print files on the queue. • It assigns up to 1000 form queues across the system. • A single print request can generate 999 copies. • It supports up to 1000 printers: this can be a mixture of parallel and serial printers, for example 800 serial and 200 parallel. Printer Administration The system administrator is responsible for system-wide tasks such as installing new printers and adding them to the system configuration. These tasks allow the Spooler to operate efficiently for all users. The administrator generally controls: • Installing and configuring printers. • Restarting inoperative printers. • Removing printers from the system. • Inspecting status of printer and the Spooler print queue. This section, reviews these tasks in brief. This should familiarise you with the operation of the Spooler and the configuration of system printers. For a more detailed description of printer installation and startup, refer to the UniVision System Administration Guide. Starting the Spooler st The UniVision Spooler process starts automatically when the 1 user logs in to the UniVision environment. In addition, you can restart the SS process by using :STARTPOOLER without having to log everyone out of UniVision. For printers to work in UniVision you must have set the printer up in the operating system. The remainder of this section is an outline of specific UniVision spooler commands. For detailed information on setting up printers in the operating system, refer to the manuals that came with the operating system software. 9-6 A Guide to the UniVision System For more information on setting up printers for use with UniVision, refer to the UniVision System Administration Guide. Configuring Printers (STARTPTR) STARTPTR initiates or restarts a system printer. In addition, you can use STARTPTR to assign form queue to a printer and to specify the following printer information: the number of pages the printer is to skip between print files, the type of printer, and the number of the assigned process for the printer. The syntax for STARTPTR is as follows: STARTPTR printer[,form,skip,type-process, [options]] printer number of the printer, can be any number from 0 to 999. You must enter a printer number. form form queue number, can be any number from 0 to 9999. You require the form queue number when initialising a printer. skip number of pages to skip between print files, can be from 0 to 9 pages. type-process specifies two things: the printer type and the process number assigned to the printer. Do not separate type and process with a comma. The type can be P (parallel) or S (serial). The process number can be any valid line (process) number for serial printers, or the physical device number (0, 1, 2, etc.) for parallel printers. You must enter parameters in the exact order shown, separated by commas where indicated. options The Spooler can be any of the following: A begins the alignment process. There must be a print job waiting in the queue in order for the alignment process to work. S specifies that the printer is to ignore the form-feed command at the beginning of a print file. Use this option when you have set skip to a number other than zero. Not available with parallel printers. U starts external spooler. 9-7 Initialising a Serial Printer >STARTPTR 1, 1, 0, S8 Shows how to use STARTPTR to initialise a serial printer. The system assigns Printer 1 to form queue 1, skipping 0 pages between print files, and it is a serial printer assigned to process 8. If you attempt to start a printer not defined in Uvsetup, for instance. >STARTPTR 0,0,0,S4 The system displays the following message: UniVision process #4 is being used by a VDU or is not available for use as a printer If you attempt to specify too many spool queues, for instance: >STARTPTR 0,(1,2,3,4) The system displays the following message: Too many UniVision Print Files Initialising a Parallel Printer >STARTPTR 1,1,0,P1 The UniVision printer control block has been initialised. Check that there is paper in the printer, and the current lpi is set. >SP-ASSIGN F1 >PRINTRONIX 66 Entry #nn Shows how to use STARTPTR to initialise a parallel printer. The system assigns printer 1 to form queue 1, skipping 0 pages between print files, and it is a parallel printer assign to process 1. Changing a Printer’s Form Queue >STARTPTR 1,(1,5,6) Shows how to assign multiple form queues to a printer already started. 9-8 A Guide to the UniVision System The system assigns printer 1 form queues 1, 5, and 6. The system print jobs in the order specified by STARTPTR. In the example, the system prints any jobs in forms queue 1 first, followed by any jobs in forms queue 5, and finally any jobs in forms queue 6. Restarting a Stopped Printer Restarting a stopped printer is the simplest form of STARTPTR. Use this form of STARTPTR to restart a prints after a stop. All other processes remain unchanged. >STARTPTR 1 To see the configurations for printers, use LISTPTR, described later. Restarting a Failed Printer You use SP-ENABLE to restart a UniVision printer and re-enable UNIX printers after you have encountered a UNIX printer or spooler failure. ! Note: You cannot use SP-ENABLE until you resolve all your UNIX printer or spooler problems. Checking the Status of Printers (LISTPTR) You use LISTPTR to obtain information about printers. For each printer the report lists: • Printer type. • Form queues assigned. • Number of blank pages skipped between print jobs. • The device number (if a parallel printer) or the number of the line attached to the printer (if a serial printer). • The current status of the printer, ACTIVE, INACTIVE, STOPPED ACTIVE, STOPPED INACTIVE, DISABLED or UNALLOCATED. The syntax is: LISTPTR [n[-m]][options] n number of the printer. n-m range of printer numbers. options can be one of the following. You do not need parentheses: B The Spooler lists information about all printer control blocks, whether allocated or not. 9-9 N suppresses automatic paging. P sends output to the printer. U displays the UNIX printer name, and if the system has set the 'suppress initial form feed' option of STARTPTR it displays a (s next to the Page Skip setting. LISTPTR produces a report that looks like this: UniVision Printer Assignments Printer Type Number Output Queues PARALLEL PARALLEL SERIAL SERIAL SERIAL SERIAL SERIAL 0 2 3 4 5 6 7 16:25:34 Page Skip Dev Or Process # 0 0 1 1 1 1 1 0 2 8 70 63 53 13 0 1 3 7 8 4 7 8 5 6 2 Status ACTIVE INACTIVE ACTIVE ACTIVE ACTIVE ACTIVE ACTIVE The report generated lists the following information: Printer Type PARALLEL or SERIAL. number of the printer. Used by STARTPTR, STOPPTR, and Number SP-KILL. Output Queues form queues attached to the printer currently. Page Skip number of pages you want to skip between each print job. Dev or Process# number of the process attached to the printer, or the parallel printer device number. Status ACTIVE, INACTIVE, DISABLED. STOPPED, UNALLOCATED, or LISTPTR with a U option produces a report such as the following: UniVision Printer Assignments Number 3 Printer Uvepson Output Queues 3 16:41:16 Page Skip Dev Or Process # Status 1 (s 8 ACTIVE > 9-10 A Guide to the UniVision System LISTPTR with the B option produces a report such as the following: UniVision Printer Assignments Printer Type Output Queues Number PARALLEL SERIAL PARALLEL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL SERIAL 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16:35:54 Page Skip Dev or Status Process # 0 0 0 1 3 7 8 4 7 8 5 6 2 0 1 1 1 1 1 1 8 70 63 53 13 ACTIVE UNALLOCATED INACTIVE ACTIVE ACTIVE ACTIVE ACTIVE ACTIVE UNALLOCATED UNALLOCATED UNALLOCATED UNALLOCATED UNALLOCATED UNALLOCATED UNALLOCATED UNALLOCATED > Stopping Printers (STOPPTR) The printer has several states: ACTIVE The printer is currently printing a job. INACTIVE The printer is available for printing. STOPPED The printer has stopped in UniVision and does not send print jobs to the operating system. UNALLOCATED You have deleted a printer defined previously in the operating system. DISABLED The operating system has disabled the printer. This printer does not accept print jobs. STOPPTR stops one or more printers after the current print jobs, if any, have finished printing. STOPPTR requires SYS2 privileges as it affects a system resource available to all users. Usually you stop a printer prior to removing the printer from the system, since STOPPTR allows the current print job to finish first. The syntax is: STOPPTR [n[-m]][B][W] The Spooler 9-11 n number of the printer you want to stop. If you do not specify a printer, the system stops printer number 0. n-m range of printers you want to stop. B stops all printers. W causes the process to wait until the printer is inactive before it returns the terminal to the UCL prompt, EXECUTE or Proc. Stopping a printer tells the Spooler that the printer is off-line. If you stop a printer successfully, the system displays the following message: Printer #n Changed to Stop And Is Inactive where n is the printer number. If the printer is still printing, the system displays the following message: Printer #n Changed to Stop But Is Still Active. Once the current file has finished printing, the printer becomes inactive The W option is useful when you are using certain Procs to handle the Spooler. For example, since STARTPTR does not work if the printer is still active, you should always use STOPPTR with the W option before using STARTPTR to ensure that the printer is inactive before the process returns to the Proc. Once the printer is inactive, it is safe to remove it from the system using SP-KILL with the D option. You require SYS2 privileges to use this option. You can use SP-KILL to remove a printer no matter what state it is in. However, recommended practice is, to remove the printer only when it is inactive. The following example, removes system Printer 1 from the system. >STOPPTR 1 Printer #1 Changed to Stop And is Inactive >LISTPTR 1 UniVision Printer Assignments Printer Type Number Output Queues SERIAL 1 0 11:10:09 Page Skip 1 Dev or Status Process # 10 INACTIVE >SP-KILL D1 Serial Printer #1 Has been deleted for UniVision The message indicates SP-KILL has removed a serial printer. Use STARTPTR, to restart the printer. 9-12 A Guide to the UniVision System Assigning Spooler Specifications (SP-ASSIGN) SP-ASSIGN directs and controls output sent to the Spooler and to assign a form queue to a process. SP-ASSIGN determines what the current spooler assignments are and specifies the number of copies you want to print, print job priority and the destination of the print job. The syntax is: SP-ASSIGN [options] options can be any combination of the following, details about each option follow the list: ? displays current SP-ASSIGNments. n assigns number of copies you want to print, You can assign up to 999 copies. A prints jobs on the Auxiliary port of the terminal. B prints a print banner at the beginning of each print. C chokes printer output to the speed of the printer. You must use the C option with the I option. Ignored by UniVision. Fform assigns a specified form queue to user's process, any number from 0 to 125. H saves output as hold file. I specifies immediate printing that is puts file to front of queue. O keeps print files open, allowing multiple print requests to be processed as one print job. Rpfile reassigns print file generated by UniVision BASIC PRINT ON statements. S suppresses printing of a print job. Normally used with the H option. T sends output to the tape device. You require SYS1 privileges to use this option. You do not need to enclose options in parentheses, can enter them in any order, and need not separate them with spaces or commas. When you install the system initially, it sends all printer output, by default, to form queue 0 and sets the number of copies to print to 1. To see a list of current SP-ASSIGNments for all processes, use LISTABS. The Spooler 9-13 Users can change their queue assignments and output specifications for their own processes at any time with SP-ASSIGN. Any changes made remain in effect until the user logs to another account or logs off. To reset the SP-ASSIGNments to the original default options, use SP-ASSIGN with no options. In addition, you can place SP-ASSIGN in a Logon Proc for the account. This ensures that the system establishes the assignment each time the user logs on. This is necessary only if you want to maintain a form queue assignment other than the default. Listing the Assignments Status (?) The ? option displays the current status of SP-ASSIGN for the user's process. The report is similar to the following: >SP-ASSIGN ? Process Status 0012 P Cop ies UniVision Form Queue# 1 0 > Status codes that correspond to SP-ASSIGN options can be any of the following: H Output to a hold file. I Print immediately, that is, put file to front of queue. O Keep print file open. P Output to the printer. T Output to tape. Selecting the Number of Copies (n) The n option assigns the number of copies you want to print. If you do not specify n, the system prints one copy. When you assign multiple copies, the system does not release the print file until it has printed the last copy. If you use the T, tape, option, the system ignores the n option. The following example assigns the number of copies you want to print to 20: >SP-ASSIGN 20 Process Status Cop ies 0012 P 20 UniVision Form Queue# 0 > 9-14 A Guide to the UniVision System Print to Auxiliary Port (A) The A option allows a UniVision process to send its print jobs to the Auxiliary port of the terminal. It is possible to combine this option with the S, T and H options of SP-ASSIGN. Print Banner (B) The B option prints a banner at the beginning of each print file. It is possible to customise the banner, defined in the ERRMSG file in an item called PRINTBANNER. Form Queue (F) The Form option assigns a form queue to the user's process. When you install the system initially, all processes have form queue 0 assigned to them. When users change their form queues, these assignments remain until you change them explicitly using SP-ASSIGN, or until the user logs to another account or logs off. If you send output to a tape device, the system ignores the F option. >SP-ASSIGN F3 Process Status Cop ies 0012 P 1 UniVision Form Queue# 3 > Destination Options (H, S, T) The H option creates a hold file. If you use the H option with the S option, the system creates a hold file but sends nothing to the printer. The H option is useful when you want to save print jobs until it is more convenient to print them, or when the system administrator needs to change the type of paper in the printer. >SP-ASSIGN HS3 Process Status Cop ies 0012 H 3 UniVision Form Queue# 0 > Saves the print job as a hold file; the S option prevents the print job from being sent to the printer. When you remove the hold, the system sends the print job to an available printer assigned to form queue 0. The system prints three copies. The Spooler 9-15 If you use the T option without the S (suppress printing) option, the system sends the output to a tape device as well as to the printer. The system sends output to the tape wherever the current position is. The tape-unit does not rewind automatically, so you can send print files to the tape one after another. You require SYS1 privileges to use this option. ! Note: Ensure that you have a tape drive attached, T-ATT, and have the proper tape-unit selected, T-SELECT. If you use the T option with the S option, the system sends output to the tape device, but sends nothing to the printer. If you use the T option with both the S and H option, the system sends output to the tape device and creates a hold file, but sends nothing to the printer. The S option suppresses printing and normally you use it with the T, tape, and H, hold file, options. When you use the S option, the system does not enqueue the print file for printing. >SP-ASSIGN TS BLOCK SIZE: 500 Process Status Cop ies 0012 T 1 UniVision Form Queue# 0 > Directs output directly to tape, by-passing the Spooler, the S option suppresses printing, and displays the current SP-ASSIGNments. Selecting Job Priority (I) The I option starts the print job as soon as possible. This option assigns a higher priority to the job, causing the system to process it before other jobs. When you use the I option, the Spooler finishes any jobs currently active, before it ‘immediately’ processes the requested job. The system processes I-jobs in the order in which you enter them. If you use the T, tape, the H, hold file, or the S, suppress printing options, the system ignores the I option. The following example assigns form queue 1 to process 12 and specifies that the system should handle subsequent print jobs immediately, once the printer is free. >SP-ASSIGN F1I Process Status Cop ies 0012 PI 1 UniVision Form Queue# 1 > 9-16 A Guide to the UniVision System Open Option (O) The O option keeps a print file open until you close it explicitly. The O option is useful when you want to collect output from multiple print requests and print it as a single print job. The system prevents all other print jobs from printing until you close the print file, however, it continues to spool the print jobs. Remember to close the O option setting after you use it, by re-executing SP-ASSIGN without the O option. In addition, using SP-CLOSE or logging off closes an open print file. >SP-ASSIGN HSF20 Process Status Cop ies 0012 H O 1 UniVision Form Queue# 2 >SORT ORDERS WITH DATE >= "05/01/95" AND DATE <= "05/31/95" (P) HOLD ENTRY #24 >SORT ORDERS WITH DATE >= "06/01/95" AND DATE <= "06/30/95" (P) >SORT ORDERS WITH DATE >= "07/01/95" AND DATE <= "07/31/95" (P) >SP-ASSIGN HSF2 [1140] Your Open UniVision Spooler Files Were closed Process Status Cop ies 0012 H 1 UniVision Form Queue# 2 > Creates a hold file using form queue 2, leaves the print job open and displays the current SP-ASSIGNments. The system sends several print requests, and you close the print job by re-issuing SP-ASSIGN without the O option. Reassigning Print Files (R) You use the R (Reassign) option in conjunction with PRINT ON pfile in a UniVision BASIC program. This option reassigns the print files generated by a PRINT ON. Use R together with other SP-ASSIGN options to customise the SPASSIGN options for the reassigned print file. They do not change any of the current SP-ASSIGNments, nor do they affect the options assigned to any other reassigned print file by the R option. The Spooler 9-17 >SP-ASSIGN F3HR3? Process Status Cop ies 0012 H 10 UniVision Form Queue# 3 > Allows the system to generate a print job by a PRINT or PRINT ON 3 in a UniVision BASIC program. The system makes the print job into a hold file, prints a single copy using form queue 3, and displays the current SP-ASSIGNments Checking the Print Queue Use LISTPEQS when you require information about print jobs and hold files currently by the Spooler. The syntax is: LISTPEQS [n[-m]] [account] [options] n number of print file. n-m range of print file numbers. account displays all print files generated by the specified account. You must enclose the account name in single or double quotes. You require SYS2 privileges to use this option. options can be any of the following: A lists only those print files generated by the current logon account. C lists only the total number of print files and the total amount of space they use. E lists the UNIX filename of the specified print files. F lists print jobs in order, firstly by form queue, then by the order in which the system lists them. The system does not list hold files. L lists obsolete print files already deleted, in addition to active print files. P sends the report to the printer If you do not specify any options, the system lists the status of all print files. LISTPEQS produces a report similar to the following: 9-18 A Guide to the UniVision System PRINTER LIST ELEMENTS # LK 1 2 3 4 5 6 7 8 9 10 11 12 13:49:17 14 JUL 1993 LN STATUSES CP FO SIZE DATE TIME ACCT 11 1 5 0 5 5 11 11 11 11 11 11 HP C HP C H C HP CR H C P C H C HP C R HP C XR HP C H L HP C XR 1 1 1 1 3 1 3 1 5 1 3 1 4 4 0 0 0 0 0 0 1 4 0 0 261 575 37 81 4 OPEN 1 30 21 420 OPEN 19 06/22/88 06/23/88 07/13/88 07/13/88 07/14/88 07/14/88 07/14/88 07/14/88 07/14/88 07/14/88 07/14/88 07/14/88 11:54:34 10:37:09 12:46:00 14:12:28 13:14:49 13:17:48 13:21:00 13:24:10 13:26:18 13:27:15 13:29:52 13:30:03 TSB TSB MANUALS SYSPROG DP MANUALS DP SYSPROG DP TSB DP CAROL 12 QUEUE ELEMENTS 1449 BYTES USED > All jobs except for entry 6 are hold files. These hold files remain on the Spooler even after the system has printed the jobs. The system has not scheduled entries 3, 5, and 7 for printing currently. Entries 6 and 11 are both open print jobs, which means they are locked files that are not accessible by SP-EDIT. Once you close these files, however, you can use SP-EDIT on these files. SP-EDIT has edited entries 4, 8, 9, and 12. Of these four entries, the system has only spooled 4 and 8 completely to the printer; it has cancelled entries 9 and 12 during output by SPKILL. The report contains the following information: # print file number, sometimes called the entry number. LK forward link, showing the sequences in which the system prints the jobs. Only shown if it is non-zero. LN number of the line, process, on which the system generated the print file or of the hold file being edited. STATUSES status of the print file. For details on status codes see below. CP number of copies. FO number of the UniVision form queue. SIZE number of bytes of a closed print file; the system displays the word OPEN if the print file is open. DATE date when the system queued the print file. TIME time when the system queued the print file. ACCT name of the account that generated the print file. The Spooler 9-19 The codes in the STATUSES column indicate the following: Destination G Print file is the alignment segment of another print file. When you use the A option of STARTPTR, the system generates a special print file used only for aligning the printer. H File is a hold file. The system creates hold files because of their SP-ASSIGNments; because the F option of SP-KILL dequeues them; or because a cold start has occurred. I Print the print file immediately, specified by SP-ASSIGN with the I option. P The system is to send the print file to the printer. T The system is to send the print file to the tape drive. Open, Spooled, or Currently Being Printed N The system generated a print file under an SP-OPEN condition. Open files are not available to SP-EDIT. S The system has spooled the print file to a form queue using SP-EDIT. Such spooled files are no longer available to SPEDIT. O The system is printing the print file currently. Files being printed currently are not available to SP-EDIT. L The system has locked the print file. The system locks file when they are available, open, spooled, being printed, or being edited. Locked files are not available to SP-EDIT. Closed or Edited C Print file is closed. If C does not appear, the print file is being printed currently or in an SP-OPEN condition. R The system has edited the print file and sent it to the printer. Cancelled X 9-20 The system killed the print file using SP-KILL. A Guide to the UniVision System A Printer control block is available for re-use. The system does not create any new control blocks for print files until it has re-used the existing ones. The system encloses all other status codes for these obsolete print files in parentheses. Files in available control blocks are not accessible to SPEDIT. LISTPEQS has several options that allow you to show hold files only (H), show entries for your account (A) and sort pending jobs by form queue (F). Refer to the UniVision Command Reference Guide for more information. Cancelling Print Jobs SP-KILL has many uses, some of which should be limited to the administrator. Use SP-KILL to stop a current print job from printing or to turn print files into hold files. As mentioned earlier in the section Spooler Administration, you use SP-KILL to remove a printer from the system. Cancelling an Active Print Job SP-KILL used with a printer number cancels a print job being printed currently: SP-KILL n[-m] [A][B][N][O] n is the printer number, and you must specify at least one printer number When you use SP-KILL to cancel a job printing currently, the Spooler stops sending data to the printer immediately. However, the printer continues printing whatever still remains in the print buffer before it stops. If you do not use the N option, the system prints the print the ABORT message on the next line after the point where it cancelled the report. If you use the A option, the system cancels all print files created on the current logged on account if they are being printed currently. If you use the B option, the system cancels all print file being printed currently. You require SYS2 privileges to use this option. If you use the O option, the system cancels the report being printed currently and makes the print file into a hold file. >SP-KILL 3 Cancels the print job going to printer 3. The system prints the message ABORT! on the page at the point where the cancellation takes effect: >SP-KILL 3N The Spooler 9-21 Cancels the print job going to printer 3, but the N option suppresses the ABORT message. >SP-KILL 3-5 Cancels print jobs going to Printers 3, 4, and 5: Exactly when an active print job stops depends on how large a buffer the printer has and how much data the system was able to send it before it received the abort message. Killing a print job does not stop the printer; it simply tells the system to stop sending data from that print file to the printer. As soon as the printer buffer empties, the printer stops printing the current job and begins to print the next job in its queue. The system delete the cancelled print file from the print queue if it is not a hold file. Retaining Print Files as Hold Files SP-KILL used with the F option removes print files from the queue and turns them into hold files: SP-KILL Fn [-m] [A][B][O] where n-m is the number or range of numbers of entries in the form queue. You must specify at least one print file with the F option. Use LISTPEQS to list the print files. When you remove a print file from the queue, it becomes a hold file, which is available for further processing by SP-EDIT. The F option does not remove a print file from the queue and make it a hold file if the file is being printed currently. If you use the A option, the system removes all print files created on the current logged on account from the queue. If you use the B option the system removes all print files from the queue. >SP-KILL F5 Removes print file 5 from the queue and makes it a hold file. >SP-KILL F5-9A Removes any print files from 5 to 9 generated from the current logged on account and makes them hold files. Removing Printer from the System SP-KILL used with the D option removes printers from the system: SP-KILL Dn[B] 9-22 A Guide to the UniVision System You must specify at least one printer number with the D option. It is not a good idea to remove a printer from the system while it is running. If you want to remove an active printer, first stop the printer using STOPPTR, and use SP-KILL n, to cancel the current print job, if there is one, and remove the printer. When you remove a parallel printer, it becomes inactive. When you remove a serial printer, the attached line, process, becomes a normal communications line. If you use the B option together with the D option, the system removes all printers. Removing Printers >SP-KILL D1 SERIAL PRINTER #1 HAS BEEN DELETED, AND ITS PROCESS SET TO LOGON Removes printer 1 from the system. >SP-KILL D3-5 Removes printers 3,5 and 5. >SP-KILL DB Removes all printers from the system. Manipulating Hold Files The print queue consists of two types of file: print files and hold files. SP-EDIT manipulates Spooler hold files. SP-EDIT can: • display and print all or part of any hold file. • redirect a hold file to another printer or to a tape device. • convert a hold file into data file items. • delete one or more hold files from the Spooler. If you invoke SP-EDIT without any arguments, it selects all the hold files generated from your own account. A set of command line options allow you to select hold files by number, by account, or by form queue. For each of the selected hold files, SP-EDIT prompts you for the appropriate action to take. There are actually four prompts that SP-EDIT uses to prompt for input. These following summarises the prompts in the order in which you generally encounter them: The Spooler 9-23 DISPLAY Display the first 500 characters of the hold file. STRING Specifies that printing of a hold file start at first line matching a string. SPOOL Spools the hold file for printing, displays the file on the screen, or converts the file to a data file items. DELETE Delete the hold file. Figure 9-3 summarises the responses at each prompt and how you can move from one prompt to the next. In addition, a group of command line options exist that avoid the prompting sequence and allow you to invoke SP-EDIT to perform a specific function. 9-24 A Guide to the UniVision System DISPLAY Y Displays first part of file and prompt for STRING N Skip to STRING prompt S Skip to SPOOL prompt D Skip to DELETE prompt X Exit SP-EDIT Return Skips to next hold file, if any String Move to first line containing STRING if not found, prompt again STRING Return Skip to SPOOL prompt Y Release hold for printing or for tape drive N or SPOOL Return Skip to DELETE prompt T Displays entire hold file on screen F Converts hold file to data file item Y Delete hold file DELETE N or Return Select next hold file Figure 9-3. SP-EDIT prompts and responses The Spooler 9-25 ! Note: The responses to the SP-EDIT prompts must be in uppercase. The system ignores any response in lower-case. Viewing the Contents of a Hold File When you enter SP-EDIT, the system displays the following prompts: >SP-EDIT UniVision Spooler Entry # nnn DISPLAY (Y/N/S/D/X(CR))?- nnn is the number of the 1st hold file selected. the prompt allows you to display the first 500 characters of the hold file. If you want to display the entire hold file, skip to the Spool prompt and enter T or TN. Responding to the ‘Display’ Prompt At the Display prompt, enter one of the following: Y displays the file. N skips to the String prompt. S skips to the Spool prompt. D skips to the Delete prompt. X exits SP-EDIT and returns to the UCL prompt. <RETURN> skips to the next hold file, or if there are no more selected, to the calling process, the UCL prompt, a Proc, or a UniVision BASIC program. Any other response skips to the String prompt. When you select Y the system displays the first 500 character of the hold file. If the 500 characters appear in the middle of a line, the system displays the remaining character in the last line, and displays the String prompt. If the system is printing the hold file you want to displays currently, use the O option of SP-EDIT to displays it. If you do not use the O option, the system displays the following message. ENTRY # n IS NOT AVAILABLE and the process continues to the selected hold file or, if there are none, to the UCL prompt. To proceed to the next file, press <RETURN> at the NEXT? prompt. If you included the L option when you entered SP-EDIT initially, only three responses to the Display prompt are possible. 9-26 A Guide to the UniVision System <RETURN> skips to the next hold file. X exits SP-EDIT and returns to the UCL prompt. other any other response displays the beginning of all hold files that are not being printed currently. Responding to the ‘String’ Prompt The String prompt looks like this: STRING:- The String prompt allows you to start printing a hold file from any line in the file. You can identify the line by specifying a unique string of character contained in the line from which you want to start. One of two responses is possible here: entering a character string, or skipping to st the Spool prompt. To move to the 1 occurrence of a character string in the hold file, enter the character string at the prompt. If the system finds the string, SPEDIT moves the beginning-of-report address to the line containing the character string, and displays the Spool prompt. If the system does not find the string it displays the following message. STRING NOT FOUND STRING:- and you can try again. To skip the String prompt altogether, press <RETURN>. The system displays the Spool prompt. Responding to the ‘Spool’ Prompt The Spool prompt allows you to spool the hold file for printing, print the file on your screen, or convert the file to a data file. The Spool prompt looks like this: SPOOL (Y/N=CR/T/TN/F)?- Enter one of the following: Y releases the hold file for printing or sends it directly to a tape device, depending on the currently active options. N skips to the Delete prompt. <RETURN> skips to the Delete prompt. T displays the entire hold file on the screen. The Spooler 9-27 displays the entire hold file on the screen and suppresses automatic paging. TN converts the hold file to a data file item, or series of items, in F RUNOFF format. The following sections describe each of these responses in detail. Spooling a Hold File If you select Y and the system cannot spool the hold file, it displays the following message: Your specification is not output Reassign your process if you want to output a Hold file END OF PRINT FILE CONTROL BLOCK and the system returns you to the UCL prompt. You can modify the SPASSIGNments to allow spooling of the file, and re-enter SP-EDIT to spool the file. Printing a Hold File on the Screen If you select T to display the entire contents of the file on your screen, the system st displays the 1 page. You can enter any of the following: U repeats the current page. T causes output to start from the top. X exits the displayed page and return you to the Spool prompt. Any other character displays the next page. These three option are not available if you use the TN option. Converting a Hold File to a Data File If you use the F option , the following prompt appears: FILE NAME:- Enter the name of the data file to which you want to transfer the hold file, and the following prompt appears: INITIAL ITEM:- Enter the name of the item. ! Note: 9-28 If the item exists, this option overwrites it. A Guide to the UniVision System The system converts the hold file into an item in the file you specified. If you include the V option when you enter SP-EDIT initially, the system retains all trailing blank lines in the data item. Responding to the ‘Delete’ Prompt The Delete prompt allows you to delete a file from the Spooler. You must make a print file into a hold file before you can delete it. The Delete prompt looks like this: DELETE (Y/N=CR? Enter Y to delete the specified hold file. Enter N to skip to the next specified hold file. Selecting Hold Files The section shows some of the ways to select a file you want to edit. Normally SP-EDIT selects the hold files associated with an account. It is possible to select, all hold files system wide, or hold file in the account assigned to a particular form queue. The U option selects all available hold files, whether generated by the current account logged on or not. >SP-EDIT U UniVision Spooler Entry #1 DISPLAY (Y/N/S/D/X/(CR))? The system displays a prompt for each selected hold file unless you enter X to exit at Display prompt. You can specify hold file generated in another account by specifying the name of the account enclosed in quotes. The following example selects all hold file generated in the SALES account: >SP-EDIT ‘SALES’ The Fn option restricts selection to a form queue n, or to a range of form queues, n-m. The following example selects all hold file generated on the current account sent to form queue 1. >SP-EDIT F1 It is possible to combine these option. For instance, UF1 selects all files systemwide sent to form queue 1. The Spooler 9-29 Spooling and Deleting Multiple Hold Files You use the MS and MD options to avoid being prompted for each of the selected hold files individually. The MS option spools all selected print files to the form queue specified originally. The MD option deletes all selected print file. The following example sends all hold file created by the account SALES to form queue 4. >SP-EDIT F4MS ‘SALES’ The next example deletes all hold file created on any account sent to form queues 1 or 2. >SP-EDIT UF1-2MD Modifying Spooler Records The UniVision administrator can use SP-COPIES to modify a spooler record for a specific spooler entry. It syntax is: SP-COPIES entry copies entry is the number of the spooler entry you want to modify and copies is the number of copies you want the Spooler record to have. SP-COPIES 4 3 Modifies Spooler entry 4 to have 3 copies. Using the Spooler with Tape Drives It is not possible to share a tape drive. Before you can direct any output to tape, you must attach the tape drive using T-ATT. No other users can access the tape drive while you have it attached. SP-ASSIGN with the T option specifies that a tape drive services the output queue. In addition, this option attaches the tape drive. The system sends output to the tape at the current position. The tape unit does not rewind automatically, so you can send print files to the tape one after another. The following sets of options modify how the Spooler handles each subsequent print job: 9-30 A Guide to the UniVision System T Send output to tape drive as well as the printer. TS Send output to tape but not to the printer. THS Send output to tape and retain as a hold file but do not print the job. The following example directs output directly to tape, by-passing the Spooler (the S option suppresses printing). >SP-ASSIGN TS DEVICE ATTACHED BLOCK SIZE: 16896 Process Status Cop ies 0012 T 1 UniVision Form Queue# 0 Sending a Hold File to Tape It is possible to send hold files to tape using SP-EDIT with the T option. SP-EDIT writes to tape using the default block size. Do not change the block size between requests without writing a new tape label. You can use the following SP-EDIT options with the T option: H Suppress tape label. W Wait for tape drive to become available. Without this option, the request fails if the tape drive is not available. MS Sends selected hold files to tape without prompting individually for confirmation. The next example sends all hold files between numbers 7 and 11 generated on the logged on account, to tape: >SP-EDIT 7-11 TS Copying a Print File from Tape SP-TAPEOUT copies the contents of a print file from tape and places an entry for it in the print queue. The Spooler processes the file according to the SPASSIGNments set currently. SP-TAPEOUT has a number of options that specify the formatting of data: The Spooler 9-31 A converts data in EBCDIC format on the tape to ASCII format, and transfers the data to the Spooler print file. U converts alphabetic characters from lower-case to uppercase, then transfers the data to the Spooler print file. SP-TAPEOUT executes T-ATT and transfers the contents of a print file to the Spooler. It does this by having the Spooler create a print file and transferring the print file from tape to the print file on disk. The system prints the file in accordance with the current SP-ASSIGNment. Using Procs for Printer and Tape Control It is possible to control the Spooler system to some extent from a Proc (refer to the UniVision PROC Reference Guide for detailed information on the PROC processor). A Proc can use information in the secondary input buffer supplied by the ERRMSG processor and by the Spooler. All verbs that use the ERRMSG file place error message numbers as well. Sources other that the ERRMSG processor can supply the following information to a Proc: the entry number for each print file when initialised, data on the condition of the printers, and tape attachment conditions for any process attempting to attach a tape drive. You can inspect data in the secondary input buffer or transfer it to one of the output buffers. You lose this data after the execution of a PROC P command. If you expect particular pieces of information, you can define conditional statements that perform some action on encountering the specified information. The main uses of a Proc include: hold file retention, tape control, and printer control. Hold File Retention If you execute an SP-ASSIGN H from a Proc, it leaves a mark with the print file number in the secondary input buffer at the time when the system displays ENTRY#. The mark is the ERRMSG number [1099]. If the process generates the message: HOLD ENTRY #17 and the PROC secondary input buffer contains: 1099 17 In addition, it contains any other error message numbers generated during execution of the verb. In the following example, a portion of a Proc retrieves a hold file entry number for a succeeding SP-EDIT. 9-32 A Guide to the UniVision System PROC Command Explanation P SS B 5 IF # A G 99 IF A1 = 1099 G 15 F G5 15 F IF A # (ON) G 98 HSP-EDIT A Execute the verb. Set the buffer pointer to the secondary input buffer. Backup input pointer. End of buffer, entry not found. Test for mark. Advance the pointer to the next argument. Test the next parameter. Advance the pointer to the print file number. Absent or spurious data. SP-EDIT the print file. Move the print file number to the primary output buffer. Turn on the stack for the prompts, as necessary. Answer S to DISPLAY prompt. Answer Y to the SPOOL prompt. Process the SP-EDIT. Normal exit. Exit with error message. Exit with error message. STON HS<< HY<< P X DONE 98 XBAD DATA 99 XON DATA Tape Control Because it is not possible to share a tape drive, it is important to ensure that it is available before you run any sequence of processes involving the tape drive under PROC control. Procs cannot mount tapes or continue when the tape is inoperative. The ERRMSG file contains the tape control error message numbers (90 to 99). Certain tape difficulties are not amenable to PROC control because they interrupt the process and speak only to the operator of the terminal. In these cases only user intervention can correct the problem. Each time you use the tape, it is advisable to attach it specifically using T-ATT. If the tape is available or already attached, TATT places 90 nnnn into the PROC secondary input buffer. Message [90] is a mark that specifies that the system has attached the tape, and nnnn is the tape block size. It is advisable to use an explicit block size with T-ATT, because there might be times when the prior state of the process is unacceptable. If the tape is not available, T-ATT inputs 95 nn into the PROC secondary input buffer, where 95 is a mark indicating the tape is not available, and the string nn is the number of the line the attached to the tape. The following example uses SP-EDIT in a Proc that spools all selected print files to tape automatically. The Spooler 9-33 PROC Command Explanation P SS B 5 IF # A XXNO DATA IF A1 = 1099 G 15 X NO PRINT JOB 15 F IF A # (ON) X BAD DATA HSP-EDIT A HMSTW PP Execute the verb. Get the print file entry number Put SP-EDIT entry. Move the number Wait until the tape is available. This Proc yields SP-EDIT in MSTW. Spooler Verb Input Conventions Normally, you enter spooler verbs in free-form. There are input conventions that you must follow, however, when you change this format. When you enter verbs, the options, either individually or as a group, you might not have enclosed them in parentheses. Often you only require a single left parenthesis. In the example below, A, B, and C represent Spooler options. > > > > > > VERB VERB VERB VERB VERB VERB ABC (ABC) AN(C (A)B(C) (ABC A,B,C If you place a number in an option string containing parentheses, the number must precede the parenthesis or all of the options must be in parentheses. If you do not use parentheses, the option can be in any order. > > > > VERB VERB VERB VERB A B 3 C 3ABC 3 A (BC (3ABC If you use a pair of numbers to create a range, they must have the exact form n-m. st If you enter the pair in any other form, the Spooler ignores the 1 number and retains the last number as a single parameter. 9-34 A Guide to the UniVision System > VERB ABC 2-3 > VERB 2-3 (ABC > VERB (ABC2-3 If you enter more than one number, or more than one pair of numbers, in the same option string, the system only retains the last number or pair of numbers entered. > VERB 2 ABC 3 > VERB 2-3 ABC 6 > VERB 2-3 ABC 4-5 implies > implies > implies > VERB 3 ABC VERB 6 ABC VERB 4-5 ABC When you use the 'account-name' parameter in an option string, you must surround it with single or double quotes. When you use the 'account-name' parameter with other options and use parentheses, 'account-name' must precede all other options, and the other options must be in parentheses. If you do not use parentheses, the options, including 'account-name', can be in any order. The system only accepts one 'account-name' parameter in an option string. > VERB ABC 3 'ACCOUNT-NAME > VERB 'ACCOUNT-NAME' (ABC2-3) > VERB 'ACCOUNT-NAME' (ABC 2-3) The Spooler 9-35 Section 10 USING MAGNETIC TAPE This Section covers the commands for writing and reading magnetic tapes. It contains a tutorial for new users that introduces the fundamental commands, and guides the user step-by-step through the process of creating a tape. In addition, it describes how the system organises data on tape and introduces frequently used terms. Subsequent sections describe various functions typically performed using a tape drive in the UniVision environment. Overview of UniVision Tape Operations UniVision supports many different tape devices. The general rule is if the tape, or tape like, device works in the operating system, you can set up the device and it functions properly in the UniVision environment. Examples of such tape devices that function properly in UniVision include devices such as: • ½-inch tape drives. • ¼-inch tape drives. • 8mm tape drives. • 4mm DAT tape drives. Examples of tape-like devices include: • CD-ROM drives. • cartridge diskettes. Usually, you do not use tape like devices in the same way you would use a tape device. However, in the UniVision environment you can use these tape-like devices in the same way you would use a normal tape device. Throughout this Section system generating the examples has a quarter-inch cartridge tape as its default tape device. UniVision requires each tape device to have a logical tape unit number assigned as part of the installation of the UniVision environment. The system administrator performs these assignments using :INIT-TAPE. To setup any tape device for the first time you must use the B option. To re-initialise existing tape devices requires the I option. Using Magnetic Tape 10-1 ! Note: To add a new tape device to an existing system you must use the B intialise option, otherwise you do not see the new device in the UniVision environment. To change the default device number setup in :INIT-TAPE you must use SETTAPE. This allows you to re-order the tape devices so, for example, you can make the normal backup tape drive device 0. device 0 is the default tape device and the system attaches it automatically without the need to perform a T-SELECT before attaching a tape device. ! Note: It is not possible to attach a tape device if another user on the system is using it. For more information on setting up tape devices for use with UniVision, refer to the UniVision System Administration Guide. You must attach a tape device to your process before you can use it. Attaching the tape drive gives the user exclusive control of the tape device. T-ATT attaches the tape drive to the process issuing the command, if no other process or user is using the device. The tape drive remains attached to the process until the user logs off or detaches the unit by performing a T-DET. To select a tape device other than the default you must use T-SELECT and specify the device’s logical tape unit number. You can display a list of the available devices by performing a T-STATUS. In addition, T-STATUS displays the fact of whether another process has the tape device attached. A number of tape utility commands attach the tape drive automatically if you have not attached it already. However, it is a good idea to attach the tape drive as an explicit step when accessing a tape drive, examples of commands that attach the tape drive automatically include: 10-2 • T-ONLINE • T-REW • T-EOD • T-ERASE • T-RDLBL • T-WEOF • T-WTLBL • T-WHAT • T-READ • T-RET • T-SPACE A Guide to the UniVision System • T-DUMP • T-LOAD Tape commands use the tape drive attached currently. If you have not selected one the system uses the default device. T-SELECT allows you to select a tape device other than the default. It is possible to chain a series of tape devices together and select them for the same process. The chain should only include devices of the same type, that is, all half-inch tape drives or all quarter-inch tape drives. This allows continuous multist reel tape operation using all the selected drives in sequence. When the 1 tape drive in the series reaches the end of tape, the process rewinds the tape and begins writing to the next selected tape drive. The system instructs the operator to mount new tape media only when it reaches the end of the last tape on the last tape drive in the series. Writing and Reading Tape: A Tutorial There are a number of commands that handle tape operations. You use some frequently; others are more special-purpose and you use them in a particular set of circumstances. This tutorial demonstrates how simple it is to write data to tape and read files from tape. This tutorial has the following sections. • Accessing the tape drive. • Dumping a file to tape. • Restoring items from tape. • Appending data to tape. • Positioning the tape. Accessing the Tape Drive. In order to access a tape drive, you must attach a tape device. To see a list of available tape devices on a system performs a T-STATUS. This displays all the tape device defines currently in the UniVision environment. Included is the: • device number (LTU). • drive type. • process currently having the device attached, if any. • device description. • UNIX device name. Using Magnetic Tape 10-3 >T-STATUS LTU DRIVE 0 FO 1 D0 2 Q0 ATT FORMAT HIGH DENSITY LONG LABEL DEVICE DESCRIPTION High Density (1.44M) HPC1533A Drive UNIX DEVICE NAME /dev/rdsk/f03ht /dev/rmt/c0t4d0s0n /dev/rmt/c0t6d0s0n Before using a tape device you must attach it to your process. Use T-ATT to attach a tape drive. You cannot attach a tape drive attached to any other process. >T-ATT BLOCK SIZE: 16896 Once you have selected a device, you can use T-WHAT to display the type of tape device attached currently. Remember if you have not attached a tape device to your process, T-WHAT is one of those tape commands that attaches the default device automatically. >T-WHAT [6007] 1/4 inch cartridge unit LONG LABEL It is a good practice to always put a tape device on-line before performing a read or write to tape. One way to put a tape on-line is to use the switches or buttons on the device. Under software control, you can use T-ONLINE to put the tape device on-line. >T-ONLINE BLOCK SIZE: 16896 [6004] tape on line Sometimes it is necessary to retension quarter-inch, 8mm and 4mm DAT tapes. You should retension a tape after many uses where systems do not utilise the entire tape during a read or write pass. For example, a tape used once a week for a full file save where the system does not write to the entire tape during the backup is a good candidate for retension. >T-RET BLOCK SIZE: 16896 L 420 16:16:07 21 NOV 1996 A tape retension, fast-forwards to the end of the tape and rewinds. This action on the tape media allows the tape drive to correct any bumps in the actual media. You do not need to retension every time you use a tape. However, it is good practice to do a retension on a tape that has infrequent use or rarely used completely. 10-4 A Guide to the UniVision System Before you can write data to a disk, you must format the media. If you do not format the disk, any tape function writing to tape formats it automatically. You can use FORMAT in UniVision to perform a format. Formatting disks erases any data contained on the disk. >T-SELECT 1 [6037] Floppy device attached >FORMAT BLOCK SIZE: 500 > ! Note: Formatted diskettes available on the market come with a standard MS-DOS format. UNIX and AIX can usually read and write to MS-DOS formatted diskettes. However, on average it takes six times longer to write to a diskette with MS-DOS format. It is recommended you purchase unformatted diskettes and allow UniVision to format the diskettes properly automatically. In addition, you can use FORMAT to reformat MS-DOS formatted diskettes. If you ever require to transport data to an MSDOS based system via diskette, make sure you do not format the diskette on a UNIX or AIX-based system. Any verb that attaches the tape drive also reports the block size. This is the fixedlength block, or physical record, used to store and retrieve data. You can find a description of the block size, use the default at present, that is 16896 bytes for a quarter-inch cartridge tape. An important but rather obvious step is that a tape cartridge, reel or diskette must be located in the appropriate drive. For this tutorial it does not matter whether the tape is new or not, as long as it is permissible to overwrite any existing data on the selected media. Dumping a File to Tape This section describes how to make a tape containing the data from a single file. You ‘dump’ the ORDERS file to tape using T-DUMP. This operation does not affect the contents of the file, you can think of it as making a copy of the file and placing it on tape. The syntax is: T-DUMP [DICT] filename [item-list] [selection] [HEADING “text”] [modifiers] [(options)] DICT Specifies the file dictionary. When copying dictionary items, T-DUMP does not copy any File Definition items to tape. filename Using Magnetic Tape Name of the file. 10-5 item-list List of individual item IDs. Enclose each item ID in quotes. If you do not specify a list of item IDs, the system dumps all items in the file. selection Specifies one or more conditions that an item must meet before the system copies it. For a complete description of selection expression syntax, refer to LIST in the UniVision Command Reference Guide. text Added to the standard tape label via the HEADING modifier. modifiers Include one or more keywords that specify the report format. These parameters affect headers, footer, spacing, totalling column figures, control breaks, etc. For details refer to the VISION Reference Guide.: The following modifiers operate differently HDR-SUPP Suppresses creation of a tape label. ID-SUPP Suppress listing of item IDs during the copy to tape operations options ! Note: Include one or more single character codes that specify the report format and direct or modify output. You must enclose them in parentheses, can enter them in any order, and need not separate them with spaces or any delimiters such as commas. For details refer to the VISION Reference Guide. In addition, there is a ‘SORT’ version of T-DUMP called S-DUMP. In the following command, T-DUMP makes a tape containing the entire ORDERS file: 10-6 A Guide to the UniVision System >T-DUMP ORDERS BLOCK SIZE: 16896 1 10107 2 10119 3 10110 4 10122 5 10113 6 10104 7 10116 8 10101 9 10134 10 10105 11 10108 12 10120 13 10111 13 Items dumped The system dumped the 13 items in the ORDERS file to tape. Once the UCL prompt returns, the system has completed the operation. It positions the tape just after a mark known as the End-Of-File (EOF) mark. At this point, you can rewind the tape drive using T-REW and detach it using T-DET, you can remove the tape cartridge from the drive, and the system makes the tape drive available to other users. >T-DET The system does not display a message if it detaches the tape drive successfully, and you can remove the tape from the tape drive. Some tape devices, such as half-inch, 8mm, and 4mm DAT tape drives can unload the tape media under software control. T-UNLOAD can be used to rewind the tape and unload the media from the drive. However, the device is still attached to your process. When you have completed using the tape device you should detach the drive or log off. Either action releases the tape device for use by another user logged on to another process. Restoring Items from Tape The previous section copied the ORDERS file to tape. This section restores one of the items from tape. If you removed the tape at the end of the previous section of this tutorial, you should replace the tape cartridge in the tape drive. Enter T-ONLINE to attach the tape drive and rewind the tape. The system positions the tape at the beginning of the tape, which is also the beginning of the ORDERS file. Using Magnetic Tape 10-7 You use T-LOAD to load a file from tape. However, it does not overwrite an existing item on file. To demonstrate T-LOAD, assume you want to delete a single item from the file, and then restore it from tape. The following command deletes one of the items from the ORDERS file on disk. >DELETE ORDERS 10121 ‘10121’ Deleted T-LOAD has the following syntax: T-LOAD [DICT] filename [item-list] [selection] [(options)] DICT specifies the file dictionary. filename name of the file. item-list list of individual item-IDs. Enclose each item ID in single quotes. If you do not specify a list of item IDs, the system loads all items in the file. selection specifies one or more conditions that an item must meet before the system restores it. For a complete description of selection expression syntax, refer to LIST in the UniVision Command Reference Guide. options include one or more single character codes that specify the report format and direct or modify output. You must enclose them in parentheses, enter them in any order, and need not separate them with spaces or delimiters such as commas. I suppress the listing of the items being loaded. O allows you to overwrite items that exist in the file. The following example, restores item ‘10121’ from tape and places it in the ORDERS file. >T-LOAD ORDERS ‘10121’ BLOCK SIZE: 16896 1 10121 1 Item(s) loaded It is important to realise that filename specifies where you want to copy the items; it does not identify the file on tape. The position of the tape determines the tape file. Thus, T-LOAD searches for the specified data item in the current file on tape. if, for instance, you specify the CUSTOMERS file, the system copies the item ‘10121’ from tape to the CUSTOMERS file. 10-8 A Guide to the UniVision System When you finish restoration, the system position the tape at an EOF mark following the file. To read from the same file on tape, you must reposition the tape at the beginning of the file. When using a cartridge tape, you must position the tape at the beginning and advance it forward to the particular position of the file. Because there is only one file on this tape, you need to rewind the tape to the beginning. Use T-REW to rewind the tape. >T-REW BLOCK SIZE: 16896 In addition, T-REW reports the current block size. If you are near the system itself, you should be able to hear the system rewinding the tape. As was mentioned earlier, T-LOAD does not overwrite an item if it already exists on file. Issuing the same command produces the following result: >T-LOAD ORDERS ‘10121’ BLOCK SIZE: 16896 ‘10121’ already exists 0 Item(s) loaded The system does not write the item from tape. If you want the item from tape to overwrite the item on file, use the parenthetical option O with T-LOAD. You can use LIST and SORT to view the contents of items on tape. The TAPE modifier extracts items from the current file on tape as though it were a data file on disk. For example, to position the tape to the beginning of the file. >T-REW BLOCK SIZE: 16896 Use LIST to list the data from two attributes of a single item. >LIST ORDERS ‘10121’ TOTAL.AMT DATE TAPE PAGE 1 15:09:23 ORDERS... Amount... Date of Order 10121 $68.94 15/11/96 22 NOV 1996 End of list ! Note: Using Magnetic Tape The filename ORDERS as specified in the statement identifies only the dictionary used to issue the report. It does not identify the file on tape. 10-9 Appending Data to Tape The system writes an End-Of-Data mark at the end of the last file on tape. To write another file to the same tape as used to write the ORDERS file, you must position the tape at the EOD mark. T-EOD moves the tape to the EOD mark. >T-EOD BLOCK SIZE: 16896 [92] End of recorded data - 1 FILE(S) Once the system has positioned the tape at the EOD, it is possible to dump another file to tape. The following example, dumps the CUSTOMERS file. >T-DUMP CUSTOMERS BLOCK SIZE: 16896 1 AEDWA51BLA 2 SPIRS112AE 3 AJOHN760JE 4 HJENK1222M 5 AMEAD251BL 6 JBROW129B0 7 BLEAR34TRE 8 JPEER89RIA 9 HJOHN3550T 10 JBOHA126TR 11 JBUCK26STO 12 HHIGG5425T 13 DEDGE338BR 14 AORLA55VEN 15 MASHX912AE 16 RPIER123WE 17 BLAMP344TR 18 JMASO226RO 18 Items dumped Now there are two files in sequence on the tape. Positioning the Tape This section examines a few commands used to position the tape and determine its contents. Some tape devices, such as quarter-inch, 8mm, and 4mm DAT tape drives cannot backup one tape record. Half-inch tape and diskettes can backup one tape record. When using a device that cannot be backed-up you must rewind the tape and position the tape by moving to the correct position. 10-10 A Guide to the UniVision System When you write a file to tape, the system writes an EOF mark after the end of the last tape record used by the file. To locate a particular file on tape, you position the tape just after the EOF preceding the specified file. Figure 10-1 shows the layout of data on a cartridge tape. The system stores the contents of a file in physical tape records. These records are of fixed length, specified as the block size when you attach the tape. If the contents of a file do not fill up the tape record, the system pads the record to fill it. If the contents of the file do not fit in a single tape record, the file spans multiple tape records. Each file written to tape has a label. The information on this label can vary, but it should provide the time and date of tape creation and the name of the file. The tape label can be 80 or 512 characters long, the device determines the label size. For example, half-inch tapes are 80 bytes long, 8mm and 4mm DAT tapes are 512 bytes long. Quarter inch tapes can be 80 or 512 bytes long. On quarter-inch drives you can set the label size by issuing a T-FORMAT with the L (long) or S (short) option. LABEL Size of the physicalrecord is a fixed length, set as the block size Tape Record File1 fits in a single tape record Tape Record EOF EOF BOD LABEL Tape Record File2 spans over two physical tape records Figure 10-1. Layout of data on cartridge tape Using Magnetic Tape 10-11 The following example, repositions the tape at the beginning and uses T-RDLBL to examine the label of the first file on tape. >T-REW BLOCK SIZE: 16896 >T-RDLBL BLOCK SIZE: 16896 L 4200 14:43:11 25 NOV 1995 ORDERS ~1 > As you can see, this label identifies the ORDERS file. After executing T-RDLBL, the system positions the tape after the label. To be able to read the label of the next file on tape, you must advance the tape to the next EOF mark. There are two ways to advance the tape. T-SPACE counts EOF marks to advance the tape past a specified number of files. T-FWD moves forward to the next EOF. T-FWD n moves forward n records or to EOF if there are less than n records in the file. Because the first file consists of only a single block of data, and the system positions the tape before the first block, you can use T-FWD to move to the next EOF mark. >T-FWD BLOCK SIZE: 16896 [94][EOF]End Of File >T-RDLBL BLOCK SIZE: 16896 L 4200 14:43:11 25 NOV 1995 ORDERS ~1 > T-RDLBL displays the label that identifies the CUSTOMERS file. T-FWD 1 moves ahead to the next tape record. If a file spans several tape records, you can advance the tape a record at a time or for a specified number of records using T-FWD. If you specify a block size smaller than the default, then it is more likely that the system stores a file on tape in multiple tape records. If this is the case, it might be easier to position the tape using T-SPACE, which is the same as a sequence of T-FWD commands. T-SPACE is a Proc the executes T-RDLBL and T-FWD to move ahead by a specified number of files. The following example, rewinds the tape, and uses Tnd SPACE to position the tape at the beginning of the 2 file. 10-12 A Guide to the UniVision System >T-REW BLOCK SIZE: 16896 >T-SPACE 1 BLOCK SIZE: 16896 BLOCK SIZE: 16896 L 4200 14:43:11 25 NOV 1995 ORDERS ~1 > T-SPACE displays the label of the file that it passes over. The system now positions the tape at the beginning of the CUSTOMERS file and you could use TLOAD to restore items from the tape file. Before continuing, you should detach the tape drive from the process and remove the tape cartridge or reel from the drive. Use T-UNLOAD to rewind and unload the tape in a ½-inch tape drive. Tape Command Summary There are two groups of magnetic tape verbs: utility verbs and production verbs. Utility verbs set up the tape drive or position the tape for various operations. Production verbs allow you to read and write formatted tapes. The following is a list of tape commands, arranged alphabetically. FORMAT Formats a floppy disk for use in UniVision. T-ATT Attaches a logical tape unit to the user’s process. T-DET Detaches a tape unit from the user’s process. T-DUMP Copies items to magnetic tape. T-EOD Advances a tape to the end of the data. T-ERASE Erases selected tape drives T-FORMAT Sets the tape drive format. T-FWD Advances the tape forward. T-LOAD Restores items from tape to disk. T-ONLINE Puts the tape drive on-line and rewinds the tape. T-RDLBL Reads, displays and stores tape labels. T-READ Displays the contents of a tape. T-RET Retensions the tape media. T-REW Rewinds a tape. T-SELECT Selects and attaches logical tape units to a process. Using Magnetic Tape 10-13 T-SPACE Spaces a tape forward. T-STATUS Lists the current tape device assignments. T-UNLOAD Rewinds and unloads a tape media under software control. T-WEOF Writes an End-OF-File mark on tape. T-WHAT Displays the type of tape drive currently selected. T-WTLBL Writes and stores labels. In addition, to these commands there is a TAPE modifier, which reads items from the current file on tape. Overview of Utility Verbs The utility verbs, T-ATT, T-ONLINE, and T-SELECT, allow a process to gain exclusive control of a tape drive. T-DET relinquishes control of the tape drive on completion of processing. T-FORMAT establishes the QIC format of the tape, such as QIC150, QIC525, etc. In addition, T-FORMAT can set tape label length (80 or 512 bytes) and high or low density, such as 1600 BPI, 320 BPI, 6250 BPI, etc. TSTATUS displays the status of tape drives. You use the utility verbs T-FWD, T-EOD, T-REW, and the T-SPACE Proc to position the tape. T-WEOF writes an EOF mark on tape. T-RET retensions tapes. T-ERASE erases selected tape drives. Two utility verbs, T-READ and T-RDLBL, are available to inspect tapes and can be helpful if you encounter any difficulties when using tape as a storage or transport medium. Overview of Production Verbs The production verbs fall into four categories: • Performing an account-save or file-save and restoration. • Reading and writing files using VISION verbs. • Reading and writing Spooler print files. • Reading and writing tape records using UniVision BASIC. Performing an Account-Save or File-Save and Restore The basis for commands used to save and restore the system is the result of SAVE. ACCOUNT-SAVE and FILE-SAVE invoke SAVE with a specific group of SAVE options. You can retrieve data from a SAVE tape using any of the following methods. 10-14 A Guide to the UniVision System • :FILELOAD • ACCOUNT-RESTORE • ADD-ACCOUNTS • SEL-RESTORE The UniVision System Administration Guide covers the commands used for backing up and restoring the system. Reading and Writing Files using VISION Verbs T-DUMP, S-DUMP and T-LOAD write data to and read data from tape. T-DUMP and S-DUMP save data from one file at a time, and is the recommended method of creating tapes for data transfer between the different types of PICK-based systems. T-DUMP and S-DUMP allow you to use selection expression to identify the items dumped to tape. In addition, it accepts item-lists and processes an active select-list. T-LOAD retrieves data written by T-DUMP or S-DUMP and loads it into a specified file. In addition, it accepts selection expressions to identify a set of items you want to load. T-DUMP and SAVE format the data on the tape in a different manner, thus the data is not interchangeable between these tape formats. Reading and Writing Spooler Print Files You can spool print files to tape by assigning the tape drive as the destination for subsequent print jobs: see SP-ASSIGN and SP-EDIT. You can read print files from tape and output them to the printer using SP-TAPEOUT, or you can make them into hold files with the HS option of SP-ASSIGN. You can use print files to make tapes that are readable by non UniVision machines. You can use SPTAPEOUT to read files on tape that use carriage returns or linefeeds as record delimiters. Refer to the Section entitled The Spooler for more information on spooling files to tape, in addition see the section at the end of this Section on transferring data to non UniVision systems. Reading and Writing Print Records using UniVision BASIC READT and WRITET are UniVision BASIC statements used to read and write from tapes. These statements assume full control of all blocking and deblocking of tape data records. Each time you issue WRITET, the system writes a new tape block. WRITET specifies that the system places a string in the next tape block. If the string does not fill up the tape block, the system pads the unused portion with blanks. There are two conditions that produce error messages. • If the string is null. Using Magnetic Tape 10-15 • If the length of the string exceeds the size of the tape block. In the latter case, the system truncates the string to fit in the tape block. A data record written with WRITET cannot span two blocks. Therefore it is efficient to write fixed-length data records and to set the block size equal to the size of the data record or to a multiple of it. Understanding Tape Layout The layout of data on tape is different for ½-inch and ¼-inch tape drives. The main difference is that the ½-inch tape uses an Inter-Record Gap (IRG), a length of tape used to demarcate the sections on tape. Figure 10-2 shows the layout of ½inch tape. On ½-inch tape, two consecutive EOF (End-Of-File) marks indicate the EOD (End-Of-Data). On the ¼-inch tape, the beginning of a section of blank tape indicates the EOD. end of data E O F I R G LABEL I R G DATA I R G E O F E O F Figure 10-2. Tape layout for ½-inch tape The system writes data to fixed-length blocks or physical tape records. Files consist of variable-length items that are logical data records. Because the system stores data records as a continuous string, multiple file items can fit in a single block and the system allows individual items to span over multiple blocks. Thus there is no necessary correlation between block size and data record size. The system pads any unused portion of a tape record at the end. The pad character is an X’FB’ character if T-DUMP and SAVE generate the tape. It is a null (X’00’) character if the tape record contains a print file. The pad character is a blank when UniVision BASIC generates the tape. UniVision BASIC tape statements do not write labels. You can use T-WTLBL to write a label to tape. In addition, the programmer is responsible for writing the EOF. mark. 10-16 A Guide to the UniVision System Tape Label Format A tape label consists of seven elements, as shown in Figure 10-3. A label is 80 or 512 bytes in length. Only the first 80 bytes are significant in a 512 byte label, the system pads other bytes with the null character (X’00’). T-DUMP and S-DUMP create it. system time source file label indicator L reel number 01F4 16:12:27 06 MAR 1997 FILENAME block size TEXT…..~1 header text system date Figure 10-3. A sample tape label The label contains the source file name as specified in T-DUMP. In addition, it contains any user-supplied text provided using the HEADER, or HEADING modifier. The system only stores the first 47 characters in the heading on tape. For instance, the following T-DUMP uses the HEADER modifier to add text to the label after the filename: >T-DUMP CUSTOMER HEADER “BEFORE REMOVING DUPLICATES” You can read the resulting label with T-RDLBL: >T-RDLBL BLOCK SIZE: 16896 L 0800 11:31:36 26 NOV 1996 CUSTOMERS BEFORE REMOVING DUPLICATES ~1 If necessary the system truncates the header string from the right to fit into the label block. If the Spooler generates the tape output, the file name is the account name. UniVision BASIC does not write a label. Using Magnetic Tape 10-17 Block Size It is possible to change tape block size in two ways. You can specify a block size with T-ATT, or you can read it from a tape label using the UniVision tape-reading commands T-RDLBL and T-READ. These commands change the block size to match the block size used when the system dumped the data to tape. The system tests specified block sizes against a range of values allowed for the system configuration. If the block size specified with T-ATT falls outside the valid range for that configuration, the system adjusts the block size. ½-inch Tape Block Sizes On the ½-inch reel-to-reel tape drives, the recommended minimum record size is 80 bytes for the generation of a tape of card images for transfer to a machine that needs such a tape. The recommended record length is 4000 bytes and the maximum block size is 32256 bytes. The presence of the Inter-Record Gap (IRG) places an upper limit on the number of blocks on a tape of given length. The block size used affects the storage capacity of the tape. Since the tape drive starts and stops for each record, increasing block size decreases the number of blocks on the tape as well as the number of IRGs. The optimum block size decreases wear and tear on the tape drive, decreases processing time and increases system throughput. ¼-inch Tape Block Sizes On a ¼-inch cartridge tape drive, the block size must be a multiple of 512. The system rounds block sizes that are not multiples of 512 down. Any block size specification lower than 512 bytes defaults to 512. The maximum block size is 32256 bytes. 8mm and 4mm DAT Tape Block Sizes On 8mm and 4mm DAT tape drive, the record length can be any number up to 33256 bytes, although the recommended value is the default of 4096 bytes. For best results, the block size should be a multiple of 1024. Diskettes and CD-ROM Device Tape Block Size When using diskettes, the block size supported is 500 bytes. If you specify any block size less than or greater than 500, the system ignores it and uses 500 bytes. 10-18 A Guide to the UniVision System Selecting the Tape Drive If there is only one tape drive on the system, you can skip this section since the system would set up that tape drive as the default tape unit. This section is about how to select a specific tape drive. Setting Tape Drive Assignments The system assigns numbers, known as logical tape unit numbers, to tape drives, like printers, you add them to the system. You assign a logical tape unit number to each physical tape drive using SET-TAPE. You usually make these assignments when you cold-start the system, (if you have specified them in the USERSTARTUP Proc). In addition, you can override them to allow a different physical tape drive to be a particular logical tape unit. The UniVision Command Reference Guide describes SET-TAPE. Listing Current Tape Device Assignments You can determine the current tape assignments by examining the report produced by T-STATUS. T-STATUS lists all assigned logical tape units, their assigned tape devices, the attached processes (if any), and the tape format specifications. T-STATUS[(P)] The only option available for T-STATUS is the P option, which sends the report to the printer. T-STATUS produces a report such as the following: >T-STATUS LTU DRIVE ATT FORMAT 0 1 Q0 F0 DEVICE DESCRIPTION UNIX DEVICE NAME 021 LONG LABEL WANGTEK 5525ES SCSI /dev/rmt/c0t3d0s0n HIGH DENSITY 3.5 inch 1.44 Mbyte /dev/rdsk/f03ht This report contains the following information: LTU logical tape unit. DRIVE type and number of the tape drive assigned to the tape unit. Type can be: Using Magnetic Tape F floppy disk drive. E 8mm tape drive. H ½-inch tape drive. Q ¼-inch tape drive. 10-19 D 4mm tape drive. C CDROM drive. ATT number of the process attached to the tape unit. If you have not attached a tape unit, this field is empty. FORMAT tape format as set by T-FORMAT. The T-STATUS report does not list any tape units not assigned with SET-TAPE. Selecting a Tape Drive for an Account Whenever a user logs on to the system, it selects tape unit 0 automatically by default. However, the system does not attach it to the user’s process. The user can select and attach another tape unit, or a set of tape units, by executing T-SELECT. These tape units remain selected until the user logs off or selects another tape unit. They remain attached until the user logs off or detaches them with T-DET. TSELECT selects one or more tape units and attaches them to your current process. You can use T-WHAT to report the current selection for your account. >T-WHAT [6007] 1/4 Inch cartridge unit LONG LABEL This example reports that you have selected logical tape unit 0, the default, for this account and that it is assigned to a ¼-inch tape drive. Use the following syntax to select a single tape drive for an account: T-SELECT [tapeunit1] where tapeunit1 is the number of logical tape unit. T-SELECT checks the DEVICE-NAMES files to check for a valid device name. You can only select a tape unit assigned to a physical tape device with T-SELECT. If you have not assigned the tape unit, the system displays the following message. [6008] Tape unit not assigned If you have another process attached to the tape unit, the system displays the following message: DEVICE d ATTACHED TO USER n and the system selects the tape unit but does not attach it to the user’s process. The U option unconditionally detaches the tape unit from another process and attaches it to the user’s process. 10-20 A Guide to the UniVision System ! Note: Do not detach a tape drive that is currently in use, and never hand-code a T-DET into a program. The following example shows how to select and attach tape unit 1. >T-SELECT 1 [6037] Floppy device attached >T-STATUS LTU DRIVE ATT FORMAT 0 1 Q0 F0 DEVICE DESCRIPTION UNIX DEVICE NAME 021 LONG LABEL WANGTEK 5525ES SCSI /dev/rmt/c0t3d0s0n HIGH DENSITY 3.5 inch 1.44 Mbyte /dev/rdsk/f03ht Selecting Multiple Tape Drives You can use T-SELECT to chain two or more tape drives to a single process. This allows you to perform multi-reel operations without operator intervention. You must assign each of the tape units to tape drives of the same type and using the same format. Use the following syntax for T-SELECT to select a chain of tape drives: T-SELECT [ tapeunit1[-tapeunit2]|({P|S})] [(U)] where tapeunit1 is the number of the logical tape unit from 0 to 11, tapeunit2 is the number of one or more additional tape units chained to tapeunit1, P is tapeunit 0, the primary unit and S is tape-unit 1, the secondary unit. Specify each tape unit, separated by hyphens, in the order in which you want them chained. If the system cannot attach one of the tape units in a chained set to the user’s process for any reason, the system does not attach any of the specified tape units, although tit does select them. The following example selects and attaches tape units 0, 2, 3 and 1, in that order, as a chained set. >T-SELECT 0-2-3-1 Tape operations using this set proceeds from tape unit 0 to tape unit 2, then to tape nd unit 3 and finish on tape unit 1. You can mount a 2 set of reels and operations return from tape unit 1 to tape unit 0. Tape operations proceed, going round the chain again in the same order. It is not possible to chain unlike tape devices. If you specify unlike tape devices for example, a quarter-inch cartridge and diskette the system displays the following warning and does not select the devices. >T-SELECT 0-1 DEVICES 0 AND 1 ARE DIFFERENT TYPES OF DEVICE Using Magnetic Tape 10-21 Specifying Tape Drive Format T-FORMAT rewinds the tape and sets the tape format for the tape drive. To display the current tape format set, enter T-FORMAT with the ? option. If you enter an invalid selection at either prompt, the system displays the following message: ‘X’ IS NOT A VALID FORMAT FOR THIS DEVICE Attaching a Tape Device T-ATT attaches the currently selected tape unit to your process, giving you exclusive control of the assigned tape drive. A number of tape verbs automatically attach the process to the tape drive. Therefore you do not need to use T-ATT to attach the tape drive unless you want to change the block size. The syntax is: T-ATT [block] block block size of the tape record, in bytes. The maximum is 32256 bytes. The system defaults are: ¼-inch tape drives ½-inch tape drives 8mm tape drives Floppy disk drives 4mm tape drives CD-ROM 16896 bytes 16000 bytes 16384 bytes 500 bytes 4096 bytes 512 bytes Using T-RDLBL with a mounted labelled tape sets the block size to the tape record length specified in the tape label. When you have attached the tape unit to the process successfully, the system displays the following message: BLOCK SIZE: xxxx where xxxx is the block size. If you have attached the selected tape unit to another process, the system displays the following message: DEVICE d ATTACHED TO USER x where x is the process number attached to the tape unit. 10-22 A Guide to the UniVision System The system detaches the tape unit from the process automatically when log off takes place. You can detach it at any time by issuing T-DET. Detaching a Tape Unit T-DET detaches the attached tape unit from the process. Detaching the tape unit releases it from the exclusive control of the process and makes is available to other users. The tape unit remains selected, however. T-DET deletes all multiple tape units attached to the process. >T-DET > The system does not display a message if the detachment is successful. The U option of T-DET, which requires SYS2 privilege, detaches the currently selected tape unit from any process it is possible to attach to. The U option affects only the currently selected tape unit. If the selected tape unit is currently attached to another process, using T-DET with the U option detaches the tape unit from the other process and makes it available again. If the selected tape unit is one of a chained set, the system detaches the entire set. ! Note: It is not recommended practice to use the U option to detach tape units, since other processes might be using those tape drives. Attaching a Cartridge Tape Unit T-ONLINE resets the cartridge tape drive, checks that you have inserted a tape cartridge, and rewinds the tape. Before you use T-ONLINE, insert a tape cartridge in the ¼-inch tape drive. If you have selected the tape unit assigned to it, T-ONLINE checks for attachment, determines that you have inserted a tape into it, and rewinds the tape. The following example resets the ¼-inch tape drive: >T-ONLINE BLOCK SIZE: 16896 [6004] Tape on line Since T-ONLINE can attach the tape drive, you do not need to use T-ATT. A standard practice is to enter T-ATT first. A program can test if the T-ATT fails and take alternative action. If it fails using T-ONLINE, the system prompts the user to continue of quit. Using Magnetic Tape 10-23 If you have not inserted a tape, T-ONLINE attaches the tape unit, if selected, and displays the following message: >T-ONLINE BLOCK SIZE: 16896 DEVICE NOT READY CONTINUE/QUIT (C/Q)? To continue, insert a tape cartridge in the drive, and enter C at the prompt. To quit, enter Q. Positioning the Tape This section covers commands used to position the tape. There are commands for rewinding the tape and for advancing the tape to specific tape blocks or to an EndOf-File mark. Rewinding the Tape T-REW rewinds a tape to the load point (BOT). T-REW When system has rewound the tape, the system returns to the UCL prompt. If the tape is already at beginning of tape, the system takes no action. The following example rewinds the attached tape: >T-REW BLOCK SIZE: 16896 Forwarding the Tape T-FWD advances a specified number of tape records or to the End-Of-File mark. T-FWD [record] record number of records you want to advance. The maximum is 32767. If you encounter an End-Of-File mark before passing the specified number of records, or if you do not specify record, the system position the tape after the End-Of-File mark. 10-24 A Guide to the UniVision System The following example moves the attached tape forward one record: >T-FWD 1 BLOCK SIZE: 16896 If you have not specified an argument, T-FWD advances to the next EOF. Reading Tape Labels T-RDLBL reads a tape label, whether it is at the beginning of a tape or at the beginning of a file that is after an End-OF-File mark. Using T-RDLBL with a mounted labelled tape sets the block size to the tape record length specified in the tape label. T-RDLBL T-RDLBL reads the tape label and displays the reel number, block size, time, and date when the system wrote the tape, and a header text on the screen. If you use T-RDLBL, on a tape that is one of a multi-reel set of tapes, the system includes the reel number with the tape label. At the end of the tape, the system prompts you to load the next reel in sequence. ! Note: T-RDLBL reads tape labels created by T-DUMP or SAVE operations. Tape labels created on non-UniVision systems are incompatible and most of the time you cannot determine the block size. In order to use the tape you must know the block size and issue the proper commands to avoid or skip the tape label. Moving to a Specified File T-SPACE spaces a tape forward over a specified number of files. T-SPACE executes T-RDLBL and T-FWD as many times as number specifies. The syntax is: T-SPACE number where number is the number of files to space over. If you do not enter number in the command line, the system prompts you to enter it. The following example moves the tape forward one file: >T-SPACE 1 BLOCK SIZE: 16896 BLOCK SIZE: 16896 L 4200 09:20:11 28 NOV 1996 CUSTOMERS ~1 > Using Magnetic Tape 10-25 Advancing to End-Of-Data T-EOD moves the tape forward to the end of the recorded data. At the EOD mark, you can append new data to the tape. The following example advances the attached tape to the end of the recorded data: >T-EOD BLOCK SIZE: 16896 [6000] End of recorded data Writing an End-Of-File Mark T-WEOF writes an End-Of-File mark on the tape at the current position. T-WEOF If the tape’s write protection is on or if no write ring is present, the system displays one of the following messages: WRITE PROTECTED CONTINUE/QUIT (C/Q)? or DEVICE NOT READY CONTINUE/QUIT (C/Q)? Remove the write protection or install a write ring, and enter C to continue, or enter Q to quit. Unloading a Tape T-UNLOAD rewinds the tape to the load point (BOT). If supported the drive ejects the tape. T-UNLOAD When you have unloaded the tape, the tape unit is no longer on line. This means that no other process can read or write to the tape. The system returns to the UCL prompt. If you have finished using the tape device, you should detach it using TDET. 10-26 A Guide to the UniVision System Erasing Selected Tape Drives T-ERASE erases selected tape drives and rewinds to the beginning of the tape (BOT). T-ERASE ! Note: T-ERASE erases all data on the tape media. Retensioning Tape Media T-RET retensions the tape media. A tape retension fast-forwards to the end of tape and rewinds. This action on the tape media allows the tape drive to correct any bumps in the actual media. T-RET Other Tape Verbs It is possible to use three other verbs with tapes. T-DUMP and S-DUMP create a tape containing all or selected items from a file. T-LOAD reads all or selected items from a tape and loads them into a file or file dictionary. Dumping a File to Tape T-DUMP transfers a copy of all or selected file items to magnetic tape. In addition, T-DUMP creates a tape label and writes an End-Of-File mark on the tape after the completion of the transfer. You can find the syntax of T-DUMP in the UniVision Command Reference Guide. S-DUMP is a version of T-DUMP that accepts a sort expression. The following modifiers operate in a special way relative to T-DUMP and SDUMP. HEADER ‘text’ Specify heading text used in the tape label. HEADING ‘text’ Same as HEADER. HDR-SUPP Suppresses the creation of a tape label. ID-SUPP Suppresses listing of item IDs during the copy-to-tape operation. If the tape’s write protection is on or if no write ring is present, the system displays one of the following messages: WRITE PROTECTED CONTINUE/QUIT (C/Q)? Using Magnetic Tape 10-27 or DEVICE NOT READY CONTINUE/QUIT (C/Q)? Remove the write protection or install a write ring, and enter C to continue, or enter Q to quit. The following example writes all items from the ORDERS file whose date is before December 12, 1987 to magnetic tape. The tape label includes an addition to the standard text that reads ‘OLD ORDERS’. >T-DUMP ORDERS WITH DATE LT “12/12/87” HEADING “OLD ORDERS” 1 10117 2 10232 3 10089 . . . 24 Items dumped If you execute a T-DUMP, and the file is empty, that is, no items dumped, the system writes an EOF mark to tape. This allows a Proc that executes multiple TDUMPs followed by as many T-LOADs to function properly. Restoring Items from Tape T-LOAD restores file items previously copied to tape with T-DUMP or S-DUMP. You can only copy these file items to an existing file. You can find a description of T-LOAD in the UniVision Command Reference Guide. When the restore operation is complete, the system positions the tape at the EndOF-File (EOF) mark. The following example restores all item from the tape file to the ORDERS file from magnetic tape. The I option suppresses the listing of item IDs: >T-LOAD ORDERS (I) 24 Items loaded Including Data from Tape in Reports You can use the TAPE modifier with any VISION modifier to retrieve data from tape and display it in reports. The you must attach the tape unit prior to using the TAPE modifier. By adding the TAPE keyword to a statement, the report uses the items from the file on tape, even if there is a data file on disk with the same name and containing the same items. 10-28 A Guide to the UniVision System The following example reads the items from tape, using the ORDERS dictionary, and displays a report on the screen. >LIST ORDERS CUST.ID DATE TOTAL.AMT TAPE Examining the Contents of a Tape T-READ reads a tape record and displays its contents on the screen or sends it to the printer. It does not restore the data or format it. It is somewhat the equivalent of DUMP, which dumps a specified frame on the screen. T-READ dumps one or more blocks from tape, and you can use it to examine the tape to locate a specific file. The syntax is: T-READ [n-m][(options)] where n is the number of tape records to read and display relative to the current record. If you do not specify n, the system displays all records up to the next EOF. n-m specifies a range of records. T-READ options can be any of the following: A converts from EBCDIC alphanumeric segments. to ASCII, then displays P sends the display to the printer. S prevents the tape cartridge from rewinding to the tape label. You can only use this option on a 1/4-inch tape drive. X displays tape contents in hexadecimal format as well as in character format. st On ¼-inch tape drives, the 1 element T-READ displays is the tape label. If the system has not positioned the tape at the label, T-READ rewinds the cartridge to the beginning before it reads the tape. Using Magnetic Tape 10-29 >T-READ (1 BLOCK SIZE: 512 L 0200 16:34:10 29 NOV 1996 DICT MD ~01 RECORD = 1 1 51 101 151 201 251 301 351 401 451 501 BLOCK-CONVERT^Q^BLOCK-CONVERT^^^^^^^L^10^[T-LOAD^P T^35^73^[RTD^P^20A0^[DATA^CZ^[DTR^[^10A0^[LISTPEQS ^P^AB^[TAPETEST^PQ^SS^IT^IF A # DALE’S ORDERS GO 100^HTIME^P^D0^X^100 ONOT THE RIGHT TAPE^P^[IT^PQ IT^D0^HTIME^P^[X-ON^P^510E^[T3^PQ^T (-5),”TWINKLE” ,(-6)^[B^PQ^HSORT ORDERS BY-EXP^S2^A^HBREAK-ON^B^D 0^A^HTOTAL AMOUNT^P^[HEADING^CL^[BLOCK-PRINT^P^500 A^41^[SS^PQ^SS^HLIST CUSTOMERS^A2^D0^P^[“A10^A^10^ ^^^^^^L^10^[LOCALSUB^PQ^HSORT CUSTOMERS BY^A2^HNLNA ME FNAME^ODOUBLE SPACE?+^IP^S3^IF A = Y []20^P^X^ 20 H DBL-SPC > The following example, uses T-FWD to advance four physical tape records. TREAD, entered with the S option, displays the block at that position. >T-FWD 4 BLOCK SIZE: 512 >T-READ 1S BLOCK SIZE: 512 RECORD = 1 1 51 101 151 201 251 301 351 401 451 505 REPORT^IP^IF A = YES GO 500^IF A # YES X REPORT NOT GENERATED^500 HSORT CUSTOMERS BY LNAME^H LNAM E_[FNAME^P^TESTIP2^PQ^ODO IT+^IP2?^IF A = N GO 99 9^HSORT CUSTOMERS^P^999 x I WONT THEN^[CUST-FIND^ P^E6^^^BP^[DEBUG-OFF^P^1234^[FXSUB^P^E6^^^BASICLIB ^[D^[^242^[SIZE^A^9999^^^^^^MR0^R^10^[C-O^PQ^R.R M D CUST.ORDER.LIST^P^[LBP^Q^LMUI^BP^^^^^^L^10^[V/CO NV^A^07^CONVERSIONS^^^^^^L^30^1^[LIST-LABEL^PA^35^ 4D^7D^[BUILD-LOCK-XREF^P^E6^^^BASICLIB^[L/UPD^A^06 ^^^^^^^L^5^[ADDD^PA^40A0^[LISTPTR^P^AE^[SORT-ITEM^ PA^35^4E^508 > This block is somewhere in the middle of a file. The system does not display a label. Without the S option, the system would have rewound the tape to the beginning and the output would be the same as the previous example. Transferring Data to and from Other Systems This section looks at specific issues involved when using tape media to transfer data between computer systems. 10-30 A Guide to the UniVision System Transferring Data between Pick-like Systems The most reliable method of transferring data between a UniVision and a Pick-like system is using T-DUMP to create the tape and T-LOAD to restore it. As a rule, the recommended tape block size is 512 bytes for tape compatibility. When loading a tape onto UniVision, use T-READ to read the label and re-attach the tape using the correct block size. In addition, it is a good idea to suppress the tape label when making the tape, as tape labels vary between different versions of Pick or Picklike products. Transferring Data to a Non-Pick-like System To be able to transfer data on tape media to a non-Pick-like system, such as an IBM mainframe, the two tape drives involved in the interchange must be compatible. To know whether or not they are compatible involves examining the technical specifications of both drives. Generally, you can transfer 1/2-inch tapes between different types of machine. In brief, create a 9-track tape at either 1600 or 6400 bpi, (bits per inch), using the ASCII character set with high order bit off and write fixed block records without labels. Once you are able to determine the compatibility of physical protocols, you must check the compatibility of character sets. If the data on the tape does not use the ASCII character set, you must translate it. SP-TAPEOUT can translate EBCDIC to ASCII, providing the source tape uses carriage returns and linefeeds as delimiters. rd If two drives are incompatible, you must use a 3 machine that supports a tape drive, can read the source tape and create a compatible tape for the target machine. Use of Print Files Tapes created with T-LOAD and SAVE are formatted tapes that contain standard delimiters for items, attributes, and values. Generally, a non UniVision machine cannot read a formatted tape unless you have written special programs. In some cases, you might use print files to transfer data between UniVision and nonUniVision machines. Print files are a continuous string of data with lines delimited by carriage returns (X’0D’) and linefeed (X’0A’) characters. You delimit pages with form-feed (X’0C’) characters. If the page length parameter found in TERM is zero, VISION does not paginate. The system pads the end of the print file with nulls. Each line of a print file is of variable length, without padding of blocks on the right. If you require fixed-length lines, you could print a meaningless character in the far-right column of each line. .HILITE in Runoff can format text by placing a specified character always in the same column; it includes spaces before the character and a carriage return and linefeed. Using Magnetic Tape 10-31 It might be possible to truncate individual data values to fixed-length fields that you have concatenated to form a single fixed length record. You must reserve the final two character for the CR/LF. Another strategy is to use the F correlative to construct a fixed-length data record. For instance, the following correlative: F;2(ML####) formats the second attribute as a 4-character string. Use SELECT or SSELECT, specifying an output attribute, to produce a select-list containing the desired attributes of the data items as though they were keys. Save the select-list and read it into a UniVision BASIC program using READNEXT to obtain each data record from the list. The program can pad them as you desire. This approach uses less programming and computer time. COPY-LIST is available if you want a hard copy of the transmitted data. To read a non-UniVision tape that is in print file format, use SP-TAPEOUT. The following command uses the A option to convert files from EBCDIC to ASCII: >SP-TAPEOUT A Use SP-EDIT to move the print file into items, in Runoff format, in a data file. If the print file format is not acceptable, you must use a UniVision BASIC program. In addition, UniVision BASIC is the best choice when you require matching alternate data patterns. Block Size If the foreign tape label has the same block size as the data following it, the system reads the label as data. Often labels are shorter than data and some machines might produce two or three labels. To read the data, use T-READ to read the label or T-FWD to skip past the label. To use T-READ, the block size of the reading process must match the size of the label. If it is not, the system displays the number of bytes specified by T-ATT on the screen and the tape advances to the inter-record gap on 1/2-inch drives. It is possible to find the size of the tape record by using T-ATT and T-READ repeatedly. If the attached size is larger than the record size the system retries the tape repeatedly. If the attached size is less than the record size, the system loses the trailing bytes. If you want to inspect the data, use T-READ. If the data is in EBCDIC, you can translate it into hexadecimal using the X option. 10-32 A Guide to the UniVision System Troubleshooting The system detects many tape problems as parity errors, which can occur for a number of reasons. Perhaps the most common cause of parity errors is using the wrong block size when copying to and from tape. In addition, dirty tape heads can cause parity errors. The tape itself might be bad, for instance, dirty heads might have corrupted the data at the time the system wrote it to tape. Another problem is that the following EOD message appears unexpectedly: [6000] END OF RECORDED DATA If you know that the system has not positioned the tape at the end of tape. Perhaps you have specified the wrong tape format. Quarter-inch tapes use different formats such as QIC60, QIC150, QIC525, etc. When you have set the tape drive to a different QIC format from the format on the media the message above might appear. use T-STATUS to check what the current tape format setting is, and use TFORMAT to specify the correct tape format. A common problem is not using the proper command to read a tape. Make sure you know what command you use to make the tape then use the appropriate command to restore it. Obviously, physically labelling tapes is a key part of ensuring that you can restore data from tape. Using Magnetic Tape 10-33 Section 11 DATA COMMUNICATIONS This section discusses how to communicate with other computer systems, via RS232 communications. It covers the low level support for RS232 data communications provided in the UniVision environment. It explains how to establish the connection between two machines, and how to use that connection to initiate a remote RS232 logon session on the other system. In addition, UniVision supports a number of communications software products that offer a higher level of integration for performing specific tasks between systems such as: WinLink WinLink links your Microsoft Windows applications directly to the UniVision Database. WinLink allows you to incorporate the Windows interface into your applications allowing UniVision users to support a true Client/Server environment. UniComms UniComms is a set of utilities that allows a user to transfer data between UniVision systems using industry-standard protocols via serial RS232 cabling and modems. WinLink Users Guide or UniVision UniComms Users Guide give details of the above products. Overview It is possible to connect UniVision to another computer across a direct serial cable or via a modem. This connection uses one of UniVision's serial ports. CONVERSE allows a user to access a communications line for two-way communications. In order to use the line via CONVERSE, you must unlink the line serving that communications port from a process. You attach the available line to the user's process and CONVERSE passes input from the user process to the attached line. In addition, it directs output from that line back to the user process. Thus, if line 5 is an available line connected to a modem, a user at a terminal attaches line 5 to the process to begin communicating with the modem. Commands typed at the keyboard are 'passed-through' the process to the device and interpreted by the device or passed to the remote system. Data Communications 11-1 ! Note: Before using CONVERSE recommended practice is to acquire the RS232 line for UniVision use using Before using ACQUIRE-LINE. CONVERSE recommended practice is to acquire the RS232 line for UniVision use using ACQUIRE-LINE. Command Summary ACQUIRE-LINE Acquires UNIX line for subsequent use by UniVision. CONVERSE ‘Connects’ an attached line and a linked line. LINE-ATT Attaches a line to a process, providing exclusive use of that line. LINE-DET Detaches a line from a process. LINE-PROTOCOL Displays the line characteristics of specified lines. LINK-LINE Links a line to a process LIST-ACQUIRED-LINE Lists UNIX lines acquired for UniVision use. LIST-LINE-CHARS Lists protocol settings of processes and lines. LINE-STATUS Displays the status of a specified line or a range of lines. PROCESS-STATUS Displays the status of a specified process or a range of processes. PROTOCOL Sets line transmission characteristics and protocols. RELEASE-LINE Releases a line acquired previously back to UNIX. UNLINK-LINE Unlinks and detaches a line from a process. 11-2 A Guide to the UniVision System Making the Connection When you have established a connection between UniVision and another computer system, the connection between the two devices is across a serial cable. There are two types of physical connection. A direct connection between computers requires a serial cable running from a port on one system to a port on the other system. A dial-up connection requires two modems, each connected to one of the computers by a serial cable. The modems communicate with each other across phone lines. Setting Line Characteristics and Protocols Two machines connected directly or by modem must have the same transmission characteristics and communication protocols in order to communicate with each other. You must specify the correct speed for data transmission (the baud rate), the type of parity, and the number of significant data bits. In addition, you must implement communications protocols such as DTR or X-ON/X-OFF, if used, on both systems. For a direct connection, the speed should probably be 9600. For a modem connection, the baud rate depends on the speed of the modem and the speed of the modems used by the systems performing communication. You must use the lowest common denominator. 1200 and 2400 are the most common speeds, although higher speed modems are becoming available. For performance and throughput reliability there is a recommendation for a modem with error correcting capabilities. In addition, serial lines have the option of using a simple form of error checking known as parity. Parity uses the setting of an additional bit to verify that what the system sent out is the same as what it received. There are five possible parity settings: Odd The sum of the parity bit plus the assorted data bits must always add up to an odd number. Even The sum of the parity bit plus the assorted data bits must always add up to an even number. Marking The parity bit is always 1. Space The parity bit is always 0. None There is no parity. Data Communications 11-3 Even or odd parity are the only settings that provide any error protection. The sending computer sets the parity bit to 0 or 1 depending on the value of the data bits. The receiving computer checks to make sure that the parity came out as expected - odd or even. If line noise (for example, on a telephone line) changes one data bit (appears as 0 or 1 when the sending computer did not send it that way), the parity is incorrect. Various kinds of more complex error checking implemented in software or hardware devices have superseded parity. Nonetheless, parity is a feature of serial communications that you cannot overlook, since both sides must agree to use the same parity settings or no communication occurs. The basic data unit is a byte - 8 bits (or in the case of serial communications, 8 serial pulses). Two or three additional bits accompany a byte: a start bit, and either one or two stop bits. When the system is not transmitting data, the signal on pin 2 (the carrier tone on a modem) is equivalent to a continuous stream of binary ones, referred to as the MARKING state. The start bit is a voltage equivalent to binary 0, often referred to as SPACE. After receiving the start bit, both devices count the desired number of data bits and look for the stop bit that is always binary 1. In addition, it is possible to use only seven data bits, most commonly used in communication links transmitting only text files, since ASCII codes (a standard in the United States) use only seven of the eight bits of a byte; there is an extended ASCII used internationally that uses a full 8 bits. A terminal set to 8 data bits with no parity can often communicate with a line set for 7 data bits and any parity. You use DTR and X-ON/X-OFF signals to establish a 'handshaking' protocol between two systems. You observe these protocols to help control the flow of data so that the transmitter does not send more data than the receiver can process at one time. DTR is a signal or voltage on a pin. A machine transmits data if DTR is present. Some serial printers raise and lower DTR. X-ON flow control uses pins 2 or 3. You set outward X-ON (X-OUT) if you want a printer or terminal to use a <CTRL-S> to halt output and <CTRL-Q> to resume. When X-OUT is on, a process never sees the <CTRL-S> and <CTRL-Q> because the line does not pass these characters to the process. You only use X-IN, or inward X-ON, in intermachine communications. In addition, serial printer might set X-IN on but not XOUT because they are not expecting to get <CTRL-S> and <CTRL-Q>. If you suspend output from the system by <CTRL-S> and X-OUT is 'OFF', the line does not see the <CTRL-Q> to resume. 11-4 A Guide to the UniVision System Using LIST-LINE-CHARS and PROTOCOL Generally, when you install the system, all lines have the following default settings: BAUD PARITY BITS DTR X-IN X-OUT 9600 NONE 8 OFF ON ON Line/Process 0 might be different as it is usually the system console device. If you use UniVision on a system where you configured the lines previously for general O/S use, it uses those settings, that is, UniVision does not require any special settings. ! Note: If you configure the line for 8 bits with output Xon/Xoff flow control, UniVision changes it, for the duration of th the UniVision session, to be full 8 bits, without 8 bit stripping, and full input and output Xon/Xoff flow control. Use LIST-LINE-CHARS (or its simpler synonym LLC) to display all current line characteristics. In addition, it is possible to list the line characteristics for a single line or range of lines. Use PROTOCOL to set or change line transmission characteristics. PROTOCOL lets you set the baud rate, parity, number of significant bits, and lets you raise or lower the DTR signal as well as monitor or ignore the DTR signal, set X-ON/XOFF protocol, and set other characteristics and protocols for all serial lines except line 0. The system reserves line 0 for the pseudo system console, and so should always be capable of communication with the system. Therefore, you cannot change its baud rate, parity and number of data bits. ! Note: Line/process 0 is the line that runs the initial building of the UniVision parameter files. The syntax is: PROTOCOL line (options) where line is the number of the line whose parameters you want to set, and options are one or more of the following parameters in any order, separated by spaces or commas: baud baud rate. parity parity Data Communications 11-5 bits number of significant data bits. [-]D enables or disables DTR (Data Terminal Ready) flow control (NOT RECOMMENDED) [-]XI enables or disables inward X-ON/X-OFF flow control. [-]XO enables or disables outward X-ON/X-OFF flow control. [-]W enables or disables type-ahead buffer wrap. The system accepts these options as input but UniVision does not action them. [-]B enables or disables the bell signal on input buffer full condition. The system accepts these options as input but UniVision does not action them. [-]C enables or disables CTS flow control. C={0|1} forces the system's RTS output signal level low/high. D={0|1} forces the system's DTR output signal level low/high. (C) clears local input and output buffers. (I) clears local input buffers. (O) clears local output buffers. (K) kills line input and output. BK=<xx> sets an alternative break-key value in hex. This is useful for network users. XI=<xx><xx> sets the XOFF/XON codes for inward flow control in hex. XO=<xx><xx> sets the XOFF/XON codes for outward flow control in hex. B=<xx> sets the alternate bell value in hex. Not yet available. Perhaps the simplest form of PROTOCOL sets the baud rate: >PROTOCOL 3 19200 The preceding statement sets the speed of line 3 to 19200 baud. The next example sets the baud rate on line 3 to 1200 and enables both inward and outward XON/X-OFF protocols: >PROTOCOL 3 1200 XI XO 11-6 A Guide to the UniVision System Refer to the UniVision Command Reference Guide for more details about LISTLINE-CHARS and PROTOCOL. Accessing Communication Lines UniVision handles all serial communication devices in the same manner. A terminal, for instance, connects to a communications port via a serial cable. It communicates with the system across a line linked to a user process. The system directs input to the process and output from the process to that communications line. Thus, line 1 links to process 1. When the user turns on the terminal, the system displays a logon prompt and the Logon processor monitors input on the line. An unlinked line is a line not attached to a process, referred to as an available line. In order for your process to receive input from an available line, you must attach the line to your process. CONVERSE accesses an available communications line. It attaches the line to the current process to enable it to use the line for input and output. Once CONVERSE attaches the line, the process begins to act in a pass-through mode. It sends characters received from the line through the process to the terminal, and characters coming from the terminal through the process to the communications line. In other words, while the process is in CONVERSE mode, it sends what you type at the terminal out to the communications line, instead of the process interpreting it. The process linked to that line on the other system handles input. It sends the output from that process to the system and displays it at the terminal. It continues to send input out from the communications line until you press <ESC X>. This command detaches the line from the process and ends the communication session Example This example shows how you might establish a connection between two systems, A and B. As a result of this connection, a user working on system A is able to log on to system B. First of all, you establish the physical connection: connecting line 5 on system A by direct cable or by modem to line 3 on system B. Link line 3 of system B to process 3. The user is working at a terminal connected to line 2 on system A. There is a link between the status of all lines on system A. This is how to log on to system B, knowing that there is a connection between line 5 on the current system and system B: • Use UNLINK-LINE to unlink line 5 from the process associated with it. This makes it an available line. • Use CONVERSE to attach line 5 to the current process, that is, process 2 connected to line 2. It is now possible to converse to line 5. Data Communications 11-7 • Dialup Connection: If the connection between system A and system B is via modems, you must set up communication with the modem. You must instruct the modem, in its own command language, to dial the other system. On a Hayes-compatible modem, send the string 'ATDT phonenumber'. • Once you have established the connection, the Logon processor on system B sends a logon prompt to the terminal. At the prompt, type the user ID and password. If the logon is successful, system B sends the login message and the terminal receives it. • Log off to end the remote logon session and return to the O/S login. Do this by performing a :QUIT at UCL or by entering OFF at UCL followed by QUIT at the Logon Please prompt. • Disconnect the modem. On a Hayes-compatible modem, enter the command ATH to hang up the modem. • To end the communications session and exit CONVERSE mode, enter the escape sequence <ESC-X> at the terminal. The process interprets the escape sequence, and it detaches line 5 from the current process. (Line 5 remains unlinked.) • Use LINK-LINE to link line 5 to process 5. If you require a more complicated use of a modem line, recommended practice is nd to acquire the outgoing line for sole UniVision use. In the 2 step above substitute ACQUIRE-LINE instead of LINK-LINE. The preceding example shows how to log on to a remote machine using CONVERSE over an RS232 line and a network connection. In addition, you can use software products such as UniComms to conduct the communications session. In addition to providing a remote logon capability, UniComms permits file transfer between UniVision systems. For more details refer to the UniVision UniComms Reference Guide. Changing the State of the Line A line used for communications must be available if you want to use it to initiate a connection with another system. If you want to use the same line to allow the other system to initiate the connection, you must link the line to a process (to provide a user process.) The state of a line, whether linked or available, determines which system can initiate a logon session. For a dialup connection that handles either incoming or outgoing calls, you must change the status of the lines prior to use. To maintain a bi-directional line, users need to have access to LINKLINE and UNLINK-LINE by copying them to their account or by gaining access to SYSPROG. 11-8 A Guide to the UniVision System For example, if you have unlinked line 5 on a system, it means that you can use it to call another system but that system cannot call and get a logon prompt. You can use LINK-LINE to change the state of the line to 'linked', and the system displays a logon prompt. You might decide to keep the communications line linked at all times, except when being used explicitly for dialling out. Or, for security purposes, you might require to keep it as an available line, prohibiting anyone from dialling in. Unlinking and Linking Lines UNLINK-LINE and LINK-LINE are powerful commands that can change the state of any line, you should use them with caution if you copy them to a user's Master Dictionary. UNLINK-LINE breaks a link between a line and the process. In addition, it breaks any attachment between the line and the process. It makes unlinked and unattached lines ‘available’, that is, it is possible to link and attach them to any process. Its syntax is: UNLINK-LINE line line number of the line you want to unlink. When you unlink the line successfully, the system displays the following message: [8012] Line n Unlinked where n is the line you specified. If the line is unlinked or detached already, the system does not display a message when you enter UNLINK-LINE. LINK-LINE links a communications line to a process. It is not possible for the line to be linked or attached to another process already. LINK-LINE line-process [(U)] line number of the line you want to link. process number of the process to which you want to link the link. U breaks any existing link or attachment between the specified line and any other process and links the specified line and process. For example: >LINK-LINE 8-7 [8010] Line 8 linked to process 7 links line 8 to process 7. Data Communications 11-9 Attaching a Line LINE-ATT, which requires SYS1 privileges, attaches the specified line to the current process. When you have attached a line to a process, the process has exclusive use of that line. No other process can use the line for input or output until you detach the line with LINE-DET. LINE-ATT line [(U)] line number of the line you want to attach. U breaks the attachment of any other process to the specified line and attaches that line to the current process. You require SYS2 privileges to use this option. When you attach the line successfully, the system displays the following message: [8013] LINE n ATTACHED where n is the specified line. If you specify a line attached currently or linked to another process, the system displays the following message: [8011] Line in use If the line selected is not a valid RS232 line the system displays the following message. [8015] Illegal line number If you use CONVERSE, there is no need to attach the line as a separate step. The UniVision BASIC statement SEND can direct output to another line, even if you have not attached the line to the user process, providing that you have acquired the line or linked it to a line running UniVision currently. However, GET requires that you attach the line to the process before it can read from that line. Refer to the UniVision BASIC Reference Guide for more information on SEND and GET. Detaching a Line LINE-DET, which requires SYS1 privileges, detaches the specified line from the current process, making the line accessible to other users. LINE-DET line [(U)] line number of the line you want to detach. U breaks the attachment of the specified line to the current or any other process. You require SYS2 privileges to use this option. When you detach the line successfully, the system does not display a message. 11-10 A Guide to the UniVision System If the system has not attached the specified line to the process, it displays the following messages: [1141] NOT ATTACHED! Acquiring a UNIX Line ACQUIRE-LINE obtains UNIX line for later use by UniVision. The syntax is: ACQUIRE-LINE m m specific line number. The UniVision line number requested must relate to an unused UNIX line, that is, if the line is already in use by UNIX or UniVision you cannot acquire it. You use ACQUIRE-LINE prior to UniVision use to prevent UNIX from interfering with the protocol settings of the line when not being used by UniVision. Listing Acquired Lines LIST-ACQUIRED-LINE lists all UNIX lines obtained for use by UniVision. LIST-ACQUIRED-LINE [m[-n]] [(N)] [(P)] m specific line number. m-n range of numbers. If you do not specify line numbers it displays all acquired lines. N disables the paging of the display. P prints the output to the assigned printer. If the line or range is not valid the system displays the following message: [1145] Illegal Specification Number n where n is the invalid number. The following is an example of a typical display of LIST-ACQUIRED-LINE: Line 0000L 0002L 0003LA 0010L Process 0000* 0002 0003 0010 Acq PID 26476 26476 26476 26476 UNIX PID 125791 25541 84308 53619 UNIX Device Name /dev/console /dev/term/002 /dev/term/003 /dev/term/010 If the system only displays the heading it has not acquired any lines. Data Communications 11-11 An explanation of the display is as follows: Line UniVision line number. Process Matching UniVision Process number for a particular UniVision line L Indicates a linked process A Indicates an attached process. * Indicates you are running the verb from your process. Acq PID UNIX Process ID for the Acquired Line Monitor program that runs whenever you acquire a line for UniVision. UNIX PID UNIX Process ID for a particular line as a further crossreference between UNIX and UniVision UNIX Device Name Cross reference to the actual UNIX line connected to the UniVision line. Releasing Acquired Lines RELEASE-LINE releases a line acquired previously by UniVision, using ACQUIRE-LINE, back to UNIX. RELEASE-LINE m m specific line number. RELEASE-LINE releases a line acquired previously by UniVision back to UNIX, whereupon UNIX takes control of that line and resets its line protocol. If the line number is illegal the system displays the following error message. [8015] Illegal line number When the system releases the line to UNIX it displays the following message. [UV8017] Acquired line is released It the system has not acquired the line, that is, released already, the system does not display an error message. Using CONVERSE Once you have established a conversation across an available line, you can use CONVERSE for two-way communications. The syntax is: 11-12 A Guide to the UniVision System CONVERSE line line line you want to attach to your process. In order to attach a line to the process with CONVERSE, the line must be available - that is, no other process can be linked or attached to it. You must have set up transmission characteristics for the line attached with CONVERSE and set up the line linked to the process correctly with PROTOCOL. When you attach the line successfully, the system displays the following message: LINE ATTACHED! and the process is in CONVERSE mode. For example, to unlink and detach line 7 from another process, and attach it to the current process, perform the following: >UNLINK-LINE 7 [8012] Line 7 Unlinked. >CONVERSE 7 LINE ATTACHED! Two-way communication is now possible between the terminal and a device connected to line 7. While in CONVERSE mode, CONVERSE interprets <ESC>. Enter <ESC>-<ESC> to send one <ESC> to the conversed line. To exit CONVERSE mode and return to UCL, press <ESC>, and press X (it must be upper-case X). The system displays the following message when you exit CONVERSE mode: LINE DETACHED! Because CONVERSE accesses data one character at a time, you cannot stack input to this verb in a Proc or UniVision BASIC program. Using BASIC Programs Custom UniVision BASIC programs can make the most of the communication capabilities of UniVision. It is possible for a UniVision BASIC program that uses SEND and GET to send and receive data via the line. It is possible to control what goes on in the user process in addition to controlling what happens over multiple communications lines. Data Communications 11-13 A process can have as many lines as it wants attached to it. Attachment gives the originating process exclusive control over that line; that is, no other process can receive input from or send output to an attached line. Using GET, the originating process can now receive input from two lines, the line originally linked to it and nd the 2 line it has attached to itself. In addition, using SEND, the originating process can send output to any unattached line on the system, even if linked to another process. In addition, you could use a UniVision BASIC program to monitor a communications line. A program might verify that a user has permission to use the modem, offer a selection of the systems it is possible to reach, and submit commands to the modem to dial up the remote system. The following example of a custom data communications program achieves greater security by monitoring access to the modem from the outside. It verifies the ID of the user dialling in and calls the user back. To create this application, it is necessary to set up an account synonym in the SYSTEM Dictionary for an account name DIALUP. It is a Q-pointer to the SYSPROG account: 001 002 003 004 005 006 007 008 009 010 DIALUP Q SYSPROG SYS2 U 17 You use SYSPROG to gain access to LINK-LINE and UNLINK-LINE, but it could be any account that has these verbs available. Next, create a Logon Proc in the Master Dictionary of the account. The following lists the DIALUP: 11-14 A Guide to the UniVision System DIALUP 001 PQ 002 C FRONT END FRO MODEM PORT/PROCESS 003 HMSG !0 I AM ON 004 P 005 RI 006 C BELOW GETS NNP WHERE NN IS MY PORT. 1NNP IS POSSIBLE 007 S1 008 U31AD 009 P 010 HCREATE-FILE 011 A1 012 H 1 5 013 P 014 HLINK-LINE 015 A(1,2) 016 P 017 HDEBUG-OFF 018 P 019 C INVOKE BASIC PROGRAM FRONTEND TO PROMPT USER 020 C WITH FAKE LOGON PROMPT AND VALIDATE ENTRY 021 C THE PROGRAM PLACES THE PORT NUMBER IN THE INPUT 022 C BUFFER AS PARAMETER 2 AND RETURNS THE STATUS AS 023 C "OK" OR "BAD". 024 HRUN BP FRONTEND 025 STON 026 A1 027 P 028 C UPON RETURN, INPUT BUFFER PARAMETER 2 IS PURE NUMERIC 029 HUNLINK-LINE 030 A2 031 P 032 C CHECK INPUT BUFFER PARAMETER 3 FOR "OK"; ELSE MUST BE "BAD" 033 C SO LOGOFF USER 034 IF A3=OK GO 20 035 HMESSAGE !0 IMPROPER ATTEMPT 036 P 037 HOFF 038 P 039 20 CONTINUE 040 C AT THIS POINT, SHOULD RELINK LINE, USING PARAMETER 2 AND 041 C RUN A USER-SUPPLIED PROGRAM DIALBACK THAT SENDS THE 042 C USER-SUPPLIED PHONE NUMBER TO THE MODEM AND MAKES THE CONNECTION 043 C THEN IT MIGHT DROP TO UCL OR RUN AN APPLICATION MENU 044 CHRUN CBP DIALBACK 045 CSTON 046 CA1 047 CP 048 X AT UCL: USE EXIT TO DISCONNECT FROM SYSTEM. 049 C EXIT IS A CUSTOM-PROC WHICH INVOKES THIS PROC You can find a description of what this Proc does shortly. Data Communications 11-15 Next create a Proc in SYSPROG called SETUP-MODEM. You can execute this Proc from UCL. It prompts the user to identify the line and process number connected to the modem. SETUP-MODEM 001 PQ 002 C START A PROCESS FOR THE MODEM. 003 C PROMPTS FOR LINE NUMBER USED BY MODEM, UNLINKS LINE 044 C AND THEN STARTS A PHANTOM PROCESS RUNNING ON THE LINE. 005 C THIS PROC COULD BE RUN FROM UCL OR PLACED IN 006 C USER-COLD-START PROC WITH LINE NUMBER HARD-CODED RI 007 O WHAT LINE/PROCESS+ 008 S1 009 IP 010 IF #A1 XNO ACTION 011 IF A199 XTOO BIG 012 IF A1 # 0 IF A1 # 00 IF A1 # 000 GO 20 013 X NOT ALLOWED ON PORT 0 014 20 CONTINUE. NO CHECKING FOR "LINE IN USE" 015 HUNLINK-LINE 016 A1 017 PP 018 HECHO-OFF 019 A1 020 PP 021 HPROTOCOL 022 A1 023 H+XI,+XO (C) 024 PP 025 HLOGON 026 STON 027 A1 028 H,DIALUP,CUSTOMER 029 PP 030 XSIMPLE EXAMPLE The SETUP-MODEM Proc unlinks the process from the line and sets the line transmission characteristics using PROTOCOL. It logs on the DIAL UP account. Logging in runs the DIALUP Proc. The DIALUP Proc begins by determining what line number the user of the SETUP-MODEM Proc is at. It returns a twodigit number followed by the letter P. Thus it returns 02P if the user is on process 2. It creates a log file under that name. It links that process to the line controlling the modem and the DIALUP Proc invokes the UniVision BASIC program FRONT-END. 11-16 A Guide to the UniVision System FRONTEND 001 * FRONTEND IS SIMPLE EXAMPLE OF A SECURE 002 * PROC BUFFER TO START=NP. COULD ALLOW 1 NNP IF 99 003 * IF OK, BUFFER BECOMES 'NNP NN OK' WHEN DONE 004 PROMPT";CNT=0 005 HELLO='LOGON PLEASE-006 INPUT PORTFILE; * TEMP FILE CREATED BY DIALUP PROC, WHICH ALSO SUPPLIES NAME 007 PORTNUM=FIELD(PORTFILE,'P',1) 008 PROCWRITE PORTFILE:' ':PORTNUM 'R%%':'BAD';*WRITE TO PROC INPUT BUFFER 009 OPEN",PORTFILE ELSE STOP 010 CLEARFILE;* CLEAR OUT ANY OLD ITEMS IF FILE EXISTS 011 WRITE TIMEDATE() ON 'STARTED';* CREATE ITEM NAMED 012 100 * GET RESPONSE 013 PRINT HELLO:;INPUT USER 014 IF USER='ALPHA,BETA,GAMMA' THEN GOTO 200;* VALID LOGIN 015 * GIVE THREE TRIES 016 CNT=CNT+1;IF CNT3 THEN STOP 017 GOTO 100;* GARBAGE ON PHONE LINE? 018 200 * GET PHONE NUMBER FOR CALLBACK 019 PRINT 'ENTER PHONE NUMBER TO RETURN CALL':;INPUT WHERE 020 WRITE WHERE ON 'CALLBACK' 021 PROCWRITE PORTFILE:'':PORTNUM:' OK';* WRITE OK TO PROC INPUT BUFFER 022 STOP 023 END The FRONTEND program prompts the user to supply a valid login ID. It communicates with the DIALUP Proc by placing parameters in the PROC input buffer. If it validates the user, the input buffer contains the string OK, otherwise, it contains BAD. The user is given 3 chances to supply a valid ID. Remember, the logon prompt output by FRONTEND is a fake and not one generated by the system. The idea is to restrict system access via modem to those who know the special access key coded into the FRONTEND program. In this case, it is ALPHA, BETA, GAMMA. If the user supplies the correct access key, the program prompts the user to supply a phone number so that the system can call back. At this point control passes back to the DIALUP Proc, which checks for OK in the primary input buffer. If it is not there, the system logs off the DIALUP account. If it is there, the DIALUP Proc passes control to the DIALBACK program. DIALBACK (not shown) drops the connection and submits a command to the modem to call the user back, using the phone number supplied by the FRONTEND program. Once it has established the connection, the program might exit to UCL or run an application-specific program. These programs have increased the level of security by 1) validating the user; 2) initiating the connection with a remote user; 3) keeping a log of activity on this line. Data Communications 11-17 Refer to the UniVision BASIC Reference Guide for more information on controlling a communication line from a program. Possible Problems These are potential problems to look out for. If someone sends a message to two physically connected machines, that message nd nd goes out the line to the 2 machine. The 2 machine is looking for a user ID and, st st not getting it, this outputs the logon prompt to the 1 machine. The 1 machine nd responds as the 2 did. This is called ping-ponging. Often a user unlinks a line from a process before logging that process on for communications. After logging on, the system links the line and the process begins communicating when the system normally outputs the welcome banner. Typically, UniVision operates in full-duplex mode. The system only displays a character typed on a terminal when UniVision echoes it back. If echo is off and the terminal is in half-duplex mode, the character displayed is due to the terminal. Communications most often require echo to be off unless the transmitting machine expects to get everything back and does not echo it back again - another example of ping-ponging, often interspersed with bells (character 7) when the type-ahead buffer becomes full. 11-18 A Guide to the UniVision System Section 12 B+TREE FILES AND SECONDARY INDEXING A database's storage mechanism must provide a good balance of concurrent A database's storage mechanism must provide a good balance of concurrent access, disk space utilisation and item access time. UniVision bases the traditional storage structure it uses on the static hashed file. The static hashed file storage structure offers extremely quick random access to data, but suffers when there is a requirement for sorted access. In addition, since this storage structure's size is pre-determined at file creation by the user, there is a sacrifice of disk space utilisation or access time as the amount of data in the file changes. The B+Tree storage structure offers solutions to the above problems and has become the defacto standard for storing items into a database file, but creates a new set of performance issues. UniVision uses the latest techniques to address performance as explained later in this Section. Static Hashed Files Static hashed files distribute database items across a user pre-determined number of database file groups based on the item's id. The reason for this distribution is an attempt to keep each group filled with an equivalent number of items and to reduce the number of items that the system needs to search when retrieving the item. Since the system stores the file in many groups, users can access and modify the file concurrently as long as each is in a different group. As long as the user has sized the file properly (the correct number of groups), access to an individual item is extremely quick, usually requiring only a single disk page access. For files that contain a static amount of data, proper sizing is a simple job of analysing the number and size of items stored in the file. For files that contain a varying amount of data, this is not possible. Improperly sized files, waste disk space or require excessive disk activity to process overflowed groups. When sorted access to data is unimportant, hashed files offer a simple solution. In many database applications, order is important, such as reports in alphabetical order. B+Tree Files and Secondary Indexing 12-1 B+Trees Files B+Trees offer solutions to all the issues raised above for static hashed files. B+Trees are dynamic structures that guide the storage mechanism to the proper disk page through a tree-like series of pointers starting at a base page, called the root. Each page, called a node, contains fixed number of entries (called the B+Tree's order) containing information to nodes containing entries with id's either less than or greater than the current node. The last nodes in these series of pointers are called leaf nodes. An important property of B+Trees is that they stay balanced, that is the number of nodes from the root node to each leaf node is the same. The user achieves this by only ever adding new items into leaf nodes. If the leaf node overflows, the system splits the node into two and promotes the middle item to the node above. The system repeats this process node by node up the tree until a node does not overflow. If the root node overflows, the system splits it and places the middle item in a new root node, thus maintaining balance. I C A B F D L E G H J K M O N P Q Figure 12-1: Simple B+Tree 12-2 A Guide to the UniVision System Issues with B+Trees B+Trees offer a great advancement for the storage and access of database data, but they also have some issues: • Wasted Disk Space: Since each node contains a fixed-number of entries, there can be a wastage of disk space if you store smaller items. It is necessary to store larger items indirectly which would waste space in the node as well. • Sorted Access: Although the system stores the data effectively in sorted access, providing sorted access is a complicated procedure of traversing up and down the tree from node to node. • Concurrent Access: Semaphores or locks usually maintain concurrency, because the algorithms for maintaining the balance of the tree requires modification of multiple nodes, the usual method is to lock the entire B+Tree. This method effects concurrent access adversely. UniVision B+Trees UniVision's implementation of B+Trees uses the latest state-of-the-art techniques to address each of the above issues. The way to resolve wasted disk space is by packing entries together using variable-length entries and storing as many entries per node that fit. This results in a different number of entries per node and thus is called a variable-order B+Tree. The user can simplify sorted access by storing all data in the lowest level nodes, called leaf nodes. This technique is known as a B+Tree structure. Since all the data resides in the leaf nodes, a simple link from each leaf node to the next provides a simple sequential sorted access to the data. Thus the upper level nodes of a B+Tree, called branch nodes, form an index to the data in the leaf nodes. Since the branch nodes only serve as an index to the data in the leaf nodes, it is only necessary to store a limited number of keys in the branch nodes. Although this requires additional disk space, it reduces the height of the tree allowing quicker access to the actual data. Since B+Tree branch nodes only provide an index to the data, the user does not have to store the entire key in these nodes. They only have to store enough of the key to identify which branch to take. This technique is known as prefix indexing. This reduction in the size of the keys allows the user to compress the index further thus reducing the amount of disk space required, possibly reducing the height of the tree even further and thus improving the navigation to the data. B+Tree Files and Secondary Indexing 12-3 G C A B E C M I D E F G H K I J O K L M N O Q P Q Figure 12-2: UniVision B+Trees Solutions to the concurrency control issue should be simply matter of locking the next node and releasing the previous node while searching down the tree for a particular item, since the system has effectively separated the data into different nodes. The technique is known as crabbing locks. This technique causes a problem because the algorithms for maintaining balance require the user to modify nodes from the leaf nodes to the root node, thus requiring them to set the locks in the opposite direction. Having locks set in both directions would create a deadlock condition. UniVision addresses this issue by a technique called deferred promotion. When a node overflows, the system splits it into two nodes, but defers the modification of upper level node until the next time the user searches the tree. UniVision's B+Tree implementation uses state-of-the-art advancements to the original concept on B+Trees. By the use of B+Tree techniques, prefix-indexing, crabbing locks and deferred promotion it provides very effective performance, concurrent access and efficient sorted access. 12-4 A Guide to the UniVision System The Need for Secondary Keys When VISION query statements do not detail specific item IDs, it is not possible to identify individual items without performing whole file scans. Of course, this results in poor performance, particularly when the number of items in the result is significantly smaller that the total number of items in the file being queried. For example, imagine a STOCK file where the item ID is the stock line number and one of the attributes details unit price: >LIST STOCK WITH LINE-NUMBER = “120265” specifies a single item ID and thus accesses the desired item directly. >LIST STOCK WITH UNIT-PRICE = “1.00” does not specify any item IDs and thus requires a full scan of all items in the stock file. If the user knows that they are to query specific attributes frequently, such as UNIT-PRICE above, it makes sense to enable direct item access through those attributes rather than always requiring full file scans. In other words, the item ID constitutes the primary method for accessing items quickly within a file, and is, therefore termed the primary key of the file. It should be possible to specify alternate methods of direct access via attributes that appear frequently in VISION queries, such as attributes, are often termed alternate, or secondary, keys. This is the purpose of indexing. Types of Index The following types of index are available: • Hash • Left Justified Index. • Left Justified B+Tree • Right Justified B+Tree Hash Index A hash index gives the best performance where the user uses the attribute they want to index in equality tests, rather than less-than and greater-than comparisons. A hash index is appropriate for any type of attribute justification, that is, it does not matter what is in line nine of the attribute definition. B+Tree Files and Secondary Indexing 12-5 Left-Justified B+Tree A Left-justified B+Tree index gives the best performance where the user references the attribute they want to index in VISION queries that perform lessthan and greater-than comparisons on that attribute. A Left-justified B+Tree stores items in sorted alphabetic order and is thus appropriate for all attribute justifications apart from right justification, which requires numeric rather than alphabetic order. To create a left-justified B+Tree index use the following: >CREATE-INDEX filename attribute-name (B) Right-Justified B+Tree As with the Left-Justified B+Tree index, a Right-Justified B+Tree index is appropriate when VISION queries reference the attribute as part of a less than or greater than comparison. A Right-Justified B+Tree stores items in sorted numeric order and is thus appropriate for only right-justified attributes, that is, where an R appears in line nine of the attribute definition. To created a right-justified B+Tree index use the following: >CREATE-INDEX filename attribute-name (R) Index Administration It is possible to add an index to a file using CREATE-INDEX. The user must create the index before they can build it using BUILD-INDEX. Setting up a secondary index is a two-step process. First, the user must create or define the index using CREATE-INDEX, then they must build the index using BUILD-INDEX. To disable an index, (make it inactive) use DISABLE-INDEX. When the user disables the index the system no longer updates it or uses it in any VISION queries. To enable an index (make it active) use ENABLE-INDEX. The user rebuilds an index to reflect the current state of the attribute it represents using BUILD-INDEX. BUILD-INDEX builds a secondary index from a normal hashed data file. It builds a newly created index for a data file that already contains data. The user deletes an index using DELETE-INDEX. This deletes the index definition and the index table. For more details on the above commands, refer to the UniVision Command Reference Guide. 12-6 A Guide to the UniVision System Section 13 DATABASE TRIGGERS Triggers are BASIC subroutines that control the behaviour of the database system. The programmer attaches BASIC trigger code to a UniVision file on one or more redefined hooks. The filing system executes triggers automatically whenever it encounters one of these hooks, whether it be by the system editor, a BASIC program, or a Visual BASIC client. Triggers maintain history or cross reference files or enforce business rules and database constraints. Triggers are an integral part of UniVision's strategy to provide a feature rich traditional environment with all the tools required for the migration to client-server. Although very important in maintaining the integrity of your data, UniVision triggers are flexible enough to do much more. It is possible to use UniVision's triggers to search history or archive files when an item does not exist in the current live database. Adding Data Integrity to an Application A significant percentage of a typical application program is the enforcement of Business Rules that range from the commercial (for example, value ranges for credit limits) to the procedural (for example, the user wants all updates to the customer file logged to a history file). Traditionally, the user embeds business rules in application code. In many very old applications the user would have duplicated the same code at many points throughout the application, this caused well-known maintenance headaches. In more well considered implementations, the user implements business rules as libraries of subroutines called explicitly at many points throughout the application. Embedding business rules in application code has served us well for many years, however, as applications mature, the user adds new rules, and changes old rules, there is a significant burden on the programmer ensuring that the whole application follows all rules. Furthermore, once the user is outside the protection of the application (in the editor for example) there is simply no way to enforce business rules at all. Without these database constraints the integrity of your data suffers. Database Triggers 13-1 The system should enforce business rules automatically and on a system-wide basis ensuring the integrity of the data. If the user accepts the intent of business rules as the protection of data going into and coming out of the filing system, then the only sensible location for business rules is in the filing system itself. UniVision unlike other multi-dimensional database management systems has a solution to this ongoing problem. The solution is called database triggers. Triggers put business rules and data constraints where they belong; in the database. Trigger Hooks – How They Work Triggers are a series of hooks embedded within the UniVision environment. There are four major categories of hooks: READ, WRITE, DELETE, and READNEXT. Although major category names match BASIC statement keywords, it is possible to invoke triggers throughout the whole of UniVision, not just BASIC. For example, using the editor FI command (which writes an item to disk) executes any applicable WRITE triggers. Similarly, FD (which deletes an item from disk) executes any applicable DELETE triggers. The Trigger hooks are available automatically within the UniVision environment, however, it is the responsibility of the application to build the actual Trigger procedures called by the various database functions or hooks. Within each major category there are a number of specific hooks to which the user can attach triggers: READ Hooks There are three READ hooks available for use before or after a read to the UniVision environment. WAY-BEFORE-READ (WBR) Before starting the read operation and before setting any applicable new item locks and releasing any applicable old item locks. AFTER-SUCCESSFUL-READ (ASR) After reading the required item successfully, and after setting any applicable new item locks and releasing any applicable old item locks. AFTER-FAILED-READ (AFR) After determining that the required item does not to exist and after setting any applicable new item locks and releasing any applicable old item locks. 13-2 A Guide to the UniVision System WRITE Hooks There are five WRITE hooks available for use before, during or after a write, or update, to the UniVision environment. WAY-BEFORE-WRITE (WBW) Before starting the write operation and before setting any applicable new item locks and releasing any applicable old item locks. JUST-BEFORE-INSERT (JBI) After determining that the item to be written does not to exist, that is, this is a new item, and after setting any applicable new item locks but before releasing any applicable old item locks. AFTER-INSERT (AI) After writing the new item to disk and after setting any applicable new item locks and releasing any applicable old item locks released. JUST-BEFORE-UPDATE (JBU) After determining that the item to be written exists, that is, this is not a new item, and after setting any applicable new item locks but before releasing any applicable old item locks. AFTER-UPDATE (AU) After updating the item on disk and after setting any applicable new item locks and releasing any applicable old item locks. DELETE Hooks There are four DELETE hooks available for use before, during or after a Delete to the UniVision environment. WAY-BEFORE-DELETE (WBD) Before starting the delete operation and before setting any applicable new item locks and releasing any applicable old item locks. JUST-BEFORE-SUCCESSFUL-DELETE (JBSD) After locating the item to be deleted and after setting any applicable new item locks but before releasing any applicable old item locks have been. Database Triggers 13-3 AFTER-SUCCESSFUL-DELETE (ASD) After deleting the item from disk and after setting any applicable new item locks and releasing any applicable old item locks. AFTER-FAILED-DELETE (AFD) After determining that the item to be deleted does not exist and after setting any applicable new item locks and releasing any applicable old item locks. READNEXT Hooks There are three READNEXT hooks available for use before or after a readnext operation to the UniVision environment. WAY-BEFORE-READNEXT (WBR) Before starting the READNEXT operation. AFTER-SUCCESSFUL-READNEXT (ASR) After the READNEXT succeeded in returning the next value from the file being iterated. AFTER-FAILED-READNEXT (AFR) After the READNEXT failed because you have exhausted the file being iterated. Anatomy of a Trigger A trigger is a BASIC subroutine that accepts no parameters, but has a single common list, and returns a status value: 001 SUBROUTINE VALIDATE-CUST 002 * 003 $INCLUDE BASICLIB TRIGGER.COMMON 004 * Attribute 5 of an item in the customer file is a count of the number 005 * of orders received to date. 006 * An update which sets the order count below zero is rejected : 007 IF ITEM$<5> < 0 THEN 008 Status = "ORDERS TO DATE < 0" 009 END ELSE 010 * 011 * Valid customer records are copied to a log file 012 * 013 IF LOG.FILE.IS.OPEN = 0 THEN 014 OPEN "CUSTOMER-LOG-FILE" TO LOG.FILE ELSE ABORT 201, "LOG-FILE" 015 LOG.FILE.IS.OPEN = 1 016 END 017 WRITE ITEM$ ON LOG.FILE, ID$ 018 Status = 1 019 END 020* 021 RETURN Status 13-4 A Guide to the UniVision System Trigger Common Area The Trigger common area allows applications programmers a way of passing information between application programs and Triggered procedures. The common area is as follows: COMMON.FILE$ File variable attached to the trigger. FILENAME$ Name of the file to attach to the trigger. ID$ Item ID of the item you are manipulating. ITEM$ Item you are manipulating, not for DELETE triggers. OLDITEM$ Old value of item, for WRITE and DELETE triggers. HOOKTYPE$ Type of trigger hook, for example: AFTER-INSERT RESERVED$(14) Reserved for future use. USER$(80) ! Note: Scratch pad area, can be used by the application. The trigger code can only modify the ITEM$ and USER$(80) variables. All other variables in the common list are 'read-only'. Local Variables The first time the user executes a trigger after opening a file, the system sets all of its local variables to zero. On prior executions, all local variables retain the values they had when the user last executed the trigger. The example above exploits this facility to open a log file the first time it writes a valid item. Return Values A trigger must return a value that evaluates to a positive integer, a negative integer, or zero. ! Note: Any non-numeric string evaluates to zero (such as Status = "ORDERS TO DATE < 0" in the example above). If the return value evaluates to a positive number then the filing system continues with the current READ, WRITE, DELETE, or READNEXT operation as normal. Database Triggers 13-5 If the return value evaluates to zero, the filing system abandons the current READ, WRITE, DELETE, or READNEXT operation immediately and, in the case of BASIC, takes the ELSE path of that operation. If the return value evaluates to a negative number, the filing system abandons the READ, WRITE, DELETE, or READNEXT operation immediately and, in the case of BASIC takes the THEN path of that operation. The BASIC function SYSTEM(223) provides the return value of the most recently executed trigger. ! Note: An error in the execution of a trigger, if for example the trigger does not exist, returns a value of "BAD TRIGGER". Trigger Examples ADD-WRITE-TRIGGER CUSTOMER BP VALIDATE-CUST (WBW Attaches a compiled trigger (BP VALIDATE-CUST) to the way before write hook of the CUSTOMER file. ! Note: If VALIDATE-CUST was a catalogued program, there would be no need to specify the program file (BP) in this command. DISABLE-READ-TRIGGER STOCK (AFR Disables the trigger attached to the after failed read hook of the STOCK file. ENABLE-DELETE-TRIGGER SALES (A Enables all delete triggers for the SALES file. DROP-READNEXT-TRIGGER INVOICES (ASR Drops the trigger from the after successful READNEXT hook of the INVOICES file. Trigger Procedures Verb Definitions The system attaches trigger procedures to hooks on a file based via the following UCL commands: ADD-READ-TRIGGER filename trig (hook filename 13-6 name of the file that engages the triggered procedure that must exist on the current account. A Guide to the UniVision System trig name of the compiled and catalogued UniVision BASIC program that must exist on the current account. hook specifies where the user wants to add the triggered procedure: WBR ASR AFR WAY-BEFORE-READ AFTER-SUCCESSFUL-READ AFTER-FAILED-READ ADD-WRITE-TRIGGER filename trig (hook filename name of the file that engages the triggered procedure that must exist on the current account. trig name of the compiled and catalogued UniVision BASIC program that must exist on the current account. hook specifies where the user wants to add the triggered procedure: WBW JBI AI JBU AU WAY-BEFORE-WRITE JUST-BEFORE-INSERT AFTER-INSERT JUST-BEFORE-UPDATE AFTER-UPDATE ADD-DELETE-TRIGGER filename trig (hook filename name of the file that engages the triggered procedure that must exist on the current account. trig name of the compiled and catalogued UniVision BASIC program that must exist on the current account. hook specifies where the user wants to add the triggered procedure: WBD JBSD ASD AFD WAY-BEFORE-DELETE JUST-BEFORE-SUCCESSFUL-DELETE AFTER-SUCCESSFUL-DELETE AFTER-FAILED-DELETE ADD-READNEXT-TRIGGER filename trig (hook filename name of the file that engages the triggered procedure that must exist on the current account. trig name of the compiled and catalogued UniVision BASIC program that must exist on the current account. Database Triggers 13-7 hook specifies where the user wants to add the triggered procedure: WBR ASR AFR WAY-BEFORE-READNEXT AFTER-SUCCESSFUL-READNEXT AFTER-FAILED-READNEXT The system disables triggers (that is, stopped from firing) via the commands: DISABLE-READ-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to disable. WBR ASR AFR A WAY-BEFORE-READ AFTER-SUCCESSFUL-READ AFTER-FAILED-READ all triggers attached to READ hooks. DISABLE-WRITE-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to disable. WBW JBI AI JBU AU A WAY-BEFORE-WRITE JUST-BEFORE-INSERT AFTER-INSERT JUST-BEFORE-UPDATE AFTER-UPDATE all triggers attached to WRITE hooks. DISABLE-DELETE-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to disable. WBD JBSD ASD AFD A 13-8 WAY-BEFORE-DELETE JUST-BEFORE-SUCCESSFUL-DELETE AFTER-SUCCESSFUL-DELETE AFTER-FAILED-DELETE all triggers attached to DELETE hooks. A Guide to the UniVision System DISABLE-READNEXT-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to disable. WBR ASR AFR A WAY-BEFORE-READNEXT AFTER-SUCCESSFUL-READNEXT AFTER-FAILED-READNEXT all triggers attached to READNEXT hooks. The system re-enables triggers (that is, activated for firing) via the commands: ENABLE-READ-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to re-enable. WBR ASR AFR A WAY-BEFORE-READ AFTER-SUCCESSFUL-READ AFTER-FAILED-READ all triggers attached to READ hooks ENABLE-WRITE-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to re-enable. WBW JBI AI JBU AU A WAY-BEFORE-WRITE JUST-BEFORE-INSERT AFTER-INSERT JUST-BEFORE-UPDATE AFTER-UPDATE all triggers attached to WRITE hooks ENABLE-DELETE-TRIGGER filename ({hook|A} filename Database Triggers name of the file that engages the triggered procedure that must exist on the current account. 13-9 hook specifies the triggered procedure the user wants to re-enable. WBD JBSD ASD AFD A WAY-BEFORE-DELETE JUST-BEFORE-SUCCESSFUL-DELETE AFTER-SUCCESSFUL-DELETE AFTER-FAILED-DELETE all triggers attached to DELETE hooks ENABLE-READNEXT-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to re-enable. WBR ASR AFR A WAY-BEFORE-READNEXT AFTER-SUCCESSFUL-READNEXT AFTER-FAILED-READNEXT all triggers attached to READNEXT hooks The system drops and removes triggers via the commands: DROP-READ-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to remove. WBR ASR AFR A WAY-BEFORE-READ AFTER-SUCCESSFUL-READ AFTER-FAILED-READ all triggers attached to READ hooks DROP-WRITE-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to remove. WBW JBI AI JBU AU A 13-10 WAY-BEFORE-WRITE JUST-BEFORE-INSERT AFTER-INSERT JUST-BEFORE-UPDATE AFTER-UPDATE all triggers attached to WRITE hooks A Guide to the UniVision System DROP-DELETE-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to remove. WBD JBSD ASD AFD A WAY-BEFORE-DELETE JUST-BEFORE-SUCCESSFUL-DELETE AFTER-SUCCESSFUL-DELETE AFTER-FAILED-DELETE all triggers attached to DELETE hooks DROP-READNEXT-TRIGGER filename ({hook|A} filename name of the file that engages the triggered procedure that must exist on the current account. hook specifies the triggered procedure the user wants to remove. WBR ASR AFR A Database Triggers WAY-BEFORE-READNEXT AFTER-SUCCESSFUL-READNEXT AFTER-FAILED-READNEXT all triggers attached to READNEXT hooks 13-11 Section 14 VIRTUAL FILE SYSTEM INTERFACE – EXTERNAL FILE HANDLING Introduction The Virtual File System Interface - eXternal File Handler (XFH) functionality of rd UniVision allows access to data stored with 3 party file handlers. Access is transparent at the UniVision file level, and allows all UniVision processes rd read/write access to 3 party file data directly without any special syntax. UniVision BASIC applications can reference and modify data stored in these files. Functional Description Dynamically loaded XFH drivers provide functionality. A link gives information about the driver location and parameters required to gain access to the required data file. It appears to behave as if the file was a standard UniVision file, thus allowing all UniVision processors access to the data without change. Normally, the user creates a standard UniVision dictionary file to hold the XFH link item and VISION dictionary items so that it is possible to use the selection and report generator on external files. External File Handler Link Item Format Format: 001 002 003 004 005 006 007 008 009 010 linkname Q{X|U} driver-path parameters reserved retrieval-codes update-codes conversion correlative justification width Virtual File System Interface – External File Handling 14-1 Q{X|U} Specifies that item is an XFH link. X defines that the drive provides all necessary locking. U defines that standard UniVision mechanisms should be used in addition to the locking provided by the driver. driver-path Specifies UNIX path to XFH driver. parameters Specifies driver-specific parameters needed to reference the file data referred to by the XFH link. reserved Not used. retrieval-codes Specifies the standard UniVision file retrieval code used on the XFH file. update-codes Specifies the standard UniVision file update code used on the XFH file. conversion Specifies the standard UniVision conversion codes applied to the XFH item-id. correlative Specifies the standard UniVision correlative codes applied to the XFH item-id. justification Specifies the standard UniVision justification applied to the XFH item-id. width Specifies the standard UniVision file width applied to the XFH item-id. External File Handler Driver The user must provide the XFH driver as shared object executable, this must provide functions that support the following interface. 14-2 A Guide to the UniVision System External File Handler Interface The driver MUST provide the following function. The following line must appear at the top of the driver source code #include “Uvxfh.h” All function return one of the following values Return Value Reason UVXFH STATUS SUCCESSFUL Successful completion UVXFH STATUS NOT FOUND Requested item not found UVXFH STATUS LOCKED Requested item locked UVXFH STATUS FATAL Any other error In the following descriptions ‘file’ refers to the XFH-specific data structure that behaves as the UniVision file, and ‘item’ refers to the UniVision formatted data identified by an ‘id’ contained within ‘file’ Open Synopsis int (*Open) (void** ppHandle,char,parameters [ ]); Description Called when the user initiates access and before any other function. The system passes XFH-specific parameters contained in attribute 3 of XFH link item as a null terminated character string. The function needs to return the address of a structure in ppHandle that it passes to all other functions to control access the ‘file’ identified by parameters. Close Synopsis int (*Close) (void* pHandle) ; Description Called when the user no longer needs access to the ‘file’ identified’ by pHandle, they do not need pHandle after this call. If the system allocated the structure pointed to by pHandle dynamically, the user should deallocate it in this function. Clear File Synopsis int (*ClearFile) (*void pHandle) ; Virtual File System Interface – External File Handling 14-3 Description Called when all ‘items’ in the ‘file’ should be deleted Read Synopsis int (*Read) (void* pHandle, char id[], char** ppItem); Description Called when the user requires to retrieve the ‘item’ identified by id from the ‘file’ associated with pHandle. ppItem needs to return the address of buffer containing ‘item’. ReadU Synopsis int (*ReadU) (void* pHandle, char id[], char** ppItem) ; Description Called when the user requests an exclusive lock on an ‘item’ identified by ‘id’ and the ‘item’ they need to retrieve it from the ‘file’ associated with pHandle. ppItem needs to return the address of buffer containing ‘item’. Write Synopsis int (*Write) (void* pHandle, char id []) ; Description Called when the user wants to write the item identified by id on the ‘file’ associated with pHandle. It should release any lock on the ‘item’ identified by ‘id’. WriteU Synopsis int (*WriteU) (void* pHandle, char id [ ]) ; Description Called when the user wants to write the item identified by id on the ‘file’ associated with pHandle. It should maintain an exclusive lock on the ‘item’ identified by id. 14-4 A Guide to the UniVision System Delete Synopsis int (*Delete) (void* pHandle, char id []) ; Description Called when the user wants to delete the item identified by id on the ‘file’ associated with pHandle. It should release any lock on the ‘item’ identified by id. Lock Synopsis int (*Lock) (void* pHandle, char id []) ; Description Called when the user wants to lock the ‘item’ identified by id on the ‘file’ associated with pHandle exclusively. Release Synopsis int (*Release) (void* pHandle, char id []) ; Description Called when the user wants to remove the lock on the ‘item’ identified by id on the ‘file’ associated with pHandle. ReleaseAll Synopsis int (*ReleaseAll) (void* Phandle) ; Description Called when the user wants to remove all locks on ‘items’ locked on the ‘file’ associated with pHandle. IterateStart Synopsis int (*IterateStart) (void* pHandle, char** ppId, char** ppItem) ; Description Called when the user wants to start the sequential retrieval of the ‘ids’ and ‘items’ on the ‘file’ associated with pHandle. ppID needs to return the address of a buffer st containing the 1 ‘id and ppItem needs to return the ‘item’. Virtual File System Interface – External File Handling 14-5 IterateNext Synopsis int (*IterateNext) (void* pHandle, char** ppId, char** ppItem) ; Description Called when the user wants to make the next sequential retrieval of the ‘ids’ and ‘items’ on the ‘file’ associated with pHandle. ppID needs to return the address of st a buffer containing the 1 ‘id and ppItem needs to return the ‘item’. This function always calls IterateStart() before it executes. IterateDone Synopsis int (*IterateDone) (void* pHandle) ; Description Called when the user no longer needs the sequential retrieval of the ‘ids’ and ‘items’ on the ‘file’ associated with pHandle. This function always calls the IterateStart() before it executes when the user no longer needs iteration. External File Handler Support Routines COBOL Record Transfer It is possible to translate COBOL records containing fixed length binary typed fields to and from UniVision records with the help of the methods provided by the ‘Translator’ C++class. Format Definition Specifies the format of the fields so that it is possible to perform conversion between the fixed length binary-type fields and the UniVision delimited ASCIII attributes. The format definition string defines each field with a comma separated field specifier as summarised below: 14-6 A Guide to the UniVision System Type Syntax Alphanumeric Alength Binary B[N]length ‘N’ specifies CPU-specific storage, instead of Most Significant Byte (MSB) first Numeric Display D[L][S]length ‘L’ Notes specifies Leading Sign ‘S’ specifies Separate Sign Floating Point F{1|2} ‘1’ specifies Single precision ‘2’ specifies Double precision Packed Decimal P[S]length Filler +length Offset @offset Multi-field delimiter ID &delimiter ‘S’ specifies Signed key-format only and must be first specifier Special specifiers handle multiple occurrences of a field or fields in the format below. These special format specifiers deal with the conversion of multi-valued field that exist in COBOL as an OCCURS specification. It is possible to use multiple specifiers between the occurrence-start and occurrence-end to deal with the occurrence of records and require that the size of each record be given. Multiple ‘Values’ occurrences may exist within ‘Attribute’ occurrences, and multiple ‘Subvalues’ occurrences may exist within ‘Values’ occurrences as long as the size values include the total of those multiple occurrences. Occurrence-start number[*size],specifiers…occurrence-end occurrence start occurrence end Attribute ( ) Values [ ] Sub-values { } Type Virtual File System Interface – External File Handling 14-7 Storage Representation The binary storage representation of each supported type is as follows: Alphanumeric This is a fixed-length ASCII data field. Translation from this type removes trailing spaces. Translation to this type truncates at length if necessary. Binary Holds numeric data in length byte in pure binary two’s complement format. The system stores the number Most Significant Byte (MSB) first, unless the user uses the Native (N) option, that specifies that they want the number stored in CPUspecific native order. Numeric Display Holds numeric data as ASCII digit characters 0 to 9 one digit per byte of storage. Negative values have bit 6 (hex value ’40) set on the last digit character. If the st user specifies the Leading Sign (L) option, the system sets bit 6 of the 1 digit character of negative values. If the user specifies the Separate Sign (S) option, the system places an ASCII PLUS (+) or MINUS (-) sign in the first or last digit position, depending on the Leading Sign (L) option. Floating Point Holds floating point data in CPU-specific single precision or double precision floating point binary numbers, specified by option 1 or 2 respectively. Packed Decimal Holds numeric data in binary-coded-decimal format. Each byte holds two decimal digits. The system holds the sign, depending on the Signed (S) option, in the last half-byte digit position as a hex value F for unsigned values, hex value C for positively signed values, or hex D for negatively signed values. Program Interface Use of the Translator class requires the following line in the source code #include “Translator.h” In addition, the user must link Translator.0 in the final executable. 14-8 A Guide to the UniVision System TranslateCobolKey Synopsis static boolean_t TranslateCobolKey{ char cobolBuffer[], int cobolBufferSize, char univIdBuffer[], char formatBuffer[]); Description Translates the record key defined by formatBuffer from the record in cobolBuffer with a size of cobolBufferSize to a UniVision item-id in univIdBuffer. The buffer provided by univBuffer must be large enough to accept the largest item-id possible. Diagnostics Returns B_FALSE if an error exists in the syntax of formatBuffer. TranslateUnivId Synopsis static boolean_TranslateUnivID( char cobolBuffer[], int cobolBufferSize, char univIdBuffer[], char formatBuffer[]); Description Translates the UniVision item-id in univIdBuffer to the record key defined by formatBuffer in cobolBuffer with a size of cobolBufferSize. Diagnostics Returns B_FALSE if an error exists in the syntax of formatBuffer or you would exceed the cobolBufferSize. Also sets the maximum UniVision Id buffer size required retrieved by MaximumUnivID(). TranslateCobol Synopsis static boolean_t TranslateCobol( char univBuffer[], char cobolBuffer[], int cobolBufferSize, char formatBuffer[]); Virtual File System Interface – External File Handling 14-9 Description Translates the record data defined by formatBuffer from the record in cobolBuffer with a size of cobolBufferSize to a UniVision item in univBuffer. The buffer provided by univBuffer must be large enough to accept the largest possible Diagnostics Returns B_FALSE is an error exists in the syntax of formatBuffer. TranslateUniv Synopsis static boolean_t TranslateUniv( char cobolBuffer[], int cobolBufferSize, char univBuffer[], char formatBuffer[]); Description Translates the UniVision item univBuffer to the record data defined by formatBuffer in cobolBuffer with a size of coboBufferSize. Also sets the maximum UniVision Item buffer size required, retrieved by the MaximumUnivItem() function. Diagnostics Returns B_FALSE if an error exists in the syntax of formatBuffer or you would exceed the cobolBufferSize. MaximumUnivId Synopsis static int MaximumUnivId(); Description Returns the maximum UniVision Id buffer size possible with the format string passed in formatBuffer to the TranslateUnivID() function Synopsis static int MaximumUnivItem(); Description Returns the maximum UniVision Item buffer size possible with the format string passed in format buffer to TranslateUniv(). 14-10 A Guide to the UniVision System Section 15 SETTING UP A DISTRIBUTED FILING SYSTEM This Section describes how you set up two or more systems to provide access to files across multiple UniVision Environments. You can define a distributed file as any file not resident in the local UniVision database. A distributed file must, therefore, be resident in either of two locations: on another machine or another copy of UniVision on the same machine. UniVision facilitates access to all distributed files via a simple extension to the standard Q-Pointer mechanism. A user simply provides location information for a non-local account (in line two of the Q-Pointer) and specifies the remainder of the Q-Pointer as normal. ! Note: The Distributed Filing System access in UniVision works with the TCP/IP communications protocol. TCP/IP must, therefore, be running on your network. UniVision does not, however, restrict you to any specific lower-level protocol. This facility will work equally well over Ethernet, FDDI, ATM, etc. You need to perform the following steps to set up a Distributed Filing System between two or more systems running the UniVision Environment. • Define the naming characteristics of each system. • Set up the TCP/IP network. • Add required configuration information to the /etc/services file. • Install UniVision on each system. • Set-up the Remote and Local paths between the two systems using the Uvsetup menus. • Start the Server on the remote machine. • Set-up the required Q-pointers in the main UniVision system to access information on the remote system. Setting Up A Distributed Filing System 15-1 Define the Naming Characteristics in Each System To illustrate the set-up of Distributed Filing System and provide consistent examples, we will use an imaginary corporate network. Figure 15-1 shows an example network made up of several nodes together with its topology. System Host Name: univclient IP Address: 199.1.1.101 Real UniVision Name (login): univc Logical UniVision Name: univclientlink System Host Name: univserver IP Address: 199.1.1.102 Real UniVision Name (login): univs Logical UniVision Name: univclientlink The Logical UniVision Name is a label that identifies the TCP/IP connection, for example, univserver link Figure 15-1: Example Network Topology Figure 15-1 is a simple network of two systems. The main system is called univclient (client) and the backup system is called univserver (server). The IP addresses for the system are 199.1.1.101 and 199.1.1.102 respectively. Also, the UniVision login is univc on the univclient system and univs on the univserver system. Set-up the TCP/IP Network To deliver data between two TCP/IP hosts, it is necessary to move the data across the network to the correct host, and within the appropriate host to the correct user or process. The TCP/IP protocol uses three schemes to accomplish this task: 15-2 Addressing IP address, identifying every host on the network uniquely and delivers data to the correct host. Routing Gateways deliver data to the correct network. A Guide to the UniVision System Multiplexing Protocol and port number deliver data to the correct software module within the host. Each of the above functions: addressing between hosts, routing between networks, and multiplexing between layers is necessary to send data between two cooperating applications across the network. Hosts Table The hosts table is a text file associating IP addresses with host names. On most UNIX systems, the table is stored in the file /etc/hosts. Each table entry in /etc/hosts contains the IP addresses and the host names associated with each remote system. IP addresses are usually written as 4 decimal numbers separated by periods. Each of the 4 numbers is in the range 0 to 255 representing the decimal values possible for a single byte. Because the bits that identify class are contiguous with the network bits of the address, it is possible to lump them together and look at the address as composed of full bytes of network address and full bytes of host address. If the first byte of an address is: • less that 128, it is a class A address. The 1 byte is the network number, and the next three bytes are the host address. • from 128 to 191 is a class B address. The 1 two bytes identify the network, and the last two bytes identify the host address. • from 191 to 224 is a class C address. The 1 three bytes are the network address, and the last byte is the host address. • greater than 224, the address is reserved. st st st In our example, Figure 15-1 the IP addresses used are class C addresses. The IP addresses chosen are just an example and might not work within an existing network. Very small sites, not connected to the Internet, can use this configuration. However, systems connected to the Internet or very complex networks require the help of your Network administrator. Network Administration is a topic beyond the focus of this documentation. To assign IP addresses please confer with your Network Administrator or the O/S documentation provided with your system. Another good source of information on Network Administration is a book called TCP/IP Network Administration authored by Craig Hunt and published by O’Reilly & Associates, Inc. ! Note: If you do not set-up the /etc/hosts file at this point the system prompts you to set-up a host address and aliases when using UVsetup menu entry 13, Maintain Local/Remote UniVision Names. Setting Up A Distributed Filing System 15-3 Using the example above, Figure 15-2 shows the /etc/hosts file for the univclient system: # # Table of IP addresses and host names for univclient # 199.1.1.101 univclient 127.0.0.1 localhost me 199.1.1.102 univserver 199.1.1.10 JohnsPC 199.1.1.11 MikesPC Figure 15-2: The /etc/hosts File on the System Called univclient Figure 15-3 shows the /etc/hosts file for the univserver system: # # Table of IP addresses and host names for univserver # 199.1.1.102 univserver 127.0.0.1 localhost me 199.1.1.101 univclient 199.1.1.10 JohnsPC 199.1.1.11 MikesPC Figure 15-3: The /etc/hosts File on the System Called univserver ! Note: The LOCAL UniVision definition defaults to an alias called me. In order for the communications process to work, add the me alias to the localhost or loop back IP address. If you fail to add this alias, you will not be able to start the Server (:START-MASTER-SERVER) on the univserver system. Set-up the pse.conf File ! Note: This file set-up is required for AIX-Based systems. If you are setting up a Non-AIX system, skip to testing the IP connection. The pse.conf file is located in the /etc directory. This file must be set-up in order to get TCP/IP connections working properly on an AIX-based system. Using the cat command or vi editor verify the PSE communication protocols are set-up properly. 15-4 A Guide to the UniVision System # PSE drivers d+ d+ d+ d+ dlpi dlpi dlpi dlpi en et tr fi /dev/dlpi/en /dev/dlpi/et /dev/dlpi/tr /dev/dlpi/fi #streams #streams #streams #streams dlpi dlpi dlpi dlpi ethernet driver 802.3 driver token ring driver FDDI driver # PSE communication protocols d+ d+ d+ d+ xtiso xtiso xtiso xtiso unixdg unixst udp tcp /dev/xti/unixdg /dev/xti/unixst /dev/xti/udp /dev/xti/tcp # # # # unix domain datagrams unix domain byte-stream UDP/IP TCP/IP # PSE modules m m timod tirwr #TLI module #TLI read/write interface If any of the above lines is commented out by having a # character at the beginning of the line, remove the # and reboot the system. Should you require further assistance please check with your network administrator or AIX documentation. Test the IP Connections Before proceeding to the next step, test to assure the network is configured properly and all cables are connected properly. This can be accomplished by using ping. ping is a UNIX network utility that indicates whether a remote host can be reached. In addition, ping displays statistics about the packet loss and deliver time. Using the example above, pinging or testing the univserver system can be accomplished by typing ping 199.1.1.102 or ping univserver from either systems. Any failures show that a problem exists with the network or the cables are not installed properly. In addition, after you have successfully pinged both systems, you can use telnet to make sure network application software is working properly. For example, you can use telnet univserver from the root prompt on the univclient system to test the software and connections between the two systems. Any failures must be corrected before going to the next step. Install UniVision on Each System The next step is to load UniVision on each system. This is accomplished by following the installation instructions in the UniVision Installation Instructions & Administration Guide provided with the software media. Setting Up A Distributed Filing System 15-5 The only exception, for clarity is to change the UniVision login name. This is accomplished by changing the installation path which is the first question after entering the pkgadd command. ! Note: The installp command in AIX does not allow you to create different logins for UniVision. Therefore, only the standard UniV login is supported. Using the example in Figure 15-1, during UniVision Installation, the prompt UniVision installation path? (default:/home/UniVision)[?,q]. requires the following responses: System Response Login univclient /home/UniVision/univc univc univserver /home/UniVision/univs univs ! Note: You can use the default path of /home/UniVision and still maintain the default login of UniV. However, by having different logins (and passwords) allows for easier administration of the systems. (The difference in this documentation is for clarity only. You are not required to have different logins.) Add Configuration Information to the /etc/services File The UniVision Environment requires a definition in the /etc/services file on both the client, univclient, and server, univserver, system. This is accomplished by using the vi editor and adding the following: # # UniVision Services # UniVision 12345/tcp The word UniVision and tcp are required. The UniVision configuration number can be any five-digit numeric number and must be the same on both systems. For example, Figure 15-4 shows that the univserver system should have the following added to the /etc/services file. ! Note: 15-6 If you do not set-up the /etc/services file at this point, the system prompts you to set-up UniVision services when using UVsetup menu entry 13, Maintain Local/Remote UniVision Names. A Guide to the UniVision System # # Network services, Internet style # echo 7/tcp echo 7/udp discard 9/tcp sink null . . . host_table 468/udp # # Unix specific services # . . . bootpc 68/udp listen 9100/tcp listen 2766/tcp # # UniVision Services # UniVision 12345/tcp Figure 15-4: The /etc/services File on the System Called univserver ! Note: The above example is a copy of the /etc/services file on an AT&T/NCR system. Each system requires different services so do not change this file. Just add to the bottom (or top) the lines in the above example in bold. Set-up the Remote and Local Paths The next step involves setting up the link between the two systems, the client machine and the server machine. This example uses the following names for the two machines, univclient for the client and univserver for the server. The client machine, does not have any files stored on it, whereas the server machine does. The next step is required on both systems. You must set-up both the remote_univision_name and local_univision_names files on both systems. When UniVision is installed, the local_univision_names file is automatically setup on both the univclient and univserver systems as shown in Figure 15-5. Since UniVision sets up this file automatically, this display is added for clarity. ! Note: Before making any changes to remote_univision_names file, make sure the /home directory has write permissions for other. If not, please use chmod to change the permissions of the /home directory. Setting Up A Distributed Filing System 15-7 Maintain Local/Remote UniVision Names (E)xit ------------------ Maintain -----------------(I)dentity Name (L)ocal Names (R)emote Names :- L The format for the "/home/local_univision_names" file is: Logical UniVision Name:Real UniVision Name@ System Host Name:Optional Comment The contents are: <1> univc:/home/UniVision: (E)xit (D)elete (A)dd :-E Figure 15-5: Display of the Local Names on the univserver System You are required to set-up the remote_univision_name file on both univclient and univserver systems. This is accomplished by continuing with the same program in UVsetup menu entry 13, Maintain Local/Remote UniVision Names. ! Note: The system being used as the Server system must have a Logical UniVision Name of LOCAL. Figure 15-6, is a display of the program and entries required to create the remote_univision_name file on the univserver system. In order to set the file properly you need to answer three questions: Logical UniVision Name The name you want to give to the link from the main system to the remote. In our sample configuration, univserver is the server so you must call it LOCAL. Real UniVision Name The normal login from UNIX into the UniVision environment on the univserver system. Our example loaded UniVision into the univs directory, therefore, the login is univs and the response to this field can only be univs System Host Name The system name entered in the /etc/hosts file. In our example the system name is univserver. ! Note: 15-8 The Server is on the univserver system, the Logical UniVision Name on the univserver system must be entered as LOCAL. A Guide to the UniVision System (E)xit Maintain Local/Remote UniVision Names ------------------ Maintain -----------------(I)dentity Name (L)ocal Names (R)emote Names :- R The format for the "/home/local_univision_names" file is: Logical UniVision Name:Real UniVision Name@ System Host Name:Optional Comment The contents are: <1> LOCAL:univs@me: (E)xit (D)elete (A)dd :- D Enter line <number> of Name to delete :- 1 Delete: LOCAL:UniV@me: Are you sure? (Y/N) :- Y There is an entry for "me" in "/etc/hosts" as follows:127.0.0.1 me loopback localhost Do you also want to delete this entry? (Y/N):- N "/etc/hosts" not modified. Press any key to continue.<RETURN> The file is empty or does not exist. (E)xit (A)dd :- A Enter the Logical UniVision Name (ESC to exit):- LOCAL Enter the Real UniVision Name (ESC to exit):- univs Enter the System Host Name (ESC to exit):- univserver Enter an optional Comment:- Local Server on univserver link on univserver system There is an entry for "univserver" in "/etc/hosts" as follows:199.1.1.103 univserver Please check that these details are correct. Press any key to continue. <RETURN> The format for the "./univision/admin/remote_univision_names" file is: LogicalUniVisionName:RealUniVisionName@SystemHostName:Optional Comment The contents are: <1> LOCAL:Univs@univserver:Local univserver link on the univserver system (E)xit (D)elete (A)dd :-E Figure 15-6: Addition of the Remote Names on the univserver System Setting Up A Distributed Filing System 15-9 When UniVision is installed, the local_univision_names file is automatically setup on the univserver system as shown in Figure 15-7. Since UniVision sets up this file automatically, this display is added for clarity. Maintain Local/Remote UniVision Names (E)xit ------------------ Maintain -----------------(I)dentity Name (L)ocal Names (R)emote Names :- L The format for the "/home/local_univision_names" file is: Logical UniVision Name:Real UniVision Name@ System Host Name:Optional Comment The contents are: <1> univs:/home/UniVision: (E)xit (D)elete (A)dd :-E Figure 15-7: Display of the Local Names on the univserver System Figure 15-8, is a display of the program and entries required to create the remote_univision_name file on the univclient (client) system. In order to set the file properly you need to answer three questions: Logical UniVision Name The name you want to give to the link from the main system to the remote. In our sample configuration, we are calling the link univclientlink. Real UniVision Name The normal login from UNIX into the UniVision environment on the univserver system. Our example loaded UniVision into the univs directory, therefore, the login is univs and the response to this field can only be univs. System Host Name The system name entered in the /etc/hosts file. In our example the system name is univserver. You are on the client system and attempting to access files on the server system, therefore the Real UniVision Name is the Login from UNIX to UniVision on the Server system, that is, univs, and the System Host Name is the Host Name of the Server system, that is univserver. 15-10 A Guide to the UniVision System (E)xit Maintain Local/Remote UniVision Names ------------------ Maintain -----------------(I)dentity Name (L)ocal Names (R)emote Names :- R The format for the "/home/local_univision_names" file is: Logical UniVision Name:Real UniVision Name@ System Host Name:Optional Comment The contents are: <1> LOCAL:univc@me: (E)xit (D)elete (A)dd :- D Enter line <number> of Name to delete :- 1 Delete: LOCAL:Univc@me: Are you sure? (Y/N) :- Y There is an entry for "me" in "/etc/hosts" as follows:127.0.0.1 me loopback localhost Do you also want to delete this entry? (Y/N):- N "/etc/hosts" not modified. Press any key to continue.<RETURN> The file is empty or does not exist. (E)xit (A)dd :- A Enter the Logical UniVision Name (ESC to exit):- univclientlink Enter the Real UniVision Name (ESC to exit):- univs Enter the System Host Name (ESC to exit):- univserver Enter an optional Comment:- univclient link on univclient system There is an entry for "univserver" in "/etc/hosts" as follows:199.1.1.101 univclient Please check that these details are correct. Press any key to continue. <RETURN> The format for the "./univision/admin/remote_univision_names" file is: LogicalUniVisionName:RealUniVisionName@SystemHostName:Optional Comment The contents are: <1> univclientlink:Univs@univclient:univclient link on univclient system (E)xit (D)elete (A)dd :-E Figure 15-8: Addition of the Remote Names on the univclient System Setting Up A Distributed Filing System 15-11 Start the Server on the Remote Machine On the remote machine called univserver, you need to start the UniVision Server. You accomplish this by logging to SYSPROG and typing :START-MASTERSERVER at the UCL prompt. The Master Server allows users on the main system called univclient to access data on the remote system called univserver. ! Note: You must stop the server, using :STOP-MASTERSERVER before you shut-down the system. If you do not you cannot re-enter UniVision without resetting the processor. Set-up the Required Q-Pointers To access files on the remote system called univserver you need to create Qpointers on the main system called univclient. This is accomplished by logging in to the appropriate account on the univclient system and at UCL enter a Q-pointer as follows: Attr# Definition Example 0 Q-pointer key CUSTOMERS 1 Q Q 2 Account-name@ Logical-Remote-name ACCOUNT@univclientlink 3 Filename CUSTOMER 4 Not used 5 Retrieval lock 6 Update lock 7 Conversion specification 8 Not used 9 Justification L 10 maximum field length 10 Process Size Limits You must ensure that there are sufficient server processes, to achieve this you should use option 10 of UVsetup. 15-12 A Guide to the UniVision System ! Note: For details of this option refer to the section entitled Maintain Process Size Limits in the Section entitled UniVision Administration Utility. You should allow at least one server process for each user process that is to use a Remote File in the Distributed Filing System. For example, if the system has 100 users of which, 35 are using the Distributed Filing System at any given time, you should set: • size 140 • servers 40 At worst, although this is overkill, double the number of users, for example: • size 200 • servers 100 Remote Files in UniVision Assume that there are two machines, one in London (local) and one in New York (remote), and the user is located in London, before they can access files on the machine in New York they must have set up the following: In the directory /etc/hosts on both the local and remote machines enter: internet-address aliases comments internet-address internet address of the machine in the form nnn.n.n.nn. aliases name of the internet address. comment any comment relevant to the machine. Example Assume that the machine in London has the internet address 192.1.1.90 with the alias LDS10, and the machine in New York has internet address 192.1.1.91 with the alias NYS10, the user would set up the following in the directory /etc/hosts: 192.1.1.90 LDS10 192.1.1.91 NYS10 Testing the Link To test the linking is operating use telnet or ping. telnet aliases ping internet-address Setting Up A Distributed Filing System 15-13 internet-address internet address of the machine in the form nnn.n.n.nn. aliases name of the internet address. Example Using the internet addresses and aliases of the previous example use the following. telnet LDS10 or ping 192.1.1.90 telnet NYS10 or ping 192.1.1.91 Once complete the user should set up the following in the directory /etc/services on both machines. Insert UniVision num num unique five digit decimal number that does not exist, this must be the same on all machines. Example /etc/services UniVision 12345/tcp Accessing Remote Files On the local machine the directory: /directory/Uvname/univision/admin/remote_univision_names should contain: logical-name:remoteUV@remote-internet-address directory full pathname to the directory where UniVision is installed on the local machine. Uvname name of UniVision on the local machine. logical-name logical name of the file on the remote machine. remoteUV name of UniVision on the remote machine. remote-internet-address internet address of the remote machine. On the remote machine the directory: /home/local-univision-names 15-14 A Guide to the UniVision System should contain: remoteUV:directory: remoteUV name of UniVision on the remote machine. directory full pathname to the directory where UniVision is installed on the remote system. The directory: /directory/Uvname/univision/admin/remote_univision_name should contain: LOCAL:logical-name@aliases directory full pathname to the directory where UniVision is installed on remote machine. Uvname name of UniVision on the remote machine. logical-name logical name of the file on the remote machine. aliases name of the internet address. Local Machine At the following prompt: LOGON PLEASE: enter the name of the account from which the user wants to access the remote machine. When the system displays the UCL prompt (>)enter the following: ED MD logical name logical-name logical name of the file on the remote machine. This should contain: 001 Q 002 rem-account@logical-name 003 rem-file where: rem-account account name on the remote machine. logical-name logical name of the file on the remote machine. rem-file file name on the remote machine. Setting Up A Distributed Filing System 15-15 On Remote Machine At the following prompt: LOGON PLEASE: enter SYSPROG at the UCL prompt (>) enter :START-MASTER-SERVER Listing Remote Files To obtain a listing of a file from the remote machine enter LIST logical-name logical-name logical name of the file on the remote machine. Example Assume that the local machine is in London, UniVision is installed in the directory ‘unistore’, and UniVision is known as Lduniv. The remote machine is located in New York, UniVision is installed in the directory /unistore/Nyuniv, UniVision is known as Nyuniv, the logical name of the file is NYOREDERS, the remote account name is WINDEMO and the remote file name is ORDERS. The following should be set up LONDON The directory: /unistore/london/univision/admin/remote_univision_names should contain: NYORDERS:Nyuniv@LDS10 NEW YORK The directory: /home/local_univision_name should contain: Nyuniv/unistore/Nyuniv: The directory /unistore/NYUNIV/univision/admin/remote_univision_names 15-16 A Guide to the UniVision System should contain: LOCAL:NYORDERS@NYS10 Accessing Files LONDON LOGON PLEASE: SYSPROG >ED MD ORDERS 001 Q 002 WINDEMO@NYORDERS 003 ORDERS .FI NEW YORK LOGON PLEASE: SYSPROG >:START-MASTER-SERVER Listing Files LIST NYORDERS Setting Up A Distributed Filing System 15-17 A Guide to the UniVision System Index ! .A command .C command Options .E command .G command .K command .L command .M command .MU command .O command .P command .Q command .R command .S command .U command .X command .Z command :AUTHORISE verb :FILELOAD verb :INIT-DISK verb :INIT-SYSTEM verb :INIT-TAPE verb :START-MASTER-SERVER verb :STARTSPOOLER verb :STOP-MASTER-SERVER verb ? option @ phrase Creation @TCL << verb >> verb 6-22 6-22 - 6-24 6-22 - 6-23 6-21 6-21 6-24 2-10 - 2-11, 6-19 - 6-20 6-21 - 6-22 6-21 - 6-22 6-25 6-25 6-25 6-24 6-25 6-25 2-10 - 2-11, 6-20 6-25 8-3 8-5 8-4 8-4 8-4 15-12 8-3, 9-5, 9-6 - 9-7 8-5 9-14 3-15 8-15 6-15, 8-5 6-15, 8-5 A A option ACC file Index 9-15 8-10 Index-i Access communication lines Acquire UNIX line Attach line Change state of line Detach line List acquired line Release acquired lines Unlink and link lines Access remote files Access files List remote files Local machine Remote machine Access tape drive Access to SYSPROG account Account Account definition items Creation Deletion File synonym items User Account definition items Account options Attributes Base Definition code Item ID Modulo Password Privilege level Reallocation Retrieval codes Update codes User process code Width Account management SYSPROG account SYSPROG commands SYSTEM dictionary Account management commands Account options Account definition items Account synonym items Account Attributes Definition code Item ID Account usage statistics CHARGES verb CHARGE-TO verb Index-ii 11-7 - 11-12 11-11 11-10 11-8 - 11-9 11-10 - 11-11 11-11 - 11-12 11-12 11-9 15-14 - 15-17 15-17 15-16 - 15-17 15-15 15-16 10-3 - 10-5 8-1 - 8-2 1-8 4-8 2-1 - 2-2, 8-6 8-6 4-12 2-1 - 2-19 4-4 - 4-7, 4-12 - 4-15, 8-8 4-6 - 4-7 4-4 - 4-7 4-4 4-4 4-4 4-5 4-5 4-6 4-7 4-5 4-5 4-7 4-7 8-1 - 8-15 8-1 - 8-2 8-2 - 8-5 8-8 - 8-12 8-3 4-6 - 4-7 4-8 4-8 4-8 4-8 4-8 8-7 - 8-8 8-7 - 8-8 8-7 - 8-8 A Guide to the UniVision System ACCOUNT-RESTORE verb ACCOUNT-SAVE verb Acquire UNIX line ACQUIRE-LINE verb Add configuration information to /etc/services file Add data integrity to application Add triggers ADD-ACCOUNTS verb ADDD verb ADD-DELETE-TRIGGER verb ADD-READNEXT-TRIGGER verb ADD-READ-TRIGGER verb ADD-WRITE-TRIGGER verb ADDX verb Advance to end-of-data AMC Analysing file structure Anatomy of trigger Local variables Return values Trigger common area Trigger examples Append data to tape Append text Assign item ids Assign spooler specifications Associate multi-valued attributes Attach cartridge tape unit Attach line Attach tape device Attribute Attribute definition items Attibutes Attribute number Conversions Correlatives Definition code Item ID Justification Structure Tag Width Attribute mark Attribute number Attribute definition items Attributes Account definition items Account synonym items Attribute definition items File definition items File synonym items Index 7-26, 8-5 7-26, 8-5 11-11 5-8, 11-2, 11-11 15-6 - 15-7 13-1 - 13-2 13-6 - 13-8 8-5 6-16 13-7 13-7 - 13-8 13-6 - 13-7 13-7 6-16 10-26 1-8 7-20 13-4 - 13-6 13-5 13-5 - 13-6 13-5 13-6 10-10 6-22 3-12 9-13 - 9-18 3-9 10-23 - 10-24 11-10 10-22 - 10-23 1-8 2-12 4-13 4-13 4-14 4-14 4-13 4-13 4-14 - 4-15 4-14 4-14 4-15 1-8 3-8 4-13 4-4 - 4-7 4-8 4-13 4-9 - 4-11 4-12 Index-iii AUTO-LOGOFF verb Options Automatic logoff AUTO-LOGOFF verb 6-4 - 6-5, 8-3 6-4 - 6-5 6-4 - 6-5 6-4 - 6-5 B B option B+Tree files B+Tree files and secondary indexing B+Tree files Index administration Issues with B+Trees Need for secondary keys Static hashed files Types of index UniVision B+Trees Backup Base Account definition items File definition items Basic operation of spooler Command summary Forms Hold files Print files Printers Summary of spooler features Block size 1/2-inch tape 1/4-inch tape 4mm DAT tape 8mm DAT tape CD-ROM device tape Diskette device tape BLOCK-CONVERT file BLOCK-PRINT verb BREAK key BUILD-INDEX verb BUILD-LOCK-XREF verb BUILD-TR-INDEX verb 9-15 12-2 12-1 - 12-5 12-2 12-6 12-3 12-5 12-1 12-5 12-3 - 12-4 7-26 1-8 4-4 4-10 9-1 - 9-6 9-5 - 9-6 9-2 - 9-4 9-4 - 9-5 9-4 - 9-5 9-2 - 9-4 9-6 10-18 10-18 10-18 10-18 10-18 10-18 10-18 8-11 6-15 2-9 - 2-10 12-6 8-4 8-4 C Cancel active print jobs Cancel print jobs Cancel active print jobs Remove printer from system Retain print files as hold files Index-iv 9-21 - 9-22 9-21 - 9-23 9-21 - 9-22 9-22 - 9-23 9-22 A Guide to the UniVision System Catalogued UniVision BASIC programs Change printer's form queue Change state of line CHARGES verb CHARGE-TO verb Check print queue Check status of printers Choose command to modify Clear file CLEAR-FILE verb CLEAR-GROUP-LOCKS verb COBOL record transfer Alphanumeric Binary Floating point Format description MaximumUnivId Numeric display Packed decimal Program interface Storage representation TranslateCobol TranslateCobolKey TranslateUniv TranslateUnivId Column heading Column width Command summary Communications line settings COMPARE verb Configure printers Change printer's form queue Initialise parallel printer Initialise serial printer Restart stopped printer Contents of SYSPROG account Controlling and dependent specifications CONVERSE verb Possible problems Using BASIC programs Conversions Attribute definition items File definition items Convert hold file to data file Copy file items Copy print file from tape Copy SYSPROG commands COPY verb Options Index 6-18 9-8 - 9-9 11-8 - 11-9 8-7 - 8-8 8-7 - 8-8 9-18 - 9-21 9-9 - 9-11 6-21 7-6 - 7-7 7-1, 7-6 - 7-7 8-4 14-6 - 14-9 14-8 14-8 14-8 14-6 - 14-7 14-10 14-8 14-8 14-8 14-8 14-9 14-9 14-10 14-9 3-9 3-10 - 3-11 9-5 - 9-6 6-5 - 6-6 8-5 9-7 - 9-9 9-8 - 9-9 9-8 9-8 9-9 8-2 4-20 - 4-21 5-8, 11-2, 11-12 - 11-17 11-18 11-13 - 11-17 3-9 4-14 4-10 9-28 - 9-29 7-8 - 7-11 9-31 - 9-32 8-5 - 8-6 6-17, 7-2, 7-8 - 7-11 7-8 - 7-9 Index-v Correlatives Attribute definition items File definition items Correlatives and conversions Date format Dollar amounts format Format dates Format dollar amounts Format times Manipulate existing data Stored format and output format Time format Translate data from another file CPU Create @ phrase Create account Create data file Create data items Assign item ids Create database Create database application Create dictionary Create dictionary entries Associate multi-values attributes Attribute number Column heading Column width Conversions Correlatives Identify entry Justification Name attribute definition item Create dictionary items in numeric sequence Create file Create data file Create dictionary Create dictionary entries Create file in target account Create new database Create UniVision BASIC files Select filename Select modulo Create file in target account Create file synonyms Create Q-pointers SET-FILE verb Create new database Create Q-pointers Create UniVision BASIC files CREATE-ACCOUNT verb Index-vi 3-9 4-14 4-10 4-21 - 4-25 4-23 4-22 - 4-23 4-23 4-22 - 4-23 4-23 4-23 - 4-24 4-21 - 4-23 4-23 4-25 1-8 3-15 2-1 - 2-2, 8-6 7-4 - 7-5 3-11 - 3-12 3-12 3-1 - 3-15 3-15 7-4 3-6 - 3-11 3-9 3-8 3-9 3-10 - 3-11 3-9 3-9 3-7 - 3-8 3-10 3-7 3-15 3-2 - 3-12, 7-3 - 7-6 7-4 - 7-5 7-4 3-6 - 3-11 7-6 7-5 - 7-6 7-6 3-3 3-3 - 3-4 7-6 7-14 - 7-16 7-14 - 7-15 7-15 - 7-16 7-5 - 7-6 7-14 - 7-15 7-6 8-3, 8-6 A Guide to the UniVision System CREATE-BFILE verb CREATE-FILE verb Options CREATE-INDEX verb CT verb 7-6 3-4 - 3-5, 7-1, 7-3 - 7-6 7-4 12-6 6-18 D Data communications Access communication line Command summary Make connection Overview Set line characteristics and protocols Data file Creation Data files Data items Creation Database Creation Design Database application Creation Database architecture Database management system Database triggers Add data integrity to application Anatomy of trigger Hooks Date format DE verb Options DEBUG-OFF verb DEBUG-ON verb Define default output specifications Create @ phrase Create dictionary items in numeric sequence Define naming characteristics in each system DEFINE-CURSOR verb Definition code Account definition items Account synonym items Attribute definition items File definition items File synonym items Delete account Delete file DELETE hooks Index 11-1 - 11-17 11-7 - 11-12 11-2 11-3 11-1 - 11-2 11-3 - 11-7 1-8 7-4 - 7-5 4-4 3-11 - 3-12 1-8 3-1 - 3-15 3-1 - 3-2 3-15 4-1 - 4-25 5-1 - 5-11 13-1 - 13-11 13-1 - 13-2 13-4 - 13-6 13-2 - 13-4 4-23 6-17, 7-11 - 7-12 7-11 - 7-12 6-16 6-16 3-14 - 3-15 3-15 3-15 15-2 8-4 4-4 4-8 4-13 4-9 - 4-10 4-12 8-6 7-7 - 7-8 13-3 - 13-4 Index-vii Delete items Delete multiple hold files Delete statement from stack DELETE verb DELETE-ACCOUNT verb DELETE-FILE verb DELETE-INDEX verb Design database Destination options Detach line Detach tape unit DEVICE-DETAILS file DEVICE-ERRORS file DEVICE-NAMES file Dictionaries File Master SYSTEM Dictionary Creation Dictionary entries Creation Dictionary items Account definition items Attribute definition items File definition items Verb definition items Dictionary items in numeric sequence Creation Disable triggers DISABLE-DELETE-TRIGGER verb DISABLE-INDEX verb DISABLE-READNEXT-TRIGGER verb DISABLE-READ-TRIGGER verb DISABLE-WRITE-TRIGGER verb Distributed filing system Access remote files Add configuration information to /etc/services file Define naming characteristics in each system Install UniVision on each system Process size limits Remote files in UniVision Set up Set up remote and local paths Set up required Q-pointers Set up TCP/IP network Start server on remote machine Test link DIVD verb DIVX verb Index-viii 7-12 - 7-13 9-30 6-24 7-2, 7-12 - 7-13 8-3, 8-6 7-1 - 7-2, 7-7 - 7-8 12-6 3-1 - 3-2 9-15 - 9-16 11-10 - 11-11 10-23 8-11 8-11 8-11 4-3 - 4-4 4-3 4-3 1-8 7-4 3-6 - 3-11 4-4 - 4-16 4-4 - 4-7 4-12 - 4-15 4-9 - 4-11 4-9 3-15 13-8 - 13-9 13-8 12-6 13-9 13-8 13-8 15-14 - 15-17 15-6 - 15-7 15-2 15-5 - 15-6 15-12 - 15-13 15-13 15-1 - 15-17 15-7 - 15-11 15-12 15-2 - 15-5 15-12 15-13 - 15-14 6-16 6-16 A Guide to the UniVision System DOC-EDIT verb Options Dollar amounts format DROP-DELETE-TRIGGER verb DROP-READNEXT-TRIGGER verb DROP-READ-TRIGGER verb DROP-WRITE-TRIGGER verb DTR verb DTX verb Dump file to tape DUMP verb Options 6-17, 7-11 - 7-12 7-11 - 7-12 4-22 - 4-23 13-11 13-11 13-10 13-10 6-16 6-16 10-5 - 10-7, 10-27 - 10-28 5-2 - 5-3, 6-15, 8-4 5-2 - 5-3 E ECHO verb ECHO-OFF verb ECHO-ON verb ED verb Options Edit command line Edit item Edit stack EDIT verb Options Enable stacker ENABLE-DELETE-TRIGGER verb ENABLE-INDEX verb ENABLE-READNEXT-TRIGGER verb ENABLE-READ-TRIGGER verb ENABLE-WRITE-TRIGGER verb Enter UCL command Erase selected tape drives ERRMSG file Format of ERRMSG items Examine account List contents of items List files Examine contents of tape Examine group in close detail Execute previous statements Exit UniVision environment External file handler driver External file handler interface External file handler interface Clear File Close Delete IterateDone Index 6-15 6-16 6-16 6-17, 7-2, 7-11 - 7-12 7-11 - 7-12 2-8 - 2-9 7-11 - 7-12 6-21 6-17, 7-2, 7-11 - 7-12 7-11 - 7-12 6-19 13-9 - 13-10 12-6 13-10 13-9 13-9 2-8 10-27 8-11, 8-13 - 8-15 8-13 - 8-15 2-12 - 2-17 2-14 - 2-17 2-13 - 2-14 10-29 - 10-30 7-22 - 7-24 6-20 2-5 14-2 - 14-6 14-3 - 14-6 14-3 - 14-4 14-3 14-5 14-6 Index-ix External file handler interface (Continued) IterateNext IterateStart Lock Open Read ReadU Release ReleaseAll Write WriteU External file handler link item format conversion correlative driver-path justification parameters Q{X|U} retrieval-codes update-codes width External file handler support routines COBOL record transfer External file handling External file handler driver External file handler support routines Functional description Introduction Extraction of information Define default output specifications 14-6 14-5 14-5 14-3 14-4 14-4 14-5 14-5 14-4 14-4 14-1 - 14-2 14-2 14-2 14-2 14-2 14-2 14-2 14-2 14-2 14-2 14-6 - 14-9 14-6 - 14-9 14-1 - 14-9 14-2 - 14-6 14-6 - 14-9 14-1 - 14-9 14-1 3-13 - 3-15 3-14 - 3-15 F F option File Creation File access Retrieve items File creation File definition items Attributes Base Conversions Correlatives Definition code Item ID Justification Modulo Realloaction Index-x 9-15 7-3 - 7-6 5-4 - 5-7 5-6 - 5-7 3-2 - 3-12 2-12, 4-9 - 4-11 4-9 - 4-11, 4-12 4-10 4-10 4-10 4-9 - 4-10 4-9 4-10 4-10 4-11 A Guide to the UniVision System File definition items (Continued) Retrieval code Update code Width File dictionary File efficiency Analysing file structure Test file structure File maintenance Examine group in close detail File efficiency Reallocating files File management File management tasks Clear file CLEAR-FILE COPY Copy file items Create file CREATE-FILE DELETE Delete file Delete items DELETE-FILE ED EDIT Edit item Filename syntax Item lists MOVE-FILE RENAME File security Retrieval codes Update codes File synonym items Account Definition code Filename Item ID File synonyms Creation File system UniVision Filename File synonym items Filename syntax FILE-SAVE verb FILE-TEST verb FIND verb Form queue Index 4-10 4-10 4-11 1-8, 4-3 - 4-4 7-19 - 7-22 7-20 7-20 - 7-22 7-19 - 7-25 7-22 - 7-24 7-19 - 7-22 7-24 - 7-25 7-1 - 7-25 7-1 - 7-13 7-6 - 7-7 7-1 7-2 7-8 - 7-11 7-3 - 7-6 7-1 7-2 7-7 - 7-8 7-12 - 7-13 7-1 - 7-2 7-2 7-2 7-11 - 7-12 7-2 - 7-3 7-3 7-1 7-1 7-16 - 7-19 7-17 - 7-19 7-17 - 7-19 2-12, 4-11 - 4-12 4-12 4-12 4-12 4-12 7-14 - 7-16 4-1 - 4-3 4-12 7-2 - 7-3 8-5 7-20 - 7-22 6-17 1-8 Index-xi Format date Format of ERRMSG items @TCL Logon messages Format time FORMAT verb Forms Forms queue option Forward tape Frame Frame formats DUMP verb Physical item structure 4-23 8-13 - 8-15 8-15 8-15 4-23 10-13 9-2 - 9-4 9-15 10-24 - 10-25 1-8 5-2 - 5-4 5-2 - 5-3 5-4 G Generate VISION reports List contents of dictionary Glossary Group GROUP verb GROUP-LOCKS file 2-17 - 2-19 2-18 - 2-19 1-8 - 1-9 1-8 6-17, 7-22 - 7-23 8-11 H H option Hash index HASH-TEST verb Hierarchy Hold file retention Hold files Hosts table 9-15 12-5 7-20 - 7-22 1-2 - 1-3 9-32 - 9-33 9-4 - 9-5 15-3 - 15-4 I I option IDATE verb Identify entry Include data from tape in reports Index administration Information Extraction Initialise parallel printer Initialise serial printer Install UniVision on each system Issues with B+Trees ISTAT verb Item Index-xii 9-16 8-2 3-7 - 3-8 10-28 - 10-29 12-6 3-13 - 3-15 9-8 9-8 15-5 12-3 7-20 1-8 A Guide to the UniVision System Item ID Account definition items Account synonym items Attribute definition items File definition items File synonym items Item lists ITEM verb ITEM-LOCKS file 1-8 4-4 4-8 4-13 4-9 4-12 7-3 7-23 - 7-24 8-11 J Justification Attribute definition items File definition items 3-10 4-14 - 4-15 4-10 L Left-justified B+Tree index LINE-ATT verb LINE-DET verb LINE-PROTCOL verb LINE-PROTOCOL verb LINE-STATUS verb LINK-LINE verb List acquired line List assignment status option List contents of dictionary List contents of items List current tape device assignments List files List line and process characteristics LLC verb List stack LISTABS verb LIST-ACQUIRED-LINE verb LISTCONN verb LISTDEV verb LISTDICT verb LISTFILES verb LIST-FILE-STATS verb LIST-LINE-CHARS verb LISTPEQS verb Options LISTPRO verb LISTPROCS verb LISTPTR verb Options LIST-SECUIRTY-LOG verb Index 12-6 5-8, 11-2, 11-10 5-8, 11-2, 11-10 - 11-11 5-8 11-2 5-8, 11-2 5-8, 11-2, 11-9 11-11 - 11-12 9-14 2-18 - 2-19 2-14 - 2-17 10-19 - 10-20 2-13 - 2-14 6-7 6-7 6-19 - 6-20 9-5 5-8, 11-2, 11-11 - 11-12 6-18 5-8 6-18 6-18 8-4 6-7, 11-2, 11-5 9-5, 9-18 - 9-21 9-18 5-8 6-18 9-5, 9-9 - 9-11 9-9 - 9-10 8-3 Index-xiii LIST-TR-INDEX verb LISTVERBS verb LLC verb Local paths Set up Local variables LOCKOUT verb LOCKOUT-STATUS verb LOCKS-XREF file Log off Log on Log on and off Automatic logoff Log other users on and off Log to other accounts Logoff Proc Logon Proc Receive system messages Restrict access to UCL Restrict user access Log other users on and off Log to other accounts Log to UniVision environment Logical tape unit Logoff Proc Logon messages Logon Proc 8-4 6-18 6-7, 11-5 15-7 - 15-11 13-5 8-3 8-3 8-12 2-4 - 2-5 2-3 - 2-4 6-1 - 6-5 6-4 - 6-5 6-4 6-4 6-3 6-2 6-3 6-2 - 6-3 6-2 6-4 6-4 2-2 - 2-3 1-9 6-3 8-15 6-2 M Magnetic tape Attach cartridge tape unit Attach tape device Detach tape unit Examine contents of tape Overview of production verbs Overview of tape operations Overview of utility verbs Position tape Select tape drive Specify tape drive format Transfer data to and from other systems Troubleshooting Write and read Make connection Managing files Managing users Manipulate existing data Index-xiv 10-1 - 10-33 10-23 - 10-24 10-22 - 10-23 10-23 10-29 - 10-30 10-14 - 10-16 10-1 - 10-3 10-14 10-24 - 10-27 10-19 - 10-21 10-22 10-30 - 10-32 10-33 10-3 - 10-13 11-3 1-6 - 1-7 1-5 - 1-6 4-23 - 4-24 A Guide to the UniVision System Manipulate hold files Convert hold file to data file Delete multiple hold files Print hold file on screen Select hold files Spool hold file Spool multiple hold files View contents Master dictionary Attribute definition items File definition items File synonym items Proc Verb definition items VISION keywords MAXUSERS verb Message items MESSAGE verb Messages Logon Miscellaneous administrative commands MODEM-OFF verb MODEM-ON verb Modify previous statements Modify spooler records Modulo Account definition items File definition items Move to specified file MOVE-FILE verb MSG verb MULD verb Multi-valued attributes MULX verb 9-23 - 9-30 9-28 - 9-29 9-30 9-28 9-29 9-28 9-30 9-26 1-9, 2-11 - 2-12, 4-3 2-12 2-12 2-12 2-12 2-12 2-12 8-3 8-9 - 8-10 6-15 8-15 8-5 8-3 8-3 6-20 - 6-22 9-30 1-9 4-5 4-10 10-25 7-1 6-15 6-16 4-17 - 4-20 6-16 N Name attribute definition item Need for secondary keys New database Creation NEWAC file NSELECT verb 3-7 12-5 7-5 - 7-6 8-12 6-17 O O option Open option Index 9-17 9-17 Index-xv Options .C command ? A AUTO-LOGOFF verb B COPY verb CREATE-FILE verb DE verb Destination DOC-EDIT verb DUMP verb ED verb EDIT verb F Forms queue H I List assignment status LISTPEQS verb LISTPTR verb O Open Parenthetical Print to auxiliary port Printer banner PROTOCOL verb R Reassign print files S Select job priority SP-ASSIGN verb STARTPTR verb T T-DUMP verb T-LOAD verb T-READ verb Organisation of information Data file File dictionary MASTER dictionary Structure of data SYSTEM dictionary Overflow area Overflow table Overview of data communications Overview of production verbs Overview of tape operations Overview of utility verbs Index-xvi 6-22 - 6-23 9-14 9-15 6-4 - 6-5 9-15 7-8 - 7-9 7-4 7-11 - 7-12 9-15 - 9-16 7-11 - 7-12 5-2 - 5-3 7-11 - 7-12 7-11 - 7-12 9-15 9-15 9-15 9-16 9-14 9-18 9-9 - 9-10 9-17 9-17 6-11 - 6-12 9-15 9-15 11-5 - 11-7 9-17 - 9-18 9-17 - 9-18 9-16 9-16 9-13 - 9-18 9-7 9-16 10-6 10-8 10-29 1-1 - 1-4 1-2 - 1-3 1-2 - 1-3 1-2 - 1-3 1-3 - 1-4 1-2 - 1-3 5-1 - 5-2 1-9 11-1 - 11-2 10-14 - 10-16 10-1 - 10-3 10-14 A Guide to the UniVision System P P verb Paging Parenthetical options Password Account definition items Perform account save or file-save and restore Peripheral device Physical item structure Physical map of disk Overflow area POINTER-FILE file POKE verb Position tape Advance to end-of -data Erase selected tape drives Forward tape Move to specified file Read tape labels Retension tape Rewind tape Unload tape Write end-of-file mark Print banner option Print file Statuses Print files Print hold file on screen Print to auxiliary port option Printer administration Check status of printers Configure printers Restart failed printer Starting spooler Stop printers Printer adminstration PRINT-ERR verb Printers Privilege level Account definition items Proc Process settings Type-ahead buffer Process size limits Processes and lines ACQUIRE-LINE verb CONVERSE verb LINE-ATT verb Index 6-15 2-9 6-11 - 6-12 4-5 10-14 - 10-15 1-9 5-4 5-1 - 5-2 5-1 - 5-2 8-12 8-3 10-10 - 10-13, 10-24 - 10-27 10-26 10-27 10-24 - 10-25 10-25 10-25 10-27 10-24 10-26 10-26 9-15 9-20 - 9-21 9-4 - 9-5 9-28 9-15 9-9 - 9-11 9-7 - 9-9 9-9 9-6 - 9-7 9-11 - 9-12 9-6 - 9-12 6-17 9-2 - 9-4 4-6 2-12 6-6 - 6-7 6-7 15-12 - 15-13 5-7 - 5-11 5-8 5-8 5-8 Index-xvii Processes and lines (Continued) LINE-DET verb LINE-PROTOCOL verb LINE-STATUS verb LINK-LINE verb LIST-ACQUIRED-LINE verb LISTDEV verb LISTPRO verb PROCESS-STATUS verb RELEASE-LINE verb UNLINK-LINE verb Processors BASIC ED PROC UCL VISION PROCESS-STATUS verb Procs Production verbs Perform account-save or file-save and restore Read and write print records using UniVision BASIC Read and write spooler print files Read and write using VISION verbs PROTOCOL verb Options pse.conf file Set up 5-8 5-8 5-8 5-8 5-8 5-8 5-8 5-8 5-8 5-8 1-6 1-6 1-6 1-6 1-6 5-8, 11-2 6-17 - 6-18 10-14 - 10-15 10-15 - 10-16 10-15 10-15 11-2, 11-5 - 11-7 11-5 - 11-7 15-4 - 15-5 Q Q-pointers Creation Set up QSELECT verb 7-14 - 7-15 15-12 6-17 R R option RAM Read and write print records using UniVision BASIC Read and write spooler print files Read and write using VISION verbs READ hooks Read tape labels READNEXT hooks Reallocating files Index-xviii 9-17 - 9-18 1-9 10-15 - 10-16 10-15 10-15 13-2 10-25 13-4 7-24 - 7-25 A Guide to the UniVision System Reallocation Account definition items File definition items Reassign print files option Receive system messages Re-enable triggers Reference other processes Release acquired lines RELEASE-LINE verb Remote files in UniVision Remote paths Set up Remove printer from system Remove triggers RENAME verb Replace text RESET-ITEM-LOCKS verb RESET-PROCESS verb Restart failed printer Restart stopped printer Restoration Restore items from tape Restrict access to UCL Restrict user access Retain print files as hold files Retension tape Retrieval codes Account definition items File definition items Retrieve item Retrieve items Return values Rewind tape Right-justified B+Tree index RTD verb 4-7 4-11 9-17 - 9-18 6-3 13-9 - 13-10 6-19 11-12 5-8, 11-2, 11-12 15-13 15-7 - 15-11 9-22 - 9-23 13-10 - 13-11 6-17, 7-1 6-21 - 6-22 8-4 8-2 9-9 9-9 7-26 10-7 - 10-9, 10-28 6-2 - 6-3 6-2 9-22 10-27 7-17 - 7-19 4-5 4-10 6-24 5-6 - 5-7 13-5 - 13-6 10-24 12-6 6-16 S S option SAVE verb SECURITY-LOG file Select filename Select hold files Select job priority option Select modulo Select multiple tape drives Select tape drive List current tape device assignments Select tape drive for account Set tape drive assignments Index 9-16 8-5 8-12 3-3 9-29 9-16 3-3 - 3-4 10-21 10-19 - 10-21 10-19 - 10-20 10-20 - 10-21 10-19 Index-xix Select tape drive for account Select multiple tape drives SEL-RESTORE verb Send hold file to tape Server control commands SERVER-STATUS verb Set line and process characteristics Communications line settings List line and process characteristics Process settings Terminal and printer output settings Set line characteristics and protocols Set stacker options Set tape drive assignments Set time and date commands Set up distributed filing system Set up pse.conf file Set up remote and local paths Set up required Q-pointers Set up TCP/IP network Hosts table Set up pse.conf file Test IP connections SET-DATE-EUR verb SET-DATE-STD verb SET-FILE verb SET-TAPE verb SET-TERM verb SLEEP verb SP-ASSIGN options ? A B Destination F Forms queue H I List assignment status O Open Print banner Print to auxiliary port R Reassign print files Select job priority SP-ASSIGN verb Options SP-CLOSE verb SP-COPIES verb Index-xx 10-20 - 10-21 10-21 7-26 9-31 8-5 8-5 6-5 - 6-10 6-5 - 6-6 6-7 6-6 - 6-7 6-8 - 6-10 11-3 - 11-7 6-25 10-19 8-2 15-1 - 15-17 15-4 - 15-5 15-7 - 15-11 15-12 15-2 - 15-5 15-3 - 15-4 15-4 - 15-5 15-5 8-2 8-2 7-15 - 7-16 8-3, 10-19 8-3 6-15 9-13 - 9-18 9-14 9-15 9-15 9-15 - 9-16 9-15 9-15 9-15 9-16 9-14 9-17 9-17 9-15 9-15 9-17 - 9-18 9-17 - 9-18 9-16 9-5, 9-13 - 9-18 9-13 - 9-18 9-5 9-5, 9-30 A Guide to the UniVision System Special operator accounts FILE-SAVE STARTUP Specify tape drive format SP-EDIT verb SP-ENABLE verb SP-KILL verb Spool hold file Spool multiple hold files Spooler Basic operation Spooler features Summary Spooler verb input conversions SP-OPEN verb SP-STATUS verb SP-TAPEOUT verb Stacker Append text Choose command to modify Delete statements from stack Edit stack Enable Execute previous statements List stack Modify previous statements Reference other processes Replace text Retrieve item Set stacker options Store series of statements Stacker commands .A .C .E .G .K .L .M .MU .O .P .Q .R .S .U .X .Z STACK-OFF verb STACK-ON verb Index 8-8 8-8 8-8 10-22 9-5, 9-23 - 9-30 9-5, 9-9 9-5, 9-21 - 9-23 9-28 9-30 1-9, 9-1 - 9-35 9-1 - 9-6 9-6 9-34 - 9-35 9-5 9-5 9-6, 9-31 - 9-32 2-10 - 2-11, 6-18 - 6-25 6-22 6-21 6-24 6-21 6-19 6-20 6-19 - 6-20 6-20 - 6-22 6-19 6-21 - 6-22 6-24 6-25 6-22 - 6-24 6-22 6-22 - 6-24 6-21 6-21 6-24 2-10 - 2-11, 6-19 - 6-20 6-21 - 6-22 6-21 - 6-22 6-25 6-25 6-25 6-24 6-25 6-25 2-10 - 2-11, 6-20 6-25 6-16 6-16 Index-xxi Start server on remote machine Starting spooler STARTPTR verb Options Start-up and shutdown commands STARTUP verb STAT-FILE file Static hashed files Statuses of print file Stop printers STOPPTR verb Store series of statements Stored format and output format Date format Dollar amounts format Format date Format dollar amounts Format time Time format STORE-PATHS file Structure Attribute definition items Structure of data Structure of items Controlling and dependent specifications Multi-valued attributes SUBD verb SUBX verb Summary of spooler features SYSPROG account Access to SYSPROG account Contents SYSPROG commands Account management Copy Miscellaneous Server control Set time and date Start-up and shutdown System backup System maintenance and control System monitoring System restoration SYSPROG verbs :AUTHORISE :INIT-TAPE :INIT-DISK :INIT-SYSTEM :FILELOAD :STARTSPOOLER Index-xxii 15-12 9-6 - 9-7 9-5, 9-7 - 9-9 9-7 8-2 8-2 8-12 12-1 9-20 - 9-21 9-11 - 9-12 9-6, 9-11 - 9-12 6-22 - 6-24 4-21 - 4-23 4-23 4-22 - 4-23 4-23 4-22 - 4-23 4-23 4-23 8-12 4-14 1-3 - 1-4 4-16 - 4-21 4-20 - 4-21 4-17 - 4-20 6-16 6-16 9-6 8-1 - 8-2 8-1 - 8-2 8-2 8-2 - 8-5 8-3 8-5 - 8-6 8-5 8-5 8-2 8-2 8-5 8-3 - 8-4 8-4 8-5 8-3 8-4 8-4 8-4 8-5 8-3, 9-5 - 9-7 A Guide to the UniVision System SYSPROG verbs (Continued) :STOP-MASTER-SERVER << >> ACCOUNT-RESTORE ACCOUNT-SAVE ADD-ACCOUNTS AUTO-LOGOFF BUILD-LOCK-XREF BUILD-TR-INDEX CLEAR-GROUP-LOCKS COMPARE CREATE-ACCOUNT DEFINE-CURSOR DELETE-ACCOUNT DUMP FILE-SAVE IDATE LIST-FILE-STATS LIST-SECURITY-LOG LIST-TR-INDEX LOCKOUT LOCKOUT-STATUS MAXUSERS MODEM-OFF MODEM-ON POKE RESET-ITEM-LOCKS RESET-PROCESS SAVE SERVER-STATUS SET-DATE-EUR SET-DATE-STD SET-TAPE SET-TERM STARTUP TANDEM UDATE System backup commands SYSTEM dictionary Account definition items Message items Special operator accounts System level files User IDs System hierarchy System level files ACC BLOCK-CONVERT DEVICE-DETAILS Index 8-5 6-15, 8-5 6-15, 8-5 8-5 7-26, 8-5 8-5 6-4 - 6-5, 8-3 8-4 8-4 8-4 8-5 8-3, 8-6 8-4 8-3, 8-6 5-2 - 5-3, 6-15, 8-4 8-5 8-2 8-4 8-3 8-4 8-3 8-3 8-3 8-3 8-3 8-3 8-4 8-2 8-5 8-5 8-2 8-2 8-3, 10-19 8-3 8-2 8-3 8-2 8-5 1-9, 4-3, 8-8 - 8-12 8-8 8-9 - 8-10 8-8 8-10 - 8-12 8-8 1-2 - 1-3 8-10 - 8-12 8-10 8-11 8-11 Index-xxiii System level files (Continued) DEVICE-ERRORS DEVICE-NAMES ERRMSG GROUP-LOCKS ITEM-LOCKS LOCKS-XREF NEWAC POINTER-FILE SECURITY-LOG STAT-FILE STORE-PATHS UV.HELP UVPROCS UVPROGS System maintenance and control commands System monitoring commands System overview System restoration commands System software Managing files Managing users Process scheduling Processors 8-11 8-11 8-11, 8-13 - 8-15 8-11 8-11 8-12 8-12 8-12 8-12 8-12 8-12 8-12 8-12 8-12 8-3 - 8-4 8-4 1-1 - 1-9 8-5 1-4 - 1-7 1-6 - 1-7 1-5 - 1-6 1-6 1-6 T T option Tag Attribute definition items TANDEM verb Tape commands Summary Tape control Tape label format Tape layout Block size Tape label format T-ATT verb TCP/IP network Hosts table Set up Set up pse.conf file Test IP connections T-DET verb T-DUMP verb Options T-EOD verb T-ERASE verb Index-xxiv 9-16 4-14 8-3 10-13 - 10-14 9-33 - 9-34 10-17 10-16 - 10-18 10-18 10-17 10-13, 10-22 - 10-23 15-3 - 15-4 15-2 - 15-5 15-4 - 15-5 15-5 10-13, 10-23 10-3, 10-5 - 10-7, 10-13, 10-27 - 10-28 10-6 10-2, 10-10, 10-13, 10-26 10-2, 10-13, 10-27 A Guide to the UniVision System TERM verb Terminal and printer output settings TERM verb Test file structure Test IP connections Test link T-FORMAT verb T-FWD verb Time format TIME verb T-LOAD verb Options T-ONLINE verb Transfer data between Pick-like systems Transfer data to and from other systems Transfer data between Pick-like systems Transfer data to non-Pick-like system Transfer data to non-Pick-like system Block size Use of print files Translate data from another file T-RDLBL verb T-READ verb Options T-RET verb T-REW verb Trigger common area Trigger hooks DELETE READ READNEXT WRITE Triggers Add data integrity to application Anatomy of trigger Hooks Troubleshooting magnetic tape T-SELECT verb T-SPACE verb T-STATUS verb T-UNLOAD verb T-WEOF verb T-WHAT verb T-WTLBL verb Type-ahead buffer Types of index Hash Left-justified B+Tree Right-justified B+Tree Index 6-8 - 6-10, 6-15 6-8 - 6-10 6-8 - 6-10 7-20 - 7-22 15-5 15-13 - 15-14 10-13, 10-22 10-12, 10-13, 10-24 - 10-25 4-23 6-15 10-3, 10-8, 10-13, 10-28 10-8 10-2, 10-7 - 10-9, 10-13, 10-23 - 10-24 10-31 10-30 - 10-32 10-31 10-31 - 10-32 10-31 - 10-32 10-32 10-31 - 10-32 4-25 10-2, 10-12, 10-13, 10-25 10-2, 10-13, 10-29 - 10-30 10-29 10-2, 10-13, 10-27 10-2, 10-12, 10-13, 10-24 13-5 13-2 - 13-4 13-3 - 13-4 13-2 13-4 13-3 13-1 - 13-11 13-1 - 13-2 13-4 - 13-6 13-2 - 13-4 10-33 10-13, 10-20 - 10-21 10-2, 10-12, 10-14, 10-25 10-14, 10-19 - 10-20 10-14, 10-26 10-2, 10-14, 10-26 10-2, 10-14 10-2, 10-14 6-7 12-5 12-5 12-6 12-6 Index-xxv U UCL UCL-I verbs UCL-II verbs UDATE verb UniVision B+Trees UniVision BASIC files Creation UniVision Control Language BREAK key Edit command line Enter command Paging UniVision file system Data files Master dictionary SYSTEM dictionary Unlink and link lines UNLINK-LINE verb Unload tape Update codes Account definition items File definition items Use Procs for printer control Hold file retention Tape control Use Procs for tape control Hold file retention Tape control Use spooler with tape drives Copy print file from tape Send hold file to tape User account management Account usage statistics Create account Delete account User account verbs :START-MASTER-SERVER ACQUIRE-LINE ADDD ADD-DELETE-TRIGGER ADD-READNEXT-TRIGGER ADD-READ-TRIGGER ADD-WRITE-TRIGGER ADDX BLOCK-PRINT BUILD-INDEX CHARGES Index-xxvi 1-9 6-15 - 6-16 6-16 - 6-17 8-2 12-3 - 12-4 7-6 2-5 - 2-10, 6-1 - 6-25 2-9 - 2-10 2-8 - 2-9 2-8 2-9 4-1 - 4-3 4-4 4-3 4-3 11-9 5-8, 11-2, 11-9 10-26 7-17 - 7-19 4-5 4-10 9-32 - 9-34 9-32 - 9-33 9-33 - 9-34 9-32 - 9-34 9-32 - 9-33 9-33 - 9-34 9-30 - 9-32 9-31 - 9-32 9-31 8-6 - 8-8 8-7 - 8-8 8-6 8-6 15-12 5-8, 11-2, 11-11 6-16 13-7 13-7 - 13-8 13-6 - 13-7 13-7 6-16 6-15 12-6 8-7 - 8-8 A Guide to the UniVision System User account verbs (Continued) CHARGE-TO CLEAR-FILE CONVERSE COPY CREATE-BFILE CREATE-FILE CREATE-INDEX CT DE DEBUG-OFF DEBUG-ON DELETE DELETE-FILE DELETE-FILE\r DELETE-INDEX DISABLE-DELETE-TRIGGER DISABLE-INDEX DISABLE-READNEXT-TRIGGER DISABLE-READ-TRIGGER DISABLE-WRITE-TRIGGER DIVD DIVX DOC-EDIT DROP-DELETE-TRIGGER DROP-READNEXT-TRIGGER DROP-READ-TRIGGER DROP-WRITE-TRIGGER DTR DTX ECHO ECHO-OFF ECHO-ON ED EDIT ENABLE-DELETE-TRIGGER ENABLE-INDEX ENABLE-READNEXT-TRIGGER ENABLE-READ-TRIGGER ENABLE-WRITE-TRIGGER FILE-TEST FIND FORMAT GROUP HASH-TEST ISTAT ITEM LINE-ATT LINE-DET LINE-PROTOCOL Index 8-7 - 8-8 7-1, 7-6 - 7-7 5-8, 11-2, 11-12 - 11-17 6-17, 7-2, 7-8 - 7-11 7-6 3-4 - 3-5, 7-1 12-6 6-18 6-17, 7-11 - 7-12 6-16 6-16 7-2, 7-12 - 7-13 7-7 - 7-8 7-1 12-6 13-8 12-6 13-9 13-8 13-8 6-16 6-16 6-17, 7-11 - 7-12 13-11 13-11 13-10 13-10 6-16 6-16 6-15 6-16 6-16 6-17, 7-2, 7-11 - 7-12 6-17, 7-2, 7-11 - 7-12 13-9 - 13-10 12-6 13-10 13-9 13-9 7-20 - 7-22 6-17 10-13 6-17, 7-22 - 7-23 7-20 - 7-22 7-20 7-23 - 7-24 5-8, 11-2, 11-10 5-8, 11-2, 11-10 - 11-11 5-8, 11-2 Index-xxvii User account verbs (Continued) LINE-STATUS LINK-LINE LISTABS LIST-ACQUIRED-LINE LISTCONN LISTDEV LISTDICT LISTFILES LIST-LINE-CHARS LISTPEQS LISTPRO LISTPROCS LISTPTR LISTVERBS LLC MESSAGE MOVE-FILE MSG MULD MULX NSELECT P PRINT-ERR PROCESS-STATUS PROTOCOL QSELECT RELEASE-LINE RENAME RTD SEL-RESTORE SET-FILE SLEEP SP-ASSIGN SP-CLOSE SP-COPIES SP-EDIT SP-ENABLE SP-KILL SP-OPEN SP-STATUS SP-TAPEOUT STACK-OFF STACK-ON STARTPTR STOPPTR SUBD SUBX T-ATT T-DET Index-xxviii 5-8, 11-2 5-8, 11-2, 11-9 9-5 5-8, 11-2, 11-11 - 11-12 6-18 5-8 6-18 6-18 6-7, 11-2, 11-5 9-5, 9-18 - 9-21 5-8 6-18 9-5, 9-9 - 9-11 6-18 6-7, 11-5 6-15 7-1 6-15 6-16 6-16 6-17 6-15 6-17 5-8, 11-2 11-2, 11-5 - 11-7 6-17 5-8, 11-2, 11-12 6-17, 7-1 6-16 7-26 7-15 - 7-16 6-15 9-5, 9-13 - 9-18 9-5 9-5, 9-30 9-5, 9-23 - 9-30 9-5, 9-9 9-5, 9-21 - 9-23 9-5 9-5 9-6, 9-31 - 9-32 6-16 6-16 9-5, 9-7 - 9-9 9-6, 9-11 - 9-12 6-16 6-16 10-13, 10-22 - 10-23 10-13, 10-23 A Guide to the UniVision System User account verbs (Continued) T-DUMP T-EOD T-ERASE TERM T-FORMAT T-FWD TIME T-LOAD T-ONLINE T-RDLBL T-READ T-RET T-REW T-SELECT T-SPACE T-STATUS T-UNLOAD T-WEOF T-WHAT T-WTLBL UNLINK-LINE WHO XTD User accounts User commands Catalogued UniVision BASIC programs Procs Verbs User IDs User process User process code Account definition items Using BASIC programs UV.HELP file UVPROCS file UVPROGS file 10-3, 10-5 - 10-7, 10-13, 10-27 - 10-28 10-2, 10-10, 10-13, 10-26 10-2, 10-13, 10-27 6-8 - 6-10, 6-15 10-13, 10-22 10-12, 10-13, 10-24 - 10-25 6-15 10-3, 10-8, 10-13, 10-28 10-2, 10-7 - 10-9, 10-13, 10-23 - 10-24 10-2, 10-12, 10-13, 10-25 10-2, 10-13, 10-29 - 10-30 10-2, 10-13, 10-27 10-2, 10-12, 10-13, 10-24 10-13, 10-20 - 10-21 10-2, 10-12, 10-14, 10-25 10-14, 10-19 - 10-20 10-14, 10-26 10-2, 10-14, 10-26 10-2, 10-14 10-2, 10-14 5-8, 11-2, 11-9 6-15 6-16 2-1 - 2-19 6-10 - 6-18 6-18 6-17 - 6-18 6-11 - 6-17 8-8 1-9 4-7 11-13 - 11-17 8-12 8-12 8-12 V Value Verb definition items Verb format Verb syntax Verbs :AUTHORISE :INIT-TAPE :INIT-DISK :INIT-SYSTEM 1-9 2-12, 4-9 6-12 - 6-15 6-11 6-11 - 6-17 8-3 8-4 8-4 8-4 Index Index-xxix Verbs (Continued) :FILELOAD :START-MASTER-SERVER :STARTSPOOLER :STOP-MASTER-SERVER << >> ACCOUNT-RESTORE ACCOUNT-SAVE ACQUIRE-LINE ADD-ACCOUNTS ADDD ADD-DELETE-TRIGGER ADD-READNEXT-TRIGGER ADD-READ-TRIGGER ADD-WRITE-TRIGGER ADDX AUTO-LOGOFF BLOCK-PRINT BUILD-INDEX BUILD-LOCK-XREF BUILD-TR-INDEX CHARGES CHARGE-TO CLEAR-FILE CLEAR-GROUP-LOCKS COMPARE CONVERSE COPY CREATE-ACCOUNT CREATE-BFILE CREATE-FILE CREATE-INDEX CT DE DEBUG-OFF DEBUG-ON DEFINE-CURSOR DELETE DELETE-ACCOUNT DELETE-FILE DELETE-INDEX DISABLE-DELETE-TRIGGER DISABLE-INDEX DISABLE-READNEXT-TRIGGER DISABLE-READ-TRIGGER DISABLE-WRITE-TRIGGER DIVD DIVX DOC-EDIT Index-xxx 8-5 15-12 8-3, 9-5 - 9-7 8-5 6-15, 8-5 6-15, 8-5 7-26, 8-5 7-26, 8-5 5-8, 11-2, 11-11 8-5 6-16 13-7 13-7 - 13-8 13-6 - 13-7 13-7 6-16 6-4 - 6-5, 8-3 6-15 12-6 8-4 8-4 8-7 - 8-8 8-7 - 8-8 7-1, 7-6 - 7-7 8-4 8-5 5-8, 11-2, 11-12 - 11-17 6-17, 7-2, 7-8 - 7-11 8-3, 8-6 7-6 3-4 - 3-5, 7-1, 7-3 - 7-6 12-6 6-18 6-17, 7-11 - 7-12 6-16 6-16 8-4 7-2, 7-12 - 7-13 8-3, 8-6 7-1 - 7-2, 7-7 - 7-8 12-6 13-8 12-6 13-9 13-8 13-8 6-16 6-16 6-17, 7-11 - 7-12 A Guide to the UniVision System Verbs (Continued) DROP-DELETE-TRIGGER DROP-READNEXT-TRIGGER DROP-READ-TRIGGER DROP-WRITE-TRIGGER DTR DTX DUMP ECHO ECHO-OFF ECHO-ON ED EDIT ENABLE-DELETE-TRIGGER ENABLE-INDEX ENABLE-READNEXT-TRIGGER ENABLE-READ-TRIGGER ENABLE-WRITE-TRIGGER FILE-SAVE FILE-TEST FIND Format FORMAT GROUP HASH-TEST IDATEP ISTAT ITEM LINE-ATT LINE-DET LINE-PROTOCOL LINE-STATUS LINK-LINE LISTABS LIST-ACQUIRED-LINE LISTCONN LISTDEV LISTDICT LISTFILES LIST-FILE-STATS LIST-LINE-CHARS LISTPEQS LISTPRO LISTPROCS LISTPTR LIST-SECURITY-LOG LIST-TR-INDEX LISTVERBS LLC LOCKOUT Index 13-11 13-11 13-10 13-10 6-16 6-16 5-2 - 5-3, 6-15, 8-4 6-15 6-16 6-16 6-17, 7-2, 7-11 - 7-12 6-17, 7-2, 7-11 - 7-12 13-9 - 13-10 12-6 13-10 13-9 13-9 8-5 7-20 - 7-22 6-17 6-12 - 6-15 10-13 6-17, 7-22 - 7-23 7-20 - 7-22 8-2 7-20 7-23 - 7-24 5-8, 11-2, 11-10 5-8, 11-2, 11-10 - 11-11 5-8, 11-2 5-8, 11-2 5-8, 11-2, 11-9 9-5 5-8, 11-2, 11-11 - 11-12 6-18 5-8 6-18 6-18 8-4 6-7, 11-2, 11-5 9-5, 9-18 - 9-21 5-8 6-18 9-5, 9-9 - 9-11 8-3 8-4 6-18 6-7, 11-5 8-3 Index-xxxi Verbs (Continued) LOCKOUT-STATUS MAXUSERS MESSAGE MODEM-OFF MODEM-ON MOVE-FILE MSG MULD MULX NSELECT P Parenthetical options POKE PRINT-ERR PROCESS-STATUS PROTOCOL QSELECT RELEASE-LINE RENAME RESET-ITEM-LOCKS RESET-PROCESS RTD SAVE SEL-RESTORE SERVER-STATUS SET-DATE-EUR SET-DATE-STD SET-FILE SET-TAPE SET-TERM SLEEP SP-ASSIGN SP-CLOSE SP-COPIES SP-EDIT SP-ENABLE SP-KILL SP-OPEN SP-STATUS SP-TAPEOUT STACK-OFF STACK-ON STARTPTR STARTUP STOPPTR SUBD SUBX Syntax TANDEM Index-xxxii 8-3 8-3 6-15 8-3 8-3 7-1 6-15 6-16 6-16 6-17 6-15 6-11 - 6-12 8-3 6-17 5-8, 11-2 11-2, 11-5 - 11-7 6-17 5-8, 11-2, 11-12 6-17, 7-1 8-4 8-2 6-16 8-5 7-26 8-5 8-2 8-2 7-15 - 7-16 8-3, 10-19 8-3 6-15 9-5, 9-13 - 9-18 9-5 9-5, 9-30 9-5, 9-23 - 9-30 9-5, 9-9 9-5, 9-21 - 9-23 9-5 9-5 9-6, 9-31 - 9-32 6-16 6-16 9-5, 9-7 - 9-9 8-2 9-6, 9-11 - 9-12 6-16 6-16 6-11 8-3 A Guide to the UniVision System Verbs (Continued) T-ATT T-DET T-DUMP T-EOD T-ERASE TERM T-FORMAT T-FWD TIME T-LOAD T-ONLINE T-RDLBL T-READ T-RET T-REW T-SELECT T-SPACE T-STATUS T-UNLOAD T-WEOF T-WHAT T-WTLBL UCL-I UCL-II UDATE UNLINK-LINE VISION WHO XTD View contents of hold file Virtual file system handling Virtual file system interface External file handler driver External file handler link item format External file handler support routines Functional description Introduction Virtual memory VISION keywords VISION verbs 10-13, 10-22 - 10-23 10-13, 10-23 10-3, 10-5 - 10-7, 10-13, 10-27 - 10-28 10-2, 10-10, 10-13, 10-26 10-2, 10-13, 10-27 6-8 - 6-10, 6-15 10-13, 10-22 10-12, 10-13, 10-24 - 10-25 6-15 10-3, 10-8, 10-13, 10-28 10-2, 10-7 - 10-9, 10-13, 10-23 - 10-24 10-2, 10-12, 10-13, 10-25 10-2, 10-13, 10-29 - 10-30 10-2, 10-13, 10-27 10-2, 10-12, 10-13, 10-24 10-13, 10-20 - 10-21 10-2, 10-12, 10-14, 10-25 10-14, 10-19 - 10-20 10-14, 10-26 10-2, 10-14, 10-26 10-2, 10-14 10-2, 10-14 6-15 - 6-16 6-16 - 6-17 8-2 5-8, 11-2, 11-9 6-17 6-15 6-16 9-26 14-1 - 14-9 14-2 - 14-6 14-1 - 14-2 14-6 - 14-9 14-1 - 14-9 14-1 1-9 2-12 6-17 W WHO verb Width Account definition items Attribute definition items File definition items Index 6-15 4-7 4-15 4-11 Index-xxxiii Write and read tape Access tape drive Append data to tape Dump file to tape Position tape Restore items from tape Write end-of-file mark WRITE hooks 10-3 - 10-13 10-3 - 10-5 10-10 10-5 - 10-7 10-10 - 10-13 10-7 - 10-9 10-26 13-3 X XTD verb Index-xxxiv 6-16 A Guide to the UniVision System