OAS Administration - Windows

OASYS Administration for Windows 64 Bit Platforms

© 2012 Onsystex Inc.

Onsystex 2012 All Rights Reserved

Note: This document may contain Confidential Privileged information and is intended only for the recipient(s). Receipt of this document by any person other than the intended recipient does not constitute permission to examine, copy, or distribute this document thereto and doing so is strictly prohibited. If you receive this document in error, please notify the sender immediately, by either electronic mail message or telephone. We kindly request that no copies be made of the original electronic document.

OASIS Administration Microsoft Windows 64 bit Platforms Introduction by Onsystex Inc. Welcome to OASYS, the most advanced, high performance transactional business application server built to leverage the best capabilities of MultiValue and Relational technologies. If you are look ing to create, extend or migrate multiuser business applications to the cloud in a SAAS model, OASYS is the right product for you. OASYS offers a sophisticated and robust core environment ideal to create and host business rules that can be accessed natively or through any of the built in multipurpose data provider connectors to interface with web, client/server and/or terminal based applications that utilize multi-discipline software technlogy including Java and .NET For ultimate flexibility, application data can be stored, accessed and managed on OASYS' hybrid multidimensional data store which supports relational databases including Oracle, SQL Server, Postgres, DB2, MySQL. As a result applications can seamlessly integrate with external data sources mak ing a reality the ability to "write once and deploy anywhere" software applications. Thank you for using our products. This document is property of Onsystex, Inc and should not be copied, altered or reproduced without the express written authorization of Onsystex, Inc. Please note that all references to vendors and their respective third party products in this document are in most cases protected by trademark s, patents and/or copyrights. Any references made on this document were solely used for illustration purposes. The content of this document is subject to change without notice. For more information about this document or to learn more about the family of Onsystex products, please contact Onsystex directly or visit us at www.onsystex.com.

OASYS Administration for Windows 64 Bit Platforms © 2012 Onsystex Inc. All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the written permission of the publisher. Products that are referred to in this document may be either trademarks and/or registered trademarks of the respective owners. The publisher and the author make no claim to these trademarks. While every precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of information contained in this document or from the use of programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document.

Publisher Onsystex Publications Managing Editor Onsystex Mark eting Technical Editors Onsystex Technical Support Team Onsystex Engineering Cover Designer Onsystex - Euphoria .NET Team Coordinator Onsystex Technical Publications Production Onsystex Mark eting

Special thanks to: All the team members of Onsystex and Beta customers who contributed to this document.

4

OASYS Administration for Windows 64 Bit Platforms

Table of Contents 1 Introduction

10

1 About................................................................................................................................... This Manual 10 Audience .......................................................................................................................................................... 10 About the Product .......................................................................................................................................................... 10 Unsupported .......................................................................................................................................................... Com m ands 10 Reserved Characters .......................................................................................................................................................... 11 Case Sensitivity .......................................................................................................................................................... 11 Sym bolic Links .......................................................................................................................................................... 12 Phantom Com.......................................................................................................................................................... m and 12 Dynam ic Files.......................................................................................................................................................... 12 Deleting Files.......................................................................................................................................................... 12 PCPERFORM Com .......................................................................................................................................................... m and 13 Shell Com m and .......................................................................................................................................................... Differences 13 Use of Sem icolon .......................................................................................................................................................... 13

2 Notes................................................................................................................................... About Terminal Devices and Tape Drives 14 Term inal Devices .......................................................................................................................................................... 14 Tape Devices .......................................................................................................................................................... 14

3 Printing ................................................................................................................................... in OAS for Windows Platforms 15

2 Managing and Using the OASTelnet Service

17

1 Introduction ................................................................................................................................... 17 Requirem ents.......................................................................................................................................................... for the OASTelnet Service 17

2 Overview ................................................................................................................................... of Features 17 Configurability .......................................................................................................................................................... 17 Direct Access.......................................................................................................................................................... to OAS 18 Security .......................................................................................................................................................... 18 Secure Sockets .......................................................................................................................................................... Layer 18 Term inal Em ulation .......................................................................................................................................................... 18

3 Configuring ................................................................................................................................... the OASTelnet Service 18 Service Options .......................................................................................................................................................... 19 User Profiles .......................................................................................................................................................... 21 Custom izing User .......................................................................................................................................................... Profiles 23 Generated Profiles .......................................................................................................................................................... 24

4 Starting, ................................................................................................................................... Stopping and Pausing OASTelnet 25 Controlling OASTelnet .......................................................................................................................................................... from OAS Adm in 26 Controlling OASTelnet .......................................................................................................................................................... from the Control Panel 26

3 OAS and Services

28

1 What................................................................................................................................... Is a Service? 28 2 Principal ................................................................................................................................... OAS Services 28 Basic Object Manager .......................................................................................................................................................... (oas_objm anager) 28 Shared Mem ory .......................................................................................................................................................... Manager (oas_shm anager) 29 Clean Up (oas_cleaner) .......................................................................................................................................................... 29

© 2012 Onsystex Inc.

Contents

5

3 Monitoring ................................................................................................................................... OAS Services 29 Log Files

.......................................................................................................................................................... 30

4 OAS and Memory

32

1 Windows ................................................................................................................................... Platforms and Shared Memory 32 2 OAS and ................................................................................................................................... Shared Memory 32 oas_shm anager .......................................................................................................................................................... and Shared Mem ory 32 oas_objm anager .......................................................................................................................................................... and Shared Mem ory 33 Self-Created Segm .......................................................................................................................................................... ents 33

5 Configuring Your OAS System

35

1 Configuration ................................................................................................................................... Procedure 35 1. Identify Disk .......................................................................................................................................................... Requirem ents 35 2. Identify Mem .......................................................................................................................................................... ory Requirem ents 35 3. Verify Version .......................................................................................................................................................... Com patibilities 35 4. Check/Reset .......................................................................................................................................................... System -Level Param eters 36 5. Check/Reset .......................................................................................................................................................... OAS Configuration Param eters 36 6. Define Peripherals .......................................................................................................................................................... w ithin OAS 36 7. Create OAS.......................................................................................................................................................... Accounts 36 8. Add Window .......................................................................................................................................................... s Users 37 9. Set Environm .......................................................................................................................................................... ent Variables 37 10. Review OAS .......................................................................................................................................................... Security 38 11. Convert Data .......................................................................................................................................................... Files 39 12. Review Backup .......................................................................................................................................................... Procedures 39

6 Starting and Stopping OASIS

41

1 Normal ................................................................................................................................... Operation 41 OAS Log Files.......................................................................................................................................................... 41 Starting & Stopping .......................................................................................................................................................... OASIS 42

2 Additional ................................................................................................................................... Commands 42 Stopping a User .......................................................................................................................................................... Process w ith deleteuser 42

7 Managing OAS Accounts

45

1 What................................................................................................................................... Is an OASIS Account? 45 2 Creating ................................................................................................................................... an OAS Account 45 3 Deleting ................................................................................................................................... an Oasis Account 47

8 Managing OAS Security

50

1 Customizing ................................................................................................................................... Permissions 50 2 Customizing ................................................................................................................................... a VOC File 51 Rem oving Entries .......................................................................................................................................................... 51

3 Customizing ................................................................................................................................... OASIS Behavior 53 4 Remote ................................................................................................................................... Items 53 5 The SETFILE ................................................................................................................................... Command 54 6 LOGIN ................................................................................................................................... and LOGOUT Paragraphs 54 7 Field-Level ................................................................................................................................... Security for OASQuery 56 Points to Rem.......................................................................................................................................................... em ber about Field-Level Security 56 © 2012 Onsystex Inc.

5

6

OASYS Administration for Windows 64 Bit Platforms The QUERY.PRIVILEGE .......................................................................................................................................................... File 56 OASQuery Processing .......................................................................................................................................................... 58 Turning on Field-Level .......................................................................................................................................................... Security 58

9 Managing OAS Files

61

1 OAS Hashed ................................................................................................................................... Files 61 2 Static................................................................................................................................... Hashed Files 61 3 Dynamic ................................................................................................................................... Hashed Files 62 Dynam ic Files.......................................................................................................................................................... and Overflow 62 When Dynam ic .......................................................................................................................................................... Files Are Created 64 Tips and Constraints .......................................................................................................................................................... for Creating a Dynam ic File 64 Dynam ic Files.......................................................................................................................................................... and Disk Space 65

4 Sequentially ................................................................................................................................... Hashed Files 69 The dat001 File .......................................................................................................................................................... 69 The over001 File .......................................................................................................................................................... 69 The gm ekey File .......................................................................................................................................................... 70

5 DIR-Type ................................................................................................................................... Files 71 6 Multilevel ................................................................................................................................... Directory Files 71 7 Index................................................................................................................................... Files and Index Log Files 72 Index-Related.......................................................................................................................................................... Files for a Static Hashed File 73 Index-Related.......................................................................................................................................................... Files for a Dynam ic Hashed File 73

8 File-Handling ................................................................................................................................... Commands 74 9 File Corruption ................................................................................................................................... 75 What Causes .......................................................................................................................................................... File Corruption? 75 Preventing File .......................................................................................................................................................... Corruption 76

10 OAS Detection ................................................................................................................................... Tools 76 oas_analyzetbls .......................................................................................................................................................... 76 oas_analyzetbls_ndx .......................................................................................................................................................... 79 oas_validatetbls .......................................................................................................................................................... 81

11 OAS Recovery ................................................................................................................................... Tools 82 oas_dum pgroup .......................................................................................................................................................... 82 oas_fixgroup .......................................................................................................................................................... 83 oas_fixtbls .......................................................................................................................................................... 84

12 Detection ................................................................................................................................... and Repair Examples 86 13 How to ................................................................................................................................... Use oas_analyzetbls 88 14 Error ................................................................................................................................... Messages 89 File Access Messages .......................................................................................................................................................... 89 Block Usage Messages .......................................................................................................................................................... 89 Group Header.......................................................................................................................................................... Messages 90 Header Key Messages .......................................................................................................................................................... 90 Other Header .......................................................................................................................................................... Messages 90 Free Block Messages .......................................................................................................................................................... 91 Long Record Messages .......................................................................................................................................................... 91 Dynam ic File Messages .......................................................................................................................................................... 92

10 Managing OAS Locks

94

1 The OASIS ................................................................................................................................... Global Lock Manager 94 How OASIS Global .......................................................................................................................................................... Locking Works 94 © 2012 Onsystex Inc.

Contents

7

2 Locking ................................................................................................................................... in OasBasic 95 How Locks Work .......................................................................................................................................................... 95 Locking Com m .......................................................................................................................................................... ands 95

3 Resource ................................................................................................................................... Locks 96 4 Listing ................................................................................................................................... Locks 97 LIST.READU .......................................................................................................................................................... 97 LIST.LOCKS .......................................................................................................................................................... 98 LIST.QUEUE .......................................................................................................................................................... 98 Param eters .......................................................................................................................................................... 99 LIST.QUEUE Display .......................................................................................................................................................... 99

5 Commands ................................................................................................................................... for Clearing Locks 102 SUPERCLEAR.LOCKS .......................................................................................................................................................... Com m and 102 SUPERRELEASE .......................................................................................................................................................... Com m and 102

6 Procedure ................................................................................................................................... for Clearing Locks 103

11 Managing OAS Users

106

1 Adding ................................................................................................................................... Users 106 User Groups.......................................................................................................................................................... 106 Hom e Directories .......................................................................................................................................................... 106 Logon Scripts .......................................................................................................................................................... 107

2 Monitoring ................................................................................................................................... User Processes 108 OAS Com m ands .......................................................................................................................................................... 108

3 Stopping ................................................................................................................................... User Processes 109 Using TIMEOUT .......................................................................................................................................................... 109

12 Managing Printers in OAS

112

1 Configuring ................................................................................................................................... and Troubleshooting a Printer 14-3 112 Physical Configuration .......................................................................................................................................................... 112 Troubleshooting .......................................................................................................................................................... 112 Definition in .......................................................................................................................................................... OAS 115 Default Printers .......................................................................................................................................................... 115

2 Spooling ................................................................................................................................... From OAS 115 The Spooling.......................................................................................................................................................... Process 115 OAS for Window .......................................................................................................................................................... s Platform s Specifics 115 Creating a Local .......................................................................................................................................................... Printer 116

3 Creating ................................................................................................................................... a Form 121 4 Defining ................................................................................................................................... a Printer Unit in OAS 123 Exam ples .......................................................................................................................................................... 126 Printing to the .......................................................................................................................................................... _HOLD_ File 128 Selecting a Spooler .......................................................................................................................................................... Mode 129 Redefining the .......................................................................................................................................................... Default OAS Print Unit 131 Subm itting Concurrent .......................................................................................................................................................... Print Jobs 131

5 OAS................................................................................................................................... Printing Commands 131

13 Managing Cataloged Programs

134

1 OasBasic ................................................................................................................................... Source and Compiled Programs 134 OasBasic Com .......................................................................................................................................................... piled Program s 134

2 Cataloging ................................................................................................................................... OasBasic Programs 134 © 2012 Onsystex Inc.

7

8

OASYS Administration for Windows 64 Bit Platforms Direct Cataloging .......................................................................................................................................................... 135 Local Cataloging .......................................................................................................................................................... 135 Global Cataloging .......................................................................................................................................................... 135

3 Managing ................................................................................................................................... Global Catalogs 136 Contents of .......................................................................................................................................................... a Global Catalog 136 Verifying a Program .......................................................................................................................................................... Version 138 Activating New .......................................................................................................................................................... ly Cataloged Program s and Subroutines 139

4 Listing ................................................................................................................................... Programs in Use 141 5 Creating ................................................................................................................................... an Alternate Global Catalog Space 142 Files and Directories .......................................................................................................................................................... Created by new hom e 142 Procedure for .......................................................................................................................................................... Creating an Alternate Global Catalog Space 144

14 Managing and Using Tape Devices

147

1 OAS................................................................................................................................... Tape Handling Commands 147 SETTAPE

.......................................................................................................................................................... 148

2 Steps ................................................................................................................................... for Tape Device Use 148

15 Monitoring and Tuning OAS

152

1 Monitoring ................................................................................................................................... Your Windows System 152 2 OAS................................................................................................................................... Performance Factors 152 Database Design .......................................................................................................................................................... Considerations 152 Using Alternate .......................................................................................................................................................... Key Indexes 152 Sizing Static .......................................................................................................................................................... Hashed Files 152 Sizing Dynam.......................................................................................................................................................... ic Hashed Files 153 OasBasic Coding .......................................................................................................................................................... Tips 153

3 OasBasic ................................................................................................................................... Profiling 154

16 Appendix A OAS Configuration Parameters

158

17 Appendix B Environment Variables for OAS

165

Index

0

© 2012 Onsystex Inc.

Part

1

10

1

OASYS Administration for Windows 64 Bit Platforms

Introduction This introduction provides an overview of the information in this manual and describes the conventions it uses.

1.1

About This Manual The purpose of this manual is to collect, in a single book, as much information as possible about activities needed to administer an OASYS installation on Windows platforms. This manual repeats some information presented elsewhere in the OASYS documentation set. Certain command descriptions and examples have been amplified or modified in this manual to increase their usefulness to system administrators as opposed to end users.

1.1.1

Audience Administering OASYS on Windows Platforms is intended for users whose responsibilities may include the following: Tasks performed at the Windows operating system level Modifying file permissions Adding users Creating directories Starting and stopping OASYS Backing up OASYS Tasks performed within OASYS Creating and managing OASYS accounts Optimizing OASYS configuration settings Customizing security Managing files Monitoring and accessing files, peripherals, and system resources

1.1.2

About the Product OASYS for Windows Platforms includes most of the features present in OASYS for Linux. Please read all the features carefully as some many not supported on OASYS for Windows Platforms

1.1.3

Unsupported Commands The following OASYS linux commands are not supported on OASYS for Windows platforms: oas_pickload oas_start oas_stop oasinstall

© 2012 Onsystex Inc.

Introduction

1.1.4

11

Reserved Characters OASYS for Windows platforms does not allow the use of the following characters in a file or directory name: “ (double quotation mark) | (pipe sign) * (asterisk) / (slash) : (colon) < (less than sign) > (greater than sign) ? (question mark) \ (backslash) You may use the reserved characters in a file specification. For instance, C:\Onsystex\oas61 \PDPSAMPLE\ORDERHISTORY is an acceptable file specification. The reserved characters : and \ are used as delimiters in the file specification. However, they may not be used within the name of a file or directory. TES:T or ORDER\HISTORY are unacceptable.

1.1.5

Case Sensitivity Windows platforms do not distinguish between uppercase and lowercase, except in a user’s password, which is case sensitive. OASYS is case sensitive.

File Names On Windows platforms, you cannot have two files whose names are identical except for case. For example, if your application creates files such as “aatemp” and “AATEMP”, you must modify the application since Windows platforms will not allow both to exist.

Record Names You cannot have two records in the same DIR or MULTIDIR file whose names are identical except for case. The following screen illustrates one effect of this limitation:

OASYS could not copy the LISTDICT record because a record called listdict already was copied. Since each record in a DIR (or MULTIDIR) file is an NTFS file, Windows platforms treat listdict and LISTDICT as the same file. You need to consider this limitation if your application: Creates records with names differing only in case in a DIR file or multilevel subdirectory. Copies records from a hashed file, where the limitation does not exist, into a DIR file or multilevel subdirectory. © 2012 Onsystex Inc.

12

OASYS Administration for Windows 64 Bit Platforms

Index Files and Index Log Files On OASYS for Linux, the index file and the index log file for a static hashed file are named X_filename and x_ filename, respectively. On OASYS for Windows platforms, the index file and index log file for a static hashed file are named X_FILENAME and L_FILENAME, respectively. Warning: The Windows operating system does not distinguish between X_filename and x_filename. If you copy an index file and an index log file to your Windows machine, Windows platforms may overwrite the first one you copied with the second, and you could lose information. When you are migrating your application, consider removing the index log files for your static files, or renaming them to the Windows platforms convention, before physically moving them to the Windows machine.

savedlists File By default, a OASYS account on Linux contains a SAVEDLISTS file for saving SELECT lists, and a savedlists file for storing temporary information for BY.EXP sorts. At the operating system level, the file named savedlists on OASYS for Linux is called the SAVEDLISTSL file on OASYS for Windows platforms. However, the VOC file contains an entry for savedlists pointing the correct file, so you should not have to modify your application. You must change the name of the savedlists file in any OASYS account you are moving from Linux to Windows platforms.

Note: Query verbs invoked in lower case will be treated in mode 'U'.

1.1.6

Symbolic Links Windows platforms, unlike Linux, do not support symbolic links. If your application has identified files by using symbolic links at the operating system level, you must restructure your OASYS accounts to eliminate them. You can use environment variables in VOC pointers, or set new pointers with SETFILE, just as you can in OASYS for Linux.

1.1.7

Phantom Command On OASYS for Windows platforms, the PHANTOM command behaves differently, depending from where you execute it. If you execute PHANTOM from a OASYS session at the console, then end the OASYS session, the phantom job completes. If you execute PHANTOM from a telnet session, the phantom job continues until it completes. This behavior matches the behavior of PHANTOM on Linux.

1.1.8

Dynamic Files The dynamic file implementation on OASYS for Windows platforms differs slightly from the implementation on OASYS for Linux. On OASYS for Windows platforms, the “parts” of a large dynamic file must remain in the same partition where the file was created. Because of this, the “part table” is not relevant to OASYS for Windows platforms. The size of each part file is limited by the configuration parameter OAS_MaxPartitionLength in OASHOME\include\oasconfig.

1.1.9

Deleting Files Windows platforms do not allow a process to delete a file if any other process has that file open. This operating system limitation significantly affects the behavior of the ECL DELETE.FILE command. To minimize the impact of this restriction, DELETE.FILE only removes the DICT portion and VOC entry for a file if it has successfully removed the DATA portion of the file. However, the operating system restriction still results in the following behaviors in OASYS: © 2012 Onsystex Inc.

Introduction

13

If one process executes DELETE.FILE filename, and another process has the DATA portion of filename open, or both the DICT and the DATA portions of filename open, the DELETE.FILE fails with an error, and no component of the file is deleted. If one process executes DELETE.FILE filename, and another process has only the DICT portion of filename open, the DELETE.FILE removes only the data portion of the file, leaving the VOC entry and the DICT portion intact, and displaying an error. In OASYS on Linux, DELETE.FILE would succeed in both cases. If your appli-cation depends on the Linux-style behavior, you need to rework the application.

1.1.10 PCPERFORM Command The OASBasic PCPERFORM command allows users to execute an operating system command from within a OASBasic program. In OASYS for Windows platforms, only MS-DOS commands can be executed with PCPERFORM. In some cases (for instance, the echo command) there are MS-DOS commands named like the Linux versions (although their behavior may differ somewhat). In other cases (for instance, who, ls, ps) you must identify replacements. Refer to your Windows platform and Linux documentation for information about system-level commands.

1.1.11 Shell Command Differences echo The MS-DOS echo command behaves differently from Linux in the following ways: Quotes are echoed. In Linux, the command echo ‘test’ displays the string test. In MS-DOS, echo ‘test’ displays ‘test’. In MS-DOS, echo displays the input starting from one space after the command on the command line, as shown in the following example:

Warning: In Linux, the three commands in the example are equivalent. If your application depends on comparing the output from echo to another string, make sure your echo command is formatted correctly. If you direct the output to a file, echo displays everything between its starting point and the redirection character (>). The two commands echo test>file and echo test >file, equivalent on Linux, are not equivalent on Windows platforms. The second command produces a 4-character string, with a space as the fourth character.

1.1.12 Use of Semicolon In Linux, the semicolon is recognized as a command separator, so users can enter multiple commands on a single command line. This functionality is lacking in MS-DOS. This particular operating system difference can cause © 2012 Onsystex Inc.

14

OASYS Administration for Windows 64 Bit Platforms

unexpected results. On Linux, the command line entry would echo the string abc to the file named file, then attempt to execute the dir command.

1.2

Notes About Terminal Devices and Tape Drives This sections discusses terminal and tape devices.

1.2.1

Terminal Devices OASYS for Windows Platforms records and displays a “tty” for a OASYS process. The tty is formed by appending the OASNO (from LISTUSER) to the string “pts/”. This tty can be used with the !portnumber option in the ECL MESSAGE command, to send a message to a specific terminal or window. A number of ECL commands (LISTUSER, MYSELF, WHO, and STATUS) display the tty number for each OASYS session.

1.2.2

Tape Devices When you use OASYS tape commands (for instance, SETTAPE), you must use the Universal Naming Convention (UNC) format for device identifiers. UNC names are in the form \\server\device. The following example shows the SETTAPE, T.ATT, and T.STATUS commands on OASYS for Windows Platforms:

The device identifier \\.\TAPE0 indicates the current server (.), device TAPE0. You can identify a disk file as a tape device by entering a path and file name (not in UNC format) on the SETTAPE command line. If you do not use UNC format, OASYS checks for a path and file that matches your entry. If the file exists, OASYS writes to the file as a “tape device”. Otherwise, SETTAPE fails with an error message.OASYS stores tape definition information in a file called OASHOME\sysprog\tapeinfo. This is a text file, which you can view with any text editor. You must log in as a member of the Administrators group to define a tape device with the SETTAPE command.

© 2012 Onsystex Inc.

Introduction

1.3

15

Printing in OAS for Windows Platforms Windows platforms allow users to print to printers (which are simply drivers that control print devices). A printer may control a network print device or a local print device. Microsoft applications, through their own print menus, allow users to incorporate printing options (like font selections, orientation, duplex mode, and so forth) within their application. Linux spoolers, on the other hand, allow users to select many of these options outside of their application, on the command line of the spooler. The Windows spooler allows users to write data, including device-specific escape sequences, to a print device (RAW mode), or to incorporate pre-defined printing options (WINDOW) mode. Within a OASYS session, the SETPTR command identifies a print unit with a default spooler mode of RAW. If the output from your application contains escape sequences for formatting, you do not need to specify printing options when you define a print unit with SETPTR. If you are not using escape sequences, you can specify printer options in a quoted string on the SETPTR command line. OASYS then passes that information to the Windows spooler.

© 2012 Onsystex Inc.

Part

2

Managing and Using the OASTelnet Service

2

17

Managing and Using the OASTelnet Service The OASYS Telnet Service (OAS Telnet) enables multiple users to log on to a single Windows platform to run OASYS. With the OASYS Telnet Service installed and started, your Windows platform exports a logon prompt to its network so that network users can log on and run OASYS. For SSL connectivity Onsystex SSL Telnet Server is available as an add-on product.

2.1

Introduction The OASYS Telnet Service is a service that exports a logon prompt to a network. Users can log on through the logon prompt, and multiple users can work on the system at the same time. OAS Telnet creates an alternate console window when a user runs programs other than OASYS in that window, just as they would run in a console window. When a user opens a OASYS session through OAS Telnet, OASYS writes screen output directly to a socket. Using the socket is more efficient than writing screen output to the alternate console window. When a user “shells out” from OASYS to execute a non-OASYS process (for instance, !DIR), OASYS directs output to the alternate console window. This allows programs that write to “standard output” to function without modification under OAS Telnet.

2.1.1

Requirements for the OASTelnet Service This sections describes the requirements for the using the OAS Telnet service.

Operating System Your system must be running a 64 bit Microsoft Windows operating system.

Disk Space OAS Telnet uses less than one megabyte of disk space. During the installation process, OASYS installs the files for OAS Telnet in the Telnet subdirectory in your \oas61\bin folder.

Memory The OASYS Telnet service and configuration screens take less than one megabyte of system memory to run. You need somewhat less than 1 MB of memory for every Telnet user logged into your system, over and above the memory required for the application.

Telnet Client You must have a Telnet client running on your Windows system. The OAS Telnet Service interacts with the existing Telnet client.

2.2

Overview of Features This section describes the features of the OAS Telnet Service.

2.2.1

Configurability local Administrators group to configure the OAS Telnet Service. You can perform the following tasks to configure the OAS Telnet Service:

© 2012 Onsystex Inc.

18

OASYS Administration for Windows 64 Bit Platforms

Establish a default configuration for all users who access your system through OAS Telnet. Create individual user profiles that establish session characteristics for each user. Create a combination of custom profiles and a default configuration. Set parameters, including the number of concurrent OAS Telnet sessions and the number of logon attempts to allow each user. Make tuning changes that may affect performance for users logging in via OAS Telnet to execute MS-DOS commands.

2.2.2

Direct Access to OAS You can configure the OASYS Telnet Service so that users never see the Windows command prompt. Users can log directly on to OASYS, or on to a custom application.

2.2.3

Security Users cannot log on through the Telnet Service unless: They have a valid logon on the Windows workstation or domain. They belong to a local group that has the user privileges Access this computer from network and Log on locally assigned. These constraints mean that users logged on through Telnet have only the permissions already associated with their Windows system account, just as if they had logged on from the console.

2.2.4

Secure Sockets Layer For Secure Sockets Layer (SSL) connectivity , use the Onsystex SSL Telnet Server product.

2.2.5

Terminal Emulation The OASYS Telnet Service provides any terminal emulation supported by OASYS. OASYS uses the oastermcap file to validate terminal settings. The oastermcap file, located in the OASHOME\include directory, contains definitions for terminals supported within OASYS. By default, the oastermCAP file contains definitions for the following terminals: VT100, VT200, VT300, VT400, VT420 WYSE60 ADDS-VP IN 9400 IN 9400B You can add terminal definitions to oastermcap, or modify the definitions, if you desire.

2.3

Configuring the OASTelnet Service Note: You need to log in to the Administrator account or log on as a member of the local Administrators group to configure the OAS Telnet Service.

© 2012 Onsystex Inc.

Managing and Using the OASTelnet Service

19

You configure the OASYS Telnet Server by executing the oas_ConfigTelnet.exe utility.

The OAS Telnet Server dialog box appears, as shown in the following example:

The following table describes the dialog tabs for Telnet Server. Dialog Tab

Use

Services

Settings for maximum log on attempts, log on pause, log on timeout, termination pause, telnet port number and log on banner. Allows you to specify a list of users that are allowed to connect to your Windows platform through OAS Telnet. Telnet S erver Dialog Tabs

Users

2.3.1

Service Options Select the Service tab from the Telnet Server dialog box to view and edit parameters that govern the operation of the OAS Telnet Service. A dialog box similar to the following example appears:

© 2012 Onsystex Inc.

20

OASYS Administration for Windows 64 Bit Platforms

Set Telnet Port Set the telnet port number that the OAS Telnet service should monitor for client connections. The default value for the Telnet Port Number is 23. Onsystex recommends that you not change this unless you have another service that requires socket 23. Tip: In the TCP/IP protocol stack, certain sockets are reserved for specific services. The file %systemroot% \system32\drivers\etc\services on your Windows platform contains a partial listing of reserved sockets, excerpted from Internet RFC1060. Use the listing as an aid to identify available sockets.

Set Connection Parameters Max Login Tries In the Max Login Tries box, enter the maximum number of attempts a user is allowed to enter a logon ID and password. Use the Max Login Tries arrows to choose the number of times. The default is 5.

Welcome Message In the Welcome Message box, enter a message to display when a user successfully connects to OAS Telnet.

Starting, Stopping, and Pausing the Telnet Server To start and stop the OAS Telnet Server, use the Service manager in the Windows Control Panel Administration.

© 2012 Onsystex Inc.

Managing and Using the OASTelnet Service

21

Click OK to save the new settings and exit the Telnet Server dialog box. Click Apply to save the new settings and keep the Telnet Server dialog box open. Changed settings do not affect Telnet sessions that are already started. New sessions started after the service parameters were changed use the new parameters. Click Cancel to exit the Telnet Server dialog box without saving changes.

2.3.2

User Profiles Select the Users tab to specify which users are allowed to connect to your system through OAS Telnet, and to create custom user profiles. A dialog box similar to the following example appears when you click the Users tab:

This dialog box enables you to specify a list of users that are allowed to connect to your Windows system through OAS Telnet. At installation, OAS Telnet is started with a default configuration that allows any user who © 2012 Onsystex Inc.

22

OASYS Administration for Windows 64 Bit Platforms

can access your Windows system from the network to access the system through OAS Telnet as well. This default behavior is acceptable in many instances. However, administrators may wish to grant only certain users Telnet access, or to create individual user profiles. The Users dialog box allows this flexibility. Warning: If you remove the Default profile, no user can log on through OAS Telnet unless you have created a specific profile for the user.

Default User Profile When you first display the Users dialog box, you see an entry for DEFAULT in the User box. Highlight DEFAULT and click Edit to display the default profile. The following example illustrates a sample default profile.

Command In the Command box, enter the full path of an executable. In the default profile, this is set to OASBIN\oas.exe, which starts a OASYS session

Initial Directory Enter the full path of the working directory to which you want to connect when you log on in the Startup Directory box. In the default profile, this is set to the OASYS demo account.

Command Arguments (shown as 2nd Command) In the Command Line box, enter any arguments you want to pass to the default shell. In the default configuration, this is blank.

ANSI Version 3.x Select the ANSI Version 3.x check box if you want to enable faster screen refreshes for terminals that support ANSI 3.x color. By default, this check box is not selected.

Use Redir Characters Select the Use Redirection Chars check box if you want to map unprintable characters to printable characters. By default, this check box is selected.

Ask Directory ? Select the Ask Directory ? check box if you want the user to select a working directory when they log on. By default, this check box is not selected. Note: If you want one or more users to see the MS-DOS prompt when they log on, edit the user profile or

© 2012 Onsystex Inc.

Managing and Using the OASTelnet Service

23

profiles so that the default shell is %systemroot%\system32\cmd.exe. Click OK to return to the Telnet Server dialog box, or click Cancel to exit without saving changes.

2.3.3

Customizing User Profiles Complete the following steps to create a customized profile for a user. 1. Add a Profile

Click New to add a user profile. The following dialog box appears:

Enter the logon name of the user, then click OK. Enter the logon name only (for instance, main_user). Do not enter the domain name (for instance, do not enter PARTS\main_user). When you click OK, a dialog box similar to the following appears:

OASYS populates the dialog elements with the values from the Default Configuration. Click OK to accept those values, or edit one or more fields to customize the profile. Note: If you deleted the Default profile, OASYS displays a message when you attempt to add new user profiles. You must enter all the configuration settings manually, since OASYS cannot copy them from the default profile. 2. Customize a Profile

To edit a profile, highlight the user name in the User box, then click Edit. Consider the following points when customizing a user profile: Specify a full path in the Conmand box. You can use either drive letters or the Universal Naming Convention (UNC) to specify the path.

© 2012 Onsystex Inc.

24

OASYS Administration for Windows 64 Bit Platforms

By specifying the Initial Directory, you can direct different users to different startup directories, even if they are using the same default shell. You can allow users to choose their directory when they log on by selecting the Ask Directory ? check box. If you do not know whether a particular terminal supports Version 3 Color, select the ANSI Version 3.x check box. Test the terminal; if screen colors are not displayed correctly, modify the user profile to clear the ANSI Version 3.x check box. The following example shows a sample configuration that allows a user to log on through OAS Telnet, select a starting directory, and access the MS-DOS command prompt. The default startup directory is C:\Onsystex\oas61 \sysprog.

Changes to a user’s configuration are visible the next time the user logs in through OAS Telnet.

2.3.4

Generated Profiles If you selected Prompt Directory in your Default Profile, OASYS creates a profile for each user who would normally receive the default user profile. OASYS creates the individual profiles the first time a user chooses a startup directory different from the default. The generated profile uses the same configuration settings as the default profile, with the exception of Startup Directory, which is set to the directory chosen by the user when they log on. The following examples show the effect of the Prompt Directory option. In the first example, the default user profile has Prompt Directory selected:

© 2012 Onsystex Inc.

Managing and Using the OASTelnet Service

25

Notice that the default path is C:\Onsystex\oas61\sysprog, and the user is selecting an alternate startup directory, \Onsystex\oas61\FirstAccount. Pressing ENTER starts a OASYS session in \Onsystex\oas61 \FirstAccount. This logon session also creates a profile for the user, which you can view or edit from the Telnet Server dialog box. The generated profile is shown in the following example:

The next time the user logs on through Telnet, the default path is changed accordingly.

2.4

Starting, Stopping and Pausing OASTelnet You can control the OAS Telnet service from the OAS Telnet Configuration dialog box or from the Control Panel. Note: Pause and Stop have the same functionality. Once a user logs on through Telnet, their process is not affected by Pause or Stop. Pause and Stop both prevent additional users to log on through Telnet.

© 2012 Onsystex Inc.

26

2.4.1

OASYS Administration for Windows 64 Bit Platforms

Controlling OASTelnet from OAS Admin You can start, stop, or pause the OAS Telnet Server Service from the Service tab in the Telnet Server dialog box. Click Stop to stop the OAS Telnet Service. Users already logged on can continue to work, but no additional users can log on through OAS Telnet until you Start the service. Click Start to start the OAS Telnet service (if it is stopped) or continue the service (if it is paused). Click Pause to pause the OAS Telnet service. Users already logged on can continue to work, but no additional users can log on through OAS Telnet until you Start the service.

2.4.2

Controlling OASTelnet from the Control Panel You can start, stop, or pause the OAS Telnet Service from the Control Panel. Select the Services icon from the Control Panel, and scroll through the list of services to display OASYS Telnet Service. The Status column indicates whether the service is presently running, and the Startup column indicates whether the service is started automatically when you start your system. The following example shows the appearance of the Services window:

Notice the following points: The OASYS Telnet Service 6.1 is started. The OASYS Telnet Service starts automatically when you start your system. This is the default configuration when you install OASTelnet. You can click Stop or Pause to stop or pause the service. Click Startup to switch between manual and automatic startup for the service. Note: If you Pause the OASYS Telnet Service from Control Panel, click Continue to resume the service. This is a difference in the interface from the Telnet Server dialog box.

© 2012 Onsystex Inc.

Part

3

28

3

OASYS Administration for Windows 64 Bit Platforms

OAS and Services This chapter explains what services are, and describes services specific to OASYS.

3.1

What Is a Service? A service is a background process that performs a specific task or set of tasks. Services wait in the background until they receive a request for their specific function. A number of standard Windows services run to control system processes, schedule commands, handle print requests, and to perform other similar functions. Consult your host operating system documentation for detailed information about the services that run on your system.

3.2

Principal OAS Services OASYS Database services control your OASYS environment. When a user starts a OASYS session, the user’s process, called a oas, communicates with the services. The oas process runs with the permissions valid for the user, preventing inappropriate file access by the OASYS services. Lock tracking- oas_shmanager records all OASBasic locks and semaphore locks, identifying which OASYS user holds each. Process cleanup- At periodic intervals, the oas_cleaner service checks to see if terminated process flags have been set. If oas_cleaner detects a terminated process flag, it deletes the associated process from internal tables, removes any requests from the queue, and removes any messages sent to the terminated process. If oas_cleaner receives a message from a process, it checks to see if the message was sent from a terminated process. If so, it throws away the message.

3.2.1

Basic Object Manager (oas_objmanager) The Basic Object Manager, manages shared memory used by globally cataloged OASBasic programs. OASYS starts oas_objmanager when you execute oas_start and stops it when you execute oas_stop. The functions of oas_objmanager include: Loading and tracking globally cataloged programs- oas_objmanager loads globally cataloged programs into shared memory as needed, and keeps track of the programs loaded and the number of processes executing each one. When a user executes a globally cataloged program, oas_objmanager checks in shared memory, then takes the following actions: If the program is already loaded, oas_objmanager increments the counter for the number of users executing it, and tells the oas process which segment to attach to execute the program. If the program has not been loaded, oas_objmanager loads the program into shared memory and starts a counter for it. Periodically, oas_objmanager checks shared memory and removes loaded programs that are no longer in use. Controlling shared memory- The oas_objmanager daemon can attach up to 20 shared memory segments. The maximum size of each segment for oas_objmanager is determined by the OASYS configuration parameter OAS_MaxCatalogBytes. oas_objmanager attaches segments as it needs to load globally cataloged programs, and releases memory back to the operating system when it is no longer needed. Process cleanup- At periodic intervals, the oas_objmanager process checks the oas_cleaner service to see if terminated process flags have been set. If oas_objmanager detects a terminated process flag, it removes all messages sent for the process. If the terminated process is the only process using a program in shared memory, it removes the program from shared memory. oas_objmanager uses the process ID to determine if a message it receives is from a terminated process. If so, oas_objmanager discards the message.

© 2012 Onsystex Inc.

OAS and Services

3.2.2

29

Shared Memory Manager (oas_shmanager) The shared memory manager, oas_shmanager, builds and manages structures and tables within shared memory. OASYS starts oas_shmanager when you start the OASYS Database Service, and stops it when you stop the OASYS Database Service. OASYS processes (OAS processes) communicate with oas_shmanager to request and return shared memory. The OASYS processes request shared memory from oas_shmanager for the following tasks: License control- The oas_shmanager process tracks the number of users for which a site is licensed, and prevents more than that number of users from logging on to OASYS. oas_shmanager also displays warning messages when a license is about to expire. User process tracking- When a user logs on to OASYS, oas_shmanager assigns an internal tracking number to the user’s process and records information about the process in tables within OASYS. Buffering program variables. Storing query records and intermediate results. Storing select lists. Storing expression buffers. Managing a current modulo table for dynamic files. Process cleanup- At periodic intervals, the oas_shmanager process checks the oas_cleaner service to see if terminated process flags have been set. If oas_shmanager detects a terminated process flag, it checks all ipc IDs. If one of the ipc IDs is invalid, oas_shmanager exits, bringing down OASYS. oas_shmanager also checks all process groups to see if the services terminated abnormally. If so, oas_shmanager removes all self-created shared memory pieces and reclaims all global pages occupied by the terminated group. oas_shmanager also corrects any inconsistencies that may have occured if an update was terminated. The Onsystex Application Server Service starts oas_shmanager, which creates a control table (CTL) in shared memory. The CTL tracks all information about the shared memory segments that oas_shmanager manages. The size of the CTL is related to the number of users on the system and to a series of configuration parameters.

3.2.3

Clean Up (oas_cleaner) The clean up process, oas_cleaner, detects terminated user processes at check time intervals. If oas_cleaner detects a terminated process, internal flags are set. The oas_shmanager and oas_objmanager services periodically check to see if oas_cleaner has set internal flags. If these services detect flags, each service performs the necessary clean up and resets its own flag to zero. The oas_cleaner service performs clean up that is not handled by oas_shmanager or oas_objmanager. When the oas_shmanager and oas_objmanager services have reset their flags to zero, the oas_cleaner service resets its flag to zero, makes the user process ID available, and frees the local control table.

3.3

Monitoring OAS Services To monitor OASYS services, click the Start menu, point to Settings, click Control Panel, and then double-click Services. A window similar to the following appears:

© 2012 Onsystex Inc.

30

OASYS Administration for Windows 64 Bit Platforms

In the previous example, the OASYS Database Service, RPC Server and Telnet Service are all started. Automatic in the Startup column indicates that these services automatically start when you boot your Windows system.

3.3.1

Log Files The oas_objmanager, oas_cleaner, and oas_shmanager services each record messages in a pair of logs in the OASBIN directory. In addition, the oas process writes messages to a log file called oas.errlog if a OASYS process encounters file corruption in a data file. The following table lists these log files. Daemon/Process oas_shmanager oas_shmanager oas_objmanager oas_cleaner oas oas_start

Routine Messages Error Messages OASBIN/oas_shmanager.log OASBIN/oas_shmanager.errlog OASBIN/oas_shmanager.log OASBIN/oas_shmanager.errlog OASBIN\oas_objmanager.log OASBIN\sbsc.errlog OASBIN\oas_cleaner.log OASBIN\oas_cleaner.errlog N/A OASBIN\oas.errlog OASBIN\oas_start.log OASBIN\oas_start.errlog Log Files for OAS YS Daemons and Processes

Note: All messages written to the .errlog for a daemon are also written to the daemon log file. For example,if an error is written to the oas_shmanager.errlog, the message also appears in the oas_shmanager.log.

The oas.errlog file If a OASYS process encounters file corruption in a data file during processing, OASYS writes a message to the oas.errlog in OASBIN. System administrators can monitor this log and take corrective action for the specified file. The following example illustrates errors printed to the oas.errlog when a SELECT statement is executed against a corrupt file

© 2012 Onsystex Inc.

Part

4

32

4

OASYS Administration for Windows 64 Bit Platforms

OAS and Memory This chapter describes how to configure, attach, and release shared memory.

4.1

Windows Platforms and Shared Memory Shared memory is a region of memory that more than one process can access. Shared memory resides on a Windows system outside the address space of any process. It is partitioned into segments. As a process requires memory, the process attaches a segment to its own address space. Processes use systemlevel calls to create, attach, and release shared memory segments.

4.2

OAS and Shared Memory OASYS interacts with shared memory by using system-level calls, OASYS services, and OASYS configuration parameters to build its own structures in shared memory. OASYS defines shared memory segments that can be attached by OASYS processes. The oas_objmanager (Basic Object Manager) service creates shared memory structures for storing active globally cataloged OASBasic programs. The oas_shmanager (shared memory manager) service creates shared memory structures for internal tables required by OASYS processes. OASYS processes request memory for: Buffering OASBasic variables Storing intermediate results Storing a current modulo table for dynamic files

4.2.1

oas_shmanager and Shared Memory The shared memory manager (oas_shmanager) creates shared memory segments as needed. The size and characteristics of segments oas_shmanager or the OASYS Database Service create are determined by OASYS configuration parameters. Whenever OASYS starts, it reads the oasconfig file located in OASHOME\include and stores these values in shared memory. oas_shmanager subdivides each of its segments into global pages, and subdivides each global page into local pages. oas_shmanager also creates and maintains internal tables that track the use of the structures it creates. These internal tables, stored in shared memory structures, allow oas_shmanager to protect shared memory pages against accidental overwriting, and to optimize the efficiency of memory use by releasing unneeded shared memory pages back to the operating system.

Displaying Parameter Settings Use the OASYS system-level command oas_showmem -h to display the current settings for configuration parameters related to shared memory.

Note: See “Appendix A OASYS Configuration Parameters,” for further information about these parameters.

© 2012 Onsystex Inc.

OAS and Memory

4.2.2

33

oas_objmanager and Shared Memory oas_objmanager creates structures in shared memory as needed for storing active globally cataloged OASBasic programs. The limits for structures created by oas_objmanager are different from those for oas_shmanager. The following table describes two oasconfig parameters that control the size of oas_objmanager segments. Configuration Parameter OAS_M axCatalogBytes

Description Size, in bytes, of shared memory segments created by oas_objmanager. oas_objmanager uses the segments to store globally cataloged programs. oas_objmanager can attach a maximum of 20 segments. OAS_M axSizeBasicObject M aximum size, in bytes, of object code files that oas_objmanager can be load into shared memory. oas_objmanager loads object code files larger than this size into the user’s address space instead of shared memory. Configuration Parameters for oas_objmanager

4.2.3

Self-Created Segments A OASYS process can attach a segment of shared memory larger than a standard global page. OASYS requires that a OASBasic variable read into memory be contained in a single global page. If a variable is larger than the size of a global page, oas creates a special segment in shared memory. These “self-created” segments, also called “indirect” segments, are attached to the requesting oas process and managed by oas_shmanager. Some circumstances resulting in self-created segments are: Editing a large report with AE. AE is a OASBasic program, and it reads a report in as a single variable. Reading a large array as a single variable. oas_shmanager creates a segment large enough to hold the variable. The self-created segment is counted as a global page used by the OASYS process that created the segment. Warning: Creating these segments of memory is not an efficient resource use, and may result in poor performance or in thrashing. Use the system-level lstt command or the oas_ipcstatus command to determine if your application is using self-created segments on a regular basis. If so, analyze the sizes of variables the application uses. Consider increasing the value of OAS_BytesperPage (the size of a global page) to handle the variables. Also, consider modifying the application to read arrays by element rather than as a single variable.

© 2012 Onsystex Inc.

Part

5

Configuring Your OAS System

5

35

Configuring Your OAS System This chapter outlines configuration considerations that may be appropriate when you first implement OASYS or when you make major changes to your system. Major changes include adding or reconfiguring hardware, installing a new software application, or upgrading or relicensing OASYS. This chapter does not present detailed information, but outlines the considerations and refers you to sources of additional information.

5.1

Configuration Procedure If you are installing or upgrading OASYS, see Installing and Licensing OASYS Products for estimates for initial disk and memory needs for your system. These estimates should be sufficient to allow you to install and start OASYS with a minimal configuration.

5.1.1

1. Identify Disk Requirements The initial estimates in Installing and Licensing OASYS Products should allow you to install and run OASYS. However, we recommend that you evaluate your system, including your operating system, your hardware configuration, and your application, to develop accurate disk space requirements. Onsystex offers the following suggestions. Disk Requirements- Use the largest expected size for your data files to estimate how much disk space you need. In certain applications, such as financial applications, the number of records varies in a predictable way over time. Your system must have enough disk space to handle the maximum number of records without difficulty. Disk I/O- For best results, configure your disk system so that access is balanced across all devices. Onsystex suggests the following: \TEMP directory- Locate your \TEMP directory on a different physical drive from your data for improved performance. OASYS accounts- If your application uses more than one OASYS account, locate the account directories on separate drives to distribute load.

5.1.2

2. Identify Memory Requirements The initial estimates in Installing and Licensing OASYS Products should allow you to install and run OASYS with a minimal configuration. However, memory requirements can be platform dependent as well as application dependent. Estimate the memory required for the following components of your application: The memory segments controlled by oas_shmanager The memory segments controlled by oas_shmanager The memory segments for oas_objmanager See Chapter 6, “OASYS and Memory,” for information about estimating memory needs.

5.1.3

3. Verify Version Compatibilities If you are considering major upgrades to your hardware or to your operating system, consult your Onsystex account representative early in your planning process to determine if your current OASYS version is supported

© 2012 Onsystex Inc.

36

OASYS Administration for Windows 64 Bit Platforms

by the hardware or software you are considering.

5.1.4

4. Check/Reset System-Level Parameters Depending on your version of Windows, you may or may not be able to modify system-level parameters directly. You may need to adjust the following categories of parameters when you first implement OASYS: Memory- Review parameters that limit the number of shared memory segments system-wide, the maximum and minimum size of a segment, and the maximum number of segments per process. See Chapter 6, “OASYS and Memory,” for additional information. Files and Users- Review parameters that define the maximum number of open files and file locks supported system-wide, the maximum number of files per user process, and the maximum number of user processes the system can support at one time. ipc Facilities- Review parameters that define the number and size of message queues, the number of semaphore sets and semaphores, and the number of semaphore undo structures your system supports.

5.1.5

5. Check/Reset OAS Configuration Parameters The OASYS oasconfig file, located in OASHOME\include, contains a set of parameters that are given default values when you install OASYS. When you start a OASYS session, OASYS sets environment variables for each value in the oasconfig file. Note: The oasconfig file is always located in OASHOME\include. Do not move the directory to another location, or OASYS will not run. The oasconfig file enables you to define values for each parameter that applies to your OASYS environment. You can adjust most oasconfig parameters for your environment, but some should not be changed. Refer to “Appendix A OASYS Configuration Parameters,” for detailed information about each oasconfig parameter. You must log in as Administrator to modify oasconfig parameters.

5.1.6

6. Define Peripherals within OAS You must define tape devices, printers, and line devices within OASYS before you can access them from OASYS. Before defining a device within OASYS, make sure that it is properly installed and functioning in your Windows environment. Refer to your operating system documentation for information about setting up peripherals on your system. Use the ECL SETTAPE, SETLINE, and SETPTR commands to define your peripherals to OASYS. See Chapter 14, “Managing Printers in OASYS,” and Chapter 16, “Managing and Using Tape Devices,” for additional information.

5.1.7

7. Create OAS Accounts When you implement OASYS, you may need to create one or more OASYS accounts for your application. A OASYS account is a directory that contains a OASYS VOC file and its dictionary. The VOC file identifies commands, paragraphs, and all data files that are used in the OASYS account. The data files may be in the same directory as the VOC file, or the VOC file may contain pointers to data files in other file systems. Your system may have a single OASYS account or several, depending on your application.

© 2012 Onsystex Inc.

Configuring Your OAS System

37

Note: A Windows account (logon ID, password) is not the same as a OASYS account. Every OASYS user should have a separate Windows account (logon ID and password), but many users can access the same OASYS account. Use the Windows platform mkdir command and the OASYS system-level oas_newacct command to create OASYS accounts. See your host operating system documentation for information about the mkdir command, and see Chapter 9, “Managing OASYS Accounts,” for information about the oas_newacct command.

5.1.8

8. Add Windows Users Accessing OASYS requires each user to have a logon ID and password on your Windows system. Onsystex recommends you create a separate Windows account for each OASYS user. See your host operating system documentation for detailed information on creating Windows accounts. See Chapter 10, “Managing OASYS Security,” for OASYS-specific information.

5.1.9

9. Set Environment Variables You do not have to set the OASHOME and OASBIN environment variables on Windows platforms, unless your OASHOME and OASBIN directories differ from those defined in the Registry. A user wishing to access OASYS using a different OASHOME and OASBIN than those defined in the Registry must have two environment variables set: OASHOME and OASBIN. The settings you assign for these variables depend on whether you performed a basic or an advanced OASYS installation. See Installing and Licensing OASYS Products for information about installation types. OASHOME- This variable identifies the path of the OASYS “home” directory. The home directory contains subdirectories OASYS needs for processing. OASBIN- This variable identifies the path for the directory that contains OASYS executables. By default, OASBIN is a subdirectory under OASHOME.

Setting OASHOME and OASBIN You can add commands to set these environment variables to each user’s profile, if the user is accessing OASYS with a different OASHOME or OASBIN than defined in the Registry. Use the following commands to set these variables: set OASHOME \directory-name set OASBIN \directory-name set PATH \directory-name You can also set environment variables from the System window. From the Start menu, click Control Panel, and then double-click System. Click the Advanced tab, then click Environment Variables. A dialog box similar to the following example appears:

© 2012 Onsystex Inc.

38

OASYS Administration for Windows 64 Bit Platforms

Enter the name of the environment variable you want to establish or change in the Variable box. Enter the setting for the environment variable in the Value box. Click Set to set the variable, or Delete to delete the variable.

Setting Additional Environment Variables “Appendix B Environment Variables for OASYS,” lists an additional set of variables that are significant for OASYS users. These can be set in the same manner as the environment variables in the previous example before entering OASYS. Note: While you are in a OASYS session, you cannot change environment variables for that session.

5.1.10 10. Review OAS Security Depending on your application, you may need to implement additional measures to ensure data security and separation of duties. Review your application and implement any or all of the following: Default Permissions- Modify the default permissions for OASHOME and its contents that were set when you installed OASYS. Users and domains- Assign OASYS users to separate domains, and set permissions on your database so that each group of users has access to the data they need. VOC file- Customize your VOC file to limit access to powerful commands. Remote entries- Use remote pointers to files and commands to allow more fine-grained protection. Query Privileges- For OASQuery access, use the QUERY.PRIVILEGE file. See Chapter 10, “Managing OASYS Security,” for additional information.

© 2012 Onsystex Inc.

Configuring Your OAS System

39

5.1.11 11. Convert Data Files Depending upon the nature of your system change, you may need to perform some conversion of OASYS hashed files. Consider the following: RDBMS Integration- OASIS provides seamless integration with RDBMS Tables providing the same functionality support as if these were hashed native files. If you are migrating your hashed data files to normalized storage forms or need to integtrate with external RDBMS data sources, please refer to the "OASYS RDBMS Integration Guide" for additional information. File characteristics- OASIS also offers you the capability to convert files from static to dynamic, change file characteristics such as block size and modulo, change hashing algorithm for a static file, and change file format between high-byte and low-byte formats. See Chapter 11, “Managing OASYS Files,” and the OASYS Commands Reference for additional information.

5.1.12 12. Review Backup Procedures Special considerations are needed to back up OASYS accounts. Make sure your backup procedures have the following capabilities: Subdirectories- Your backup procedure should be able to back up at least three levels of subdirectories. This is required to support OASYS MULTIDIR and MULTIFILE files. Backing up selected files - Your backup procedure should allow you to input a list of files to back up. This is required to support full backups of OASYS accounts. Simply backing up the directory that contains the VOC file may be insufficient, since data files are not necessarily located in the same directory as the VOC file. The ECL SETFILE command creates VOC entries with pointers to files in other locations. However, backup utilities may not follow these SETFILE pointers. To create a complete backup of an account, you need to make sure you back up and verify each physical file associated with the account.

© 2012 Onsystex Inc.

Part

6

Starting and Stopping OASIS

6

41

Starting and Stopping OASIS This chapter describes procedures for normal startup and shutdown of OASYS, and also describes commands used to log out users, stop processes, and remove ipc facilities, if needed. These commands are also documented in the OASYS Commands Reference.

6.1

Normal Operation Use the OASYS services for normal startup and shutdown. These commands start and stop the oas_objmanager, oas_cleaner, and oas_shmanager processes, in the correct order. Note: You must log on as Administrator to manage the OASYS services.

6.1.1

OAS Log Files oas_start makes entries in the log files (oas_shmanager.log, oas_objmanager.log, and oas_cleaner.log) that identify the system resources used by the daemons. The following example is a sample oas_objmanager.log:

The next example shows a sample oas_shmanager.log:

The next example is a sample oas_cleaner.log:

© 2012 Onsystex Inc.

42

6.1.2

OASYS Administration for Windows 64 Bit Platforms

Starting & Stopping OASIS Use Control Panel > Administration > Services to start and stop OASYS

6.2

Additional Commands OASYS provides a number of system-level commands to assist you in clearing users, processes, and system resources from OASYS if needed. These commands are intended for removing hung processes, clearing ipc facilities for a clean start of OASYS, or logging users and resources off for an emergency shutdown. These commands are listed in the following table. Parameter

Description

listuser oas_removeuser

Lists all current OASYS users. Forces a user out of OASYS and removes the user’s entry from the internal tables. Lists all ipc structures in use on the system; identifies those used by OASYS processes.

oas_oas_ipcstatus

OAS YS S ystem-Level Commands

Warning: Notice that oas_removeuser may compromise the integrity of your data. You should never use them as a routine substitute for normal user logoff.

6.2.1

Stopping a User Process with deleteuser The oas_removeuser command first tries to kill the oas process by sending OASYS an internal signal equivalent to the Linux kill -15 command. If this signal is unsuccessful after five seconds, it uses the Win32 API Terminate Process to kill that process. Syntax: oas_removeuser pid © 2012 Onsystex Inc.

Starting and Stopping OASIS

43

The argument pid is the process ID. Warning: Because oas_removeuser may execute the Terminate Process, it is particularly important that you verify the pid carefully. The following screen shows an example of the oas_removeuser command:

C:\Onsystex\oas61\Bin>oas_listu Efective users..: 8 /8

oas 1

oasSql Total 0

1

O ASN O U SR N B R U ID U SR N AM E U SR TY PE TTY 1 48056 197608 M ario oas pts/1 Console

IP-AD D R ESS TIM E D ATE 11:35:49 27 Sep 2011

C:\Onsystex\oas61\Bin>oas_removeuser 48056

Note: You must log on as Administrator to execute oas_removeuser

© 2012 Onsystex Inc.

Part

7

Managing OAS Accounts

7

45

Managing OAS Accounts This chapter describes OASYS accounts and describes procedures used to create, save, and clear the accounts.

7.1

What Is an OASIS Account? A OASYS account is a directory that contains a default set of OASYS files, including a VOC file and its dictionary. Note: The system-level oas_newacct command creates the default files OASYS requires for an account. The VOC file identifies commands, paragraphs, and all data files that are used in the OASYS account. The data files may be in the same directory as the VOC file, or the VOC file may contain pointers to data files in other directories. Your system may have a single OASYS account, or several, depending on your application. Note: A Windows account typically means a logon ID, its associated password, and its default directory. There is no direct relationship between OASYS accounts and Windows accounts (logon IDs). Many Windows users may access any OASYS account. A Windows user’s default directory does not have to be (and usually is not) a OASYS account.

7.2

Creating an OAS Account There are three steps required to create a OASYS account: 1. Use the MS-DOS mkdir command to create the directory that will house the account. The name of the OASYS

account directory can be in uppercase, lowercase, or mixed uppercase and lowercase. 2. Make the new directory your working directory. You can change to the directory with the MS-DOS cd command. 3. Use the OASYS oas_oas_newacct command to create the VOC and other OASYS-specific files in the directory. Note: You do not need to log on as Administrator to create a OASYS account. However, you must have Change access in the account directory. The following three screens illustrate how to create a OASYS account. In the examples, the new account is names ACCOUNT, and is located in the OASYS directory: The first window shows creating the account directory:

© 2012 Onsystex Inc.

46

OASYS Administration for Windows 64 Bit Platforms

The example illustrates executing the oas_newacct command:

Notice that the screen displays the current setting of OASHOME and prompts you if you wish to continue. The final window shows the contents of your new OASYS account:

When you execute oas_ewacct, OASYS creates the VOC file for the new account using a standard VOC file located in the sysprog subdirectory of your OASYS home directory. Tip: If you want to tailor your standard VOC file before creating new accounts, you may do so. There are a number of reasons you may wish to tailor your VOC file. You may want to add custom paragraphs, for instance, that all users should execute. Onsystex recommends that you save a copy of the standard VOC before making changes. The following table describes the default subdirectories OASYS creates with a new account. S ubdirectory

Description

© 2012 Onsystex Inc.

Managing OAS Accounts

BP CTLG SAVEDLISTS SAVEDLISTSL _SpoolJobs_

S ubdirectory _CaptJobs_

47

Used to store OASBasic source and object code. Used to store locally cataloged OASBasic programs. Used to store SELECT lists. Used to store temporary information for BY.EXP sorts. OASYS automatically creates and deletes the contents of this subdirectory. Used to store print files. S ubdirectories in a OAS YS Account

Description Used to store output from background processes (created by the OASYS ECL PHANTOM command) and captured terminal I/O (created by the OASYS ECL COM O command). S ubdirectories in a OAS YS Account (continued)

OASYS creates the subdirectories empty and populates them as the account is used. The next table describes the OASYS hashed files that OASYS creates are created in a new account. File

Description

M ENUFILE VOC

Stores user-generated menu definitions. VOC (vocabulary) file, containing references for ECL commands, sentences, paragraphs, and file names. Used to store OASYS SQL access privileges. Dictionary for the BP file, which holds OASBasic programs. Dictionary for CTLG. Dictionary for M ENUFILE. Dictionary for SAVEDLISTS. Dictionary for VOC. Dictionary for SpoolJobs. Dictionary for CaptJobs Hashed Files in a OAS YS Account

privilege D_BP D_CTLG D_M ENUFILE D_SAVEDLISTS D_VOC D__SpoolJobs_ D__CaptJobs

File D_SAVEDLISTSL

Description Dictionary for savedlists. Hashed Files in a OAS YS Account (continued)

Note: See Developing OASBasic Applications and Using OASYS RDBMS Integraton for information about OASBasic and OASYS RDBMS integration

7.3

Deleting an Oasis Account There is no OASYS command or utility that allows you to delete an entire account. If you need to delete an account, complete the following steps: 1. Analyze the database and identify which files you want to delete. Take care not to delete shared files that other

OASYS accounts still need. 2. Create and verify a full backup of at least the account you are going to delete. 3. Consider strategy. If the account is self-contained (that is, within one file system), you can use the MS-DOS rmdir /s command to delete the account directory. If the account has file pointers to other file systems, you may wish to use the ECL DELETE.FILE command to delete the files before removing the account directory. Use the ECL MAX.USER command to prevent inadvertent access to the OASYS account.

© 2012 Onsystex Inc.

48

OASYS Administration for Windows 64 Bit Platforms

Warning: Be careful with rmdir /s. This command removes all files and subdirectories below the directory you specify. If you have nested accounts (that is, a OASYS account within a OASYS account) and you remove an account directory with rmdir /s, you could remove more than one account.

© 2012 Onsystex Inc.

Part

8

50

8

OASYS Administration for Windows 64 Bit Platforms

Managing OAS Security When you install OASYS, OASYS sets default permissions on system files and directories. After installing OASYS, you may want to customize some permissions.

8.1

Customizing Permissions To customize permissions, from Windows Explorer, select the directories or files for which you want to customize permissions. Using the right mouse button, click the directory or file, click Properties, and then click the Security tab. The following dialog box appears:

Select the permissions you desire in the Permissions area, then click OK. Onsystex make a series of recommendations for customizing these permissions, as shown in the next table. Directory or File

Guidance

OASHOME\sysprog\CTLGTB

Users responsible for cataloging or deleting cataloged programs need write permission. Other users need only read permission. Users need only read permission. Administrators need write permission as well. Users need only read permission. Administrators need write

OASHOME\sysprog\DICT.DICT OASHOME\sysprog\VOC

© 2012 Onsystex Inc.

Managing OAS Security

51

permission as well. Users, including programmers, need execute permission to this global catalog directory. In general, do not allow users to add or delete subdirectories to CTLG. OASHOME\sysprog\CTLG\n and directories CTLG contains a subdirectory for each letter of the alphabet and and files within these subdirectories one for symbols. Users need execute permission to these directories and read access to the files in them. Programmers may need Change permissions to the subdirectories and files so they can catalog or delete cataloged programs. OASHOME\demo Use this directory for training and experimentation. Use any permissions settings that suit your situation. OASHOME\sysprog\AE_BP All users with access to AE (the line editor) need read and write permissions. Guidelines for Permissions for OAS YS S ystem Files OASHOME\sysprog\CTLG

When you create a OASYS account, Onsystex suggests the following guidelines for setting permissions for the directory, subdirectories, and files in the account: Direct

Description

The account directory

Only users who need to create files in the directory should have write permission. Users need read and execute permissions so they can run OASBasic programs that are not globally cataloged. Programmers need write permission. Users need read and execute permissions so they can run locally cataloged programs. Programmers and administrators need write permission so they can locally catalog and delete locally cataloged programs. Users need read and write permissions. Users need read and write permissions. Users need read and write permissions. (This refers to the account VOC file, not the master VOC file in OASHOME \sysprog.) Users must have read and write access to enter their accounts unless you have set the VOC_READONLY environment variable. See Using OASYS for more information about the VOC file. S uggested Permissions for a OAS YS Account

BP CTLG

SAVEDLISTS SpoolJobs CaptJobs VOC

8.2

Customizing a VOC File This section describes ways to customize your VOC file.

8.2.1

Removing Entries Depending on your application, you may wish to prevent users from executing certain ECL commands. If you remove the entries corresponding to these commands from a VOC file in an account, users logged on to that account will not be able to execute them. When a user enters an ECL command, OASYS searches the VOC file in the current account. If there is no corresponding entry, OASYS displays an error message instead of executing the command. The following example shows the results of deleting a VOC entry:

© 2012 Onsystex Inc.

52

OASYS Administration for Windows 64 Bit Platforms

The following table lists ECL commands that create or modify OASYS files, or allow users to execute system-level commands. You may want to consider removing some or all of these from the VOC files for your accounts. These commands allow users to perform the following tasks. Command ! CLEAR.FILE CNAM E COPY CREATE.FILE

Command CREATE.INDEX DELETE DELETE.CATALOG DELETE.FILE DELETE.INDEX DISABLE.INDEX ED ENABLE.INDEX M ODIFY PTRDISABLE PTRENABLE RESIZE UPDATE.INDEX

Description Escape to an M S-DOS shell prompt. Clears the data or dictionary of a file. Changes a filename. Copies records. Creates files. VOC Commands S ecurity

Description Creates an alternate key index. Deletes records from VOC or other files. Deletes catalog entries. Deletes a file. Deletes an alternate key index. Disables an alternate key index. Invokes the ED editor. Enables an alternate key index. M odifies records in a data or dictionary file. Disables a printer or queue. Enables a printer or queue. Resizes a file. Updates an alternate key index. VOC Commands S ecurity (continued)

Note: You can remove entries from the OASYS master VOC file (located in OASHOME\sysprog) or from the VOC files in one or more OASYS accounts. The master VOC is installed as part of the OASYS installation, and is used to build VOC files for your accounts when you execute the oas_newacct command. If you remove commands from the master VOC file, and then create new OASYS accounts, users in the new accounts will not be able to execute the commands you remove. Tip: If you choose to modify the master VOC file, make sure you save a copy of it and its dictionary before you begin your modifications. Warning: When you remove a VOC command entry, OASYS no longer recognizes that command. OASYS displays an error message if a user tries to execute the command, whether at the ECL prompt, or within a OASBasic program.

© 2012 Onsystex Inc.

Managing OAS Security

8.3

53

Customizing OASIS Behavior The CUST.OPTIONS command enables you to customize your OASYS environment. CUST.OPTIONS 19 allows you to choose whether Administrators can bypass security restrictions created by removing entries from the VOC file. If CUST.OPTIONS 19 is on, OASYS prevents even Administrators from executing commands after the entries are removed from the VOC. If CUST.OPTIONS 19 is off (the default), OASYS allows Administrators to execute ECL commands even if the command entries were removed from the VOC file. When a user logged on as Administrator executes a command, OASYS first reads the VOC file in the current account, just as it does for any other user. If there is a matching entry, OASYS executes the command. If there is no matching VOC entry, and if CUST.OPTIONS 19 is OFF, Administrators can still execute the command. The following table shows the behavior of CUST.OPTIONS 19. CUS T.OPTIONS 19

Command S tatus

Behavior

ON

VOC entry exists

OFF

VOC entry exists

ON

No VOC entry

OFF

No VOC entry

Administrators can execute command Others can execute command Administrators can execute command Others can execute command Administrators cannot execute command Others cannot execute command Administrators can execute command Others cannot execute command

CUS T.OPTIONS 19

CUST.OPTIONS 19 is turned off by default. Leave it off to allow a user with Admin-istrator privileges to execute commands that users cannot; turn it on to make Administrators consistent with other users. Note: See the CUST.OPTIONS Commands Reference for detailed information about the CUST.OPTIONS command.

8.4

Remote Items You can further customize security by replacing some command entries in your VOC file with remote items. A remote item (R-type VOC record) allows a record definition to be stored in a location other than the VOC file. You can substitute remote items for sentences, paragraphs, commands, locally cataloged programs, or menus. See Using OASYS for more information about R-type items. R-type items enable you to customize security in two ways: You can use a remote item as a pointer to a location with different Windows file permissions from the current account, limiting access to the item. You can supply a “security routine” for the remote item. R-type items name a cataloged subroutine that is executed when a user invokes the remote item. The subroutine must have one argument, and return a value of 1 (true) or 0 (false). When a user invokes a remote item with a security subroutine, the remote item does not execute unless the subroutine returns 1 (true). The following screen shows an example of a remote item created for the ECL LIST command:

© 2012 Onsystex Inc.

54

OASYS Administration for Windows 64 Bit Platforms

With this VOC record in place, when a user executes the LIST command, OASYS executes a security subroutine called SECTEST2. If that subroutine returns a value of 1, OASYS executes the item called LIST in a file called OTHER_VOC. The next screen shows a sample program:

8.5

The SETFILE Command You can also customize security by placing data files in a location with different NTFS permissions than your OASYS account, and then modifying the corresponding VOC entries to point to the location. Use the SETFILE ECL command to establish the file pointers, as shown in the following example:

You can set the NTFS permissions at the location of the file to limit access. If a user with insufficient permissions tries to access the file, OASYS displays an error message.

See the OASYS Commands Reference for information about the SETFILE command.

8.6

LOGIN and LOGOUT Paragraphs You can define LOGIN and LOGOUT paragraphs in the VOC files of your accounts to provide further control of users’ environments. A typical LOGIN paragraph sets CUST.OPTIONS and then invokes an application menu. A typical LOGOUT paragraph executes a routine that cleans up application files and exits the application in an orderly manner. If you define the environment so that a user logs directly on to a OASYS account and executes the oas command, and the LOGIN paragraph defines the CUST.OPTIONS and displays a menu, the user does not see either the MS-DOS command prompt or the ECL prompt. The behavior of LOGIN and LOGOUT paragraphs are summarized as follows:

© 2012 Onsystex Inc.

Managing OAS Security

55

When you enter OASYS, OASYS checks the VOC file in the account you are entering for a LOGIN paragraph. If there is one, OASYS automatically executes it. If you change accounts with the ECL LOGTO command, OASYS does NOT execute the LOGOUT paragraph in the account you are leaving. OASYS looks in the VOC file of the account you are entering, and executes the LOGIN paragraph there, if there is one. When you exit OASYS, OASYS checks the VOC file in your current account and executes the LOGOUT paragraph, if one is there. Note: You can also use the ECL ON.ABORT command to prevent users from accessing the ECL or MS-DOS prompt. ON.ABORT defines a paragraph that executes whenever a OASBasic program aborts. See the OASYS Commands Reference for information about ON.ABORT. The following sample session shows simple examples of LOGIN and LOGOUT paragraphs in a OASYS account, and a different LOGOUT paragraph in a second account:

In the preceding example, the second LOGOUT paragraph , displays the DATA and prints a message. A userwritten exit program can perform a variety of tracking and reporting functions. The next example shows the response when two of these paragraphs are executed:

Notice that the LOGIN paragraph defines CUST.OPTIONS and then prints a message. A LOGIN paragraph can also execute a program, or display a menu. If a user’s .login or .profile file sets their working directory to a OASYS account and executes the oas command, and the LOGIN paragraph defines the CUST.OPTIONS and displays a menu, the user does not see either the MS-DOS command prompt or the ECL prompt.

© 2012 Onsystex Inc.

56

OASYS Administration for Windows 64 Bit Platforms

Notice also that logging out of OASYS after the LOGTO command executes the LOGOUT paragraph of the current account only. Note: If CUST.OPTIONS 20, U_IGNLGN_LGTO, is on, users logged on as an Admin-istrator can access an account through the LOGTO command without executing the LOGIN paragraph. If a user logged on as an Administrator accesses the account directly, OASYS executes the LOGIN paragraph regardless of the setting of CUST.OPTIONS 20.

8.7

Field-Level Security for OASQuery OASYS includes functionality to determine OASQuery access on a attribute-by-attribute basis. System administrators can set privileges for OASQuery access at the file or attribute level for a single user or for all users in a domain by creating a QUERY.PRIVILEGE table in a specified format and adding records to that table. You can also set a default for your system, defining all files as OPEN or SECURE. In an OPEN system, the ability to access a file or a field with OASQuery is a function of system-level file permissions, other OASYS security implementations, and privi-leges granted using the QUERY.PRIVILEGE table. In a SECURE system, unless privileges are granted in the QUERY.PRIVILEGE table, users cannot access files through OASQuery, regardless of system-level permissions or other implementations.

8.7.1

Points to Remember about Field-Level Security Remember the following points about field-level security: Implementing and maintaining field-level security is a completely manual process. You must create and populate the QUERY.PRIVILEGE file manually. ECL commands, such as CREATE.FILE, DELETE.FILE, and CNAME, do not update the QUERY.PRIVILEGE table. ECL commands are not affected by OASQuery security. The OASQuery MODIFY command is not affected by the OASQuery security feature. The security is imposed when a user attempts to SELECT. A default of OPEN or SECURE affects all OASYS accounts that share the same OASHOME. You cannot define some accounts as OPEN and some as SECURE. Privileges granted on a file are not automatically applied to its dictionary. Therefore, if a user has ALL access to the INVENTORY file and its dictionary, you must consider D_INVENTORY as well. If the system default is OPEN, the user can access D_INVENTORY. Otherwise, if you want the user to access D_INVENTORY, you need a QUERY.PRIVILEGE record for D_INVENTORY as well.

8.7.2

The QUERY.PRIVILEGE File OASQuery security depends on the existence of the QUERY.PRIVILEGE file, which must be located in OASHOME\sysprog. If this file does not exist, OASQuery functions as it has previously, with no field-level security. Warning: If you create the QUERY.PRIVILEGE file, but do not populate the file with any records, OASYS does not allow any user to access any files on the system through OASQuery. When you install OASYS, the OASQuery security is not implemented, and there is no QUERY.PRIVILEGE file. If you wish to turn this feature on, you must create QUERY.PRIVILEGE and D_QUERY.PRIVILEGE manually.

© 2012 Onsystex Inc.

Managing OAS Security

57

Records in the QUERY.PRIVILEGE file grant the SELECT privilege to users or groups of users, at the file level or the attribute level. Each QUERY.PRIVILEGE record has one attribute. The dictionary of the QUERY.PRIVILEGE file contains four records. Following is a sample of the dictionary of the QUERY.PRIVILEGE file:

The following table describes each QUERY.PRIVILEGE attribute. Attributes

Description

@ID

Data attribute that defines the user or domain and the file for which you are setting privileges. If you are setting up a system default, @ID is DEFAULT. Otherwise, @ID must be of the format username*path, domain\ uername*path, or PUBLIC*path.

PRIV

Data attribute that indicates the attributes to which you are granting privileges, by location. PRIV is a multivalued attribute. To grant privileges to all attributes in a file, set PRIV to ALL. If you are setting a system default, set PRIV to OPEN to grant privileges. To restrict privileges to every attribute in a file, set PRIV to SECURE.

FULLPATH

Virtual attribute formula that designates the full path of the file affected by PRIV. This formula has the format FIELD(@ID,”*”,2).

USERNAM E

Virtual attribute formula that designates the user affected by PRIV. This formula has the format FIELD(@ID,”*”,1). QUERY.PRIVILEGE Record Attributes

Note: You can customize the length of the dictionary attributes in the QUERY.PRIVILEGE file. The length of @ID should be sufficient to contain the longest Linux user name and the longest absolute path for a OASYS file on your system. FULLPATH and USERNAME should be long enough to handle the longest absolute path and longest user name, respectively. The following example shows a very simple example of a QUERY.PRIVILEGE file:

This QUERY.PRIVILEGE file means:

© 2012 Onsystex Inc.

58

OASYS Administration for Windows 64 Bit Platforms

Except for TEST, which are in the FirstAccount database, all users have privileges to query all files in all accounts that share the same OASHOME. Marco can query the fields in positions 1, 2, 3, 4, 5, and 12 only in the TEST file. No other user can query this file.

8.7.3

OASQuery Processing If you turn on the security feature by creating and populating the QUERY.PRIVILEGE file, every time a user logs on to OASYS, their OASYS process reads the contents of QUERY.PRIVILEGE and stores the information for reference. Then, when a user attempts a OASQuery access, OASYS checks the stored information, following these steps: 1. Check for privileges granted to the user’s domain.

If the user’s domain has sufficient privileges for the requested access, allow the access. Otherwise, proceed to step 2. 2. Check for privileges granted specifically to the user. If the user has sufficient privileges for the requested access, allow the access. Otherwise, proceed to step 3. 3. Check for privileges granted to PUBLIC. Privileges granted to PUBLIC apply to all system users. If PUBLIC has sufficient privileges for the requested access, grant the access. Otherwise, proceed to step 4. 4. Check for a DEFAULT entry. If there is a DEFAULT record in QUERY.PRIVILEGE, and if the default is set to OPEN, allow the requested access. If there is no DEFAULT, or if the DEFAULT is SECURE, disallow the access, displaying the following message:

8.7.4

Turning on Field-Level Security Complete the following steps to implement the OASQuery field-level security feature: 1. Log on to your system as Administrator.

OASYS must be running. Users do not need to log off. 2. Create QUERY.PRIVILEGE Change your working directory to OASHOME\sysprog, and enter oas to start a OASYS session. Use the ECL CREATE.FILE command as follows:

Make the QUERY.PRIVILEGE file a static hashed file. 3. Set Permissions on QUERY.PRIVILEGE

© 2012 Onsystex Inc.

Managing OAS Security

59

The QUERY.PRIVILEGE file and its dictionary should be read-only to all users except Administrator. Check the permissions and change them, if necessary. 4. Edit the Dictionary Use AE, or ED to edit D_QUERY.PRIVILEGE. The dictionary must look like the following example:

You can customize the format for the dictionary items to specify lengths for the attributes that match your system. 5. Add Records to QUERY.PRIVILEGE

For this step, you may prefer to have users logged out of OASYS. As you add records to the QUERY.PRIVILEGE file, users logging on to OASYS access whatever records are present at the time they log on, which may cause unexpected results. Use AE or ED to populate the QUERY.PRIVILEGE file.

© 2012 Onsystex Inc.

Part

9

Managing OAS Files

9

61

Managing OAS Files OASYS stores your data in hashed files of several different types. OASYS also supplies other types of files to support your database, including index files, program files, and directory files. This chapter describes the types of OASYS hashed files and explains the commands you can use to manage them.

9.1

OAS Hashed Files Hashed files are binary files that cannot be viewed at the operating system level or read by text editors external to OASYS. Each OASYS hashed file consists of a file header and one or more groups of data. Each data group contains the following structure: A fixed-length group header A pointer array Record IDs Data A record key is assigned to a group in the file according to a hashing algorithm. Then the precise location of the data is stored in the header of that group. The goal of hashing is to make searching for data more efficient by eliminating the need to search an entire file for a record. In a hashed file, OASYS searches only the group where the primary key of the record was assigned. OASYS supports two proprietary hashing algorithms (hash type 0 and hash type 1). The hash type determines the data group that contains each record. The most efficient hashing algorithm for a file is the one that provides the best distri-bution of keys across the groups in the file. If the distribution is uneven, heavily loaded groups are accessed more frequently, which results in inefficient disk space use and increased contention for those groups. The default hash type for both static and dynamic files is 0. You can specify hash type 1 when you create a file, and you can switch between hash types with the memresize command.

9.2

Static Hashed Files OASYS creates static hashed files with a specified block size multiplier and a specified modulo (number of data groups). OASYS stores the block size and modulo in the header of the file. Groups in static hashed files can overflow in two ways, as shown in the following table. Overflow Type

Description

Level 1 overflow

The amount of space required for the data in the group is larger than the amount of space available. This happens if the length of a data record is too long for the block size, or if the number of records in the group grows so large that not all of the data fits. OASYS appends overflow blocks to the original file, and stores the data portions of records in overflow. The pointers and keys remain in the primary data file; accessing a record can require two reads, one to determine the address and the second to read the data in overflow.

Level 2 overflow

The amount of space required for pointers and keys is larger than the total size of the group. This happens if too many records are hashed to the group. OASYS creates overflow blocks which contain both data and keys. Record access can require multiple reads to determine the location and find the data. Level 1 and Level 2 Overflow

© 2012 Onsystex Inc.

62

OASYS Administration for Windows 64 Bit Platforms

Note: When a group in a static file overflows, OASYS links the overflow blocks to that specific group. If overflow blocks are freed (by deleting records, for example) they remain linked to the original group and are not available to handle overflow from any other group in the data file. The space used by the blocks is not returned to the operating system. Level 1 overflow eventually impacts the performance of a static hashed file. Level 2 overflow impacts performance earlier and more severely, so correct sizing to prevent level 2 overflow is critical.

9.3

Dynamic Hashed Files Dynamic hashed files automatically increase modulo (number of groups) to minimize level 2 overflow. When you view the structure of dynamic files at the operating system level, the structure is different from that of static files. A dynamic file is actually an Windows directory containing at least two binary files: One or more data files named dat00x. These are hashed files. dat001 is the primary data file. Each group in a dat file contains a group header, keys, pointers, and data. One or more overflow files named over00x. Blocks in these files hold data when a group in a data file is in level 1 overflow. The following example shows the structure of the TEST file in the OASYS demo database:

Notice that the dictionary file (D_TEST) is not a directory.

9.3.1

Dynamic Files and Overflow Dynamic files automatically change size (both physical size and modulo) as data is added to them. You create a dynamic file with a specified initial modulo, which is the minimum modulo of the file. As records are added, OASYS adds groups to the data file (dat001) to prevent level 2 overflow and adds blocks to the overflow file (over001) to contain level 1 overflow. If you specify the OVERFLOW option with the CREATE.FILE command, OASYS creates a dynamic file with an overflow file for each dat file. For example, over001 corresponds to dat001, over002 corresponds to dat002, and so forth. When the file is cleared, OASYS maintains this overflow structure. For more information about the CREATE.FILE command, see the OASYS Commands Reference.

Splitting and Merging When a group in the primary data file reaches level 1 overflow, OASYS stores the overflowed data in blocks in the overflow file. Blocks in over001 are linked (internal to OASYS) to groups in the primary data file dat001. When © 2012 Onsystex Inc.

Managing OAS Files

63

the overflow file runs out of blocks, OASYS adds blocks to it. To prevent level 2 overflow, OASYS splits groups (increasing the modulo of the primary file) whenever the load factor of an existing group reaches a level called the splitting threshold (or SPLIT.LOAD). The splitting process is transparent to the user. When a group splits, OASYS adds the additional group to the primary data file, increasing its modulo and physical size. As records are removed from a dynamic file, groups that had been split can merge back together if all the following conditions are true: The current modulo of the file is greater than the minimum modulo of the file. The combined load factor of the two groups is less than a value called merging threshold (or MERGE.LOAD). One of the two groups is the last group in the file. OASYS provides two different split/merge types for dynamic files, KEYONLY and KEYDATA. You can set the split/merge type when you create a dynamic file, and you can change an existing split/merge type for a file with the CONFIGURE.FILE command or the memresize command. Use FILE.STAT, ANALYZE.FILE, or GROUP.STAT to display the split/merge type for a file.

KEYONLY Type The KEYONLY split/merge type is the default for OASYS dynamic files. For KEYONLY dynamic files, the load factor of a group is the percentage of the group space that is filled with keys and pointers. By default, the splitting threshold for a group in a KEYONLY dynamic file is 60%, meaning that the group can split into two when the space occupied by keys and pointers reaches 60% of the size of the group. By default, the merging threshold for a KEYONLY dynamic file is 40%, meaning that if the total load in a pair of groups that resulted from a split is under 40% of the size of a single group, the pair are eligible to merge. You can change the splitting threshold for a single KEYONLY file with the CONFIGURE.FILE or memresize commands, and you can change the defaults for all files by changing the OAS_SplitLoadand OAS_MergeLoadparameters in the OASYS configuration file (\OASHOME\include\oasconfig).

KEYDATA Type The KEYDATA split/merge type is also available for OASYS dynamic files. For KEYDATA dynamic files, the load factor of a group is the percentage of the group space that is filled with keys, pointers, and data. By default, the splitting threshold for a group in a KEYDATA dynamic file is 95 percent, meaning that the group can split into two when the space occupied by keys, pointers, and data reaches 95 percent of the size of the group. By default the merging threshold for a KEYDATA dynamic file is 40 percent, meaning that if the total load in a pair of groups that resulted from a split is under 40 percent of the size of a single group, the pair are eligible to merge. You can change the splitting threshold for a single KEYDATA file with the CONFIGURE.FILE or memresize commands, and you can change the defaults for all files by changing the KEYDATA_OAS_SplitLoadand KEYDATA_OAS_MergeLoadparameters in the OASYS configuration file (\OASHOME\include\oasconfig).

Selecting a Split/Merge Type Use the KEYONLY split/merge type for files whose records differ widely in length (standard deviation from average is large). When record lengths vary widely, the KEYONLY split/merge type makes more efficient use of disk space. Use the oas_analyzetbls or FILE.STAT command to determine the record length and standard deviation from average for an existing file. Use KEYDATA for files whose record length is consistent and in which the length of the data portion of each record is large with respect to the record ID. For files with these characteristics, the KEYDATA split/merge type provides a better distribution of records and less overflow than KEYONLY.

Dynamic Files and Hash Type For both static and dynamic files, the default hash type was is 0. This hash type provides a more even distribution of keys in groups in dynamic files. If key distribution in a file is uneven, you should consider tuning the modulo, block size, and split/merge type of the file. If none of these methods is effective, you should consider switching the hash type to 1.

© 2012 Onsystex Inc.

64

9.3.2

OASYS Administration for Windows 64 Bit Platforms

When Dynamic Files Are Created The following considerations determine where the parts of a newly created dynamic file are located.

Estimating the Size of the File The estimated space required for a new dynamic file is the smaller of the following: OAS_MaxPartitionLength minimum modulo * block size If (minimum modulo * block size) is larger than OAS_MaxPartitionLength, the new file needs more than one data part file.

Locating the Dynamic File Directory The dynamic file directory is located in the OASYS account where CREATE.FILE was executed. The following example illustrates creating a dynamic file in the current account directory:

In the preceding example, the primary data file (dat001) includes a file header and the three data groups for a total of four 1K blocks. The overflow file (over001) includes a 1K file header. Since OAS_MaxPartitionLength is larger than minimum modulo * block size, the primary data file and overflow file each have only one “part.”

9.3.3

Tips and Constraints for Creating a Dynamic File This sections provides information about choosing the optimal modulo and block size for a dynamic file.

Choosing the Initial Modulo If you are creating a dynamic hashed file, selecting an appropriate starting (minimum) modulo is critical to the © 2012 Onsystex Inc.

Managing OAS Files

65

future efficiency of the file. You should select a starting modulo based on the expected future size of the file, because subsequent splitting and merging operations are affected by the initial modulo. Starting with a modulo that is very small (for instance, 3) produces inefficient hashing and splitting as the file grows. Starting with a modulo that is very large produces a file that may initially take up more disk space than needed, but that impact is more desirable than the slow performance and inefficiency that results if the starting modulo is too small. When you create a dynamic file, estimate the initial modulo by using the same procedure for estimating the modulo for a static file.

Choosing the Block Size If you are creating a KEYDATA dynamic file, make sure the block size is large with respect to the record length. Onsystex recommends you choose a block size that is at least 10 times the average record length. OASYS bases the load factor in a KEYDATA file on the percentage of the space in each block that is occupied by both keys and data. If the block size is not large with respect to record size, the file will occupy a large amount of space, and much of that space will be unused. If you are creating a KEYONLY dynamic file, make sure the block size is large with respect to the average key length. Onsystex recommends you choose a block size that is at least ten times the average key length. Load factor in a KEYONLY file is based on the percentage of the space in each block that is occupied by keys and pointers. If the block size is not large with respect to the average key length, and the hashing is not even, certain groups will be split over and over, resulting in an inefficient distribution.

9.3.4

Dynamic Files and Disk Space When data is removed from blocks in the overflow file, OASYS keeps those blocks for the dynamic file. A certain number are reserved for the groups they were part of, and the remainder of the blocks are available for overflow from any group in the file. The OASYS configuration parameter OAS_FreeBlocksinGroup defines the maximum number of free blocks that should be kept in the free block list for a particular group. If more blocks are freed, they are kept in the free block list at the file level. Note: See “Appendix A OASYS Configuration Parameters,” for a list of the configuration parameters. If you remove all records from a dynamic file with either the ECL CLEAR.FILE command or the ECL DELETE command with the ALL option, the file returns to its minimum modulo, and the disk space is returned to the operating system. However, if you remove all records from a dynamic file using a select list, the file may not return to its minimum modulo. Depending on the order in which records are removed, some groups resulting from earlier splits may not become eligible for merging, even though they do not contain any records. The following examples show splitting and merging in a dynamic file. The first example shows creating a dynamic file with a minimum modulo of 3:

© 2012 Onsystex Inc.

66

OASYS Administration for Windows 64 Bit Platforms

Notice the following points: Because the file was created with a block size multiplier of two, the size of each block is 2048 bytes. The primary file (dat001) has one block for the file header, and three for the data. The overflow file (over001) is initially allocated one block for its header. Because the split/merge type was not specified, the file was created as a KEYONLY file. The next example shows what happens when the dynamic file is populated with records:

© 2012 Onsystex Inc.

Managing OAS Files

67

The FILE.STAT command shows the following output:

Notice the following points: The original three groups have split. Now there are 11 groups in the primary data file, and 3 groups (plus the header group) in the overflow file. The following example shows the results of deleting all records with a select list:

© 2012 Onsystex Inc.

68

OASYS Administration for Windows 64 Bit Platforms

Notice the following points: Merging has reduced the modulo to 10. The file size as measured at the operating system level has not changed from the previous example. Some groups did not merge, and the groups that were added remain allocated to the file. The final example shows the results of CLEAR.FILE:

© 2012 Onsystex Inc.

Managing OAS Files

69

The ECL CLEAR.FILE command returns the file to its original modulo and size.

9.4

Sequentially Hashed Files A sequentially hashed file has the same structure as a dynamic file, but OASYS stores all records sequentially, based on the primary key. The modulo (number of groups) for a sequentially hashed file is fixed, it does not grow and shrink as records are added or deleted. You create sequentially hashed files by converting from existing OASYS static or dynamic files. You specify a percentage of the file that you want to remain empty to allow for growth. Although the structure for a sequentially hashed file is the same as a dynamic file, the modulo is fixed. Use sequentially hashed files for files where the majority of access is based on the primary key.

9.4.1

The dat001 File The dat001 file is also called the primary data file. As you add records to a sequentially hashed file, OASYS hashes the keys, based on information in the gmekey file, to groups in dat001. If your data overflows the group (level 1 overflow), OASYS writes the overflow data to the over001 file.

9.4.2

The over001 File As you add records to a sequentially hashed file, whenever the space reserved for data in a group in the primary file gets too full, OASYS writes the excess data into blocks in over001. Registers within OASYS track how blocks

© 2012 Onsystex Inc.

70

OASYS Administration for Windows 64 Bit Platforms

in over001 are linked to groups in dat001. If over001 gets too large, OASYS adds additional blocks to it. If the current file system becomes full, or over001 grows larger than a OASYS limit, OASYS creates an over002 file. If the sequentially hashed file has level 2 overflow, the file should be rebuilt using the oas_shfbuild command.

9.4.3

The gmekey File Each sequentially hashed file contains a static, read-only file called the gmekey file. OASYS reads this file into memory when you open a sequentially hashed file. The gmekey file contains information about the type of keys in the file (alpha or numeric), and controls which group a record is hashed to when it is written. You create a sequentially hashed file by converting an existing dynamic or static file with the oas_shfbuild command: Syntax: oas_shfbuild [-a |-k] [-n | -t] [-f] [-e empty percent] [-m modulo] [-b block size multiplier] [-i infile] outfile The following table describes the oas_shfbuild options. Parameter

Description

-a

Only rebuild the last group of the sequentially hashed file. OASYS splits the last group into groups according to the records in the group. If you use this option, the outfile should be the name of the sequentially hashed file. Do not specify infile.

-k

Build the gmekey file only. If you use this option, outfile should be the name of the sequentially hashed file. Do not specify infile. OASYS rebuilds the gmekey file according to the keys in each group of outfile.

-n/-t

Force the outfile to be in numeric or alphabetic order. By default, the order of outfile is determined by the infile primary key type. If infile is a sequen-tially hashed file, OASYS uses the same order in outfile. If infile is not a sequentially hashed file, the order of outfile is determined by the justifi-cation of the @ID of the infile dictionary record. If it is right justified, it is numeric. Otherwise, it is alphabetic. If you use the -a or the -k option, these options have no effect.

-f

Force outfile to truncate before being built.

-m

Specifies the new modulo of outfile.

-e

Empty percent. This is a number between 0 and 99 which indicates how much space in the rebuilt groups to reserve. OASYS calculates the new modulo of the file from empty_percent and the number of records in the rebuilt groups. If you do not specify -e or -m, OASYS rebuilds the sequen-tially hashed file according to the default empty percent of 20. oas_shfbuild Parameters

Parameter

Description

-b

Specifies the block size of the sequentially hashed file in kilobytes. Load the contents from infile instead of outfile. infile can be any type of OASYS file. The name of the output file.

-i infile outfile

© 2012 Onsystex Inc.

Managing OAS Files

71

oas_shfbuild Parameters (continued)

To convert an existing file, execute the oas_shfbuild command from the system level prompt, as shown in the following example:

After converting a file to a sequentially hashed file, you must manually enter a file pointer in the VOC file in order to access the sequentially hashed file, as shown in the following example:

9.5

DIR-Type Files A OASYS DIR-type file is an NTFS directory that contains NTFS text or data files. Each NTFS text or data file is a OASYS record. The BP file, a OASYS file that stores OASBasic source files and compiled programs, is a DIR-type file. The following example shows the structure of a sample DIR file:

In the example, MYTEST is a directory file.

9.6

Multilevel Directory Files A OASYS multilevel directory (LD) file is a NTFS directory. The NTFS directory contains one or more NTFS subdirectories (OASYS DIR type files). All of the DIR files share the same dictionary. To access a record, you must specify both the multilevel directory file and the DIR file where the record resides. The following example shows some characteristics of a multilevel directory file:

© 2012 Onsystex Inc.

72

OASYS Administration for Windows 64 Bit Platforms

Note: If a subdirectory of a multilevel directory file has the same name as the main directory, you can use the main directory name to access the subdirectory. For instance, LIST MULTID is correct syntax if the directory MULTID contains subdirectory MULTID.

Points to Remember About Multilevel Directory Files A OASYS multilevel directory file is a NTFS directory that contains OASYS DIR files (NTFS subdirectories). All of the DIR files in a multilevel file share the same dictionary. Each record in a multilevel directory is a NTFS file. OASYS supports multilevel directory files to simplify conversion for legacy applications. However, multilevel directory files are less efficient than ordinary DIR files. The leveled structure means that more system resources are needed to read and update these files. For this reason, Onsystex recommends using ordinary DIR files rather than multilevel directory files whenever possible. You can share a single dictionary between OASYS DIR files by modifying the VOC entries for each file to reference the same dictionary.

9.7

Index Files and Index Log Files OASYS creates an index file whenever you create the first alternate key index on a OASYS hashed file. Index information is stored in B+ tree format. OASYS index files are NTFS data files. Note: Regardless how many alternate key indexes users create for a data file, OASYS creates a single index file. The ECL CREATE.INDEX command creates the index file. The ECL BUILD.INDEX command populates the index. DELETE.INDEX (with the ALL option) removes the index file. By default, each time you update a OASYS data file, its associated indexes are updated at the same time. You can turn off automatic indexing on one or more data files (using the ECL DISABLE.INDEX command) to speed © 2012 Onsystex Inc.

Managing OAS Files

73

performance during periods of heavy activity on your system. If you turn off automatic indexing, OASYS stores all index updates in an index log file. The ECL UPDATE.INDEX command applies updates from index logs to indexes in batch mode, and the ECL ENABLE.INDEX command turns automatic updating back on. The ENABLE. INDEX command also creates an index log file if one is not already there. DELETE.INDEX (with the ALL option) removes the index log file. See the OASYS Commands Reference for additional information about index handling commands.

9.7.1

Index-Related Files for a Static Hashed File For a static hashed file, OASYS creates both the index file and the index log file in the account directory with the data file. The following example shows a sample account where a static file named MYSTATIC has been indexed:

X_MYSTATICFILE is the index file for the data file MYSTATICFILE.

9.7.2

Index-Related Files for a Dynamic Hashed File For a dynamic hashed file, OASYS creates both the index file and the index log file in the dynamic file directory itself. The following example shows the structure of the TEST file in the demo database after an index is created on the file:

Notice that the index and index log files are located in the dynamic file directory rather than in the account. The file idx001 is the index file, and xlog001 is the index log file.

© 2012 Onsystex Inc.

74

OASYS Administration for Windows 64 Bit Platforms

Note: A dynamic hashed file can have more than one idx file. The same configuration parameter (OAS_MaxPartitionLength) that limits the size of a dat or over part file limits the size of index files. When the size of an index file (for instance, idx001) reaches OAS_MaxPartitionLength, OASYS creates the next index file (for instance, idx002).

9.8

File-Handling Commands OASYS includes a variety of commands for users to create and delete OASYS files as well as to obtain status information, change file parameters, and diagnose and repair damaged hashed files. The following table describes ECL file-handling commands and indicates the OASYS file types they affect. Command CREATE.FILE DELETE.FILE CLEAR.FILE

CNAM E

SETFILE

RECORD

FILE.STAT

Description Creates a OASYS file; works for static and dynamic hashed files, dictionary files, DIR files, multilevel files and multilevel directories. Deletes a OASYS file; works for static, dynamic, and sequen-tially hashed files, dictionary files, DIR files, multilevel files, and multilevel directories. Removes all records from a OASYS file; works for static, dynamic, and sequentially hashed files, dictionary files, DIR files, multilevel subfiles, and multilevel subdirectories. Changes the name of a OASYS file; works for static, dynamic, and sequentially hashed files and DIR files. Does not work for multilevel subfiles and multilevel subdirectories or dictionary files. Sets a pointer to a OASYS file; works for static, dynamic, and sequentially hashed files, DIR files, multilevel files, and multi-level directories. Does not work for dictionary files or for multilevel subfiles or subdirectories. Identifies group where a primary key is hashed, and displays a list of keys hashed to that group. Works for static, dynamic, and sequentially hashed files and for multilevel subfiles. Does not work for dictionaries, directory files, multilevel directories, or multilevel subdirectories. Displays statistics about a hashed file, including modulo, block size, hash type, and record statistics. Works for static, dynamic, and sequentially hashed files or static or dynamic multilevel subfiles. Does not work for dictionaries, directory or multilevel directory files, or multilevel subdirectories. ECL File Commands

Command

Description

GROUP.STAT

Displays record distribution in a OASYS hashed file. Works for static, dynamic, or sequentially hashed files or static or dynamic multilevel subfiles. Does not work for dictionaries, directory or multilevel directory files, or multilevel subdirectories. Changes the modulo, block size, or hash type of a OASYS static hashed file. Works on static hashed files and static hashed multi-level subfiles. Does not work on directories, multilevel directories or subdirectories, dictionaries, or any dynamic hashed file or subfile. Displays statistics, including current and minimum modulo, hash type, block size, split/merge type, split load, merge load, and record distribution for a dynamic file. Works on dynamic and sequentially hashed files and dynamic hashed multilevel subfiles only. Changes split/merge type, split load, merge load, part table, or minimum modulo for a dynamic file. Works on dynamic hashed files and dynamic hashed multilevel subfiles only. Reconstructs a dynamic file using current settings for split load, merge load, and minimum modulo. Used after CONFIGURE.FILE. Works on dynamic hashed files and dynamic hashed multilevel subfiles only.

RESIZE

ANALYZE.FILE

CONFIGURE.FILE

REBUILD.FILE

© 2012 Onsystex Inc.

Managing OAS Files

CHECKOVER

75

Checks OASYS hashed files for level 2 overflow. Works on all OASYS hashed files and subfiles. Used to check all files in a OASYS account directory. ECL File Commands

See the OASYS Commands Reference for detailed information about the syntax of the file-handling commands. The next table describes OASYS system-level file-handling commands. Command

Description

checkover

Checks OASYS hashed files for level 2 overflow. Works on all OASYS hashed files and subfiles. Checks all files in a OASYS account directory. The system-level version can be executed with OASYS shut down or with OASYS running. Unloads the contents of a damaged group in a hashed file; can be executed with OASYS shut down or with OASYS running. Does not work with EDA files. Repairs damaged groups in a file; can be executed with OASYS shut down or with OASYS running. Does not work with EDA files. Repairs a damaged group; can be executed with OASYS shut down or with OASYS running. Does not work with EDA files. Identifies damaged hashed files or dictionary files. Cannot be executed if OASYS is shut down. Does not work with EDA files. Changes the modulo, block size, or hash type of a OASYS hashed file. Works on static or dynamic hashed files and multilevel subfiles. Does not work on sequentially hashed files, directories, multilevel directories or subdirectories, EDA files, or dictionaries. This command uses shared memory and disk storage rather than disk storage alone as working storage. Although it is executed from the system-level prompt, you cannot run it if OASYS is shut down. memresize also converts static files to dynamic files, dynamic files to static files, and changes the split/merge type and part table for dynamic files. Converts a static or dynamic file to a sequentially hashed file. Identifies damaged hashed files or dictionary files; you cannot execute if OASYS is running. OAS YS S ystem-Level File Commands

dumpgroup oas_fixtbls fixgroup oas_analyzetbls memresize

oas_shfbuild oas_validatetbls

9.9

File Corruption File corruption is damage to the structure of a file. OASYS file management tools diagnose and repair problems that occur if invalid, unreadable, or inconsistent infor-mation is written to file or group headers. Such invalid information can result in OASYS being unable to access part or all of the data in the file. OASYS provides a series of utilities that enable you to detect and repair damaged files. Note: OASYS file tools do not detect or repair invalid or inconsistent data in files. Detecting data inconsistencies should take place at the application level.

9.9.1

What Causes File Corruption? File corruption can result from a variety of causes: Hardware failures, including CPU crashes, media or memory failure, controller failures, bad spots on a disk. Interrupting a write in progress; for example, terminating a OAS Telnet Service while users are still logged on to the system. Incomplete writes; for example, a disk runs out of space before a write is complete. Note: Overflowed files are more likely to become corrupted, since multiple I/O operations can be required to accomplish a single read or write to an overflowed file. An interrupted write can result in a condition where a

© 2012 Onsystex Inc.

76

OASYS Administration for Windows 64 Bit Platforms

primary data block and corresponding overflow blocks are out of synch. The increased chance of corruption is particularly significant for files in level 2 overflow.

9.9.2

Preventing File Corruption You can reduce the possibility of file corruption by sizing your files to minimize overflow. Level 1 overflow can leave incomplete records in a file, although all the IDs are available. Level 2 overflow can cause more severe data problems because IDs and data can be lost. Onsystex strongly recommends you monitor and minimize level 2 overflow. Using dynamic files versus static files minimizes level 2 overflow, which provides some protection. However, using dynamic files greatly increases level 1 overflow, making the risk of file corruption greater than that for static files. Certain OASYS commands carry a direct risk of file corruption, as shown in the following table. Command oas_removeuser

Risk Factor This OASYS command first tries to gracefully terminate a process. If unsuccessful, oas_removeuser forces the process to terminate. OAS YS Commands that can corrupt a file

There are other operations that can corrupt OASYS files; the following list contains some examples: Stopping the OASYS Telnet Service (OAS Telnet) while users are logged on to the system. Attempting to view/edit a OASYS file with an MS-DOS text, octal, or binary editor can damage the file whether or not OASYS is running. In many cases, the file damage is irreversible. Backing up and restoring a OASYS file while users are accessing the file during backup may damage the restored file. Any OASYS file can be damaged in this way, but the risk is particularly great for dynamic files. Note: The file being backed up is not damaged. Danger is only to the file being restored.

9.10

OAS Detection Tools OASYS supplies the following tools for detecting damaged files: oas_analyzetbls - Use the oas_analyzetbls command to detect file damage when OASYS is running. oas_validatetbls - Use the oas_validatetbls command to detect file damage when OASYS is not running.

9.10.1 oas_analyzetbls Syntax: oas_analyzetbls [file1, file2,...][-options] Note: You may supply oas_analyzetbls with the name of a single OASYS file or a series of file names separated © 2012 Onsystex Inc.

Managing OAS Files

77

by commas or spaces. If you do not specify any files, oas_analyzetbls processes all files in the current OASYS account directory. However, oas_analyzetbls does not work with EDA files.

Description oas_analyzetbls is a OASYS-supplied, system-level utility that provides detailed statistics and suggestions for optimizing file size and ensuring data integrity.

Options The following table lists the options available for the oas_analyzetbls command. Option

Description

-a |-A [filename] -na | -NA (no advice)

Controls whether management advice is included in the output. The default file name for the advice information is GUIDE_ADVICE.LIS. You cannot combine the -a and -o options, because OASYS assumes the -a option when the -o (output) option is present. You may use the -na option in combination with the -o option.

-b | -B [filename] -nb | -NB (no brief statistics - this is the default)

Controls whether OASYS produces a file containing a brief summary of statistical information. The default file name is GUIDE_BRIEF. LIS.

-d1 | -D1

Includes minimum statistics about the file. Does not work with the ns option.

-d2 | -D2

Includes statistical information helpful in estimating correct file sizing. This is the default. Does not work with the -ns option.

-d3 | -D3

Includes all information reported with -d2, plus additional information about distribution of data sizes. Does not work with the ns option.

-e | -E [filename] -ne | -NE (no errors)

Controls whether oas_analyzetbls produces a report of structural errors in the selected files. The default error list file name is GUIDE_ERRORS.LIS. OASYS assumes the -e option when the -o (output) option is present, and may not be specified at that time. You may, however, use the -ne option in combination with the -o option. Specifies the file that should receive a list of damaged groups. The default filename, if none is specified, is GUIDE_FIXUP.DAT. OASYS creates this file only if it detects errors.

-f | -F [filename]

-ha | -HA

Evaluates all hash algorithms (default). Note: the -h option has no effect if specified for a dynamic file. oas_analyzetbls Command Options

Option

Description

-h0 | -H0 -h1 | -H1 -i | -I [filename]

Evaluates algorithm 0. Note: the -h option has no effect if specified for a dynamic file. Evaluates algorithm 1. Note: the -h option has no effect if specified for a dynamic file. Directs the oas_analyzetbls utility to evaluate all of the files in the file named filename. GUIDE_INPUT.DAT is the default. The file should be composed of one file name per line. OASYS treats blank lines and lines that begin with an exclamation point as comments.

-l | -L [count]

If you specify the -d3 option, the oas_analyzetbls utility displays the keys for the largest records. The key appears in quotes and, if truncated, is followed by an asterisk (*). The -l option controls the number of records that display. The default value is three. Specifying a large number of records results in a significantly slower analysis.

© 2012 Onsystex Inc.

78

OASYS Administration for Windows 64 Bit Platforms

-m | -M new_modulo

Directs the utility to evaluate the effects of a different modulo upon the specified file. You must use this option in conjunction with the -h (hash test) option. This option has no effect when specified for a dynamic file.

-o | -O [filename]

Controls whether output is combined or directed to separate files. If you specify -o, OASYS directs all output to the file specified by filename. If you do not specify a file name, OASYS directs the output from oas_analyzetbls to “standard out” (usually, your terminal).

-p | -P page_length -np | -NP (no pagination)

Controls the display of oas_analyzetbls output when you specify the -o option and direct output to the terminal. Specify -np to scroll the output past with no pause. Specify -p pagelength to pause after displaying each page and prompt with the following message: “Press RETURN to continue...” The following responses are accepted at the prompt: • to display the next page. • “N” to continue with no pauses. • “Q” to quit the application. page_length is the number of lines per page in the screen display. The default value is 24. oas_analyzetbls Command Options (continued)

Option

Description

-r | -R [filename]

Specifies whether to produce a reporting file. The filename must be the Linux file specification of a OASYS database file, previously created by the CREATE.FILE command. Use this option to generate file statistics reports using OASQuery. Copy a dictionary for the report file from OASHOME\sysprog\D_OASYS_GUIDE. If you specify the -d3 option, the oas_analyzetbls utility displays the keys for the smallest records. OASYS displays the key in quotes. If the key is truncated, it is followed by an asterisk (*). The “-s count” option controls the number of records to appear in sorted order. The default value is three. Large values result in a significantly slower analysis. Controls whether OASYS includes statistical information about the file in the output file. If you do not specify a filename, OASYS uses GUIDE_STATS.LIS. (The -s (statistics) option is assumed when the -o (output) option is present, and may not be specified at that time.) You may use the -ne (no errors) option in combination with the -o option. oas_analyzetbls Command Options (continued)

-s | -S count

-s | -S [filename] -ns | -NS (no statistics)

oas_analyzetbls Output The oas_analyzetbls utility can create five output files. The following table lists these files. You may change the default names. File

Description

GUIDE_ADVICE.LIS GUIDE_ERRORS.LIS GUIDE_STATS.LIS GUIDE_BRIEF.LIS

Displays management advice about files that are poorly sized or corrupted. Lists structural errors detected in the files specified. Lists statistical information about the files specified. Displays summary information about selected files, including record counts, total size, used size and modulo. Contains a list of damaged groups that can be used as input for oas_fixtbls. This list can also be used to input file names/group numbers for dumpgroup/fixgroup. oas_analyzetbls Output Files

GUIDE_FIXUP.DAT

If you do not specify options, OASYS selects the default options: -a, -e, -f, and -s, and places the results in the default files. The oas_analyzetbls utility checks for existing output files. If there are existing output files, oas_analyzetbls appends a timestamp to the end of the existing file before it creates the current output file. The most current output files will not have this time stamp. OASYS does not overwrite output files generated in a previous analysis. As a result, you may accumulate a large number of files that you should purge periodically.

oas_analyzetbls Report File You can use the -r option of oas_analyzetbls to create a OASYS file containing statistical infor-mation about your database. To use the option, complete the following steps:

© 2012 Onsystex Inc.

Managing OAS Files

79

1. Create a OASYS file in the account where you are running oas_analyzetbls. 2. Copy the records from OASHOME\sysprog\D_OASYS_GUIDE to the dictionary of the file you created in step

1. 3. Execute oas_analyzetbls -r filename, where filename is the OASYS file you created in step 1.

The oas_analyzetbls utility creates statistical information in filename about the evaluated files. The records contain 62 attributes and are keyed by VOC entry name. You can use OASQuery or ECL commands, or write OASBasic code, to analyze the data and produce reports.

oas_analyzetbls Example The following example shows output from oas_analyzetbls executed against a directory that contains a damaged file:

Note: oas_analyzetbls works only if OASYS is running.

9.10.2 oas_analyzetbls_ndx Syntax: oas_analyzetbls_ndx{-x | -X} {1 | 2 | 3}, {index_names, ... | ALL} [-t template |-T template] filename

Description As with other OASYS file types, an index file could become corrupt due to hardware failures, the interruption of a write to the index file, or an incomplete write. The oas_analyzetbls_ndx utility checks for physical and logical corruption of an index file. If an index file is corrupt, OASYS displays a runtime error when a OASYS process tries to access the index. If the index file is associated with a recoverable file, a message is written to the sm.log. The oas_analyzetbls_ndx command creates two files, the GUIDE_XERROR.LIS and the GUIDE_STATS.LIS. GUIDE_ERROR.LIS lists any corruption found in the index file, and GUIDE_STATS.LIS list statistics about the index. If you have a corrupt index, you must rebuild it using the CREATE.INDEX and BUILD.INDEX commands. For more information and creating and building indexes, see Using OASYS. Note: Onsystex recommends deleting the index with the DELETE.INDEX ALL command. Using the ALL option deletes all alternate key indexes and the index file itself.

© 2012 Onsystex Inc.

80

OASYS Administration for Windows 64 Bit Platforms

Parameters The following table describes each parameter of the syntax. Parameter

Description

-x{1 | 2 | 3}

Determines the type of checking oas_analyzetbls_ndx performs: 1 – Perform physical checking 2 – Perform logical checking 3 – Perform physical and logical checking The index names you want oas_analyzetbls_ndx to check. Separate each index name with a comma, or enter ALL to check all indexes for the file. The template to use for output files. The default is GUIDE. The name of the data file containing the index. oas_analyzetbls_ndx Parameters

index_names -t template filename

Example The following example illustrates the contents of the GUIDE_XERROR.LIS file when oas_analyzetbls_ndx detects corruption:

The following table describes the column heading that display in output for the X_STATS.LIS file. Column Heading

Description

Index name F-type V-type

Name of the index. Type of attribute indexed: D for data attribute, V for a virtual attribute. Value code for the attribute. S for singlevalues, M for multi-valued or multisubvalued. Type of index: Txt for text, Num for numeric. X_S TATS .LIS Display

K-type

© 2012 Onsystex Inc.

Managing OAS Files

Column Heading

Description

Nulls

“Yes” indicates that empty strings are indexed. “No” indicates that empty strings are not indexed. “Yes” indicates that duplicate keys are allowed in the alternate key index. “No” indicates that duplicate keys are not allowed. The attribute location for alternate key indexes built on data attributes (D-type) or the virtual attribute definition for alternate key indexes built on virtual attributes (V-type). X_S TATS .LIS Display (continued)

Dups F-No/VF-expr

81

9.10.3 oas_validatetbls Syntax: oas_validatetbls [-Y | -y] [-H | -h block address] [-O | -o block address]

Description The oas_validatetbls command, like oas_analyzetbls, detects file corruption. Although oas_validatetbls does not produce as much information as oas_analyzetbls, and does not produce the damaged group list for repair, oas_validatetbls runs much more quickly, runs with OASYS down, and can be used for a rapid scan of files.

Parameters: The following table describes each parameter of the syntax. Parameter

Description

[-Y | -y]

Writes the file name and @ID of damaged records to a file called \OAS_Tmp\vrfy2.pid, where pid is the process ID of the process that executed oas_validatetbls. Bypasses checking the block whose hexadecimal address is block address. This option allows you to bypass a single damaged block, if you know its address, and examine the rest of the file. Same as -h option, but -o allows you to bypass a block in the overflow portion of a dynamic file. oas_validatetbls Parameters

[-H | -h block address]

[-O | -o block address]

The following example shows typical output from oas_validatetbls on files that are not damaged:

© 2012 Onsystex Inc.

82

OASYS Administration for Windows 64 Bit Platforms

The next example shows output from oas_validatetbls on a damaged file:

9.11

OAS Recovery Tools OASYS includes the following commands to recover corrupted hashed files: oas_dumpgroup- Use this command to unload complete and valid records from a damaged group, separating valid records from damaged records. oas_fixgroup- Use this command to clear records from a damaged group and to reload and rebuild the group with the valid records unloaded by dumpgroup. oas_fixtbls- Use oas_fixtbls in conjunction with oas_analyzetbls. oas_analyzetbls provides a FIXUP.DAT file that lists corrupt files and groups. oas_oas_fixtbls uses FIXUP.DAT to unload, clear, and rebuild the damaged groups.

9.11.1 oas_dumpgroup Syntax: oas_dumpgroup filename group.no [-doutputfile] [-p]

Description The system-level dumpgroup command unloads readable records from a group you specify in a OASYS file. If the file was corrupted, dumpgroup unloads complete, valid records, leaving behind any information it cannot read. © 2012 Onsystex Inc.

Managing OAS Files

83

Parameters The following table describes each parameter of the syntax. Parameter

Description

filename

Specifies the name of the file containing groups to be dumped.

group.no

Specifies the number of the group to dump. The output from either oas_analyzetbls or oas_validatetbls identifies groups that are damaged. Use this infor-mation to select groups to process.

[-doutputfile]

Specifies the name of a file that contains the readable records from the dumped group, in an uneditable form. If you do not specify the -d parameter with an outputfile, the output prints to screen. To load outputfile back into the file, use fixgroup. Note: No space is allowed between -d and outputfile.

[-p]

Converts nonprinting field markers to printable characters in editable output file. This option is only valid if -d is used. Parameters of dumpgroup Command

If you execute oas_dumpgroup without specifying an output file, the output simply displays on the screen. You will not be able to use that output to verify records or repair the damaged group. If you do specify an output file, OASYS places the records in uneditable form, suitable for reloading, into the output file. OASYS also creates a directory within your current account for each dumped group. The directory is named FILE_GROUP, where FILE and GROUP are the file name and group number you specify on the command line. This directory contains an ASCII file for each record, so that you can check them for consistency before reloading the damaged file. Warning: When you use the -d option, make sure you name your output file with a name that does not already exist in your account name. If you specify a duplicate name, the preexisting file may be overwritten.

9.11.2 oas_fixgroup Syntax: oas_fixgroup filename group.no [-iinputfile] [-k] The system level oas_fixgroup command reloads a hashed file group based on a file created by the dumpgroup command. The following table describes each parameter of the syntax. Parameter filename

Description Specifies the name of the file to repair.

group.no [-iinputfile]

Indicates the identifying number of the damaged group. Specifies the name of the file created by dumpgroup. If you do not specify an input file argument, fixgroup simply clears the specified group, without reloading it. Note: No space is allowed between -i and inputfile. Allows fixgroup to reload the damaged records from inputfile without zeroing the group first. This option may be useful if the group was updated since dumpgroup was executed. However, for best results, do not allow access to a file while it is being repaired, and clear the damaged groups rather than using the -k

[-k]

© 2012 Onsystex Inc.

84

OASYS Administration for Windows 64 Bit Platforms

option. fixgroup Parameters

Warning: If you execute oas_fixgroup without an input file argument, OASYS clears the damaged group. Be sure that you have saved the readable records with oas_dumpgroup before clearing the group. If you clear the damaged group and you have not saved the readable records, the data in that group is lost. The syntax for clearing a group without reloading it is:

OASYS displays a warning message before clearing the group, as shown in the following example

9.11.3 oas_fixtbls Syntax: oas_fixtbls {-t | {-dfilename | -k | -p | -f}} [-mfilename] [-wdirectory] [-ifilename | filename group.no] The system-level oas_fixtbls command repairs damaged groups in OASYS files by clearing the group and optionally restoring readable records to the group. Use oas_fixtbls in conjunction with the oas_analyzetbls utility. Do not let users access files while oas_fixtbls is running because you could lose records. The following table describes each parameter of the oas_fixtbls syntax. Parameter

Description

{-t}

Direct all output to the terminal only. Each readable record is described in a new line that includes the record key and the record length. All attributes in the record appear on separate lines, each line indented by two spaces. Special and nonprintable characters are translated as follows: Attribute M ark - New line Value M ark - “ } ” Subvalue M ark - “ | ” Text M ark - “ { ” Non-printables - “ . ” The -t and -d parameters are mutually exclusive and cannot be used together.

{-dfilename}

A file specification is required. For static files, dumps the readable records to this file in uneditable format. For dynamic files, OASYS creates this file, but dumps the actual records to a file in \temp. With the -d option, OASYS also writes the records, in readable format, to a directory in your current OASYS account. This directory contains an ASCII file for each readable record in the group. The records are in a format suitable for editing. To repair any file, you need both the -d and f options.

{-k}

If you specify the -k option with the -d option, OASYS does not clear the damaged groups. This has the effect of dumping the readable records for examination, but leaving the file corrupt. If you specify the -d and -f option along with the -k option, OASYS repairs the file and returns the readable records to the group. Any unreadable records that OASYS did not dump remain in the file as well.

{-p}

If you specify the -p option with the -d option, OASYS trans-lates all non-printing characters and characters with special meaning to OASYS. This translation applies to the editable ASCII files created by the -d option. If you do not specify the - p option, only attribute marks are translated. © 2012 Onsystex Inc.

Managing OAS Files

85

oas_fixtbls Command Parameters

Parameter

Description

{-f}

If you specify the -f option with the -d option, OASYS clears the damaged group and restores the records that were dumped back into the group, creating a fixed file with all readable data restored. You must specify the -d option with the -f option. OASYS writes all error messages and statistics to the file you specify, instead of the terminal. OASYS creates the work files that are generated in the directory you specify. OASYS uses this file as the source of the names of damaged files and groups to be repaired. If you do not use this option or the {filename group.no} option, OASYS uses the GUIDE_FIXUP.DAT file under the current directory. This option is mutually exclusive with {filename group.no}.

[-mfilename] [-wdirectory] {-ifilename}

{filename group.no}

The file name and group number that contains the corruption. If you do not use this option or the {-ifilename} option, OASYS uses the GUIDE_FIXUP.DAT file under the current directory. This option is mutually exclusive with the {-ifilename} option oas_fixtbls Command Parameters (continued)

How oas_fixtbls Works with Static Files When you run oas_fixtbls with the -t option on a static file, OASYS displays the readable records from the file and group to the terminal. OASYS does not clear or repair the group. You can supply the names of damaged files and groups from the command line or from an input file. The default input file is GUIDE_FIXUP.DAT. When you run oas_fixtbls with -dfilename on a static file, OASYS creates: An NTFS directory or directories for the files and groups being repaired. If only one group in a file is damaged, the directory is named FILE_GROUP, where FILE is the damaged file (from GUIDE_FIXUP.DAT or oas_validatetbls) and GROUP is the damaged group. If several groups in a file are damaged, OASYS creates a directory named FILE_dir. Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged group. Each file name is the key for the corresponding OASYS record. These records are in a format suitable for editing. Each FILE_dir contains a subdirectory for each damaged group in FILE. The name of each subdirectory is the group number of the damaged group. Each subdirectory contains an ASCII file for every readable record in the damaged group. Each file name is the key for the corresponding OASYS record. These records are in a format suitable for editing. A file, with the name you specify on the command line, that contains the records oas_fixtbls could read, in uneditable format. This file is used to reload the records into the damaged groups after the groups are cleared. Note: If you specify the -p option, oas_fixtbls translates nonprinting characters in the records when it creates the “editable” files. Otherwise, OASYS translates only attribute marks to new lines. When you run oas_fixtbls with the -d and -f options on a static file, OASYS reloads the records into the damaged groups, taking them from the file you specify on the command line. Unless you specify the -k option, oas_fixtbls clears the groups, removing all contents, before reloading the data. If you specify the -k option, OASYS adds the

© 2012 Onsystex Inc.

86

OASYS Administration for Windows 64 Bit Platforms

records back, but does not clear any data from the group. Note: It is possible to run oas_fixtbls in two steps, one to dump the records for review and the second to repair the file. To dump the records only, run oas_fixtbls with the -d option, but without the -f option. Unless you specify the -k option, running oas_fixtbls with the -dfilename deletes the readable data from the specified groups when it creates output. To repair the file, run oas_fixtbls with both -d and -f options.

How oas_fixtbls Works with Dynamic Files When you execute oas_fixtbls with the -d option on a dynamic file, OASYS creates the following: An NTFS directory located in \temp for each file-group combination being repaired. The directories are named FILE_GROUP where FILE is a damaged file (from GUIDE_FIXUP.DAT or oas_validatetbls) and GROUP is a damaged group. If several groups in a file are damaged, OASYS creates a directory for each damaged group. Each FILE_GROUP directory contains an ASCII file for every readable record in the damaged group. Each record’s name is the key for the corre-sponding OASYS record. These records are in a format suitable for editing. A file containing the records oas_fixtbls could read, in uneditable format suitable for reloading into the group after it has been cleared. This file is located in \temp (or in the directory identified by the OAS_Tmp environment variable) and is named ud_dp_pid, where pid is the process ID of the process that executed oas_fixtbls. Note: If you specify the -p option, oas_fixtbls translates nonprinting characters in the records when it creates the editable files. Otherwise, OASYS translates only attribute marks to new lines. When you run oas_fixtbls with the -d and -f options on a dynamic file, OASYS reads the file you specify with the -d option on the command line and also reads the uneditable file of dumped records. OASYS then reloads the records from that file into the damaged groups. Unless you specify the -k option, oas_fixtbls clears the groups, removing all contents, before reloading the data. Otherwise, OASYS adds the records back, but does not clear any data from the group. Note: You can run oas_fixtbls in two steps, one to dump the records for review and the second to repair the file. To dump the records for review, run oas_fixtbls with the -d option, but without the -f option. (You do not need to use -k for dynamic files. For dynamic files, running oas_fixtbls with -dfilename and not -f does not delete the readable data from the specified groups when it creates output.) To repair the file, run oas_fixtbls with both the -d and -f options. If you specify the same file name with -d in both the review and repair steps, OASYS will prompt whether or not to clear the damaged groups.

9.12

Detection and Repair Examples The following example shows typical output from running oas_analyzetbls against a damaged file:

© 2012 Onsystex Inc.

Managing OAS Files

87

The output displays statistics and then reports which groups are damaged. In this case, group 1 is damaged. The next example shows the output from dumping the records from the damaged group with oas_dumpgroup: C:\Onsystex\oas61\bin\oas_dumpgroup TEST 1 -dhold_file 2 records dumped for group 1 The records can be found under directory Check them before fixing the file

C:\TEMP\TEST_1

At this point you can review the directory CLIENTS_1, containing a file for each record that was dumped from group 1.You should verify that the data in each record is valid. The following example shows the output from rebuilding the damaged group with oas_fixgroup:

C:\Onsystex\oas61\bin\oas_fixgroup TEST 1 -dhold_file 1 block (including the group header) of group 1 was made empty 2 records written to file TEST

© 2012 Onsystex Inc.

88

9.13

OASYS Administration for Windows 64 Bit Platforms

How to Use oas_analyzetbls The steps listed below provide guidelines for effectively using the oas_analyzetbls utility.

1. Monitor File Integrity with oas_analyzetbls You should execute oas_analyzetbls against your database at regular intervals, as well as when you have had a system crash. You can set up shell scripts to run oas_analyzetbls at specified intervals on specified lists of files, or you can simply execute the oas_analyzetbls command in each OASYS account. You can execute oas_analyzetbls against static hashed files at any time, and schedule oas_analyzetbls to run on dynamic files at a time when the system is idle or only lightly loaded. Note: The oas_analyzetbls utility requires exclusive access to process any dynamic file. There are two considerations: first, if you run oas_analyzetbls against such files while the system is under heavy load, oas_analyzetbls may be unable to process the majority of your files. Second, if oas_analyzetbls is able to gain exclusive access to a file, OASYS blocks other access to that file until oas_analyzetbls completes.

2. Check Error Output (GUIDE_ERRORS.LIS) Use the following information to determine what action to take, depending on the error output.

No Errors If there are no errors, proceed to step 5.

Partially Allocated Block Messages Partially allocated block messages are not false error reports; they indicate an out-ofsynch condition in a dynamic file, but they do not mean that the file must be fixed immediately. Users can continue to access the file; this will not cause damage. Complete the repair at a convenient time using the procedure in step 3. Partially allocated block messages look like:

Other oas_analyzetbls Error Messages oas_analyzetbls produces many messages besides the one discussed above. If you see error messages pertaining only to static files, or if you see other error messages pertaining to dynamic files, proceed to step 3.

3. Repair Damaged Files Complete the following steps: 1. Back up the damaged file(s)- If time and space permit, Onsystex strongly recommends you back up (or simply

make a copy of) the damaged files before proceeding. In the event of a system failure during the repair process, you will be able to restore from the backup copies and repeat the procedures rather than attempting to recover a partially-completed repair. DO NOT ALLOW USERS TO ACCESS YOUR FILES WHILE YOU ARE BACKING THEM UP! 2. Repair the damaged groups- After oas_analyzetbls completes, you can execute either oas_fixtbls or © 2012 Onsystex Inc.

Managing OAS Files

89

dumpgroup/fixgroup to repair the damaged groups. In either case, the process overview is: dump the readable records from a damaged group, clear the group, and then reload all readable records back into the group. Tip: Onsystex recommends that you not use the -k option with oas_fixtbls or with fixgroup. The -k option lets you reload the readable records without clearing the group. However, you may encounter additional errors if you do not clear the group. Use oas_fixtbls or fixgroup without -k; this procedure automatically clears the group before reloading the readable records. Be sure no users are accessing your files before repairing damaged groups. The dumpgroup command does not obtain exclusive oas_fixtbls/fixgroup only lock the file when the records are being written back to a group. Concurrent access to the file could make corruption worse. 3. Verify the repair- Rerun oas_analyzetbls after the repair is complete to verify that the errors are fixed. If they are not, or if additional groups are damaged, repeat the previous step.

4. Back Up the Repaired Files Back up any files you have just completed repairing.

5. Continue Processing If you shut OASYS down to repair files, start it again before allowing users to log in.

9.14

Error Messages This section lists error messages users may see and provides information about the meaning of them. Some of the messages are generated by the oas_analyzetbls command and others are generated by the oas_validatetbls command.

9.14.1 File Access Messages File access messages are similar to the following example:

All of these messages indicate that oas_analyzetbls or oas_validatetbls did not process the file because it was unable to obtain an exclusive lock on the file. Note: These messages display only at the terminal. They are not logged in any file.

9.14.2 Block Usage Messages Block usage messages are similar to the following example:

These indicate that a block is found to be referenced by more than one link, which should not occur. These messages indicate damage.

A block has been found that is not in the global free chain and is not used by any group. This error can be reported when oas_analyzetbls or oas_validatetbls encounters a corrupt block, and is therefore unable to check © 2012 Onsystex Inc.

90

OASYS Administration for Windows 64 Bit Platforms

blocks linked through the corrupted one.

9.14.3 Group Header Messages Group header messages are similar to the following example:

These messages indicate damage.

9.14.4 Header Key Messages Header key messages are similar to the following example:

These errors indicate that key area size or number of keys have been corrupted in a group header.

9.14.5 Other Header Messages There are a number of other header messages, as shown in the following examples:

The group number recorded in the block header does not match the group being checked.

The offset (link to next disk block) is not a multiple of the block size, or, for a dynamic file, the offset does not indicate an overflow file offset.

A data position in a group header is damaged.

© 2012 Onsystex Inc.

Managing OAS Files

91

Each group header has an area that stores offset-record length pairs, which are sorted by offset. Each offset of a record equals the offset of the previous record plus its length. If these conditions are not met, corruption results, and some or all of the previous messages display.

The counter that records the number of bytes available in a block does not agree with the actual number of bytes in the block.

The actual record length does not match the offset-length pair of the record.

9.14.6 Free Block Messages

The actual count of free blocks for a group does not match the counter in the group header.

A block is linked to the free block list but not correctly initialized. Blocks linked to the free list should have no bytes used and should be “normal” blocks (not header blocks).

9.14.7 Long Record Messages “Long” records are records which span more than one block. Messages about problems with these are similar to the following example:

© 2012 Onsystex Inc.

92

OASYS Administration for Windows 64 Bit Platforms

In OASYS hashed files, a long record always starts from the beginning of a level one overflow block, which is flagged as “STARTLONG.” Each intermediate block is flagged as “MIDLONG,” and the last block is flagged as “ENDLONG.” If the length of a long record does not match header information, or if any flag in its data blocks is incorrect or the pointer in the chain gets broken, oas_analyzetbls and oas_validatetbls report messages like the preceding ones.

9.14.8 Dynamic File Messages

Header information for overflow part files has been damaged.

© 2012 Onsystex Inc.

Part

10

94

10

OASYS Administration for Windows 64 Bit Platforms

Managing OAS Locks This chapter outlines file, record, and system resource locking within OASYS, describes tools for listing locks and listing the contents of the wait queue, and describes procedures for releasing locks that remain set when a process exits OASYS.

10.1

The OASIS Global Lock Manager The Global Lock Manager (OASYS Locking) is an internal software module that is linked into each oas process to manage logical record locks.

10.1.1 How OASIS Global Locking Works OASYS manages local lock tables for each oas process and a shared global lock table in shared memory, which can be accessed by multiple oas processes. The lock tables are hashed tables containing linked lists, which contain lock nodes. When a oas process locks a record, OASYS writes the file name, record ID, and lock mode to both the local lock table and the global lock table. When a oas process requests a lock, OASYS first searches that local lock table for the oas to see if that process is holding the lock, then the global lock table to see if another oas process is holding the lock.

OASYS Locking oasconfig Parameters There are four oasconfig parameters which control the size of the shared lock table and the memory OASYS allocates for each memory request.

OAS_NoGlobalSlots This parameter defines the number of hash buckets system-wide, used to hold the lock names in shared memory. This setting directly affects performance. Normally, the default value of this parameter should not be changed. However, if you notice significant degradation in performance, or your application intensively accesses specific files, you should increase this parameter. The value should be the closest prime number to OAS_MaxUsers * 3.

OAS_NoLocalSlots This parameter determines the number of hash buckets for the local lock table, and is highly application dependent. If the application requires a large number of locks in one transaction (more than 20), this setting should be increased from the default of 23. The setting should be the closest prime number to the maximum number of locks per transaction.

OAS_NoBlockingNode This parameter defines the number of lock nodes allocated for each memory request, and is highly application dependent. If your application requires a large number of locks in one transaction, this setting should be increased to the maximum number of locks per transaction * 2.

OAS_BytesperNode This parameter specifies the segment size for each shared memory segment required for OASYS Locking. The maximum number of segments is 16. Large application environments require a larger size. The default value is 10. OAS_BytesperNode must be greater than 4096 and less than OAS_MaxShmSize. The formula for determining OAS_MaxShmSize is OAS_MaxUsers * maximum number of locks per transaction * 512. OAS_MaxShmSize should be a multiple of 4096.

© 2012 Onsystex Inc.

Managing OAS Locks

10.2

95

Locking in OasBasic A series of OASBasic commands enable users to set read-only locks and exclusive locks on OASYS files and their contents.

10.2.1 How Locks Work OASBasic locks are advisory rather than physical, meaning that they inform other users of a file or record that the file or record is in use, rather than explicitly preventing access. You can set exclusive locks or shared (read-only) locks.

Exclusive Locks (U Type) Exclusive (U) locks are respected by all lock-checking commands except those that write and delete. Exclusive locks are set by “U” commands, for instance READU, MATREADU, and RECORDLOCKU.

Shared Locks (L Type) Shared, or read-only, locks can be shared by more than one user. These locks are set by “L” commands, for instance READL, MATREADL, RECORDLOCKL. A record locked with an L lock can be accessed for reading by another “L” command, but cannot be accessed by “U” commands.

Writing and Deleting WRITE and DELETE commands execute regardless of lock status. WRITEU, WRITEVU, MATWRITEU, and DELETEU retain locks set by previous commands. To prevent multiple updates to records, all WRITE and DELETE commands should be preceded by a lock-setting command like READU.

10.2.2 Locking Commands The following table lists OASBasic commands for setting and releasing locks. Command

Description

FILELOCK

Locks the data or dictionary portion of a OASYS file against access by commands that check locks. Unlocks a file previously locked with the FILELOCK command. Assigns the values found in successive attributes of a record to corresponding elements of a matrix and sets a read-only lock on the record.

FILEUNLOCK M ATREADL M ATREADU

Assigns the values found in successive attributes of a record to corresponding elements of a matrix and sets an exclusive lock on the record.

M ATWRITE

Writes successive elements of a matrix to the corresponding attributes of a record and releases locks previously set on the record. Writes successive elements of a matrix to the corresponding attributes of a record without releasing locks previously set on the record.

M ATWRITEU READBCKL

Retrieves one record from a B+ tree based alternate key index and places a readonly lock on the record. Each subsequent READBCKU retrieves the previous record in the index.

READBCKU

Retrieves one record from a B+ tree based alternate key index and places an exclusive lock on the record. Each subsequent READBCKU retrieves the previous record in the index. Retrieves one record from a B+ tree based alternate key index and places a readonly lock on the record. Each subsequent READBCKU retrieves the next record in the index.

READFWDL

© 2012 Onsystex Inc.

96

OASYS Administration for Windows 64 Bit Platforms

READFWDU

Retrieves one record from a B+ tree based alternate key index and places an exclusive lock on the record. Each subsequent READBCKU retrieves the next record in the index. Reads a specified record from a file, assigning the record contents to a dynamic array and setting a read-only lock on the record. OAS Basic Commands for Locking Files and Records

READL

Command

Description

READU

Reads a specified record from a file, assigning the record contents to a dynamic array and setting an exclusive lock on the record.

READVL

Reads a specified attribute of a specified record, assigning the attribute value to a variable and setting a read-only lock on the record.

READVU

Reads a specified attribute of a specified record, assigning the attribute value to a variable and setting an exclusive lock on the record.

RECORDLOCKL RECORDLOCKU

Sets a read-only lock on a specified record in a specified file. Sets a read-only lock on a specified record in a specified file.

RELEASE

Releases record locks without updating records.

WRITE

Writes an expression to a record, releasing locks previously set by READU, READL, READVU, and M ATREADU.

WRITEU

Writes an expression to a record without releasing any previous locks on the record. Writes an expression to an attribute of a record, releasing previous update locks.

WRITEV WRITEVU

10.3

Writes an expression to an attribute of a record without releasing previous locks on the record. OAS Basic Commands for Locking Files and Records (continued)

Resource Locks In both OASYS and OASBasic, you can reserve a system resource by setting a semaphore lock on it. Note: Certain device handling commands (T.ATT, T.DET, LINE.ATT, and LINE.DET) set semaphore locks. The following table lists commands for explicitly reserving system resources from the ECL prompt. Command

Description

UNLOCK

Releases system resources reserved by the LOCK command. (OASYS does not automatically release these resources when a program terminates.) This command is not needed to release file and record locks. Reserves a system resource for exclusive use.

LOCK (ECL and OASBasic)

Locking S ystem Resources

Note: Although the LOCK and UNLOCK commands enable users to set and release semaphore locks, OASYS does not necessarily use system-level semaphores to control access to system resources. The output from LIST. LOCKS and oas_ipcstatus may not appear to be consistent, but OASYS is functioning correctly.

© 2012 Onsystex Inc.

Managing OAS Locks

10.4

97

Listing Locks OASYS offers three commands for listing record and file locks, semaphore locks on system resources, and processes waiting to get locks.

10.4.1 LIST.READU The ECL LIST.READU command enables any user with access to the ECL prompt to display a list of file and record locks set on the system. Syntax: LIST.READU [user_number | ALL | FILENAME filename | USERNAME user_name] [DETAIL]

Parameters The following table describes each parameter of the syntax. Parameter

Description

user_number ALL FILENAM E filename

Displays all locks held by the user number you specify Displays all currently active locks. Displays all active locks associated with the file name you specify. If the file name does not reside in the current account, nothing is displayed. Displays all active locks associated with the user name you specify. Displays detailed information. LIS T.READU Parameters

USERNAM E user_name DETAIL

Examples The following example illustrates the output from the LIST.READU command when you do not specify any options.

The next example illustrates the output from the LIST.READU command when you specify a user number. The user number can be found in the output from the LIST.QUEUE and LIST.READU commands under the UNBR column.

The next example illustrates output from the LIST.READU command when you specify a user name.

The final example illustrates output from the LIST.READU command when you specify a file name.

LIST.READU Display © 2012 Onsystex Inc.

98

OASYS Administration for Windows 64 Bit Platforms

The following table describes the output from the LIST.READU command. Column Heading

Description

UNO UNBR UID UNAM E TTY

A sequential number OASYS assigns to the oas process that set the lock. The process ID of the user who set the lock. The user ID of the user who set the lock. The login name of the user who set the lock. The terminal device of the user who set the lock. LIS T.READU Display

Column Heading

Description

FILENAM E RECORD_ID M

The file name in which the record is locked. The record ID of the locked record. The type of lock. X indicates an exclusive lock. S indicates a shared lock. Time the lock was set. Date the lock was set. LIS T.READU Display (continued)

TIM E DATE

10.4.2 LIST.LOCKS Use the ECL LIST.LOCKS command to display semaphore-type locks that reserve system resources for exclusive use. These locks can be set individually with the LOCK command. They are also set by other ECL commands, including T.ATT. Syntax: LIST.LOCKS The following examples shows the LIST.LOCKS command and its output:

Note: If you need to clear a semaphore lock that has been left set, you need to note the UNBR and the lock number for the lock. In the example, the lock number is 1 for the lock displayed.

10.4.3 LIST.QUEUE The ECL LIST.QUEUE command displays a list of all processes waiting to get locks. If a process is waiting for a lock, LIST.QUEUE displays information about the holder of the lock and processes waiting for the lock. Locks are set by each oas process through the general lock manager (OASYS Locking) module. Syntax: LIST.QUEUE [USERNAME user_name | FILENAME filename | user_number][DETAIL]

© 2012 Onsystex Inc.

Managing OAS Locks

99

10.4.4 Parameters The following table describes each parameter of the syntax. Parameter USERNAM E user_name FILENAM E filename user_number

Description Lists all locks the user is waiting for. user_name is the operating system logon name. Lists all users waiting for locks for the file name you specify. Lists all locks for which the user_number is waiting. The user number can be found in the UNBR column of the LIST.READU and LIST. QUEUE output.

DETAIL

Displays a detailed listing. LIS T.QUEUE Parameters

The following example illustrates the output from the LIST.QUEUE command when you do not specify any parameters.

The next example illustrates the LIST.QUEUE output when you specify a user name:

The next example illustrates the LIST.QUEUE command output when you specify a file name:

The final example shows the output from the LIST.QUEUE command when you specify a user number:

10.4.5 LIST.QUEUE Display The LIST.QUEUE display in the previous examples use the default display. Infor-mation about the owner of the lock is listed above the line. Information about processes waiting for the lock is listed below the line, sorted by

© 2012 Onsystex Inc.

100

OASYS Administration for Windows 64 Bit Platforms

the date and time the process requested the lock. The following table describes the LIST.QUEUE default display for the owner of the lock. Column Heading FILENAM E RECORD_ID

Description The name of the file holding the lock. The record ID holding the lock.

M OWNER UNBR

Type of lock held. X is an exclusive lock, S is a shared lock. The user name of the owner of the lock. The process group ID (pid) of the user who set the lock.

UNO

Column Heading TTY TIM E DATE

The sequential number OASYS assigns to the oas process for the owner of the lock. LIS T.QUEUE Owner Display

Description The Terminal device of the user owning the lock. The time the lock was set. The date the lock was set. LIS T.QUEUE Owner Display (continued)

The next table describes the LIST.QUEUE display for the processes waiting for locks. Column Heading FILENAM E RECORD_ID

Description The name of the file for which a lock is requested. The record ID of the record for which a lock is requested.

M

The type of lock requested. X is an exclusive lock, S is a shared lock. The user name of the process waiting for a lock. The process ID (pid) of the user waiting for a lock. The sequential number OASYS assigns to the oas process waiting for a lock. The terminal device of the user waiting for a lock. The time the lock was requested. The date the lock was requested. LIS T.QUEUE Waiting Display

WAITING UNBR UNO TTY TIM E DATE

The following example illustrates the LIST.QUEUE display when you specify the DETAIL option:

The following table describes the owner information the LIST.QUEUE command displays when you specify the DETAIL option. Column Heading FILENAM E RECORD_ID M

Description The name of the file for which a lock is held. The record ID of the record for which a lock is held. The type of lock held. X is an exclusive lock, S is a shared lock.

© 2012 Onsystex Inc.

Managing OAS Locks

INBRH INBR DNBR OWNER UNBR UNO TTY TIM E DATE

101

The high integer of the inode of the file holding the lock. The low integer of the inode of the file holding the lock. Used in conjunction with the INBR to define the file holding the lock at the operating system level. The user name of the process holding the lock. The process ID (pid) of the user holding a lock. The sequential number OASYS assigns to the oas process holding a lock. The terminal device of the user holding a lock. The time the lock was set. The date the lock was set. LIS T.QUEUE Detail Display

The following table describes the waiting information the LIST.QUEUE command displays then you specify the DETAIL option. Column Heading FILENAM E RECORD_ID

Description The name of the file for which a lock is requested. The record ID of the record for which a lock is requested.

M INBRH INBR

The type of lock held. X is an exclusive lock, S is a shared lock. The high integer of the inode of the file holding the lock. The inode of the file for which a lock is requested. LIS T.QUEUE Detail Display

Column Heading DNBR WAITING

Description Used in conjunction with the INBR to define the file for which a lock is requested at the operating system level. The user name of the process requesting a lock.

UNBR

The process ID (pid) of the user requesting a lock.

UNO

The sequential number OASYS assigns to the oas process requesting a lock. The terminal device of the user requesting a lock.

TTY TIM E DATE

© 2012 Onsystex Inc.

The time the lock was requested. The date the lock was requested. LIS T.QUEUE Detail Display (continued)

102

10.5

OASYS Administration for Windows 64 Bit Platforms

Commands for Clearing Locks If you break out of a process that is running, if a process is killed, or if a system resource is not unlocked by a OASBasic program, locks can remain after they should have been released. If a lock remains set, other users experience difficulty accessing a record, file, or resource. As other processes attempt to access the locked item, message queue congestion can result if the process that set the lock is no longer logged on. The typical manifestations of unneeded locks are: Users cannot perform expected operations on a file or record. Over a lengthy period of time, users receive messages indicating that the file or record is locked. Performance suffers, either because the item that is locked is heavily used or because a message queue has become clogged due to the lock. Batch jobs attempting to access a locked item fail. Specific symptoms depend on the type of lock and the frequency of usage of the locked item. OASYS includes two commands that enable an administrator with root access to release locks held by other users.

10.5.1 SUPERCLEAR.LOCKS Command SUPERCLEAR.LOCKS enables you to release semaphore locks on system resources (such as tape drives). Syntax: SUPERCLEAR.LOCKS usrnbr [locknum] The following table describes each parameter of the syntax. Parameter usrnbr [locknum]

Description The process ID (pid) that holds the lock. This number is UNBR in the LIST.LOCKS display. The number of the locked system resource. If you do not specify locknum, the command clears all locks set by usrnbr. S UPERCLEAR.LOCKS Parameters

The following example shows the effects of SUPERCLEAR.LOCKS:

10.5.2 SUPERRELEASE Command The SUPERRELEASE command enables you to release locks you have set on records. Syntax:

© 2012 Onsystex Inc.

Managing OAS Locks

103

SUPERRELEASE usrnbr [inbr devnum] [record.id] The following table describes each parameter of the syntax. Parameter usrnbr [inbr devnum]

[record.id]

Description The process ID that holds the lock. This number is UNBR in the LIST.READU display. The inode number and device number for the file that has the lock set. These numbers are INBRH, INBR and DNBR in the LIST.READU display. The identifier for the record to clear. This number is RECORD ID in the LIST.READU display. S UPERRELEAS E Parameters

Note: If you execute SUPERRELEASE and specify only usrnbr, you release all record locks held by the process ID corresponding to usrnbr. The following example shows the effect of SUPERRELEASE:

10.6

Procedure for Clearing Locks Complete the following steps to identify and clear unneeded locks.

1. Check for Unneeded Locks Use the OASYS LIST.READU and LIST.LOCKS commands to display the locks currently set on the system. Use LIST.QUEUE to identify locks for which processes are waiting. Note locks that meet the following criteria: They are set on files or records that users cannot currently access. They have been set for a long period of time (shown by the time and date on the list). They were set by users who are not currently on the system.

2. Note Information for Clearing For record locks, note UNBR, INBRH, INBR, DNBR, RECORD NO. For semaphore locks, note UNBR and lock number. To clear record locks, proceed to step 3. To clear semaphore locks, proceed to step 4.

3. Release Record Locks Log on as an Administrator and use the OASYS SUPERRELEASE command to clear record locks. If possible, specify only a UNBR to clear all the locks belonging to a process ID. If you have semaphore locks to clear, proceed to step 4. Otherwise, proceed to step 5. Warning: Some situations that retain locks can also cause file corruption (for example, a oas process is inadvertently killed). Consider checking the file with oas_analyzetbls to make certain it has not been corrupted.

© 2012 Onsystex Inc.

104

OASYS Administration for Windows 64 Bit Platforms

4. Clear Semaphore Locks Log on as an Administrator and clear semaphore locks with the SUPERCLEAR.LOCKS command.

© 2012 Onsystex Inc.

Part

11

106

11

OASYS Administration for Windows 64 Bit Platforms

Managing OAS Users This chapter outlines considerations for adding OASYS users to your Windows system, and describes how to use OASYS commands to view user processes for troubleshooting, to remove user processes when needed, and to start and stop OASYS.

11.1

Adding Users To access OASYS on your system, each user needs a valid Windows account, including an MS-DOS logon ID and password. In Pick® systems, where each logon account must be a Pick® account, shared logon IDs and passwords are common. In contrast, OASYS allows multiple relationships between user logon IDs and OASYS accounts. A user may have access to more than one OASYS account, and many users can access a single OASYS account using separate logon IDs. Therefore, Onsystex strongly recommends you set up a separate Windows account for each user. Onsystex recommends separate logon IDs for the following reasons: It is easier to identify processes and locks belonging to an individual user, which facilitates troubleshooting. Using separate logon IDs allows you to define your users’ responsibilities for protecting their passwords and your data.

11.1.1 User Groups When you add a user account to your Windows system, you can assign the user to one or more user groups. In contrast to Linux, Windows platforms allows a user to belong to many groups simultaneously, and allows access to objects based on all groups to which the user is assigned. When you install OASYS on your Windows system, the installation procedure sets permissions on the OASYS directory structure. OASYS grants permissions to three categories of users, Administrators, members of the OASYS group, and all other users. After you install OASYS, you must assign your OASYS users to the OASYS group. Note: Use User Accounts to create user accounts. Use Computer Management add users to groups, and assign User Rights. From the Start menu, click Control Panel then double-click User Accounts. Refer to your Windows documentation for further information.

11.1.2 Home Directories On Windows platforms, you can define a home directory for each logon ID. This directory is the user’s working directory when they log on. You are not required to define a home directory. If you wish, you can define the same home directory for a group of users, or create a separate one for each user. The home directory does not need to be a OASYS account. To define a home directory for a user, from the Start menu, double-click Adminis-trative Tools, and then doubleclick Computer Management. Double-click Users, double-click the user for which you are defining a home directory, and then click the Profile tab. The following dialog box appears:

© 2012 Onsystex Inc.

Managing OAS Users

107

Enter the path to the user’s home directory in the Local Path box in the Home folder section, then click OK.

11.1.3 Logon Scripts You can create a logon script that is executed whenever a user logs on to a Windows console or Telnet session. You must create the script in the directory identified by your Windows platform logon script path. If you specify the script in the User Environment Profile window, OASYS executes the script whenever the user logs on. To specify a logon script for a user, from the Start menu, double-click Adminis-trative Tools, and then doubleclick Computer Management. Double-click Users, double-click the user for which you are defining a home directory, and then click the Profile tab. The following dialog box appears:

© 2012 Onsystex Inc.

108

OASYS Administration for Windows 64 Bit Platforms

Enter the path to the user’s login script, enter the path where the logon script resides in the User Profile Path box, the script name in the Logon Script box, and then click OK.

11.2

Monitoring User Processes For troubleshooting purposes, it is often necessary to identify and monitor processes owned by a particular OASYS user.

11.2.1 OAS Commands OASYS includes a group of commands to display a list of current OASYS sessions, to display a list of users currently logged on to the system, and to display detailed information about process activity for a specific user, or for all users. These OASYS commands are summarized in the following table. OAS YS Command WHO LISTUSER listuser M YSELF

Description ECL command; displays a list of users currently logged on to the system, including users who are not OASYS users. ECL command; displays a list of current OASYS sessions. OASYS system-level command; enter at a M S-DOS prompt; displays the same information as the ECL LISTUSER command. ECL command; displays login ID for the current OASYS session. OAS YS Commands for Monitoring User Processes

© 2012 Onsystex Inc.

Managing OAS Users

109

Note: You do not need to log on as an Administrator to execute these commands. The following example shows the system response to the WHO, LISTUSER, and listuser commands. :W H O

M ario M ario

Console Console

13:11:42 27 Sep 2011 13:13:05 27 Sep 2011

:LISTU SER Effective users..:

oas

8 /8

2

oasSql Total 0

2

O ASN O U SR N B R U ID U SR N AM E U SR TY PE TTY 1 50512 197608 M arco oas pts/1 Console 2 55168 197608 M arco

oas

pts/2 Console

IP-AD D R ESS TIM E D ATE 13:11:42 27 Sep 2011 13:13:05 27 Sep 2011

Notice that the output of the WHO command includes the user name but not the process ID. Also, output from the LISTUSER command includes a series of identifications: OASNO (OASYS user number), USRNBR (the pid), UID (the user’s uid number), and USRNAME. Displaying further information about a OASYS process typically requires the pid (USRNBR).

11.3

Stopping User Processes OASYS includes commands that enable you to stop a user’s oas process if the process is hung, or if you need to stop OASYS while a user is still logged on. These commands are summarized in the following table. OAS YS Command oas_removeuser

Description First attempts to gracefully exit and allow a write in progress to complete. If the command is not successful in five seconds, force logs out a user, which may interrupt a write in progress, potentially causing file corruption. OAS YS Commands for Removing User Processes

You can log yourself out using the stopoas command, but you must log on as an Administrator to log out other users using stopoas. You must log on as an Administrator to execute oas_removeuser. Warning: Both of these commands can disrupt the consistency of your database, and oas_removeuser can also corrupt data. Do not use these commands should as a substitute for normal user logout.

11.3.1 Using TIMEOUT You can execute the ECL TIMEOUT command at the ECL prompt, in a LOGIN paragraph, or in a OASBasic program. TIMEOUT forces the current oas process to log out after a specified number of seconds. If you include TIMEOUT in the LOGIN paragraphs for your OASYS accounts, you can provide some improved security for terminals left idle. © 2012 Onsystex Inc.

110

OASYS Administration for Windows 64 Bit Platforms

Note: Be careful with TIMEOUT. Because this command can cause a OASBasic program to terminate at an INPUT statement rather than concluding normally, using TIMEOUT can cause inconsistent data in your database.

© 2012 Onsystex Inc.

Part

12

112

12

OASYS Administration for Windows 64 Bit Platforms

Managing Printers in OAS This chapter explains how OASYS interacts with the Windows spooler and describes how to configure and access printers from within OASYS.

12.1

Configuring and Troubleshooting a Printer 14-3 On Windows platforms, the term “printer” refers to a printer driver. The term “print device” refers to a piece of hardware that can be accessed using one or more “printers.” In order for any user to print to a print device from OASYS, all the following conditions must be true. Use these conditions as guidelines for setting up a print device and for troubleshooting print device problems.

12.1.1 Physical Configuration Configure a print device as follows: The print device must be physically connected to your computer or network. If you are accessing the print device from a local printer you create, the driver for the print device must be installed on the workstation or server from which you are printing. Note: Depending on your network configuration, you may need to complete additional steps before you can print successfully from your Windows platform. For instance, you may need to install additional network software and then create a “printer” or “local printer” that identifies the device using a network address. Refer to your Microsoft documentation, the documentation for your network hardware and software, and your printer documentation for information about connecting and troubleshooting a print device.

12.1.2 Troubleshooting Check cables and connections. Check power to print device and check print device for error conditions. Print a file to the print device. If you cannot print to the device from outside OASYS, you will not be able to print to it from within OASYS. Missing printer drivers or restrictive permissions to a device can result in print jobs failing.

Definition in Windows Platforms You may either print directly to a network print device or a print to a “local printer” from within OASYS.

Network Print Device A network print device is a print device that is connected to a remote print server. When you print to a network printer, the printer driver and the configuration are downloaded to your computer. To connect to a network printer, from the Start menu click Printers and Faxes, click Printers, and then double-click Add Printers. The Add Printer wizard displays, as shown in the following example:

© 2012 Onsystex Inc.

Managing Printers in OAS

113

Click Next. The following dialog box appears:

Click Network printer, and then click Next to display the Specify a Printer dialog box, as shown in the following example:

© 2012 Onsystex Inc.

114

OASYS Administration for Windows 64 Bit Platforms

If you know the name of the printer, enter the path in the Name box. If you are connecting to a printer on the internet or on your intranet, enter the URL of the printer in the URL box. If you do not know the name of printer, click Browse, then click Next. The Browse for Printer dialog box appears, as shown in the following example:

Click Next to locate your network printer.

Local Printer A local printer is a driver you can create that identifies a print device. When you define a local printer, your workstation becomes the print server for that printer. A local printer may point to a network print device, but you define the printer configuration on your workstation.

© 2012 Onsystex Inc.

Managing Printers in OAS

115

12.1.3 Definition in OAS Within a OASYS session, the following commands and statements can access a printer: OASBasic PRINT statements (following PRINTER ON statements) OASQuery statements with the LPTR option SPOOL commands The SP.EDIT command To write to a particular printer from a OASYS session, you need to link the printer to an internal print unit in OASYS. Use the ECL SETPTR command with the DEST or AT option for this. For more information, see “Defining a Printer Unit in OASYS” on page 14-24.

12.1.4 Default Printers If you do not map a print unit to a particular printer or queue, OASYS checks for a default destination for output of printing commands as follows: The printer or queue defined by the last previous SETPTR command in your current OASYS session. If there was no prior SETPTR command, the printer identified by the system environment variable OASYS_DEFAULT_PRINTER. Each OASYS session checks for that variable at when users log on to the system. If the variable was set, the defined printer is treated as the default printer throughout the session. If there was no prior SETPTR command, and OASYS_DEFAULT_PRINTER was not set, OASYS checks for the default printer on your Windows system. Note: If you are a local user (your account information is on a local Windows machine rather than a domain) and you log on through Telnet, and OASYS_DEFAULT_PRINTER was not set, you will see an error message when you attempt to display the default printer name with SETPTR 0.

12.2

Spooling From OAS Enter topic text here.

12.2.1 The Spooling Process Print requests from within OASYS are generated by OASBasic commands (PRINT, PRINT ON), by ECL commands (SPOOL, SP.EDIT) and by using the LPTR keyword in OASQuery. When a print request is generated, the following actions happen: OASYS uses information from the print request to create a temporary file containing the output to be printed. Note: If you executed SETPTR and set the printer mode to 3 or 6, OASYS creates the print file in the SpoolJobs file of your current OASYS account. OASYS prints that file with Windows Win32 API calls, using information from the printer setup (SETPTR for the printer to receive the output). After the output is printed, OASYS deletes the temporary file.

12.2.2 OAS for Windows Platforms Specifics OASYS for Windows Platforms enables you to print to any printer you can access from outside of OASYS. The DEST or AT option of SETPTR enables you to print to a particular device. SETPTR options control some output characteristics, and you can specify other characteristics by including spooler options in a quoted string on the SETPTR command line. © 2012 Onsystex Inc.

116

OASYS Administration for Windows 64 Bit Platforms

By using RAW spooler mode (the default in OASYS), you can control formatting by using printer-specific escape sequences rather than spooler options.

12.2.3 Creating a Local Printer On Windows platforms, the term “printer” refers to a printer driver. The term “print device” refers to a piece of hardware you can be access by using one or more “printers”. You can create a local printer to print to a device local to your server or workstation. In some circumstances, you may wish to create a local printer that points to a network print device, and print to that local printer rather directly to the network device. Complete the following steps to create a local printer. From the Start menu, point to Printers and Faxes, and then click Add Printer. A window similar to the following appears:

Click Next. The following dialog box appears:

© 2012 Onsystex Inc.

Managing Printers in OAS

117

Click Local printer to indicate the printer is a local printer. Note: Your Windows machine becomes the “server” for the printer you are creating. After you add the printer, click File, then Server Properties to view and edit settings for this printer. Click Next to display the following dialog box:

If your local printer identifies a device local to your workstation or server, scroll through the list of ports and select the check box the one where the printer is connected. Click Next and proceed to step 5. If your local printer identifies a network print device, scroll through the list of Available Ports to determine if the UNC identifier for the network print device is listed with “Local Port” as its description. If so, proceed to step 5. If the network print device is not on the list, or its description is not “Local Port,” click © 2012 Onsystex Inc.

118

OASYS Administration for Windows 64 Bit Platforms

Create a new port. Select Local Port from the Type list, then click Next. The following dialog box appears:

Click OK. A dialog box similiar to the following example appears:

Select the manufacturer and model of your printer. If your printer came with an instal-lation disk, click Have Disk. If the manufacturer or model of your printer is not listed, see your printer documentation for a a compatible printer. Click Next. Enter a name for the local printer in the Name Your Printer dialog box, as shown in the following example:

© 2012 Onsystex Inc.

Managing Printers in OAS

119

Warning: Do not use spaces in the printer name. Although Windows platforms allow spaces in the name (for instance, “LASER PRINTER”), the OASYS SETPTR command does not support names that contain spaces. If you use a name containing spaces with the DEST or AT options of SETPTR, the command fails. You can share your printer with other users on the network. In the following dialog box, enter a name for the shared printer, or select Do not share this printer.

Note: You may share a local printer if you wish. However, sharing a local printer offers no advantage in OASYS. OASYS only recognizes local printers created on the same Windows system where you are running OASYS. Also, OASYS does not use the share name to recognize a printer. Rather, OASYS uses the printer name you entered previously. When you click Next after defining Sharing properties, a dialog box similar to the following appears:

© 2012 Onsystex Inc.

120

OASYS Administration for Windows 64 Bit Platforms

Tip: Onsystex recommends you print a test page to verify the printer setup. Click Finish. A dialog box similar to the following example appears:

Click Finish to add the printer to your machine. An icon for the printer appears in the Printers window. Display the Properties sheet for the printer you just created. The following table summarizes the dialog tab. Dialog Tab

Purpose

General

Adds comments or location information, or changes printer driver. Within OASYS, the first 24 characters of comment entry displays as Description in the output from LISTPTR or SP.STATUS. References a different network print device.

Ports

© 2012 Onsystex Inc.

Managing Printers in OAS

Scheduling

Dialog Tab Sharing Security Device Settings

121

Views or edits times the printer is available, job priority, and job handling. Printer Properties S heet

Purpose Shares or unshares your printer. Views or edits permissions, ownership, auditing. M aps forms to trays/feeders. Printer Properties S heet (continued)

Note: Use caution modifying device settings. You can enter settings for a local printer that are inconsistent with the underlying print device. Note: You must have Full Control permissions on a printer to assign a default form. Click Security, and then click Permissions on the Property sheet to determine what permissions you have. To assign a default form to a printer, right-click the printer for which you want to set the default, click Properties, then click Printer Properties. A dialog box similar to the following example appears:

Select the desired form from the Form Type list. If the form you want is not included in the list, see “Creating a Form” on page 14-20. You can also choose copies, orien-tation, and duplex options from this dialog box. Note: Options you select on either this tab or the Advanced tab only work if the network print device supports them. Click OK when your selections are correct. Note: Although you can select Copy Count from this tab, the value you select here is overridden in OASYS by the COPIES option of the SETPTR command.

12.3

Creating a Form Windows platforms store information about forms that are available on your current Windows system. Not all the forms are available for all print devices, because each print device supports particular sizes of stock and loading

© 2012 Onsystex Inc.

122

OASYS Administration for Windows 64 Bit Platforms

devices. To view the list of forms available on your system, from the Start menu, click Printers and Faxes. Click the File menu, then click Server Properties, then click the Forms tab. A dialog box similar to the following example appears:

Select the Forms tab on the properties sheet, and complete the following steps to create a new form.

1.Select an Existing Form You create new forms by editing the characteristics of existing forms. Highlight a form, and then select the Create a New Form check box. Tip: To minimize editing, pick an existing form whose characteristics are similar to the new form you are creating.

2. Edit Form Characteristics When you select the Create a New Form check box, the name, paper size and margins are enabled for editing. Follow the instructions on the properties page to edit and save the new form. The following example shows selections for a form called test_form, based on the existing form called Letter.

© 2012 Onsystex Inc.

Managing Printers in OAS

123

Note: Although you can create forms of varying sizes, you cannot select a particular form for use on a particular printer unless the print device can support that size of stock. Refer to your Windows documentation and the documentation for your print device for information about constraints. The new form now displays in the form list. Click OK to exit the Forms tab.

12.4

Defining a Printer Unit in OAS Use the ECL SETPTR command to define printer units within OASYS. This command maps Windows printers to logical unit numbers within a OASYS session. Syntax: SETPTR unit [width,length,topmargin,bottommargin] [,mode] [,options] [,“spooler_options ”] With SETPTR, you can define up to 31 logical printer units in a single OASYS session. Throughout OASYS, you can define up to 255, but only 31 can be defined in a single user session. The following table lists each parameter of the syntax. Parameter unit

© 2012 Onsystex Inc.

Description Logical printer unit number that is internal to OASYS. You can map this to a Windows printer with the DEST or AT option. M ust range from 0 through 254; default is 0.

124

OASYS Administration for Windows 64 Bit Platforms

[width]

The number of characters per line; must be from 0 to 1024; default is 132.

[length] [topmargin]

The number of lines per page; must be from 1 to 32,767 lines; default is 60. The number of lines to leave blank at the top of each page; must be from 0 to 25; default is 3.

[bottommargin]

The number of lines to leave blank at the bottom of each page; must be from 0 to 25; default is 3. Allows you additional flexibility to direct output; default is 1; see separate table.

[mode] [options] [“spooler_options”]

Report formatting and printer control options. For more infor-mation, see “SETPTR Options.” Options that are valid with the Windows spooler. See separate table for list of supported options. Supply these options in a quoted string. S ETPTR Parameters

Note: Users familiar with Pick ® conventions should be aware that printer unit numbers set with SETPTR are not the same as Pick ® printer numbers. SETPTR allows you to define logical printer units, which may be, but are not necessarily, linked to specific printers. OASYS printer unit numbers are used with the PRINT ON statement in OASBasic to allow multiple concurrent jobs. Pick ® printers (forms) are specified with the DEST option of SP.ASSIGN. The next table describes modes for the SETPTR command. Mode

Description

1 2

Directs output to a line printer only. M ust be used with DEVICE option; directs output to the serial device specified by the DEVICE option. Directs output to a SpoolJobs file only. Directs output to both a SpoolJobs file and a printer. Directs output to a line printer; suppresses display of the SpoolJobs entry name. S ETPTR Modes

3 6 9

The next table describes options for the SETPTR command. Option

Description

BANNER [string]

M odifies the default banner line (which is the Windows user ID). Depends on M ODE setting; also modifies SpoolJobs entry name.

BANNER UNIQUE [string]

M odifies the default banner line, and automatically uses attribute 1 (NEXT.HOLD) in the dictionary for the SpoolJobs file to create unique entry names for jobs sent to SpoolJobs. Directs OASYS NOT to prompt for verification upon execution of SETPTR.

BRIEF COPIES n DEFER [time] DEST unit (or AT unit)

Prints n copies of the print job. Does not work with mode 3. Delays printing until the specified time. Specify the time in HH:M M format. Does not work with mode 3. Directs output to a specific printer or queue. The unit may be either a local printer or a network printer. S ETPTR Options

Option DEVICE name EJECT

Description Used with mode 2 only. Directs output to the Windows device (for instance, a COM port) identified by name. Ejects a blank page at the end of each print job.

© 2012 Onsystex Inc.

Managing Printers in OAS

NOEJECT

Suppresses the form feed at the end of each print job.

LNUM NFM T or NOFM T NHEAD or NOHEAD OPEN

Prints line numbers in the left margin of each print job. Suspends all OASYS print formatting. Suppresses the banner for each print job. Opens a print file, and directs output to this file until the file is closed by the SP. CLOSE command. S ETPTR Options (continued)

The next table describes spooler options you can specify in a quoted string. Option

Description

Orientation

Paper orientation; must be PORTRAIT or LANDSCAPE. Defaults to the setting in the Default Document Properties sheet for the printer.

PaperSource

Default paper source; must match an available paper source listed on the Device S ettings tab of the printer’s Properties Sheet.

Duplex

M ust be NONE, HORIZONTAL, or VERTICAL; default is NONE. If the print device does not support duplex printing, this option is ignored. Jobs print single-sided and no error message displays.

Form

Form to use (for instance, Letter). M ust match an available paper size listed on the Device S ettings tab of the printer’s Properties Sheet. S ETPTR S pooler Options

Option

Description

M ode

RAW or WINDOW. Default is RAW, meaning that printer-specific escape sequences are required for all formatting. Specifying formatting options (Form, Font, FontSize, Orien-tation, FontStyle, DefaultSource, or Duplex) in a quoted string automatically switches M ode to WINDOW.

Prefix

stevPrinter-specific escape sequence, specified as the literal ASCII characters. Valid in RAW mode only. For example, “PREFIX = \002”

Font

Font name, for instance “Courier New”. The OASYS spooler creates a “logical font” using the values you provide for Font, FontSize, and FontStyle. Windows platforms attempt to find an appropriate font to use from the ones installed on your computer. Font size in points (for instance, 8, 9, 10, 11). The OASYS spooler creates a “logical font” using the values you provide for Font, FontSize, and FontStyle. Windows platforms attempt to find an appropriate font to use from the ones installed on your computer. M ust be Regular, Italic, Bold, Underline, or StrikeOut. Default is Regular. The OASYS spooler creates a “logical font” using the values you provide for Font, FontSize, and FontStyle. Windows platforms attempt to find an appropriate font to use from the ones installed on your computer. Left margin of the page, in inches. For example, “LeftM argin = 1.0” Right margin of the page, in inches. For example, “RightM argin = 0.75”

FontSize

FontStyle

LeftM argin RightM argin TopM argin

Top margin of the page, in inches. TopM argin is measured beginning at the value of the SETPTR topmargin option (default is 3 lines). If topmargin is 3 lines (the default) and TopM argin = 1, the first printed line is one inch below the third line on the page. S ETPTR S pooler Options (continued)

© 2012 Onsystex Inc.

125

126

OASYS Administration for Windows 64 Bit Platforms

Option BottomM argin

Priority JobState

Description Bottom margin of the page, in inches. BottomM argin is measured beginning at the value of the SETPTR bottommargin option (default is 3 lines). If bottom-margin is 3 lines (the default) and BottomM argin = 1, the first printed line is one inch above the third line from the end of the page. M ust be from 1 to 99, where 1 is minimum priority and 99 is maximum. The only valid value is PAUSE, which stops all jobs to the print unit. You can reverse this option from the Printers applet. S ETPTR S pooler Options (continued)

12.4.1 Examples You can define local or network printers to OASYS using the SETPTR command, as shown in the following examples:

Notice the following points: The default print device (printer unit 0) is now mapped to the local printer LETTER. If you use the PRINT © 2012 Onsystex Inc.

Managing Printers in OAS

127

command or LPTR with no print unit specified, OASYS directs your print job to LETTER. Use SETPTR unit to display the current settings for a print unit. When you specify spooler options (TopMargin, BottomMargin), OASYS automatically recalculates the width and length taking these into account. When you specify formatting options in a quoted string, OASYS implicitly changes the spooler Mode from RAW (the default) to WINDOW. You can specify spooler options in a quoted string either before or after SETPTR options like AT, DEFER. You can map a printer unit to a network print device even if that device is not displayed in your Printers dialog. After you have defined printers with SETPTR, you can display a list with the LISTPTR command, as shown below:

Only users with Full Control permissions on a printer can control the printer with PTRDISABLE and PTRENABLE. Check Permissions on the Security tab of the Properties sheet for the printer to determine who has permissions. Notice that the argument for PTRDISABLE and PTRENABLE is the name of the printer (as specified with DEST or AT in SETPTR). You can use the ECL SP.STATUS command to display information about printers defined with SETPTR and print © 2012 Onsystex Inc.

128

OASYS Administration for Windows 64 Bit Platforms

jobs started from your OASYS session. The following example shows SP.STATUS output:

The status of all the printers is Running, and the network print device has a deferred job. Depending on how a print device was configured, users in console sessions may see printer notification messages when a job completes. Note: The Printing Notification only displays if you log on to a console session. If you log on to OASYS through Telnet, you will not see the notification.

12.4.2 Printing to the _HOLD_ File Selecting SETPTR mode 3, 6, or 9 on the command line directs output from printing commands to the SpoolJobs file. When you print to the SpoolJobs file, OASYS actually creates two entries, one for the printing command output and one for the SETPTR settings. OASYS preserves the SETPTR settings so you can print from the SpoolJobs file at a later time using the settings selected with SETPTR. The following example shows the creation and contents of two SpoolJobs entries generated by a printing command:

© 2012 Onsystex Inc.

Managing Printers in OAS

129

12.4.3 Selecting a Spooler Mode The OASYS spooler interface enables you to print to an Windows printer using one of two spooler modes: RAW or WINDOW.

RAW Mode In RAW mode, the default, all formatting is controlled by printer-specific escape sequences you include in your print job. OASYS writes to the spooler device using the WritePrinter win32 API call. RAW mode enables you to migrate existing applications and utilities without rewriting printing logic.

WINDOW Mode In WINDOW mode, formatting is controlled by your selection of SETPTR options and spooler options. You can print in WINDOW mode by specifying “Mode=WINDOW” on the SETPTR command line or by including any of the spooler options (Form, Font, FontSize, Orientation, FontStyle, DefaultSource, or Duplex) that only work in WINDOW mode.

Examples In the following example, the spooler mode is changed from RAW (the default) to WINDOW. Notice that OASYS © 2012 Onsystex Inc.

130

OASYS Administration for Windows 64 Bit Platforms

changes the width and length automatically:

In the next example, setting Font to COURIER implicitly changes the spooler mode to WINDOW, even though the display does not indicate this. Notice that width and length were adjusted:

© 2012 Onsystex Inc.

Managing Printers in OAS

131

If you combine incompatible options on the SETPTR command line, the command fails with an error message as shown in the following example:

12.4.4 Redefining the Default OAS Print Unit To keep OASBasic applications general, developers typically use (or assume) printer unit 0, which is the default. The SETPTR command enables you to redefine unit 0 to direct output from different parts of an application to different physical printers or queues, or to change formatting options. The following example is a very simple paragraph that redefines the default print unit for different reports:

12.4.5 Submitting Concurrent Print Jobs With SETPTR, you can define up to 31 logical printer units in a single OASYS session. You can use this functionality to submit concurrent print jobs from a OASBasic application. One common implementation follows: Define two logical printer units (for instance, 0 and 1) that point to different physical print devices. Direct all lines of a report to one printer with the OASBasic PRINT ON command (for instance, PRINT ON 0 PRINT.LINE). Direct summary (break) lines to the second printer (PRINT ON 0 PRINT.LINE followed by PRINT ON 1 PRINT. LINE). In this way, you can print a summary report and a detail report at the same time.

12.5

OAS Printing Commands OASYS includes a number of options that enable you to customize output from OASBasic programs and reports. See the CUST.OPTIONS Commands Reference for a complete listing of all available options. The following table describes ECL commands related to printing. Command

Description

SETPTR SPOOL

Defines logical printer units within a OASYS session. Prints the contents of a record to the printer.

© 2012 Onsystex Inc.

132

OASYS Administration for Windows 64 Bit Platforms

PTRDISABLE or STOPPTR

Pauses a Windows printer. You must supply the printer name (the name you used with the DEST or AT option) rather than the OASYS logical print unit number.

PTRENABLE or STARTPTR

Resumes a Windows local printer. You must supply the printer name (the name you used with the DEST or AT option) rather than the OASYS logical print unit number.

SP.CLOSE SP.ASSIGN

Closes a print file. Sets characteristics of the default OASYS print device, printer unit 0 (Pick® compatible syntax). Views or prints files in the SpoolJobs directory Cancels a job. Opens a continuous print job. This command is equivalent to the OASYS SETPTR,,,,,,OPEN command. Provides printer and queue information. Displays the names of printers and the paths of devices associated with them. Lists entries in the SpoolJobs file of the current account. ECL Printing Commands

SP.EDIT SP.KILL SP.OPEN SP.STATUS LISTPTR LISTPEQS

Note: See the OASYS Commands Reference for the syntax of these ECL commands.

© 2012 Onsystex Inc.

Part

13

134

13

OASYS Administration for Windows 64 Bit Platforms

Managing Cataloged Programs This chapter describes the behavior of global, direct, and local cataloging for OASBasic programs. The chapter also describes how to create an alternate global catalog space using the newhome command.

13.1

OasBasic Source and Compiled Programs OASYS stores OASBasic source code in DIR-type files in the OASYS account where the source is developed. The default location for storing OASBasic source code files is the BP file, which OASYS creates as an empty file when you create a OASYS account. Developers store OASBasic source code files as records in the BP file. Note: In a OASYS DIR-type file, such as BP, each “record” is a file. Each OASYS account may contain numerous DIR files for OASBasic source.

13.1.1 OasBasic Compiled Programs When you issue the BASIC command to compile a OASBasic program, OASYS stores the compiled code in the same DIR file where the source code resides. The compiled code is a record whose name is the same as the source record, prefixed with an underscore. Note: See the OASYS Commands Reference and Developing OASBasic Applications for information about the BASIC command. The following example shows the contents of a program file:

Records beginning with an underscore are compiled programs. Other records are OASBasic source files. Note: Use the ECL RUN command to execute a compiled program. See the OASYS Commands Reference and Developing OASBasic Applications for information about the RUN command.

13.2

Cataloging OasBasic Programs Cataloging OASBasic programs simplifies program execution and can improve efficiency of system resource use by allowing multiple users to access a single copy of a compiled program from shared memory. Use the ECL CATALOG command to catalog one or more OASBasic programs. Note: See the OASYS Commands Reference and Developing OASBasic Applications for information about cataloging and the CATALOG command. Compiled OASBasic programs can be cataloged directly, locally, or globally.

© 2012 Onsystex Inc.

Managing Cataloged Programs

135

13.2.1 Direct Cataloging Points to remember about direct cataloging are: Compiled code is located in the program file in the OASYS account where the program was compiled and cataloged. The VOC file in the account contains a pointer to the compiled code in the program file. Users in the same account can execute the program by entering the program name at the ECL prompt. Because users access the compiled code in the program file, developers do not need to recatalog the code if they recompile. When you execute a directly cataloged program, OASYS loads a copy of the program into your address space.

13.2.2 Local Cataloging Points to remember about local cataloging are: Compiled code is located in the CTLG directory in the OASYS account where the program was cataloged, as well as in the program file. CTLG is a DIR-type OASYS file, and each record is a compiled OASBasic program. The VOC file in the account contains a pointer to the compiled program in the CTLG. Users in the same account can execute the program by entering the program name at the ECL prompt. Developers must recatalog a program after recompiling to place a new copy of the compiled code into the CTLG. When you execute a locally cataloged program, OASYS loads a copy of the program into your address space.

13.2.3 Global Cataloging Points to remember about global cataloging are: If you execute the CATALOG command without specifying local or direct cataloging, your program is globally cataloged. Compiled code is located in a systemwide global catalog. The default global catalog is OASHOME \sysprog\CTLG. Developers must recatalog a program after recompiling it to place a new copy of the compiled code into the global catalog. Note: A OASYS installation can have more than one global catalog space. The environment variable OASHOME determines which global catalog space a particular OASYS session accesses. See “Creating an Alternate Global Catalog Space” on page 15-15 for more information about creating multiple global catalog spaces. A systemwide global catalog is a DIR-type file, with 26 subdirectories named a through z. Compiled code is located in the subdirectory corre-sponding to the first letter of the program name. Compiled programs that begin with nonalphabetic characters are stored in a subdirectory named X. The cataloged program name can be the same as the source and object, or you can specify a different name when you execute CATALOG. Tip: Consider your program naming conventions if you are using global cataloging. Since OASYS places the compiled code in subdirectories according to name, you may have an unbalanced situation if a large number of your program names begin with the same letter (for instance, a general ledger application where all the files begin with “gl”). A globally cataloged program is available to users in all OASYS accounts. When you execute a globally cataloged program, the shared basic code server (oas_objmanager) checks to see if a copy already exists in the shared memory it controls. If so, oas_objmanager notifies the oas process which shared memory segment to attach to access that copy. © 2012 Onsystex Inc.

136

OASYS Administration for Windows 64 Bit Platforms

If not, oas_objmanager loads a copy into one of its shared memory segments for you to execute. Any object file located in the OASHOME\sysprog\CTLG file system is handled by oas_objmanager, regardless of how the program is accessed. The oas_objmanager process can manage up to 20 shared memory segments for globally cataloged programs. OASYS determines the size of each segment by the OAS_MaxCatalogBytes parameter in the OASYS configuration file (\OASHOME\include\oasconfig). The default value for OAS_MaxCatalogBytes is 1,048,576 bytes (1 MB), which is set when you install OASYS. You will encounter runtime errors if this size is insufficient. You can increase the segment size as long as you do not exceed the configuration parameter OAS_MaxShmSize. Tip: See “Appendix A OASYS Configuration Parameters” for more information about OAS_MaxCatalogBytes and OAS_MaxShmSize.

13.3

Managing Global Catalogs OASYS provides a group of files and commands that manage global catalogs. These files and commands accomplish the following: Identify the contents of a global catalog space Verify consistency between OASBasic source and a globally cataloged program Activate newly cataloged programs and subroutines Display use of globally cataloged programs

13.3.1 Contents of a Global Catalog OASYS maintains two files that store contents of a global catalog. The global catalog table, called CTLGTB, is a dynamically maintained file that shows the current contents of the global catalog. You can list the catalog table from a OASYS account, as shown in the following example:

© 2012 Onsystex Inc.

Managing Cataloged Programs

137

The _MAP_ file also contains information about the contents of a global catalog. In addition to the information in CTLGTB, _MAP_ includes the size of each compiled program, the date it was cataloged, and the last date it was executed. The _MAP_ file is not dynamically maintained by OASYS. The ECL MAP command updates the _MAP_ file to reflect recent activity. The MAP command clears the _MAP_ file, updates the file, and displays its contents, as shown in the following example:

© 2012 Onsystex Inc.

138

OASYS Administration for Windows 64 Bit Platforms

By default, the CTLGTB file and the _MAP_ file are located in the same directory as the global catalog: OASHOME\sysprog. Tip: The CTLGTB file and the _MAP_ file are OASYS hashed files. You can display records in these files with standard ECL and OASQuery commands to determine if particular programs are in the global catalog.

13.3.2 Verifying a Program Version The VCATALOG command checks the date/time stamp of a OASBasic source file against the compiled program in the global catalog. If the OASBasic source file was modified after the program was cataloged, the program does not verify. The following example shows output from VCATALOG: Syntax: VCATALOG filename catalog.name program.name The following table describes each parameter of the syntax. Parameter filename catalog.name

program.name

Description Name of the file containing the program (BP, for instance). Name given to the program when you executed CATALOG. For example, the command CATALOG BP TRIAL TEST creates a global catalog entry named TRIAL from a program called TEST. So catalog.name is TRIAL. Name of the program source file. In the example in the previous row of this table, program.name is TEST. VCATALOG Parameters

Note: If catalog.name and program.name are the same, you need only supply the name once.

© 2012 Onsystex Inc.

Managing Cataloged Programs

139

In the example, notice that recataloging the program did not make the program verify. This result indicates that the source code was changed, but was not recompiled or recataloged. After the source code was recompiled and recataloged, the program verified successfully. See the OASYS Commands Reference for more information about the VCATALOG command.

13.3.3 Activating Newly Cataloged Programs and Subroutines Main Programs When you globally catalog a OASBasic main program, OASYS: Copies the new compiled code into the global catalog. If there is a version of the program in shared memory, marks that version as obsolete. The users already executing the main program continue to execute the previous version. Users that execute the program after the new version is cataloged get the new version. Once all users exit the previous version, OASYS removes the copy of that version from shared memory. Note: A user executing a main program continues to execute that version until it completes.

Subroutines If a subroutine is recataloged while the main program is running, users will not execute the newly-cataloged subroutine until the next time they execute the main program. This prevents inconsistent execution of a subroutine during one execution of the main program. Under certain circumstances, however, a user or system administrator can override the default behavior. Overrides are dangerous in a production environment, but may be useful in a development or test environment.

NEWVERSION Keyword The NEWVERSION keyword for the CATALOG command allows a user logged on as an Administrator to dynamically replace a globally cataloged subroutine. If a subroutine is cataloged with NEWVERSION, any user executing the main program accesses the new version of the subroutine with the next CALL or EXECUTE of the subroutine, rather than waiting until the main program completes. Consider the following sequence of events: 1. A user executes the main program MAIN. 2. MAIN calls a subroutine called SUBR, which completes and returns to MAIN. 3. MAIN continues with other processing. 4. MAIN calls SUBR again. SUBR completes and returns to MAIN. 5. MAIN completes.

If SUBR is recataloged after step 1 without the NEWVERSION keyword, the same version of SUBR is used for both calls (step 2 and step 4). With the next execution of MAIN, the newly cataloged SUBR is used. If SUBR is recataloged after step 1, with the NEWVERSION keyword, there are three possible results:

© 2012 Onsystex Inc.

140

OASYS Administration for Windows 64 Bit Platforms

CATALOG happens after step 1 but before step 2. In this case, the newly cataloged SUBR gets accessed in both step 2 and step 4. CATALOG happens after step 2, but before step 4. In this case, the prior version of SUBR gets accessed in step 2, and the newly cataloged version gets accessed in step 4. CATALOG happens after step 4. In this case, the prior version gets accessed in both step 2 and step 4. With the next execution of MAIN, the newly cataloged SUBR is accessed. Warning: Using the NEWVERSION keyword to CATALOG a subroutine can produce inconsistent results for users who are currently executing the main program. For example, the number of arguments could change. The following sample CATALOG command shows the syntax including the NEWVERSION keyword:

newversion System-Level Command The OASYS system-level command newversion allows a user logged on as an Administrator to dynamically replace a cataloged subroutine (just as the NEWVERSION keyword does) but limits the behavior to a selected user or users. Syntax: newversion path userno... The following table describes each parameter of the syntax. Parameter

Description

path userno...

Absolute path of the cataloged subroutine. Process ID (pid) for a user who should access the new subroutine dynam-ically. You can specify more than one userno; separate the numbers with spaces. newversion Parameters

The following screen shows an example of the newversion command:

In the example, the newly cataloged subroutine is dynamically available to cgustafs, the owner of user number 2664. If cgustafs is executing a main program that calls a subroutine, the next call to the subroutine accesses the newly cataloged version. For all users other than cgustafs, the default behavior remains in effect. The newly cataloged subroutine is activated with the next execution of the main program, not the next subroutine call. Notice that, in the example, the subroutine is globally cataloged; this command works with locally or directly cataloged © 2012 Onsystex Inc.

Managing Cataloged Programs

141

routines as well.

NEWPCODE Command The ECL NEWPCODE command dynamically activates a cataloged subroutine. This command is useful if a developer uses a OASBasic shell program to modify, recompile, recatalog, and retest a OASBasic program without exiting to ECL. Syntax: NEWPCODE path path is the absolute path of a cataloged subroutine. The following example shows one use of the NEWPCODE command executed in a OASBasic program:

In the example, a user executing MAINPROG accesses the current version of MAINPROG2 in the first statement. Including the NEWPCODE command before the next execution of MAINPROG2 causes the program to access the newest version. (In the example, MAINPROG2 was recompiled and recataloged after the first step, so the next execution accesses the newly cataloged MAINPROG2.) Tip: If you are developing programs with the AE editor, the N option of the FI command equates to the NEWPCODE command. For example, FIBCFN compiles a program and catalogs it (locally) with NEWPCODE. You need to use F (force) in conjunction with the N option. See the online help for the AE editor or Developing OASBasic Applications for more information. Note: The NEWPCODE command is effective only in the oas session where it is executed. Although NEWPCODE is an ECL command, you cannot affect a different user or even a different window with NEWPCODE.

13.4

Listing Programs in Use The OASYS system-level oas_objrunning command enables any user with access to the system-level prompt to display a list of globally cataloged programs currently in use, with counters for the number of processes currently accessing each one. The following example shows typical output from oas_objrunning:

C :\O nsystex\oas61\FirstAccount>c:\O nsystex\oas61\bin\oas_objrunning N o program s in O AS G lobal m em ory.

In the example, two users are executing AE, and two are executing AE_AE. The oas_objmanager daemon maintains the counter, incrementing it as users execute a program and decreasing it as users complete execution. When the counter for a routine reaches zero, oas_objmanager removes the copy of the compiled program from shared memory, making the space available for other programs as needed. Tip: If you run oas_objrunning regularly throughout your processing cycle, you can learn which programs are used most heavily. This information is useful if you are troubleshooting an application performance problem. Note: The reference counter is not decremented when a user terminates abnormally (for example, when a © 2012 Onsystex Inc.

142

OASYS Administration for Windows 64 Bit Platforms

process is killed). Because of this, the count may be inaccu-rately high, causing excess memory to remain held. Stopping and restarting OASYS resets the counter and releases memory.

13.5

Creating an Alternate Global Catalog Space The system-level newhome command creates a new OASYS account containing an alternate global catalog space for use in development and testing.

13.5.1 Files and Directories Created by newhome OASYS creates or overlays the directory indicated by path. This directory contains only the subdirectory sysprog, which contains the following files and directories:

© 2012 Onsystex Inc.

Managing Cataloged Programs

© 2012 Onsystex Inc.

143

144

OASYS Administration for Windows 64 Bit Platforms

The following directories make up the program catalog spaces: D_CTLGTB CTLGTB D_CTLG CTLG, including subdirectories a through z and X for storing globally cataloged programs. newhome does not create the entire directory structure that exists in the default OASYS home directory, and it does not copy OASBasic executables developed at your site.

13.5.2 Procedure for Creating an Alternate Global Catalog Space Follow the steps below to create an alternate global catalog space:

1. Change to the New Account Directory At the operating system prompt, change to the directory in which you intend to locate the new OASYS account, as shown in the following example:

2. Execute oas_newhome Execute the oas_newhome command, indicating the path to the new account. In this example, a new directory, FirstAccount, will be created under \OAS61\FirstAccount. Notice that the oas_newhome command is executed from the ECL prompt, and therefore is preceded by the ! ECL command:

© 2012 Onsystex Inc.

Managing Cataloged Programs

145

3. Modify VOC Entries for Users Decide which OASYS accounts should access the new global catalog space. For each account, modify the VOC entry for CTLGTB. The entry should point to the new global catalog space, as shown in the following example. Notice that this example uses a soft pointer to @OASHOME. This ensures that the VOC always points to the correct catalog space.

You do not need to log on as an Administrator to edit the VOC entries; however, you need write permissions on the VOC file in each account.

4. Modify OASHOME for Users You need to reset the OASHOME environment variable for each user who needs to access the alternate global catalog space. The value of OASHOME that is defined during a particular OASYS session determines the global catalog space a user accesses. Note: Even if the VOC file is set up to point to the alternate global catalog (CTLGTB), a user whose OASHOME is set to the default value accesses the default global catalog space.

5. Copy Application Programs After resetting OASHOME to point to the new space, start OASYS from an account that has access to the sitespecific programs that you want to access from the new account, and recatalog those programs. Because you have reset the OASHOME environment variable, the recataloged programs are placed in the new space.

6. Use the Alternate Global Catalog Space The alternate global catalog space is now ready to use. The following example shows the output of the oas_objrunning command when two global catalog spaces are used:

Notice that AE is running twice, but that the two copies are cataloged in different global catalog spaces.

© 2012 Onsystex Inc.

Part

14

Managing and Using Tape Devices

14

147

Managing and Using Tape Devices This chapter describes OASYS commands for identifying and accessing Windows tape devices. Tip: When you define tape devices within OASYS, you must use the Universal Naming Convention (UNC) format for device names. Refer to your Microsoft documentation for information about UNC format.

14.1

OAS Tape Handling Commands OASYS includes a number of ECL and OASBasic commands for reading data from a tape and writing data to a tape. The ECL commands are summarized in the following table. Command SETTAPE T.ATT

Description Defines a logical tape unit in OASYS; must precede any other tape commands. Links a logical tape unit to a OASYS process; must precede any reads/ writes involving the tape.

T.BAK T.CHK T.DET

M oves a tape backward by a specified number of files. Reads a tape created by T.DUM P and checks for damage. Releases a logical tape unit when a OASYS process is finished with it.

T.DUM P T.EOD T.FWD

Copies the contents of a file or active select list to tape. M oves a tape unit to end of file. M oves a tape unit to the beginning of the next file.

T.LOAD

Loads records from a tape created with T.DUM P.

T.RDLBL T.READ

Reads and displays the first 80 characters of the tape label on a tape created with T.DUM P. Reads and displays the next record from tape.

T.REW

Rewinds a tape to the beginning.

T.SPACE

M oves a tape forward a specified number of spaces.

T.STATUS T.UNLOAD T.WEOF

Displays current tape device assignments. Rewinds and unloads a tape. Writes an end-of-file mark on a tape. ECL Tape Handling Commands

Note: See the OASYS Commands Reference for information about ECL commands. The next table summarizes OASBasic commands for I/O on tape devices. Command

Description

READT RESIZET

Reads the next available record from tape. Changes the block size used by the WRITET statement.

REWIND WEOF WRITET

Rewinds a tape to the beginning. Writes an end-of-file mark to a tape. Writes the value of a specified expression as a record on a tape. OAS Basic Tape Handling Commands

Note: See the OASBasic Commands Reference for information about these OASBasic commands.

© 2012 Onsystex Inc.

148

OASYS Administration for Windows 64 Bit Platforms

14.1.1 SETTAPE Syntax: SETTAPE unit.no [dn.path.nr][dn.path.r][blocksize]

Description The SETTAPE command defines logical tape units in your OASYS environment. This command establishes a link between a OASYS internal tape unit number and a tape device. You can use SETTAPE to relate unit number to tape devices or disk files. Any user can execute SETTAPE unit.no to display the current settings for a tape unit. However, you must log on as an Administrator to define a tape unit or modify settings. Once a tape unit has been defined using SETTAPE, it can be accessed by users in any OASYS account on your system. The tape unit definition remains the same unless it is changed by an Administrator.

Writing to a Device To relate a tape unit number to a tape device, use the full UNC format for the device name in the SETTAPE command syntax. The following example shows how to identify a tape device with SETTAPE:

Writing to a File To relate a tape unit number to a disk file, use the full path and file name in the SETTAPE command syntax. The disk file must already exist. The following example shows how to identify a disk file with SETTAPE:

Parameters The following table describes the parameters of the SETTAPE syntax. Parameter

Description

unit.no

Internal OASYS tape unit number. M ust be from 0 to 9. The default tape unit is 0. Device name, in UNC format, or full path and file name of disk file for no rewind device driver for unit.no. Device name, in UNC format, or full path and file name of disk file, for rewind device driver for unit.no. Tape block size in bytes; must be a multiple of 512. If you do not specify blocksize, the default value is 4096. S ETTAPE Parameters

[dn.path.nr] [dn.path.r] [blocksize]

14.2

Steps for Tape Device Use The following steps must take place, in order, for successful tape device use from OASYS.

1. Define Tape Units A user with Administrator privilege must execute the SETTAPE command to define up to 10 tape units for the OASYS environment. Note: Remember that the tape unit number must be from 0 through 9. These are logical tape unit numbers within OASYS; the SETTAPE command maps these to Windows device names. Warning: When defining tape units, be sure to define unit 0. Some of the OASYS tape handling commands require unit 0 to be defined so that it can be used as a default.

© 2012 Onsystex Inc.

Managing and Using Tape Devices

149

When you define a tape device or modify a definition, you create or update an entry in the text file OASHOME \sysprog\tapeinfo.

2. Attach a Tape Device You must attach a logical tape device to your process before accessing it. The T.ATT command attaches a tape device. Any user can execute T.ATT from the ECL prompt or from within a OASBasic program. The following screen shows some typical outputs from T.ATT:

Notice the following points about T.ATT. You cannot attach a tape unit with T.ATT unless the unit was previously defined with SETTAPE. You can execute T.ATT successive times to change the tape block size and also the tape length. If you do not specify BLKSIZE, T.ATT uses the default tape block size specified in SETTAPE. Only one process can attach a tape unit at any time. You can attach more than one tape unit to a single process, but you cannot attach the same tape unit to more than one process. You can use the ECL T.STATUS command to list all defined tape units, and see which ones are attached and which are available. The following screen shows sample output from T.STATUS:

Notice that the “tape devices” for tape units 1 and 2 are actually disk files. A:\TAPEFILE is a FAT file, while \USERS\DEFAULT\TAPEFILE is a NTFS file. When using a disk file as a tape device the functionality is naturally limited to simple loads and unloads, but this may be useful for demonstration or testing. Warning: Do not specify a disk drive (for instance, A:) as a tape device. SETTAPE may succeed, but you will be unable to write to the disk drive. If you wish to dump files to disk, create disk files and then specify the disk files as tape devices.

3. Read From, or Write To, the Tape Device When a tape unit is attached, you can access it from ECL or within a OASBasic program. The following example shows some typical outputs when a process with tape unit 1 attached executes the ECL T.DUMP command:

© 2012 Onsystex Inc.

150

OASYS Administration for Windows 64 Bit Platforms

Notice the following points about the example: You cannot write to a tape device unless it is attached with T.ATT. If you have attached more than one device, you must specify the device to write to or read from. If you have attached only one device, OASYS accesses the device you attached. With T.DUMP, you can write from an active select list. If you supply a single-digit value (for instance, 4) OASYS interprets the digit as the conversion code, and attempts to attach the default device (unit 0). Note: When you access a tape device, the operation fails if the device is not properly connected or if the device does not have a tape mounted. The OASYS T.ATT and SETTAPE commands do not detect device configuration problems, so you may be able to define and attach a device, but be unable to complete your access to it.

4. Release the Tape Device When you have finished using a tape device, use the T.DET command to release the device so that another OASYS process can use it. If you have attached more than one device, you must release each one separately. If you have attached only one, the T.DET command releases the one you have attached. You can execute T.DET from ECL or from within a OASBasic program.

© 2012 Onsystex Inc.

Part

15

152

15

OASYS Administration for Windows 64 Bit Platforms

Monitoring and Tuning OAS This chapter outlines considerations that can affect OASYS performance on your Windows platform and describes OASYS-specific procedures for monitoring performance.

15.1

Monitoring Your Windows System The Performance Monitor provides great flexibility for monitoring the behavior of your Windows system. From the Start menu, click Control Panel, then double-click Administrative Tools, and then click Performance. Note: A description of the Microsoft Performance Monitor is outside the scope of OASYS documentation. Refer to your operating system documentation for information about how to use the Performance Monitor. Onsystex recommends you monitor your system performance regularly to develop baseline expectations throughout your processing cycle. The performance history of your system provides information you can use to implement new procedures (such as scheduling certain jobs to run off-hours or purchasing more resources), as well as to identify problems quickly to minimize downtime. Tip: You can select an individual oas session and monitor detailed information about its use of system resources, in addition to monitoring OASYS as a whole.

15.2

OAS Performance Factors Within OASYS applications, the major performance factors are: database design, file sizing, and program coding efficiency.

15.2.1 Database Design Considerations Structure your database so records do not exceed a size limit of 4K bytes. When possible, avoid long, multivalued, variable-length records. Locate the most frequently accessed attributes near the beginning of a record. As far as possible, keep key lengths numeric and small in length.

15.2.2 Using Alternate Key Indexes Using alternate key indexes speeds query access in a hashed file, but can slow down updates. Consider this factor when creating indexes. The more indexes created for a file, the longer an update takes. Index overflows occur when the maximum length value is too small for the fields being indexed. Index overflows can degrade performance for query as well as update access. The solution for index overflows is to delete all the indexes for a file and rebuild them with a longer maximum length value. Tip: Use the OASYS LIST.INDEX tool to identify index overflow problems. Consider running LIST.INDEX periodically. See Using OASYS for information about alternate key indexes.

15.2.3 Sizing Static Hashed Files Performance loss results if OASYS hashed files are allowed to overflow. Level 2 overflow, which occurs when primary keys outgrow a block, has a particularly serious performance impact. Level 1 overflow, which occurs when data overflows a block, eventually affects performance as well.

© 2012 Onsystex Inc.

Monitoring and Tuning OAS

153

For information about file sizing commands, see the OASYS Commands Reference.

15.2.4 Sizing Dynamic Hashed Files Dynamic hashed files differ from static hashed files in that they split and merge with respect to a minimum modulo. Splitting prevents level 2 overflow conditions, because a group splits whenever the percentage occupied by keys exceeds a preset value. Merging supports efficient access to the file, because maintaining the file at a low modulo makes searches faster. For information about dynamic file sizing commands, see the OASYS Commands Reference.

15.2.5 OasBasic Coding Tips The efficiency of your OASBasic application has a significant impact on OASYS performance. Use the following guidelines when designing and coding.

Use Modular Programming Use inserts and include files consistently. opens.

Open frequently-used files to COMMON to reduce physical file

Use Efficient Commands Use the EQUATE command where possible. Use CASE statements instead of IF, THEN, ELSE structure whenever possible. Avoid nested IF, THEN, ELSE. Use OASYS @variables. Minimize new assignment of variables. Eliminate GOTO statements. Use GOSUB instead of external CALLs when appropriate; use CALL when multiple programs access the same code. When using CALLs: Avoid opening files; pass through COMMON or an argument list. Minimize local variables in subroutines. Use inserts, COMMON, and argument lists whenever possible. Use A += B instead of A = A + B. Use LOOP and REMOVE when extracting data sequentially from a string. Avoid unnecessary shell commands; minimize PERFORM, EXECUTE, and MDPERFORM statements. Use CALL or CHAIN to run another OASBasic program. Avoid repeated ITYPE( ) function calls. Minimize use of EXECUTE “SELECT.....” by: Using OASBasic SETINDEX, READFWD, READBCK. Using the OASBasic SELECT command.

Use Dynamic Arrays and Matrices Appropriately Use dynamic arrays when you are accessing small strings and variables. Use matrices if you are handling a large number of attributes and multi-valued strings.

Use the Correct READ in Each Situation Use READ when you are accessing small records, and the data you want is near the beginning of each record. Use READV if your intention is to get only one attribute. Use MATREAD when: You are handling records with a large number of attributes, and you want to access more than one attribute. You are handling large multivalued lists. © 2012 Onsystex Inc.

154

OASYS Administration for Windows 64 Bit Platforms

Manage Locks Carefully Use the LOCKED clause with a loop. Remember to release locks promptly.

15.3

OasBasic Profiling OASYS allows users to generate execution profiles that track call counts and execution times for OASBasic programs, internal subroutines, and program calls. You can use these profiles to identify sections of your OASBasic application that are called most frequently, and then focus optimization efforts in those areas. Complete the following steps to create OASBasic execution profiles.

1. Compile the Programs with -G Compile OASBasic programs with the -G option to include information about internal subroutines in the profile reports.

2. Execute the Programs with -G To profile a OASBasic program, run the program with the -G option. See Developing OASBasic Applications for information about compiling and running programs.

3. Review the Profile Output OASYS stores profile output in the NTFS directory where the OASBasic program was executed. Output files are called profile.pid and profile.elapse.pid where pid is the process ID (USRNBR in LISTUSER output) of the user’s OASYS process. The following example shows a portion of a profile report for a sample OASBasic program:

© 2012 Onsystex Inc.

Monitoring and Tuning OAS

155

In this example, the main program is called TIME_TST. It has three internal functions, named A, B, and C. Note: profile.pid reports execution times as CPU execution time, while profile.elapse.pid reports “real” time. Each profile display includes two sections. The top section presents summary infor-mation, and the bottom section presents detail. The following table describes the fields in the top section of a OASBasic Profile display. There is one line for each function of the program. Field %time cumsecs seconds calls name

Description Percentage of the total run time of the program used by the function Running sum of seconds the function and those listed above it used within a cycle Number of seconds used by the function in a cycle Number of times the function was invoked in a cycle Name of the function OAS Basic Profiling: S ummary Information

OASYS sorts program functions by execution time, and assigns an index to each function for ease of reporting. For each index, OASYS computes information about functions that call, or are called by, the function corresponding to the index. The detail section of a profile contains this information, grouped by index. The next table describes the fields in the detail section. Field

© 2012 Onsystex Inc.

Description

156

OASYS Administration for Windows 64 Bit Platforms

index

%time self descendents called

Field called+self

name index

Assigned by OASYS. The indexes are assigned in descending order of execution time for the functions of the program. The index in column 1 identifies the routine of interest for the group of data (the current index function). Reported for the current index function; percentage of the execution time used by the current index function and its descendents. Time spent by the function either calling, or being called by, the function identified by the current index. Time spent by the descendents of the function. For “parents” of the current index function, the number of times the function calls the current index function. For descendents of the current index function, the number of times the function is called by the current index function. OAS Basic Profiling: Detail Information

Description Reported for the current index function; the number of times the function is called by others, plus the number of times the function calls itself recursively. Function name. Index value assigned to the function. OAS Basic Profiling: Detail Information (continued)

The following screen shows one group of data, selected from the sample OASBasic profile:

This subset of the report contains data relative to the internal function A, which is identified by index number 2. “Parent” functions, or functions which call A, are listed above it; “descendents”, or functions called by A, are listed beneath it. In the example, the report indicates that 97.6% of the execution time for the entire program is used by A. The function is called 5 times, all by the main program, BP/TIME_TST. In turn, A is responsible for all 60 of the calls to B, and 15 of the 1,215 calls to C.

© 2012 Onsystex Inc.

Part

16

158

16

OASYS Administration for Windows 64 Bit Platforms

Appendix A OAS Configuration Parameters This appendix lists the names and descriptions for all OASYS configuration param-eters as of Release 7.1. See Chapter 7, “Configuring Your OASYS System,” for more information about modifying your oasconfig file. The following tables describe the configuration parameters that are placed in the oasconfig file located in \ OASHOME\include at the time of installation. They are system-dependent and should not be changed. Parameter

Description

OAS_BlockingSequence The locking sequence of processes in the system. This parameter should not be changed. OAS_BlockingStrategy Type of P/V operations used for the Recoverable File System (RFS) only. Determined at installation; platform dependent. Do not change unless instructed by Onsystex. oasconfig File Parameters that should not be changed

The following parameters may be changed to suit your environment. Parameter

Description

OAS_M axTables

Number of physical files that can be opened at the operating system level at one time in a OASYS session. This limit is for both oas and tm processes; the name of the corresponding kernel parameter varies among OS versions. Limit for number of OASYS user processes (such as oas and PHANTOM ) that can run at the same time. Switch for turning on and off messaging to your console. M ust be greater than zero for messages to display at console. Path of a directory for storing intermediate work files. Default is \OASYS\ud61\temp. Specifies a character to print to represent the null value. The ASCII character that represents the null value is nonprinting. Used with OASYS Physical Lock M anager. If a Linux platform supports test-n-set instruction, OAS_BlockingStrategy is set to 3 and OAS_TestandSet is set to 0. If a Linux platform does not support test-n-set instruction, OAS_BlockingStrategy is set to 2 and OAS_TestandSet is set to 1. Do not change this parameter unless instructed to do so by Onsystex. If OAS_TestandSet is set to 0, the length of time (in milli-seconds) that a process waits to access a shared memory address held by another process. This parameter has no effect if OAS_TestandSet is set to 1. Do not change unless instructed to do so by Onsystex.

OAS_M axUsers OAS_Console OAS_Tmp OAS_NULL OAS_TestandSet

OAS_WaitM illiseconds

OAS_NullFlag OAS_M axSystemFiles

Toggles null value handling on and off. If 0, null value handling is off. M ust be greater than 0 for null value handling to be in effect. M aximum number of Linux file systems allowed. If you have more than 200 Linux file systems, increase to your number of file systems. oasconfig File Parameters that may be changed

Parameter

Description

OAS_NoGlobalSlots

The number of hash buckets systemwide, used to hold the lock names in shared memory. This setting directly affects performance. Normally, the default value of this parameter should not be changed. However, if you notice significant degradation in performance, or your appli-cation intensively accesses specific files, you can increase this parameter. The default value is the closest prime number to OAS_M axUsers * 3.

© 2012 Onsystex Inc.

Appendix A OAS Configuration Parameters

159

OAS_NoLocalSlots

The number of hash buckets for the per-process locking table. This parameter is highly application dependent. If the application requires a large number of locks in one transaction (more than 20), you should increase this setting to the closest prime number to the maximum number of locks per transaction.

OAS_NoBlockingNodes

The number of lock nodes allocated for each memory request. This parameter is highly application dependent. If the application requires a large number of locks in one transaction, this setting should be increased to the maximum number of locks per transaction * 2.

OAS_BytesperNode

The segment size for each shared memory segment required for the lock manager. The maximum number of segments is 16. Large application environments require a larger size. Each oas will register the lock names it is locking in its per-process locking table. This table is also organized as a hashed table. oasconfig File Parameters that may be changed (continued)

The following parameter is related to internationalization. Parameter

Description

OAS_Language

The language group ID used to distinguish language groups that use similar special characters. OAS_Languageis composed of the record mark, escape sequence mark, and the null value mark. The default is 255/192/129. Internationalization oasconfig Parameters

The following table describes shared memory related parameters. These parameters may be changed to suit your environment. Parameter

Description

OAS_M axCatalogBytes

Size, in bytes, of shared memory segments created by oas_objmanager to store globally cataloged programs. oas_objmanager can attach a maximum of 20 segments systemwide. Runtime errors result if you attempt to load a new global program that exceeds this limit. Current kernel setting for maximum size (in bytes) of a shared memory segment. This parameter is set at installation; if you increase the kernel parameter shmmax, you need to increase OAS_M axShmSize to the same value as well. Starting address for shared memory attachment. Set at installation; do not change this unless instructed by Onsystex. Alignment size, in bytes, for shared memory attachment. Set at installation; do not change.

OAS_M axShmSize

OAS_AttachShmDir OAS_ShmAlignment OAS_ShmM inAttach OAS_NoGlobalTables

The minimum number of shared memory segments that should be kept attached to a process. Number of GCTs (global control tables) in CTL. Each shared memory segment is associated with a GCT. The GCT registers the use of global pages in its associated shared memory segment. Cannot exceed the kernel parameter shmmni.

OAS_GlobalPagesperSegment

Number of global pages in a shared memory segment. S hared Memory oasconfig File Parameters

Parameter

Description

OAS_BytesperPage OAS_ProcessesperGroup

Size of each global page, in 512-byte units. Number of entries in the PI table of a LCT, which is the number of processes allowed in a process group. It is set to 10 within the system, regardless of the oasconfig setting. Number of entries in the M I table of a LCT, which means the number of global pages or self-created dynamic segments that can be attached by a process. Cannot exceed 255.

OAS_GlobalPagesperProcess

© 2012 Onsystex Inc.

160

OASYS Administration for Windows 64 Bit Platforms

OAS_LocalPagesperProcess OAS_BytesperLocalPage OAS_FreePagesTx100

OAS_M axFreeSegments

The number of entries in the CI table of each LCT, which is the number of local pages that can be attached by a process. Size, in 512-byte blocks, of each local page in a global page. A global page is divided into local pages, so OAS_BytesperPage must be a multiple of OAS_BytesperLocalPage. Percentage of freed global pages in an active global shared memory segment that OASYS keeps in the global shared memory pool. oas_shmanager checks the current percentage; if the percentage is less than OAS_FreePagesTx100, oas_shmanager creates a new shared segment. The number of inactive shared memory segments that OASYS keeps in the system. oas_shmanager checks the current number of inactive segments; if the number is larger than OAS_M axFreeSegments, oas_shmanager returns some inactive global shared segments to Linux. S hared Memory oasconfig File Parameters (continued)

The following table describes size limitation parameters. Parameter

Description

OAS_AverageRecordLength

Number of local pages that matches the average length of records in your applications. Specifies the length of a buffer kept by OAS for holding a record. Should not exceed the number of local pages in a global page. OAS_IntermediateBufferLength Number of local pages used for expression buffers.OAS keeps a buffer of this size for intermediate results. Onsystex recommends you set this parameter so the buffer is onequarter to one-half the size of a global page. OAS_M axSizeBasicObject M aximum size, in bytes, of object programs that can be loaded into shared memory. Object programs larger than this size are loaded into the user’s address space instead of shared memory. OAS_M inGlobalPagesforTemp The minimum number of local pages that should be kept for temporary buffers in a Buff process group. Determined at installation. S ize Limitation oasconfig File Parameters

The following table describes parameters related to dynamic files. Parameter

Description

OAS_FreeBlocksinGroup

Pertains to dynamic files only; the number of free blocks kept in the free block list at the group level. If more blocks are freed, they are kept at the file level. M aximum number of dynamic files that can be open concurrently, systemwide. Default loading factor option (percent) at which a group in a dynamic file using the KEYONLY option splits. Splitting occurs when the percentage of space in a group occupied by keys and pointers reaches the split load. The ECL CONFIGURE. FILE command overrides this for individual files. Default loading factor (percent) at which a group pair in a dynamic file using the KEYONLY option merges. A group pair is eligible for merging when the sum of the percentages of space occupied by keys and pointers in both groups is less than M ERGE_LOAD. The CONFIGURE.FILE command lets users override this for individual files. Default loading factor (percent) at which a group in a dynamic file using the KEYDATA option splits. Splitting occurs when the percentage of space in a group occupied by keys and pointers reaches the split load. The ECL CONFIGURE. FILE command overrides this for individual files. Default loading factor (percent) at which a group pair in a dynamic file using the KEYDATA option merges. A group pair is eligible for merging when the sum of the percentages of space occupied by keys and pointers in both groups is less than KEYDATA_M ERGE_LOAD. The CONFIGURE.FILE command overrides this for individual files.

OAS_M axOpenDynamicTables OAS_SplitLoad

OAS_M ergeLoad

OAS_KeySplitLoad

OAS_KeyM ergeLoad

© 2012 Onsystex Inc.

Appendix A OAS Configuration Parameters

OAS_M axPartitionLength

161

Upper size limit, in bytes, of each partition file (dat00x) of a dynamic file. When a part file reaches this size, OASYS does not add further blocks to it, but creates another part file using the part table. The default value is 1073741824 bytes (1 GB). M ust be greater than 32768 bytes (32 KB) and less than 2147467264 bytes (2 GB-16KB). Path of a Linux text file that directs OASYS where to create dynamic file part files.

OAS_PathPartitionTable

Dynamic File oasconfig File Parameters

The following parameters are for Telnet Parameter

Description

OAS_WaitBlockingTime OAS_WaitforInput

Used by the Telnet server to specify the maximum time to wait for a lock. Used by the OAS ts executable to specify the maximum number of seconds to wait for input from client about device information. If the information is not provided, OASYS starts without the device information. Telnet oasconfig File Parameters

The following table describes parameters related to Journaling. Parameter

Description

OAS_M axJournalProcesses M aximum number of journal processes per journal path. OAS_M axTablesperJournalProcess M aximum number of journal files allowed per journal process. Journaling oasconfig File Parameters

The following table describes OASBasic file-related parameters. Parameter

Description

OAS_M axOpenTables

M aximum number of hashed files that can be opened by OASBasic OPEN statements, per oas process. Includes RFS and non-RFS, static, dynamic, and sequentially hashed files; each dynamic file counts as one file.

OAS_M axSequentialTables

M aximum number of sequential files that can be opened at one time by OASBasic OPENSEQ statements, per oas process. M aximum number of Linux sequential files that can be opened at one time by OASBasic OSOPEN statements, per oas process.

OAS_M axSystemTables OAS_M axDynamicFileParts

M aximum number of nonrecoverable dynamic part files (dat00x, over00x) a OASYS process can open with OASBasic OPEN statements or ECL commands. Each dynamic file has at least two part files. OAS Basic File-Related oasconfig File Parameters

The following table describes parameters related to OASBasic. Parameter

Description

OAS_M axLevelExecuteCapturing

Number of levels allowed for nested OASBasic EXECUTE WITH CAPTURING or M DPERFORM WITH CAPTURING clauses. Individual users can set an environment variable that overrides the configuration parameter.

OAS_M axLevelExecuteReturning

Number of levels allowed for nested OASBasic EXECUTE WITH RETURNING or M DPERFORM WITH RETURNING clauses. Individual users can set an environment variable that overrides the configuration parameter. Used to oas_analyzetbls BASIC memory compactor to do compaction for BASIC strings.

OAS_CompressVariablePolicy

© 2012 Onsystex Inc.

162

OASYS Administration for Windows 64 Bit Platforms

OAS_VarM emPct

0 - compact when program is finished 1 - compact when EXECUTE (another BASIC pgm) is completed 2 - compact when EXECUTE (another BASIC program) or CALL is completed The percentage of free memory that should be kept in the first global page for OASBasic variables after compacting. If the actual percentage is less than this value, OASYS keeps one free global page. Otherwise, OASYS returns all free global pages to Linux. OAS Basic oasconfig File Parameters

The following parameter is used in semaphore operations. Parameter

Description

OAS_SemaphoresperGroup

Number of semaphores per semaphore set. S emaphore oasconfig File Parameters

The following table describes index-related parameters. Parameter

Description

OAS_UseBufferswithIndexes

Controls whether READFWD and READBCK statements use a buffering mechanism. Default value is 0 (buffering off). Individual environment variable overrides oasconfig setting; BUFFER.KEYS keyword in the SETINDEX statement overrides either. Controls whether READFWD and READBCK statements validate a key value just read. Default value is 0 (no validation). Individual environment variable overrides oasconfig setting. VALIDATE.KEY keyword in the SETINDEX statement overrides either. Index oasconfig File Parameters

OAS_SetIndexValidateKeys

The following parameter is used with the OASYS Physical Lock Manager. Parameter

Description

OAS_NodesperSlot

Number of nodes per bucket. If this parameter is inade-quate for an application, an out of memory message is displayed. Physical Lock Manager oasconfig File Parameters

The following parameters are used with OASYS SpoolJobs files. Parameter

Description

OAS_M axDigitsSpoolJob

Enables you to specify the number of digits used for the next SpoolJobs file number, found in the NEXT.HOLD record of D__HOLD.

OAS_ValidateSpoolJobExist

Determines if OASYS checks for the existence of a SpoolJobs file prior to unconditionally removing it when you specify the BANNER UNIQUE option with the SETPTR command. S poolJobs File oasconfig File Parameters

The following table describes Windows platform message queue parameters. Parameter

Description

OAS_M axM essageQueue OAS_M axBytesM essage OAS_M axSystemM essages OAS_M axTextLength

The maximum number of message queues available for OASYS system-wide. The maximum size of a message. The maximum number of messages allowed systemwide. The default text size of a message per node. © 2012 Onsystex Inc.

Appendix A OAS Configuration Parameters

Windows Platform Message Queue oasconfig Parameters

© 2012 Onsystex Inc.

163

Part

17

Appendix B Environment Variables for OAS

17

165

Appendix B Environment Variables for OAS This appendix lists environment variables that can be set to customize a OASYS environment. Users can set them before entering OASYS to affect a particular OASYS session. System administrators can also set them for one or more users to establish defaults for some or all users. The following table lists environment variables in alphabetical order. Parameter CSTACKSZ INIT_BREAKOFF [0 | 1]

Parameter

Description Establishes the maximum number of commands in the ECL command stack. Each stack entry can hold a 2720 character command. The default is 49. Enables/disables break key prior to invoking OASYS. If INIT_BREAKOFF is not set, the break key is enabled by default. Environment Variables for OAS YS

Description

LPREQ

Identifies an alternate spooler directory. M ust be a full path ending in “/”. Valid on OASYS for Linux only. OAS_M axLevelExecuteCapturing Number of levels allowed for nested OASBasic EXECUTE WITH CAPTURING or M DPERFORM WITH CAPTURING clauses. This environment variable overrides the configuration parameter in the oasconfig file. OAS_M axLevelExecuteReturning Number of levels allowed for nested OASBasic EXECUTE WITH RETURNING or M DPERFORM WITH RETURNING clauses. This environment variable overrides the configuration parameter in the oasconfig file. M AX_TRANS_FIELD M AX_TRANS_REL NOCHKLPREQ

Number of TRANS fields that can be kept concurrently; default value is 12; must not be greater than 64 Number of TRANS files that can be open concurrently; default value is 32; must not be greater than 32. Bypasses Linux printer verification; useful for large systems with hundreds of printers defined. Valid on OASYS for Linux only. Environment Variables for OAS YS

Parameter

Description

SETINDEX_BUFFER_KEYS

Controls whether READFWD and READBCK statements use a buffering mechanism. Default value is 0 (buffering off). Individual environment variable overrides oasconfig setting; BUFFER.KEYS keyword in the SETINDEX statement overrides both.

SETINDEX_ VALIDATE_KEY

Controls whether READFWD and READBCK statements validate a key value just read against the record. Default value is 0 (no validation). Individual environment variable overrides oasconfig setting; VALIDATE.KEY keyword in the SETINDEX statement overrides both. Specifies a number of characters to tab in OASBasic PRINT statements. M ust be 1-76. The default is 8. Identifies an alternate directory for \temp when additional work space is needed by OASYS. M ust be a directory path ending with \. Identifies the path of the text editor OASYS invokes when users execute the ECL ED command. The default is the M S-DOS editor. This variable cannot be set to AE. Environment Variables for OAS YS

TABSTOPS OAS_Tmp OAS_EDIT

© 2012 Onsystex Inc.

166

OASYS Administration for Windows 64 Bit Platforms

Parameter

Description

OAS_SAVELIST

Allows you to specify a default list name for each OASYS user. Set in the user’s .login or .profile. Users can also specify a list name when executing the SAVE.LIST command. Size of a buffer used to keep select list in memory. If a select list is larger then the size of this buffer, it will be written to a file. If OASYS_SELECTSIZE is not defined, the system uses a buffer size of 10 KB. Location of OASYS executables.

OAS_SELECTSIZE

OASBIN OASERRLOG_LEVEL

OASHOM E VFIELDSIZE

VOC_READONLY

Determines the logs to which file open errors are written. If the value of this environment variable is equal to or greater than 2, OASYS writes file open errors to the oas.errlog, and on Windows platforms, to the Windows event log. Otherwise, OASYS does not log file open errors. Location of the OASYS home directory, which contains directories including sysprog, demo, lib, work, sybase, and include. Increases the size for the stack of C routines used to process formulas created in virtual fields. Default is 300. Define a larger number if users see “virtual field too big” errors in OASQuery. If set to a nonzero number, allows OASYS to run with read-only access to the VOC file. Environment Variables for OAS YS

© 2012 Onsystex Inc.