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.

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

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.

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

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.

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

2012 Onsystex Inc.

Part

10

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 users 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

Managing and Using the OASTelnet Service

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 users 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

28

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 users
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 users 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

32

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 users 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

Configuring Your OAS System

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 users 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

Starting and Stopping OASIS

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 users 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

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

Managing OAS Accounts

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 users 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

50

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 users .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 users domain.

If the users 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

Managing OAS Files

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: <RETURN>
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
records 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.

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 users 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 users 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 users 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

oasSql Total
0

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 users 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 users 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 printers 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 printers 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 users
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 users 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
users .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.