OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / larcos.zip / MANUAL.DOC < prev next >

Wrap

Text File | 1995-03-03 | 229KB | 6,491 lines

╔═══════════════════════════════════════════════╗ ║ ║ ║ ║ ║ ║ ║ ║ █████ ║ ╔═════════════█████═════════════════════════════════════════════╝ ║ ║ ║ ║ ║ ║ LARC USER'S GUIDE ║ ║ ║ ║ ║ ║ Library Administration ║ ║ and Release Control System ║ ║ for DOS and OS/2 ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚═══════════════╝ │ │ ║ │ ║ │ │ ║ │ │ ║ │ │ ║ │ │ ║ │ SouthWind Software Incorporated │ ║ │ 1738 Tahiti Lane │ ║ │ Alabaster, Alabama 35007 │ ║ │ │ ║ │ Phone (205) 620-0827 │ ║ │ Fax (205) 620-0871 │ ║ │ │ ║ └────────────────────────────────────────────────── │ ╚═════════════════════════════════════════════════════════ └──────────────────────────────────────────────────────────────── LARC User's Guide Legal Stuff ═════════════════════════════════════════════════════════════════ The LARC System ═══════════════ The software described in this manual is furnished under a license agreement and may be used only in accordance with the terms of the agreement. See the file LICENSE.DOC for the complete description of the license agreement. Disclaimer ══════════ This document contains the latest information available at the time of publication. However, SouthWind Software Incorporated reserves the right to modify the software described herein at any time, with or without published notification. SouthWind Software Incorporated offers no warranties, express or implied, regarding the accuracy, sufficiency, suitability or merchantability of the software or other materials delivered herewith. Customers have the sole responsibility for inspecting and testing all aspects of the software described herein before using it with important data. Copyright Notice ════════════════ Copyright (c) 1994-95 SouthWind Software Incorporated. All Rights Reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any other language or computer language in whole or in part, in any form or by any means, whether it be electronic, mechanical, magnetic, optical, manual or otherwise, without prior written permission of SouthWind Software Incorporated, 1738 Tahiti Lane, Alabaster, Alabama 35007. Trademarks ══════════ LARC is a trademark of SouthWind Software Incorporated. MS-DOS and Windows are trademarks of Microsoft Corporation. OS/2 is a trademark of International Business Machines, Incorporated. Netware and Novell are registered trademarks of Novell, Inc. PKWARE and PKUNZIP are registered trademarks of PKWARE, Inc. All other product names mentioned in this document may be trademarks or registered trademarks of their respective companies and are hereby acknowledged. ───────────────────────────────────────────────────────────────── 1 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Table of Contents ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ▄▄ ║ ║ ██ ██ ║ ║ ▀▀ ██ ║ ║ ██ ║ ║ ██ ║ ║ ▄▄ ║ ║ ║ ╚══════════════╝ Chapter I - Introduction Welcome to LARC . . . . . . . . . . . . . . . . . .6 Documentation Layout . . . . . . . . . . . . . . . .6 Reading the READ.ME File . . . . . . . . . . . . . .7 Definitions. . . . . . . . . . . . . . . . . . . . .7 Conventions. . . . . . . . . . . . . . . . . . . . .8 Symbols. . . . . . . . . . . . . . . . . . .8 Type Styles. . . . . . . . . . . . . . . . .9 Technical Support. . . . . . . . . . . . . . . . . .9 Let Us Know What You Think . . . . . . . . . . . . 10 Chapter 1 - What Is LARC? What is Source Control?. . . . . . . . . . . . . . 11 What is LARC?. . . . . . . . . . . . . . . . . . . 12 Library Administration.... . . . . . . . . . . . . 13 ...and Release Control . . . . . . . . . . . . . . 15 What are Source Files? . . . . . . . . . . . . . . 15 What is Embedded Control Information?. . . . . . . 15 LARC Library Structure . . . . . . . . . . . . . . 16 Where To Begin . . . . . . . . . . . . . . . . . . 17 Chapter 2 - Installing LARC DOS System Requirements. . . . . . . . . . . . . . 19 OS/2 System Requirements . . . . . . . . . . . . . 19 To Install LARC . . . . . .. . . . . . . . . . . . 20 Modifying Your DOS System Startup Files. . . . . . 20 Modifying Your OS/2 System Startup Files . . . . . 21 LARC's Configuration File. . . . . . . . . . . . . 22 Multi-User Installation Requirements . . . . . . . 23 Chapter 3 - System Security Security Options . . . . . . . . . . . . . . . . . 25 User Initials and Passwords. . . . . . . . . . . . 25 Security Access Levels . . . . . . . . . . . . . . 26 The Security Screen. . . . . . . . . . . . . . . . 26 Exiting to the Operating System. . . . . . . . . . 27 Creating a List of Users . . . . . . . . . . . . . 27 Chapter 4 - Library Maintenance Library Structure. . . . . . . . . . . . . . . . . 29 Library Maintenance. . . . . . . . . . . . . . . . 30 Add a Library. . . . . . . . . . . . . . . . . . . 32 Modify a Library . . . . . . . . . . . . . . . . . 32 ───────────────────────────────────────────────────────────────── 2 LARC User's Guide Table of Contents ═════════════════════════════════════════════════════════════════ Delete an Obsolete Library . . . . . . . . . . . . 32 Show All Libraries . . . . . . . . . . . . . . . . 33 Print All Libraries. . . . . . . . . . . . . . . . 33 Compressed Libraries . . . . . . . . . . . . . . . 33 Installation Files . . . . . . . . . . . . . . . . 34 Revised Files. . . . . . . . . . . . . . . . . . . 35 Chapter 5 - Extension Maintenance File Control Information . . . . . . . . . . . . . 36 Extension Maintenance. . . . . . . . . . . . . . . 39 Add an Extension . . . . . . . . . . . . . . . . . 40 Modify an Extension. . . . . . . . . . . . . . . . 40 Delete an Obsolete Extension . . . . . . . . . . . 41 Show All Extensions. . . . . . . . . . . . . . . . 41 Print All Extensions . . . . . . . . . . . . . . . 41 Chapter 6 - User Maintenance User Maintenance . . . . . . . . . . . . . . . . . 42 Add an User. . . . . . . . . . . . . . . . . . . . 43 Modify a User. . . . . . . . . . . . . . . . . . . 43 Delete an Obsolete User. . . . . . . . . . . . . . 43 Show All Users . . . . . . . . . . . . . . . . . . 44 Print All Users. . . . . . . . . . . . . . . . . . 44 Chapter 7 - LARC Configuring File The LARC Configuration File. . . . . . . . . . . . 45 SET SYSTEM NAME. . . . . . . . . . . . . . 45 SET SYSTEM EXECUTABLES . . . . . . . . . . 45 SET SYSTEM DATAFILES . . . . . . . . . . . 45 SET SYSTEM TIMEOUT . . . . . . . . . . . . 46 SET SYSTEM LOGON . . . . . . . . . . . . . 46 SET SYSTEM DISPLAY . . . . . . . . . . . . 47 SET SYSTEM PATHTOUSE . . . . . . . . . . . 47 SET COLOR. . . . . . . . . . . . . . . . . 47 SET PRINTER ACTIVE . . . . . . . . . . . . 48 SET PRINTER LINESPAGE. . . . . . . . . . . 48 SET PRINTER INITIALIZE . . . . . . . . . . 48 SET PRINTER CONDENSE . . . . . . . . . . . 48 SET PRINTER NORMAL . . . . . . . . . . . . 48 SET PRINTER DONE . . . . . . . . . . . . . 48 SET FLOPPY 360KB . . . . . . . . . . . . . 49 SET FLOPPY 1.2MB . . . . . . . . . . . . . 49 SET FLOPPY 720KB . . . . . . . . . . . . . 49 SET FLOPPY 1.44MB. . . . . . . . . . . . . 49 Starting LARC. . . . . . . . . . . . . . . . . . . 49 Starting LARC From Microsoft Windows . . . . . . . 50 Network Environments . . . . . . . . . . . . . . . 50 Chapter 8 - Command Files Command File Descriptions. . . . . . . . . . . . . 52 How Do the Command Files Work Together?. . . . . . 53 LARCBLDn.BAT or LARCBLDn.CMD . . . . . . . . . . . 54 BUILDFIN.CTL . . . . . . . . . . . . . . . . . . . 59 LARCARC.BAT or LARCARC.CMD . . . . . . . . . . . . 59 ───────────────────────────────────────────────────────────────── 3 LARC User's Guide Table of Contents ═════════════════════════════════════════════════════════════════ LARCRELn.CUT Parameter Files . . . . . . . . . . . 60 Comments . . . . . . . . . . . . . . . . . 61 Installation Defaults Command. . . . . . . 61 System Name Command. . . . . . . . . . . . 62 File Copy Command. . . . . . . . . . . . . 62 Change Directory Command . . . . . . . . . 64 File Delete Command. . . . . . . . . . . . 64 Execute Command. . . . . . . . . . . . . . 64 Make Directory Command . . . . . . . . . . 65 Remove Directory Command . . . . . . . . . 65 Unzip Command. . . . . . . . . . . . . . . 65 Verify File Command. . . . . . . . . . . . 66 Directory Subsitution Characters . . . . . 66 Example CUT File . . . . . . . . . . . . . 66 LARCBUP.BAT or LARCBUP.CMD . . . . . . . . . . . . 69 DISKnn.CTL . . . . . . . . . . . . . . . . . . . . 69 LARCBACK.BAT or LARCBACK.CMD . . . . . . . . . . . 69 LARCFORM.BAT or LARCFORM.CMD . . . . . . . . . . . 70 LARCSERL.BAT or LARCSERL.CMD . . . . . . . . . . . 70 Chapter 9 - The Menus The Main Menu. . . . . . . . . . . . . . . . . . . 71 The System Maintenance Menu. . . . . . . . . . . . 71 Recognized Keystrokes. . . . . . . . . . . . . . . 71 Selecting a Library. . . . . . . . . . . . . . . . 74 Chapter 10 - File Functions The Function Selection Menu. . . . . . . . . . . . 75 Selecting a Library. . . . . . . . . . . . . . . . 77 Check Out a File . . . . . . . . . . . . . . . . . 77 Check In a File. . . . . . . . . . . . . . . . . . 77 Add a New File . . . . . . . . . . . . . . . . . . 78 Copy a File. . . . . . . . . . . . . . . . . . . . 78 Cancel a Check Out . . . . . . . . . . . . . . . . 78 Delete a File. . . . . . . . . . . . . . . . . . . 78 Get All Files. . . . . . . . . . . . . . . . . . . 79 Chapter 11 - Display Functions Display Menu . . . . . . . . . . . . . . . . . . . 80 Library Contents . . . . . . . . . . . . . . . . . 81 Source File. . . . . . . . . . . . . . . . . . . . 81 My Checked Out Files . . . . . . . . . . . . . . . 81 Checked Out Files. . . . . . . . . . . . . . . . . 81 Release History. . . . . . . . . . . . . . . . . . 82 Revised Files. . . . . . . . . . . . . . . . . . . 82 Activity Log File. . . . . . . . . . . . . . . . . 82 Chapter 12 - Print Functions Print Menu . . . . . . . . . . . . . . . . . . . . 83 Library Contents . . . . . . . . . . . . . . . . . 83 Source File. . . . . . . . . . . . . . . . . . . . 84 My Checked Out Files . . . . . . . . . . . . . . . 84 Checked Out Files. . . . . . . . . . . . . . . . . 85 Release History. . . . . . . . . . . . . . . . . . 85 ───────────────────────────────────────────────────────────────── 4 LARC User's Guide Table of Contents ═════════════════════════════════════════════════════════════════ Revised Files. . . . . . . . . . . . . . . . . . . 86 Activity Log File. . . . . . . . . . . . . . . . . 87 Chapter 13 - Release Generation Functions Release Menu . . . . . . . . . . . . . . . . . . . 88 Creating a Diskette Release. . . . . . . . . . . . 88 Creating a hard drive Release. . . . . . . . . . . 89 Release Build. . . . . . . . . . . . . . . . . . . 90 Backup Library Source Files. . . . . . . . . . . . 90 Purge Test Release Identifiers . . . . . . . . . . 90 Execute Serialization Commands . . . . . . . . . . 91 Chapter 14 - Maintenance Functions Submit a System Command. . . . . . . . . . . . . . 92 Backup the Entire System . . . . . . . . . . . . . 92 Format System Backup Media . . . . . . . . . . . . 92 Library Maintenance. . . . . . . . . . . . . . . . 93 Extension Maintenance. . . . . . . . . . . . . . . 93 User Maintenance . . . . . . . . . . . . . . . . . 93 Chapter 15 - Quitting LARC Quitting LARC. . . . . . . . . . . . . . . . . . . 94 Chapter 16 - Utilities LDIR - Library Directory Utility . . . . . . . . . 95 GETLARC - File Information Extraction Utility. . . 96 INSTALL - LARC Installation Program. . . . . . . . 97 Disk Number and Version Record . . . . . . 98 Defaults Record. . . . . . . . . . . . . . 98 System Name Record . . . . . . . . . . . . 99 Copy a File. . . . . . . . . . . . . . . . 99 Change to a Different Directory. . . . . . 99 Delete a File. . . . . . . . . . . . . . .100 Execute a Command. . . . . . . . . . . . .100 Make a Directory . . . . . . . . . . . . .100 Remove a Directory . . . . . . . . . . . .100 Unzip a Compressed File. . . . . . . . . .101 Verify a File Exists.. . . . . . . . . . .101 End of the Current Diskette. . . . . . . .101 End of All Diskettes . . . . . . . . . . .102 Special Directory Replacement Characters .102 Error Handling . . . . . . . . . . . . . .102 Example DISKnn.CTL File. . . . . . . . . .103 KCOPY - Ken's File Copy Program. . . . . . . . . .104 KDEL - Ken's File Delete Program . . . . . . . . .105 KFREE - Ken's Free Space Program . . . . . . . . .106 KVERENV - Ken's Verify Environment Program . . . .107 KDIR - Ken's Directory Program . . . . . . . . . .108 ───────────────────────────────────────────────────────────────── 5 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ██████ ║ Introduction ║ ██ ║ ║ ██ ║ This chapter provides a brief introduction to ║ ██ ║ LARC and provides the manual structure, some ║ ██████ ║ basic definitions and information of obtaining ║ ║ support for LARC. ╚══════════════╝ Welcome To LARC ═══════════════ Welcome to the Library Administration and Release Control system, referred to as LARC. This manual provides the essential information needed to install and use LARC to control source files. Use this manual to acquaint yourself with LARC and its straight-forward method of managing source files and producing software product releases. Documentation Layout ════════════════════ Chapter 1: What is LARC? - Provides a brief definition of source control and the LARC approach to the problem. Chapter 2: Installing LARC - Provides information required to install and execute LARC on your system. Chapter 3: System Security - Provides a description of the user security features provided by LARC. Chapter 4: Library Maintenance - Provides information on how to create the libraries to be controlled by LARC. Chapter 5: Extension Maintenance - Provides information on how to set up the list of files which LARC will search for embedded control information. Chapter 6: User List Maintenance - Provides information on how to set up the list of LARC users. Chapter 7: LARC Configuring File - Provides information on how to set up LARC's configuration file. Chapter 8: Command Files - Provides information on the system command and parameter files that LARC uses to manage your source files and build your product release. Chapter 9: The Menus - Provides information on the LARC menu structure. ───────────────────────────────────────────────────────────────── 6 LARC User's Guide Introduction ═════════════════════════════════════════════════════════════════ Chapter 10: File Functions - Provides information on moving files to and from LARC libraries. Chapter 11: Display Functions - Provides information on the information that can be displayed to the screen. Chapter 12: Print Functions - Provides information on the information that can be sent to the printer. Chapter 13: Release Generation Functions - Provides information for using LARC to build product releases and create release diskettes. Chapter 14: Maintenance Functions - Provides information for using the LARC system maintenance functions. Chapter 15: Quitting LARC - Provides information on exiting LARC and returning to the operating system prompt. Chapter 16: Utilities - Describes the utility programs that are provided to support your LARC configuration. Reading the READ.ME File ════════════════════════ If present, the READ.ME file will contain last minute information on the LARC system files, or corrections to this manual. Please print and read the file before continuing. Definitions ═══════════ The LARC User's Guide uses the following definitions: build The process of producing a releasable software product from a collection of source and data files. This includes (but in no was is not limited to) compiling, linking, and compressing the executable files that make up a software product. cut The process of copying the software product files from a release directory to a specific diskette or directory. In other words, "cutting" a set of release diskettes that may be distributed to the end-user for installation and use. drive The letter designating a hard drive or diskette drive. ───────────────────────────────────────────────────────────────── 7 LARC User's Guide Introduction ═════════════════════════════════════════════════════════════════ extension One to three characters that comprise the filename extension which is the portion of the file name that follows the period (.). library This term is used to indicate a group of source and release files that are being managed by LARC. library name A 1 to 50 character descriptive name associated with a library. path The drive letter and directory name. filename A file name, comprised of a one to eight character file name, followed by a period (.), followed by an optional 1 to three character file extension. Only valid DOS style "8.3" filename formats and characters are recognized. parameter Additional command line information. The format and use of parameters will be described when referenced. release The outcome of a product build process. Releases are typically comprised of the executable programs and data files which constitute a releasable software product. release directory From one to five directories that have been set reserved for use by LARC for each library to be used when building a release of the source contained in the library. A release directory will contain the executable programs and data files which result from a product build. /switch A command line control option. When used, the definition and contents of the switch will be defined. Conventions ═══════════ The following conventions have been used to help you find and better understand the information presented in this guide. Symbol Meaning ────── ───────────────────────────────────────────────── o Indicates a "bullet" point list of features, recommendations or ideas. <Esc> The escape key, which is typically marked with the letters "Esc" on most PC keyboards. ───────────────────────────────────────────────────────────────── 8 LARC User's Guide Introduction ═════════════════════════════════════════════════════════════════ <Fn> One of the functions keys F1 through F10 (or F1 through F12 on enhanced keyboards). These keys are typically marked with the letter F followed by the function key number (i.e. F1, F2, etc.). <Enter> The return, or enter key, which is typically marked with the word "Enter" and a left arrow. A second key marked "Enter" is also provided on most keyboards on the numeric keypad portion of the keyboard. <Ins> The insert key, which is typically marked with the letters "Ins" or "Insert" on most PC keyboards. <Del> The delete key, which is typically marked with the letters "Del" or "Delete" on most PC keyboards. <x> Used to denote a key to be pressed. When used in the manual, "x" will be replaced with the specific key letter. Type Style Meaning ────────── ───────────────────────────────────────────────── ALL CAPS Indicates text entered as shown, such as a drive letter or path name. lowercase Indicates parameters that you replace with actual information specific to your configuration or set up. [] Indicates optional parameter or switch information. ... Indicates that you may repeat the operation or step. space Indicates a single space character. Technical Support ═════════════════ Limited technical support is provided for non-licensed LARC users. Licensed LARC users are provided immediate response on any support issue encountered, as well as many other benefits. Please refer to the ORDER.FRM file for more information on licensing LARC. The following support options are provided: 1. You may receive support through CompuServe E-MAIL. Send your questions to SouthWind Software at 71033,3521. Licensed users will receive a response within 24 hours. ───────────────────────────────────────────────────────────────── 9 LARC User's Guide Introduction ═════════════════════════════════════════════════════════════════ 2. You may FAX your support questions or comments to SouthWind Software Incorporated at 1-205-620-0871. Licensed users will receive a response within 24. 3. You may mail your support questions or comment to: SouthWind Software Incorporated Attn: LARC Product Support 1738 Tahiti Lane Alabaster, AL 35007 When contacting us in any of the above methods, please be prepared to provide as much information about the problem as possible. Include the LARC version number and as much information concerning your system configuration as you can obtain. Include the command(s) you have tried to use, the results and a complete descriprion of the problem. When faxing a problem, please include a listing of the following files: AUTOEXEC.BAT CONFIG.SYS LARC.BAT LARC.CFG Licensed users receive immediate attention. When you license LARC, you will be provided a unique Customer Identification Number (CIN). Record your CIN in the space provided below and be sure to include this number when requesting support or assistance with a problem. ┌───────────────────────────────────────┐ │ │ │ │ └───────────────────────────────────────┘ Customer Identification Number Failure to provide the CIN may result in delays receiving support. Let Us Know What You Think ══════════════════════════ LARC was designed to make your life easier. Due to the diversity of operating environments, it's possible that you may encounter situations where LARC could be improved. We want to hear any suggestions you have for making LARC easier to use. Send or FAX your suggestions to: SouthWind Software Incorporated Attn: LARC Product Suggestions 1738 Tahiti Lane Alabaster, AL 35007 FAX: 1-205-620-0871 ───────────────────────────────────────────────────────────────── 10 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 1 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ███ ║ What is LARC? ║ ██ ║ ║ ██ ║ This chapter will discuss source control and ║ ██ ║ the specific approach taken by LARC to assist ║ ██████ ║ you with the management OF your source files. ║ ║ ╚══════════════╝ What is Source Control? ═══════════════════════ Managing source files is not an easy job. It seems simple when you have only one or two people working with the files, but add more people and in no time at all the job becomes full time. Just keeping track of who has what file can be overwhelming. Then add the task of producing a release from the various collections of sources which are now being produced by several people (all of whom seem to keep their files in different locations or formats), and you quickly reach the conclusion that you need a full time person to act as your software librarian. Many companies elect to tackle their source control problems by hiring someone to be their software librarian. This person is told to oversee which developer has which set of sources and to ensure that the latest versions are included in the product when it is built. The problems with a human librarian are obvious, once you realize there is a problem. First, all of the control methodology exists with a person which could leave your company at any time, taking with them all of your control and release standards. Next, since you rely heavily on a person, you are vulnerable to an irate employee corrupting your files. Also, no one else can easily access the sources or build a release if the librarian is either sick or away on vacation. Another method employed by some companies is the use of a central depository of sources, typically on a network server, with some form of manual check in and check out process. These manually driven control procedures rely heavily on the premise that everyone will follow the procedures exactly. The manual control procedures also usually rely on a single individual who is in charge of producing the product builds. Manually driven control procedures are both time consuming and extremely error prone. The worst method, and sadly the one employed by most companies, is no source control procedure at all. The people in charge of developing software product releases in this company typically argue that a structured release control procedure is not needed ───────────────────────────────────────────────────────────────── 11 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ because they have never encountered a problem which they believed was caused by the lack of software control. Too often the problems are hidden by programmers that do not want to admit that they made a mistake. Regrettably, it usually takes a serious and sometimes fatal software release failure to enlighten them as to the magnitude of their problem. Since you are reading this guide, it is safe to assume that you have become aware of your needs to control your sources or that you are at least evaluating the various options available to you. We are pleased that you are taking steps to control your software. We sincerely hope that you see this project through to completion and that you initiate some form of source control, be it LARC or some other package. We do have one recommendation to make before you proceed. You should ensure that your entire company is 100% behind your efforts to control your software and product releases. On numerous occasions we have witnessed development groups attempt to place their software under a control procedure only to have someone at the top request that the procedure be violated "just this once". We have also seen that once a precedence is set of violating a procedure, the procedure will be violated again and again, until you find no one using the procedure at all. We believe LARC is so simple to use that you are not likely to be put in the position of violating LARC's control procedures. Even though LARC is easily used, you are still urged to get a strong corporate policy statement on software control procedures before proceeding with your plans. In the long run, this will it much easier to implement your new source control tool. What is LARC? ═════════════ So, what is LARC and, more importantly, how does LARC define source control? Well, LARC's definition of source control is that it is simply the process of replacing nonexistent, or manual, control procedures with a simple and easy to use "electronic librarian". As your librarian, LARC helps reduce human error without over burdening the development group with an awkward or difficult to understand control procedure. LARC is a DOS or OS/2 character mode application which wraps an easy to use menu around your source files and provides an automated process for generating your software releases. The DOS version of LARC can be installed and used in a wide variety of operating environments, including Windows, virtual DOS "boxes" under OS/2 and Windows NT, or any other environment which supports DOS applications. The OS/2 version of LARC is a character-mode, full OS/2 program. You install and run the OS/2 version in either a full or windowed OS/2 screen. LARC is not a tool that will get in your way. Here are some of the things that LARC will not do to you: ───────────────────────────────────────────────────────────────── 12 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ o LARC does not modify your source files in any way. Files are maintained just the way you create or edit them. o LARC does not use delta compression techniques used by some source control systems. Your source files remain intact so you do not have to worry about your system hard drive crashing, and suddenly being stuck with a bunch of "delta" files that you can't work with. Since LARC keeps your files in their original format, you will find it easier to access your sources in such cases. o LARC does not automatically adjust the file version during check in of files. You remain in control of which files changed and which did not. o LARC does not create its own directory structure to hide your sources from you. LARC uses standard DOS directories for storing your files. o LARC does not rely on the date of your system for the revision identifier. You will not have to worry about someone changing the system date and then having the "control" of your files corrupted. LARC is designed to be a simple-to-use tool that helps you manage your sources. LARC is also designed to be easily removed from your system in the case of a catastrophic system failure, virus or other ailments that require manual recovery of your system hard drive. Since LARC uses standard DOS directories for its libraries, and since LARC maintains your files as standard DOS files, you can easily access your files from DOS if ever necessary. Library Administration... ═════════════════════════ The process of managing source files is very much like the process of managing a library of books. If you go to the library to check out a particular book, it is only possible to do if no one else has the book checked out. The comparison of source control with the process of managing a library full of books is why many companies first attempt to solve their source control problems by actually hiring a human librarian. It seems the logical thing to do. As the electronic librarian for your source files, LARC ensures that only one person at a time has a particular file checked out of a library. LARC ensures that changes to the file can not be made by more than one person at a time, which eliminates lost changes caused when two or more people are making changes to the same file at the same time. Since there is no human involved, LARC can be made available around the clock to match the preference of your programmers. ───────────────────────────────────────────────────────────────── 13 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ If you are a product manager or lead programmer in charge of a product, LARC creates various reports that help you track what's happening to your product. Reports can be generated showing the number of files that have been checked out during the current development effort. You can print a report listing all of the releases that have been created for a product. And, you can report on how many files are presently check out of a library. How many times have you started to build a release of your product only to learn half way through the build process that someone failed to give you the most current files? LARC tells you if any files are checked out of the library before it begins building your product. LARC was originally created with software developers in mind. However, LARC is well suited for anyone needing to control files. Examples of others who may find LARC useful include: Technical Writers who typically maintain large numbers of files associated with specifications, technical references, user guides or marketing material. LARC allows the technical writer to easily locate the latest copy of a particular manual. Secretaries with numerous letters, memorandum, company policies and procedures and other documents produced during the year, can use LARC to maintain an easy to access library of their documents. Network Administrators must maintain an increasingly overwhelming number of files required to properly setup the unique configurations required by their users. LARC could be used to create libraries of user configuration files, driver releases, network sign-on scripts and any number of other items required to properly maintain network users. Customer Support must maintain any number of files relating to the configuration of a customer. LARC could be used to create libraries of customer specific files and assist the support specialist in maintaining the often overlooked area of customer files. ───────────────────────────────────────────────────────────────── 14 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ ...and Release Control ══════════════════════ The process of creating releases from a set of controlled files is often overlooked. However, it is a vital step in the process of creating a product release. If you create a release which contains incorrect files, then all of your efforts at controlling your sources were of little or no use. The recipient of the release will assume the worst about your control standards and your quality assurance image is likely to suffer a severe blow. LARC considers the task of creating releases equally as important as controlling the files that constitute the release. You define the steps necessary to build the release, and LARC will ensure that those steps are properly repeated every time you build the product or every time you create a set of release diskettes. What are Source Files? ══════════════════════ The term "source" usually refers to an ASCII file that contains commands for some sort of language compiler. LARC refers to a source file as any file that you need to manage that is a part of your software product. Examples of source files are: o ASCII text files such as compiler source files, command files or text files. o Binary files such as object modules to be linked into a product, executable program files or data files. o Word processing output files such as those produced by WordPerfect and Microsoft Word. o Any other files that are required to make and release your product. What is Embedded Control Information? ═════════════════════════════════════ Most source control systems require that you define a special character string that you will place in your source files. These strings usually tell the source control system things such as what group of sources the file belongs to, the file's edit version and the name or description of the file. LARC also uses embedded strings but does not require them for all files being managed. For example, it would be impossible for you to embed strings in a vendor supplied object module, so LARC allows the strings for these types of files to be manually entered. ───────────────────────────────────────────────────────────────── 15 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ LARC searches for three special strings: Library Name This string contains the name of the library to which the file belongs. The string ensures that the file is checked into the proper library. File Version This string contains the edit version of the file. The edit version must be increased prior to the file being checked back into the library. File Description This string contains a brief description of the file which LARC shows whenever you request a display or report of files in the library. The string is not required, though it is recommended since it helps you to identify your files. You provide LARC with a list of file extensions that you want to contain embedded control information. More information on embedded control information is contained in later chapters of this guide. LARC Library Structure ══════════════════════ LARC uses standard directories for the libraries it manages. Whenever you add a new library to LARC, you tell LARC which directories are to be used. There are two types of directories maintained for each library you create: Source Directory This directory contains your source files. Release Directories Each library can have up to five directories which may contain the output of a software build procedure. You are not required to specify a release directory for the library. You only need release directories if LARC is controlling software that will be built and released. A good example of why you may need more that one release directory per library would be if you needed to produce a multi-language release of your product. You could define three release directories to contain: Release Directory 1 English language executable files. Release Directory 2 French language executable files. Release Directory 3 Spanish language executable files. ───────────────────────────────────────────────────────────────── 16 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ Another example would be to use one directory for Windows files, second for DOS files and a third for OS/2 files: Release Directory 1 Windows specific release files. Release Directory 2 DOS specific release files. Release Directory 3 OS/2 specific release files. Providing up to five release directories allows you to manage your release directories from a single reference point: LARC. You no longer are forced to rely on a manual procedure or a single person to know where the latest release (or releases) for a given product reside. Where To Begin ══════════════ LARC is not as complicated as other source control systems so it is relatively simple to place your files under LARC control. If you are currently using a manual procedure to control your sources, you should have little difficulty migrating to LARC. However, don't underestimate the task that awaits you. Even with LARC's simplistic approach to source control, you still have some work ahead of you. Placing your files under LARC control consists of the following steps: o Install LARC on your system. LARC may be installed either on a stand alone system, or on a network server. Chapter 2 describes the installation process in detail. o Define the list of LARC users. Chapters 3 and 6 should be referenced for detailed information on user security and adding users to LARC. o Perform a detailed review of your current source files. You will need to define which groups of source files you want to place in separate libraries. o Compile a detailed list of all of the file extensions which contain source code and which you want to have LARC automatically search for embedded control information. Chapter 5 describes embedded control information in more detail. o Once you have defined the number of libraries you need, use LARC to create the libraries. Chapter 4 describes the process of adding new libraries to LARC. ───────────────────────────────────────────────────────────────── 17 LARC User's Guide Chapter 1 - What is LARC? ═════════════════════════════════════════════════════════════════ o Once you have compiled the list of source files which LARC will search for embedded control information, use LARC to create the list of file extensions to be automatically searched. Chapter 5 describes the process of adding file extensions to LARC. o You must then edit all of the source files that you have told LARC will contain embedded control information and add the information to the files. o Once the control information has been added to the files, check the files into LARC and verify that you indeed added them to the correct library. Chapter 10 describes the process of adding new files to a LARC library. o If the library contains sources that will be built and released, you will need to create and debug the build, release generation and backup control files for the library. Chapter 8 describes the files required to create releases. o Document the newly created library structure and provide this information to any other LARC users in your company. o Perform a complete system backup of your newly configured LARC system as a safeguard against any possible system failure. You are also highly recommended to define a rigorous backup schedule for your LARC system files. This is a brief overview of the steps required to create a LARC library. Creating your first library will take longer than others to create because you have some one-time LARC configuration steps to complete. More detailed information on each of these steps may be found in subsequent chapters in this guide. ───────────────────────────────────────────────────────────────── 18 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 2 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ▄████▄ ║ Installing LARC ║ ▀▀ ██ ║ ║ ▄█▀ ║ This chapter explains how to install LARC on ║ ▄█▀ ║ your hard disk. ║ ██████ ║ ║ ║ ╚══════════════╝ DOS System Requirements ═══════════════════════ LARC requires the following of a DOS host system: o Intel 80286 compatible or higher based personal computer. o DOS 3.3 or later (MS-DOS 6.0 or later is recommended). o 300K of conventional memory (up to 530k of conventional memory if you use compressed libraries). o One 3½" (720K or 1.44 MB) or one 5¼" (360k or 1.2 MB) floppy diskette drive, or both. o A hard disk drive with 800K of free space for installing LARC. More space will be required for the files which LARC will maintain. o A standard VGA monitor. o A standard dot matrix or laser printer is recommended. OS/2 System Requirements ════════════════════════ LARC requires the following of a OS/2 host system: o Intel386SX compatible or higher based personal computer. o OS/2 2.0 or later (OS/2 2.1 is recommended). o 4.0 of memory minimum (6.0 or greater is recommended). o One 3½" (720K or 1.44 MB) or one 5¼" (360k or 1.2 MB) floppy diskette drive, or both. o A hard disk drive with 600K of free space for installing LARC. More space will be required for the files which LARC will maintain. o A standard VGA monitor. o A standard dot matrix or laser printer is recommended. ───────────────────────────────────────────────────────────────── 19 LARC User's Guide Chapter 2 - Installing LARC ═════════════════════════════════════════════════════════════════ Installing LARC ═══════════════ Before installing LARC, print and the review the READ.ME file. READ.ME may contain last minute changes to the installation procedure. 1. It is recommended that you perform a complete backup of your target hard drive prior to installing any new software on your system. Having this backup on hand will provide extra insurance in case you accidentally enter an incorrect command durring the installation period. 2. Create a LARC system directory by entering the command: md C:\LARC3 Of course you will replace the "C:" with the letter of the drive that you want LARC to be installed on. You can also use a different directory name, if so desired. 3. LARC is provided in a self-extracting file. Enter: LARCDOS (for DOS) or: LARCOS2 (for OS/2) 4. Make any necessary changes to your system startup files. The possible changes are described in the following section "Modifying Your DOS (or OS/2) System Startup Files". 5. Edit the LARC Configuration File to reflect the location of the LARC system files. The changes required are described in the following section "LARC's Configuration File". 6. Start LARC and establish your list of users, file names that will contain embedded control information, and libraries to be managed. More information on establishing users and libraries are described in subsequent chapters. Modifying Your DOS System Startup Files ═══════════════════════════════════════ In order to run the DOS version of LARC, you must edit your AUTOEXEC.BAT file and include the LARC installation drive letter and path in the system PATH statement. For example, assuming you installed into the default path, your PATH statement would be: PATH=C:\DOS;C:\LARC3;C:\UTIL ───────────────────────────────────────────────────────────────── 20 LARC User's Guide Chapter 2 - Installing LARC ═════════════════════════════════════════════════════════════════ LARC submits files for printing using the DOS system PRINT command. Unless you use a replacement print spooler, you may need to load PRINT when your system starts in order to eliminate memory fragmentation. Since PRINT is a terminate-and-stay-resident (TSR) program, it loads into memory at the first available free space, and then stays there! If LARC causes PRINT to be loaded into memory, it will be loaded behind LARC. To illustrate, lets assume LARC uses 200kb of 500kb of available memory. If LARC prints a file, PRINT will be loaded into memory at about the 200kb mark. This means that you will be left with 200kb and 300kb as the largest available free "chunks" of memory. This could cause LARC or other DOS applications to fail with an "insufficient memory" error. To load PRINT when your system starts, include the following line in your AUTOEXEC.BAT command file: PRINT /D:LPTn: Replace "n" with the printer port number you are using. You will most often use LPT1:. If LARC will run on a dedicated PC, you may want to have LARC started automatically whenever the PC is turned on. If so, you will need to edit your AUTOEXEC.BAT file to include the following commands at the end of the file: drive: CD LARC-path LARC "drive" is the drive letter and "LARC-path" is the path name where you install the LARC program. You must add the LARC installation directory to the system PATH statement in the AUTOEXEC.BAT file. For example, if your current path statement contains a "C:\DOS;C:\UTIL", then you should change the statement to "C:\DOS;C:\UTIL;C:\LARC3". "C:\LARC3" would be the LARC installation drive and directory name. If you installed LARC into any directory other than C:\LARC3, you will need to edit the LARC.BAT file that is delivered with LARC and adjust it according to where you installed LARC. For example, if you installed LARC to D:\LARC3, then LARC.BAT would need to be changed to: D:\LARC3\LARC3 D:\LARC3\LARC.CFG Modifying Your OS/2 System Startup Files ════════════════════════════════════════ The OS/2 version of LARC requires that you include your installation drive and directory in the LIBPATH. This is required so LARC will be able to properly locate the DLL files included with the OS/2 version of LARC. ───────────────────────────────────────────────────────────────── 21 LARC User's Guide Chapter 2 - Installing LARC ═════════════════════════════════════════════════════════════════ If you need to access LARC from various directories on your system, you will need to either include the LARC installation drive and directory in your search path, or move the LARC.CMD file from the LARC directory to a directory which is currently in your PATH statement. For example, if your path contains a "\UTIL" directory in which you keep your utility programs and command files, then the "\UTIL" directory would be a perfect location for the LARC.BAT file. If you installed LARC into any directory other than C:\LARC3, you will need to edit the LARC.CMD file and adjust it according to where you installed LARC. For example, if you installed LARC to D:\LARC3, then LARC.CMD would need to be changed to: D:\LARC3\LARC3 D:\LARC3\LARC.CFG LARC's Configuration File ═════════════════════════ Once LARC has been installed on your system, you will need to edit the configuration file LARC.CFG. LARC.CFG is an ASCII file that you can edit to change the characteristics of many of LARC's features. LARC.CFG specifies several details on your particular installation, including: o LARC program and data file location. o screen inactivity timeout interval. o the type of access security to be used. o default file check in and check out path handling. o existing file check out overwrite handling. o LARC system screen colors. o printer condensed and normal print settings. o floppy diskette drive letters. The majority of these settings will be described in a subsequent chapter. The default configuration file installed with LARC assumes that you installed LARC to C:\LARC3. If you installed LARC to a different drive or path, then you must edit the configuration file and change the following SET commands and specify the correct directories: SET SYSTEM EXECUTABLES C:\LARC ; Program files SET SYSTEM DATAFILES C:\LARC ; Data files You may also need to set up the correct drive letters for the floppy diskettes configured on your LARC system. If so, then inspect the following SET commands and change them as required: ───────────────────────────────────────────────────────────────── 22 LARC User's Guide Chapter 2 - Installing LARC ═════════════════════════════════════════════════════════════════ SET FLOPPY 360KB B ; 360kb floppy drive letter SET FLOPPY 1.2MB B ; 1.2mb floppy drive letter SET FLOPPY 720KB A ; 720kb floppy drive letter SET FLOPPY 1.44MB A ; 1.44mb floppy drive letter The remaining SET commands may be inspected and changed (if necessary) as you become more familiar with the setup and operational features provided by LARC. Refer to chapter 7 for more information on LARC's configuration file. Multi-User Installation Requirements ════════════════════════════════════ LARC monitors which functions are being used in order to ensure that multiple users are not trying to check out or check in the same file to the same library at the same time! LARC allows several users in a multi-user environment (such as a Novell network) to access it's libraries simultaneously without loss of information. This means that LARC may be installed on a network drive and accessed as if it were installed on your local hard drive. You may also choose to install the LARC system files on each local machine yet have the LARC data files reside on a network drive. Either method is acceptable and depends on personal preference, speed of your network, and your license agreement. One good example of when you may want to install LARC differently comes to light when you consider a laptop machine. Lets assume that you develop a product and have access to a network. Your office machine is connected to the network via a high speed link (Ethernet, etc.) so you elect to install LARC on a network drive so that you and the other developers in your group can access a single LARC system. This eases the process of maintaining the LARC system files by limiting the number of installed copies to one! Now, lets assume that you need to travel to a customer site and possibly make changes after seeing your code execute in the field. You could install the LARC executable files directly onto your laptop and use a modem gateway into your network to access the LARC controlled sources from the field. The advantage to this method is, of course, increased speed of loading the LARC executable files since they would be loaded from your laptop and not loaded remotely over the modem. A very important consideration for network installation is with drive letter mapping. LARC requires that you specify the hard drive letter for each library when the library entry is created. For example, a "Product Tools" library may have been established and directed to hard drive M: which is mapped to server SERVER-A. If a user maps drive M: to any server other than SERVER-A, then tries to access the library with LARC, LARC will complain that the library files can not be located. You will need to ensure that all LARC users map the LARC drive letters the same way every ───────────────────────────────────────────────────────────────── 23 LARC User's Guide Chapter 2 - Installing LARC ═════════════════════════════════════════════════════════════════ time they use LARC. If your mapping changes often, then you may want to add the appropriate mapping commands to the LARC.BAT file in order to always ensure that the drive letter is properly mapped when LARC is started. How often is your network taken down, either voluntarily or involuntarily? If your network is frequently brought down for maintenance, reconfiguration, power outages, testing, etc., then you may want to install LARC and all of your LARC libraries on a stand alone system. Otherwise, assuming that you are in a stable network environment and that all of your LARC users are consistently mapped, then LARC is oblivious as to whether it is being executed from a network server or from a local or stand alone system. The only requirement is to edit the LARC configuration file LARC.CFG and start up file LARC.BAT to point them to the proper network drive and path. ───────────────────────────────────────────────────────────────── 24 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 3 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ▄████▄ ║ System Security ║ ▀▀ ██ ║ ║ ███ ║ This chapter explains the system security ║ ▄▄ ██ ║ provided by LARC. ║ ▀████▀ ║ ║ ║ ╚══════════════╝ Security Options ════════════════ LARC provides three types of user access security: o No security. Everyone has access to all LARC files and features. o One time log on security. Users must be known to LARC and log on once when LARC is started. Security is not checked before exiting LARC to the operating system. This option is intended for users who will either run LARC on their local machine or from a shared network environment. o Complete security. Users must be known to LARC and log on every time a library or function is selected. Security will be checked before exiting LARC to the operating system and only users with a specific access level will be allowed to exit LARC. This option is intended for users who will run LARC on a stand alone system. It provides the highest level of security and ensures that LARC remains in control of the system on which it is running. Most users are not allowed to exit LARC, which reduces the chances that a user could accidentally change the setup of the system on which LARC is running. User Initials and Passwords ═══════════════════════════ Each user has several parameters that are used by LARC whenever he or she logs on to LARC. There are: User Initials: 1 to 3 characters that are the initials of the user. LARC uses these initials to determine the user's access rights and to record user activity in the system activity log. Password: 1 to 10 characters that are the password for the user. ───────────────────────────────────────────────────────────────── 25 LARC User's Guide Chapter 3 - System Security ═════════════════════════════════════════════════════════════════ Level: 1 character security access level for the user. Level 9 users have the highest access rights and are known as System Administrators. System Administrators have complete access to all of LARC's files and features. Path: 1 to 66 character path name that is the default file check out and check in path. This path is used as the default file copy path if the user does not provide a path to the check in and check out functions. If you leave this path blank, then LARC will check out files and check in files using the path from which LARC was started. ╔═════════════════════════════════════════════════════╗ ║ NOTE: Neither the user's initials nor the user's ║ ║ password are case sensitive. So, "ABC", ║ ║ "abc" and "AbC" would all be equivalent. ║ ╚═════════════════════════════════════════════════════╝ Security Access Levels ══════════════════════ The LARC System Administrator will assign a unique security access level ranging from 1 to 9 to each LARC user. When the user logs onto LARC, this security access level will determine which LARC features the user may use. Level 1 is the lowest level and level 9 is the highest. Level 9 provides complete access to all of LARC's features. Table 3-1 defines the list of features and the security access level required to gain access to each feature. LARC is delivered with no user security file defined so access rights will not be initiated until after the System Administrator creates a list of users. The Security Screen ═══════════════════ Depending on how LARC has been configured, the security screen may be presented only once when LARC is started. However, LARC may have been configured to present the security screen every time a function is selected that requires a security access level check. Most LARC functions require that the user's initials and password be entered before access can be granted. If the initials and password are valid, LARC performs a security access level check and will not allow the user to access the function if he fails to meet the function's access level requirements. You may press the <Esc> key to back out to the previous menu or screen if you decide that you do not want to continue. However, if LARC has been configured so that you only log on once when LARC is started, then pressing the <Esc> will exit LARC and return you to the operating system prompt. ───────────────────────────────────────────────────────────────── 26 LARC User's Guide Chapter 3 - System Security ═════════════════════════════════════════════════════════════════ If you enter an incorrect user name or password, or if your security access level is insufficient to allow access to the selected function, a warning message will be displayed and access to the function will be denied. If you are unable to access a function, then you have probably not been given a high enough access level to use the function. You should discuss your needs with your LARC System Administrator to determine if it is possible for your security access level to be increased. Exiting to the Operating System ═══════════════════════════════ If your security access level allows you to exit to the operating system, and if LARC has been configured to require a security check before exiting, you must enter your user name and password before you can exit LARC. If you have sufficient security rights, LARC will exit and return you to the operating system prompt. Creating a List of Users ════════════════════════ Refer to Chapter 6 for details on establishing and maintaining the list of LARC users. ───────────────────────────────────────────────────────────────── 27 LARC User's Guide Chapter 3 - System Security ═════════════════════════════════════════════════════════════════ ╔══════════════════════════════════╦════════════════╗ ║ Feature ║ Security Level ║ ╠══════════════════════════════════╬════════════════╣ ║ Select a library ║ 1 ║ ║ Check in a file ║ 5 ║ ║ Check out a file ║ 5 ║ ║ Add a new file ║ 5 ║ ║ Copy a file ║ 5 ║ ║ Cancel a file check out ║ 5 ║ ║ Get All Files ║ 5 ║ ║ Delete a file ║ 7 ║ ║ Display library contents ║ 1 ║ ║ Display source file ║ 1 ║ ║ Display my checked out files ║ 5 ║ ║ Display checked out files ║ 1 ║ ║ Display release history ║ 1 ║ ║ Display revised files ║ 1 ║ ║ Display system activity log ║ 5 ║ ║ Print library contents ║ 1 ║ ║ Print source file ║ 3 ║ ║ Print my checked out files ║ 5 ║ ║ Print checked out files ║ 1 ║ ║ Print release history ║ 1 ║ ║ Print revised files ║ 1 ║ ║ Print system activity log ║ 5 ║ ║ Create 360kb release diskettes ║ 4 ║ ║ Create 1.2mb release diskettes ║ 4 ║ ║ Create 720kb release diskettes ║ 4 ║ ║ Create 1.44mb release diskettes ║ 4 ║ ║ Create hard drive release ║ 4 ║ ║ Release build ║ 5 ║ ║ Backup library source files ║ 1 ║ ║ Purge test release identifiers ║ 8 ║ ║ Submit a system command ║ 5 ║ ║ Backup the entire system ║ 1 ║ ║ Format system backup media ║ 1 ║ ║ Library maintenance ║ 8 ║ ║ Extension maintenance ║ 8 ║ ║ User maintenance ║ 8 ║ ║ Exit to the Operating System ║ 8 ║ ╚══════════════════════════════════╩════════════════╝ ──────────────────────────────────────────────────────────── Table 3-1 - Security Access Levels ───────────────────────────────────────────────────────────────── 28 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 4 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ▄███ ║ Library Maintenance ║ ▄█▀ ██ ║ ║ ██▄▄██ ║ This chapter explains how to configure the ║ ██ ║ libraries that LARC will maintain. ║ █████ ║ ║ ║ ╚══════════════╝ Library Structure ═════════════════ Libraries are simply a set of standard system directories which LARC uses to store files. There are two types a directories: Source Directories: These directories contain your source files. Release Directories: Each library can have up to five directories which will contain the output of your build procedures. You are not required to specify a release directory for every library. In fact, there will be some cases where you only define a source directory for a library. The five release directories allow you to create up to five unique releases from the same set of sources. LARC supports directory names of up to 64 characters in length. This provides the ability to segment your files into logical directories based upon any number of categories you may need to define. It is important to know that LARC loosely associates libraries that share a common initial directory. Lets assume you are defining four libraries that will contain source files for your product. An example directory structure could be: C:\PRODUCT\ C:\PRODUCT\MAIN\ C:\PRODUCT\REPORTS C:\PRODUCT\COMMS Since these four libraries all share the same initial directory "PRODUCT", LARC will group these libraries together when it performs the following functions: Display or Print Checked Out Files - Whenever you ask LARC to show or print a list of all of the checked out files from a library, LARC will show you any file checked out of all of the libraries that share the same initial directory. Using the previous directory structure example, LARC would show you any files that were checked out of any one of the four libraries that ───────────────────────────────────────────────────────────────── 29 LARC User's Guide Chapter 4 - Library Maintenance ═════════════════════════════════════════════════════════════════ share the "PRODUCT" initial directory. Release Build - Whenever you ask LARC to build a release, LARC scans the library and lets you know if any files are still checked out of the library. When libraries share an initial directory, LARC will scan all of the libraries which share the initial directory and let you know if any files are still checked out of any one of the libraries. Again using the previous directory structure example, LARC would let you know if any files were checked out of any one of the four libraries that share the "PRODUCT" initial directory. Other than this loose association of initial directories, you are free to define your LARC directory structure to meet your specific needs. The only thing that must occur is that a previous level directory must exist before you try to specify a new sub-directory name. For example, you must create a library (or there must already be a directory present) that uses the "PRODUCT" directory before you define a library that uses the "\PRODUCT\REPORTS\" directory. This is necessary because LARC will not scan the entire directory name to create previous directory levels. LARC enforces this restriction to help reduce the possibility that someone could enter an incorrect directory name, which would then cause several erroneous directories to be created. Library Maintenance ═══════════════════ The Library Maintenance function is selected from the Main Menu by moving the highlight bar to maintenance on the Maintenance pull down menu. Only the System Administrator can use this function to maintain the libraries in the system. Select the library maintenance option by pressing the <L> key or by moving the menu bar to library maintenance and pressing <Enter>. The following field names are used by the library maintenance functions: Library number: This is the three digit library number that LARC automatically assigns to the library whenever it is created. This library number is important because you use this number when defining the LARC release diskette creation (cut) files (LARCRELn.CUT). Refer to Chapter 13 more information on release creation files. ───────────────────────────────────────────────────────────────── 30 LARC User's Guide Chapter 4 - Library Maintenance ═════════════════════════════════════════════════════════════════ Library name: Up to fifty alphanumeric characters that contain the name of the library. The system name string embedded in source files destined for this library must match this name exactly before LARC will allow the file to be added or checked in to the library. Compress files?: "Y" indicates that the library is a compressed library and that files checked into the library will be compressed into a single compressed file. See the section "Compressed Libraries" below for more information. Third party library?: "Y" indicates that the library contains files supplied by a third party vendor. "N" indicates that the library is standard library. Unlike other libraries, source files checked into a third party library will not be searched for embedded control strings. This allows you to put original copies of vendor supplied files under LARC control with modification. Installation files?: A "Y" in this column indicates that installation control files will be created by LARC when a set of release diskettes are created. See the section "Installation Files" below for more information. Write protect files?: "Y" indicates that the library files should be marked as read-only after they are added to the library. "N" indicates that the files should not be marked read-only. It is highly recommended that libraries be marked read-only unless you encounter a specific reason not to do so. For example, some third party tools may not function correctly if they are marked read-only. Maintain revisions?: A "Y" in this column indicates that the last version of the updated files will be kept by LARC. See the section "Revised Files" below for more information. Source: Up to 64-alphanumeric characters that contain the name of the source file directory. The directory will be created by LARC if it does not already exist. Begin the directory name with the drive letter, colon and backslash characters. For example, "C:\PRODUCT\SOURCES". ───────────────────────────────────────────────────────────────── 31 LARC User's Guide Chapter 4 - Library Maintenance ═════════════════════════════════════════════════════════════════ Release n: Up to 64-alphanumeric characters that contain the name of the release directory. There may be from zero to five of these entries. The release directories will be created if they do not already exist. Begin the directory name with the drive letter, colon and backslash characters. For example, "C:\PRODUCT\RELEASES". Add a Library ═════════════ This function is used to add a new library to LARC. Press the <End> key when you have entered the new library information. The information will be stored in the library name file and you will return to the System Maintenance Menu screen. Modify a Library ════════════════ This function is used to modify library information. You will be presented a list of available libraries. Select the library that is to be modified and the details of the library will be displayed. Press the <End> key when you have entered the modified library information. The information will be stored in the library name file and you will return to the System Maintenance Menu screen. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when changing ║ ║ library information. You can modify the ║ ║ parameters for any library, even libraries ║ ║ with active releases, so make sure that you ║ ║ carefully review all of the displayed ║ ║ information to ensure that the correct ║ ║ library is being changed. ║ ╚═════════════════════════════════════════════════════╝ If you change the source directory name, LARC will move all of the source files contained in the old directory to the new directory. The old directory will be removed from the system. If you change one or more of the release directory names, LARC will move all of the files contained in the old directory to the new directory. The old directory will be removed from the system. Delete an Obsolete Library ══════════════════════════ This function is used to remove an old library and the system. You will be presented a list of available libraries. Select the library that is to be deleted and the details of the library will be displayed. You will then be asked to verify that you want to deleted the displayed library from LARC. ───────────────────────────────────────────────────────────────── 32 LARC User's Guide Chapter 4 - Library Maintenance ═════════════════════════════════════════════════════════════════ Press the <Y> key if you are absolutely sure you want to delete the library. Press any other key to abort the delete process. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when deleting ║ ║ libraries from LARC. You can delete any ║ ║ library, even libraries with active releases. ║ ║ Make sure that you carefully review all of ║ ║ the displayed information to ensure that the ║ ║ correct library is being deleted. ║ ╚═════════════════════════════════════════════════════╝ Show All Libraries ══════════════════ When you choose the Show All Libraries function, you will be presented with a list of all of the available libraries. When you select a library, the information for that library will be displayed on the screen. Select the desired library and the information for that library will be displayed. Libraries are sorted in ascending order based on the name of the library. If you press the first letter of the library, the highlight bar will be moved to that library. For example, pressing the <H> key will move the highlight bar to the first library whose name begins with the letter H. Print All Libraries ═══════════════════ This function creates a printed report listing of all of the libraries that LARC is maintaining. Compressed Libraries ════════════════════ LARC allows each library you create to be marked as a compressed library. Marking a library as a compressed library simple instructs LARC to use the file compression utilities PKZIP provided by PKWare, Incorporated, to compress the library files into a single compressed "ZIP" file. The resulting compressed file name will reside in the source directory with the name of the last directory in the source library path name. For example, if you create a compressed library and define its source directory name as C:\EXAMPLE\FILES, then the compressed ZIP file will be named FILES.ZIP. Any library can be marked as a compressed library. However, you should consider the following issues before creating a compressed library: ───────────────────────────────────────────────────────────────── 33 LARC User's Guide Chapter 4 - Library Maintenance ═════════════════════════════════════════════════════════════════ o Compressed libraries save considerable disk space, especially for ASCII files such as sources or text file. You will, of course, be required to decompress the library as part of your build process in order to build your product. o Space required for word processing files is also considerably reduced when stored in compressed libraries. If possible, word processing files should always be stored in compressed libraries. However, you do not necessarily have to do so using a compressed library. You could compress them manually and store the resulting compressed file in a standard library. Either method achieves the same end result of saving disk space. o LARC is designed to use PKZIP.EXE and PKUNZIP.EXE version 2.04g for DOS. PKZIP.EXE and PKUNZIP.EXE are sold and licensed by PKWARE Incorporated and you must have a properly licensed version. These utilities can be downloaded from CompuServe as well as many local Bulletin Board Systems and the downloaded file contains detailed information on how to license the utilities from PKWARE, Incorporated. o Since LARC relies heavily on PKZIP and PKUNZIP for managing compressed libraries, the possibility exists that your compressed files could be corrupted should either PKZIP or PKUNZIP encounter some unforeseen problem. You should be completely aware of this risk and make sure that you back up your sources often to reduce your risk. ╔═════════════════════════════════════════════════════╗ ║ NOTE: PKZIP.EXE and PKUNZIP.EXE are not provided ║ ║ with LARC. If you want to take advantage of ║ ║ the compressed library feature, you need to ║ ║ obtain and license PKZIP and PKUNZIP from ║ ║ PKWARE, Incorporated. ║ ╚═════════════════════════════════════════════════════╝ Installation Files ══════════════════ When you create a library, you have the option of having LARC create what are referred to as installation files on your release diskettes. Installation files are simple ASCII files that LARC creates on your release diskettes which list, among other things, the contents of the release diskettes. These installation files can be used by the LARC installation program to provide a simple automated installation procedure for your product releases. Refer to Chapter 16 for more information on the LARC installation program. The installation files are named DISKnn.CTL where the nn portion of the file name refers to the release diskette sequence number. For example, DISK01.CTL would list the installation files and commands for the first release diskette, DISK02.CTL would list ───────────────────────────────────────────────────────────────── 34 LARC User's Guide Chapter 4 - Library Maintenance ═════════════════════════════════════════════════════════════════ the installation files and commands for the second release diskette, and so on. You control what gets written to these installation files as part of creating the release definition files for the library. The release definition files, and the process of defining the installation file commands, will be discussed in greater detail in Chapter 13. Revised Files ═════════════ Each library that you create can be configured to retain previous revisions of files. LARC's management of previous revisions is quite simple. Lets say you have file EXAMPLE.TXT checked into a library that has been configured to maintain revisions. You edit the file and increase the embedded version number from 100 to 101. When you check the file back into the library, LARC will rename the version 100 copy of the file to LARCRVSN.nnn where "nnn" is a sequential number that starts at 001. LARC updates the library control file to show you the newly created LARCRVSN file and stores the original file name in the description field. You have complete access to all previous revisions using the standard LARC menus. Previous revisions can't be checked out, but they can be copied and deleted from the library. You can have up to 999 revisions per library. If you delete an early revision, LARC will reuse the deleted revision number. For example, if you had forty revisions in a library, then deleted the first ten, LARC would reuse number 001 the next time you checked in a file. This simple approach to maintaining previous revisions makes it possible for you to quickly return to a previous version of a file if that ever becomes necessary. Also, you do not have to decide to maintain revisions when the library is created. You can turn this option on later. Likewise, if you turned the option on, then later decided it was no longer required, you may turn it off and previous revisions saves will cease. ───────────────────────────────────────────────────────────────── 35 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 5 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ██████ ║ Extension Maintenance ║ ██ ║ ║ ▀████▄ ║ This chapter explains how to maintain the list ║ ██ ║ of file extensions that LARC will search for ║ █████▀ ║ embedded control information tokens. ║ ║ ╚══════════════╝ File Control Information ════════════════════════ LARC must know three things to control files you add or check into a library: 1. The library in which file belongs. 2. The edit version number of the file. 3. A brief description of the file. LARC will allow you to enter this information in one of two ways. You may either provide the information manually or, for most of your files, you can include three special character strings which LARC can search for to automatically retrieve the information. When you elect to include the information in the file, LARC calls the three special character strings "embedded control information tokens" or simply "tokens". You will likely be required to manually enter the information for binary files such as object modules or program files because these files can not be easily edited. However, it is likely that most of your ASCII files can be edited to include the embedded control information. Including the information in your ASCII files will greatly reduce the amount of manual information you must enter when adding or checking files into a library. In order to embed control information in your files, you must first define the list of file types that can contain embedded information. You then provide this list to LARC so that LARC will know which files you expect to be automatically searched. Note that if you add an extension to LARC's list, then the embedded control information tokens must exist in the file before the file can be added or checked into a library. ───────────────────────────────────────────────────────────────── 36 LARC User's Guide Chapter 5 - Extension Maintenance ═════════════════════════════════════════════════════════════════ The three embedded control information tokens are: Library Name: This token contains the one to fifty character name of the library that "owns" the file and this token ensures that the file is checked into the proper library. The token must match the library name of the library into which the file is being added. The text defined by the token is case sensitive, so you need to make sure you enter the name of the library exactly as appears for the owner library. File Version: This token contains the three character edit version of the file. The edit version must be incremented before you try to return a checked out file to the library. Failure to properly increment the version number will cause LARC to reject the check in operation. File Description: This token contains a brief one to forty character description of the file. LARC shows this description whenever you request a display or report that lists the files in the library. The token is not required, though it is recommended since it allows you to easily identify your files. When you add or check in a file, LARC first determines if the extension portion of the file name matches one of the automatic search extensions. If a match is found, LARC will search the file for the embedded control information tokens. You get to control which files contain embedded control tokens by creating and maintaining a list of extensions to be searched. Some examples may help clarify how this works. Lets assume you are developing a small C-based program that uses the following files: EXAMPLE.C C language main source file. SUBS.C C language subroutine file. EXAMPLE.H Included header definition file. EXAMPLE.MAK Program make definition file. GO.BAT DOS Make-n-Execute batch file. You would tell LARC that there are four extension types that it should search for embedded control information. These four types are C, H, MAK and BAT. However, in order to tell LARC about the extensions, you need to define the character sequences that you want to use for the three tokens. To do this, you must decide how the three strings will be used in your code. For example, it's possible to use the control strings as part of a C-based routine so that the description and version used by LARC are ───────────────────────────────────────────────────────────────── 37 LARC User's Guide Chapter 5 - Extension Maintenance ═════════════════════════════════════════════════════════════════ also used by your code. The token information containing the program description and version could be displayed on the screen when the program is executed. So for a C-based source, you could define your embedded tokens in one of two ways: As comments only: // // LARC-L "Example Library" // LARC-D "Program Description" // LARC-V "100" // : : [ actual code ] : : As integrated code #define LARC_L "Example Library" #define LARC_D "Program Description" #define LARC_V "100" : : printf( "%s\n%s V%s", LARC_L, LARC_D, LARC_V); : : It is highly advantageous to use the embedded information for both LARC control and your code because the end user would be able to speak to you using the same terms that your programmers use. However, this may be a bit much to accomplish while trying to get a large system under LARC control for the first time. You may find it easier to start by adding the information as comments, then integrate them into your source codes at a later time. LARC certainly supports either decision. You can use any data string for your embedded tokens, but it is recommended that you use a unique sequence of characters to ensure that LARC does not find false tokens in your file. Lets assume that you are adding a C language source file extension of "C" to your list. You could define your tokens as follows: o Use a double quote " character as your token separator. o Use LARC-L as your library name token. o Use LARC-D as your file description token. o Use LARC-V as your file version token. ───────────────────────────────────────────────────────────────── 38 LARC User's Guide Chapter 5 - Extension Maintenance ═════════════════════════════════════════════════════════════════ Your batch command file would contain the following lines of code to comply with the above listed embedded control token information: ECHO OFF REM REM LARC-L "Library Administration and Release Control" REM LARC-D "Example DOS Command File" REM LARC-V "100" REM DIR *.* >PRN: ╔═════════════════════════════════════════════════════╗ ║ NOTE: LARC also makes the system wide release build ║ ║ version token available to your build process ║ ║ which means an overall system release build ║ ║ identifier can be included in your sources. ║ ║ Chapter 13 describes this system wide release ║ ║ build version token in more detail. ║ ╚═════════════════════════════════════════════════════╝ Extension Maintenance ═════════════════════ The Extension Maintenance function is selected from the Main Menu by moving the highlight bar to extension maintenance on the Maintenance pull down menu. Only the System Administrator can use this function to maintain the list of extensions in the system. Select the extension maintenance option by pressing the <E> key or by moving the menu bar to extension maintenance and pressing <Enter>. The following field names are used by the extension maintenance functions: Extension: One to three character file extension. All files with this extension must contain embedded token strings. Separator: One character delimiter such as ' or " which defines the character that will signal the start and end of the text that is to be associated with each of the embedded tokens. Library name token: One to twenty character library name token. When found in the source file, the text string is compared against the name of the selected library to ensure that files are not accidentally checked into the wrong library. ───────────────────────────────────────────────────────────────── 39 LARC User's Guide Chapter 5 - Extension Maintenance ═════════════════════════════════════════════════════════════════ File description token: One to twenty character file description token. This token is used to define an optional descriptive text for the file which will be display and printed by LARC whenever the file name is referenced. File version token: One twenty character file version token. This token is used to define the edit version of the file. When found, this version number is compared against the previous file version number to ensure that the user properly increments the version before checking the file back into the library. Add an Extension ════════════════ This function is used to add a new extension to LARC. When selected, you will be asked to enter the new extension you are adding to the system. Once you have entered a unique new extension, you may then enter the token information that you want associated with the new extension. Press the <End> key when you have entered the new extension information. The information will be stored in the extension name file and you will return to the System Maintenance Menu screen. Modify an Extension ═══════════════════ This function is used to modify extension information. Enter the extension that is to be modified and the details of the extension will be displayed. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when changing ║ ║ extension information. You can modify the ║ ║ parameters for any extension, even extensions ║ ║ with active files, so make sure that you ║ ║ carefully review all of the displayed ║ ║ information to ensure that the correct ║ ║ extension is being changed. ║ ╚═════════════════════════════════════════════════════╝ ───────────────────────────────────────────────────────────────── 40 LARC User's Guide Chapter 5 - Extension Maintenance ═════════════════════════════════════════════════════════════════ Once you have selected the extension you may then change the token information for that extension. Press the <End> key when you have entered the modified extension information. The information will be stored in the library name file and you will return to the System Maintenance Menu screen. Delete an Obsolete Extension ════════════════════════════ This function is used to remove obsolete extensions from the system. Enter the extension that is to be deleted and the details of the extension will be displayed. You must then verify that you have indeed entered the correct extension before it can be deleted. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when deleting ║ ║ extensions from LARC. You can delete any ║ ║ extension, even extensions with active files. ║ ║ Make sure that you carefully review all of ║ ║ the displayed information to ensure that the ║ ║ correct extension is being deleted. ║ ╚═════════════════════════════════════════════════════╝ Press the <Y> key if you are absolutely sure you want to delete the extension from the system. Press any other key to return to the System Maintenance Menu screen. Show All Extensions ═══════════════════ This function will display a list of all of the available extensions. Print All Extensions ════════════════════ This function will print a list of all of the available extensions. ───────────────────────────────────────────────────────────────── 41 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 6 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ▄████▄ ║ User Maintenance ║ ██ ▀▀ ║ ║ █████▄ ║ This chapter explains how to maintain the list ║ ██ ██ ║ of users that LARC will allow to access the ║ ▀████▀ ║ libraries. ║ ║ ╚══════════════╝ User Maintenance ════════════════ The User Maintenance function is selected from the Main Menu by moving the highlight bar to user maintenance on the Maintenance pull down menu. The System Administrator can use this function to maintain information for all users. Individual users can use this function to maintain their own information. Select the user maintenance option by pressing the <U> key or by moving the menu bar to user maintenance and pressing <Enter>. The following field names are used by the user maintenance functions: User Initials: One to three characters that are the initials of the user. LARC uses these initials to determine the user's access rights and to record user activity in the system activity log. Password: One to ten characters that are the password for the user. Level: One character security access level for the user. Level 9 users are have the highest access rights and are referred to as System Administrators. System Administrators have complete access to all of LARC's files and features. Path: One to sixty-six character path name that is the default file check out and check in path for the user. This path is used as the default file copy path if the user does not provide a path to the check in and check out functions. If you leave this path blank, then LARC will check out files and check in files using the path from which LARC was started. ───────────────────────────────────────────────────────────────── 42 LARC User's Guide Chapter 6 - User Maintenance ═════════════════════════════════════════════════════════════════ Add a User ══════════ This function is used to add a new user to LARC. Press the <End> key when you have entered the new user information. The information will be stored in the user name file and you will return to the System Maintenance Menu screen. Modify a User ═════════════ This function is used to modify user information. Select the user that is to be modified and the details of the user will be displayed. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when changing user ║ ║ information. You can modify the parameters ║ ║ for any user, even active users, so make sure ║ ║ that you carefully review all of the displayed║ ║ information to ensure that the correct user is║ ║ being changed. ║ ╚═════════════════════════════════════════════════════╝ Once you have entered the initials, you may then enter the changes to that user's information. Press the <End> key when you have entered the changes for the user. The information will be stored in the user name file and you will return to the System Maintenance Menu screen. Delete an Obsolete User ═══════════════════════ This function is used to remove obsolete users from the system. Enter the initials of the user that is to be deleted and the details of that user will be displayed. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when deleting users║ ║ from LARC. You can delete any user, even ║ ║ active users with files still checked out. ║ ║ Also, you need to make sure that the user does║ ║ not have any files currently checked out ║ ║ before he is deleted. Make sure that you ║ ║ carefully review all of the displayed ║ ║ information to ensure that the correct user ║ ║ is being deleted. ║ ╚═════════════════════════════════════════════════════╝ Once you have entered a unique set of initials, you must then verify that you have indeed entered the correct user before they will be deleted. Press the <Y> key if you are absolutely sure you want to delete the user from the system. The user will be deleted from the user name file and you will return to the System Maintenance Menu screen. ───────────────────────────────────────────────────────────────── 43 LARC User's Guide Chapter 6 - User Maintenance ═════════════════════════════════════════════════════════════════ Show All Users ══════════════ The Show All Users function displays a list of all of the available users. Print All Users ═══════════════ The Print All Users function prints a list of all of the available users. ───────────────────────────────────────────────────────────────── 44 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 7 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ██████ ║ LARC Configuring File ║ ██ ║ ║ ██ ║ This chapter explains how to set up and maintain ║ ██ ║ the LARC system configuration file for single ║ ██ ║ or multiple users. It also describes the LARC ║ ║ startup parameters and provides some tips on ╚══════════════╝ how best to start LARC for your users. The LARC Configuration File ═══════════════════════════ When started, LARC is passed the name of a configuration file. This configuration file tells LARC several things about the system on which LARC is running. The configuration file tells LARC: o the location of LARC programs and data files o the type of access security to be used o LARC system screen colors o the characteristics of the printer that you will be using with LARC o the drive letters of the floppy diskettes configured on your system Each line in the file contains a SET command. These SET commands are described in the following sections. SET SYSTEM NAME "system-name" ───────────────────────────── This command tells LARC where to find the LARC executable programs and command files. "system-name" can contain any sequence of 50 characters. SET SYSTEM EXECUTABLES d:\path ────────────────────────────── This command tells LARC where to find the LARC executable programs and command files. "d:\path" can contain any valid drive letter and path designator. SET SYSTEM DATAFILES d:\path ──────────────────────────── This command tells LARC where to find the LARC data files. "d:\path" can contain any valid drive letter and path designator. ───────────────────────────────────────────────────────────────── 45 LARC User's Guide Chapter 7 - LARC Configuring File ═════════════════════════════════════════════════════════════════ ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should never change the two previous SET ║ ║ commands unless you also move all of the files║ ║ from the old directories to the new ║ ║ directories. Changing these two SET commands ║ ║ could result in LARC no longer running ║ ║ properly. ║ ╚═════════════════════════════════════════════════════╝ SET SYSTEM TIMEOUT nnnn ─────────────────────── This command defines the amount of time to wait for a keyboard key to be pressed before timing out and returning to the previous screen or menu. Nearly every place where LARC is waiting for keyboard input, it is also watching to see how much time has elapsed since the last time a key was pressed. If the wait period specified by this command is reached, LARC will cancel the current keyboard input request and backup to the previous screen or menu. The timeout feature reduces the risk of someone logging onto LARC, then leaving before signing off which could allow some unknown person access to LARC. The timeout interval nnn is specified in seconds. For example, 0120 would specify that the keyboard wait interval is 120 seconds, or two minutes. A value of 0000 disables the timeout feature. ╔═════════════════════════════════════════════════════╗ ║ NOTE: If you are using the OS/2 version of LARC and ║ ║ want to leave LARC running in an OS/2 window, ║ ║ you should set the time out interval to 0000. ║ ║ Otherwise, LARC would timeout and exit which ║ ║ would cause you window to be closed. ║ ╚═════════════════════════════════════════════════════╝ SET SYSTEM LOGON n ────────────────── This command defines the system security method to be used. "n" must be set to one of the following numbers: 1 Logon once only when LARC is started. No logoff to exit to the operating system. Access to the various LARC functions are controlled via the security setting assigned to each user by the LARC System Administrator. 2 Logon each time a library is selected. Logoff to exit to the operating system. Access to the various LARC functions are controlled via the security setting assigned to each user by the LARC System administrator. Only users with the appropriate access level will be allowed to exit LARC and return to the operating system. ───────────────────────────────────────────────────────────────── 46 LARC User's Guide Chapter 7 - LARC Configuring File ═════════════════════════════════════════════════════════════════ SET DISPLAY xxxx ──────────────── This command tells LARC what type of screen I/O to perform. "xxxx" can be set to one of the following values: DOS Perform DOS level screen I/O. This mode is the slowest mode, but is the most compatible with non-standard machines. BIOS Perform BIOS level screen I/O. This mode is slightly faster than DOS mode, and can be used on any system that is 100% compatible with standard AT BIOS. MAPPED Perform direct video memory mapped screen I/O (default). This is the fastest mode and can be used with any machine that is 100% compatible with the original AT specification. It is recommended that you use MAPPED mode unless you encounter a display problem. SET SYSTEM PATHTOUSE n ────────────────────── This command controls the process of prompting you for a destination or source path. "n" must be set to one of the following numbers: 0 Display the path name prompt and use the path name if one is entered. If no path is entered, use the path in the user's password file. If both are blank, use the default path. 1 Do not prompt for a path name. Instead, always use the path in the user's password file. If the user's password path is blank, use the default path. 2 Do not prompt for a path name and ignore the path in the user's password file. Always use the default path. SET COLOR which foreground ON background ──────────────────────────────────────── This command defines the screen colors used by LARC for the various areas or types of information displayed by LARC. "which" defines the screen area being displayed and must be set to one of the following: NORMAL Normal screen text HEADER Screen header HEADER2 Display column heading BARMENU Menu bar LASTLINE Screen footer ACTIONS Menu box selection bar WARNING Warning messages ───────────────────────────────────────────────────────────────── 47 LARC User's Guide Chapter 7 - LARC Configuring File ═════════════════════════════════════════════════════════════════ ABORT Abort messages INFORMATION Information boxes EDITS Edit boxes HOTKEY Menu hot keys DATAENTRY Data entry boxes ACTIVE End of edit SELECTION Selection scroll bar REVISED Updated (revised) files SHADOW Box shadow CHECKEDOUT Checked out files FILEIOBAR File I/O activity bar TAGGED Tagged files FULLRELEASE Full release information PRINTBOX Printing... information box Recognized foreground colors names are: BLACK RED GREEN BROWN BLUE MAGENTA CYAN WHITE GRAY HI-RED HI-GREEN YELLOW HI-BLUE HI-MAGENTA HI-CYAN HI-WHITE Recognized background colors names are: BLACK RED GREEN BROWN BLUE MAGENTA CYAN WHITE SET PRINTER ACTIVE YES|NO ───────────────────────── This command defines whether or not you have a printer attached to LARC. It is highly recommended that you attach a printer to your system since LARC provides several valuable reports. You must be set this command to either "YES" or "NO". SET PRINTER LINESPAGE nn ──────────────────────── This command defines the number of text lines per page for your reports. The number of lines per page only counts the body lines. The header lines are not included in the count. "nn" can be any value from 01 to 99. SET PRINTER INITIALIZE string SET PRINTER CONDENSE string SET PRINTER NORMAL string SET PRINTER DONE string ───────────────────────────── These commands define the printer initialization, condense mode, normal print mode and termination command strings that will be sent to the printer prior to and after a report is printed. These strings allow you to "customize" LARC for your specific printer. "string" can be any sequence of characters, from 1 to 50 characters, which is recognized by your printer for performing the desired function. ───────────────────────────────────────────────────────────────── 48 LARC User's Guide Chapter 7 - LARC Configuring File ═════════════════════════════════════════════════════════════════ SET FLOPPY 360KB d SET FLOPPY 1.2MB d SET FLOPPY 720KB d SET FLOPPY 1.44MB d ─────────────────── These commands define the drive letters for the floppy diskettes you have available on your system. LARC uses this information when creating release diskettes to ensure that correctly formatted diskettes are used when you create your releases. "d" can be any valid floppy drive letter, such as A or B. Starting LARC ═════════════ To start LARC, you enter the command: d:\path\LARC3.EXE d:\cfg-path\filename.cfg "d:\path" is the drive and path name of the LARC3.EXE program. "d:\cfg-path\filename.cfg" is the name of the LARC configuration file to use. The configuration file tells LARC not only were the LARC program and data files live, it also provides other information to LARC such as what screen colors and printer initialization commands to use. This allows each user to customize LARC to suite their own personal taste. It also would allow you to customize various configuration of LARC so that you can easily determine which set of libraries you were working with. For example, lets assume that you are developing two distinct software products. You could create a PROD1.CFG and a PROD2.CFG. Each configuration file could point to two different sets of LARC data files, yet both point to the same set of LARC executable. These two sets of LARC data files could also define a specific set of developers that could access each product's libraries. You may also decide to change the screen colors of the second LARC so that you can easily tell which system you selected by the color of the screen. The real flexibility of the configuration files is with individual users who are running LARC from a network drive. Each user provides there own customized configuration file that tells LARC where to find the program and data files on the network, and provides LARC with information on the users printer and diskette configuration. LARC is delivered with a command file named LARC.BAT for DOS versions and LARC.CMD for OS/2 versions. This file is configured to start LARC3.EXE from the default LARC installation directory C:\LARC. You may need to modify this command file in order to start LARC from some other drive or directory. And if you use more than one configuration of LARC, you may need to create a ───────────────────────────────────────────────────────────────── 49 LARC User's Guide Chapter 7 - LARC Configuring File ═════════════════════════════════════════════════════════════════ startup command file for each configuration (e.g. LARC1.BAT, LARC1.CMD, etc.). Assuming you installed LARC in the default installation directory and assuming you want to use the default configuration file, simply enter the command: LARC This command assumes that you have the LARC.BAT file in a directory that is included in your path statement. If not, then you will need to enter the command: C:\LARCDIR\LARC Starting LARC From Microsoft Windows ════════════════════════════════════ LARC can be started from Microsoft Windows by simply creating a Windows Program Information File (PIF). LARC does not require any special resources so a standard PIF should work fine. LARC does not provide a special Windows icon, so you are free to use any one of Window's standard icons. We like using the Windows supplied icon that depicts a safe since LARC provides a "safe" environment for controlling your files. When you create your LARC PIF, make sure that you specify the complete LARC command, including the drive and path for the LARC configuration file. ╔═════════════════════════════════════════════════════╗ ║ NOTE: We have observed a peculiar behaviour with the║ ║ Microsoft Windows windowed DOS box. Under ║ ║ certain undefined conditions, Windows fails to║ ║ properly establish the windowed DOS box ║ ║ default path. We have also observed that ║ ║ under these conditions, the heading for the ║ ║ windowed DOS box contains unexpected text. ║ ║ We urge caution when using the windowed DOS ║ ║ box until after a problem has been better ║ ║ defined and, hopefully, resolved by Microsoft.║ ╚═════════════════════════════════════════════════════╝ Network Environments ════════════════════ Users in a network environment can install and execute LARC on a network drive. However, you are subject to a network license agreement and must install the proper version of LARC before multiple users will be able to access LARC. Once you have installed a proper version of LARC on the network, setup and maintenance of LARC is the same as for the single user configuration. ───────────────────────────────────────────────────────────────── 50 LARC User's Guide Chapter 7 - LARC Configuring File ═════════════════════════════════════════════════════════════════ LARC controls access to the various libraries it is managing to ensure that two or more users are not allowed to check out the same file at the same time. The second user will be presented a message indicating that the someone else is currently in the library and asks him to try again in a few minutes. Chapter 1 has more information concerning use of LARC in a networked environment. ───────────────────────────────────────────────────────────────── 51 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 8 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ▄████▄ ║ Command Files ║ ██ ██ ║ ║ ████ ║ This chapter explains how to configure the ║ ██ ██ ║ system command files that LARC uses to produce ║ ▀████▀ ║ releases, create back up sets, and generate ║ ║ release diskettes. ╚══════════════╝ Command File Descriptions ═════════════════════════ In addition to the source files contained in a library, LARC recognizes several file names that have very specific purposes. These special files are used to build product releases, create release diskettes, produce intermediate backups and produce final off-site archives of final releases. The DOS version of LARC uses the *.BAT files while the OS/2 version of LARC uses thE *.CMD files. The library specific command files are: LARCBLDn.BAT/CMD: These files contain the system commands required to build your product release. BUILDFIN.CTL: This file is created by the LARC build command files to let LARC know if the build completed successfully. LARCARC.BAT/CMD: This file contains the system commands required to produce a complete archive of all sources and built releases for a product. This file is automatically executed whenever you create a final or full release of your product. LARCRELn.CUT: This file contains parameters that LARC uses to know what files to copy to your release diskettes whenever you create your release diskette. LARCBUP.BAT/CMD: These files contain the system commands required to produce a backup of each specific library that LARC is maintaining. LARCSERL.BAT/CMD: These files contain the system commands required to add serial number information to your release diskettes. DISKnn.CTL: These files are optionally created on your release diskettes for use with an intelligent installation program. ───────────────────────────────────────────────────────────────── 52 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ The system-wide command files are: LARCBACK.BAT/CMD: These files contain the system commands required to produce a complete backup of all of your LARC executable, data and library files. LARCFORM.BAT/CMD: These files contain the system commands required to produce a complete backup of all of your LARC executable, data and library files. How Do the Command Files Work Together? ═══════════════════════════════════════ When you ask LARC to build a release, several steps are taken: 1. You select the library that you wish to build. 2. You select the release number for that library. 3. LARC changes to the release directory associated with the release number you selected and deletes any previously existing files from the release directory. In this way, you are assured that you are always starting with a clean directory. This is the preferred method since it guarantees that all components will be compiled and linked each time a build is produced. 4. LARC executes the selected command file LARCBLDn.BAT for DOS or LARCBLDn.CMD for OS/2. 5. When the LARC build command finishes and returns to LARC, LARC looks for the file BUILDFIN.CTL in the release directory. If the file is present in the release directory, this tells LARC that the build completed successfully. LARC will store the release identifier you selected for the release in the Release Control file. 6. If the BUILDFIN.CTL file is not found in the release directory, LARC assumes that the build failed and does not record the release identifier. This allows you to correct the problem(s) and restart the build process and use the same release identifier. 7. If you selected a full release build in response to the build number prompt, and if the build completed, then LARC will execute the archive file (LARCARC.BAT for DOS or LARCARC.CMD for OS/2) to produce an archive of the product release. As you may have noticed, the LARC build command files are very important to the process of building your release. You create and maintain the LARC build files by adding the commands required ───────────────────────────────────────────────────────────────── 53 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ to build your product. LARC will faithfully ensure that your commands are executed in the same sequence every time you build your product. LARCBLDn.BAT or LARCBLDn.CMD ════════════════════════════ Each release directory has a command file named LARCBLDn.BAT for DOS and LARCBLDn.CMD for OS/2. The "n" portion of the name is a number from one to five that associates the file with the release directory. These files are known as LARC build files and they contain the commands necessary to build a product. When you select the release build option from the Release pull down menu and select a release number, LARC will execute the build command file associated with the release number you selected. The LARC build command file is simply a command file in which you place the system commands necessary to build your product. Using a command file in this way allows LARC to provide you complete control in selecting the tools and techniques you require to build your release. The LARC build command file is by far the most important file in the system since it defines how your product will be built. When LARC executes a build file, it passes the following parameters to the file: %1 The release identifier that you enter when you started the build. %2 The release number or "F" if you selected to build the final release. %3 The library's hard drive letter and colon (e.g., C:) %4 The library's source directory name (e.g., C:\EXAMPLE\SOURCES). %5 The library's release directory name (e.g., C:\EXAMPLE\RELEASE). %6 The current system date, formatted as mm-dd-yy. %7 The current system time, formatted as hh:mm:ss. %8 The source library number. This number can be used with several LARC utilities that may be executed from your LARC build command files. Further information can be found in Chapter 16. ───────────────────────────────────────────────────────────────── 54 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ %9 This parameter contains the same release identifier that was passed in argument %1. However, here the identifier has several special characters removed. These characters are "V" (only if it is the first character), "." or "_". For example, if you entered "V1.00" as your release identifier, this parameter would contain "100". This parameter allows you to use the release identifier as part of file names that you may need to create when building your product release. The LARC build command files can be as simple as a file that contains a single NMAKE command, or as complex as containing path set statements, copy commands, "IF EXISTS" statements, individual compile and link commands, and any other system level commands required to build your release. The only requirement that LARC places on LARC build command files is that they must create a BUILDFIN.CTL file when they have finished. This tells LARC that the build completed successfully. We will discuss the BUILDFIN.CTL file in greater detail in a moment. First we need to see some example LARC build command files. Here is a simple LARC build command file for DOS. The OS/2 version of the file will look very similar and often may be identical to the DOS example provided here: @ECHO OFF REM REM LARC-L "Example Library" REM LARC-D "Release 1 Build File" REM LARC-V "100" REM COPY %4\*.* *.* >NUL NMAKE -S -FEXAMPLE.MAK >>MAKE.OUT IF NOT EXIST %4\EXAMPLE.EXE GOTO ERR01 ECHO %6%7%2%1 >BUILDFIN.CTL GOTO DONE :ERR01 ECHO.>>MAKE.OUT ECHO>>MAKE.OUT Error: EXAMPLE.EXE did not build! :DONE PRINT MAKE.OUT Here is a description of the example LARC build file: @ECHO OFF REM REM LARC-L "Example Library" REM LARC-D "Release 1 Build File" REM LARC-V "100" REM ───────────────────────────────────────────────────────────────── 55 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ The LARC build files are checked into your source library and are controlled by LARC just like all of your other source files. So, they must have proper release control information. COPY %4\*.* *.* >NUL Remember that LARC clears the release directory for you, and sets your active path to the release directory. The example command file is issuing the copy command to copy the example source files from the source library into the release directory. The %4 parameter is used to help keep the command file "generic" in case the library is moved or the file is used as a base for a future file. The copy command may not be necessary if the EXAMPLE.MAK file could be made to find the source files in the source directory. However, since you are likely to want to use the same make file for developing and final release building, using the copy command may be the easiest thing to do. NMAKE -S -FEXAMPLE.MAK >>MAKE.OUT This line shows how you might use the Microsoft C NMAKE utility to perform the build. EXAMPLE.MAK is checked into your library just like any other source file and it will be copied into the release directory by the previous copy command. Notice that we have used the system pipe facility ">>MAKE.OUT" to route the screen output into the file MAKE.OUT that will be created in the release directory. Though not required, it is highly recommended that you take advantage of this type of activity recording otherwise some problem may scroll past you on the screen and be missed. Piping your tool output to a file will help you debug any problems you encounter with your build files. IF NOT EXIST 3%4\EXAMPLE.EXE GOTO ERR01 After NMAKE has completed, a simple "IF EXISTS" command is issued to verify that the EXAMPLE.EXE program was properly created by the NMAKE step. If not found, then a message is displayed and BUILDFIN.CTL will not be created. ECHO %6%7%2%1 >BUILDFIN.CTL GOTO DONE If the EXAMPLE.EXE program was found, then the date, time, release type and release identifier is piped into the BUILDFIN.CTL file as required by LARC. Creating this file tells LARC that the build completed successfully. Piping the date, time, release type and release identifier into the file allows LARC to later identify the release. As you will see in a later example, you want to be as specific as possible when trying to determine whether the build completed successfully. Where possible, you would want to check the ERRORLEVEL returned by your tools (compilers, linkers, etc.) to verify the status of the build. ───────────────────────────────────────────────────────────────── 56 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ :ERR01 ECHO.>>MAKE.OUT ECHO>>MAKE.OUT Error: EXAMPLE.EXE did not build! The ERR01 section places the error message in the MAKE.OUT file. This allows you to see where the build failed. :DONE PRINT MAKE.OUT The DONE section prints the piped build results file MAKE.OUT and then exits. When the LARC build command file exits, LARC will display a "press any key to continue" message and check for BUILDFIN.CTL. As mentioned above, if BUILDFIN.CTL does not exist, LARC assumes that the build did not complete successfully. This allows you to have complete control over what is a successful build and what is a bad build. Since the LARC build files are standard system batch command files, you can take advantage of the features provided by your operating system to improve the maintenance of your build procedure. For example, you can use a combination of the ECHO command and file output piping to display and record build progress information as shown below. ECHO Compiling %4\MAKEBOOT.SRC ECHO>>MAKE.OUT Compiling %4\MAKEBOOT.SRC IF NOT EXIST %4\MAKEBOOT.SRC GOTO ERR01 REALCOB/Q %4\MAKEBOOT.SRC,,NUL; >>MAKE.OUT IF ERRORLEVEL 1 GOTO ERR09 Another advantage offered by using standard system command files is the ability to create files using the information that is passed into the LARC build file. For example, you can create an include file that uses the release identifier and build type so that this information can be included, at build time, in the programs that are being built. REM -------------------------------------------------- REM Creating the release ID include modules REM -------------------------------------------------- ECHO>RELEASE.H // ECHO>>RELEASE.H // Example Release Include File ECHO>>RELEASE.H // ECHO>>RELEASE.H #define LARC_R %1 ECHO>>RELEASE.H #define LARC_T %2 One other interesting feature provided when using batch command files is the ability to set the system environment specifically for your tools. For example, issuing the following commands for the DOS version will set the PATH so that the tools are properly located for compiler COMP-A: ───────────────────────────────────────────────────────────────── 57 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ SET PATH= SET PATH=C:\;C:\DOS;C:\COMP-A; This PATH will only be in effect while LARC build is executing and once the build exits the original PATH is restored. This method allows you to define paths (and any other system environment parameter using the SET command) that only are in effect during your build process. You can also reset the PATH or SET commands within the same LARC build file. Doing so allows you to use two or more compilers while in the same build process. Of course you are also free to use any other tools that can be executed from a system command file. Examples are your compilers and linkers, special procedures that build initial copies of your product data files, enhanced command processing shells, file compression utilities, and any number of other system utility programs. As flexible as system command files are, using them is not without some limitations or warnings. There are several issues you need to consider when setting up your LARC build files: 1. LARC only knows if the build was successful if you create the BUILDFIN.CTL file. If your tools return status codes (such as is provided by DOS using the ERRORLEVEL mechanism), you should check the codes for any problems the tool may have encountered. If the tool returns an error, then you should make sure that the BUILDFIN.CTL file is not created so that LARC will allow you to correct the problem and rebuild the release. 2. Some older tools do not set return status codes. With these tools you have to resort to checking for the existence of object modules or executable files. 3. The standard DOS or OS/2 system command shells can create simple output files, but complex file processing is not possible. There are several after market products available which enhance the standard shells (such as REXX for OS/2) and you may take advantage of these tools to enhance your build procedures. While LARC does not stop you from using these products, they may have memory requirements that exceed the amount available when LARC is running. We recommend that you carefully test these tools with LARC before using them with your actual live files. 4. When you create a new library, you will likely start with a LARC build file from an existing library when creating the LARC build file for the new one. You should make sure that you specify the correct path names and commands when you use any existing LARC build file as your base. ───────────────────────────────────────────────────────────────── 58 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ 5. Because the LARC build files are standard system command files, you can issue any valid system command or start any system program. There are some potentially dangerous commands and utility programs that, if used incorrectly, could result in a loss of data. LARC marks all library files with the read-only attribute, but some utility programs ignore this attribute when deleting files. Carefully review your build files to ensure that you do not use any command or utility program in a way that could result in the accidental loss of your files. Also, you should back up your files frequently to reduce your risk. BUILDFIN.CTL ════════════ The Build Finished control file, as stated previously, tells LARC that the build file completed with no failures. This file is a simple ASCII file that contains one line of the following format: ddddddttttttxvvvvvvvv Each field is defined: dddddd The current system date. tttttt The current system time. x The build type. vvvvvvvvvvv The release build identifier. You typically create this file by including the following line in each of your LARC build files and using the parameters passing into the file by LARC: ECHO %6%7%2%1 >BUILDFIN.CTL By not creating this file, you tell LARC that the build did not complete. LARC will not continue with the next step in the build process unless this file is created when the build file exits. LARCARC.BAT or LARCARC.CMD ══════════════════════════ The archive file is executed whenever a final product release build is produced. This file is used to create the archive backup that you will store in a safe place. It is highly recommended that these archives be stored off site in a fire safe vault. You may already have such an off site storage location, especially if you are contractually obligated to produce escrow accounts of your software for your customers. If not, this is definitely the time to look into this issue further. Never put disaster recovery off till tomorrow! ───────────────────────────────────────────────────────────────── 59 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ The LARC archive file is started with parameters similar to those passed to the LARC build command files. The parameters are: %1 The release identifier that you enter when you requested the build. %2 Always a "F" because this command file is only executed when you build the final release. %3 The library's hard drive letter and colon (e.g., C:) %4 The library's source directory name (e.g., C:\EXAMPLE\SOURCES). %5 Always "FULL RELEASE". %6 The current system date, formatted as mm-dd-yy. %7 The current system time, formatted as hh:mm:ss. %8 The source library number. This number can be used to back up the LARC system files associated with the library. %9 This parameter contains the same release identifier that is passed in argument %1. However, here the identifier has several special characters removed. These characters are "V" (only if it is the first character), "." or "_". For example, if your entered "V1.00" as your release identifier, this parameter would contain "100". This parameter allows you to use the release identifier when creating your archive files. If possible, you should include statements in your archive file to verify that the archive was successfully created. However, since there is no guarantee that your archive system can provide good status feedback, LARC will ask you to verify that the backup was successfully created. If you answer no, then LARC will treat the entire build as if it failed. Otherwise, LARC considers the entire build a success and adds the release identifier to the control file. LARCRELn.CUT Parameter Files ════════════════════════════ Each release directory has a file named LARCRELn.CUT, where "n" is a number from one to five that associates the file with the release directory. These files are known as release cut (or simply cut) files and they contain the commands that LARC will use when creating release diskettes from the built product release directories. ───────────────────────────────────────────────────────────────── 60 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ These cut parameter files are used to tell LARC how to create a set of release diskettes from your built product release directories. When you select a release creation options from the menu and choose a release number, LARC will execute the appropriate cut parameter file. The CUT parameter file is an ASCII text file that you create and maintain. The file contains text lines that tell LARC what to do when creating your release diskettes. If you want to use the LARC Installation Program to install your product, these commands are written in the installation control files to tell the installation program how to install your software. Refer to the following information and Chapter 16 for more information on the relationship between CUT file formats and the LARC Installation Program. Using a parameter file in this way allows LARC to provide a high degree of flexibility when creating product release diskettes. The CUT files are very important and must be carefully managed to ensure that the correct files are copied onto your release diskettes. LARC recognizes and uses several CUT parameter commands when it creates the release diskettes. These are defined in the following sections. Comments ──────── Comments are allowed in the LARCREL files but they are not written into the diskette control files. Any line that begins with ";" or "REM" is considered to be a comment line. Installation Defaults Command ───────────────────────────── The Installation Defaults Command is used to provide a way for you to set the default values for the LARC Installation Program. The command line has the following format: byte 1: Always "!". byte 2: Always " ". byte 3: The default source floppy diskette drive letter. This field should contain either an "A" or "B". byte 4: The default destination hard drive letter. This field can contain any valid hard drive letter. ───────────────────────────────────────────────────────────────── 61 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ byte 5-36: The default destination directory name. This field should start with the "\" character. An example could be "\MYPROD". The LARC Installation Program does not create complex directories, so you should not specify "\LEV1\LEV2" unless your are quite sure that the "\LEV1" directory exists on your target systems. System Name Command ─────────────────── The System Name Command is used to provide the name of your system to the LARC Installation Program. The LARC Installation Program will display this system name on the screen when your product is installed. The command line has the following format: byte 1: Always "S". byte 2: Always " ". byte 3-52: Defines the name of your system. An example could be "My Special Product". File Copy Command ───────────────── File Copy Commands are used to define files that are to be copied to the release diskettes. The command line has the following format: byte 1: Control byte: " " Copy the file specified in bytes 2-13 to the release diskette. The installation program will always copy the file from the diskette to the destination directory. "-" Copy the file specified in bytes 2-13 to the release disk. The installation program will not copy the file from the diskette. "*" Copy the file specified in bytes 2-13 to the release disk. The installation program will only copy the file from the diskette if the file does not already exist in the destination directory. "+" Advance to the next release disk. All other fields are ignored. bytes 2-13: Contains the name of the file to be copied to the release diskette in the standard DOS "filename.ext" format. ───────────────────────────────────────────────────────────────── 62 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ byte 14: Blank. bytes 15-17: This field contains the three digit library number that LARC assigned to the library when it was created. This number is used as a shorthand way of specifying the location of the file you want to copy to the diskette. byte 18: Blank. bytes 19: For copying files to the release disks, this field is used with the number from bytes 15-17 to locate the file you want to copy to the release diskette. Values in this field may be: "S" Find the file in the source library. "1" - "9" Find the file in a release directory associated with the library. The file must have been copied into, or created in the release directory by a LARC build file. byte 20: Blank. bytes 21-23: This field contains the three digit library number that LARC assigned to the library when it was created. This number is used as a shorthand way of specifying the location of a library source file. LARC will use the number to extract version and description information for the file being copied to the release diskette. This information is written into the release report that LARC produces when you create your release diskettes. This field may be left blank if no version or name is required or available. If left blank (usually due to no source file being available, such as for build-created ZIP files), bytes 38-87 can be used to "hard code" a release file description. byte 24: Blank. bytes 25-36: This field contains the name of the source file to look up for the release file's version and name information. The version and description information will be included on the release creation report produced by LARC. byte 37: Blank. ───────────────────────────────────────────────────────────────── 63 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ bytes 38-87: This field contains a one to fifty character text string that you may use to describe the file being copied to the release diskette if you are not able to automatically extract this information from a file located in a LARC library. Change Directory Command ──────────────────────── The Change Directory Command is used to tell the LARC Installation Program to change to a different default directory. By default, the LARC Installation Program uses the drive and directory that you provide the program. Since you are likely to need to always install certain files into specific directories, this command provides a way for you to tell the LARC Installation Program to change to directories. Use the "Make Directory Command" to create directories. The command line has the following format: byte 1: Always "C". byte 2: Always " ". byte 3-79: Specifies the name of the directory as "d:\path-name". See the section "Directory Substitution Characters" below. File Delete Command ─────────────────── File Delete Commands are used to tell the LARC Installation Program to delete a file from the installation target system. The command line has the following format: byte 1: Always "D". byte 2: Always " ". byte 3-79: Specifies the name of the file to be deleted. Execute Command ─────────────── The Execute Command is used to have the LARC Installation Program execute a system command or start another program. This allows you to install and execute conversion programs from the LARC Installation Program, and have them automatically executed when your software is installed. The command line has the following format: byte 1: Always "E". byte 2: Always " ". byte 3-79: Specifies the name of the command or program to be executed. ───────────────────────────────────────────────────────────────── 64 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ Make Directory Command ────────────────────── The Make Directory Command is used to tell the LARC Installation Program to create a directory on the destination system. Since you may need to install certain files into specific directories, this command provides a way for you to tell the LARC Installation Program to make the directories for you. Once the directory has been created, use the "Change Directory Command" to set the directory as the default directory. The command line has the following format: byte 1: Always "M". byte 2: Always " ". byte 3-79: Specifies the name of the directory as "d:\path-name". See the section "Directory Substitution Characters" below. Remove Directory Command ──────────────────────── The Remove Directory command is used to tell the LARC Installation Program to delete a directory. The directory will only be deleted if all of the files have been deleted from the directory. The command line has the following format: byte 1: Always "R". byte 2: Always " ". byte 3-79: Specifies the name of the directory as "d:\path-name". See the section "Directory Substitution Characters" below. Unzip Command ───────────── The Unzip Command is used to tell the LARC Installation Program to issue a PKUNZIP command to cause a compressed file to be unzipped. The command line has the following format: byte 1: Always "U". byte 2: Display control byte: " " Clear the screen and display run PKUNZIP so that it displays it's progress on the screen. "-" Run PKZIP so that it does not display it's output to the screen. byte 3-79: Specifies the name of the file to be unzipped. ───────────────────────────────────────────────────────────────── 65 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ Verify File Command ─────────────────── The Verify File Command is used to tell the LARC Installation Program to make sure that the specified file actually exists on the destination system. The command line has the following format: byte 1: Always "V". byte 2: Always " ". byte 3-79: Specifies the name of the file to be verified. Directory Subsitution Characters ════════════════════════════════ Usually, the directory path names will contain directory names such as "C:\LARC\TEMP". The LARC Installation Program allows you to code these records so that the installation destination information you enter can be used. You can use "?:?\TEMP" as the directory name. The program will replace the first "?" character with the destination hard drive letter you entered. The second "?" character will be replaced by the directory name that you entered. Parameterizing the directory names this way provides flexibility. You do not have to hard code directory creation or force the product to install into a specific set of directories. Example CUT File ════════════════ Here is an example CUT parameter file. The example shown is actually the CUT file used when LARC creates release diskettes of itself! ; ; LARC-S "Library Administration and Release Control" ; LARC-D "Release 1 (DOS) Cut Definition File" ; LARC-V "330" ; ; Define the prompt defaults and the name of the system being installed. ; ! AC\LARC3 S Library Administration and Release Control ; ; Free up as much space as possible before beginning to ; copy and expand the new release files. ; D CFREAD.DLL D ERRLOG.DLL D GETLARC.EXE D INSTALL.EXE D KCOPY.EXE ───────────────────────────────────────────────────────────────── 66 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ D KDEL.EXE D KDIR.EXE D KFREE.EXE D KVERENV.EXE D LARC3.EXE D LARCLIB.DLL D LDIR.EXE D MAINT.DLL D MESSAGES.LRC D OVL1.DLL D OVL2.DLL D OVL3.DLL D OVL4.DLL D OVL5.DLL D OVL6.DLL ; ; Copy the files... ; INSTALL.EXE 002 1 002 INSTALL.SRC *LARC.BAT 002 1 002 LARC.BAT *LARC.CFG 002 1 002 LARC.CFG *LARC.PIF 002 1 002 LARC.PIF *MESSAGES.LRC 002 1 002 MESSAGES.ASC *LARCFORM.BAT 002 1 002 LARCFORM.BAT *LARCBACK.BAT 002 1 002 LARCBACK.BAT CFREAD.DLL 002 1 002 CFREAD.SRC ERRLOG.DLL 002 1 002 ERRLOG.SRC GETLARC.EXE 002 1 002 GETLARC.SRC KCOPY.EXE 002 1 002 KCOPY.SRC KDEL.EXE 002 1 002 KDEL.SRC KDIR.EXE 002 1 002 KDIR.SRC KFREE.EXE 002 1 002 KFREE.SRC KVERENV.EXE 002 1 002 KVERENV.SRC LARC3.EXE 002 1 002 LARC.SRC LARCLIB.DLL 002 1 Realia Runtime Library Routines LDIR.EXE 002 1 002 LDIR.SRC MAINT.DLL 002 1 002 MAINT.SRC OVL1.DLL 002 1 002 OVL1.SRC OVL2.DLL 002 1 002 OVL2.SRC OVL3.DLL 002 1 002 OVL3.SRC OVL4.DLL 002 1 002 OVL4.SRC OVL5.DLL 002 1 002 OVL5.SRC OVL6.DLL 002 1 002 OVL6.SRC ; ; These files are not copied from the diskette ; -READ.ME 002 1 002 READ.ME -EXAMPLES.ZIP 002 1 Example Build Files -RELEDIT.EXE 002 1 002 RELEDIT.SRC ; ; Perform some post-installation clean-up and verification. ; V CFREAD.DLL ───────────────────────────────────────────────────────────────── 67 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ V ERRLOG.DLL V GETLARC.EXE V INSTALL.EXE V KCOPY.EXE V KDEL.EXE V KDIR.EXE V KFREE.EXE V KVERENV.EXE V LARC.BAT V LARC.CFG V LARC3.EXE V LARCBACK.BAT V LARCFORM.BAT V LARCLIB.DLL V LDIR.EXE V MAINT.DLL V MESSAGES.LRC V OVL1.DLL V OVL2.DLL V OVL3.DLL V OVL4.DLL V OVL5.DLL V OVL6.DLL The LARC Installation Program would interpret the commands shown as follows: "!" Establish the defaults for the program prompts. "S" Display the system name on all screens. "D" Delete the file from the installation directory. " " Copy the file from the diskette to the installation directory, overwriting any previously existing file. "*" Only copy the file from the installation diskette if a file by the same name does not already exist in the directory where LARC is being installed. "V" Verify that the file exists in the installation directory. Assuming you want to use the LARC Installation Program to install your product, you can use LARC to consistently create installation script files that automate your product installation. However, LARC will also allow you to create diskettes without these installation control files. You can, of course, use any third party installation program by simply checking in their script files just as you would any other source file. ───────────────────────────────────────────────────────────────── 68 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ LARCBUP.BAT or LARCBUP.CMD ═════════════════════════════════════════════════════════════════ These LARC backup files are provided to allow you to get a quick backup of a single library. You may want to create "snapshot" backups of a library during periods of heavy development. Use these command files to provide this feature to your team members without requiring them to exit to the operating system and issuing the commands manually. These commands allow you to maintain consistent backups across all of your libraries. As with the build and full archive files, LARC passes several parameters to the backup command files: %1 The library's hard drive letter and colon (e.g., C:) %2 The library's source directory name (e.g., C:\EXAMPLE\SOURCES). %3 The current system date, formatted as mm-dd-yy. %4 The current system time, formatted as hh:mm:ss. %5 The source library number. This number can be used to backup the LARC system files associated with the library. DISKnn.CTL ══════════ If you configure your library to create installation files on your release diskettes, LARC will copy the lines from your CUT files to release control file on your release diskettes. These release control files are named DISKnn.CTL. The "nn" portion of the file name corresponds to the release diskette sequence number. Refer to the earlier section "LARCRELn.CUT Parameter File" and to Chapter 16 for more information on the use and format of the release control files. LARCBACK.BAT or LARCBACK.CMD ═════════════════════════════════════════════════════════════════ The system backup command file is a simple system command file that you create and maintain. This file is placed in the LARC executable directory and it contains the commands that work with your backup system. Since there are more ways to backup a system then we can count (floppy, tape, DAT, CD-ROM, WORM, network, etc.), this command file provides an interface to LARC and allows you create full LARC system backups from the LARC main menu. LARC does not pass any parameters to this command file. LARC assumes that you will use this command file to backup the entire system so no parameters from LARC's configuration will be required. ───────────────────────────────────────────────────────────────── 69 LARC User's Guide Chapter 8 - Command Files ═════════════════════════════════════════════════════════════════ LARCFORM.BAT or LARCFORM.CMD ═════════════════════════════════════════════════════════════════ The backup media format command file is a simple system command file that you create and maintain. This file is placed in the LARC executable directory and it contains the commands necessary to format the media that works with your backup system. This command file provides an interface to LARC and allows you to format your backup media from the LARC main menu. LARC does not pass any parameters to the format command file. LARC assumes that you will use this command file only to format the backup media so no parameters from LARC's configuration will be required. LARCSERL.BAT or LARCSERL.CMD ═════════════════════════════════════════════════════════════════ The release serialization command file is a simple system command file that you create and maintain. This file is checked into the library and it contains the commands necessary to add serial number, or any other post-release cut information, to your release diskettes. This command file is executed whenever you select the "execute serialization command" option from the "release" menu. No arguments are passed to this command file. ───────────────────────────────────────────────────────────────── 70 ╔══════════════╗ ║ ║ ║ ╔════════════╩════════════════════════════════════════════════╗ ║ ║ Chapter 9 ║ ║ ╚════════════╦════════════════════════════════════════════════╝ ║ ║ ║ ▄████▄ ║ The Menus ║ ██ ██ ║ ║ ▀█████ ║ This chapter explains how to select a library ║ ██ ║ and generally navigate through the LARC menus. ║ █████▀ ║ ║ ║ ╚══════════════╝ The Main Menu ═════════════ LARC provides a basic menu system to help you navigate through the system. Navigating through the menus requires simple use of arrow keys, page keys and minimal input of other information. Depending on how your LARC system is configured, it may be possible for you to do most of your work with just the arrow, page and enter keys. LARC's Main Menu provides a central starting place for accessing all of LARC's features. The System Maintenance Menu ═══════════════════════════ LARC' System Maintenance Menu provides access to LARC's system administration functions. Recognized Keystrokes ═════════════════════ LARC uses straight forward cursor movement keys, such as the arrow keys, as much as possible to allow you to navigate the menus and program prompts. Here is list of the keys that LARC recognizes with a brief description of the action caused by each key. <Esc> Pressing this key will exit to the previous screen or menu. If you are on the main menu screen, LARC will terminate and return to the operating system prompt, or return you to the LARC security screen, based upon how LARC has been configured. <> Move the highlight bar up to the previous field. <> Move the highlight bar down to the next field. <> Move the highlight bar to the right one field. <> Move the highlight bar to the left one field. ───────────────────────────────────────────────────────────────── 71 LARC User's Guide Chapter 9 - The Menus ═════════════════════════════════════════════════════════════════ <PgUp> Move the highlight bar up 16 lines. <PgDn> Move the highlight bar down 16 lines. <Hone> Move the highlight bar to the first item or line being displayed. <End> Terminate and accept the information being entered. <Tab> Selects the highlighted item or terminates an input field. <Enter> Selects the highlighted item or terminates an input field. <F2> Whenever the Main Menu is displayed, pressing the <F2> key causes the list of libraries to be quickly displayed. This has the same effect as pressing the <Alt> and <F> keys together, followed by the <S> key, followed by the <Enter> key. <F3> From any of the file listing screens, such as the check out or check in screens, pressing the <F3> key causes file display sort sequence to be changed. There are three modes. One displays files in ascending order based on the full file name. The second displays files in ascending order besed on the file extension. The third displays files in ascending date and time stamp order. <F4> From any of the file listing screens, such as the check out or check in screens, pressing the <F4> key causes file display to be expanded to include the file date and time stamp. Pressing the <F4> key again causes the display to return to its normal state. <F10> When adding files to a library that are binary files, LARC will ask you to manually enter the file version number and description information. Since it is possible to select files that you did not intend to add to a library (such as OBJ files from your working directory), pressing the <F10> key provides a way for you to skip incorrectly selected binary files. The menus provide quick access keys which help reduce keystrokes required to move through the system. ───────────────────────────────────────────────────────────────── 72 LARC User's Guide Chapter 9 - The Menus ═════════════════════════════════════════════════════════════════ The Main Menu quick access keys are: <Alt+F> Pressing the <Alt> key and the <F> key at the same time moves the menu to the "File" menu functions. <Alt+D> Pressing the <Alt> key and the <D> key at the same time moves the menu to the "Display" menu functions. <Alt+P> Pressing the <Alt> key and the <P> key at the same time moves the menu to the "Print" menu functions. <Alt+R> Pressing the <Alt> key and the <R> key at the same time moves the menu to the "Release" functions. <Alt+M> Pressing the <Alt> key and the <M> key at the same time moves the menu to the "Maintenance" functions. <Alt+Q> Pressing the <Alt> key and the <Q> key at the same time moves the menu to the "Quit!" function. The System Maintenance Menu quick access keys are: <Alt+L> Pressing the <Alt> key and the <L> key at the same time moves the menu to the "Libraries" menu functions. <Alt+E> Pressing the <Alt> key and the <E> key at the same time moves the menu to the "Extensions" menu functions. <Alt+U> Pressing the <Alt> key and the <U> key at the same time moves the menu to the "Users" menu functions. <Alt+Q> Pressing the <Alt> key and the <Q> key at the same time moves the menu to the "Quit!" function. Each menu pull down has an accelerator key that can be pressed to further increase the speed with which you can move through the menus. These special accelerator keys are displayed in the drop-down menus as a single character of a color differnt from the rest of the menu text. Simply pressing that letter allows the associated option to be selected without having to move the highlight bar. ───────────────────────────────────────────────────────────────── 73 LARC User's Guide Chapter 9 - The Menus ═════════════════════════════════════════════════════════════════ Selecting a Library ═══════════════════ The first thing you must do is select a working library. To select a library, either: 1. Move the Main Menu highlight bar to "File" and press enter while "select a library" is highlighted. Or, 2. Press the <F2> key whenever the Main Menu is displayed. Either method will cause the library selection screen to be displayed. In addition to using the cursor movement keys to position the highlight bar, you can enter the first letter of the library name and the cursor bar will be automatically moved. For example, if you press the letter <H>, the highlight bar will be moved to the first library that begins with that letter (or a letter greater if no libraries begin with "H"). The name of the library that you select will always be displayed at the top of the screen. ───────────────────────────────────────────────────────────────── 74 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 10 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ▄████▄ ║ File Functions ║ ██ ██ ██ ║ ║ ██ ██ ██ ║ This chapter explains the file access ║ ██ ██ ██ ║ functions that allow you check files into and ║ ██████ ▀████▀ ║ out of LARC libraries. ║ ║ ╚═══════════════╝ The Function Selection Menu ═══════════════════════════ The File functions are selected from the Main Menu by moving the highlight bar to File then selecting an option from that pull down menu. Select the desired file option by either pressing the hot-key letter or by moving the menu bar to desired option and pressing <Enter>. The File screens display the following information: Stat: Status of the file: " " The file is available and can be checked out. "C" The file is currently checked out. "R" The file is a revised file. File: The file name. Version: The edit version of the file. M: "Y" indicates that the file has changed since the last full system build. Who: The initials of the last person to work with the file. Description: The description of the file. The File functions all basically operate the same. You use the cursor movement keys to move the highlight bar to the desired file, then press <Enter>, <Tab> or <SpaceBar> to select or unselect the file. Files are sorted in ascending order based on the name of the file. If you press the first letter of the file, the highlight bar will be moved to the first file name that begins with that letter. For example, pressing the <H> key will move the highlight bar to the first file whose name begins with the letter H. ───────────────────────────────────────────────────────────────── 75 LARC User's Guide Chapter 10 - File Functions ═════════════════════════════════════════════════════════════════ Pressing the star key <*> will cause a file name prompt to appear. You can use this prompt to enter the name of the file you want to select. You can enter any standard DOS-style wildcards, so it is possible to select a group of common files. For example, you could enter "*.BAT" to select all of the batch command files. Pressing the <F3> will toggle the display between full file name and extension order sorting. Pressing the <F4> will expand the listing to show the file date and time stamp. As you select each file, a check mark character will be displayed by the file selected. Press the <End> key when you have selected all of the desired files. You will then be asked to verify that you have selected the correct set of files. Answer <Y> if you selected the right files or <N> to return to the selection screen. Once you answer the yes to the verification screen, LARC will complete the requested operation. Depending on your LARC configuration, you may be presented several additional prompts when copying or checking out files. Respond to these prompts appropriately to complete the process: 1. You may be asked to verify the output directory or diskette path name. 2. If a file by the same name already exists in the destination directory, LARC will compare the date, time and size of the file being checked out against those of the of file that already exists. If the existing file has a date or time that is later than the file being checked out, or the files sizes are different, LARC will ask you to verify that you want to overwrite the existing file. This feature helps prevent lost code caused when you incorrectly edit a file before checking it out. If this happens, you can save the existing file before it gets overwritten, then apply the changes to the correct file. If you receive the warning, you must specifically tell LARC to overwrite the existing file. LARC will show the name of the file and ask you to enter one of several choices: <Y> Yes, overwrite the file. <N> No, do not overwrite the file. The file will not be copied or checked out. <G> Go ahead and overwrite the file, and also have LARC skip checking for the existance of any additional files in your selection list. ───────────────────────────────────────────────────────────────── 76 LARC User's Guide Chapter 10 - File Functions ═════════════════════════════════════════════════════════════════ <Q> Quit. The displayed file, as well as any remining files, will not be checked out or copied. Any files that you have already anwered yes to will have been checked out or copied. Selecting a Library ═══════════════════ Refer to Chapter 9 for details on how to select a library. Check Out a File ════════════════ Use this option to check files out of the library. When you select this option, a listing of all of the files in the currently selected library will be presented. Check In a File ═══════════════ Use this option to check files back into the library. When you select this option, a listing of all of the files that you have checked out will be presented. Once you answer the verification screen <Y>, LARC will begin to check in the files. Depending on your LARC configuration, you may be presented with a screen asking you to enter a path name. This prompt appears if you started LARC from some directory other than the directory where the files exist, or if the diskette containing the files is not in the correct drive. Either enter the correct path, or exit and restart LARC from the correct library. LARC allows you to check in both ASCII text files and binary files. If you check in a file that does not contain embedded release control information, LARC will prompt you to manually enter the version and description of the file. LARC allows any type of binary file to be placed into a library. This includes, but in no way is limited to, executable programs, linkable object modules, word processing files, and other non-text files. It may be possible to embed release control information in your word processing files. For example, WordPerfect files can contain comments that include the embedded tokens and information strings. LARC can search these files and properly identify the embedded release control information. Using embedded release control information in your word processing files would allow them to be easily checked in and out of a library without forcing you to manually enter the file's information. ───────────────────────────────────────────────────────────────── 77 LARC User's Guide Chapter 10 - File Functions ═════════════════════════════════════════════════════════════════ Add a New File ══════════════ Use this option to add new files back to the library. When you select this option, LARC will prompt you to enter the name of the file you want to add. You may specify the full drive and path name of the file(s) you want to add. You may also use any valid DOS-style file name substitution character in the file name. If you leave the path name prompt blank or enter "*.*", then all of the files in the default directory that are not already in the library will be presented. If you enter a partial file name, say "*.BAT" for example, then only the batch files that are not already in the library will be listed. When you enter the file name, you will be presented with a list of files to select. Copy a File ═══════════ Use this option to copy files out of the library. Copying files from a library does not mark them as checked out. When you select this option, a listing of all of the files in the currently selected library will be presented. You can copy any file from the library. Even files that you or another user previously checked out can be copied. Cancel a Check Out ══════════════════ Use this option to cancel the check out of files. When you select this option, a listing of all of the files that you have checked out will be presented. The selection screen only displays files that have been previously checked out by you. Delete a File ═════════════ Use this option to delete obsolete files from the library. When you select this option, a listing of all of the files that are in the library will be presented. ╔═════════════════════════════════════════════════════╗ ║ NOTE: You should be very careful when deleting files║ ║ from libraries. As with any delete operation,║ ║ it is possible to delete files that should not║ ║ be deleted. Make sure that you carefully ║ ║ review all of the displayed information to ║ ║ ensure that only the proper files are deleted.║ ║ ║ ║ NOTE: You cannot delete files that are currently ║ ║ checked out. You can delete any other file, ║ ║ including revised files, at any time. ║ ╚═════════════════════════════════════════════════════╝ ───────────────────────────────────────────────────────────────── 78 LARC User's Guide Chapter 10 - File Functions ═════════════════════════════════════════════════════════════════ Get All Files ═════════════ Use this option to get a copy of all of the files that are in the library. This option is intended for network users. The function simply recreates LARC's same directory structure on your local hard drive and copies all of the files to your drive. When you select the get all function, LARC will ask you the several questions: 1. You will be asked to enter the destination hard driver letter. This hard drive must be different from the drive where the libraries are stored. 2. Do you want to get just the files from the currently selected library, or those files plus any files that are associated with that library. Libraries are "associated" when they share the same root directory name. 3. Do you want to copy the files from any release directories that have been defined for the libraries that will be cpied? 4. Do you want to delete any existing files from the destination directories before the files are copied from the libraries? Answer these questions according to your needs and LARC will then begin copying the files. Note that LARC will skip any files that you had previously checked out. LARC will also warn you if a file is encountered in the destination directory that has a date and time that is later than the source file. When the get all function completes, LARC will display a summary box showing the number of files that were copied and skipped. ╔═════════════════════════════════════════════════════╗ ║ WARNING: If you ask LARC to delete the destination ║ ║ directories, then any files that you had ║ ║ previously checked out to one of the ║ ║ destination directories will be deleted! ║ ║ This option is intended to provide an easy ║ ║ "cleanup" at the start of your work in a ║ ║ set of libraries. ║ ╚═════════════════════════════════════════════════════╝ ───────────────────────────────────────────────────────────────── 79 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 11 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ███ ║ Display Functions ║ ██ ██ ║ ║ ██ ██ ║ This chapter explains the file display ║ ██ ██ ║ functions which allow you display file and ║ ██████ ██████ ║ other LARC information on the screen. ║ ║ ╚═══════════════╝ Display Menu ════════════ The Display functions are selected from the Main Menu by moving the highlight bar to Display then selecting one of the available options from that pull down menu. Select the desired display option by either pressing the hot-key letter or by moving the menu bar to desired option and pressing <Enter>. Several of the display screens use the following fields. Stat: This is the status of the file: " " The file is available and can be checked out. "C" The file is currently checked out by the person whose initials appear under the "who" column. "R" The file is a revised file. It was revised by the person whose initials appear under the "who" column and the original file name appears in the "description" column. Lib.: The library number that owns the file that has been listed. Since LARC associates libraries that share the same initial directory name, viewing a list of checked out files may show files that you have checked out of several libraries. This number identifies the library for the checked out file. Also, as the number changes, the "Library:" heading name will change. File: The file name. Version: The edit version of the file. If this is a revised file, this is the version number of the file prior to it being revised. ───────────────────────────────────────────────────────────────── 80 LARC User's Guide Chapter 11 - Display Functions ═════════════════════════════════════════════════════════════════ M: "Y" indicates that the file has changed since the last full system build. Who: The initials of the last person to work with the file. If the file is currently checked out, these are the initials of the person that has the file checked out. For revised files, these are the initials of the person who updated the file. Description: The description of the file. Library Contents ════════════════ Use this option to display a listing of all of the files in the currently selected library. Source File ═══════════ Use this option to display show source files that exist in a library on the screen. When you select this option, lets you select the a list of files to be shown. You can use all of the features available when selecting files to be copied or checked out. So, you can use the <*> file selection key and specify a group of files (using wildcard characters) to be viewed. Pressing the <Esc> key will exit viewing of the current file. If there are more files in the selection list, the next file will be displayed. If there are no more files to be viewed, the menu will be redisplayed. My Checked Out Files ════════════════════ Use this option to display a listing of the files that you have checked out of the library. Remember that LARC associates libraries that share a common initial directory name. This option will show all of the files that you have checked out of the currently selected library, plus any libraries have the same initial directory name. Checked Out Files ═════════════════ Use this option to display a listing of the files that all users have checked out of the library. Remember that LARC associates libraries that share a common initial directory name. This option will show all of the files that are checked out of the currently selected library, plus any libraries that have the same initial directory name. ───────────────────────────────────────────────────────────────── 81 LARC User's Guide Chapter 11 - Display Functions ═════════════════════════════════════════════════════════════════ Release History ═══════════════ Use this option to display a listing of the release that have been created for this library. The listing is displayed in ascending order based on the date and time that the release was created. Final release will be shown in a unique color. Revised Files ═════════════ Use this option to display a listing of the files that have been revised in the library. Remember that LARC associates libraries that share a common initial directory name. This option will show all of the files that have been revised in the currently selected library, plus any libraries that have the same initial directory name. Activity Log File ═════════════════ Use this option to display the LARC system activity log file. This screen displays the following fields. Date: The date of the log file entry in YYMMDD format. Time: The time of the log file entry in HHMMSStt format. Lib: The LARC library number for the library that was selected by the user. Who: The initials of the person that selected the library. Logged text: The activity log text. Examples of logged events are LARC start and stop messages, file check out and check in operations and warning messages. ───────────────────────────────────────────────────────────────── 82 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 12 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ▄████▄ ║ Print Functions ║ ██ ▀▀ ██ ║ ║ ██ ▄█▀ ║ This chapter explains the file print functions ║ ██ ▄█▀ ║ which allow you create hard copy listings of ║ ██████ ██████ ║ file and other LARC information. ║ ║ ╚═══════════════╝ Print Menu ══════════ The Print functions are selected from the Main Menu by moving the highlight bar to Print then selecting one of the available options from that pull down menu. Select the desired print option by either pressing the hot-key letter or by moving the menu bar to desired option and pressing <Enter>. As each option is selected, a small message will appear indicating that the report is being produced. You continue as soon as that message is removed from the screen. ╔═════════════════════════════════════════════════════╗ ║ NOTE: LARC writes all report files into a file named║ ║ LARCPRN.xxx where xxx is your initials. You ║ ║ need to wait until after the file is ║ ║ completely printed before requesting a second ║ ║ print option. The length of time you need to ║ ║ wait depends on your environment. If you are ║ ║ using a print spooler, then a few seconds ║ ║ should be sufficient. ║ ╚═════════════════════════════════════════════════════╝ Library Contents ════════════════ Use this option to create a listing of all of the files in the currently selected library. This report uses the following fields. No.: This is a sequential count of the files in the library. S: File status: " " The file is available. "C" Checked out. "R" Revised file. ───────────────────────────────────────────────────────────────── 83 LARC User's Guide Chapter 12 - Print Functions ═════════════════════════════════════════════════════════════════ Module: The file name. Version: The edit version of the file. M: "Y" indicates that the file has changed since the last full system build. Who: The initials of the last person to work with the file. If the file is currently checked out, these are the initials of the person that has the file checked out. Date: Date of the file. Time: Time of the file. Size: Size of the file in bytes. Description: The description of the file. Source File ═══════════ Use this option to print source files that exist in a library. When you select this option, LARC lets you select a list of files to be printed. You can use all of the features available when selecting files to be copied or checked out. So, you can use the <*> file selection key and specify a group of files (using wildcard characters) to be printed. LARC will print each file once you complete these selection process. My Checked Out Files ════════════════════ Use this option to create a listing of the files that you have checked out of the library. This report uses the following fields. Lib: This is the number for the library that owns the file that you have checked out. This number is used whenever a group of libraries share a common initial directory. Module: The file name. Version: The edit version of the file. M: "Y" indicates that the file has changed since the last full system build. ───────────────────────────────────────────────────────────────── 84 LARC User's Guide Chapter 12 - Print Functions ═════════════════════════════════════════════════════════════════ Who: This will always be your initials for this report. Date: Date of the file. Time: Time of the file. Size: Size of the file in bytes. Description: The description of the file. Checked Out Files ═════════════════ Use this option to create a listing of the files that all users have checked out of the library. This report uses the following fields. Lib: This is the number for the library that owns the file that you have checked out. This number is used whenever a group of libraries share a common initial directory. Module: The file name. Version: The edit version of the file. M: "Y" indicates that the file has changed since the last full system build. Who: The initials of the person that checked the file out. Date: Date of the file. Time: Time of the file. Size: Size of the file in bytes. Description: The description of the file. Release History ═══════════════ Use this option to create a listing of the release that have been created for this library. This report uses the following fields. No.: Sequential count of releases built for this library. Release: One to eight character release identifier. ───────────────────────────────────────────────────────────────── 85 LARC User's Guide Chapter 12 - Print Functions ═════════════════════════════════════════════════════════════════ Type: Release build type. This field will contain the release build number or "F" if this was a full build. Date: Date of the release. Time: Time of the release. Who: The initials of the person that initiated the build. Description: The description for the build that was entered by the person when the build was produced. Revised Files ═════════════ Use this option to create a listing of the revised files in library. This report uses the following fields. Lib: This is the number for the library that owns the file that has been revised. This number is used whenever a group of libraries share a common initial directory. Module: The name given to the previous version of a revised file. The latest version always keeps the original file name and you can inspect the description field to see the original name of the revised file. Version: The edit version of the file. M: "Y" indicates that the file has changed since the last full system build. Who: The initials of the person that revised the file. Date: This is the date of the file before it was revised. Time: This is the time of the file before it was revised. Size: Size of the original file in bytes. Description: The description field contains the orginal name of the file. ───────────────────────────────────────────────────────────────── 86 LARC User's Guide Chapter 12 - Print Functions ═════════════════════════════════════════════════════════════════ Activity Log File ═════════════════════════════════════════════════════════════════ Use this option to print the LARC system activity log file. Each line of the report contains the date and time that the entry was logged. The report also contains the library number, the user's initials and the event being logged. ───────────────────────────────────────────────────────────────── 87 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 13 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ▄████▄ ║ Release Generation Functions ║ ██ ▀▀ ██ ║ ║ ██ ██ ║ This chapter explains how to use LARC to ║ ██ ▄▄ ██ ║ build software releases and how to produce ║ ██████ ▀████▀ ║ release diskettes. ║ ║ ╚═══════════════╝ Release Menu ════════════ The Release functions are selected from the Main Menu by moving the highlight bar to Release then selecting one of the available options from that pull down menu. Select the desired print option by either pressing the hot-key letter or by moving the menu bar to desired option and pressing <Enter>. Creating a Diskette Release ═══════════════════════════ The first four option provided on the release menu all work the same way. These options allow you to cut a set of release diskettes by specifying which size diskette you want to use. When you select one of the first four options, LARC ensure that the correct diskette size is used. After selecting one of the first four options, LARC will ask you to enter the type of release being cut. If you enter <A>, then LARC will create all available releases, in order. As each release is cut, LARC will scan the release cut file and make sure that all of the files it references are available. Assuming no problems are detected, you will be asked to insert the first release diskette. LARC will copy your release files to the diskette and prompt you to insert the next diskette if more than one diskette is required. When the release diskettes have been created, LARC will print a report showing the files that were copied to the diskettes. This report uses the following fields. Disk: This is the release disk number. File(s): The name of file copied to the disk. Versions: The version number of the file. Timestamp: The date and time stamp of the file. Description: The description of the file. ───────────────────────────────────────────────────────────────── 88 LARC User's Guide Chapter 13 - Release Generation Functions ═════════════════════════════════════════════════════════════════ Size: Size of the file in bytes. Total bytes: The total space required to copy the files to the diskette. Remaining bytes: The amount of free space remaining on the diskette. Creating a hard drive Release ═════════════════════════════ When creating a hard drive release, you select a release cut type just as you would if you were creating a floppy release. However, before the release can be created, you have to provide LARC with a drive and path name to use. LARC will create the directory if it does not already exist. Once you enter a directory name, LARC will scan the release cut file and make sure that all of the files it references are available. Assuming no problems are detected, LARC will begin copying the release files to the release directory. When the release diskettes have been created, LARC will print a report showing the files that were copied to the hard drive. This report uses the following fields. Disk: Always "HD" to indicate that this was a hard drive release. File(s): The name of file copied to the disk. Versions: The version number of the file. Timestamp: The date and time stamp of the file. Description: The description of the file. Size: Size of the file in bytes. Total bytes: The total space required to copy the files to the hard drive. Remaining bytes: The amount of free space remaining on the hard drive. ───────────────────────────────────────────────────────────────── 89 LARC User's Guide Chapter 13 - Release Generation Functions ═════════════════════════════════════════════════════════════════ Release Build ═════════════ After selecting the release build options LARC will ask you to enter the type of release to build. Once you enter the release build type LARC will ask you enter the release identifier to use with this release. You must enter a unique release identifier before LARC will build the release. Once you have entered a unique release identifier and a reason for the build, LARC will execute the LARC build command file that you selected. If you selected <F> or <T>, then LARC will execute all of the release build files that have been created for the library. Also, selecting <F> tells LARC that this is a "final", or "full", system build so LARC will execute the library archive file LARCARC.BAT when the build completes. Once the build process finishes (either successfully or with errors), LARC will display a message and wait for your response. LARC's screen inactivity timer is not active at this screen, so it is safe for you to go do something else while a build is in progress. When you return, LARC will be waiting with the status of the build. Backup Library Source Files ═══════════════════════════ The backup option allows you to produce a backup set of just the sources in the library. The library contains a file named LARCBUP.BAT for DOS or LARCBUP.CMD for OS/2 that contains the commands necessary to backup the library source files. Use this command file as an easy way to produce backup sets of your work while it is in progress. When you select this option, LARC reminds you to prepare the backup media before continuing. Press the <Esc> to exit without creating the backup. Press any other key to continue and create the backup. Purge Test Release Identifiers ══════════════════════════════ Any release that you create that is not a full (<F>) release is classified by LARC as a test release. It is possible that the majority of the releases that you will build will be test releases. This option provides a means of deleting these test release identifiers from the release control file. When you select this option, LARC asks you to verify that you want to delete the test release identifiers. Pressing any key than <Y> will exit the prompt and return to the main menu without purging the test release identifiers. ───────────────────────────────────────────────────────────────── 90 LARC User's Guide Chapter 13 - Release Generation Functions ═════════════════════════════════════════════════════════════════ ╔═════════════════════════════════════════════════════╗ ║ NOTE: Test release identifiers will only be purged ║ ║ for the currently selected library. No other ║ ║ library release identifiers will be effected. ║ ╚═════════════════════════════════════════════════════╝ Execute Serialization Commands ══════════════════════════════ When you select this option, LARC executes the system command file LARCSERL.BAT for DOS or LARCSERL.CMD for OS/2. This command file allows you to add any post-release "fixups" to the release diskettes created by LARC. This feature can be used to: o embed serial number information in your executable files once they have been copied to your release diskettes. o add license information (i.e. user access files) to the release diskette. o run your favorite virus checking software against the release diskettes. o perform any other imaginable post-release process in an automated and repeatable environment. Since the LARCSERL command file is checked into the library, you can have unique serialization commands for each library you create. ───────────────────────────────────────────────────────────────── 91 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 14 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ▄███ ║ Maintenance Functions ║ ██ ▄█▀ ██ ║ ║ ██ ██▄▄██ ║ This section describes the system maintenance ║ ██ ██ ║ functions provided by the LARC. ║ ██████ █████ ║ ║ ║ ╚═══════════════╝ Submit a System Command ═══════════════════════ Provided you have sufficient security access, you can submit a system level command from within LARC. You submit the command by selecting submit a system command from the Maintenance main pull down menu. Select the system command option by pressing the <C> key or be moving the menu bar to submit a system command and pressing <Enter>. Every command that you submit to the system will be logged in the system activity log file. The date, time, your initials and status of the command will also be logged. Backup the Entire System ════════════════════════ The backup entire system function is selected from the maintenance pull down menu provided on Main Menu. Select the backup option by pressing the <B> key or by moving the menu bar to backup the entire system and pressing <Enter>. You will be reminded to prepare the system backup media before continuing. Pressing the <Esc> key will exit and return to the Main Menu screen without producing a backup of the system. Pressing any other key will cause LARC to execute the system backup command file. Format System Backup Media ══════════════════════════ The Backup Media Format function is selected from the maintenance pull down menu provided on Main Menu. Select the format option by pressing the <F> key or by moving the menu bar to format system backup media and pressing <Enter>. You will be reminded to prepare the system backup media before continuing. Pressing the <Esc> key will exit and return to the Main Menu screen without formatting the backup media. Pressing any other key will cause LARC to execute the backup media format command file. ───────────────────────────────────────────────────────────────── 92 LARC User's Guide Chapter 14 - Maintenance Functions ═════════════════════════════════════════════════════════════════ Library Maintenance ═══════════════════ Library maintenance is a system administration function that has been described in Chapter 4. Only users with level 9 security can access this function. Extension Maintenance ═════════════════════ Extension maintenance is a system administration function that has been described in Chapter 5. Only users with level 9 security can access this function. User Maintenance ════════════════ User maintenance is a system administration function that has been described in Chapter 6. Only users with level 9 security can access the information of all users in the system. Any one is able to access this function in order to display and change their own information. ───────────────────────────────────────────────────────────────── 93 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 15 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ██████ ║ Quitting LARC ║ ██ ██ ║ ║ ██ ▀████▄ ║ This chapter describes the methods of ║ ██ ▄▄ ██ ║ quitting LARC and exiting to the operating ║ ██████ ▀████▀ ║ system. ║ ║ ╚═══════════════╝ Quitting LARC ═════════════ There are two ways to quit LARC. From the main menu bar, either select the "Quit" option or press the <Esc> key. If you have sufficient security, LARC will terminate and exit to the operating system prompt. ───────────────────────────────────────────────────────────────── 94 ╔═══════════════╗ ║ ║ ║ ╔═════════════╩═══════════════════════════════════════════════╗ ║ ║ Chapter 16 ║ ║ ╚═════════════╦═══════════════════════════════════════════════╝ ║ ║ ║ ███ ▄████▄ ║ Utilities ║ ██ ██ ▀▀ ║ ║ ██ █████▄ ║ This chapter explains the various utility ║ ██ ██ ██ ║ programs delivered with LARC. ║ ██████ ▀████▀ ║ ║ ║ ╚═══════════════╝ LDIR - Library Directory Utility ════════════════════════════════ The Library Directory (LDIR) Utility is provided to allow you to produce files that show the names of all the files in a particular LARC directory. These output from LDIR is an ASCII text file that is written as a report file. This output file can be printed and archived with the product backup as a historical listing of the files used to build the release. LDIR is typically executed from either the LARC build files or from the LARCARC full system archive file. The command format for LDIR is: LDIR/s cfg-name library-number filename.ext where: cfg-name: This is the name of a LARC configuration file. This configuration file should be the same as the one used when you started LARC. LDIR uses this configuration file in the same way that LARC uses it to find the library files. library-number: This is any valid LARC library number. You can determine the number of the library that you want listed by producing a printing of the library configurations. The number for LARC assigned to each library is provided as the first line of the report. ───────────────────────────────────────────────────────────────── 95 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ filename.ext: This field contains the name of output listing file that you want LDIR to create. The output file is an ASCII report file that can be sent to the printer as soon as LDIR completes. If you enter the name of an output listing file that already exists, the files reported will be appended to the previous listing file. This feature allows you to create one large listing file that contains all of the libraries used to produce your product. /s: There are two switches that LDIR recognizes. These are: /P LDIR will print the file after it is created. /Q LDIR will run in "quiet" mode and not display to the screen. If you specify the two switches together, do so as "/PQ". GETLARC - File Information Extraction Utility ═════════════════════════════════════════════ GETLARC is a utility program used to create an ASCII file that contains the version and description for a LARC library file. This program was written to create a simple ASCII file to be used by the LARC build file as input to PKZIP as a comment. The PKZIP comments allows you to get the LARC version and description information included in your compressed files. When LARC copies PKZIP compressed files to your release diskettes, it searches the compressed files and extracts any comments. The comments are then written to the report that LARC produces that tells you what was copied to the release diskettes. GETLARC is typically executed from the LARC build files. The command format for GETLARC is: GETLARC/s cfg-name nnn larcname.ext outname.ext Where: cfg-name: This is the name of a LARC configuration file. This configuration file should be the same as the one used when you started LARC. GETLARC uses this configuration file in the same way that LARC uses it to find the library files. ───────────────────────────────────────────────────────────────── 96 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ nnn: This number is the three digit LARC library number that contains the file that you are searching for. larcname.ext: This is the name of the file to be found in the library. This parameter should only contain the file name. Do not include a drive letter or path in this parameter. This name is simply the name of the file recorded in a LARC library. outname.ext: This is the name of the file that will contain the version number and file and description that GETLARC will extract from LARC. The filename can contain a drive and directory. However, since you will typically be executing GETLARC from your LARC build file, you will not need to specify either a drive letter or path name. /s: The only optional switches that GETLARC recognizes is the /Q switch. This switch tells GETLARC to run in "quiet" mode and not display to the screen. The output file created by GETLARC will contain one record. This record has the following format: vvv description where: vvv: This is the version number of the file. description: This is a one to fifty character description of the file. If you specify a source file name that is not in the LARC library, or specify an incorrect library number, GETLARC will create the output file with "*** NO VERSION OR DESCRIPTION AVAILABLE ***". INSTALL - LARC Installation Program ═══════════════════════════════════ The LARC Installation Utility program (INSTALL) is provided to allow you to integrate a simple automated installation procedure into your products. Your LARC libraries can be configured to create install files on your release diskettes. Then, when you cut release diskettes, records from your LARC release CUT files will be copied into the install files. These install files can be processed by the LARC INstallation Program to automate the process installing your product. ───────────────────────────────────────────────────────────────── 97 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ The install files contain records that tell the LARC Installation Program what to do. Each record that the program recognizes is started with a special character. The following records are supported by the program. "0" Disk number and version record. "!" LARC Installation Program defaults record. "S" System name record. "1" Copy a file. "8" End of the current diskette. "9" End of all diskettes. "C" Change to a different directory. "D" Delete a file. "E" Execute a command. "M" Make a directory. "R" Remove a directory. "U" Unzip a compressed file. "V" Verify that a file exists. Disk Number and Version Record ────────────────────────────── This record defines the diskette sequence number and documents the version number for the release diskettes. This record must be the first record for all release diskettes. byte 1: Always "0". bytes 2-3: Two digit diskette number. The first diskette is always diskette number "01". byte 4: The release build type of either "S" or the numbers "1" through "5". bytes 5-12: The eight character release identifier that you provided to LARC when the release was built. Defaults Record ─────────────── This record defines the default field values for the installation program. This record must exist as the second record on diskette number 01. byte 1: Always "!". byte 2: The default floppy drive letter. byte 3: The default hard drive letter. bytes 4-n: The default destination directory name. ───────────────────────────────────────────────────────────────── 98 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ System Name Record ────────────────── This record defines the name of the system that you are installing. The LARC Installation Program will display this name during the installation process. This record must be the third record for diskette number 01. Byte 1: Always "S". Bytes 2-51: Up to fifty characters for the name of your system. Copy a File ─────────── This record defines a file that may be copied from the installation diskette to the destination directory. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. byte 1: Always "1". byte 2: Copy control indicator: " " Always copy the file from the installation diskette to the destination directory. "-" Do not copy the file from the installation diskette to the destination directory. "*" Only copy the file from the installation diskette to the destination directory if the file does not already exist in the directory. Bytes 3-14: This is the name of the file to copy. Change to a Different Directory ─────────────────────────────── This record defines a directory that should become the destination directory. The installation program will change to this directory and any subsequent commands will effect this new directory. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "C". Byte 2: Always blank. Bytes 3-n: This is the name of the directory to be changed as the destination directory. See the note below on special replacement characters recognized for this record. ───────────────────────────────────────────────────────────────── 99 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ Delete a File ───────────── This record defines a file that is to be deleted from the destination directory. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "D". Byte 2: Always blank. Bytes 3-14: This is the name of the file to be deleted from the destination directory. Execute a Command ───────────────── This record defines a program or system command file that is to be executed. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "E". Byte 2: Always blank. Bytes 3-n: This is the name of the program or command file to be executed. Make a Directory ──────────────── This record defines a directory that is to be created. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "M". Byte 2: Always blank. Bytes 3-n: This is the name of the directory to be created. See the note below on special replacement characters recognized for this record. Remove a Directory ────────────────── This record defines a directory that is to be removed from the system. All of the files must be deleted from the directory before it can be removed. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "R". Byte 2: Always blank. ───────────────────────────────────────────────────────────────── 100 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ Bytes 3-n: The name of the directory to be removed. See the note below on special replacement characters recognized for this record. Unzip a Compressed File ─────────────────────── This record defines a file that is to be decompressed using the PKUNZIP utility program. The PKUNZIP program must be available to LARC in order for this command to work correctly. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "U". Byte 2: Always blank. Bytes 3-14: This is the name of the file to be unzipped. Verify a File Exists ──────────────────── This record defines a file that is to be verified in the destination directory. These records can occur in any order as long as they exist between a "1" and either the "8" or "9" records. Byte 1: Always "V". Byte 2: Always blank. Bytes 3-14: This is the name of the file to be verified. End of the Current Diskette ─────────────────────────── This record defines the end of the current diskette. The installation program will prompt you to insert the next installation diskette. This record should be the last record in the file. Byte 1: Always "8". Byte 2: Always blank. Bytes 3-6: This field contains a count of the number of files that are present on the diskette. ───────────────────────────────────────────────────────────────── 101 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ End of All Diskettes ──────────────────── This record defines the end of the current diskette and that this diskette is the last installation diskette. This record should be the last record in the file. Byte 1: Always "9". Byte 2: Always blank. Bytes 3-6: This field contains a count of the number of files that are present on the diskette. Special Directory Replacement Characters ──────────────────────────────────────── Usually, the directory path names will contain directory names such as "C:\LARC\TEMP". The LARC Installation Program allows you to code these records so that the installation destination information you enter can be used. You can use "?:?\TEMP" as the directory name. The program will replace the first "?" character with the destination hard drive letter you entered. The second "?" character will be replaced by the directory name that you entered. Parameterizing the directory names this way provides flexibility. You do not have to hard code directory creation or force the product to install into a specific set of directories. Error Handling ────────────── The installation program lets you know what is happening by displaying messages that will scroll up the screen. INSTALL will prompt for the next diskette and make sure that the proper diskette was loaded. INSTALL will notify you if it encounters any problem with the commands it reads from the installation control files. Any problem will cause the install program to terminate and display a message warning the user that a complete installation was not performed. Likewise, when the installation completes successfully, INSTALL will display a message indicating so. ───────────────────────────────────────────────────────────────── 102 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ Example DISKnn.CTL File ─────────────────────── Here is an example DISK01.CTL file for a single diskette release. This just happens to be the control file for LARC. 001*3.00y ! AC\LARC3 S Library Administration and Release Control D CFREAD.DLL D ERRLOG.DLL D GETLARC.EXE D LARC3.EXE D LARCLIB.DLL D LDIR.EXE D MAINT.DLL D MESSAGES.LRC D OVL1.DLL D OVL2.DLL D OVL3.DLL D OVL4.DLL D OVL5.DLL D OVL6.DLL 1 INSTALL.EXE 1-READ.ME 1*LARC.BAT 1*LARC.CFG 1*LARC.PIF 1*MESSAGES.LRC 1*LARCFORM.BAT 1*LARCBACK.BAT 1 CFREAD.DLL 1 ERRLOG.DLL 1 GETLARC.EXE 1 LARC3.EXE 1 LARCLIB.DLL 1 LDIR.EXE 1 MAINT.DLL 1 OVL1.DLL 1 OVL2.DLL 1 OVL3.DLL 1 OVL4.DLL 1 OVL5.DLL 1 OVL6.DLL V CFREAD.DLL V ERRLOG.DLL V GETLARC.EXE V LARC.BAT V LARC.CFG V LARC3.EXE V LARCBACK.BAT V LARCFORM.BAT V LARCLIB.DLL V LDIR.EXE ───────────────────────────────────────────────────────────────── 103 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ V MAINT.DLL V MESSAGES.LRC V OVL1.DLL V OVL2.DLL V OVL3.DLL V OVL4.DLL V OVL5.DLL V OVL6.DLL 90021 Here are some comments about this file: 1. The LARC Installation Program will default to "A" as the floppy drive letter, "C" as the hard drive letter and "\LARC3" as the destination directory. 2. The LARC Installation Program will display "Library Administration and Release Control" as the name of the product being installed. 3. The delete records are placed at the front of the file. Deleting obsolete or temporary files, and files that we are about to replace, provides the maximum free hard drive space to the LARC Installation Program. 4. Copy the file from the diskette to the destination. Notice that several of the files use the "*" control byte which tells the LARC Installation Program to only copy them if they do not already exist. This keeps future releases from destroying changes to configuration or data files. 5. The verify records are placed at the end of the file. Verifying that the required files exist in the destination directory ensures that everything was installed as expected. 6. The "9" record tells the LARC Installation Program that we are done and shows that there should be 15 installlation files on the release diskette. KCOPY - Ken's File Copy Program ═══════════════════════════════ KCOPY is a simply utility that can be used to copy files from the current hard disk directory to a floppy diskette. This utility basically functions as the standard "copy" command with one exception. When the diskette is full, KCOPY will prompt you to enter the next diskette. To use KCOPY, enter: KCOPY[/switch] d:\path\filename.ext d: ───────────────────────────────────────────────────────────────── 104 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ where: /switch: Optional command switches which must be entered right behind the KCOPY command, like KCOPY/QF. Valid switches are: F Display a total of the remaining bytes after this file is copied. H Display the help screen. Q Ask before copying each file to the diskette. d:\path\filename.ext: This a valid DOS path and file name. DOS wildcard characters are supported. d: This is the destination drive letter of either A: or B:. If you enter do not enter the two arguments, KCOPY will prompt you to enter the "From:" and "To:" information. KDEL - Ken's File Delete Program ════════════════════════════════ KDEL is a simply utility that can be used to delete files from your system. This utility basically functions as the standard system "del" command except that KDEL will asks before deleting a file. To use KDEL, enter: KDEL[/switch] d:\path\filename.ext where: /switch: Optional command switches which must be entered right behind the KDEL command, like KDEL/N. Valid switches are: A Delete ALL files, including hidden and system files. Be very careful with this switch! H Display the help screen. ───────────────────────────────────────────────────────────────── 105 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ M Use monochrome display attributes. N Do not ask before deleting the file (delete all files). d:\path\filename.ext Consists of any valid path and file naming string. You can use the "*" and "?" wildcards to specify groups of files to be deleted. If you enter do not enter the argument, KDEL will prompt you to enter the "Files(s)?" to be deleted. You will be prompted "Delete file d:\path\filename.ext [Y/N/G/Q]?" and expected to provide an answer before the file will be deleted. You can respond with: Y Yes, delete the file. N No, do not delete the file. G Go, deleting this file and all remaining files without further prompting. Q Quit. Do not delete the file. Exit immediately to the operating system prompt. KFREE - Ken's Free Space Program ════════════════════════════════ KFREE is a simply utility that can be used to show the current free space for a specified drive. To use KFREE, enter: KFREE[/switch] [d:] where: /switch: Optional command switches which must be entered right behind the KFREE command, like KFREE/M. Valid switches are: H Display the help screen. M Use monochrome display attributes. d: The drive for which the free space is to be displayed. If no drive is specified, the free space for the current drive will be displayed. ───────────────────────────────────────────────────────────────── 106 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ The KFREE information shown is: o Drive letter and volume label. o Total number of clusters. o Available clusters. o Sectors per cluster. o Bytes per sector. o Bytes per cluster. o Total bytes available. o Total bytes used. o Remaining free bytes. o Percent of the space used. KVERENV - Ken's Verify Environment Program ══════════════════════════════════════════ KVERENV is a simply utility that can be used to verify that a system environment variable has been properly set. This utility can be used in LARC build command files to ensure the proper set up of required system environment string before the build is attempted. To use KVERENV, enter: KVERENV[/switch] envvar=string where: /switch: Optional command switches which must be entered right behind the KVERENV command, like KVERENV/M. Valid switches are: H Display the help screen. M Use monochrome display attributes. Q Run in "quite mode". Nothing will displayed on the screen. envvar=string: KVERENV searches the current environment settings for the variable "envver" and compares what it finds againts "string". The program exit code will be set to indicate wheather or not the environment string was found, and if so, whether or not it matched "string". If you enter do not specify a argument, KVERENV will display a help screen and exit. On exit, KVERENV will return the following codes. Note that these codes can be checked in DOS command batch files by testing ERRORLEVEL: ───────────────────────────────────────────────────────────────── 107 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ 00 OK, the environment string "envvar" exists and matches "string" exactly. 01 "envvar" exists, but does not match "string". 02 "envvar" does not exist. 03 An invalid "envvar=string" environment string format was passed into KVERENV. 04 The version or help screen displayed and KVERENV stopped. KDIR - Ken's Directory Program ══════════════════════════════ KDIR is a simply utility that can be used to display a list of files on your system. This utility basically functions as the standard "dir" command except that KDIR displays the directory information in an easier to read format, and KDIR uses color to highlight several interresting directory features. To use KDIR, enter: KDIR[/switch] d:\path\filename.ext where: /switch: Optional command switches which must be entered right behind the KDIR command, like KDIR/AD. Valid switches are: A Show the archive attribute setting. D show <directory> names. H Display the help screen. L Produce only a list of file names, followed by one space character. This option lets you create easliy edited lists of file. M Use monochrome display attributes. d:\path\filename.ext Consists of any valid path and file naming string. You can use the "*" and "?" wildcards to specify groups of files to be listed. ───────────────────────────────────────────────────────────────── 108 LARC User's Guide Chapter 16 - utilities ═════════════════════════════════════════════════════════════════ If you enter KDIR without providing any arguments, all files in the current directory will be shown. The files are listed in the order in which they appear in the directory. Sub-directory entries will be listed with text "<directory>". The file creation and/or modification date and time stamp is listed in millitary (24 hour) format. KDIR uses special colors to display information on your screen. The colors used depends on the current seeting of your "PROMPT" command, so you will have to enter "KDIR/H" and let KDIR tell you what colors are being used. KDIR displayed files of the certain size ranges in different colors. This helps you locate certain sized files when/if you are performing disk management chores. The size ranges are: o files from 0 to 512k bytes. o files from 512k to 1 megabyte. o files larger than 1 megabyte. Finally, each file will have a descriptive text string displayed after the time stamp which shows the current file attribute settings. The attribute texts are:. blank: normal file. Archive: The archive attribute is set. This text is only shown if /A switch is used. RO: The file is a read only file. Hidden: The file is a hidden file. System: The file is a system file. While KDIR is scrolling file listings up the screen, pressing any key on the keyboard will halt the scrolling. When halted, pressing any key again will resume scrolling. ───────────────────────────────────────────────────────────────── 109